From 5180e25f91a7020ec7347929bb61321241c9fbbf Mon Sep 17 00:00:00 2001 From: Tolik <85737314+Tolik-Trek@users.noreply.github.com> Date: Thu, 18 Jun 2026 20:52:50 +1000 Subject: [PATCH] Num Lock numbers --- DSS-MAIN.exp | 10 + DSS/KEYINTER.ASM | 88 ++++- DSS/build.txt | 2 +- DSS/defines.inc | 29 +- keys.md | 828 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 941 insertions(+), 16 deletions(-) create mode 100644 DSS-MAIN.exp create mode 100644 keys.md diff --git a/DSS-MAIN.exp b/DSS-MAIN.exp new file mode 100644 index 0000000..5b6683f --- /dev/null +++ b/DSS-MAIN.exp @@ -0,0 +1,10 @@ +CORE_BUFFERS.BUFFERSplace: EQU 0x00003207 +CORE_BUFFERS.FM_BUF: EQU 0x00003207 +CORE_BUFFERS.FS_Buffer: EQU 0x00003423 +CORE_BUFFERS.EXEBUFF: EQU 0x00003464 +CORE_BUFFERS.XSTACK: EQU 0x00003664 +CORE_BUFFERS.BUFFER: EQU 0x00003764 +CORE_BUFFERS.SECTOR_BUFFER: EQU 0x00003764 +CORE_BUFFERS.MemoryTable: EQU 0x00003964 +CORE_BUFFERS.CurrentDirectory: EQU 0x00003A66 +CORE_BUFFERS.WorkDirectory: EQU 0x00003B66 diff --git a/DSS/KEYINTER.ASM b/DSS/KEYINTER.ASM index 2ed4d15..008bd11 100644 --- a/DSS/KEYINTER.ASM +++ b/DSS/KEYINTER.ASM @@ -550,9 +550,18 @@ KEYSCAN: LD IX,KEYFLAG ; BIT FLAG_F0,(IX+KEYFLG) JR NZ,UN_KEY - ; + ;[ ]18/06/2026 ignore AT fake-shift (E0-12/E0-59) around extended keys + IF ENABLED_KEYBOARD_CONTROL + CALL FAKE_SHIFT + JR NC,.real_make + RES FLAG_E0,(IX+KEYFLG) + JP .RESCAN +.real_make: + ENDIF LD L,A CALL XLAT + CALL NUMPAD_KEY ; [ ]18/06/2026 keypad digit? CF=1 if emitted + JP C,.RESCAN ; emitted -> drain rest of SIO FIFO CALL SHIFTS RES FLAG_E0,(IX+KEYFLG) IF USE_E1_SCANCODE @@ -655,6 +664,13 @@ KEYSCAN: LD IX,KEYFLAG ; RET ; ELSE UN_KEY: RES FLAG_F0,(IX+KEYFLG) + IF ENABLED_KEYBOARD_CONTROL + CALL FAKE_SHIFT + JR NC,.uk_real + RES FLAG_E0,(IX+KEYFLG) + RET +.uk_real: + ENDIF LD L,A CALL XLAT CALL UNSHIFT @@ -664,6 +680,76 @@ UN_KEY: RES FLAG_F0,(IX+KEYFLG) RET ; ENDIF ; +;-------------------------------------------------------------------------------- +;[ ] 18/06/2026 NUMPAD: keypad key. DIGIT if (NumLock XOR Shift), else clean NAVIGATION. +; in : L = AT positional code (from XLAT), IX = KEYFLAG, FLAG_E0 still valid +; out: CF=1 -> keypad key fully handled and pushed via PUTSYM (caller drains FIFO) +; out: CF=0 -> not a keypad key; caller continues normal path (L preserved) +; NB: navigation is emitted as D=poscode (bit7=0), E=0 so EvComComb sees Del/arrows, +; NOT #XX|#80 which the editor reads as the Ctrl+key variant. +NUMPAD_KEY: BIT FLAG_E0,(IX+KEYFLG) ; E0 => dedicated Ins/Del/nav key -> normal path + JR NZ,.skip + LD A,L ; positional code + CP #4F ; keypad block = pos #4F..#59 (Del/. Ins/0 .. PgUp/9) + JR C,.skip ; below (keypad + - * /) -> normal path + CP #5A + JR NC,.skip ; above -> normal path + ; + ; mode: DIGIT if (NumLock XOR Shift), else NAVIGATION + LD A,(KEYCTRL) + AND 1<0 if Shift held + BIT NUM_L,(IX+K_LOCK) ; Z=0 if NumLock on + JR Z,.nl_off + AND A ; NumLock ON : digit unless Shift + JR NZ,.nav ; Shift -> navigation + JR .digit +.nl_off: AND A ; NumLock OFF: navigation unless Shift + JR Z,.nav ; no Shift -> navigation + ; +.digit: LD A,L + CP #4F ; keypad '.' + JR Z,.dot + SUB #50 ; #50..#59 -> 0..9 + ADD A,'0' ; -> '0'..'9' + LD E,A + LD A,L + OR #80 ; D = poscode | keystroke flag + LD D,A + JR .emit +.dot: LD E,'.' + LD D,#4F | #80 + JR .emit + ; +.nav: LD D,L ; clean position code, bit7=0 + LD E,0 ; ASCII=0 => navigation event (EvComComb) + LD A,L + CP #50 ; Ins toggles insert mode (like dedicated Ins) + CALL Z,INS_X +.emit: LD BC,(KEYFLAG) ; C=KEYFLAG B=KEYCTRL snapshot + CALL PUTSYM + SCF ; CF=1 -> handled + RET +.skip: OR A ; CF=0 -> not handled, normal path + RET +;-------------------------------------------------------------------------------- +;[ ]18/06/2026 AT fake-shift detector: E0 12 / E0 59 sent around extended keys +; when NumLock/Shift is active. MUST be ignored, else it sets L_SHIFT and the +; cursor key that follows gets bit7 set in D -> editor stops recognising it. +; in : A=scancode, IX=KEYFLAG, FLAG_E0 reflects prefix ; out: CF=1 if fake-shift + IF ENABLED_KEYBOARD_CONTROL +FAKE_SHIFT: BIT FLAG_E0,(IX+KEYFLG) + JR Z,.nofake + CP #12 ; fake Left Shift + JR Z,.isfake + CP #59 ; fake Right Shift + JR Z,.isfake +.nofake: OR A ; CF=0 -> real key + RET +.isfake: SCF ; CF=1 -> ignore it + RET + ENDIF +;-------------------------------------------------------------------------------- +; CAPS_X: LD A,(KEYFLAG) XOR 1< handle AT fake-shift (E0 12/59). HW is receive-only -> keep 0 +; DEFINE CLASSIC_CURSOR 0 ; -;LD_DSK EQU 16 ; ᨬ쭮 ⢮ ᪨ HDD ᪮ ⥬ +;LD_DSK EQU 16 ; ᨬ쭮 ⢮ ᪨ HDD ᪮ ⥬ ///////////////////////////////////////////////////////////////////////////////////////////////////////////// - DEFINE CHANGE_FREE_CLU_AFTER_DEL 1 + DEFINE CHANGE_FREE_CLU_AFTER_DEL 1 SERVICE_SECTORS: .FAT12 EQU #0FEF diff --git a/keys.md b/keys.md new file mode 100644 index 0000000..8fb7131 --- /dev/null +++ b/keys.md @@ -0,0 +1,828 @@ +# Промт для новой сессии: изучение и модификация клавиатурной подсистемы DSS + +## Задача +Изучить и при необходимости модифицировать алгоритмы работы с клавиатурой, +реализованные в [DSS/KEYINTER.ASM](DSS/KEYINTER.ASM) — модуле, который +включается в ядро DSS через `INCLUDE` из [DSS/DSS-MAIN.ASM](DSS/DSS-MAIN.ASM) +(строка 402, сразу после таблицы `DSS_API_TABLE`). Это код для компьютера +**Sprinter** (Z84C15), работающего как PS/2-хост для AT-клавиатуры через +встроенный в Z84C15 SIO канал A. + +Перед изменениями сверяй свои выводы с исходным кодом: в этом проекте уже +зафиксирована память о том, что **доверять разбору регистров/стека от +суб-агентов нельзя** — трассируй PUSH/POP/EX AF/EXX лично (см. +`[[verify-subagent-reg-flow-claims]]` в auto-memory). + +--- + +## 1. Рабочее окружение + +- **Основная директория проекта** (kernel + сборка): + `/Users/tolik/Documents/SP_Projects/ASM/GIT/Estex DSS` +- **Доп. директория** (архив/референс, не собирается): + `/Users/tolik/Documents/SP_Projects/ASM/Another` (подключена в + `Estex DSS.code-workspace` как второй корень) +- **Подмодуль git**: [Shared_Includes/](Shared_Includes/) — общие + константы/структуры/доки; ветка `main`, url `../Shared_Includes.git`. +- **Кодировка/переводы строк**: исходники в **CP866 (русский DOS)** с + **CRLF**. Это включает `DSS-MAIN.ASM`, `KEYINTER.ASM` и большинство + `Shared_Includes/constants/*.inc`. `grep -aI` нужен, если grep считает + файлы бинарными. +- **Ассемблер**: `sjasmplus --syntax=afw`. Сборка идёт через VS Code + ([.vscode/tasks.json](.vscode/tasks.json)) — Makefile нет. Полезные + задачи: `Build SYSTEM.DOS`, `Build SYSTEM.DOS [NEW]` + (`--define INCREASE_BUILD` → инкремент `DSS/build.txt`), + `Build SYSTEM.EXE`, `Build SYS.EXE`, `Copy all files to MAME` + (вызывает [RUN/Image.sh](RUN/Image.sh) → `hdfmonkey put` в + `/Users/tolik/Documents/MAME/IMG/test_2g.img`), `Run MAME`. +- **Выходы сборки**: + `Build/DSS/SYSTEM.DOS` (ядро), + `Build/DSS/SYSTEM.EXE` (шелл), + `Build/DSS/SYS.EXE` (бутлоадер), + `Build/DSS-MAIN.LST` (листинг ~1 МБ), + `Build/Variables.inc` (экспортированные символы через `--exp`). +- **Версия**: `VERS=1, MODF=71`, билд из `DSS/build.txt` (сейчас 68) → "DSS 1.71.68". + Логика в [DSS/VERSION.INC](DSS/VERSION.INC) + LUA в + [Shared_Includes/LUA/Functions.lua](Shared_Includes/LUA/Functions.lua). + +--- + +## 2. Архитектура DSS и место KEYINTER + +### 2.1. Точка входа ядра — [DSS/DSS-MAIN.ASM](DSS/DSS-MAIN.ASM) +- `ORG 0`, ядро располагается с адреса #0000 на странице ядра. +- **RST-векторы** (DSS-MAIN.ASM около строк 30-310): + - `RST 00` — RETFAR / реентри для дочерних процессов + - `RST 08` (`ToBIOS`) — портал в BIOS в SLOT0 + - `RST 10` (`ToDSS`) — DSS API gateway → `RST_10` диспетчер на строке 187 + - `RST 18` — портал в страницу драйверов + - `RST 20`, `RST 28` — NOPS + - `RST 30` (`ToDSS.Mouse`) — мышиный API + - `RST 38` (IM 1) — `INTx38_Handler` на строке 275: сохраняет все регистры + (главный набор + альтернативный + IX/IY), вызывает `CALL KEYSCAN`, + затем `RST ToDSS.Mouse GetPackets`, затем `cursor_interrupt`, `RETI`. +- **Диспетчер `RST_10`** (строка 187): `LD H,high DSS_API_TABLE / LD L,C` — + C=номер функции, индексирует таблицу адресов с раздельными байтами + (низкие байты строки 340-361, высокие 369-390). +- **Клавиатурные слоты в `DSS_API_TABLE`** (строки 344-345 / 373-374): + - `#30 WAITKEY`, `#31 SCANKEY`, `#32 ECHOKEY`, `#33 CTRLKEY`, + **`#34 NOPS`** (зарезервирован, не реализован — константа + `Dss.EDIT` есть, кода нет), `#35 K_CLEAR`, `#36 K_SETUP`, `#37 TESTKEY`. +- **INCLUDE KEYINTER.ASM** — строка 402. +- **Boot-флоу** `F_START` (строка 567): DEPLOY → `CALL KEYBOARD_INIT` + (строка 592) → PRINT_INIT → инициализация мыши → инициализация дисков → + `EI` → `CLEAR_BUFFER_AND_INIT_PROC`. +- **Карта памяти** ([DSS/DSS_MAP.TXT](DSS/DSS_MAP.TXT)): + - `#0000..#0038` — RESTARTS + - `#0200..#03FF` — `DSS_API_TABLE` + - `#0400..#043F` — **SBUF** (буфер клавиатуры, 64 байта) + - `#0440..#0BD1` — код KEYINTER (~1936 байт) + - `#0BD2..#0EF5` — драйвер экрана (для совместного использования с + `Cursor_On/Off`) + +### 2.2. Соседние модули +- [DSS/API.asm](DSS/API.asm) — агрегатор-INCLUDE для всех `DSS/API/*.asm`. +- [DSS/FS_Module.asm](DSS/FS_Module.asm) — `FS/FAT.asm` + `FS/CDFS.ASM`. +- [DSS/DOS_Proc.asm](DSS/DOS_Proc.asm) — DOS-уровневые помощники + (имена файлов, маски, `SET_FM`, `OPENDSK` и т.п.). +- [DSS/Procedures.asm](DSS/Procedures.asm) — общие хелперы + (`PUTCHAR` строка 103, `PUTCHAR.NO_SCROLL` строка 104, `MK_TIME` и др.). +- [DSS/DRV-MAIN.ASM](DSS/DRV-MAIN.ASM) — отдельная страница драйверов + (DISP/ENT-блок в `DSS-MAIN.ASM:695-699`), своя таблица RST по адресам + `#A0000..#A0038`. Клавиатура там НЕ живёт. +- [DSS/drivers/Input/MOUSE.ASM](DSS/drivers/Input/MOUSE.ASM) — мышь; + делит окно INT 38h с KEYINTER (сначала `KEYSCAN`, потом мышь). +- [DSS/defines.inc](DSS/defines.inc) — compile-time флаги (см. §5). +- [DSS/DSS_MACROSES.Z80](DSS/DSS_MACROSES.Z80) — макросы. Закомментированный + `BUFFER_KEYINTER` (строки 2-82) задокументирован как канонический layout + `SBUF/KEYFLAG/KEYCTRL/KEYFLG/SOUND_K`, но реальные определения сейчас + inline в `KEYINTER.ASM`. `SET_PAGE_X` (строки 137-143) — рабочий макрос + переключения страниц SLOT3. + +### 2.3. Внешние символы, на которые ссылается KEYINTER +| Символ | Что | Где определён | +|--------|-----|---------------| +| `PUTCHAR`, `PUTCHAR.NO_SCROLL` | вывод символа | `DSS/Procedures.asm:103-104` | +| `LOCATE` | установка курсора | `DSS/API/Locate.asm:8` | +| `VMODE` | байт текущего видеорежима | `DSS/API/SetVMod.asm:90` | +| `BANKTBL` | таблица логическая→физическая страница | `DSS/DSS-MAIN.ASM:423` | +| `RST_10` | диспетчер DSS | `DSS/DSS-MAIN.ASM:187` | +| `ToBIOS`, `BIOS.*` | BIOS API | `Shared_Includes/constants/BIOS_equ.inc` | +| `ToDSS`, `Dss.*`, `DSS_Error.*` | DSS константы | `Shared_Includes/constants/dss_equ.inc` | +| `Z84.SIO.Ch_A.{Data,Ctrl}`, `SP_SND.Beeper`, `SLOT3`, `TXTPAGE` | железо | `Shared_Includes/constants/SP2000.inc` (модуль `Z84`, строки 2111-2127); часть EQU может приходить из внешнего SP2000-инклюда не из снимка репо — проверять `Build/Variables.inc` | + +--- + +## 3. KEYINTER.ASM подробно + +Файл — 1371 строка, CRLF, CP866. Заголовок R01 (10.02.2003, DNS — добавлен +курсор в `ECHOKEY`) и R02 (13.04.2023, BAO — исправлен stack overflow в +`K_CLEAR`). + +### 3.1. Публичный API (вызывается через `RST 10` с `C=` номер функции) + +| C | Метка | Строки | Назначение | +|---|-------|--------|------------| +| #30 | `WAITKEY` | 112-119 | Блокирующее ожидание. Выход: `A=E=ASCII`, `D=` поз.код, `B=KEYCTRL`, `C=KEYFLAG` | +| #31 | `SCANKEY` | 122-128 | Неблокирующее. `ZF=1` если буфер пуст | +| #32 | `ECHOKEY` | 195-212 | `SCANKEY` + программный курсор (`Cursor_On`/`Off`), эхо через `PUTCHAR.NO_SCROLL` | +| #33 | `CTRLKEY` | 383-391 | Прочесть `BC=(KEYFLAG)` без извлечения; `A=0` если буфер пуст, `A=#FF` если есть | +| #34 | (NOPS) | — | `Dss.EDIT` определён, но функция не реализована в v1.71 | +| #35 | `K_CLEAR` | 431-445 | Очистить буфер (`HEAD:=HOST`), потом `JP RST_10` для повторной диспетчеризации, если `B ∈ [#30..#34]`. Иначе `A=#01 INVALID_FUNCTION`, `CF=1` | +| #36 | `K_SETUP` | 934-... | Мультиплексор: см. §3.6 | +| #37 | `TESTKEY` | 393-408 | Peek текущей записи без сдвига `HOST`. `ZF=1` если пуст | + +### 3.2. Кольцевой буфер +- **`SBUF`** (строка 14): `_mInfoALIGN 256,0` + `BLOCK 64,0` — 64 байта на + границе страницы. Поэтому high-byte адреса слота = `high SBUF`, а + `HEAD`/`HOST` — только low-byte (0..#3F). +- **`HEAD`** (строка 33) — указатель писателя. +- **`HOST`** (строка 34) — указатель читателя. +- **Слот = 4 байта**: `byte+0=E (ASCII)`, `byte+1=D (поз.код | #80)`, + `byte+2=B (KEYCTRL snapshot)`, `byte+3=C (KEYFLAG snapshot)`. +- Макс. 16 записей. +- Пуст: `HEAD == HOST`. Полон: `HEAD == (HOST-4) & #3F` (проверка + `PUTSYM` строки 450-453). +- **`GetSymAddr`** (строки 467-476) — общий помощник: `A := (HL)`, + `INC (HL)` ×4, `RES 6,(HL)` (wrap modulo 64), формирует + `HL = high SBUF : старый offset`. +- **`PUTSYM`** (448-464) — продьюсер. На переполнении прыгает в + `FULL_BF` (496-505): если `SF_BUFF` бит SOUND_K взведён — `BEEP` + с `DE=230, HL=50`, ключ отбрасывается. +- **`GETSYM`** (479-493) — консьюмер. + +### 3.3. Байты состояния (адресуются через `LD IX,KEYFLAG` на строке 519) + +**`KEYFLAG`** (offset 0, alias `K_LOCK`, строка 45, init `#02` — `INS_L` on): +| Бит | Имя | Значение | +|-----|-----|---------| +| 7 | `LANG_L` | язык RUS/LAT | +| 6 | `PAUSE_L` | Pause Lock | +| 5 | `RES5_L` | резерв (в комментариях помечено как историческое `X_SHIFT`) | +| 4 | `RES4_L` | резерв | +| 3 | `NUM_L` | Num Lock | +| 2 | `SCRL_L` | Scroll Lock | +| 1 | `INS_L` | Insert | +| 0 | `CAPS_L` | Caps Lock | + +Переключается: `CAPS_X` 668-671, `LANG_X` 674-690, `INS_X` 693-696, +`NUM_X` 699-702, `PAUSE_X` 705-718, `SCL_X` 721-724. + +**`KEYCTRL`** (offset 1, alias `K_SHIFT`, строка 56, init `#00`): +| Бит | Имя | +|-----|-----| +| 7 | `L_SHIFT` | +| 6 | `R_SHIFT` | +| 5 | `X_CTRL` (любой Ctrl) | +| 4 | `X_ALT` (любой Alt) | +| 3 | `L_CTRL` | +| 2 | `L_ALT` | +| 1 | `R_CTRL` | +| 0 | `R_ALT` | + +Устанавливаются в `SHIFTS` (799-836) на нажатии, сбрасываются в `UNSHIFT` +(738-797) на отпускании. Также чистятся в `KBD_Receiver_Overrun` (1240). + +**`KEY_FLG`** (offset 2, alias `KEYFLG`, строка 67, init `#00`): +| Бит | Имя | +|-----|-----| +| 7 | `FLAG_E0` — защёлкнут E0-префикс (extended) | +| 6 | `FLAG_F0` — защёлкнут F0-префикс (release) | +| 5 | `FLAG_E1` — E1-префикс (только если `USE_E1_SCANCODE`) | +| 4-1 | резерв | +| 0 | `CTRL_SHIFT` — Ctrl+Shift зафиксирован (для `LANG_X` при `CHANGE_LANG_CTRL_SHIFT`) | + +**`SOUND_K`** (offset 3, строка 78, init `#03` — оба звука включены): +| Бит | Имя | +|-----|-----| +| 7-2 | `FLAG_S7..S2`, резерв | +| 1 | `SF_ALT` — звук при смене языка | +| 0 | `SF_BUFF` — звук при переполнении буфера | + +**`UNCODE`** (offset 4, WORD, строка 81) — последний отпущенный скан-код +(пишется в `UN_KEY` строка 663). + +### 3.4. Таблица трансляции скан-кодов +- **`XLAT_T`** (строки 21-30) — сырая таблица 144 байта, + AT scancode (Set 2) → внутренний позиционный код 0..#5A. + `XLAT_T.Size = 144`. Bounds-check в `XLAT` на строке 860. +- **`XLAT`** (839-870) — собственно переводчик. Если защёлкнут `FLAG_E0`, + жёстко мапит специальные коды (`#11→#39 R-ALT`, `#14→#3A R-CTRL`, + `#5A→#4E numpad Enter`, `#4A→#4A /`, `#7C→#47 PrintScreen`); иначе + `L = XLAT_T[A]`. + +### 3.5. ASCII-таблицы (`MODULE ASCII_TABLES`, строки 1285-1368) +Все таблицы ровно 90 байт (`Size EQU 90`): +- `ASCII_TABLES.ENGLISH` (1287-1295) — без шифта, англ +- `ASCII_TABLES.SHIFT_ENG` (1297-1305) — с шифтом, англ +- `ASCII_TABLES.CAPS_ENG` (1307-1315) — Caps, англ +- `ASCII_TABLES.CAPS_SHIFT_ENG` (1317-1325) — Caps+Shift, англ +- `ASCII_TABLES.RUSSIAN` (1328-1336) — без шифта, рус CP866 +- `ASCII_TABLES.SHIFT_RUS` (1338-1346) +- `ASCII_TABLES.CAPS_RUS` (1348-1356) +- `ASCII_TABLES.CAPS_SHIFT_RUS` (1358-1366) + +Старые метки `NORMTAB / SHIFTAB / CAPSTAB / SHF2TAB / NORMRUS / SHIFRUS +/ CAPSRUS / SHF2RUS` сохранились ТОЛЬКО в закомментированной legacy-копии +`K_SETUP` (строки 1097-1167) и **не являются живыми**. Все +KEYMAP/READMAP используют `ASCII_TABLES.*`. + +### 3.6. K_SETUP подфункции (диспетчер на строке 934) +`INC B / DJNZ K_SND_R` — цепочка DJNZ: +| B | Метка | Поведение | +|---|-------|-----------| +| 0 | `KEYMAP` (937-972) / `READMAP` (974-1006) | Запись/чтение одной из 8 ASCII-таблиц. `HL=` буфер, `A bit7=0` запись, `bit7=1` чтение, биты0-2 = номер подтаблицы 0..7. Объём LDIR = `ASCII_TABLES.Size`=90 байт. Неверный A → `XOR A : SCF : RET` | +| 1 | `K_SND_R` (1019-1023) | `A := SOUND_K` | +| 2 | `K_SND_W` (1025-1030) | `SOUND_K := A` | +| 3 | `K_CURSOR_ON` (1034-1038) | Если `VMODE` показывает текстовый режим — `JP Cursor_On` | +| 4 | `K_CURSOR_OFF` (1042-1046) | То же → `JP Cursor_Off` | +| ≥5 | `K_SETUP.ERROR` (1015-1017) | `A = #0E INVALID_ACCESS, SCF, RET` | + +### 3.7. Сканер клавиатуры — `KEYSCAN` (519-629) +- `LD IX,KEYFLAG` — IX указывает на блок состояния. +- **В текущем билде сканер ПОЛЛИНГ** (`KEYBOARD_INT_ENABLED=0`): + IF-блок строк 521-526 (который бы делал `CALL .RESCAN`, выход из INT) + НЕ ассемблируется. `KEYSCAN` падает прямо в `.RESCAN`. На практике он + вызывается из `INTx38_Handler` (`DSS-MAIN.ASM:275-306`), который сам + висит на `IM 1` `RST 38h`. +- **Логика `.RESCAN`** (от строки 527): + 1. `IN A,(Z84.SIO.Ch_A.Ctrl)` — читаем RR0. + 2. Если `bit0` (Rx Character Available) = 0 → `RET`. + 3. Иначе пишем 1 в Ctrl (указать на регистр 1), читаем обратно, + тестируем `bit5` (Receiver Overrun) → ошибка → `JP KBD_Receiver_Overrun` + (1228) — дренаж FIFO, `OUT %00110000` в WR0 для error reset, + обнуление `KEYCTRL/KEY_FLG`. + 4. Иначе `IN A,(Z84.SIO.Ch_A.Data)` (строка 538) — байт скан-кода. + 5. Префиксы: + - `#F0` → `FULL_BF.F0_KEY`: устанавить `FLAG_F0`, `JP .RESCAN`. + - `#E0` → `FULL_BF.E0_KEY`: устанавить `FLAG_E0`, `JP .RESCAN`. + - `#E1` → если `USE_E1_SCANCODE=1` устанавить `FLAG_E1`, + иначе игнорировать. + 6. Обычный байт + `FLAG_F0` → `UN_KEY` (657-664): `XLAT` → `UNSHIFT` + модификаторов, `UNCODE := HL` (последний отпущенный). + 7. Обычный байт без `FLAG_F0` → `XLAT` → `SHIFTS` → сброс `FLAG_E0/E1` → + при `CHANGE_LANG_CTRL_SHIFT=1` опционально установить `CTRL_SHIFT` → + `INPCODE` → `PUTSYM` → `JP .RESCAN` (продолжать дренировать FIFO, + строка 628) — поскольку SIO имеет **3-байтовый Rx FIFO** (см. §6.4). + +### 3.8. INPCODE/RUSCODE/CONVERT (875-930) +- **`INPCODE`** (875-906) — выбор одной из 4 английских таблиц на основе + `KEYCTRL` бит шифта и `KEYFLAG.CAPS_L`. Если `LANG_L` взведён → `JP RUSCODE`. +- **`RUSCODE`** (908-930) — то же для русских. +- **`CONVERT`** (901-906): `SET 7,D` (флаг keystroke), `HL = таблица+L`, + `E := (HL)`. После этого `PUTSYM`. + +### 3.9. Курсор и звук +- **`Cursor`** (215-218) — переключатель: `CPL` `.Flag`, falls into + `Cursor_On`. +- **`Cursor_On`** (220-253): `BIOS.LP_GET_PLACE` (#8E) → DE=Y/X, сохранить; + `BIOS.WIN_GET_SYM` (#B4); вычислить глиф — `NORM_ZG=#1B` обычно, + `INS_CUR_ZG=#9B` при `INS_L`, `CURSOR_ZG=#5B` для фазы blink; + `BIOS.WIN_PUT_SYM.NoChangeZG` (`#01B5`); `LOCATE`. +- **`Cursor_Off`** (257-284): обратное действие; `JP LOCATE`. +- **`cursor_interrupt`** (287-295): тик. Если `.Flag != 0`, декрементировать + таймер; на нуле `CALL Cursor`. +- **`SETUP_CURSORS`** (298-375): один раз при старте подгружает кастомные + глифы (#5B блок и #9B инверт.) в страницу шрифта (`BANKTBL+TXTPAGE`) + через `BIOS.WIN_GET_ZG` (#B8) → CPL → `BIOS.WIN_SET_ZG` (#B6). +- **`BEEP`** (1173-1192): `DE=` период, `HL=` повторы. Тогглит A=#10/#00 в + `(SP_SND.Beeper)` = порт #FE бит 4. + +### 3.10. Инициализация — `KEYBOARD_INIT` (1194-1224) +Последовательность для SIO Ch_A (стандартная Z80 SIO init): +- `DI` +- WR0 := 0 (clear pointer) +- WR4 := парам. (clock, stop, parity) — точные байты в коде, ср. с + `Another/SPRINTER/TASM/Keybdrv.z80` (там 9 байт init) +- WR3 := `#C1` (Rx enable, 8 бит/символ) +- WR5 := `#62` (`0110'0010`: бит3 **Tx Enable = 0 → передатчик ВЫКЛЮЧЕН**; биты5-6 = 8 бит/символ). Передача данных клавиатуре аппаратно отключена — см. §6.5 +- WR1 := `%00011001` если `KEYBOARD_INT_ENABLED=1`, иначе 0 +- `EI : RET` + +--- + +## 4. Конвенция вызова DSS API + +- **DSS**: `LD C,Dss.Xxx` (номер функции из `Shared_Includes/constants/dss_equ.inc`, + модуль `Dss:`), `RST 10` (= `ToDSS`). Параметры — в регистрах согласно + спецификации (см. [Shared_Includes/Docs/DSS_1.71_Functions.asm](Shared_Includes/Docs/DSS_1.71_Functions.asm), + раздел 6). +- **Выход**: `CF=0` — успех (значения в регистрах согласно функции); + `CF=1` — ошибка, `A=` код ошибки (`DSS_Error.sys.*`). +- **BIOS**: `LD C,BIOS.XXX` (`Shared_Includes/constants/BIOS_equ.inc`, + модуль `BIOS:`), `RST 08` (= `ToBIOS`). Перед вызовом необходим `DI` и + `OUT (#7C),0` для переключения банка BIOS; стек должен быть в `#8000-#BFFF`. + Подробно — [Shared_Includes/Docs/BIOS functions.asm](Shared_Includes/Docs/BIOS%20functions.asm), строки 1-60. +- **Подфункции**: верхний байт BC (т.е. `B`) — индекс подфункции; константа + обычно собрана как `EQU subfn*256 + .Func`. Пример: `Dss.K_SETUP.SetSoundVars + EQU 2*256+#36`. + +--- + +## 5. Compile-time флаги ([DSS/defines.inc](DSS/defines.inc)) + +| Флаг | Текущее | Что переключает в KEYINTER | +|------|---------|-----------------------------| +| `KEYBOARD_INT_ENABLED` (стр. 21) | `0` | `0` = поллинг из `INT 38h`; `1` = SIO Ch_A прерывание (WR1 := `#19`), отдельный обработчик в начале `KEYSCAN` | +| `CHANGE_LANG_CTRL_SHIFT` (стр. 22) | `1` | `1` = переключение языка Ctrl+Shift (через `CTRL_SHIFT` бит и `UNSHIFT.CHECK_CTRL_SHIFT`); `0` = Ctrl+Space (legacy путь `IFN CHANGE_LANG_CTRL_SHIFT` строки 585-591) | +| `BREAK_PROCESS_CODE` (стр. 23) | `#AC00` | Cooked-код Ctrl+C для `WaitKey`/`EDIT` → `DSS_Error.sys.USER_ABORT` (#25) | +| `USE_E1_SCANCODE` (стр. 24) | `0` | `1` = обрабатывать E1 (Pause/Break), `0` = игнорировать | +| `ENABLED_KEYBOARD_CONTROL` (стр. 24) | `0` | `1` = компилировать `FAKE_SHIFT` (игнор AT fake-shift `E0 12`/`E0 59` вокруг серых nav-клавиш). `0` = выключено: на железе SIO Tx отключён (WR5=`#62`), хост не может слать `0xED`, клавиатура не знает NumLock → fake-shift не приходит. Включать, только если появится двунаправленный канал к клавиатуре. См. §6.5 | +| `SHORT_RSTx10_TABLE` (стр. 10) | `0` | Должен быть `0` (либо ≥#37), иначе клавиатурные слоты не войдут в API table | +| `COMPILE_UNUSED_CODE` (стр. 11) | `0` | Гейтит legacy/debug куски | + +Также в `defines.inc` — мышиные флаги (`MOUSE_INT_ENABLED`, ...) которые +делят с клавиатурой инфраструктуру SIO/IRQ. + +--- + +## 6. Аппаратура Sprinter / Z84C15 + +### 6.1. Карта внутренних портов Z84C15 +`Shared_Includes/constants/SP2000.inc`, `MODULE Z84` (строки 2111-2127): + +| Порт | Назначение | +|------|------------| +| `#10..#13` | `CTC.Ch_0..3` (таймеры) | +| **`#18`** | `Z84.SIO.Ch_A.Data` — **PS/2 клавиатура DAT_A** | +| **`#19`** | `Z84.SIO.Ch_A.Ctrl` — **PS/2 клавиатура COM_A** | +| `#1A` | `SIO.Ch_B.Data` (DMOUSE) | +| `#1B` | `SIO.Ch_B.Ctrl` (CMOUSE) | +| `#1C..#1D` | `PIO.Port_A` — LPT1 (принтер) | +| `#1E..#1F` | `PIO.Port_B` — LPT2 | +| `#F0..#F1` | WDT | +| `#F4` | `IntPrior_Reg` | +| `#EE/#EF` | `SYS.Control / SYS.Data` | + +Так что коммит `e334545 "M_INT: RFI is CH-A ONLY (per Z80 SIO spec)"` +относится к SIO Ch_A (клавиатура) — принтер на PIO, не на SIO. + +### 6.2. Порт бипера и банкование +- `SP_SND.Beeper` = порт `#FE`, бит 4 (`%00010000`). Прямая запись из + KEYINTER (нет BIOS-функции для звука). +- `SLOT0..SLOT3` = `#82, #A2, #C2, #E2` — внешние порты переключения + страниц памяти на окна `#0000/#4000/#8000/#C000`. `SET_PAGE_X` из + `DSS_MACROSES.Z80` (137-143) использует SLOT3 + `BANKTBL[page]`. +- `TXTPAGE` — индекс в `BANKTBL` для страницы шрифта (используется в + `SETUP_CURSORS` строка 304). Если EQU не определён в снимке репо, + он приходит из внешнего SP2000-инклюда (см. `Build/Variables.inc` + после первой сборки). + +### 6.3. Прерывания +- IM 1, единый вектор `#FF` для **кадрового И клавиатурного** прерывания. +- Различие: после входа в `INT 38h` ([DSS-MAIN.ASM:275](DSS/DSS-MAIN.ASM)), + читать порт `#19` (SIO Ch_A Ctrl/RR0); `bit0=1` → пришёл байт от + клавиатуры (в FIFO). Это и делает `KEYSCAN.RESCAN`. +- SIO Ch_A имеет **Rx FIFO на 3 байта** — `sp2000.pdf §9.4` явно + предписывает: «после обработки одного байта проверять, не пришло ли + ещё, и возвращаться только если FIFO пуст». +- Включение режима, при котором клавиатурный INT работает: + `Port_All_Mode` = `#204E`, биты `SPECTRUM_MODE_OFF=1` (бит 0) и + `STOP_KBD_INT_OFF=8` (бит 3) (см. `SP2000.inc`). +- Активный указатель ISR хранится в `SYS_PAGE.INT_ADRESS = #FEC124`, + `INT_PAGE = #FEC126`, `INT_ID = #FEC127` (сентинель `#AA` — установлено). + +### 6.4. Z80 SIO регистры (для модификаций инициализации) +- **WR0** — command + pointer на следующий WR/RR. +- **WR1** — interrupt enable (бит 0 ExtINT, биты 1-2 Tx Int, биты 3-4 Rx Int + mode `%01100` = INT_ON_RXBYTE), бит 5 Wait/Ready. +- **WR2** — Interrupt vector (только Ch_B по Z80 SIO spec — нерелевантно + для клавиатуры). +- **WR3** — Rx control: bit0 Rx Enable, биты 6-7 Rx bits/character. +- **WR4** — clock multiplier, stop bits, parity. +- **WR5** — Tx control: бит 3 Tx Enable, биты 5-6 Tx bits/character. +- **RR0** — статус: **бит 0 = Rx Character Available** (то что тестирует + KEYINTER), бит 1 = Int Pending (CH-A only), бит 2 = Tx Buffer Empty, + бит 5 = Sync/Hunt, бит 6 = CTS, бит 7 = Break. +- **RR1** — special Rx conditions: framing/parity/overrun errors. +- Полный datasheet — Zilog Z80 SIO Technical Manual (UM008); в репо его + нет, см. ссылки в §8. + +### 6.5. Команды PS/2 хост→клавиатура (host commands) +Если потребуется управлять светодиодами Caps/Num/Scroll или autorepeat, +то протокол описан в [/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/KBD.TXT](/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/KBD.TXT): +- `#FF` reset+self-test, `#FE` resend, `#F4` enable scanning, `#F5` disable+default, +- `#ED` set LEDs (bit0 Scroll, bit1 Num, bit2 Caps), +- `#F3` set typematic rate+delay (биты 6-5 delay 250/500/750/1000 ms, + биты 4-0 rate 6..30 cps), +- `#F2` read keyboard ID, +- `#FB-#FD`, `#F7-#FA` per-key/all-keys typematic. + +**Передача клавиатуре аппаратно невозможна в текущей конфигурации**: `KEYBOARD_INIT` +ставит WR5 = `#62` (бит3 Tx Enable = 0), т.е. передатчик SIO Ch_A выключен. +Поэтому host-команды (`0xED` Set LEDs, autorepeat и др.) не отправляются и не могут. + +Важное следствие про **fake-shift**: по стандарту AT/PS-2 клавиатура шлёт fake-shift +(`E0 12` / `E0 59` вокруг серых extended nav-клавиш — стрелки/Ins/Del/Home/End/PgUp/PgDn) +ТОЛЬКО когда её внутренний Num Lock-LED включён. А LED выставляет ТОЛЬКО хост командой +`0xED` (нажатие Num Lock для клавиатуры — обычный скан-код `0x77`, своё состояние она не +меняет). Раз `0xED` послать нельзя → клавиатура всегда считает Num Lock выключенным → +**fake-shift на реальном железе не генерируется**, выделенные стрелки всегда приходят +чисто (`E0 6B` и т.п.). Обработка fake-shift реализована в `FAKE_SHIFT`, но компилируется +только при `ENABLED_KEYBOARD_CONTROL=1` (§5) — на железе это мёртвый код, нужен лишь для +эмуляторов (MAME msnat сам моделирует Num Lock+fake-shift, чего на железе быть не может). +Чтобы реально слать команды — включить Tx (WR5 бит3=1) и писать в `#18` после проверки +готовности Tx Buffer (RR0 bit2). + +### 6.6. CMOS-привязка +- `CMOS_CELL.BootUpParams` = `#0E`, `.Mask.Language = %0000'0100` — пресет + языка при загрузке. +- `CMOS_CELL.Typematic` = `#0F`, маски `.Enabled %1000'0000`, + `.Delay %0110'0000`, `.Rate %0000'0111`. +- Доступ через `BIOS.CMOS_RD (#F6) / CMOS_WR (#F7)` или прямые порты + `CMOS.Port.{Data.Read=#FFBD, Data.Write=#BFBD, Address.Write=#DFBD}`. +- **Сейчас KEYINTER НЕ читает CMOS** — состояние локов и языка + сбрасывается на каждый boot к дефолтам. Если нужна persistence, + добавлять в `KEYBOARD_INIT` или в высокоуровневый `AUTOEXEC.BAT`. + +--- + +## 7. Reference материалы + +### 7.1. В репозитории +| Документ | Что искать | +|----------|------------| +| [Shared_Includes/Docs/sp2000.pdf](Shared_Includes/Docs/sp2000.pdf) | §1.1 Sp2000 hardware (p.4), §1.3 block diagram (p.5), §9 Внутренние порты Z84C15 (p.21), **§9.4 AT-Клавиатура p.25-26** (COM_A/DAT_A, sample code), §13.2 карта портов p.31 | +| [Shared_Includes/Docs/BIOS functions.asm](Shared_Includes/Docs/BIOS%20functions.asm) | Раздел 5 «Функции печати и управления режимом экрана» (стр. 628-1100): `LP_PRINT_SYM #82`, `LP_PRINT_ALL #81`, `LP_SET_PLACE #84`, `LP_GET_PLACE #8E`, `WIN_GET_SYM #B4`, `WIN_PUT_SYM #B5`, `WIN_GET_ZG #B8`, `WIN_SET_ZG #B6`, `LP_SCROLL_UD #8A`, `LP_PR_LINE_DIR #E0`. Конвенция вызова — стр. 1-60 | +| [Shared_Includes/Docs/DSS_1.71_Functions.asm](Shared_Includes/Docs/DSS_1.71_Functions.asm) | **Раздел 6 «Функции ввода с клавиатуры» (строки ~364-446)** — авторитетная спецификация на функции #30..#37 с корректировками из последней сессии (Pause Lock bit6, CTRLKey A=#FF/A=0, K_CLEAR INVALID_FUNCTION, K_SETUP B=0 это Get/Set table transfer) | +| [Shared_Includes/constants/dss_equ.inc](Shared_Includes/constants/dss_equ.inc) | `Dss.WaitKey..TestKey` (137-149), `Dss.K_SETUP.*` (144-148), `DSS_Error.sys.*` (280-336), **Приложение А — позиционные коды клавиш** (547-595) | +| [Shared_Includes/constants/BIOS_equ.inc](Shared_Includes/constants/BIOS_equ.inc) | `BIOS.*` функции (см. §7.1 ниже) | +| [Shared_Includes/constants/SP2000.inc](Shared_Includes/constants/SP2000.inc) | `MODULE Z84` (2111-2127), `SP_SND`, `ACEX.*`, `ZXKeys.Line_*` (#FEFE..#7FFE legacy ZX), `Port_All_Mode #204E`, `SYS_PAGE.INT_*`, `CMOS_CELL.*` | +| [Shared_Includes/constants/zx_char_codes.inc](Shared_Includes/constants/zx_char_codes.inc) | Control codes ZX: `.cursor_left=#08 (backspace)`, `.right=#09 (== TAB!)`, `.cursor_down=#0A`, `.cursor_up=#0B`, `.delete_left=#0C`, `.carriage_return=#0D`, и т.п. | +| [Shared_Includes/constants/dss_errors.z80](Shared_Includes/constants/dss_errors.z80) | Строки ошибок: #01 Invalid function, #0E Unknown operation, #13 Access denied, #20 Operation not supported, #25 User abort, #27 Unexpected app termination | +| [DSS/DSS_MAP.TXT](DSS/DSS_MAP.TXT) | Карта памяти ядра — #0400-#043F SBUF, #0440-#0BD1 KEYBOARD DRIVER | +| [DSS/CHANGES.LOG](DSS/CHANGES.LOG) | Хронология; ECHOKEY cursor 2003-02-10, txt 40x32 cursor bug, OVR cursor square | +| [DSS/KNOWN.BUG](DSS/KNOWN.BUG) | §3.3-3.4 — legacy ECHOKEY/PUTCHAR закомментированы, можно убирать; буферы #100/#80 без bounds-check | + +### 7.2. В `Another/` (референсы, не собираются) +| Файл | Зачем | +|------|-------| +| [/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Sprinter_Programming.pdf](/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Sprinter_Programming.pdf) | **p.22 «Прерывания»** (вектор #FF, бит 0 порта #19), **p.25-26 «Клавиатура»** (пример K_SETUP layout-table, 9×16=144 байта на подтаблицу, Ctrl+Space layout switch), p.27 коды ошибок | +| [/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/KBD.TXT](/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/KBD.TXT) | PS/2 host→keyboard команды (см. §6.5) | +| [/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/AT-Keyboard.pdf](/Users/tolik/Documents/SP_Projects/ASM/Another/Docs/Keyboard/AT-Keyboard.pdf) | Scan Code Set 2 на 3 страницах | +| [/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/TASM/Keybdrv.z80](/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/TASM/Keybdrv.z80) | Минималистский standalone-драйвер клавиатуры Дениса Паринова (517 строк): полная init-последовательность 9 байт WR0..WR5 на ComA=#19, чтение DataA=#18. Полезно при отладке железа отдельно от DSS | +| [/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/TASM/Scantabl.z80](/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/TASM/Scantabl.z80), [Scantabl2.z80](/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/TASM/Scantabl2.z80) | Альтернативные scancode→symbol таблицы (для сверки `XLAT_T`) | +| [/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/SRC/cpm3-s/SCAN.PLM](/Users/tolik/Documents/SP_Projects/ASM/Another/SPRINTER/SRC/cpm3-s/SCAN.PLM) | CP/M-3 Sprinter scan-логика на PL/M (третий независимый референс) | +| **НЕ нужно**: `Another/scancode.inc` | NASM/x86 BIOS INT16h (Sergey Kiselev Micro-8088). Другая архитектура, пропустить | + +### 7.3. Внешние (нужно скачать) +- **Zilog Z80 SIO Technical Manual (UM008)** — главы 3-4: полный layout + `WR0..WR7` / `RR0..RR2`. `sp2000.pdf §9` явно отсылает туда («Ссылка + на описание PIO, SIO и т.д. от Zilog»). +- **Zilog Z84C15 Product Specification** — карта внутренних портов, + CTC/PIO timing. + +--- + +## 8. История изменений KEYINTER (git log) + +`git log --oneline -- DSS/KEYINTER.ASM`: +- **9235af1** RUS keys fix +- **f5eacf4** KEYINTER.ASM: russian chars fix +- **e334545** M_INT: RFI is CH-A ONLY (per Z80 SIO spec) — **сохранять** + CH-A-only RFI семантику при правках ISR +- **73c7ab5** K_SETUP show/hide cursor sub-fns +- **12c0287** ECHOKEY scroll fix +- **eae2582** PutChar via BIOS LP_PR_LINE_DIR (#E0) +- **23fa77a** XLAT_T overflow + Ctrl+C +- **ff2f2b9** layout-switch combo (Ctrl+Space vs Shift+Ctrl) compile flag +- **54b1e80** SIO experiments + +При работе всегда смотреть `git log -p DSS/KEYINTER.ASM | head -200` — +часто старые комментарии R-номерами (R01, R02 ...) поясняют исторические +правки. + +--- + +## 9. Полезные команды на хост-системе + +- **Сборка ядра**: VS Code task `Build SYSTEM.DOS` (или `[NEW]` с + инкрементом билда). Из терминала примерно: + ``` + cd "/Users/tolik/Documents/SP_Projects/ASM/GIT/Estex DSS" + sjasmplus --syntax=afw --fullpath -Wno-shortblock \ + --lst=Build/DSS-MAIN.LST --raw=Build/DSS/SYSTEM.DOS \ + --exp=Build/Variables.inc DSS/DSS-MAIN.ASM + ``` +- **Деплой в MAME**: VS Code task `Copy all files to MAME` → запускает + [RUN/Image.sh](RUN/Image.sh) (zsh, `hdfmonkey`). +- **Запуск MAME**: VS Code task `Run MAME`. +- **Прочитать CP866-файл с правильной кодировкой**: + ``` + iconv -f CP866 -t UTF-8 DSS/KEYINTER.ASM | less + ``` +- **grep по бинарно-определяемым файлам** (CP866 ломает heuristic): + ``` + grep -anE "WAITKEY|KEYSCAN" DSS/KEYINTER.ASM + ``` + Флаг `-a` форсит text-режим. +- **Просмотр с табами**: + ``` + sed -n '519,540p' DSS/KEYINTER.ASM | tr -d '\r' | cat -tv + ``` +- **Дамп диспетч-таблицы**: + ``` + sed -n '337,396p' DSS/DSS-MAIN.ASM + ``` + +--- + +## 10. Стилевые соглашения + +- Кодировка CP866 (DOS Russian), переводы строк CRLF. Edit'ы должны их + сохранять. +- Отступы — табы. Комментарии справа от инструкции выровнены табами до + колонки `;`. При вставке новых комментариев-продолжений использовать + 4 таба + `;`. +- Рамки секций — `;████...████` (символ █ = U+2588). Не ломать. +- Стиль меток: метки целиком капсом (`KEYSCAN`, `WAITKEY`), вложенные + через `.` (`KEYSCAN.RESCAN`, `K_SETUP.ERROR`, `Cursor_Off.Flag`). +- Self-modifying code маркирован комментариями вроде `;R01`, `;R13` с + ревизионными номерами — НЕ удалять без причины (это история). +- Хроноразметка `[ ] DD/MM/YYYY` / `[x]` для done — в комментариях. + +--- + +## 10а. Работа с файлами CP866 + CRLF (практические рецепты) + +Это **главный источник тонких багов** при редактировании. Прочитай эту +секцию ДО первой правки. + +### 10а.1. Что именно в CP866 +- Все `DSS/*.asm`, `DSS/*.ASM`, `DSS/*.inc`, `DSS/*.Z80`. +- Все `Shared_Includes/constants/*.inc` и `Shared_Includes/Docs/*.asm`. +- `DSS/CHANGES.LOG`, `DSS/KNOWN.BUG`, `DSS/DSS_MAP.TXT`. +- `Another/SPRINTER/...`, `Another/Docs/Keyboard/KBD.TXT`. + +PDF в `Shared_Includes/Docs/sp2000.pdf` и `Another/Docs/*.pdf` — отдельная +история (текст внутри PDF в своей кодировке, см. `pdftotext`). + +UTF-8 в этом проекте бывает только в `*.md` (вроде этого файла), `*.json` +(VSCode-конфиги), `*.sh`, `*.lua` и `.gitmodules`. + +### 10а.2. Байтовая карта CP866 (минимум, который надо помнить) +| Байт(ы) | Что | +|---------|-----| +| `#80..#8F` | `А..О` (рус. заглавные, первая половина) | +| `#90..#9F` | `П..Я` (рус. заглавные, вторая половина) | +| `#A0..#AF` | `а..п` (рус. строчные, первая половина) | +| `#B0..#B2` | `░ ▒ ▓` (shading) | +| `#B3..#DA` | псевдографика `│ ─ ┌ ┐ ┘ └ ┤ ├ ┬ ┴ ┼ …` и двойные `║ ═` | +| **`#DB`** | **`█` — full block, из которого строятся рамки `;██..██` в этом проекте** | +| `#DC..#DF` | `▄ ▌ ▐ ▀` | +| `#E0..#EF` | `р..я` (рус. строчные, вторая половина) | +| `#F0, #F1` | `Ё ё` | +| `#FC` | `№` | +| `#FE` | `■` | + +Важно: +- **`█` = один байт `#DB` в CP866**, а в UTF-8 это **три байта `E2 96 88`**. + Поэтому строчка `;████████` длиной ~110 символов в CP866 занимает ~110 + байт, а в UTF-8 — ~330 байт. +- Если случайно конвертнуть файл в UTF-8 и забыть конвертнуть обратно, + размер файла резко вырастает, выравнивание комментариев плывёт, а + sjasmplus может выдать странные ошибки на строковых литералах. + +### 10а.3. Просмотр и поиск + +**Просмотр через тулзу Read**: русский текст может отображаться как +заполнители или мусор, потому что Read декодирует как UTF-8. Полагаться +на это для содержания комментариев **нельзя** — но для проверки кода +(меток, инструкций Z80, hex-литералов) подходит. + +**Просмотр в человеческой форме** — через Bash + iconv: +```sh +iconv -f CP866 -t UTF-8 DSS/KEYINTER.ASM | less +iconv -f CP866 -t UTF-8 DSS/KEYINTER.ASM | sed -n '519,540p' +``` + +**Просмотр с табами/CRLF**: +```sh +sed -n '519,540p' DSS/KEYINTER.ASM | iconv -f CP866 -t UTF-8 | cat -tev +# ^I = табы, $ = конец строки (CRLF будет показан как ^M$) +``` + +**grep по ASCII-меткам** — `-a` обязательно: +```sh +grep -an "WAITKEY\|KEYSCAN\|K_SETUP" DSS/KEYINTER.ASM +``` +Без `-a` grep с какого-то порога считает CP866 бинарным и молча выдаёт +только имя файла. + +**grep по русским словам** — через pipe iconv (номера строк сохраняются, +т.к. количество переводов строк не меняется): +```sh +iconv -f CP866 -t UTF-8 DSS/KEYINTER.ASM | grep -an "клавиш" +``` +Альтернатива: сконвертить запрос в CP866 и грепать байтами (но это +крайне неудобно — pipe-метод лучше). + +**Полный hex-дамп строки** (для разбора, что именно лежит в файле): +```sh +sed -n '519p' DSS/KEYINTER.ASM | xxd | head +``` + +### 10а.4. Редактирование — критическое + +**Главная проблема Edit-инструмента**: он работает на байтовом уровне. +Если файл в CP866, а `old_string` в твоей tool-call'е содержит русский +текст в UTF-8, то байты НЕ совпадут и Edit упадёт с `String not found`. +Если случайно `new_string` запишется UTF-8'ом в CP866-файл, файл +ломается локально (на конкретной строке). + +**Безопасные паттерны**: +1. **ASCII-only анкоры (90% случаев)**. Выбирай `old_string` так, чтобы он + состоял из инструкций Z80, меток, hex-литералов и английских/латинских + фрагментов. Кириллический хвост строки пройдёт «как есть» — Edit не + трогает то, что не в old_string. + ``` + old_string: " RST ToDSS\t\t\t; " + ``` + Это сработает, даже если справа после `; ` идёт русский комментарий. + +2. **Если кириллица обязана быть в old_string** (например, надо заменить + текст внутри русского комментария) — сначала **сконвертировать + фрагмент в CP866** через Bash: + ```sh + echo -n "максимальный номер диска" | iconv -f UTF-8 -t CP866 | xxd + ``` + получишь байты, и можешь искать/заменять через `sed` или `perl` с + `LC_ALL=C` (байтовый режим), а не через Edit. + +3. **Удобный трюк**: убедиться, что `old_string` уникально совпадает с + ASCII-частью комментария или ID: + ``` + old_string: " LD A,disk_num\t\t\t; " + new_string: " LD H,device_num\t\t; " + ``` + и оставить хвостовую кириллицу в покое. + +4. **Не вставляй русский текст напрямую через Edit**, если файл в CP866. + Если требуется добавить русский комментарий, сделай это через Bash: + ```sh + echo -n "; новый комментарий" | iconv -f UTF-8 -t CP866 >> /tmp/append + # затем вставляй байты через sed/perl + ``` + Или согласись писать новые комментарии на английском/латинице (ASCII) + — это безопаснее, и стиль файла это терпит. + +### 10а.5. Сохранение CRLF +- Файлы используют `\r\n` (Windows-стиль), не `\n`. +- При вставке новых строк через Edit убедись, что в `new_string` есть + `\r` перед `\n`. Если Edit-инструмент это съест и поставит только + `\n`, файл получит **смешанные line endings** — sjasmplus съест, но + `git diff` будет показывать всю окрестность как изменённую, и в + Windows-редакторах текст рассыпется. +- **Альтернатива**: после Edit-сессии нормализуй переводы строк: + ```sh + # Проверить: + file DSS/KEYINTER.ASM + # Должно быть: "with CRLF line terminators" + # Если стало "with CRLF, LF line terminators" — есть смесь, чинить: + perl -i -pe 's/\r?\n/\r\n/g' DSS/KEYINTER.ASM + ``` + +### 10а.6. Проверка после правки (обязательная) +```sh +file DSS/KEYINTER.ASM +# Ожидается: "Non-ISO extended-ASCII text, with CRLF line terminators" +# НЕ должно быть "UTF-8 Unicode text" или "with LF line terminators" + +# Проверка, что рамки █ не превратились в UTF-8 (3 байта): +grep -c $'\xDB\xDB\xDB' DSS/KEYINTER.ASM +# Должно быть положительное число (несколько штук). 0 = рамки сломаны. + +# git diff с пониманием бинарного представления: +git diff DSS/KEYINTER.ASM | cat -v | head -50 +# Cyrillic должен показываться как M-X M-X последовательности байт +``` + +### 10а.7. Откат, если что-то сломалось +```sh +# Один файл — мгновенный откат: +git checkout HEAD -- DSS/KEYINTER.ASM + +# Если уже закоммитил битый файл — посмотреть предыдущую версию: +git show HEAD~1:DSS/KEYINTER.ASM | iconv -f CP866 -t UTF-8 | less +``` + +### 10а.8. Конвертация всего файла «туда-обратно» (последнее средство) +Если правок очень много и проще править в UTF-8: +```sh +# 1. Конвертация в UTF-8 + переход на LF (так удобнее редактировать): +iconv -f CP866 -t UTF-8 DSS/KEYINTER.ASM | tr -d '\r' > /tmp/KEYINTER.utf8 + +# 2. Правки в /tmp/KEYINTER.utf8 любым инструментом (Edit/sed/perl). + +# 3. Обратно в CP866 + восстановление CRLF: +iconv -f UTF-8 -t CP866 /tmp/KEYINTER.utf8 | perl -pe 's/\r?\n/\r\n/g' > DSS/KEYINTER.ASM + +# 4. Проверка: +file DSS/KEYINTER.ASM +git diff --stat DSS/KEYINTER.ASM +``` +**Риск**: если в файле есть байты, не имеющие пары CP866↔UTF-8 (теоретически +вряд ли в этом проекте, но возможно при кривых правках в истории), iconv +ругнётся с `illegal input sequence`. Тогда `iconv -c` пропустит проблемные +байты — но они **потеряются**. Безопаснее в этом случае работать +ASCII-only анкорами через Edit. + +### 10а.9. VS Code как замена тулинга +Если хочется визуальной правки: +- VS Code: правый-нижний угол → `Reopen with Encoding → Cyrillic (CP866)`. +- Для постоянной ассоциации `.asm/.ASM/.inc` с CP866 добавить в + `.vscode/settings.json`: + ```json + { + "[asm]": { "files.encoding": "cp866" }, + "files.eol": "\r\n" + } + ``` +- При сохранении проверь нижнюю панель — индикатор должен показывать + «CP866» и «CRLF», а не «UTF-8» / «LF». + +### 10а.10. Чек-лист: «изменения сохранят кодировку» +- [ ] `file <изменённый.asm>` → `Non-ISO extended-ASCII text, with CRLF line terminators` +- [ ] `grep -c $'\xDB\xDB\xDB' <изменённый.asm>` > 0 (если в файле были рамки) +- [ ] `git diff <изменённый.asm> | wc -l` разумного размера (не в 3× больше ожидаемого — иначе UTF-8 раздувание) +- [ ] Сборка `Build SYSTEM.DOS` проходит без warning'ов вроде «invalid character in string literal» +- [ ] Открыть результат в VS Code с CP866 — комментарии читаются по-русски + +--- + +## 11. Что важно помнить, прежде чем менять KEYINTER + +1. **Файл подключается `INCLUDE`'ом** в `DSS-MAIN.ASM:402`, сборка идёт + как монолит. Все символы видны глобально. +2. **Состояние клавиатуры — RAM-only**: не персистится в CMOS. Любая + настройка (язык, локи, sound flags, ASCII-таблицы) теряется на + reset/power-off, если её не сохранить через AUTOEXEC.BAT. +3. **Клавиатура и мышь делят окно INT 38h** — мышь идёт после `KEYSCAN`. + Долгая работа в `KEYSCAN` задерживает мышь. +4. **SIO Ch_A FIFO = 3 байта** — `.RESCAN` должен дренировать его + полностью за один заход (текущая реализация это делает через + `JP .RESCAN` на строке 628). +5. **`KEYBOARD_INT_ENABLED=0`** — текущий билд поллит, не использует SIO + INT. Если хочется перейти на прерывания, нужно переключить флаг, + убедиться что `KEYBOARD_INIT` пишет WR1=`#19`, и проверить что + обработчик RFI в `DSS-MAIN.ASM` корректно настроен (Z80 SIO Ch_A only). +6. **При правке HEAD/HOST убедиться, что `RES 6,(HL)` сохранён** — это + обеспечивает wrap modulo 64. Если изменишь размер `SBUF`, поменяй и + маску (бит-логика `RES 6` работает только для 64 = #40). +7. **При правке `XLAT_T`** — длина 144 байта (`Size`), bounds-check + `CP XLAT_T.Size` на строке 860. Если расширяешь, проверь, что не + натыкаешься на следующую область (`CURRENT DIR NAME BUFFER` по + DSS_MAP.TXT идёт от #1343). +8. **Двойственность `D` в записях буфера**: D[7] = «keystroke flag», + D[6:0] = позиционный код 0..#5A. `INPCODE/CONVERT` ставит бит 7 через + `SET 7,D` — это видимый паттерн. +9. **При правке ASCII-таблиц** — каждая ровно 90 байт, проверяется + `ASSERT .Size = Size`. Если меняешь размер, меняй и `Size EQU 90` + на строке 1286. +10. **Звук работает в обход BIOS** — прямой `OUT (SP_SND.Beeper),A` + (порт #FE бит 4). Это запрещает звуковые эффекты, если процесс + держит порт #FE для других целей (ZX-режим). Учитывать при + модификациях `BEEP`/`FULL_BF`/`LANG_X`. + +--- + +## 12. Чек-лист первого подхода + +Сначала открой и прочитай (именно в таком порядке): +1. [DSS/KEYINTER.ASM](DSS/KEYINTER.ASM) целиком (1371 строка). +2. [DSS/DSS-MAIN.ASM](DSS/DSS-MAIN.ASM): строки 187-213 (`RST_10`), + 275-310 (`INTx38_Handler`), 337-396 (`DSS_API_TABLE`), 402 (INCLUDE), + 423 (`BANKTBL`), 567-600 (boot-флоу). +3. [DSS/defines.inc](DSS/defines.inc) (короткий). +4. [Shared_Includes/Docs/DSS_1.71_Functions.asm](Shared_Includes/Docs/DSS_1.71_Functions.asm), раздел 6. +5. [Shared_Includes/constants/dss_equ.inc](Shared_Includes/constants/dss_equ.inc), приложение А (позиционные коды). +6. `Another/Docs/Sprinter_Programming.pdf` p.22, p.25-26 (страницы 25-26 содержат + пример K_SETUP layout-table). +7. `sp2000.pdf` §9.4 (PDF, страница ~25-26). +8. Скачать Zilog Z80 SIO Technical Manual (UM008), если будешь трогать + `KEYBOARD_INIT` или `KBD_Receiver_Overrun`. + +Только после этого формулируй гипотезу и план правок. + +--- + +## 13. Контрольные вопросы перед коммитом + +- [ ] Тестовая сборка `Build SYSTEM.DOS` прошла без ошибок? +- [ ] Кодировка файлов сохранена CP866/CRLF? (`file DSS/KEYINTER.ASM` + должен показать `Non-ISO extended-ASCII text, with CRLF line terminators`) +- [ ] Табы и выравнивание комментариев не нарушены? +- [ ] Если изменён публичный API (#30..#37) — обновлён ли + [Shared_Includes/Docs/DSS_1.71_Functions.asm](Shared_Includes/Docs/DSS_1.71_Functions.asm)? +- [ ] Если изменены константы (`Dss.K_SETUP.*`, ASCII-таблица size, + коды ошибок) — обновлён ли `dss_equ.inc`? +- [ ] Если изменена инициализация SIO — проверено, что коммит совместим + с `e334545 "RFI is CH-A ONLY"`? +- [ ] MAME-прогон (`Run MAME` / `Copy all files to MAME`): клавиатура + реагирует, переключение языка работает, INS/CAPS/NUM/SCRL ведут себя + ожидаемо? +- [ ] Echo (`ECHOKEY`) рисует курсор корректно во всех текстовых режимах + (40×32, 80×32)? +- [ ] `XLAT_T` не вылез за `Size=144`? + +Удачи.