Tolik-Trek/Estex-DSS
1
0
Fork 0
mirror of https://github.com/Tolik-Trek/Estex-DSS.git synced 2026-06-20 11:48:54 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
5180e25f91
Estex-DSS/keys.md
Tolik 5180e25f91 Num Lock numbers
2026-06-18 20:52:50 +10:00

829 lines
54 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Промт для новой сессии: изучение и модификация клавиатурной подсистемы 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`?
Удачи.
Reference in New Issue View Git Blame Copy Permalink