Завершить разделение SDK и внешних проектов

Реализовать двухпанельный Commander от платформенного PoC до этапов P6-P20: EMM-каталог, сортировку и выбор, операции с файлами и деревьями, транзакционное копирование, метаданные, политику конфликтов и предварительную проверку свободного места.

Добавить проектную документацию, HDD/MAME-сценарии и проверенные артефакты. Расширить libc операцией bank_write_page, исправлением режима O_RDONLY и связанными регрессионными проверками.

.clangd

@@ -0,0 +1,13 @@
+CompileFlags:
+  Add:
+    - -Ilibbgi/include
+    - -Ilibc/include
+    - -I.
+    - --target=z80-unknown-unknown
+    - -mz80
+    - -std=c99
+    - -D__SDCC              # если нужно гасить SDCC-специфику через #ifdef
+  Remove:
+    - --target=z80-unknown-unknown
+Diagnostics:
+  UnusedIncludes: None       # опционально, чтобы не ругался на "лишние" инклюды под другой таргет

.codex/README.md

@@ -0,0 +1,29 @@
+# Настройки Codex
+
+`config.toml` и запускной скрипт `toolchain/run-mame-mcp.sh` хранятся в Git.
+Запускайте Codex из корня репозитория или любой вложенной папки.
+Корень определяется через `git rev-parse --show-toplevel`.
+
+На каждом компьютере установите `uv` и `pyenv`. Используется локальный
+pyenv Python 3.12 из `.python-version`; uv ставит только пакет `mcp<2`,
+не управляет версией Python. По умолчанию сервер расположен в соседнем
+`../MAME/src/mame_mcp.py`. При иной раскладке задайте явный путь.
+
+Если расположение отличается, создайте `.codex/mame.local.env` (игнорируется Git):
+
+```sh
+MAME_UV="/opt/homebrew/bin/uv"
+MAME_MCP_SCRIPT="/путь/к/MAME/src/mame_mcp.py"
+MAME_PYTHON="/путь/к/pyenv/versions/3.12/bin/python"
+```
+
+Путь к серверу может быть абсолютным или относительно корня проекта.
+Пути к uv/Python могут быть абсолютными или именами из PATH; если
+`MAME_PYTHON` не задан, скрипт вызывает `pyenv which python`.
+Переменные можно также передать через окружение Codex; локальный файл имеет
+приоритет. Файл читается как shell-код запускным скриптом, а не самим Codex.
+Не храните в нём секреты и не добавляйте его в Git.
+
+После изменения настроек перезапустите подключение MCP или Codex.
+Инициализация MCP не требует запущенного эмулятора; для команд отладки нужен
+MAME с `mame_bridge.lua` (см. `docs/mame-autotest.md`).

.codex/config.toml

@@ -0,0 +1,28 @@
+[mcp_servers.mame-z80]
+command = "sh"
+args = [
+    "-c",
+    'root=$(git rev-parse --show-toplevel) || exit; exec sh "$root/toolchain/run-mame-mcp.sh"',
+]
+startup_timeout_sec = 60
+
+[mcp_servers.mame-z80.tools.clear_breakpoint]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.list_breakpoints]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.press_key]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.step_out]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.debugger_command]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.pause]
+approval_mode = "approve"
+
+[mcp_servers.mame-z80.tools.status]
+approval_mode = "approve"

.gitignore

@@ -3,30 +3,14 @@
 # ===========================================================================
 
 # `build/` directories anywhere in the tree
-# (top-level build/, lib/build/, toolchain/*/build/, ...)
+# (top-level build/, libc/build/, libbgi/build/, toolchain/*/build/, ...)
 build/
 
 # sprinter-cc per-example intermediate directory
 .sprinter-cc-*/
+.resource-stamps/
 
-# Per-program final/intermediate outputs landing alongside the source
-# (real apps under examples/ and libc feature tests under tests/).
-examples/*/*.exe
-examples/*/*.asm
-examples/*/*.lst
-examples/*/*.lk
-examples/*/*.ihx
-examples/*/*.noi
-examples/*/*.sym
-examples/*/*.map
-examples/*/*.rel
-examples/*/*.cdb
-examples/*/*.mem
-examples/*/*.rst
-
-# Temporary build directory for floppy disk image preparation
-examples/*/.disk_tmp/
-
+# Per-program final/intermediate outputs landing alongside SDK tests.
 tests/*/*.exe
 tests/*/*.asm
 tests/*/*.lst
@@ -40,7 +24,7 @@ tests/*/*.cdb
 tests/*/*.mem
 tests/*/*.rst
 
-# libc archive (built from libc/, see lib/Makefile)
+# libc + libbgi archives (built by libc/Makefile + libbgi/Makefile)
 lib/*.lib
 
 # Host-built mkexe binary + test outputs (input fixtures *.bin/*.ihx kept)
@@ -53,6 +37,10 @@ toolchain/mkexe/tests/*.actual
 *.obj
 *.dSYM/
 
+# Python host-tools: bytecode всегда воспроизводим и не входит в исходники.
+__pycache__/
+*.py[cod]
+
 # ===========================================================================
 # Vendored / downloaded
 # ===========================================================================
@@ -64,9 +52,6 @@ third_party/sdcc-*/
 third_party/*.tar.bz2
 third_party/*.tar.gz
 
-# MAME emulator install — ~1 GB binary + ROMs + CHDs
-mame/
-
 # ===========================================================================
 # OS / editor / AI assistant
 # ===========================================================================
@@ -89,3 +74,13 @@ mame/
 
 # Claude Code local settings (per-machine, not for the repo)
 .claude/
+
+# Тяжёлые справочные материалы, НЕ версионируются: docs/extra — архивы
+# исходников (~570 МБ, четыре почти одинаковых bad_apple), docs/sources —
+# клоны чужих репозиториев (Sprinter-BIOS, Estex-DSS, SaymanNsk) со своими
+# .git внутри (в коммите стали бы битыми gitlink-ссылками).
+docs/extra/
+docs/sources/
+
+# Локальные пути MCP; общая конфигурация .codex остаётся в Git.
+/.codex/mame.local.env

.python-version

@@ -0,0 +1 @@
+3.12

AGENTS.md

@@ -0,0 +1,94 @@
+# Sprinter C-Compiler — правила проекта
+
+Target-слой SDCC 4.5 (z80) для компьютера Sprinter Sp2000: crt0,
+линковка, libc, mkexe.  Общение и комментарии — на русском.
+
+## Сборка и проверка
+
+```
+make            # tools + lib + libbgi + все тесты SDK
+make -C libc    # только libc → lib/sprinter.lib (fast) + sprinter_safe.lib
+make -C libbgi  # только BGI → lib/bgi256.lib (fast) + bgi256_safe.lib
+make floppy     # упаковать тесты в build/media/toolkit-tests.img
+make size-check # размерный регресс: _CODE vs docs/size_baseline.tsv
+make size-baseline   # принять текущие размеры эталоном
+```
+
+Обе библиотеки собираются в двух вариантах: fast (дефолт; `-D*_NOCHECK` —
+параметр-валидации вырезаны) и safe (линкуется по `sprinter-cc --safe`).
+Критичные гарды (напр. _fd_guard — 9-й OPEN вешает DSS) — в ОБОИХ.
+
+Графика (BGI) — отдельная библиотека libbgi/ (см. ниже).  Программа,
+использующая graphics.h, собирается с `--gfx 256` (или `--gfx 16` в
+Фазе 2): sprinter-cc подлинкует lib/bgi256.lib и добавит -I libbgi/include.
+
+Одиночный тест: `cd tests/<имя> && make run` (пакует exe + EXTRA_DATA на
+дискету и запускает MAME автоматически через `toolchain/mame_interactive.py`,
+снимает скриншоты, выводит пути).  Для сложных сценариев (диалог, несколько
+шагов ввода) — прямой вызов:
+`pyenv exec python toolchain/mame_interactive.py tests/<имя>/<имя>.exe --snap T1,T2 --timeout T`.
+Скриншоты лежат в `build/mame-autotest/<session>/sprinter/`.
+Подробности: `docs/mame-autotest.md`.
+
+После правок libc/libbgi: пересборка от чистого листа (`make -C libc clean`
+/ `make -C libbgi clean`) не обязательна — stale .rel чистятся
+автоматически; `make size-check` обязателен (рост _CODE без причины —
+регрессия).
+
+## Правила libc
+
+- **1 публичная функция = 1 .c-модуль** (линкер тянет .rel целиком —
+  гранулярность файлов = гранулярность DCE).  Никакой группировки
+  «используются вместе».  Internal-хелперы — тоже по одному на модуль
+  (`_`-префикс); общие статики — в отдельные data-модули
+  (`_xxx_state.c`); internal-заголовки (`_file.h`, `_gfx.h`, …) —
+  рядом с исходниками, НЕ в libc/include.
+- Имя файла = имя функции.  libc/Makefile собирает wildcard'ом —
+  ничего регистрировать не надо.
+- Комментарии — на русском; шапка модуля объясняет что/зачем + ABI.
+- File-scope переменные НЕ инициализировать `= 0` (crt0 зануляет
+  _DATA; см. memory/sdcc_static_storage_gotcha).
+- asm-связки между модулями: `call/jp _global` — ок; `jr/djnz` через
+  границу и fall-through — НЕЛЬЗЯ (docs/libc-split-asm-cases.md).
+- Заголовки: сначала пробовать include_next-паттерн; полная замена
+  SDCC-заголовка обязана дублировать его контракт
+  (docs/libc-headers.md).
+- Справочник API — docs/libc-reference.md (обновлять при добавлении
+  функций).
+
+## Документация source debugger
+
+При изменении `<sdbg.h>`, извлечения/форматирования logMessage,
+поддержанных типов/регистров, чтения указателей или маршрутов MAME/DAP
+одновременно обновлять `docs/sdbg-log-macros.md` и проверяемые примеры;
+ссылки и краткий статус синхронизировать с `docs/mame-source-debug.md`,
+`docs/vscode-sprinter-debug.md`, `docs/mame-source-debug-status.md` и
+`docs/libc-reference.md`. Финальные задачи по hex и разыменованию
+указателей пока только в плане, не считать их рабочим API.
+
+## ABI и платформа (кратко; детали в memory/)
+
+- SDCC `__sdcccall(1)`: arg1 → HL (8-бит → A), arg2 → DE, остальные
+  на стеке (callee-pops в __naked); **возврат int/ptr в DE**, uint8 в A.
+  IX callee-saved (в __naked с IX — push/pop обязательны).
+- ESTEX (rst #0x10): CF=1 — ошибка, код в A → `call __errno_set`;
+  все регистры клобберятся (IX сохранять); стек обязан быть в W2.
+- BIOS (rst #0x08): строки/буферы в #4000-#BFFF.
+- Квирки: ESTEX WRITE возвращает DE=0 на успехе (судить по CF/A);
+  лимит 8 файловых манипуляторов, 9-й OPEN ВЕШАЕТ DSS (_fd_guard);
+  ENV $46: A=0 = NOT FOUND.
+- Перед обвинением компилятора/железа — подтвердить артефактом
+  (сгенерированный .asm в libc/build/ или libbgi/build/, дамп, репро) — см.
+  memory/defer_unexplained_quirks.
+
+## Структура
+
+- `libc/<area>/*.c` — модули libc (ядро, БЕЗ графики); `libc/include/` — публичные заголовки libc
+- `libbgi/` — графика BGI (отдельная библиотека): `common/` — mode-agnostic (один исходник, .rel в обеих driver-библиотеках), `bgi256/` + `bgi16/` — mode-specific leaf'ы (реальные реализации, без обёрток); `include/` — graphics.h + gfx.h; `_bgi.h` — внутренний заголовок.  Собирает `lib/bgi256.lib` (и `bgi16.lib` в Фазе 2).  Выбор режима линковкой: `--gfx 256` / `--gfx 16`.
+- `runtime/` — crt0-семейство, heap, bank (bank.s собирается per-build)
+- `bin/sprinter-cc` — обёртка компилятора; `toolchain/mkexe` — упаковщик
+- `tests/` — по одному API/фиче; примеры находятся в отдельном репозитории
+  `../Examples`, приложения — в независимых репозиториях `../Applications/*`
+- `docs/` — дизайн-доки; `docs/TODO.md` — roadmap
+- `third_party/solid-c/` — нативный Sprinter C (референс, CP866;
+  их ABI несовместим — только как образец)

CLAUDE.md

@@ -0,0 +1,83 @@
+# Sprinter C-Compiler — правила проекта
+
+Target-слой SDCC 4.5 (z80) для компьютера Sprinter Sp2000: crt0,
+линковка, libc, mkexe.  Общение и комментарии — на русском.
+
+## Сборка и проверка
+
+```
+make            # tools + lib + libbgi + все тесты (45) + examples
+make -C libc    # только libc → lib/sprinter.lib (fast) + sprinter_safe.lib
+make -C libbgi  # только BGI → lib/bgi256.lib (fast) + bgi256_safe.lib
+make floppy     # упаковать все .exe в mame/v306/IMG/mc.img
+make size-check # размерный регресс: _CODE vs docs/size_baseline.tsv
+make size-baseline   # принять текущие размеры эталоном
+```
+
+Обе библиотеки собираются в двух вариантах: fast (дефолт; `-D*_NOCHECK` —
+параметр-валидации вырезаны) и safe (линкуется по `sprinter-cc --safe`).
+Критичные гарды (напр. _fd_guard — 9-й OPEN вешает DSS) — в ОБОИХ.
+
+Графика (BGI) — отдельная библиотека libbgi/ (см. ниже).  Программа,
+использующая graphics.h, собирается с `--gfx 256` (или `--gfx 16` в
+Фазе 2): sprinter-cc подлинкует lib/bgi256.lib и добавит -I libbgi/include.
+
+Одиночный тест: `cd tests/<имя> && make run` (пакует exe + EXTRA_DATA на
+дискету и запускает MAME автоматически через `toolchain/mame_interactive.py`,
+снимает скриншоты, выводит пути).  Для сложных сценариев (диалог, несколько
+шагов ввода) — прямой вызов:
+`python3 toolchain/mame_interactive.py tests/<имя>/<имя>.exe --snap T1,T2 --timeout T`.
+Скриншоты лежат в `mame/v306/snap_auto/sprinter/` (читаются инструментом Read).
+Подробности: `docs/mame-autotest.md`.
+
+После правок libc/libbgi: пересборка от чистого листа (`make -C libc clean`
+/ `make -C libbgi clean`) не обязательна — stale .rel чистятся
+автоматически; `make size-check` обязателен (рост _CODE без причины —
+регрессия).
+
+## Правила libc
+
+- **1 публичная функция = 1 .c-модуль** (линкер тянет .rel целиком —
+  гранулярность файлов = гранулярность DCE).  Никакой группировки
+  «используются вместе».  Internal-хелперы — тоже по одному на модуль
+  (`_`-префикс); общие статики — в отдельные data-модули
+  (`_xxx_state.c`); internal-заголовки (`_file.h`, `_gfx.h`, …) —
+  рядом с исходниками, НЕ в libc/include.
+- Имя файла = имя функции.  libc/Makefile собирает wildcard'ом —
+  ничего регистрировать не надо.
+- Комментарии — на русском; шапка модуля объясняет что/зачем + ABI.
+- File-scope переменные НЕ инициализировать `= 0` (crt0 зануляет
+  _DATA; см. memory/sdcc_static_storage_gotcha).
+- asm-связки между модулями: `call/jp _global` — ок; `jr/djnz` через
+  границу и fall-through — НЕЛЬЗЯ (docs/libc-split-asm-cases.md).
+- Заголовки: сначала пробовать include_next-паттерн; полная замена
+  SDCC-заголовка обязана дублировать его контракт
+  (docs/libc-headers.md).
+- Справочник API — docs/libc-reference.md (обновлять при добавлении
+  функций).
+
+## ABI и платформа (кратко; детали в memory/)
+
+- SDCC `__sdcccall(1)`: arg1 → HL (8-бит → A), arg2 → DE, остальные
+  на стеке (callee-pops в __naked); **возврат int/ptr в DE**, uint8 в A.
+  IX callee-saved (в __naked с IX — push/pop обязательны).
+- ESTEX (rst #0x10): CF=1 — ошибка, код в A → `call __errno_set`;
+  все регистры клобберятся (IX сохранять); стек обязан быть в W2.
+- BIOS (rst #0x08): строки/буферы в #4000-#BFFF.
+- Квирки: ESTEX WRITE возвращает DE=0 на успехе (судить по CF/A);
+  лимит 8 файловых манипуляторов, 9-й OPEN ВЕШАЕТ DSS (_fd_guard);
+  ENV $46: A=0 = NOT FOUND.
+- Перед обвинением компилятора/железа — подтвердить артефактом
+  (сгенерированный .asm в libc/build/ или libbgi/build/, дамп, репро) — см.
+  memory/defer_unexplained_quirks.
+
+## Структура
+
+- `libc/<area>/*.c` — модули libc (ядро, БЕЗ графики); `libc/include/` — публичные заголовки libc
+- `libbgi/` — графика BGI (отдельная библиотека): `common/` — mode-agnostic (один исходник, .rel в обеих driver-библиотеках), `bgi256/` + `bgi16/` — mode-specific leaf'ы (реальные реализации, без обёрток); `include/` — graphics.h + gfx.h; `_bgi.h` — внутренний заголовок.  Собирает `lib/bgi256.lib` (и `bgi16.lib` в Фазе 2).  Выбор режима линковкой: `--gfx 256` / `--gfx 16`.
+- `runtime/` — crt0-семейство, heap, bank (bank.s собирается per-build)
+- `bin/sprinter-cc` — обёртка компилятора; `toolchain/mkexe` — упаковщик
+- `tests/` — по одному API/фиче; `examples/` — реальные приложения
+- `docs/` — дизайн-доки; `docs/TODO.md` — roadmap
+- `third_party/solid-c/` — нативный Sprinter C (референс, CP866;
+  их ABI несовместим — только как образец)

LICENSE

@@ -30,10 +30,10 @@ Vendored third-party components are under their own licenses:
                            for compatibility.  Licence not specified upstream;
                            treat as reference material, do not redistribute
                            original binaries.
-  mame/v306/             — MAME (https://www.mamedev.org), GPL v2+.
-  mame/v306/IMG/*.img *.chd *.iso — Sprinter ROM / DSS / sample disk images
-                           from Peters Plus.  Redistribution policy: see
-                           Peters Plus documentation.
+
+MAME and its Sprinter ROM/DSS/CHD installation are held in a separate
+project and are not distributed with this SDK. Their own licenses and
+redistribution terms apply.
 
 Documentation in docs/converted/, docs/reference/, docs/samples/, and
 docs/memory management/ contains material originally published by Peters Plus

Makefile

@@ -1,11 +1,10 @@
 # Sprinter C Compiler — top-level Makefile
 #
-#   make             build host tools, libc archive, all tests, all apps
+#   make             build host tools, libc archive, all tests
 #   make tools       build only host tools (mkexe)
-#   make lib         build lib/sprinter.lib (libc archive used by sprinter-cc)
+#   make lib         build lib/sprinter.lib (libc) + lib/bgi256.lib (libbgi)
 #   make tests       build all libc feature tests under tests/
-#   make examples    build all real applications under examples/
-#   make floppy      package every .exe + test fixtures into mame/v306/IMG/mc.img
+#   make floppy      пакет всех SDK-тестов в build/media/toolkit-tests.img
 #   make check       run mkexe unit tests
 #   make clean       remove all build artefacts
 #   make sdcc        download/extract vendored SDCC
@@ -13,64 +12,92 @@
 # Most heavy lifting is delegated to sub-Makefiles.
 
 # Small libc-feature tests (one program per .c-language feature or libc API).
-TESTS := hello banked bankedbg strtest cat seek malloc mem_test argv errno \
-         rt_test openenv ls conio attrprob timedir mouse banklocl stdlib \
-         assrtest ptime stattest filetest gfx_demo gfx_d16 gfx_text gfx_mous
-
-# Larger end-user applications under examples/.
-APPS  := mdview
-
-MAME_DIR    := mame/v306
-FLOPPY_IMG  := $(MAME_DIR)/IMG/mc.img
-MAKE_DISK   := $(MAME_DIR)/make_disk.py
+TESTS := hello hello2 simple banked bankedbg banktest strtest cat seek \
+         malloc mem_test argv errno rt_test openenv ls conio conio2 \
+         attrprob timedir mouse banklocl stdlib assrtest ptime stattest \
+         filetest fdmax fbench solidt irqtest cbltest cblwav cblstream dec_test gets stest2 winrest \
+         bios_text text_palette \
+         gfx_demo gfx_dbuf bgitest bgi_img accfill
+# gfx_d16 / gfx_text / gfx_mous — 16-цветные; убраны до Фазы 2 (bgi16.lib
+# ещё не собирается).  Вернуть мигрированными на BGI --gfx 16.
+FLOPPY_IMG  := build/media/toolkit-tests.img
+MAKE_DISK   := toolchain/make_disk.py
+MAME_HOME   ?=
+PYTHON      ?= $(shell pyenv which python)
+ifeq ($(strip $(PYTHON)),)
+$(error pyenv Python 3.12 не найден; задайте PYTHON=/путь/к/python3.12)
+endif
 
 TEST_EXES := $(foreach t,$(TESTS),tests/$(t)/$(t).exe)
-APP_EXES  := $(foreach a,$(APPS),examples/$(a)/$(a).exe)
-ALL_EXES  := $(TEST_EXES) $(APP_EXES)
+ALL_EXES  := $(TEST_EXES)
 
 DATA_FILES := \
     tests/cat/test.txt          \
     tests/seek/big.txt          \
-    examples/mdview/SAMPLE.MD
+    tests/cblwav/speech.pcm
 
-.PHONY: all tools lib tests examples check clean sdcc floppy $(TESTS) $(APPS)
+.PHONY: all tools lib tests check clean sdcc floppy run \
+        size-check size-baseline host-tests sdbg-tests $(TESTS)
 
-all: tools lib tests examples
+all: tools lib tests
 
 tools:
 	$(MAKE) -C toolchain/mkexe
 
 lib:
-	$(MAKE) -C lib
+	$(MAKE) -C libc
+	$(MAKE) -C libbgi
 
 check: tools
 	$(MAKE) -C toolchain/mkexe check
 
 tests:    $(TESTS)
-examples: $(APPS)
 
 $(TESTS): tools lib
 	$(MAKE) -C tests/$@
 
-$(APPS):  tools lib
-	$(MAKE) -C examples/$@
 
 # Generate big.txt if missing (gen_bigfile.py creates 100 KB marker file).
 tests/seek/big.txt:
-	cd tests/seek && python3 gen_bigfile.py big.txt 102400
+	cd tests/seek && $(PYTHON) gen_bigfile.py big.txt 102400
 
-# Re-pack the MAME floppy image with every built exe + needed data files.
-floppy: tests examples tests/seek/big.txt
-	python3 $(MAKE_DISK) $(FLOPPY_IMG) $(ALL_EXES) $(DATA_FILES)
+# Собственный SDK-носитель: не изменяет диск MAME или приложения.
+floppy: tests tests/seek/big.txt
+	$(PYTHON) $(MAKE_DISK) $(FLOPPY_IMG) $(ALL_EXES) $(DATA_FILES)
 	@echo
 	@echo "Floppy ready: $(FLOPPY_IMG)"
-	@echo "Run:  cd $(MAME_DIR) && ./run_mame.sh"
+	@echo "Run:  make run MAME_HOME=/путь/к/MAME/runtime"
+
+run: floppy
+	$(PYTHON) toolchain/run_sprinter_mame.py --mame-home "$(MAME_HOME)" --floppy "$(FLOPPY_IMG)"
+
+# Модульные тесты под ucsim_z80.  Обвязка — testkit/, сами наборы лежат
+# рядом с кодом, который проверяют.  MAME не нужна, идут за секунды;
+# ucsim идёт в комплекте нашего SDCC.
+# Тесты продуктов запускаются в собственных репозиториях.
+HOST_TEST_DIRS := testkit
+
+host-tests:
+	@for d in $(HOST_TEST_DIRS); do $(MAKE) -C $$d || exit 1; done
+
+# Отладочная карта: реальные SDCC/linker и протокол транспорта без MAME.
+# Для local pyenv: pyenv exec make sdbg-tests.
+sdbg-tests: tools lib
+	$(PYTHON) -m unittest discover -s tests/sdbg -v
+
+# Размерный регресс: сверить _CODE всех программ с docs/size_baseline.tsv.
+size-check:
+	$(PYTHON) toolchain/size_check.py
+
+# Принять текущие размеры как эталон (после осознанных изменений).
+size-baseline:
+	$(PYTHON) toolchain/size_check.py --update
 
 clean:
 	$(MAKE) -C toolchain/mkexe clean
-	$(MAKE) -C lib clean
+	$(MAKE) -C libc clean
+	$(MAKE) -C libbgi clean
 	@for t in $(TESTS); do $(MAKE) -C tests/$$t clean; done
-	@for a in $(APPS);  do $(MAKE) -C examples/$$a clean; done
 
 sdcc:
 	bash third_party/setup-sdcc.sh

README.md

@@ -27,9 +27,9 @@ banked-call trampolines, graphics & accelerator API, mouse driver wrappers, and
 git clone <this repo> sprinter-c
 cd sprinter-c
 make sdcc                      # one-time: fetch SDCC 4.5 binary (~25 MB)
-make all                       # build mkexe + libsprinter.lib + 27 examples
-make floppy                    # pack everything into mame/v306/IMG/mc.img
-cd mame/v306 && ./run_mame.sh  # boot Sprinter in MAME
+make all                       # build tools, libraries and SDK tests
+make floppy                    # pack tests into build/media/toolkit-tests.img
+MAME_HOME=/путь/к/MAME/runtime make run
 ```
 
 Compile a single program:
@@ -70,7 +70,11 @@ Banked functions are declared with `__banked`:
 void engine_tick(int dt) __banked;   // lives in BANK1, automatically swapped
 ```
 
-## Examples (27 total)
+## SDK tests and separate examples
+
+Programs listed below live in `tests/` and validate the SDK. Demonstration
+applications live in the separate `Examples` repository. Its Makefiles use
+`SPRINTER_ROOT` to find this SDK.
 
 | Example | What it demonstrates |
 |---|---|
@@ -128,8 +132,9 @@ Sprinter-specific:
 ## Toolchain commands
 
 ```sh
-make all              # build mkexe + lib + every example
-make floppy           # repack mame/v306/IMG/mc.img with all .exe files
+make all              # build mkexe + libraries + SDK tests
+make floppy           # pack SDK tests into build/media/toolkit-tests.img
+MAME_HOME=/путь/к/MAME/runtime make run
 make check            # 17 mkexe unit-tests
 make clean            # remove all build artefacts
 make sdcc             # one-time: fetch SDCC 4.5 binary
@@ -144,7 +149,8 @@ sprinter-cc -o foo.exe foo.c [more.c ...] [options]
   --memory-manual SPEC    explicit placement (CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3)
   --stack-size N          bytes reserved for the stack (default ~1278)
   --crt0=TYPE             default | minimal | banked | small
-  --bank N=FILE.c         compile FILE.c into bank N (repeatable, max 15)
+  --bank N=FILE.c         compile FILE.c into bank N (repeatable, consecutive 1..15;
+                          crt0 bank count is generated automatically)
   --debug                 enable runtime diagnostics (defines DEBUG_RT)
   -I PATH                 extra include path
   -L 0xADDR / -E / -S     override load / entry / stack addresses
@@ -197,8 +203,8 @@ runtime/                  crt0 variants (default, minimal, small, banked)
 libc/include/             headers
 libc/io|stdio|mem|gfx/    C and asm sources for libsprinter.lib
 lib/                      Makefile that archives libsprinter.lib via sdar
-examples/                 27 example programs
-mame/v306/                MAME binary + Sprinter ROM/HDD images + floppy script
+tests/                    SDK regression programs
+app.mk                    shared rules for independent applications
 third_party/sdcc/         vendored SDCC 4.5 (fetched via `make sdcc`)
 third_party/solid-c/      reference: original Sprinter native C (for compat target)
 docs/                     documentation
@@ -207,7 +213,7 @@ docs/                     documentation
 ## License
 
 This repository contains:
-* Original code in `bin/`, `toolchain/`, `runtime/`, `libc/`, `lib/`, `examples/` —
+* Original code in `bin/`, `toolchain/`, `runtime/`, `libc/`, `libbgi/`, `lib/` —
   MIT-licensed.
 * `third_party/sdcc/` — SDCC 4.5 under GPLv2 with linking exception
   (see `third_party/sdcc/COPYING.txt`)

app.mk

@@ -1,10 +1,9 @@
 # app.mk — shared Makefile fragment for any standalone Sprinter ESTEX
-# program — used both by libc feature tests under tests/ and by real
-# applications under examples/.
+# program. Приложение может лежать вне репозитория тулкита.
 #
 # Usage in a per-program Makefile:
 #
-#   PROJ_ROOT := $(abspath $(CURDIR)/../..)
+#   SPRINTER_ROOT := /путь/к/C-Compiler
 #   EXAMPLE   := my_program          # base name (matches my_program.c)
 #
 #   # Optional overrides (any combination):
@@ -12,7 +11,10 @@
 #   # STACK_SIZE := 2048              # bytes reserved for the stack
 #   # EXTRA_SRCS := helper.c util.c   # additional .c files in this dir
 #   # EXTRA_FLAGS := --crt0=minimal   # passed through to sprinter-cc
+#   # SRC_DEBUG := 1                # карта C/asm и проверенный debug-пакет
+#   # SRC_DEBUG_FILES := helper.c    # либо карта только выбранных TU
 #   # EXTRA_DATA := test.txt          # extra files to add to `make floppy`
+#   # HDD_DEST_DIR := games/myapp     # общий каталог файлов в `make hdd`
 #
 #   include $(PROJ_ROOT)/app.mk
 #
@@ -25,54 +27,165 @@
 #   all      build $(EXAMPLE).exe                                   (default)
 #   clean    remove build artefacts
 #   floppy   build the example and pack it (alone, plus EXTRA_DATA) into
-#            mame/v306/IMG/mc.img — useful for trying a single program
-#            without rebuilding every example.  Top-level `make floppy`
-#            (in the repo root) still packs all examples.
+#            build/media/$(EXAMPLE).img внутри приложения.
 #   run      floppy + launch MAME
 
+ifeq ($(strip $(PROJ_ROOT)$(SPRINTER_ROOT)),)
+$(error Задайте SPRINTER_ROOT — путь к установленному Sprinter-CC)
+endif
+ifeq ($(strip $(PROJ_ROOT)),)
+PROJ_ROOT := $(SPRINTER_ROOT)
+endif
+ifeq ($(strip $(SPRINTER_ROOT)),)
+SPRINTER_ROOT := $(PROJ_ROOT)
+endif
+
+# SPRINTER_PYTHON в sprinter-cc — один исполняемый файл, а не shell-команда.
+# pyenv which выбирает local .python-version текущего приложения.
+PYTHON      ?= $(shell pyenv which python)
+ifeq ($(strip $(PYTHON)),)
+$(error pyenv Python не найден; задайте PYTHON=/путь/к/python3.12)
+endif
 SPRINTER_CC := $(PROJ_ROOT)/bin/sprinter-cc
 MKEXE       := $(PROJ_ROOT)/toolchain/mkexe/mkexe
 LIB         := $(PROJ_ROOT)/lib/sprinter.lib
 
-MAME_DIR    := $(PROJ_ROOT)/mame/v306
-FLOPPY_IMG  := $(MAME_DIR)/IMG/mc.img
-MAKE_DISK   := $(MAME_DIR)/make_disk.py
-RUN_MAME    := $(MAME_DIR)/run_mame.sh
+ifeq ($(wildcard $(SPRINTER_CC)),)
+$(error SPRINTER_ROOT=$(SPRINTER_ROOT): bin/sprinter-cc не найден)
+endif
+
+MAME_HOME   ?=
+MAME_BIN    ?= $(if $(strip $(MAME_HOME)),$(MAME_HOME)/mame.arm,)
+MAME_ROMPATH ?= $(if $(strip $(MAME_HOME)),$(MAME_HOME)/roms,)
+MAME_DSS_IMAGE ?= $(if $(strip $(MAME_HOME)),$(MAME_HOME)/IMG/dss171u.img,)
+MAME_SYSTEM_HDD_IMAGE ?= $(if $(strip $(MAME_HOME)),$(MAME_HOME)/IMG/sp_hdd_sys.chd,)
+MAME_BIOS   ?= v3.06
+FLOPPY_IMG  ?= $(CURDIR)/build/media/$(EXAMPLE).img
+HDD_IMG     ?= $(CURDIR)/build/hdd/$(EXAMPLE).chd
+MAKE_DISK   := $(PROJ_ROOT)/toolchain/make_disk.py
+MAKE_HDD    ?= $(PROJ_ROOT)/toolchain/make_hdd.sh
+RUN_MAME    := $(PROJ_ROOT)/toolchain/run_sprinter_mame.py
+CHDMAN_BIN  ?= chdman
+MAME_PROFILE_ARGS = --mame-home "$(MAME_HOME)" --mame-bin "$(MAME_BIN)" \
+                    --mame-rompath "$(MAME_ROMPATH)" \
+                    --mame-dss-image "$(MAME_DSS_IMAGE)" \
+                    --mame-system-hdd-image "$(MAME_SYSTEM_HDD_IMAGE)" \
+                    --mame-bios "$(MAME_BIOS)"
 
 # Optional knobs — see top of file.
 MEMORY      ?= tiny
-SOURCES     := $(EXAMPLE).c $(EXTRA_SRCS)
+
+# SRC_DIR / BUILD_DIR — раскладка приложения, которое НЕ держит исходники и
+# выхлоп в одной папке с Makefile (например, SprPoP: src/ и build/).  По
+# умолчанию обе пусты, то есть всё как было: ./$(EXAMPLE).c → ./$(EXAMPLE).exe.
+# Пустое значение обрабатывается отдельной веткой намеренно: "./prog.exe" и
+# "prog.exe" — разные имена целей, и склеивать префикс безусловно нельзя.
+SRC_DIR     ?=
+BUILD_DIR   ?=
+ifeq ($(strip $(SRC_DIR)),)
+MAIN_SRC    := $(EXAMPLE).c
+else
+MAIN_SRC    := $(SRC_DIR)/$(EXAMPLE).c
+endif
+ifeq ($(strip $(BUILD_DIR)),)
+EXE         := $(EXAMPLE).exe
+else
+EXE         := $(BUILD_DIR)/$(EXAMPLE).exe
+endif
+SOURCES     := $(MAIN_SRC) $(EXTRA_SRCS)
+# Аргументы упаковщика HDD.  Обычно это exe и EXTRA_DATA; приложение со
+# своей раскладкой каталогов может переопределить переменную до include.
+HDD_PACK_ARGS ?= $(EXE) $(EXTRA_DATA)
+# Общий каталог назначения внутри HDD. Пустое значение сохраняет прежнюю
+# укладку в корень; вложенные КАТАЛОГ:файл считаются относительно него.
+HDD_DEST_DIR ?=
 
 CC_FLAGS    := --memory $(MEMORY)
 ifneq ($(STACK_SIZE),)
 CC_FLAGS    += --stack-size $(STACK_SIZE)
 endif
 CC_FLAGS    += $(EXTRA_FLAGS)
+ifeq ($(SRC_DEBUG),1)
+CC_FLAGS    += --src-debug
+endif
+ifneq ($(strip $(SRC_DEBUG_FILES)),)
+CC_FLAGS    += $(foreach src,$(SRC_DEBUG_FILES),--src-debug-file $(src))
+endif
 
-all: $(EXAMPLE).exe
+all: $(EXE)
 
-$(EXAMPLE).exe: $(SOURCES) $(MKEXE) $(LIB)
-	$(SPRINTER_CC) $(CC_FLAGS) -o $@ $(SOURCES)
+# runtime/*.s (crt0-семейство, bank.s, heap.s) собираются per-build
+# внутри sprinter-cc — без этой зависимости их правка не перелинкует
+# уже собранный exe (кусало: фикс bank.s не подхватился).
+RUNTIME_DEPS := $(wildcard $(PROJ_ROOT)/runtime/*.s)
+
+# ПРОВЕРКА БАНКОВЫХ ВЫЗОВОВ — сразу после линковки, пока артефакты свежие.
+# Ловит прямой `call` в чужой банк: он собирается МОЛЧА и стреляет диким
+# переходом в пустой хвост банка (разбор — в шапке скрипта).  Запускается
+# только если банки вообще есть, то есть по наличию каталога сборки с
+# bankN_*.asm; обычным небанковым программам ничего не стоит.
+BANK_CHECK := $(PROJ_ROOT)/toolchain/check_bank_calls.py
+
+# ПРОВЕРКА ISR-СТАБА W0-СТРАНИЦ — там же, по свежей карте.  Ловит стаб
+# _gfx_w0_isr, оставшийся в W1: программа, кладущая свои страницы в W0
+# (атласы спрайтов, gfx_w0_map), получает недетерминированные зависания,
+# когда прерывание приходит во время вызова DSS и W1 перемаплен.  Только
+# предупреждение: страницы в W0 кладут не все.  Разбор — в шапке скрипта.
+W0ISR_CHECK := $(PROJ_ROOT)/toolchain/check_w0_isr.py
+
+# Команда/зависимости карты участвуют в пересборке, включая смену режима.
+SDBG_CONFIG := $(dir $(EXE)).resource-stamps/$(EXAMPLE)-config.json
+SDBG_MANIFEST := $(dir $(EXE)).sprinter-cc-$(EXAMPLE)/manifest.json
+.PHONY: sdbg-config-force
+SDBG_CONFIG_ARGS = $(SDBG_CONFIG) $(SPRINTER_CC) $(CC_FLAGS) $(SOURCES) $(SDBG_MANIFEST)
+
+# Проверка содержимого обязательна: mtime make может иметь точность в секунду.
+# Сохранение fingerprint только после успешной сборки позволяет повторить сбой.
+$(EXE): $(SOURCES) $(MKEXE) $(LIB) $(RUNTIME_DEPS) sdbg-config-force $(SPRINTER_CC) $(wildcard $(PROJ_ROOT)/toolchain/sdbg/*.py) $(wildcard $(PROJ_ROOT)/toolchain/sdbg_*.py)
+	@state=$$($(PYTHON) $(PROJ_ROOT)/toolchain/sdbg_config.py check $(SDBG_CONFIG_ARGS)) || exit $$?; \
+	 if [ "$$state" = changed ] || [ -n "$(filter-out sdbg-config-force,$?)" ]; then \
+	   mkdir -p $(dir $@); \
+	   SPRINTER_PYTHON="$(PYTHON)" $(SPRINTER_CC) $(CC_FLAGS) -o $@ $(SOURCES) || exit $$?; \
+	   d=$(dir $@).sprinter-cc-$(EXAMPLE); \
+	   if ls $$d/bank*_*.asm >/dev/null 2>&1; then $(PYTHON) $(BANK_CHECK) $$d || exit $$?; fi; \
+	   if ls $$d/*.map >/dev/null 2>&1; then $(PYTHON) $(W0ISR_CHECK) $$d || exit $$?; fi; \
+	   $(PYTHON) $(PROJ_ROOT)/toolchain/sdbg_config.py save $(SDBG_CONFIG_ARGS); \
+	 fi
 
 $(MKEXE):
 	$(MAKE) -C $(PROJ_ROOT)/toolchain/mkexe
 
+# $(LIB) = lib/sprinter.lib (libc).  Графика (bgi256.lib) собирает
+# libbgi/Makefile; гоним и его — иначе standalone `make` в тесте с
+# --gfx 256 не найдёт bgi256.lib при линковке.  Оба инкрементальные,
+# на повторном запуске ничего не пересобирают.
 $(LIB):
-	$(MAKE) -C $(PROJ_ROOT)/lib
+	$(MAKE) -C $(PROJ_ROOT)/libc
+	$(MAKE) -C $(PROJ_ROOT)/libbgi
 
 clean:
-	rm -rf .sprinter-cc-* $(EXAMPLE).exe
+	rm -rf $(if $(strip $(BUILD_DIR)),$(BUILD_DIR),.sprinter-cc-* $(EXE))
 
-# `make floppy` packs ONLY this program (+ optional EXTRA_DATA files) into
-# the MAME floppy image, replacing whatever was there.  Handy for trying a
-# single program without rebuilding everything.
-floppy: $(EXAMPLE).exe
-	python3 $(MAKE_DISK) $(FLOPPY_IMG) $(EXAMPLE).exe $(EXTRA_DATA)
+# `make floppy` создаёт носитель только этого приложения, без записи в MAME.
+floppy: $(EXE)
+	$(PYTHON) $(MAKE_DISK) "$(FLOPPY_IMG)" $(EXE) $(EXTRA_DATA)
 	@echo
 	@echo "Floppy ready: $(FLOPPY_IMG) (with $(EXAMPLE).exe$(if $(EXTRA_DATA), + $(EXTRA_DATA))) "
-	@echo "Run:  cd $(MAME_DIR) && ./run_mame.sh"
+	@echo "Run:  make run MAME_HOME=/путь/к/MAME/runtime"
 
 run: floppy
-	cd $(MAME_DIR) && ./run_mame.sh
+	$(PYTHON) $(RUN_MAME) $(MAME_PROFILE_ARGS) --floppy "$(FLOPPY_IMG)"
 
-.PHONY: all clean floppy run
+# `make hdd` кладёт носитель в build/ приложения. Для нового inode после
+# пересборки образа запущенный MAME должен быть перезапущен.
+hdd: $(EXE)
+	mkdir -p "$(dir $(HDD_IMG))"
+	CHDMAN_BIN="$(CHDMAN_BIN)" $(MAKE_HDD) $(if $(strip $(HDD_DEST_DIR)),--dest "$(HDD_DEST_DIR)") "$(HDD_IMG)" $(HDD_PACK_ARGS)
+	@echo
+	@echo "HDD (D:) ready: $(HDD_IMG) (with $(EXAMPLE).exe$(if $(EXTRA_DATA), + $(EXTRA_DATA)))"
+	@echo "ВНИМАНИЕ: перезапусти MAME — образ пересобран."
+
+run-hdd: hdd
+	$(PYTHON) $(RUN_MAME) $(MAME_PROFILE_ARGS) --hdd "$(HDD_IMG)"
+
+.PHONY: all clean floppy run hdd run-hdd

bin/sprinter-cc

@@ -15,14 +15,15 @@
 #                           0xA2 to auto-detect whether DSS already mapped W2
 #                           (program > 16 KB) or whether we need to allocate
 #                           it ourselves (program < 16 KB).  Covers 0..30 KB.
-#                    big:   tiny + banked code in W1     [TODO]
-#                    huge:  small + banked code in W3    [TODO]
+#                    big:   tiny + banked code in W1
+#                    huge:  small + banked code in W3
 #                    manual: explicit via --memory-manual / --code-loc / --data-loc
 #   --memory-manual SPEC   placement spec, only with --memory manual.
 #                    SPEC = comma-separated KEY=VAL list:
 #                      CODE=W1|W2  DATA=W1|W2|SAME  BANKED=W1|W3
 #                    Example: --memory-manual CODE=W2,DATA=W2,BANKED=W3
 #   -I PATH          additional include path (repeatable)
+#   -DNAME[=VAL]     preprocessor define, passed to sdcc as is (repeatable)
 #   -L 0xADDR        code load address (default: derived from --memory mode)
 #   -E 0xADDR        entry address       (default: same as -L)
 #   -S 0xADDR        stack address       (default: 0xBFFE)
@@ -32,12 +33,46 @@
 #   --data-loc 0xN   override SDCC --data-loc (default: derived from --memory)
 #   -Wl FLAG         extra linker flag (repeatable)
 #   --bank N=FILE.c  compile FILE.c as bank N; repeatable; pulls crt0_banked
+#   --bank-data [N]  put bank modules' writable data INTO the bank page
+#                    (default: it goes to the shared _DATA in W1/W2, which
+#                    stays mapped and is visible from everywhere).
+#                    Without an argument — for ALL banks (old behaviour).
+#                    With a bank number — only for that bank; repeatable:
+#                      --bank-data 5 --bank-data 6
+#                    Per-bank matters because bank-local data is NOT visible
+#                    from outside the bank: a module with an exported global
+#                    must stay on the shared _DATA while its neighbour keeps
+#                    a big private buffer off the resident budget.
 #                    automatically and adds -Wl-b_BANKN=0x{N}C000
+#   --w3 FILE.c      place FILE.c resident in window 3 (0xC000), called
+#                    DIRECTLY (no trampoline).  Repeatable.  Defaults to
+#                    --memory small; works in tiny|small|big|huge.  DSS maps
+#                    all image pages incl. W3.  Compiled with --codeseg/
+#                    --constseg W3CODE (writable statics stay in W2).  In huge
+#                    the resident page SHARES W3 with trampoline banks: crt0
+#                    captures/restores it (W3_RESIDENT), mkexe gets -W.
+#                    Rules: W3 code must NOT switch the W3 page — this includes
+#                    opening a graphics batch bracket itself (_bgi_begin/_bgi_end
+#                    map the video bank via the SAME port 0xE2; doing that from
+#                    W3 code executes from video RAM -> white screen).  Calling
+#                    HOME graphics primitives is fine: they open and close the
+#                    bracket internally and restore the page before returning.
+#                    W1/W2 code that swaps W3 to another page must restore it;
+#                    no writable data belongs in W3 (code + rodata only).  From a
+#                    __banked context the resident W3 code is unreachable (but
+#                    resident -> __banked via the W1 trampoline is fine).
 #   --mkexe FLAG     extra mkexe flag (repeatable; e.g. --mkexe -p --mkexe 0)
-#   --debug          enable runtime diagnostics — defines DEBUG_RT for both
+#   --max-allocs N   SDCC --max-allocs-per-node (default: 100000 — smaller/
+#                    faster code at the cost of compile time; pass a lower
+#                    value, e.g. SDCC's own default 3000, to compile faster).
+#       --src-debug      карта C/asm для всех пользовательских модулей
+#       --src-debug-file FILE  карта выбранного TU (повторяемый, вместо --src-debug)
+#       --debug          enable runtime diagnostics — defines DEBUG_RT for both
 #                    sdcc (-DDEBUG_RT) and the crt0 assembly (prepended
 #                    `DEBUG_RT = 1`).  Exposes runtime introspection symbols
 #                    such as `_w2_self_allocated` (see <sprinter.h>).
+#   --safe           link safe versions of libraries (e.g. lib/bgi256_safe.lib)
+#                    if they exist; otherwise fall back to standard library.
 #   -v               verbose (echo every command)
 #   -h, --help       show this help
 #
@@ -48,6 +83,18 @@
 
 set -eo pipefail
 
+# Можно выбрать интерпретатор без личного пути в репозитории.
+SPRINTER_PYTHON="${SPRINTER_PYTHON:-python3}"
+
+# Отладочная сборка публикуется транзакционно отдельным драйвером.
+if [[ "${SPRINTER_SDBG_ACTIVE:-}" != 1 ]]; then
+    for arg in "$@"; do
+        if [[ "$arg" == --src-debug || "$arg" == --src-debug-file ]]; then
+            exec "$SPRINTER_PYTHON" "$(dirname "$0")/../toolchain/sdbg_driver.py" "$0" "$@"
+        fi
+    done
+fi
+
 # ------- Locate the toolchain ------------------------------------------------
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 PROJ_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"
@@ -61,6 +108,7 @@ CHECK_BANKS="$PROJ_ROOT/toolchain/check_banks.py"
 RUNTIME="$PROJ_ROOT/runtime"
 LIB_DIR="$PROJ_ROOT/lib"
 INC_DIR="$PROJ_ROOT/libc/include"
+BGI_INC_DIR="$PROJ_ROOT/libbgi/include"   # gfx.h, graphics.h (BGI)
 
 # ------- Defaults ------------------------------------------------------------
 OUT=""
@@ -75,6 +123,8 @@ LOAD_ADDR=""
 ENTRY_ADDR=""
 STACK_ADDR="0xBFFE"
 STACK_SIZE=""        # if set, used to compute HEAP_TOP = STACK_ADDR + 1 - STACK_SIZE
+SRC_DEBUG=0
+SRC_DEBUG_FILES=()
 DEBUG_RT=0           # if 1, prepend `DEBUG_RT = 1` to crt0 + pass -DDEBUG_RT to sdcc
 VERBOSE=0
 USER_INCS=()
@@ -82,10 +132,26 @@ SOURCES=()
 LD_EXTRA=()
 MKEXE_EXTRA=()
 BANK_SPECS=()    # entries like "1=engine.c"
+W3_SPECS=()      # entries like "mod.c" — резидентные модули окна W3 (--w3)
+USER_DEFS=()     # -DFOO / -DFOO=bar — пробрасываются в sdcc как есть
+BANK_LOCAL_DATA=0   # 1 (--bank-data без аргумента): данные ВСЕХ банков — в страницу
+BANK_LOCAL_LIST=()  # номера банков из --bank-data N (по одному на банк)
+W3_RELS=()       # заполняется при компиляции W3-модулей
+W3_LD_FLAGS=()   # -Wl-b_W3CODE=0xC000, если есть --w3
+USER_SET_MEMORY=""  # непусто, если --memory задан явно (для --w3 авто-small)
+W3_RESIDENT_HUGE=0  # 1, если --w3 в режиме huge (резидент делит W3 с банками)
+MAX_ALLOCS="100000"  # sdcc --max-allocs-per-node; дефолт 100000 — агрессивная
+                     # регистровая аллокация (медленнее компиляция, меньше/
+                     # быстрее код; как fast-сборки библиотек).  --max-allocs N
+                     # переопределяет (например 3000 = дефолт SDCC для скорости
+                     # компиляции).
+GFX_MODE=""      # "256" → link BGI graphics.h driver sprinter_gfx256.lib
+SAFE_LIBS=0      # if 1, prefer *_safe.lib variants (fallback to standard)
 
 # ------- Parse args ----------------------------------------------------------
 usage() {
     sed -n '3,28p' "$0" | sed 's/^# \{0,1\}//'
+    echo '  --src-debug / --src-debug-file FILE: карта исходников C и asm'
     exit "${1:-0}"
 }
 
@@ -99,13 +165,30 @@ while [[ $# -gt 0 ]]; do
         -S)            STACK_ADDR="$2";   shift 2;;
         --code-loc)    USER_CODE_LOC="$2"; shift 2;;
         --data-loc)    USER_DATA_LOC="$2"; shift 2;;
-        --memory)      MEMORY_MODE="$2";  shift 2;;
+        --memory)      MEMORY_MODE="$2"; USER_SET_MEMORY=1; shift 2;;
         --memory-manual) MEMORY_MANUAL="$2"; shift 2;;
+        --w3)          W3_SPECS+=("$2");  shift 2;;
         --stack-size)  STACK_SIZE="$2";   shift 2;;
         -Wl)           LD_EXTRA+=("$2");  shift 2;;
+        -D*)           USER_DEFS+=("$1"); shift;;
         --bank)        BANK_SPECS+=("$2"); shift 2;;
+        --bank-data)
+            # Аргумент необязателен: «--bank-data» = все банки (как было),
+            # «--bank-data N» = только банк N, флаг повторяемый.
+            if [[ -n "${2:-}" && "$2" =~ ^[0-9]+$ ]]; then
+                BANK_LOCAL_LIST+=("$2"); shift 2
+            else
+                BANK_LOCAL_DATA=1; shift
+            fi;;
         --mkexe)       MKEXE_EXTRA+=("$2"); shift 2;;
+        --max-allocs)  MAX_ALLOCS="$2";   shift 2;;
+        --gfx)         GFX_MODE="$2";     shift 2;;
+        --src-debug)   SRC_DEBUG=1; shift;;
+        --src-debug-file)
+            [[ $# -ge 2 ]] || { echo "--src-debug-file требует FILE" >&2; exit 1; }
+            SRC_DEBUG_FILES+=("$2"); shift 2;;
         --debug)       DEBUG_RT=1;        shift;;
+        --safe)        SAFE_LIBS=1;       shift;;
         -v)            VERBOSE=1;         shift;;
         -h|--help)     usage 0;;
         -*)            echo "sprinter-cc: unknown option: $1" >&2; usage 1;;
@@ -116,6 +199,84 @@ done
 [[ -z "$OUT" ]]         && { echo "sprinter-cc: -o NAME is required" >&2; exit 1; }
 [[ ${#SOURCES[@]} -eq 0 ]] && { echo "sprinter-cc: no input files" >&2; exit 1; }
 
+# ------- Validate bank layout and derive n_banks ----------------------------
+# crt0_banked loads 16 KB images consecutively and fills _bank_pages[1..N],
+# therefore N is the highest bank number and the numbering must have no gaps.
+# Several source modules may share one bank, so counting --bank options would
+# be incorrect.
+BANK_MAX=0
+BANK_SEEN=()
+for spec in "${BANK_SPECS[@]}"; do
+    if [[ ! "$spec" =~ ^([0-9]+)=(.+)$ ]]; then
+        echo "sprinter-cc: bad --bank specification: '$spec' (expected N=FILE.c)" >&2
+        exit 1
+    fi
+    bank_n="${BASH_REMATCH[1]}"
+    bank_n=$((10#$bank_n))
+    if (( bank_n < 1 || bank_n > 15 )); then
+        echo "sprinter-cc: bank number must be in range 1..15: '$spec'" >&2
+        exit 1
+    fi
+    BANK_SEEN[$bank_n]=1
+    (( bank_n > BANK_MAX )) && BANK_MAX=$bank_n
+done
+for ((bank_n = 1; bank_n <= BANK_MAX; bank_n++)); do
+    if [[ -z "${BANK_SEEN[$bank_n]:-}" ]]; then
+        echo "sprinter-cc: bank $bank_n is missing; banks must be consecutive from 1 to $BANK_MAX" >&2
+        exit 1
+    fi
+done
+
+# ------- --w3: резидентный код окна W3 (подход A) ----------------------------
+# W3-модули едут в область W3CODE @0xC000 и вызываются напрямую (без
+# трамплинов).  Работает поверх small-лейаута: main-код с 0x4100 (W1/W2),
+# W3 свободно, DSS маппит все страницы образа сам (проверено tests/w3probe).
+# --w3 подразумевает small ПО УМОЛЧАНИЮ, но поддержан во всех режимах
+# tiny|small|big|huge.  В huge резидент ДЕЛИТ окно W3 с трамплин-банками
+# (порт 0xE2): crt0_banked запоминает резидентную страницу и возвращает её
+# дефолтом после загрузки банков, а трамплин bank.s сохраняет/восстанавливает
+# W3 на каждый __banked вызов (см. W3_RESIDENT ниже).  Следствие: резидент ->
+# __banked работает, обратное — НЕТ (из банка резидентной страницы в W3 нет).
+if [[ ${#W3_SPECS[@]} -gt 0 ]]; then
+    [[ -z "$USER_SET_MEMORY" ]] && MEMORY_MODE="small"   # --w3 → small по умолчанию
+    case "$MEMORY_MODE" in
+        tiny|small|big|huge) : ;;    # поддержаны (huge — резидент делит W3 с банками)
+        *) echo "sprinter-cc: --w3 поддержан для tiny|small|big|huge (дано: $MEMORY_MODE)" >&2; exit 1;;
+    esac
+    # huge: резидентный W3-код (0xC000, HOME) сосуществует с трамплин-банками
+    # W3 — crt0_banked захватывает резидентную страницу и возвращает её
+    # дефолтом после загрузки банков (см. crt0_banked.s, W3_RESIDENT).
+    W3_RESIDENT_HUGE=0
+    [[ "$MEMORY_MODE" == "huge" ]] && W3_RESIDENT_HUGE=1
+fi
+
+# ------- BGI graphics driver selection (--gfx) -------------------------------
+# graphics.h — mode-agnostic слой; конкретный видеорежим задаёт driver-
+# архив.  Одновременно только один.  drv16 пока не реализован.
+GFX_LD=()
+case "$GFX_MODE" in
+    "")   ;;                                   # graphics.h не используется
+    256)
+        if [[ "$SAFE_LIBS" -eq 1 ]] && [[ -f "$LIB_DIR/bgi256_safe.lib" ]]; then
+            GFX_LD=("-lbgi256_safe")
+            [[ $VERBOSE -eq 1 ]] && echo "  gfx: safe variant (lib/bgi256_safe.lib)"
+        else
+            GFX_LD=("-lbgi256")
+        fi
+        ;;
+    16)   echo "sprinter-cc: --gfx 16 ещё не реализован (пока только 256)" >&2; exit 1;;
+    *)    echo "sprinter-cc: --gfx: ожидается 256 (или 16), дано: $GFX_MODE" >&2; exit 1;;
+esac
+
+# ------- libc variant selection (--safe) --------------------------------------
+# sprinter.lib — fast (LIBC_NOCHECK: параметр-валидации вырезаны);
+# sprinter_safe.lib — с валидациями.  Критичные гарды (_fd_guard) — в обеих.
+LIBC_LD="-lsprinter"
+if [[ "$SAFE_LIBS" -eq 1 ]] && [[ -f "$LIB_DIR/sprinter_safe.lib" ]]; then
+    LIBC_LD="-lsprinter_safe"
+    [[ $VERBOSE -eq 1 ]] && echo "  libc: safe variant (lib/sprinter_safe.lib)"
+fi
+
 # ------- Resolve memory mode → CODE_LOC / DATA_LOC ---------------------------
 # tiny  : CODE in W2 (0x8100), DATA auto after code (= W2)
 # small : CODE in W1 (0x4100), DATA in W2 (0x8000)        — crt0 must alloc W2
@@ -143,7 +304,8 @@ case "$MEMORY_MODE" in
     huge)
         # small layout + banked code in W3.  crt0_banked auto-detects W2
         # the same way crt0_small does, then loads banks from the .EXE.
-        MODE_CODE_LOC="0x4100"; MODE_DATA_LOC="0x8000"
+        # MODE_CODE_LOC="0x4100"; MODE_DATA_LOC="0x8000"
+        MODE_CODE_LOC="0x4100"; MODE_DATA_LOC="0"
         ;;
     manual)
         # Defaults if SPEC omits a key.
@@ -237,6 +399,7 @@ asm_runtime() {
     local prefix=""
     [[ $DEBUG_RT -eq 1 ]] && prefix+="DEBUG_RT = 1"$'\n'
     [[ $BANK_W1   -eq 1 ]] && prefix+="BANK_W1 = 1"$'\n'
+    [[ $W3_RESIDENT_HUGE -eq 1 ]] && prefix+="W3_RESIDENT = 1"$'\n'
     if [[ -n "$prefix" ]]; then
         local patched="$WORK/$(basename "$src" .s)_patched.s"
         { printf "%s" "$prefix"; cat "$src"; } > "$patched"
@@ -262,26 +425,75 @@ if [[ -n "$STACK_SIZE" ]]; then
     printf "    .module sprinter_heap_top\n    ___sdcc_heap_end = 0x%04X\n    .globl ___sdcc_heap_end\n" \
         "$_heap_top" > "$WORK/heap_top.s"
     HEAP_TOP_SRC="$WORK/heap_top.s"
-    [[ $VERBOSE -eq 1 ]] && echo "  heap_top: custom HEAP_TOP=$(printf '0x%04X' $_heap_top) (stack reserve $_stack_sz bytes)"
+    HEAP_TOP_VAL=$(printf '0x%04X' "$_heap_top")
+    [[ $VERBOSE -eq 1 ]] && echo "  heap_top: custom HEAP_TOP=$HEAP_TOP_VAL (stack reserve $_stack_sz bytes)"
 else
     HEAP_TOP_SRC="$RUNTIME/heap_top.s"
+    # Дефолт из runtime/heap_top.s (для отчёта раскладки) — обычно 0xBB00.
+    HEAP_TOP_VAL=$(grep -oiE '___sdcc_heap_end[[:space:]]*=[[:space:]]*0x[0-9A-Fa-f]+' "$RUNTIME/heap_top.s" \
+                   | grep -oiE '0x[0-9A-Fa-f]+' | head -1)
+    HEAP_TOP_VAL="${HEAP_TOP_VAL:-0xBB00}"
 fi
 run "$SDASZ80" -o "$HEAP_TOP_REL" "$HEAP_TOP_SRC"
 
+# Единый путь компиляции выбранных C-модулей с картой исходников.
+compile_c() {
+    local src="$1" rel="$2" selected=$SRC_DEBUG candidate
+    shift 2
+    for candidate in "${SRC_DEBUG_FILES[@]}"; do
+        [[ "$src" -ef "$candidate" ]] && selected=1
+    done
+    if [[ $selected -eq 1 ]]; then
+        run "$SPRINTER_PYTHON" "$PROJ_ROOT/toolchain/sdbg_build.py" compile \
+            --sdcc "$SDCC" --assembler "$SDASZ80" --source "$src" --output "$rel" \
+            -- "${CC_FLAGS[@]}" "$@"
+    elif [[ "${SPRINTER_SDBG_ACTIVE:-}" == 1 ]]; then
+        run "$SPRINTER_PYTHON" "$PROJ_ROOT/toolchain/sdbg_build.py" compile --plain \
+            --sdcc "$SDCC" --assembler "$SDASZ80" --source "$src" --output "$rel" \
+            -- "${CC_FLAGS[@]}" "$@"
+    else
+        run "$SDCC" "${CC_FLAGS[@]}" "$@" -c -o "$rel" "$src"
+    fi
+}
+
+# Уникальные имена объектов в debug-пакете допускают одинаковые basename.
+object_path() {
+    local prefix="$1" src="$2"
+    if [[ "${SPRINTER_SDBG_ACTIVE:-}" == 1 ]]; then
+        "$SPRINTER_PYTHON" -c 'import hashlib, pathlib, sys; p=pathlib.Path(sys.argv[3]); print(sys.argv[1]+"/"+sys.argv[2]+p.stem+"_"+hashlib.sha256(str(p.resolve()).encode()).hexdigest()[:12]+".rel")' "$WORK" "$prefix" "$src"
+    else
+        echo "$WORK/$prefix$(basename "$src" .c).rel"
+    fi
+}
+
 # 2. user sources → .rel (HOME)
 USER_RELS=()
-CC_FLAGS=(-mz80 --no-std-crt0 --std-c99 --opt-code-size -I "$INC_DIR" "${USER_INCS[@]}")
+CC_FLAGS=(-mz80 --no-std-crt0 --std-c99 --opt-code-size -I "$INC_DIR" -I "$BGI_INC_DIR" "${USER_INCS[@]}" "${USER_DEFS[@]}")
 [[ $DEBUG_RT -eq 1 ]] && CC_FLAGS+=(-DDEBUG_RT)
+[[ -n "$MAX_ALLOCS" ]] && CC_FLAGS+=(--max-allocs-per-node "$MAX_ALLOCS")
 for src in "${SOURCES[@]}"; do
-    rel="$WORK/$(basename "$src" .c).rel"
-    run "$SDCC" "${CC_FLAGS[@]}" -c -o "$rel" "$src"
+    rel=$(object_path "" "$src")
+    compile_c "$src" "$rel"
     USER_RELS+=("$rel")
 done
 
+# 2b. --w3 resident modules → .rel.  --codeseg/--constseg W3CODE кладёт код
+#     и rodata в W3 (0xC000); --dataseg НЕ трогаем — писучие статики
+#     остаются в обычном _DATA (W2).  Прямые вызовы, без трамплинов.
+if [[ ${#W3_SPECS[@]} -gt 0 ]]; then
+    for src in "${W3_SPECS[@]}"; do
+        rel=$(object_path "w3_" "$src")
+        compile_c "$src" "$rel" --codeseg W3CODE --constseg W3CODE
+        W3_RELS+=("$rel")
+    done
+    W3_LD_FLAGS+=("-Wl-b_W3CODE=0xC000")
+    [[ $VERBOSE -eq 1 ]] && echo "  w3: ${#W3_SPECS[@]} module(s) resident @0xC000 (direct call)"
+fi
+
 # 3. bank infrastructure — required whenever crt0_banked is in play.
 #    Always assemble bank.s for _bank_pages + the bcall/bjump trampolines.
-#    If the user did not pass any --bank, generate a tiny stub providing
-#    n_banks = 0 (crt0_banked.s imports this symbol unconditionally).
+#    Generate n_banks from the validated --bank layout.  crt0_banked.s imports
+#    this symbol unconditionally, including banked memory modes with zero banks.
 #    In BIG mode banks live in W1 at low16 = 0x4000; in HUGE / default
 #    mode they live in W3 at low16 = 0xC000.
 BANK_RELS=()
@@ -297,21 +509,34 @@ if [[ "$CRT0_TYPE" == "banked" ]]; then
     asm_runtime "$RUNTIME/bank.s" "$BANK_TRAMP_REL"
     BANK_RELS+=("$BANK_TRAMP_REL")
 
-    if [[ ${#BANK_SPECS[@]} -eq 0 ]]; then
-        # User has no banks — supply n_banks=0 so crt0_banked links.
-        STUB_C="$WORK/_n_banks_stub.c"
-        STUB_REL="$WORK/_n_banks_stub.rel"
-        echo "const unsigned char n_banks = 0;" > "$STUB_C"
-        run "$SDCC" "${CC_FLAGS[@]}" -c -o "$STUB_REL" "$STUB_C"
-        BANK_RELS+=("$STUB_REL")
-    else
+    BANK_COUNT_C="$WORK/_n_banks_auto.c"
+    BANK_COUNT_REL="$WORK/_n_banks_auto.rel"
+    echo "const unsigned char n_banks = $BANK_MAX;" > "$BANK_COUNT_C"
+    run "$SDCC" "${CC_FLAGS[@]}" -c -o "$BANK_COUNT_REL" "$BANK_COUNT_C"
+    BANK_RELS+=("$BANK_COUNT_REL")
+
+    if [[ ${#BANK_SPECS[@]} -gt 0 ]]; then
         for spec in "${BANK_SPECS[@]}"; do
             bank_n="${spec%%=*}"
             bank_src="${spec#*=}"
-            rel="$WORK/bank${bank_n}_$(basename "$bank_src" .c).rel"
-            run "$SDCC" "${CC_FLAGS[@]}" \
-                --codeseg "BANK${bank_n}" --constseg "BANK${bank_n}" --dataseg "BANK${bank_n}" \
-                -c -o "$rel" "$bank_src"
+            rel=$(object_path "bank${bank_n}_" "$bank_src")
+            # По умолчанию --dataseg НЕ задаём: писучие данные банкового
+            # модуля (глобалы, file-static, статики функций) остаются в
+            # общем _DATA, то есть в W1/W2 — они замаплены всегда и видны
+            # и банку, и остальному коду.  С --dataseg BANKn они уезжают в
+            # СТРАНИЦУ БАНКА и снаружи не читаются (проверено на .map:
+            # глобал банкового модуля лёг по 0x0001C000): это экономит
+            # W1/W2, но требует ручного контроля видимости, поэтому
+            # включается явно через --bank-data.
+            bank_data_flags=()
+            bank_local=$BANK_LOCAL_DATA
+            for bl in "${BANK_LOCAL_LIST[@]}"; do
+                [[ "$bl" == "$bank_n" ]] && bank_local=1
+            done
+            [[ $bank_local -eq 1 ]] && bank_data_flags=(--dataseg "BANK${bank_n}")
+            compile_c "$bank_src" "$rel" \
+                --codeseg "BANK${bank_n}" --constseg "BANK${bank_n}" \
+                "${bank_data_flags[@]}"
             BANK_RELS+=("$rel")
             # Virtual address: bank_n in upper byte, BANK_LOW16 in low half.
             addr=$(printf "0x%X" $(( (bank_n << 16) | BANK_LOW16 )))
@@ -324,7 +549,9 @@ fi
 IHX="$WORK/$(basename "$OUT" .exe).ihx"
 LINK_FLAGS=(-mz80 --no-std-crt0 --std-c99 --opt-code-size
             --code-loc "$CODE_LOC" --data-loc "$DATA_LOC")
+[[ "${SPRINTER_SDBG_ACTIVE:-}" == 1 ]] && LINK_FLAGS+=(--debug)
 LINK_FLAGS+=("${BANK_LD_FLAGS[@]}")
+LINK_FLAGS+=("${W3_LD_FLAGS[@]}")
 for f in "${LD_EXTRA[@]}"; do LINK_FLAGS+=("$f"); done
 # libsprinter.lib via -l/-L (sdcc passes -lsprinter through to sdldz80).
 #
@@ -335,13 +562,13 @@ for f in "${LD_EXTRA[@]}"; do LINK_FLAGS+=("$f"); done
 # the warning is just noise.  In verbose mode show everything.
 if [[ $VERBOSE -eq 1 ]]; then
     run "$SDCC" "${LINK_FLAGS[@]}" -o "$IHX" \
-        "$CRT0_REL" "$HEAP_TOP_REL" "${USER_RELS[@]}" "${BANK_RELS[@]}" \
-        "-L$LIB_DIR" "-lsprinter"
+        "$CRT0_REL" "$HEAP_TOP_REL" "${USER_RELS[@]}" "${BANK_RELS[@]}" "${W3_RELS[@]}" \
+        "-L$LIB_DIR" "${GFX_LD[@]}" "$LIBC_LD"
 else
     # Drop the warning line + its two follow-up "Library:" lines.
     run "$SDCC" "${LINK_FLAGS[@]}" -o "$IHX" \
-        "$CRT0_REL" "$HEAP_TOP_REL" "${USER_RELS[@]}" "${BANK_RELS[@]}" \
-        "-L$LIB_DIR" "-lsprinter" 2>&1 \
+        "$CRT0_REL" "$HEAP_TOP_REL" "${USER_RELS[@]}" "${BANK_RELS[@]}" "${W3_RELS[@]}" \
+        "-L$LIB_DIR" "${GFX_LD[@]}" "$LIBC_LD" 2>&1 \
         | awk '
             /^\?ASlink-Warning-Definition of public symbol/ { skip = 3 }
             skip > 0 { skip--; next }
@@ -349,9 +576,11 @@ else
         '
 fi
 
-# Quick bank-size check (only meaningful if there are banks).
-if [[ ${#BANK_SPECS[@]} -gt 0 ]] && [[ -f "${IHX%.ihx}.map" ]]; then
-    python3 "$CHECK_BANKS" "${IHX%.ihx}.map" || true
+# Отчёт по раскладке памяти + проверка лимитов — для ЛЮБОЙ модели памяти
+# (сколько свободно в W1/W2, W3 при --w3, и в каждом банке при --bank).
+if [[ -f "${IHX%.ihx}.map" ]]; then
+    "$SPRINTER_PYTHON" "$CHECK_BANKS" "${IHX%.ihx}.map" \
+        --mode "$MEMORY_MODE" --heap-top "$HEAP_TOP_VAL" --stack "$STACK_ADDR" || true
 fi
 
 # 5. mkexe → .exe.  In BIG mode tell mkexe banks live at 0x4000 (W1).
@@ -360,8 +589,14 @@ fi
 MK_PREFIX=()
 [[ $VERBOSE -eq 1 ]] && MK_PREFIX+=(-v)
 [[ $BANK_W1 -eq 1 ]] && MK_PREFIX+=(-B 0x4000)
+[[ $W3_RESIDENT_HUGE -eq 1 ]] && MK_PREFIX+=(-W)
 MK_PREFIX+=("${MKEXE_EXTRA[@]}")
 MK_PREFIX+=(-L "$LOAD_ADDR" -E "$ENTRY_ADDR" -S "$STACK_ADDR" -o "$OUT")
 run "$MKEXE" "${MK_PREFIX[@]}" "$IHX"
 
+if [[ "${SPRINTER_SDBG_ACTIVE:-}" == 1 ]]; then
+    "$SPRINTER_PYTHON" "$PROJ_ROOT/toolchain/sdbg_driver.py" --metadata "$WORK" \
+        "$OUT" "$MEMORY_MODE" "$CODE_LOC" "$DATA_LOC" "$LOAD_ADDR" "$ENTRY_ADDR" "$STACK_ADDR"
+fi
+
 echo "sprinter-cc: wrote $OUT"

docs/Original/BIOS/bios_2.md

@@ -0,0 +1,893 @@
+# Функции BIOS v2.12
+
+### Вызов функций BIOS
+
+Вызов функций BIOS осуществляется из ассемблерного кода.
+
+Номер функции задается в регистре C процессора. В остальные регистры, 
+при необходимости, загружаются входные параметры функции. После исполнения 
+функции происходит возврат в программу, из которой произошел вызов функции. 
+Установленный флаг CF (CF=1) означает, что работа функции произошла с 
+ошибкой. В некоторых регистрах передаются выходные параметры.
+
+Ниже приведены таблицы входных и выходных параметров для каждой функции: 
+
+-	Функции работы с памятью
+-	Функции управления 'железом'
+-	Функции управления окнами и режимами экрана
+-	Функции вывода текста на экран
+-	Графические функции
+-	Функции работы с жесткими дисками и дисководами
+
+При работе функций BIOS необходимо что бы стек находился в области 
+8000h..0BFFFh, так как часть функций использует переключение страниц 
+PAGE1 и PAGE3.
+
+Вызов функций BIOS возможен в различных конфигурациях компьютера Sprinter.
+
+Конфигурация Spectrum: вызов функций BIOS осуществляется через 3D13h. 
+При этом работают и все функции TR-DOS.
+
+Конфигурации Sprinter: вызов функций BIOS осуществляется через RST 18h 
+при подключенном системном ПЗУ.
+
+Для постоянного подключения системного ПЗУ можно воспользоваться 
+такой последовательностью команд:
+
+```asm
+        LD A,0
+        OUT (07Ch),A
+```
+
+После ее исполнения в 0-м окне Z80 будет включено ПЗУ BIOSа и программа 
+может вызывать функции BIOSа через RST 18h.
+
+Отключение ПЗУ BIOSа из нулевого окна Z80 производится следующей 
+последовательностью команд: 
+
+```asm
+        LD A,0
+        OUT (03Ch),A
+```
+
+При необходимости, функции BIOSа могут быть вызваны программой, находящейся 
+в ОЗУ непосредственно в нулевом окне Z80. Для этого надо установить в 
+адресе 0008h следующий код: 
+
+```asm
+ADDRESS_0008h:
+        PUSH AF
+        LD A,0
+        OUT (7Ch),A
+        POP AF
+        RET
+```
+
+После этого BIOS можно вызывать командой RST 8. (Функции TR-DOS, так 
+же как и в случае RST 18 остаются недоступны.) Вызывая программы таким 
+образом, через RST 8, следует помнить что адреса 3FFFh..0000h после входа 
+в BIOS будут содержать код ПЗУ, поэтому, если фунция использует данные в 
+ОЗУ, они должны находиться в других адресах.
+
+Оптимизация программы для RST 8 недопустима, так как в ПЗУ, для 
+обратного переключения, стоит такая же программа, только порт 3Ch для 
+отключения ПЗУ BIOSа.
+
+Вызов функций BIOS в exe-файлах, вызываемых с помощью операционной 
+системы Estex, производится командой RST 8. Необходимая программа в адресе 
+0008h уже имеется в блоке кода ОС Estex.
+
+
+### Функции работы с памятью
+
+**0C0h (192) EMM_FN0 Определение объемов ОЗУ**
+
+    Значение регистров на входе:
+      C=0C0h 	
+    Значение регистров на выходе:
+      HL - общий объем ОЗУ в страницах по 16k
+      BC - объем свободного ОЗУ в страницах по 16k
+
+**0C1h (193) EMM_FN1 Инициализация распределения памяти**
+Стирается вся информация о выделенных ранее блоках ОЗУ.
+Блоки с системной информацией и первые 256K ОЗУ объявляются занятыми.
+
+    Значение регистров на входе:
+      C=0C1h 	
+    Значение регистров на выходе:  
+      нет 
+
+**0C2h (194) EMM_FN2 Выделение блока ОЗУ**
+
+    Значение регистров на входе:
+      C=0C2h
+      B - число запрашиваемых страниц	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение - A - идентификатор блока
+      CF=1 - ошибка - A=1 - не хватает памяти
+
+**0C3h (195) EMM_FN3 Освободить блок ОЗУ**
+
+    Значение регистров на входе:
+      C=0C3h 
+      A - идентификатор блока 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+      CF=1 - неправильный идентификатор
+             идентификатор не всегда отслеживается правильно
+
+**0C4h (196) EMM_FN4 Получить физический номер страницы из блока памяти**
+
+    Значение регистров на входе:
+      C=0C4h
+      A - идентификатор блока
+      B - логическая номер страницы в блоке	
+    Значение регистров на выходе:
+      CF=0 - A - логический номер страницы
+      CF=1 - ошибка:
+          A=0 - блок не существует
+          A=255 - запрашиваемый номер страницы слишком велик
+
+**0C5h (197) EMM_FN5 Получить список физических страниц блока**
+
+    Значение регистров на входе:
+      C=0C5h 
+      A - идентификатор блока 
+      HL - буфер 256 байт для размещения списка страниц 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение:
+          B - число страниц в блоке
+          HL - тот же адрес буфера, в буфере список физических 
+               страниц по порядку, заканчивающийся байтом 0FFh
+      CF=1 - неверный идентификатор блока; старая информация в буфере 
+             может быть затерта
+
+**0C6h (198) EMM_FN6 Получение адресов портов окон**
+
+Примечание по использованию функции получения адресов портов окон (0C6h):
+>Cледует хотя бы один раз вызвать эти функции и сравнить адреса 
+>портов с теми, что используются в программе и, если они не совпадают, 
+>выдать соответствующее предупреждение. В данный момент эти порты 
+>таковы: PAGE0=82h, PAGE1=0A2h, PAGE2=0C2h, PAGE3=0E2h 
+
+    Значение регистров на входе:
+      C=0C6h 
+      A - номер окна процессора - 0,1,2 или 3	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          C - 8-битный адрес порта окна
+          B - физический номер подключенной в окно страницы
+      CF=1 - ошибка - неверный номер окна
+
+**0C7h (199) EMM_FN7 Получить номер следующей страницы блока**
+
+Примечание по использованию функции EMM_FN7 (0C7h):
+> Информация о распределении памяти хранится в виде RAM Allocation Table, 
+> похожей на дисковый FAT. Поэтому нахождение физического номера 
+> следующей страницы по предыдущему физическому номеру происходит 
+> значительно быстрее, чем поиск по увеличенному на единицу логическому 
+> номеру. 
+
+    Значение регистров на входе:
+      C=0C7h
+      A - физическая страница	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          A - следуюшая физическая страница блока
+          A=0FFh - индицирует конец блока
+      CF=1 - ошибка - страница не принадлежит никакому блоку. 
+          фактически, это означает, что она свободна. 
+
+**09Eh (158) EMM_FN8 Слияние блоков**
+
+    Значение регистров на входе:
+      A - идентификатор блока 1
+      B - идентификатор блока 2	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          A - идентификатор объединенного блока
+      CF=1 - ошибка - неверный идентификатор блока
+
+**09Dh (157) EMM_FN9 Разделение блока**
+
+    Значение регистров на входе:
+      C=09Dh 
+      A - идентификатор блока 
+      B - новая длина блока 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          A - идентификатор блока результата 
+          B - идентификатор блока остатка 
+      CF=1 - ошибка - неверный идентификатор блока 
+
+### Функции управления 'железом' 
+
+**0EFh (239) FN_VERSION Выдача информации о версии BIOSа и железа.**
+
+    Значение регистров на входе:
+      C=0EFh 
+      HL - буфер, куда будет помещена ASCII строка с несколькими 
+          полями, номером версии BIOS и названием модели 
+          компьютера. Конец строки отмечен двойным нулем.	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          HL - тот же буфер с записанной строкой. 
+          DE - версия BIOSа 
+          BC - версия железа подробности ниже 
+          A - количество полей в буфере (в данный момент - 2) 
+              Первое поле - версия BIOS. 
+              Второе - название модели компьютера. 
+      CF=1 - ошибка - Очень старая версия, 
+          не имеющая данной функции 
+
+**0F2h (242) FN_SICF=0 Установка синхронизации, очистка страницы режима экрана**
+
+    Значение регистров на входе:
+      C=0F2h 
+      A - режим синхронизации 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный номер режима синхронизации 
+
+### Функции работы с CMOS данными и Turbo режимом
+
+Комментарий к функциям CMOS (0F5h-0F7h):
+> Функции CMOS_RD, CMOS_WR, CMOS_TEST работают всегда. Если в машине нет 
+> микросхемы CMOS, то эмулируется ее память. Наличие микросхемы 
+> определяется функцией CMOS_TEST.
+
+**0F5h (245) CMOS_TEST Проверить наличие CMOS**
+
+    Значение регистров на входе:
+      C=0F5h 	
+    Значение регистров на выходе:
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**0F6h (246) CMOS_RD Читать из регистра CMOS**
+
+    Значение регистров на входе:
+      C=0F6h 
+      D - номер регистра CMOS 	
+    Значение регистров на выходе:
+      A - считанные данные 
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**0F7h (247) CMOS_WR Писать в регистр CMOS**
+
+    Значение регистров на входе:
+      C=0F7h 
+      D - номер регистра CMOS 
+      A - записываемые данные 	
+    Значение регистров на выходе:
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**08Fh (143) FN_TURBO Функция управления турбо режимом.**
+
+    Комментарий к функции FN_TURBO (08Fh):
+      Переключение режима турбо может не произойти, если прошивка не 
+      поддерживает это переключение. При этом ошибки не происходит. Так 
+      же, переключение режима TURBO блокируется кнопкой "Turbo" в 
+      режиме Turbo-OFF
+    Значение регистров на входе:
+      C=08Fh 
+      A - режим турбо: 2 - off, 3 - on 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный режим турбо 
+
+### Функции управления окнами и режимами экрана 
+
+**0B0h (176) WIN_OPEN Функция открытия окна.**
+
+    Значение регистров на входе:
+      C=0B0h 
+      IX - описатель окна 
+      E - флаги окна: 
+          бит 0 указывает какую страницу режима включать после 
+            исполнения функции;
+          бит 4 указывает на какой странице режима открывать окно 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение: 
+          A - идентификатор окна 
+      CF=1 - ошибка слишком много окон 
+
+**0B1h (177) WIN_CLOSE закрытие окна**
+
+    Значение регистров на входе:
+      C=0B1h 
+      A - идентификатор окна 	
+    Значение регистров на выходе:
+      CF=0 - успешное завершение 
+      CF=1 - ошибка - неверный идентификатор 
+          Окно с номером 0 никогда не закрывается и попытка 
+          закрытия приводит к ошибке 
+
+**0B2h (178) WIN_COPY_WIN Копирование данных текстового окна в память (запоминание окна)**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B2h 
+      A - идентификатор глобального окна 
+      H - размер окна в символах по вертикали 
+      L - размер окна в символах по горизонтали 
+      D - вертикальное положение окна в глобальном окне 
+      E - горизонтальное положение окна в глобальном окне 
+      IX - адрес буфера для запоминания данных 
+          адрес буфера указывается для окна 0C000h если адрес 
+          указан с 8000h, номер страницы буфера не действителен 
+          ниже 8000h адрес указывать нельзя
+      A' - страница буфера для данных окна эта страница должна 
+          принадлежать программе 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B3h (179) WIN_RESTORE_WIN Копирование из памяти в текстовое окно (восстановление окна)**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B2h 
+      A - идентификатор глобального окна 
+      H - размер окна в символах по вертикали 
+      L - размер окна в символах по горизонтали 
+      D - вертикальное положение окна в глобальном окне 
+      E - горизонтальное положение окна в глобальном окне 
+      IX - адрес буфера для запоминания данных 
+          адрес буфера указывается для окна 0C000h если адрес 
+          указан с 8000h, номер страницы буфера не действителен 
+          ниже 8000h адрес указывать нельзя
+      A' - страница буфера для данных окна эта страница должна 
+          принадлежать программе 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B4h (180) WIN_GET_SYM Взять символ с экрана**
+
+    Значение регистров на входе:
+      C=0B4h 
+      A - идентификатор окна 
+      DE - положение символа в окне: 
+          D - вертикаль, E - горизонталь 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          L - символ, H - атрибут, 
+          B - знакогенератор 
+      CF=1 - ошибка неверный идентификатор окна 
+
+**0B5h (181) WIN_PUT_SYM Положить символ на экран**
+
+    Значение регистров на входе:
+      C=0B5h 
+      A - идентификатор окна 
+      DE - положение символа в окне: 
+          D - вертикаль, E - горизонталь 
+      L - символ, H - атрибут символа 
+      B - знакогенератор 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка неверный идентификатор окна 
+
+**0B6h (182) WIN_SET_ZG установка знакогенератора**
+
+    Значение регистров на входе:
+      C=0B6h 
+      A - системный номер знакогенератора 
+      DE - указатель на 2Kb блок данных знакогенератора 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка (старая версия, нет функции) 
+
+**0B7h (183) WIN_MOVE_WIN Перемещение окна**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B7h 
+      A - идентификатор глобального окна 
+      H - размер локального окна по вертикали в символах 
+      L - размер локального окна по горизонтали в символах 
+      D - положение локального окна по вертикали в символах 
+      E - положение локального окна по горизонтали в символах 
+      IX - новое положение локального окна (подобно DE) 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B8h (184) WIN_GET_ZG Получение знакогенератора**
+
+    Значение регистров на входе:
+      C=0B8h 
+      DE - адрес, куда будет загружено 2kb знакогенератора 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка (старая версия, нет функции) 
+
+### Функции вывода текста на экран
+
+**081h (129) LP_PRINT_ALL Печать символов с атрибутом**
+
+  На экран выводится строка из B одинаковых символов 
+
+    Значение регистров на входе:
+      C=081h 
+      A - символ 
+      E - атрибут 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**082h (131) LP_PRINT_SYM Вывод символов на экран без атрибута**
+
+  На экран выводится строка из B одинаковых символов атрибут 
+  остается тот, который был на экране 
+
+    Значение регистров на входе:
+      C=082h 
+      A - символ 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**083h (131) LP_PRINT_ATR печать атрибутов**
+
+  На экран выводится строка из B одинаковых атрибутов. 
+  Символы не меняются. 
+
+    Значение регистров на входе:
+      C=083h 
+      E - атрибут 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**084h (132) LP_SET_PLACE Установка текущего знакоместа в окне**
+
+  Позиция печати устанавливается в соответстии с регистром DE 
+
+    Значение регистров на входе:
+      C=084h 
+      E - положение символа по горизонтали 
+      D - номер символа по вертикали 
+          Превышение границ приводит не к ошибке, а к переустановке 
+          с начала, за вычетом полного размера окна 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**085h (133) LP_PRINT_LN Вывод строки символов на экран с текущего знакоместа**
+
+    Значение регистров на входе:
+      C=085h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - длина выводимой строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**086h (134) LP_PRINT_LN2 Вывод строки символов на экран без атрибутов**
+
+    Значение регистров на входе:
+      C=086h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - длина выводимой строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**087h (135) LP_PRINT_LN3 Вывод строки символов до разделителя**
+
+  После разделителя выводятся пробелы, что бы вывести B символов 
+
+    Значение регистров на входе:
+      C=087h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**088h (136) LP_PRINT_LN4 Вывод строки символов до разделителя, без атрибутов**
+
+  символы из выводятся на экран, пока не встретится символ равный D, 
+  далее печатаются пробелы, как дополнение строки до B символов. 
+  Атрибуты не изменяются. 
+
+    Значение регистров на входе:
+      C=088h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**089h (137) LP_CLS_WIN Очистка экрана**
+
+  Выполнение производится выводом пробелов с заданным атрибутом 
+
+    Значение регистров на входе:
+      C=089h 
+      DE - положение локального окна 
+      H - размер в символах локального окна по вертикали 
+      L - размер в символах локального окна по горизонтали 
+      B - атрибут очистки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Ah (138) LP_SCROLL_UD Скроллинг части глобального окна вверх/вниз**
+
+  Скроллируются полные строки глобального окна 
+
+    Значение регистров на входе:
+      C=08Ah 
+      B - тип скроллинга: 1 - вверх; 2 - вниз 
+      D - начальная строка скроллинга 
+      E - число скроллируемых строк 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Bh (139) LP_PRINT_LN5 Вывод строки символов на экран до разделителя**
+
+  После разделителя вывод останавливается 
+
+    Значение регистров на входе:
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - максимальная длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Ch (140) LP_PRINT_LN6 Вывод строки символов на экран до разделителя без атрибутов**
+
+  После разделителя вывод останавливается. 
+
+    Значение регистров на входе:
+      C=08Ch 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - максимальная длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Dh (141) LP_CLS_WIN2 Очистка экрана с указанием символа заполнения**
+
+    Значение регистров на входе:
+      C=08Dh 
+      DE - положение локального окна 
+      H - размер в символах локального окна по вертикали 
+      L - размер в символах локального окна по горизонтали 
+      B - атрибут очистки 
+      A - символ очистки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Eh (142) LP_GET_PLACE Получить текущее положение вывода на экран**
+
+    Значение регистров на входе:
+      C=08Eh 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+      DE - координаты, в которых будет напечатан 
+          следующий символ: 
+          D - вертикаль, E - горизонталь 
+
+### Графические функции
+
+**0A1h (161) PIC_POINT Установить точку**
+
+    Значение регистров на входе:
+      C=0A1h 
+      DE - координата по вертикали (пиксели) 
+      HL - координата по горизонтали (пиксели) 
+          Координаты считаются от верхнего левого угла экрана 
+      A - идентификатор окна 
+      B - цвет точки 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный идентификатор окна 
+
+**0A4h (164) PIC_SET_PAL Установка палитры**
+
+    Значение регистров на входе:
+      C=0A4h 
+      HL - данные палитры 
+      E - номер начального цвета 
+      D - количество устанавливаемых цветов 
+      B - маска при установке палитры. 
+          Для нормального режима должнa быть 0FFh 
+      A - номер палитры 0..15; от 8 до 15 - резервные 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**0A6h (166) SET_PAL_INIT Установка внутренней палитры**
+
+    Значение регистров на входе:
+      C=0A6h 
+      A - страница палитры 
+      B - номер палитры: 
+          B=2 - установка спектрумовской палитры 
+          B=1 - установка графической плаитры 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный номер палитры 
+
+### Функции работы с жесткими дисками и дисководами 
+
+**50h,52h,53h (80,82,83) Зарезервированы**
+
+    Значение регистров на входе и на выходе:
+      нет 
+
+**51h (81) DRV_RESET Сброс контроллера и настройка на диск**
+
+    Значение регистров на входе:
+      C=51h 
+      A - номер и тип устройства
+          бит 7..4 - тип устройства:
+            #0x - FDD
+            #6x - RAM-DISK
+            #8x - HDD
+            #Cx - CD-ROM
+          бит 3..0 - номер устройства	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка, нет диска или нет устройства 
+
+**54h (84) DRV_VERIFY Проверка секторов**
+
+  Проверка внутренняя на совпадение ECC 
+
+    Значение регистров на входе:
+      C=54h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора)
+      B - количество проверяемых секторов	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - проверка с ошибкой 
+
+**55h (85) DRV_READ Чтение с устройства**
+
+    Значение регистров на входе:
+      C=55h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора) 
+      B - количество секторов 
+      DE - адрес буфера для данных 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка чтения 
+      HL:IX - номер сектора + кол-во прочитанных секторов 
+      DE - адрес буфера для данных + (кол-во прочитанных секторов * размер сектора) 
+
+**56h (86) DRV_WRITE Запись на устройства**
+
+    Значение регистров на входе:
+      C=56h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора) 
+      B - количество секторов 
+      DE - адрес буфера данных для записи 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка записи 
+      HL:IX - номер сектора + кол-во прочитанных секторов 
+      DE - адрес буфера для данных + (кол-во прочитанных секторов * размер сектора) 
+
+**57h (87) DRV_DETECT Определение параметров устройства**
+
+    Значение регистров на входе:
+      C=57h 
+      A - номер и тип устройства (см. выше) 
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          A - bit7=0 диск 720Кb 
+              bit7=1 диск 1.44Mb 
+      CF=1 - нет устройства или нет носителя 
+
+**58h (88) DRV_GET_PAR Получить параметры носителя**
+
+    Значение регистров на входе:
+      C=58h 
+      A - номер и тип устройства (см. выше) 
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          L - число секторов 
+          H - число головок 
+          DE - количество цилиндров 
+              если HL=DE=0FFFFh - устройства нет 
+          IX - размер сектора в байтах 
+          B - доп. параметры для дискет: 
+              бит7 - тип 1.44Mb/720Kb
+      CF=1 - нет устройства 
+
+**59h (89) DRV_SET_PAR Установить параметры носителя**
+
+    Значение регистров на входе:
+      A - номер и тип устройства (см. выше) 
+      L - число секторов 
+      H - число головок 
+      DE - количество цилиндров 
+      IX - размер сектора в байтах 
+      B - доп. параметры для дискет 
+          бит7 - тип 1.44Mb/720Kb
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+
+**5Ah (90) EXT_VERSION Номер версии дисковой спецификации.**
+
+    Значение регистров на входе:
+      C=5Ah	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          D - версия
+          E - модификация
+      CF=1 - ошибка
+
+**5Fh (95) DRV_LIST Список дисковых устройств**
+
+    Значение регистров на входе:
+      C=5Fh
+      IX - буфер для списка устройств	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+
+В буфере список дисков в формате:
+
+    IX+0 - размер заполненого буфера
+    IX+1 - кол-во устройств FDD
+    IX+2 - кол-во устройств HDD
+    IX+3 - кол-во устройств CD DRIVE
+    IX+4 - #00 - конец списка, иначе кол-во устройств нового типа
+
+
+### Примечания и комментарии. 
+
+##### *Примечание по использованию функции получения адресов портов окон (0C6h).*
+Cледует хотя бы один раз вызвать эти функции и сравнить адреса портов с 
+теми, что используются в программе и, если они не совпадают, выдать 
+соответствующее предупреждение. В данный момент эти порты таковы: 
+PAGE0=82h, PAGE1=0A2h, PAGE2=0C2h, PAGE3=0E2h 
+
+##### *Примечание по использованию функции EMM_FN7 (0C7h).*
+Информация о распределении памяти хранится в виде RAM Allocation Table, 
+похожей на дисковый FAT. Поэтому нахождение физического номера следующей 
+страницы по предыдущему физическому номеру происходит значительно быстрее, 
+чем поиск по увеличенному на единицу логическому номеру. 
+
+##### *Комментарий к функции FN_VERSION (0EFh).*
+Значения регистра BC на выходе и соответствующая ему конфигурация
+    BC=FFFF - Не определено
+    BC=FFFE - Конфигурация Spectrum, режим Sprinter ZX
+    BC=FFFD - Конфигурация Sprinter
+    BC=FFFC - Зарезервировано
+    BC=FFFB - Зарезервировано
+    BC=FFFA - Зарезервировано
+    BC=FFF9 - Зарезервировано
+Иные значения BC - новые прошивки. 
+
+##### *Комментарий к функциям CMOS (0F5h-0F7h)*
+Функции CMOS_RD, CMOS_WR, CMOS_TEST работают всегда. Если в машине нет 
+микросхемы CMOS, то эмулируется ее память. Наличие микросхемы 
+определяется функцией CMOS_TEST.
+
+##### *Комментарий к функции FN_TURBO (08Fh)*
+Переключение режима турбо может не произойти, если прошивка не 
+поддерживает это переключение. При этом ошибки не происходит. Так же, 
+переключение режима TURBO блокируется кнопкой "Turbo" в режиме Turbo-OFF 
+
+##### *Комментарий к функциям печати текста.*
+Эти функции работают с текущим окном, которым всегда является последнее 
+открытое окно. К графическому экрану функции печати текста не применимы.
+
+##### *Описатель окна.*
+Для открытия окон используется 32-хбайтовый описатель окна (дескриптор), 
+адрес которого указывается в регистре IX. 
+
+    IX      - 32-хбайтовый описатель окна
+    (IX+0)  - горизонтальный размер окна в знакоместах
+    (IX+1)  - вертикальный размер в знакоместах
+    (IX+2)  - положение окна по горизонтали на экране в знакоместах
+    (IX+3)  - положение окна по вертикали на экране в знакоместах
+    (IX+4)  - режим знакоместа
+              bit4=1  - text_mode  bit4=0 - graf_mode
+              bit5=0  - 16, bit5=1 - 8 точек в знакоместе
+              graf_mode bit3..0 - не существенны
+                        bit7..6 - номер палитры
+              text_mode bit7..6,3..0 - номер знакогенератора
+                        исключение: bit7..6=B"11" - бордер
+    (IX+5)  - дополнительный режим знакоместа
+              bit0=1  - указывает на включение спектрумовской
+                        адресации экрана
+    (IX+6)  - положение по X в поле графики (по знакоместам)
+    (IX+7)  - положение по Y в поле графики (по знакоместам)
+              разъяснения о положении в поле графики - ниже
+    (IX+8..31) - зарезервировано (переменные окна)
+      в этих байтах должны быть нули
+
+При открытии окна описатель копируется в системную страницу ОЗУ и 
+программа может не сохранять его. Что бы описатель окна не потерялся, 
+программа получает идентификатор окна. Он же идентификатор глобального 
+окна. В функциях запоминания, восстановления, перемещения, а так же 
+функциях стирания, скроллинга и т.п. идентификатор окна определяет 
+область экрана, относительно которой производится работа с локальными 
+окнами. Подразумеваются локальные окна в смысле "окно в окне". 
+Идентификатор окна определяет глобальное окно, отнoсительно которого 
+адресуются локальные. В части функций глобальное окно определяется по 
+умолчанию, как последнее, с которым производились действия с явным 
+указанием идентификатора.
+
+В данный момент BIOS хранит только один описатель окна - последний, 
+с которым была произведена функция открытия. Идентификатор окна 
+выставляется в 0. В дальнейшем планитруется разработка функций со 
+множеством окон, потому, во избежание неприятностей в будущем, при 
+работе с окнами, программисту следует запоминать идентификатор окна 
+и пользоваться этим значением при работе с ним. 
+
+    Типы стандартных окон: 
+      0 - окно 32x24 в формате ZX Spectrum
+      1 - текстовое окно 64x24
+      2 - текстовое окно 40x32
+      3 - текстовое окно 80x32
+      4 - окно в формате ZX Spectrum, HL - положение окна на экране в знакоместах
+      5 - текстовое окно 64x24, HL - положение окна на экране в знакоместах
+      6 - текстовое окно 40x32, HL - положение окна на экране в знакоместах
+      7 - текстовое окно 80x32, HL - положение окна на экране в знакоместах
+      8 - графическое окно 0, HL - положение окна на экране
+      9 - графическое окно 1, HL - положение окна на экране
+
+Данные палитры должны представлять собой список приблизительно такого вида: 
+
+        DB blue1,green1,red1,0
+        DB blue2,green2,red2,0
+        .....................
+        DB blueN,greenN,redN,0
+
+N - количество цветов. Значеное равное 0 соответствует 256-ти цветам. 
+При записи в видео-ОЗУ все данные предварительно проходят функцию AND 
+со значением регистра маски - B.
+
+Страницы палитры 0..3 соответствуют графическим режимам. Для вывода в 
+соответствующей палитре нужно задать соответствующее значение bit7..6 в 
+байте режима знакоместа
+
+Страницы 4..7 соответствуют текстовому режиму и спектрумовскому режиму. 
+В странице 4 задается цвет PAPER для каждого атрибута. В странице 5 
+задается цвет INK для каждого атрибута. В странице 6 задается цвет PAPER, 
+которым он будет моргать в режиме FLASH В странице 7 задается цвет INK, 
+которым он будет моргать в режиме FLASH. Таким образом, для каждого из 
+256-ти атрибутов задается четыре цвета если цвета 4,5 совпадают с 
+цветами 6,7 то режим FLASH оказывается отключенным. Для его включения 
+в спектрумовском режиме надо поменять местами цвета 6 и 7. Если надо 
+включить FLASH в режим IBM-CGA, следует установить цвета 6 и 7 
+одинаковыми и равными цвету 4. По сути режим FLASH всегда включен, и 
+на экране постоянно меняются цвета PAPER с 4-го на 6-й, а цвета INK с 
+5 на 7-й. Если эти пары цветов для атрибута знакоместа устанавливаются 
+одинаковыми, то FLASH в этом месте не виден.
+
+##### *Комментарий к функциям работы с устройствами хранения информации.*
+
+В этих функциях в регистре A обычно задается номер и тип устройства: 
+    бит 0..3 - номер устройства
+    бит 4..7 - тип устройства:
+            0 - дисковод
+            6 - ram-disk
+            8 - HDD
+            C - CD-ROM
+
+остальные номера не используются
+
+А так же задаются: старшая часть номера сектора в регисте HL, 
+младшая часть номера сектора в регистре IX.
+

docs/Original/BIOS/Функции BIOS v3.md

@@ -0,0 +1,901 @@
+# Функции BIOS v3.00
+
+### Вызов функций BIOS
+
+**Вызов функций BIOS осуществляется из ассемблерного кода.**
+
+Номер функции задается в регистре C процессора. В остальные
+регистры, при необходимости, загружаются входные параметры функции.
+После исполнения функции происходит возврат в программу, из которой
+произошел вызов функции. Установленный флаг CF (CF=1) означает, что
+работа функции произошла с ошибкой. В некоторых регистрах передаются
+выходные параметры.
+
+Ниже приведены таблицы входных и выходных параметров для каждой функции:
+
+- Функции работы с памятью
+- Функции управления 'железом'
+- Функции управления окнами и режимами экрана
+- Функции вывода текста на экран
+- Графические функции
+- Функции работы с жесткими дисками и дисководами
+
+При работе функций BIOS необходимо что бы стек находился в области
+8000h..0BFFFh, так как часть функций использует переключение страниц
+PAGE1 и PAGE3.
+
+Вызов функций BIOS возможен в различных конфигурациях компьютера
+Sprinter.
+
+**Конфигурация Spectrum:** вызов функций BIOS осуществляется через
+3D13h. При этом работают и все функции TR-DOS.
+
+**Конфигурации Sprinter:** вызов функций BIOS осуществляется через RST
+18h при подключенном системном ПЗУ.
+
+Для постоянного подключения системного ПЗУ можно воспользоваться такой
+последовательностью команд:
+
+```asm
+        LD A,0
+        OUT (07Ch),A
+```
+
+После ее исполнения в 0-м окне Z80 будет включено ПЗУ BIOSа и программа
+может вызывать функции BIOSа через RST 18h.
+
+Отключение ПЗУ BIOSа из нулевого окна Z80 производится следующей
+последовательностью команд:
+
+```asm
+        LD A,0
+        OUT (03Ch),A
+```        
+
+При необходимости, функции BIOSа могут быть вызваны программой,
+находящейся в ОЗУ непосредственно в нулевом окне Z80. Для этого надо
+установить в адресе 0008h следующий код:
+
+```asm
+ADDRESS_0008h:
+        PUSH AF
+        LD A,0
+        OUT (7Ch),A
+        POP AF
+        RET
+```
+
+После этого BIOS можно вызывать командой RST 8. (Функции TR-DOS, так
+же как и в случае RST 18 остаются недоступны.) Вызывая программы таким
+образом, через RST 8, следует помнить что адреса 3FFFh..0000h после
+входа в BIOS будут содержать код ПЗУ, поэтому, если фунция использует
+данные в ОЗУ, они должны находиться в других адресах.
+
+Оптимизация программы для RST 8 недопустима, так как в ПЗУ, для
+обратного переключения, стоит такая же программа, только порт 3Ch для
+отключения ПЗУ BIOSа.
+
+Вызов функций BIOS в exe-файлах, вызываемых с помощью операционной
+системы Estex, производится командой RST 8. Необходимая программа в
+адресе 0008h уже имеется в блоке кода ОС Estex.
+
+### Функции работы с памятью
+
+
+**0C0h (192) EMM_FN0 Определение объемов ОЗУ**
+
+    Значение регистров на входе:
+      C=0C0h 	
+    Значение регистров на выходе:
+      HL - общий объем ОЗУ в страницах по 16k
+      BC - объем свободного ОЗУ в страницах по 16k
+
+**0C1h (193) EMM_FN1 Инициализация распределения памяти**
+Стирается вся информация о выделенных ранее блоках ОЗУ.
+Блоки с системной информацией и первые 256K ОЗУ объявляются занятыми.
+
+    Значение регистров на входе:
+      C=0C1h 	
+    Значение регистров на выходе:  
+      нет 
+
+**0C2h (194) EMM_FN2 Выделение блока ОЗУ**
+
+    Значение регистров на входе:
+      C=0C2h
+      B - число запрашиваемых страниц	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение - A - идентификатор блока
+      CF=1 - ошибка - A=1 - не хватает памяти
+
+**0C3h (195) EMM_FN3 Освободить блок ОЗУ**
+
+    Значение регистров на входе:
+      C=0C3h 
+      A - идентификатор блока 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+      CF=1 - неправильный идентификатор
+             идентификатор не всегда отслеживается правильно
+
+
+**0C4h (196) EMM_FN4 Получить физический номер страницы из блока памяти**
+
+    Значение регистров на входе:
+      C=0C4h
+      A - идентификатор блока
+      B - логическая номер страницы в блоке	
+    Значение регистров на выходе:
+      CF=0 - A - логический номер страницы
+      CF=1 - ошибка:
+          A=0 - блок не существует
+          A=255 - запрашиваемый номер страницы слишком велик
+
+**0C5h (197) EMM_FN5 Получить список физических страниц блока**
+
+    Значение регистров на входе:
+      C=0C5h 
+      A - идентификатор блока 
+      HL - буфер 256 байт для размещения списка страниц 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение:
+          B - число страниц в блоке
+          HL - тот же адрес буфера, в буфере список физических 
+               страниц по порядку, заканчивающийся байтом 0FFh
+      CF=1 - неверный идентификатор блока; старая информация в буфере 
+             может быть затерта
+
+**0C6h (198) EMM_FN6 Получение адресов портов окон**
+
+Примечание по использованию функции получения адресов портов окон (0C6h):
+>Cледует хотя бы один раз вызвать эти функции и сравнить адреса 
+>портов с теми, что используются в программе и, если они не совпадают, 
+>выдать соответствующее предупреждение. В данный момент эти порты 
+>таковы: PAGE0=82h, PAGE1=0A2h, PAGE2=0C2h, PAGE3=0E2h 
+
+    Значение регистров на входе:
+      C=0C6h 
+      A - номер окна процессора - 0,1,2 или 3	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          C - 8-битный адрес порта окна
+          B - физический номер подключенной в окно страницы
+      CF=1 - ошибка - неверный номер окна
+
+**0C7h (199) EMM_FN7 Получить номер следующей страницы блока**
+
+Примечание по использованию функции EMM_FN7 (0C7h):
+> Информация о распределении памяти хранится в виде RAM Allocation Table, 
+> похожей на дисковый FAT. Поэтому нахождение физического номера 
+> следующей страницы по предыдущему физическому номеру происходит 
+> значительно быстрее, чем поиск по увеличенному на единицу логическому 
+> номеру. 
+
+    Значение регистров на входе:
+      C=0C7h
+      A - физическая страница	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          A - следуюшая физическая страница блока
+          A=0FFh - индицирует конец блока
+      CF=1 - ошибка - страница не принадлежит никакому блоку. 
+          фактически, это означает, что она свободна. 
+
+**09Eh (158) EMM_FN8 Слияние блоков**
+
+    Значение регистров на входе:
+      A - идентификатор блока 1
+      B - идентификатор блока 2	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение
+          A - идентификатор объединенного блока
+      CF=1 - ошибка - неверный идентификатор блока
+
+**09Dh (157) EMM_FN9 Разделение блока**
+
+    Значение регистров на входе:
+      C=09Dh 
+      A - идентификатор блока 
+      B - новая длина блока 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          A - идентификатор блока результата 
+          B - идентификатор блока остатка 
+      CF=1 - ошибка - неверный идентификатор блока 
+
+### Функции управления 'железом' 
+
+**0EFh (239) FN_VERSION Выдача информации о версии BIOSа и железа.**
+
+    Значение регистров на входе:
+      C=0EFh 
+      HL - буфер, куда будет помещена ASCII строка с несколькими 
+          полями, номером версии BIOS и названием модели 
+          компьютера. Конец строки отмечен двойным нулем.	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          HL - тот же буфер с записанной строкой. 
+          DE - версия BIOSа 
+          BC - версия железа подробности ниже 
+          A - количество полей в буфере (в данный момент - 2) 
+              Первое поле - версия BIOS. 
+              Второе - название модели компьютера. 
+      CF=1 - ошибка - Очень старая версия, 
+          не имеющая данной функции 
+
+**0F2h (242) FN_SICF=0 Установка синхронизации, очистка страницы режима экрана**
+
+    Значение регистров на входе:
+      C=0F2h 
+      A - режим синхронизации 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный номер режима синхронизации 
+
+### Функции работы с CMOS данными и Turbo режимом
+
+Комментарий к функциям CMOS (0F5h-0F7h):
+> Функции CMOS_RD, CMOS_WR, CMOS_TEST работают всегда. Если в машине нет 
+> микросхемы CMOS, то эмулируется ее память. Наличие микросхемы 
+> определяется функцией CMOS_TEST.
+
+**0F5h (245) CMOS_TEST Проверить наличие CMOS**
+
+    Значение регистров на входе:
+      C=0F5h 	
+    Значение регистров на выходе:
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**0F6h (246) CMOS_RD Читать из регистра CMOS**
+
+    Значение регистров на входе:
+      C=0F6h 
+      D - номер регистра CMOS 	
+    Значение регистров на выходе:
+      A - считанные данные 
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**0F7h (247) CMOS_WR Писать в регистр CMOS**
+
+    Значение регистров на входе:
+      C=0F7h 
+      D - номер регистра CMOS 
+      A - записываемые данные 	
+    Значение регистров на выходе:
+      CF=0 - часы есть 
+      CF=1 - часов нет 
+
+**08Fh (143) FN_TURBO Функция управления турбо режимом.**
+
+    Комментарий к функции FN_TURBO (08Fh):
+      Переключение режима турбо может не произойти, если прошивка не 
+      поддерживает это переключение. При этом ошибки не происходит. Так 
+      же, переключение режима TURBO блокируется кнопкой "Turbo" в 
+      режиме Turbo-OFF
+    Значение регистров на входе:
+      C=08Fh 
+      A - режим турбо: 2 - off, 3 - on 	
+      A - режим FDD: 12h - 720Kb, 13h - 1.44Mb
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный режим турбо 
+
+### Функции управления окнами и режимами экрана 
+
+**0B0h (176) WIN_OPEN Функция открытия окна.**
+
+    Значение регистров на входе:
+      C=0B0h 
+      IX - описатель окна 
+      E - флаги окна: 
+          бит 0 указывает какую страницу режима включать после 
+            исполнения функции;
+          бит 4 указывает на какой странице режима открывать окно 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение: 
+          A - идентификатор окна 
+      CF=1 - ошибка слишком много окон 
+
+**0B1h (177) WIN_CLOSE закрытие окна**
+
+    Значение регистров на входе:
+      C=0B1h 
+      A - идентификатор окна 	
+    Значение регистров на выходе:
+      CF=0 - успешное завершение 
+      CF=1 - ошибка - неверный идентификатор 
+          Окно с номером 0 никогда не закрывается и попытка 
+          закрытия приводит к ошибке 
+
+**0B2h (178) WIN_COPY_WIN Копирование данных текстового окна в память (запоминание окна)**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B2h 
+      A - идентификатор глобального окна 
+      H - размер окна в символах по вертикали 
+      L - размер окна в символах по горизонтали 
+      D - вертикальное положение окна в глобальном окне 
+      E - горизонтальное положение окна в глобальном окне 
+      IX - адрес буфера для запоминания данных 
+          адрес буфера указывается для окна 0C000h если адрес 
+          указан с 8000h, номер страницы буфера не действителен 
+          ниже 8000h адрес указывать нельзя
+      A' - страница буфера для данных окна эта страница должна 
+          принадлежать программе 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B3h (179) WIN_RESTORE_WIN Копирование из памяти в текстовое окно (восстановление окна)**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B2h 
+      A - идентификатор глобального окна 
+      H - размер окна в символах по вертикали 
+      L - размер окна в символах по горизонтали 
+      D - вертикальное положение окна в глобальном окне 
+      E - горизонтальное положение окна в глобальном окне 
+      IX - адрес буфера для запоминания данных 
+          адрес буфера указывается для окна 0C000h если адрес 
+          указан с 8000h, номер страницы буфера не действителен 
+          ниже 8000h адрес указывать нельзя
+      A' - страница буфера для данных окна эта страница должна 
+          принадлежать программе 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B4h (180) WIN_GET_SYM Взять символ с экрана**
+
+    Значение регистров на входе:
+      C=0B4h 
+      A - идентификатор окна 
+      DE - положение символа в окне: 
+          D - вертикаль, E - горизонталь 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          L - символ, H - атрибут, 
+          B - знакогенератор 
+      CF=1 - ошибка неверный идентификатор окна 
+
+**0B5h (181) WIN_PUT_SYM Положить символ на экран**
+
+    Значение регистров на входе:
+      C=0B5h 
+      A - идентификатор окна 
+      DE - положение символа в окне: 
+          D - вертикаль, E - горизонталь 
+      L - символ, H - атрибут символа 
+      B - знакогенератор 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка неверный идентификатор окна 
+
+**0B6h (182) WIN_SET_ZG установка знакогенератора**
+
+    Значение регистров на входе:
+      C=0B6h 
+      A - системный номер знакогенератора 
+      DE - указатель на 2Kb блок данных знакогенератора 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка (старая версия, нет функции) 
+
+**0B7h (183) WIN_MOVE_WIN Перемещение окна**
+
+  При работе этой функции через RST 18h или RST 8, обязателен запрет 
+  прерываний, так как функция пользуется стеком для ускорения своей работы. 
+
+    Значение регистров на входе:
+      C=0B7h 
+      A - идентификатор глобального окна 
+      H - размер локального окна по вертикали в символах 
+      L - размер локального окна по горизонтали в символах 
+      D - положение локального окна по вертикали в символах 
+      E - положение локального окна по горизонтали в символах 
+      IX - новое положение локального окна (подобно DE) 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка - неверный идентификатор окна 
+
+**0B8h (184) WIN_GET_ZG Получение знакогенератора**
+
+    Значение регистров на входе:
+      C=0B8h 
+      DE - адрес, куда будет загружено 2kb знакогенератора 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка (старая версия, нет функции) 
+
+### Функции вывода текста на экран
+
+**081h (129) LP_PRINT_ALL Печать символов с атрибутом**
+
+  На экран выводится строка из B одинаковых символов 
+
+    Значение регистров на входе:
+      C=081h 
+      A - символ 
+      E - атрибут 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**082h (131) LP_PRINT_SYM Вывод символов на экран без атрибута**
+
+  На экран выводится строка из B одинаковых символов атрибут 
+  остается тот, который был на экране 
+
+    Значение регистров на входе:
+      C=082h 
+      A - символ 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**083h (131) LP_PRINT_ATR печать атрибутов**
+
+  На экран выводится строка из B одинаковых атрибутов. 
+  Символы не меняются. 
+
+    Значение регистров на входе:
+      C=083h 
+      E - атрибут 
+      B - число выводимых символов 
+          регистры HL,IX - сохраняются 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**084h (132) LP_SET_PLACE Установка текущего знакоместа в окне**
+
+  Позиция печати устанавливается в соответстии с регистром DE 
+
+    Значение регистров на входе:
+      C=084h 
+      E - положение символа по горизонтали 
+      D - номер символа по вертикали 
+          Превышение границ приводит не к ошибке, а к переустановке 
+          с начала, за вычетом полного размера окна 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**085h (133) LP_PRINT_LN Вывод строки символов на экран с текущего знакоместа**
+
+    Значение регистров на входе:
+      C=085h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - длина выводимой строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**086h (134) LP_PRINT_LN2 Вывод строки символов на экран без атрибутов**
+
+    Значение регистров на входе:
+      C=086h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - длина выводимой строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**087h (135) LP_PRINT_LN3 Вывод строки символов до разделителя**
+
+  После разделителя выводятся пробелы, что бы вывести B символов 
+
+    Значение регистров на входе:
+      C=087h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**088h (136) LP_PRINT_LN4 Вывод строки символов до разделителя, без атрибутов**
+
+  символы из выводятся на экран, пока не встретится символ равный D, 
+  далее печатаются пробелы, как дополнение строки до B символов. 
+  Атрибуты не изменяются. 
+
+    Значение регистров на входе:
+      C=088h 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**089h (137) LP_CLS_WIN Очистка экрана**
+
+  Выполнение производится выводом пробелов с заданным атрибутом 
+
+    Значение регистров на входе:
+      C=089h 
+      DE - положение локального окна 
+      H - размер в символах локального окна по вертикали 
+      L - размер в символах локального окна по горизонтали 
+      B - атрибут очистки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Ah (138) LP_SCROLL_UD Скроллинг части глобального окна вверх/вниз**
+
+  Скроллируются полные строки глобального окна 
+
+    Значение регистров на входе:
+      C=08Ah 
+      B - тип скроллинга: 1 - вверх; 2 - вниз 
+      D - начальная строка скроллинга 
+      E - число скроллируемых строк 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Bh (139) LP_PRINT_LN5 Вывод строки символов на экран до разделителя**
+
+  После разделителя вывод останавливается 
+
+    Значение регистров на входе:
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      E - атрибут, с которым будет выведена строка 
+      B - максимальная длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Ch (140) LP_PRINT_LN6 Вывод строки символов на экран до разделителя без атрибутов**
+
+  После разделителя вывод останавливается. 
+
+    Значение регистров на входе:
+      C=08Ch 
+      HL - адрес строки должен быть между 04000h и 0BFFFh 
+      B - максимальная длина выводимой строки 
+      D - символ-разделитель, указывающий конец строки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Dh (141) LP_CLS_WIN2 Очистка экрана с указанием символа заполнения**
+
+    Значение регистров на входе:
+      C=08Dh 
+      DE - положение локального окна 
+      H - размер в символах локального окна по вертикали 
+      L - размер в символах локального окна по горизонтали 
+      B - атрибут очистки 
+      A - символ очистки 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**08Eh (142) LP_GET_PLACE Получить текущее положение вывода на экран**
+
+    Значение регистров на входе:
+      C=08Eh 	
+    Значение регистров на выходе:
+      CF=0 - всегда 
+      DE - координаты, в которых будет напечатан 
+          следующий символ: 
+          D - вертикаль, E - горизонталь 
+
+### Графические функции
+
+**0A1h (161) PIC_POINT Установить точку**
+
+    Значение регистров на входе:
+      C=0A1h 
+      DE - координата по вертикали (пиксели) 
+      HL - координата по горизонтали (пиксели) 
+          Координаты считаются от верхнего левого угла экрана 
+      A - идентификатор окна 
+      B - цвет точки 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный идентификатор окна 
+
+**0A4h (164) PIC_SET_PAL Установка палитры**
+
+    Значение регистров на входе:
+      C=0A4h 
+      HL - данные палитры 
+      E - номер начального цвета 
+      D - количество устанавливаемых цветов 
+      B - маска при установке палитры. 
+          Для нормального режима должнa быть 0FFh 
+      A - 
+        0..3 биты - значения 0..7 - номер палитры
+                  - значения 8..15 - зарезервированы
+        4..6 биты - зарезервированы (установить в 0)
+        7 бит -
+            - значение 0 - установить
+            - значение 1 - загрузить палитру в память
+    Значение регистров на выходе:
+      CF=0 - всегда 
+
+**0A6h (166) SET_PAL_INIT Установка внутренней палитры**
+
+    Значение регистров на входе:
+      C=0A6h 
+      A - страница палитры 
+      B - номер палитры: 
+          B=3 - установка текстовой палитры CGA
+          B=2 - установка спектрумовской палитры 
+          B=1 - установка графической плаитры 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - неверный номер палитры 
+
+### Функции работы с жесткими дисками и дисководами 
+
+**50h,52h,53h (80,82,83) Зарезервированы**
+
+    Значение регистров на входе и на выходе:
+      нет 
+
+**51h (81) DRV_RESET Сброс контроллера и настройка на диск**
+
+    Значение регистров на входе:
+      C=51h 
+      A - номер и тип устройства
+          бит 7..4 - тип устройства:
+            #0x - FDD
+            #6x - RAM-DISK
+            #8x - HDD
+            #Cx - CD-ROM
+          бит 3..0 - номер устройства	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка, нет диска или нет устройства 
+
+**54h (84) DRV_VERIFY Проверка секторов**
+
+  Проверка внутренняя на совпадение ECC 
+
+    Значение регистров на входе:
+      C=54h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора)
+      B - количество проверяемых секторов	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - проверка с ошибкой 
+
+**55h (85) DRV_READ Чтение с устройства**
+
+    Значение регистров на входе:
+      C=55h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора) 
+      B - количество секторов 
+      DE - адрес буфера для данных 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка чтения 
+      HL:IX - номер сектора + кол-во прочитанных секторов 
+      DE - адрес буфера для данных + (кол-во прочитанных секторов * размер сектора) 
+
+**56h (86) DRV_WRITE Запись на устройства**
+
+    Значение регистров на входе:
+      C=56h 
+      A - номер и тип устройства (см. выше) 
+      HL:IX - номер сектора (IX - младшая часть номера сектора) 
+      B - количество секторов 
+      DE - адрес буфера данных для записи 	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+      CF=1 - ошибка записи 
+      HL:IX - номер сектора + кол-во прочитанных секторов 
+      DE - адрес буфера для данных + (кол-во прочитанных секторов * размер сектора) 
+
+**57h (87) DRV_DETECT Определение параметров устройства**
+
+    Значение регистров на входе:
+      C=57h 
+      A - номер и тип устройства (см. выше) 
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          A - bit7=0 диск 720Кb 
+              bit7=1 диск 1.44Mb 
+      CF=1 - нет устройства или нет носителя 
+
+**58h (88) DRV_GET_PAR Получить параметры носителя**
+
+    Значение регистров на входе:
+      C=58h 
+      A - номер и тип устройства (см. выше) 
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          L - число секторов 
+          H - число головок 
+          DE - количество цилиндров 
+              если HL=DE=0FFFFh - устройства нет 
+          IX - размер сектора в байтах 
+          B - доп. параметры для дискет: 
+              бит7 - тип 1.44Mb/720Kb
+      CF=1 - нет устройства 
+
+**59h (89) DRV_SET_PAR Установить параметры носителя**
+
+    Значение регистров на входе:
+      A - номер и тип устройства (см. выше) 
+      L - число секторов 
+      H - число головок 
+      DE - количество цилиндров 
+      IX - размер сектора в байтах 
+      B - доп. параметры для дискет 
+          бит7 - тип 1.44Mb/720Kb
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+
+**5Ah (90) EXT_VERSION Номер версии дисковой спецификации.**
+
+    Значение регистров на входе:
+      C=5Ah	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+          D - версия
+          E - модификация
+      CF=1 - ошибка
+
+**5Fh (95) DRV_LIST Список дисковых устройств**
+
+    Значение регистров на входе:
+      C=5Fh
+      IX - буфер для списка устройств	
+    Значение регистров на выходе:
+      CF=0 - нормальное завершение 
+
+В буфере список дисков в формате:
+
+    IX+0 - размер заполненого буфера
+    IX+1 - кол-во устройств FDD
+    IX+2 - кол-во устройств HDD
+    IX+3 - кол-во устройств CD DRIVE
+    IX+4 - #00 - конец списка, иначе кол-во устройств нового типа
+
+
+### Примечания и комментарии. 
+
+##### *Примечание по использованию функции получения адресов портов окон (0C6h).*
+Cледует хотя бы один раз вызвать эти функции и сравнить адреса портов с 
+теми, что используются в программе и, если они не совпадают, выдать 
+соответствующее предупреждение. В данный момент эти порты таковы: 
+PAGE0=82h, PAGE1=0A2h, PAGE2=0C2h, PAGE3=0E2h 
+
+##### *Примечание по использованию функции EMM_FN7 (0C7h).*
+Информация о распределении памяти хранится в виде RAM Allocation Table, 
+похожей на дисковый FAT. Поэтому нахождение физического номера следующей 
+страницы по предыдущему физическому номеру происходит значительно быстрее, 
+чем поиск по увеличенному на единицу логическому номеру. 
+
+##### *Комментарий к функции FN_VERSION (0EFh).*
+Значения регистра BC на выходе и соответствующая ему конфигурация
+    BC=FFFF - Не определено
+    BC=FFFE - Конфигурация Spectrum, режим Sprinter ZX
+    BC=FFFD - Конфигурация Sprinter
+    BC=FFFC - Зарезервировано
+    BC=FFFB - Зарезервировано
+    BC=FFFA - Зарезервировано
+    BC=FFF9 - Зарезервировано
+Иные значения BC - новые прошивки. 
+
+##### *Комментарий к функциям CMOS (0F5h-0F7h)*
+Функции CMOS_RD, CMOS_WR, CMOS_TEST работают всегда. Если в машине нет 
+микросхемы CMOS, то эмулируется ее память. Наличие микросхемы 
+определяется функцией CMOS_TEST.
+
+##### *Комментарий к функции FN_TURBO (08Fh)*
+Переключение режима турбо может не произойти, если прошивка не 
+поддерживает это переключение. При этом ошибки не происходит. Так же, 
+переключение режима TURBO блокируется кнопкой "Turbo" в режиме Turbo-OFF 
+
+##### *Комментарий к функциям печати текста.*
+Эти функции работают с текущим окном, которым всегда является последнее 
+открытое окно. К графическому экрану функции печати текста не применимы.
+
+##### *Описатель окна.*
+Для открытия окон используется 32-хбайтовый описатель окна (дескриптор), 
+адрес которого указывается в регистре IX. 
+
+    IX      - 32-хбайтовый описатель окна
+    (IX+0)  - горизонтальный размер окна в знакоместах
+    (IX+1)  - вертикальный размер в знакоместах
+    (IX+2)  - положение окна по горизонтали на экране в знакоместах
+    (IX+3)  - положение окна по вертикали на экране в знакоместах
+    (IX+4)  - режим знакоместа
+              bit4=1  - text_mode  bit4=0 - graf_mode
+              bit5=0  - 16, bit5=1 - 8 точек в знакоместе
+              graf_mode bit3..0 - не существенны
+                        bit7..6 - номер палитры
+              text_mode bit7..6,3..0 - номер знакогенератора
+                        исключение: bit7..6=B"11" - бордер
+    (IX+5)  - дополнительный режим знакоместа
+              bit0=1  - указывает на включение спектрумовской
+                        адресации экрана
+    (IX+6)  - положение по X в поле графики (по знакоместам)
+    (IX+7)  - положение по Y в поле графики (по знакоместам)
+              разъяснения о положении в поле графики - ниже
+    (IX+8..31) - зарезервировано (переменные окна)
+      в этих байтах должны быть нули
+
+При открытии окна описатель копируется в системную страницу ОЗУ и 
+программа может не сохранять его. Что бы описатель окна не потерялся, 
+программа получает идентификатор окна. Он же идентификатор глобального 
+окна. В функциях запоминания, восстановления, перемещения, а так же 
+функциях стирания, скроллинга и т.п. идентификатор окна определяет 
+область экрана, относительно которой производится работа с локальными 
+окнами. Подразумеваются локальные окна в смысле "окно в окне". 
+Идентификатор окна определяет глобальное окно, отнoсительно которого 
+адресуются локальные. В части функций глобальное окно определяется по 
+умолчанию, как последнее, с которым производились действия с явным 
+указанием идентификатора.
+
+В данный момент BIOS хранит только один описатель окна - последний, 
+с которым была произведена функция открытия. Идентификатор окна 
+выставляется в 0. В дальнейшем планитруется разработка функций со 
+множеством окон, потому, во избежание неприятностей в будущем, при 
+работе с окнами, программисту следует запоминать идентификатор окна 
+и пользоваться этим значением при работе с ним. 
+
+    Типы стандартных окон: 
+      0 - окно 32x24 в формате ZX Spectrum
+      1 - текстовое окно 64x24
+      2 - текстовое окно 40x32
+      3 - текстовое окно 80x32
+      4 - окно в формате ZX Spectrum, HL - положение окна на экране в знакоместах
+      5 - текстовое окно 64x24, HL - положение окна на экране в знакоместах
+      6 - текстовое окно 40x32, HL - положение окна на экране в знакоместах
+      7 - текстовое окно 80x32, HL - положение окна на экране в знакоместах
+      8 - графическое окно 0, HL - положение окна на экране
+      9 - графическое окно 1, HL - положение окна на экране
+
+Данные палитры должны представлять собой список приблизительно такого вида: 
+
+        DB blue1,green1,red1,0
+        DB blue2,green2,red2,0
+        .....................
+        DB blueN,greenN,redN,0
+
+N - количество цветов. Значеное равное 0 соответствует 256-ти цветам. 
+При записи в видео-ОЗУ все данные предварительно проходят функцию AND 
+со значением регистра маски - B.
+
+Страницы палитры 0..3 соответствуют графическим режимам. Для вывода в 
+соответствующей палитре нужно задать соответствующее значение bit7..6 в 
+байте режима знакоместа
+
+Страницы 4..7 соответствуют текстовому режиму и спектрумовскому режиму. 
+В странице 4 задается цвет PAPER для каждого атрибута. В странице 5 
+задается цвет INK для каждого атрибута. В странице 6 задается цвет PAPER, 
+которым он будет моргать в режиме FLASH В странице 7 задается цвет INK, 
+которым он будет моргать в режиме FLASH. Таким образом, для каждого из 
+256-ти атрибутов задается четыре цвета если цвета 4,5 совпадают с 
+цветами 6,7 то режим FLASH оказывается отключенным. Для его включения 
+в спектрумовском режиме надо поменять местами цвета 6 и 7. Если надо 
+включить FLASH в режим IBM-CGA, следует установить цвета 6 и 7 
+одинаковыми и равными цвету 4. По сути режим FLASH всегда включен, и 
+на экране постоянно меняются цвета PAPER с 4-го на 6-й, а цвета INK с 
+5 на 7-й. Если эти пары цветов для атрибута знакоместа устанавливаются 
+одинаковыми, то FLASH в этом месте не виден.
+
+##### *Комментарий к функциям работы с устройствами хранения информации.*
+
+В этих функциях в регистре A обычно задается номер и тип устройства: 
+
+    бит 0..3 - номер устройства
+    бит 4..7 - тип устройства:
+            0 - дисковод
+            6 - ram-disk
+            8 - HDD
+            C - CD-ROM
+
+остальные номера не используются

docs/Original/Estex DSS/Estex.txt

@@ -0,0 +1,155 @@
+Estex: Disk SubSystem (DSS) Programming Guide
+
+Table of Contents
+1. Introducing
+2. Identification of system functions
+3. Disk devices functions
+
+
+1. Introducing
+
+   This document contains the list of functions and concepts of 
+interaction with a disk subsystem.
+   DSS is a collection of very useful functions that reside in 
+DSS itself, ready for use by any your programs. These functions 
+are stored in library SYSTEM.DOS and allow management of files, 
+memory allocation, loading and execution of the programs.
+
+File specification
+
+   The file specification is a string, containing a names of disk, 
+directories separated by a symbol "\" and name of file. The names 
+of disk drive and directories can be discard.
+
+for example:
+C:\TEXT\DOC\text.doc
+A:file.txt
+\TEXT\info.txt
+
+   The DSS used chars with colon suffix as names of disk devices 
+(A:, B:, C: etc.) The name of disk can be written down before 
+filename for specified disk there it placed. 
+For example: command 
+DIR C:DATFILE 
+searches for DATFILE in the current directory of disk C:.
+   When disk name not specified DSS used current disk. At start 
+DSS, the current disk is a disk whence was loaded DSS.
+   The filenames consist of two parts. The first part contain 8 
+chars of file name. The second part is not necessary and contain 
+3 chars of file type (also known as extentsion). At the writing 
+of filename, both parts are separated by char point.
+For example: the names "NAME" and "NAME." is specified same file. 
+In the name don't allows symbols with codes less 32 and chars 
+. " / \ [ ] : | < > + = ; ,
+   As the subdirectories files too, their names are formed by 
+same way. The name of root directory always "\". And each 
+subdirectories contain two items with names "." and "..". The 
+name "." specified a current directory and name ".." specified 
+name of parent(uplevel) directory.
+   Some console commands and DSS functions allow to use global 
+symbols ? and * which can be used for filename templates.
+   The symbol ? means that any one char of filename. The 
+symbol * means that it char can be replaced by any symbols.
+For example:
+*.txt - means, all files with type "txt"
+a??.* - means, files which contain three or less symbols and 
+    first symbol is "a"
+dc*.exe - means, files with type "exe" and began "dc"
+
+File attributes
+
+   The each bit of byte attributes specified various attribute. 
+And it can be changed by DSS function.
+
+bit 0 - Read only
+bit 1 - Hidden
+bit 2 - System
+bit 3 - Volume label
+bit 4 - Directory
+bit 5 - Archive
+bit 6 - Reserved
+bit 7 - Reserved
+
+   Attribute "read only". When value is 1, file can be read, 
+but can't be written or deleted.
+   Attribute "hidden". When value is 1, DSS can't manipulate 
+with this file.
+   Attribute "system". Specified system file.
+   Attribute "volume label". In old version of MSDOS used for 
+specified volume laben, now it can be used for long filenames. 
+And must be 0 for compatibles.
+   Attribute "directory". When value is 1, means that this 
+file is directory.
+   Attribute "archive". This bite sets in 1 when DSS writing 
+in this file. It can be used in backup utilities for detect 
+changed files.
+
+File handle
+   When any file are opened, DSS build File Control Block in 
+DSS working areas.
+   The Handle (and assigned file) identified by number which 
+returned DSS to program after file opening and used it in all 
+further DSS calls. In other words, when file is opening, the 
+program informs DSS his name and has taken back file handle. 
+Which used in further file operations.
+   All necessary information for working with file are placed 
+in DSS working areas.
+
+
+2. Identification of system functions
+
+00h (00) VERSION (Version of DSS)
+input:
+C - 00h
+output:
+D - version number
+E - modification
+The function return version number of DSS.
+
+
+3. Disk devices functions
+
+01h (01) CHDISK (Change current disk)
+input:
+A - disk number (0-A,1-B...)
+C - 01h
+output:
+A - error code, if CF=1
+A - number of disks, if CF=0
+The function changes current disk device.
+
+02h (02) CURDISK (Current disk number)
+input:
+C - 02h
+output:
+A - current disk number (0-A,1-B...)
+The function returns number of current disk device.
+
+03h (03) DSKINFO (Disk information)
+input:
+A - disk number (0-A,1-B...0FFh-current)
+C - 03h
+output:
+A - error code, if CF=1
+A - sectors per cluster, if CF=0
+HL - clusters per disk
+DE - free clusters
+BC - bytes per sector
+The function returns information about disk device 
+(capacity and free space).
+for example: 
+	LD	C,03h		;Function DSKINFO
+	LD	A,0FFh		;Information about current disk
+	RST	10h		;Execution of function
+	LD	A,D		;There is a free
+	OR	E		;space?
+	JR	Z,NO_SPACE	;No, the disk is completely filled
+
+09h (09) BOOTDSK (Number of boot disk)
+input:
+C - 09h
+B = 0
+output:
+A - number of boot disk (0-A,1-B...)
+The function returns number of boot disk device whence was loaded DSS.
+

docs/Original/Estex DSS/Estex_r.txt

@@ -0,0 +1,126 @@
+Estex: Дисковая подсистема (DSS) – Обзор
+
+1.	Введение
+2.	Загрузка подсистемы
+3.	Системная консоль
+4.	Файловая система
+
+1. Введение
+    Estex - операционная система компьютера Sprinter, включающая 
+в себя различные модули. Данный документ описывает модуль дисковой 
+подсистемы.
+    В DSS используется та же самая файловая система, как и в 
+MS-DOS FAT16 и полностью с ней совместима. 
+
+2. Загрузка подсистемы
+    После включения питания или сброса компьютера, BIOS считывает 
+первичный загрузчик с 1-го сектора загрузочного диска.
+    Если загрузка происходит с HDD или дискеты, то сначала загрузочный 
+сектор считывается в память и ему передается управление по загрузке 
+модуля дисковой подсистемы SYSTEM.DOS.
+    Затем выполняются следующие действия: 
+•	инициализация дисковой подсистемы и вывод сообщения "Starting DOS..."
+•	загрузка системной консоли SYSTEM.EXE
+•	выполнение команд указанных в файле SYSTEM.BAT
+Обычно файл SYSTEM.BAT содержит путь к программе файловой навигации 
+пользователя или другому часто используемому приложения. 
+Например "c:\fn\fn.exe".
+
+    Если во время загрузки вы хотите пропустить выполнение SYSTEM.BAT. 
+То вам следует нажать клавишу "SHIFT", как только появиться 
+сообщение "Starting DOS..." и удерживать пока не появится приглашение 
+консоли ("C:\>").
+
+3. Системная консоль
+    В DSS многие задачи могут быть выполнены через интерфейс командной 
+строки называемой системной консолью. Основная задача консоли ввод 
+команд и их исполнение. Также она имеет ряд функций, которые выполняют 
+такие действия как управление файлами, перемещение по файловой структуре 
+каталогов, редактирование командной строки и переменных среды.
+    Системная консоль позволяет пользователю взаимодействовать с 
+операционной системой. Для DOS системная консоль это SYSTEM.EXE. Если вы 
+видите на экране приглашение командной строки (A:\> или C:\>), то это 
+означает что SYSTEM.EXE загружен и активизирован. Когда вы вводите 
+командную строку, командный процессор интерпретирует команду и выполняет 
+необходимые действия.
+    На сегодняшний день в консоли доступны следующие команды:
+CD	Displays the name of or changes the current directory.
+CHDIR	Displays the name of or changes the current directory.
+CLS	Clears the screen.
+DATE	Displays or sets the date.
+DEL	Deletes one or more files.
+DIR	Displays a list of files and subdirectories in a directory.
+ECHO	Displays messages, or turns command echoing on or off.
+ERASE	Deletes one or more files.
+EXIT	Quits the SYSTEM.EXE program (command interpreter).
+HELP	Provides Help information for console commands.
+MD	Creates a directory.
+MKDIR	Creates a directory.
+PAUSE	Suspends processing of a batch file and displays a message.
+RD	Removes a directory.
+REM	Records comments (remarks) in batch files or SYSTEM.BAT.
+REN	Renames a file or files.
+RENAME	Renames a file or files.
+RMDIR	Removes a directory.
+TIME	Displays or sets the system time.
+VER	Displays the System version.
+
+4. Файловая система
+    Сейчас, в качестве файловой системы Estex использует FAT12 и FAT16. 
+С помощью файловой системы FAT (File Allocation Table) организуются 
+данные на винчестере и дискетах.
+    Для указания спецификации файла используется следующая форма:
+
+[drive:][directory\]filename[.ext]
+
+    Файловая спецификация - это строка символов содержащая наименования 
+диска, директорий отделенных символом "\" и имя файла. Имена диска и 
+директории могут быть опущены, если требуемый файл расположен в текущей 
+директории.
+
+Например: 
+
+C:\TEXT\DOC\text.doc
+A:file.txt
+\TEXT\info.txt
+
+    В DSS в качестве имен дисковых устройств используются буквы с 
+последующим символом двоеточия (A:, B:, C: и.т.д.) Имя диска может быть 
+набрано перед именем файла для указания диска, на котором он расположен. 
+
+Например: 
+команда 
+DIR C:TESTFILE 
+ищет TESTFILE в текущей директории диска C:. 
+Если имя диска не указанно используется текущий диск. После запуска DSS, 
+текущим диском является диск, с которого была загружена DSS.
+
+    Имена файлов состоят из двух частей. Первая часть может содержать 
+8 букв, цифр или следующие специальные символы: 
+$ % ' – _ @ { } ~ ` ! # ( ). 
+Вторая часть не является обязательной и содержит любую комбинацию из трех 
+букв, цифр или специальных символов с предшествующей точкой (.). 
+Например имена "NAME" и "NAME." указывают на одинаковый файл. 
+В имени файла не допускаются символы с кодом меньше 32, а также символы 
+. " / \ [ ] : | < > + = ; ,
+    Поскольку директории также являются файлами их имена образуются по 
+тем же правилам.
+    Имя корневой директории всегда "\". И каждая поддиректория содержит 
+два элемента с именами "." and "..". Имя "." указывает на текущую 
+директорию, а имя ".." указывает на родительную (на уровень выше) 
+директорию.
+    Некоторые команды и функции DSS позволяют использовать глобальные 
+символы * и ? которые могут использоваться для задания шаблона имени 
+файла.
+    Символ ? означает любой один символ в имени файла. 
+    Символ * означает, что он может быть заменен на любое количество 
+любых символов.
+
+for example: 
+*.txt     - означает, все файлы с типом "txt"
+a??.*     - означает, файлы содержащие три и менее символов и первый символ "a"
+dc*.exe   - означает, файлы с типом "exe" и начинающиеся на "dc"
+
+    В именах файлов не делается различий между заглавными и прописными 
+символами.
+

docs/Original/Акселератор/accel_r.txt

@@ -0,0 +1,97 @@
+   Акселератор компьютера Sprinter.
+
+   Акселератор предназначен для ускорения операций по пересылке блоков данных в ОЗУ и видео-ОЗУ.
+
+   Акселератор позволяет:
+
+- быстро заполнять горизонтальную или вертикальную линию длиной до 256 точек одним цветом (в режиме 640x256 - одинарную/двойную горизонтальную линию длиной до 512 точек) 
+- быстро копировать горизонтальную или вертикальную линию длиной до 256 точек (в режиме 640x256 - горизонтальную линию до 512 точек) 
+- проводить быстрые операции AND, OR, XOR с блоками памяти.
+
+   Акселератор не может работать с блоками данных ПЗУ и Быстрого-ОЗУ.
+
+   ОЗУ акселератора является частью внутреннего ОЗУ ППЛМ.
+Операции по пересылке данных производятся путем записи блока данных в это
+внутреннее ОЗУ, а затем копировании его в нужное место ОЗУ из ОЗУ акселератора.
+Блок данных, записываемый в ОЗУ акселератора может иметь различную
+длинну из диапазона 1..256 байт.
+
+   После одной записи копирование может производиться несколько раз и, таким
+образом, можно производить заполнение экрана текстурами.
+
+   Для заполнения экрана одним цветом используется другой режим
+акселератора. В нем вместо копируемого блока данных из внутреннего ОЗУ
+производится запись данных с шины процессора, которые в этот момент не
+изменяются.
+
+   Управление акселератором производится непосредственно из программы.
+Для этого изпользуются команды процессора, которые, фактически, являются
+операциями типа NOP. 
+
+        LD B,B - выключить акселетарор.
+        LD D,D - включить акселератор в режим приема байта размера блока
+                далее следует команда типа LD A,dat, где dat и будет новым
+                размером блока. Если размер блока был установлен ранее,
+                его можно не устанавливать.
+        LD C,C - Операция Fill - заполнение одним байтом. Последующая
+                команда типа LD (HL),A приведет к заполнению указанного
+                ранее количества байт значением A
+        LD E,E - Операция Fill для графического экрана - заполнение
+                вертикальных линий.
+        LD H,H - rezerved
+        LD L,L - копирование блока. Последующая команда типа LD A,(HL)
+                приведет к заполнению ОЗУ акселератора данными из адреса (HL),
+                а команда типа LD (DE),A приведет к перезаписи данных из ОЗУ
+                акселератора в ОЗУ или видео-ОЗУ.
+        LD A,A - копирование блока для графического экрана подобна команде
+                LD L,L, но работает с вертикальными линиями экрана.
+
+   Пример использования акселератора:
+
+        ; Считаем, что экранная страница уже открыта по адресу #C000
+        LD HL,#C040     ; адрес начала линии первого экрана
+        LD DE,#C180     ; адрес начала линии второго экрана
+        LD BC,#140      ; длина экрана по горизонтали
+        DI              ; запретить прерывания для работы с акселератором
+        LD D,D          ; включить акселератор на установку размера блока
+        LD A,0          ; установить размер блока - 256 байт
+        LD A,A          ; установить акселератор на копирование
+                        ; вертикальных линий.
+        LDIR            ; копировать
+        LD B,B          ; выключить акселератор
+        EI              ; включить прерывания
+
+
+
+   Эта часть программы произведет копирование всего содержимого первого экрана на другой. 
+Время исполения составляет примерно 26 милисекунд.
+
+   Дополнительные функции акселератора (AND, OR, XOR) работают таким же образом. 
+Для выполнения логических функций используются команды XOR (HL); OR (HL); AND (HL).
+
+        Пример кодирования блока в 256 байт.
+
+        LD HL,ADRES_1
+        LD DE,XOR_DAT
+        DI
+        LD D,D
+        LD A,0     ; число байт, которые надо закодировать
+        LD L,L
+        LD A,(DE)  ; взять блок данных в ОЗУ акселератора
+        XOR (HL)   ; произвести операцию XOR с данными акселератора
+        LD (HL),A  ; запомнить в ОЗУ результат операции
+        LD B,B
+        EI
+
+
+Скорость работы акселератора ограничивается только физической
+скоростью работы основного ОЗУ. Определить примерное время работы команды с
+акселератором можно по такой формуле:
+
+Время работы = время работы команды без акселератора + время работы
+акселератора
+
+Время работы акселератора = число пересылаемых байт /7 микросекунд
+
+Во время работы акселератора необходимо отключать прерывания, так как в этот момент 
+изменяется система команд процессора и программа на прерывании не сможет работать корректно. 

docs/Original/Архитектура/ARHITECT.TXT

@@ -0,0 +1,635 @@
+    ÜÜÜÜÜÜ
+   ÜÛ°°°°°°
+   Û°°   Û°°
+   Û°°ÜÜÜÛ°°
+   Û°°°°°°°°
+   Û°°   Û°°
+   Û°°   Û°° àå¨â¥ªâãà  ª®¬¯ìîâ¥à  Sprinter.
+   ß°°   ß°°
+
+        ‚¢¥¤¥­¨¥.
+
+        „ ­­®¥ ®¯¨á ­¨¥ ¯à¥¤¯®« £ ¥â ­ «¨ç¨¥ ®¯à¥¤¥«¥­­ëå §­ ­¨© ç¨â â¥«ï,
+  ¨¬¥­­® §­ ­¨¥  àå¨â¥ªâãàë ª®¬¯ìîâ¥à  ZX-Spectrum ¨ ¨å à §­®¢¨¤­®á⥩, ¢
+ç áâ­®á⨠Pentagon-128 ¨ Scorpion-256,   â ª ¦¥ §­ ­¨¥ ï§ëª  BASIC ¨
+­¥ª®â®à®¥ §­ ª®¬á⢮ á ï§ëª®¬  áᥬ¡«¥à  Z80.
+        ‡¤¥áì ï ¡ã¤ã ­ §ë¢ âì ª®­ä¨£ãà æ¨¥© ¬ è¨­ë - ª®­ªà¥â­ãî ॠ«¨§ æ¨î
+ª®­ªà¥â­®© áå¥¬ë ¢ ¯¥à¥¯à®£à ¬¬¨à㥬®© «®£¨ç¥áª®© ¬¨ªà®á奬¥ (��‹Œ).
+�â® ®§­ ç ¥â, çâ® ¬ è¨­  ¨¬¥¥â ¬­®¦¥á⢮ ª®­ä¨£ãà æ¨©, ª ¦¤ ï ¨§ ª®â®àëå
+¨¬¥¥â ᢮î á奬ã.
+        Ÿ â ª ¦¥ ¨á¯®«ì§ãî ¯®­ï⨥ Š�˜-Ž‡“. �â® ­¥ Š�˜ ¢ ä®à¬ «ì­®¬
+á¬ëá«¥,   ¡ëáâ஥ Ž‡“, ¢ ª®â®à®¬ ¯à®æ¥áá®à ¬®¦¥â à ¡®â âì ­  ¢ë᮪®©
+ç áâ®â¥ ¡¥§ ®¦¨¤ ­¨ï. Š�˜-¥¬ íâ® Ž‡“ ­ §ë¢ ¥âáï ⮫쪮 ¯® âà ¤¨æ¨¨,
+¯®¤®¡­® Š�˜-ã ­  Š�537�“10 ¢ ª®¬¯ìîâ¥à å Pentagon-128.
+
+
+        Šà âª¨¥ ¤ ­­ë¥ ª®¬¯ìîâ¥à  Sprinter.
+
+        �p®æ¥áá®p . . . . . . . . . . . Z84C15
+        ’ ªâ®¢ ï ç áâ®â  . . . .  21MHz/3.5MHz
+        Ž‡“ . . . . . . . . . . . . . . 4096Kb
+        Š�˜ Ž‡“ . . . . . . . . . . . . . 64Kb
+        �‡“ . . . . . . . . . . . . . . .128Kb
+        ‚¨¤¥®-Ž‡“ . . . . . . . . . 256Kb(512)
+        Š®­âp®««¥p ¤¨áª®¢ . . . . . Šp1818‚ƒ93
+        �®¤¤¥p¦ª  1.44Mb ä®p¬ â  . . 3.5"¤¨áª 
+        Š®­âp®««¥p ¢¨­ç¥áâ¥p  . . . . . IDE/AT
+        Š®­âp®««¥p ª« ¢¨ âãpë . . .  101key/AT
+        Š®­âp®««¥p ¬ëè¨ . . . . . . . MS-Mouse
+        „¢  á«®â  . . . . . . . áâ ­¤ pâ ISA-8
+        †¥«¥§­ ï í¬ã«ïæ¨ï AY-3-8910 áâ¥à¥®-OUT
+        COVOX . . . . . . . . . 8bit x 4chanel
+        ‚¨¤¥®-p¥¦¨¬ë: . . .  Spectrum standart
+        GRAF 320x256x256,640x256x16, TXT 80x32
+        ‚ë室 ¢¨¤¥® ­  TV ¨«¨ CGA ¬®­¨â®p, RGB
+
+
+        ’¥å­¨ç¥áª ï ॠ«¨§ æ¨ï.
+
+        Ÿ¤à®¬ ¬ è¨­ë ïîâáï ¯à®æ¥áá®à Z84C15 ¨ ��‹Œ EPF10K10QC208.
+Šà®¬¥ ­¨å ­  ¯« â¥ ¯à¨áãâáâ¢ãîâ ¬¨ªà®á奬a �‡“, 72å-¯¨­®¢ë© SIMM
+­  4Mb, 256Kb ¢¨¤¥®-Ž‡“, 64Kb Š�˜-Ž‡“, á奬  ª®­â஫«¥à  ¤¨áª®¢®¤  ­ 
+�ˆ‘ Š�1818‚ƒ93, ¡ãä¥àë ¤«ï ¯®¤ª«î祭¨ï ¤¦®©á⨪ , ¬ £­¨â®ä®­ , ¯à¨­â¥à ,
+ª« ¢¨ âãàë, ¤¨áª®¢®¤®¢, ¢¨­ç¥áâ¥à , ¬ëè¨, ¡ãä¥à­ë¥ ¬¨ªà®á奬ë 設ë ISA-8
+¨ ¥é¥ ®¤­  ��‹Œ ä¨à¬ë ALTERA - EPM7032LC44. �â  ��‹Œ ­¥ ¬¥­ï¥â ᢮¥©
+ª®­ä¨£ãà æ¨¨ ¨ ¯à¥¤­ §­ ç¥­  ¤«ï ®¡¥á¯¥ç¥­¨ï ᨭåà®­¨§ æ¨¨ ¨ ­ ç «ì­®£®
+§ ¯ã᪠ ª®¬¯ìîâ¥à . �  ¯« â¥ â ª ¦¥ ¯à¥¤ãᬮâ७  ¢®§¬®¦­®áâì ¯®¤ª«î祭¨ï
+CMOS ç á®¢ ­  ®á­®¢¥ ¬¨ªà®á奬ë DALLAS. Šà®¬¥ ¯¥à¨ä¥à¨¨ ¨ ¡ãä¥à®¢ ¨¬¥îâáï
+¬¨ªà®áå¥¬ë ¤¥è¨äà æ¨¨, ¢å®¤ë ª®â®àëå ¯®¤ª«îç îâáï ª ¯à®æ¥áá®àã ç¥à¥§ ��‹Œ.
+�â® ¯®§¢®«ï¥â «¥£ª® ¬¥­ïâì  ¤à¥á æ¨î ãáâனá⢠¡¥§ ª ª®£® «¨¡® ¨§¬¥­¥­¨ï
+à §¢®¤ª¨ ¯¥ç â­®© ¯« âë.
+
+
+        ‚®§¬®¦­®á⨠ àå¨â¥ªâãàë ¬ è¨­ë.
+
+        ‘奬  ª®¬¯ìîâ¥p  ®á­®¢ ­  ­  ¡®«ì让 ¯¥p¥¯p®£p ¬¬¨p㥬®© «®£¨ç¥áª®©
+¬¨ªp®á奬¥. �®¤ª«î祭¨¥ ¯¥à¨ä¥à¨©­ëå ãáâனá⢠ç¥à¥§ ��‹Œ ¯®§¢®«ï¥â ¯®«ãç¨âì
+¢ë᮪ãî £¨¡ª®áâì ¬ è¨­ë ¯® ª®­ä¨£ãà æ¨ï¬.
+        �p®£p ¬¬¨p®¢ ­¨¥ ��‹Œ ®áãé¥á⢫ï¥âáï ­¥¯®áp¥¤á⢥­­® ¢ ¬®¬¥­â
+¢ª«î祭¨ï,   â ª ¦¥ ¯p¨ ¯¥p¥§ £p㧪¥, çâ® ¯®§¢®«ï¥â ª p¤¨­ «ì­® ¬¥­ïâì
+á奬㠢 ��‹Œ ­¥¯®áp¥¤á⢥­­® ¢® ¢p¥¬ï p ¡®âë. �⮠ᨫ쭮 ¢ë¤¥«ï¥â
+ àå¨â¥ªâãàã ª®¬¯ìîâ¥à  ¨§ à鸞 áãé¥áâ¢ãîé¨å ª®¬¯ìîâ¥à®¢ ¨ ¯®í⮬㠬­®£¨¥
+¯®­ïâ¨ï, ¯à¨áã騥 ®¡ëç­ë¬ ¬ è¨­ ¬, ¬¥­ïîâ ᢮© á¬ëá«. ” ªâ¨ç¥áª¨ ª®¬¯ìîâ¥à
+¨¬¥¥â ¨§¬¥­ï¥¬ãî  àå¨â¥ªâãàã, ¢ ª®â®à®© ¢®§¬®¦­ë ¨§¬¥­¥­¨ï ¢® ¬­®£¨å ç áâïå
+á奬ë. ’ ª, ­ ¯à¨¬¥à, ­¥«ì§ï £®¢®à¨âì ® ª®­ªà¥â­ëå  ¤à¥á å ¯®à⮢
+¯®¤ª«î祭¨ï ¯¥à¨ä¥à¨¨, â ª ª ª ®­¨ ¬®£ãâ ¡ëâì ¨§¬¥­¥­ë ¢ ®¤­ã ᥪ㭤ã
+¯ã⥬ ¯¥à¥¯à®£à ¬¬¨à®¢ ­¨ï ��‹Œ ¨ ¤ ­­ëå ¢ Ž‡“, ®â¢¥ç îé¨å §  ª®­ä¨£ãà æ¨î
+¯®à⮢. Š®­ªà¥â­ë¥  ¤à¥á  ¯®ï¢«ïîâáï ⮫쪮 ¢ ª®­ªà¥â­ëå ª®­ä¨£ãà æ¨ïå,
+­ ¯à¨¬¥à, â ª®© ª ª ª®­ä¨£ãà æ¨ï ZX-Spectrum.
+        �¥à¥¯à®£à ¬¬¨à㥬®áâì áå¥¬ë ¤ ¥â ¤®¢®«ì­® ¡®«ìèãî ᢮¡®¤ã
+ä ­â §¨¨ ¯à®£à ¬¬¨áâ  ¯® ª®­ä¨£ãà æ¨¨ ¬ è¨­ë. ‡ ¤ã¬ë¢ ï ª®­ªà¥â­ãî
+à ¡®â㠯ணࠬ¬¨áâ ¬®¦¥â ®¯à¥¤¥«¨âì ¢ ª ª®© ª®­ä¨£ãà æ¨¨ ¥¥ ¬®¦­®
+ᤥ« âì «ãçè¥,  , ¢®§¬®¦­®, ¨ ¯à¨¤ã¬ âì á¢®î ª®­ä¨£ãà æ¨î, ª®â®àãî
+§ â¥¬ ¬®¦­® ॠ«¨§®¢ âì ¢ ��‹Œ ¨ ¢ª«îç¨âì ¯¥à¥¤ § ¯ã᪮¬ í⮩ ¯à®£à ¬¬ë.
+
+
+                �«®ç­ ï á奬  ª®¬¯ìîâ¥à  Sprinter.
+
+  ÚÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿    ÚÄÄÄÄÄÄÄÄÄÄÄÄ>Sinc
+  ³�ਭâ¥à³ ³   2 ISA SLOTS                ³    ³    ÚÄÄÄÄÄÄÄ>R
+  ÃÄÄÄÄÄÄÄ´ ÀÄÄÄÂÄÂÄÂÄÂÄÂÄÄÄÄÄÄÄÂÄÂÄÂÄÂÄÂÄÄÙ    ³    ³ ÚÄÄÄÄÄ>G
+  ³ Œëèì  ³ ÚÄÄÄÁÄÁÄÁÄÁÄÁÄÄÄÄÄÄÄÁÄÁÄÁÄÁÄÁÄÄ¿    ³    ³ ³ ÚÄÄÄ>B
+  ÀÄÂÄÂÄÂÄÙ ³   �ãä¥àë ¨ ¤¥è¨äà â®àë       ³    ³  ÚÄÁÄÁÄÁÄ¿
+    ³ ³ ³   ÀÄÄÄÂÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÂÄÂÄÄÄÄÂÄÂÄÙ    ³  ³  –€�  ³
+    ³ ³ ³       ³INT       ³ ³  ³ ³    ³ ³      ³  ³ ¡ãä¥à ³
+ ÚÄÄÁÄÁÄÁÂÄ¿    ³          ³ ³  ³ ³   ÚÁÄÁÄÄÄÄÄÄÁÄ¿ÀÄÄÂÄÂÄÄÙ   ÚÄÄÄÄÄÄÄÄ¿
+ ³ ‚­ãâà ³ ÃÄÄÄijÄÄÄÄÄÄÄÄÄÄÙ ÀÄij ³ÄÄÄ´ EPF10K10  ÃÄÄÄÙ ÀÄÄÄÄÄÄ´ ¢¨¤¥®  ³
+ ³ ¯®àâë ³ ÃÄÄÄijÄÄÄÄÄÄÄÄÄÄDATAij ³ÄÄÄ´           ÃÄÄV_DATAÄÄÄÄ´        ³
+ ÃÄÄÄÄÄÄÄÙ ÃÄÄÄijÄÄÄ¿ ÚÄÄÄÄÄÄÄÄij ³ÄÄÄ´           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´  Ž‡“   ³
+ ³         Ã<ÄÄÄÙ   ³ ³         ³ ³   ³           ³            ³        ³
+ ³         ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ÀÄÄÄ´           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´        ³
+ ³ Z84C15  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄADRESSÄÄÄÄÄ´           ÃÄV_ADRESSÄÄÄ´        ³
+ ³         ÃÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´        ³
+ ³         ³    ³ ³ ³ ³               ³           ³            ³        ³
+ ³         Ã<ÄÄij ³Ä³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ>´           ÃÄÄWE,CSiÄÄÄ>´        ³
+ ³         Ã<ÄÄij ³Ä³ ³ÄÄÄÄDIRÄÄÄÄÄÄÄ>´           ³            ÀÄÄÄÄÄÄÄÄÙ
+ ³         Ã<ÄÄij ³Ä³ ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ>´           ÃÄÄÄÄÄÄÄ> Audio OUTs
+ ³         ³    ³ ³ ³ ³               ³           ³            ÚÄÄÄÄÄÄÄÄ¿
+ ³         ³  ÚÄÁÄÁÄÁÄÁÄÄÄÄÄÄÄ¿       ³           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´ MAIN   ³
+ ³         ³  ³ �‡“ ¨ Š�˜-Ž‡“ Ã<ÄADR'Ä´           ÃÄÄDATAÄÄÄÄÄÄ´  RAM   ³
+ ÀÄÂÄÂÄÂÄÄÂÙ  ³            CS Ã<ÄCSÄÄÄ´           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´        ³
+   ³ ³ ³  ³   ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ       ³           ³            ³ SIMM   ³
+   ³ D ³  ³   ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿        ³           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´        ³
+   ³ A ³  ³   ³ EPM7032      ÃÄÄÄÄÄÄÄ>´           ÃÄÄADRESSÄÄÄÄ´        ³
+   ³ T ³  ÀÄÄ>´ Sinchro      ³        ³           ÃÄÄÄÄÄÄÄÄÄÄÄÄ´        ³
+   ³ A ³      ³ HDD_DIR      Ã<ÄÄÄÄÄÄÄ´           ³            ³        ³
+   ³ ³ ³      ³ ”€�—         Ã<ÄÄÄÄÄÄÄ´           ÃÄRAS,CAS,WEÄ´        ³
+   ³ ³ ³      ÀÄÂÄÂÄÂÄÂÄÂÄÄÄÄÙ        ³           ³            ÀÄÄÄÄÄÄÄÄÙ
+   ³ ³ ³        ³ ³ ³ ³ ³             ³           ³
+ ÚÄÁÄÁÄÁÄÄÄÄÄÄÄÄÁÄÁÄÁÄÁÄÁÄÄÄÄÄÄÄ¿     ³           ³
+ ³ �¥à¨ä¥à¨©­ë¥ ãáâனá⢠      Ã<ÄÄÄÄ´           ³
+ ³ FDD,HDD,KEMPSTON             Ã<DIRÄ´           ³
+ ³                              Ã<ÄÄÄÄ´           ³
+ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ     ³           ³
+                ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ>´           ³
+   ÚÄÄÄÄÄÄÄÄ¿   ³ ÚÄÄÄÄÄÄÄÄ¿          ³           ³
+   ³ TAPE   Ã<ÄÄÙ ³KeyboardÃÄÄÄÄÄÄÄÄÄ>´           ³
+   ³ in/out ³     ô          ³           ³
+   ÀÄÄÄÄÄÄÄÄÙ     ÀÁÁÁÁÁÁÁÁÙ          ÀÄÄÄÄÄÄÄÄÄÄÄÙ
+
+                                �¨áã­®ª 1.
+
+
+
+        „«ï ¯à®áâ®âë ­¥ª®â®àë¥ ¡ãä¥àë ¨ ¤¥è¨äà â®àë ­  á奬¥ ­¥ 㪠§ ­ë.
+Š®«¨ç¥á⢮ �஢®¤®¢ ¢ 設 å â ª ¦¥ ãá«®¢­ë. — áâì ᨣ­ «®¢ ã¯à ¢«¥­¨ï
+ãáâனá⢠á ��‹Œ á¬ã«ì⨯«¨æ¨à®¢ ­ë á  ¤à¥á ¬¨ SIMM- .
+
+
+        „ «ì­¥©è¥¥ ®¯¨á ­¨¥  àå¨â¥ªâãàë ï¥âáï ®¯¨á ­¨¥¬ ª®­ªà¥â­ëå
+ª®­ä¨£ãà æ¨© ¨ ç á⥩ ª®­ä¨£ãà æ¨©. �® ¯¥à¥¤ í⨬ á«¥¤ã¥â ᪠§ âì ­¥áª®«ìª®
+á«®¢ ® ¯¥à¥ª«î祭¨¨ á ¬¨å ª®­ä¨£ãà æ¨©.
+
+        ‡ £à㧪  ª®­ä¨£ãà æ¨©.
+
+        ‚ ¬®¬¥­â ¢ª«î祭¨ï ª®¬¯ìîâ¥à ,   â ª ¦¥ ¯®á«¥ ­ ¦ â¨ï ­  RESET ¢áï
+¨­ä®à¬ æ¨ï, ­ å®¤¨¢è ïáï ¢ ��‹Œ ®â¢¥ç îé ï §  ª®­ªà¥â­ãî ª®­ä¨£ãà æ¨î,
+áâ¨à ¥âáï. ��‹Œ ¯¥à¥å®¤¨â ¢ ०¨¬ ®¦¨¤ ­¨ï § £à㧪¨ ¡«®ª  ¤ ­­ëå á奬ë.
+        ‚ íâ®â ¬®¬¥­â ¯à®æ¥áá®à ¯®«­®áâìî ®âª«î祭 ®â ª ª®© «¨¡® ¯¥à¨ä¥à¨¨.
+‚ ¥£®  ¤à¥á­®¥ ¯à®áâà ­á⢮ ¯ ¬ï⨠®ª §ë¢ ¥âáï ¢ª«î祭  ®¤­  áâà ­¨æ  �‡“ ¨
+®¤­  áâà ­¨æ  Ž‡“ Š�˜-¯ ¬ïâ¨. ‹î¡ ï § ¯¨áì ¢  ¤à¥á­®¥ ¯à®áâà ­á⢮ ¯ ¬ïâ¨
+¯à®æ¥áá®à  ¢ íâ®â ¬®¬¥­â ¯à¨¢®¤¨â ª § ¯¨á¨ ¤ ­­ëå ¢ ��‹Œ ¨ ¯à®£à ¬¬  ¢
+¯®¤ª«î祭­®© áâà ­¨æ¥ �‡“ ¨¬¥¥â ⮫쪮 ®¤­ã ¥¤¨­á⢥­­ãî 楫ì - § £à㧨âì
+¢ ��‹Œ ¤ ­­ë¥ ª®­ä¨£ãà æ¨¨. ‚ í⮩ ¦¥ áâà ­¨æ¥ �‡“ ­ å®¤ïâáï ¤ ­­ë¥
+­ ç «ì­®© ª®­ä¨£ãà æ¨¨. (‚ ¤ ­­ë© ¬®¬¥­â íâ® ª®­ä¨£ãà æ¨ï Sprinter-1.)
+�ணࠬ¬  § £à㧪¨ ª®­ä¨£ãà æ¨¨ ¯à®¢¥àï¥â ä« £ ¢ Š�˜-¯ ¬ï⨠¨, ¥á«¨ ®­
+ãáâ ­®¢«¥­, § £à㦠¥â ¢ ��‹Œ ¤ ­­ë¥ ¨§ Ž‡“, ¥á«¨ á¡à®è¥­, â® ¤ ­­ë¥ ¨§
+�‡“. �  í⮬ ®á­®¢ ­® ¯¥à¥ª®­ä¨£ãà¨à®¢ ­¨¥ áå¥¬ë ª®¬¯ìîâ¥à .
+        „«ï ¨§¬¥­¥­¨ï áå¥¬ë ­ ¤® § £à㧨âì ¢ ¯®á«¥¤­îî áâà ­¨æã Š�˜-¯ ¬ïâ¨
+¡«®ª ¤ ­­ëå ª®­ä¨£ãà æ¨¨ ᮠᬥ饭¨ï #100 ¨ ¢ëáâ ¢¨âì ä« £, ª®â®àë¬ ï¢«ï¥âáï
+⥪á⮢ ï áâப  "FLEX_10K_LOADING", § ¯¨á ­­ ï ¯® ᬥ饭¨î #80 ¢ í⮩ ¦¥
+áâà ­¨æ¥ Š�˜- . �®á«¥ í⮣® ­ ¤® ¯à®¨§¢¥á⨠¯®«­ë© á¡à®á, ª®â®àë©
+®áãé¥á⢫ï¥âáï ¯à®£à ¬¬­® § ¯¨áìî ¢ ᯥ樠«ì­ãî áâà ­¨æã ¯ ¬ï⨠RESET_PAGE.
+�ணࠬ¬  ¢ �‡“, § ¯ã᪠¥¬ ï ¯® á¡à®áã ­ å®¤¨â ä« £ FLEX_10K_LOADING ¨
+­ ç¨­ ¥â § £à㧪㠤 ­­ëå ¢ ��‹Œ. �ਠí⮬ ®­  ®¤­®¢à¥¬¥­­® § â¨à ¥â ä« £,
+çâ® ¯à¥¤®â¢à é ¥â ¯®¢â®à­ãî § £à㧪㠭®¢®© ª®­ä¨£ãà æ¨¨ ¯à¨ ­ ¦ â¨¨ ­ 
+ª­®¯ªã RESET ¨ ¯®§¢®«ï¥â ¢¥à­ãâìáï ¯®á«¥ "àãç­®£®" á¡à®á  ¢ ­ ç «ì­ãî
+ª®­ä¨£ãà æ¨î. ‡ â¨à ­¨¥ ä« £  â ª ¦¥ ¨§¡ ¢«ï¥â ®â ¬ã祭¨© ¢ á«ãç ¥
+¯®¤ª«î祭¨ï ­¥¯à ¢¨«ì­®© ª®­ä¨£ãà æ¨¨ ¢® ¢à¥¬ï íªá¯¥à¨¬¥­â®¢ á ¯à®£à ¬¬ ¬¨.
+� ¦ â¨¥ ­  RESET ¢á¥£¤  ¢¥à­¥â á奬㠢 ­ ç «ì­ãî ª®­ä¨£ãà æ¨î.
+
+        �ਬ¥ç ­¨¥:
+        ‚­ãâ७­ïï ¨­ä®à¬ æ¨ï ¡«®ª  ¤ ­­ëå ��‹Œ ï¥âáï § ªàë⮩
+¨­ä®à¬ æ¨¥© ä¨à¬ë ALTERA. Šà®¬¥ á ¬¨å ¬¨ªà®á奬 ��‹Œ ALTERA ¯®áâ ¢«ï¥â
+¨ ¯à®£à ¬¬­®¥ ®¡¥á¯¥ç¥­¨¥ ¤«ï à §¢®¤ª¨ á奬 ¢­ãâਠ��‹Œ. Š ᮦ «¥­¨î, íâ 
+¯à®£à ¬¬  ­¥ ¬®¦¥â à ¡®â âì ­  ª®¬¯ìîâ¥à¥ ⨯  ZX-Spectrum ¨ ¢ ¡«¨¦ ©è¥¬
+®¡®§à¨¬®¬ ¡ã¤ã饬 ­¥ ¯à¥¤¢¨¤¨âáï ¥¥ ¢¥àá¨ï ¤«ï Sprinter- . �®í⮬ã
+ࠧࠡ®âª  ­®¢ëå ª®­ä¨£ãà æ¨© ¬®¦¥â ¯à®¨§¢®¤¨âáï ⮫쪮 ¯à¨ ­ «¨ç¨¨
+¤®áâ â®ç­® ¬®é­®© ¬ è¨­ë (¢á¥ ¤¥« «®áì ­  Pentium-166) ¨ ¯à®£à ¬¬ë à §¢®¤ª¨
+á奬 ¢ ��‹Œ, 業  ­  ª®â®àãî á®áâ ¢«ï¥â á®â­¨ ¤®«« à®¢ ‘˜€.
+        ‚ á¢ï§¨ á í⨬, ¢ ¤ ­­ë© ¬®¬¥­â Sprinter ¨¬¥¥â ­¥áª®«ìª® ª®­ªà¥â­ëå
+ª®­ä¨£ãà æ¨©, ¤¢¥ ¨§ ª®â®àëå § ¯¨á ­ë ¢ �‡“,   ®áâ «ì­ë¥ ¬®£ãâ ¡ëâì
+¯®¤£à㦥­ë á ¤¨áª¥âë ¨«¨ ¢¨­ç¥áâ¥à . �®áâ®ï­­® ¢¥¤¥âáï ᮢ¥à襭á⢮¢ ­¨¥
+ª®­ªà¥â­ëå ª®­ä¨£ãà æ¨© ¨ ࠧࠡ®âª  ­®¢ëå.
+
+        Š®­ä¨£ãà æ¨ï Sprinter-1.
+
+        ‚ª«î砥⠢ á¥¡ï ª®­ä¨£ãà æ¨î Spectrum-128/256, à á¯à¥¤¥«¥­¨¥ ¯ ¬ïâ¨
+¤® 4Mb, à áè¨à¥­­ë© íªà ­ á ०¨¬ ¬¨ Spectrum, Text-80x32, Graf-320x256x256,
+ª®­â஫«¥à ¤¨áª®¢®¤ , ª®­â஫«¥à IDE ¢¨­ç¥áâ¥à , ª®­â஫«¥à ª« ¢¨ âãàë AT,
+¯®¤ª«î祭­®© ª ª ZX-Keyboard, 8-bit COVOX.
+        �â  ª®­ä¨£ãà æ¨ï ¬ ªá¨¬ «ì­® ¯à¨¡«¨¦¥­  ª ª®­ä®£ãà æ¨¨ ZX-Spectrum
+¨ ¯®§¢®«ï¥â à ¡®â âì ­  ®¡ëç­ëå ᯥªâà㬮¢áª¨å ¯à®£à ¬¬ å ¨ ¯®á⥯¥­­®
+¬¥­ïâì ¨å ¯®¤ à áè¨à¥­­ë¥ ०¨¬ë íªà ­  ¨ ¯ ¬ïâ¨,   â ª ¦¥ ¤«ï à ¡®âë á
+­®¢ë¬¨ ãáâனá⢠¬¨.
+
+        Š®­ä¨£ãà æ¨ï Sprinter-2.
+
+        ‚ª«î砥⠢ á¥¡ï ª®­ä¨£ãà æ¨î Spectrum-128/256, à á¯à¥¤¥«¥­¨¥ ¯ ¬ïâ¨
+¤® 4Mb, à áè¨à¥­­ë© íªà ­ á ०¨¬ ¬¨ Spectrum, Text-80x32, Graf-320x256x256,
+ª®­â஫«¥à ¤¨áª®¢®¤ , ª®­â஫«¥à IDE ¢¨­ç¥áâ¥à , ª®­â஫«¥à ª« ¢¨ âãàë AT,
+¯®¤ª«î祭­®© ª ª ZX-Keyboard, Accelerator.
+        Š®­ä¨£ãà æ¨ï, ª ª ¨ Sprinter-1 ¯à¨¡«¨¦¥­  ª ᯥªâà㬮¢áª®©, ­®
+¨¬¥¥â ¡®«¥¥ ¦¥á⪨¥ âॡ®¢ ­¨ï ª ¯à®£à ¬¬ ¬ ¯® ᮢ¬¥á⨬®áâ¨. �®§¢®«ï¥â
+¨á¯®«ì§®¢ âì  ªá¥«¥à â®à ®¯¥à æ¨© á ®á­®¢­ë¬ ¨ ¢¨¤¥®-Ž‡“. €ªá¥«¥à â®à
+ã᪮àï¥â ®¯¥à æ¨¨ ¯¥à¥á뫪¨ ¡«®ª®¢ ¤ ­­ëå ¨ § ¯®«­¥­¨ï Ž‡“ ®¤­¨¬ ¡ ©â®¬
+¤® 䨧¨ç¥áª®£® ¯à¥¤¥«  ᪮à®á⨠®á­®¢­®£® Ž‡“.
+        ‚ ¯®á«¥¤­¥© ¢¥àᨨ ª®­ä¨£ãà æ¨ï Sprinter-2 ­¥ ¨¬¥¥â Spectrum-®¢áª®©
+ª« ¢¨ âãàë. ‚¬¥áâ® ­¥¥ ¨§ ¯®àâ  0FEh áç¨â뢠¥âáï ᪠­ª®¤ ¯à¨è¥¤è¨© á
+AT-ª« ¢¨ âãàë.
+
+        Š®­ä¨£ãà æ¨ï ZX-Spectrum-256/AY.
+
+        �â  ª®­ä¨£ãà æ¨ï ¬ ªá¨¬ «ì­® ¯à¨¡«¨¦¥­  ª ZX-Spectrum-128/256
+¨ ¢ª«î砥⠢ ᥡï á奬㠬ã§ëª «ì­®£® ᮯà®æ¥áá®à  AY-3-8910. ‚ í⮩
+ª®­ä¨£ãà æ¨¨ ®âáãâáâ¢ãîâ à áè¨à¥­­ë¥ ०¨¬ë íªà ­ .
+        ‚â®à ï ¢¥àá¨ï á奬ë AY ¢ª«î砥⠢ ᥡï âਠ£¥­¥à â®à  £®«®á®¢,
+£¥­¥à â®à è㬠 ¨ ॣã«ïâ®àë  ¬¯«¨âã¤ë. ƒ¥­¥à â®à ®£¨¡ î饩 ®âáãâáâ¢ã¥â.
+’ ª ¦¥ ®âáãâáâ¢ã¥â ¢®§¬®¦­®áâì ç⥭¨ï ¨§ ¯®à⮢ ¤ ­­ëå ᮯà®æ¥áá®à .
+        ‚ âà¥â쥩 ¢¥àᨨ AY ¯à¥¤¯®« £ ¥âáï ¤ ­­ë¥ ­¥¤®áâ âª¨ ¨áª«îç¨âì.
+
+        Š®­ä¨£ãà æ¨ï Sprinter-3.
+
+        Š®­ä¨£ãà æ¨ï ®â¢ï§ ­  ®â ª®­ä¨£ãà æ¨¨ ZX-Spectrum. �®«­®áâìî
+®âª«îç ¥âáï �‡“ ¨ ¢á¥  ¤à¥á­®¥ ¯à®áâà ­á⢮ à §¡¨â® ­  ç¥âëॠ®ª­  ¯® 16k,
+¢ ª ¦¤®¥ ¨§ ª®â®àëå ¯®¤ª«îç ¥âáï «î¡ ï ¨§ 256-⨠áâà ­¨æ Ž‡“. Žâáãâáâ¢ã¥â
+ᯥªâà㬮¢áª¨© íªà ­, £à ä¨ç¥áª¨© íªà ­ â ª®© ¦¥, ª ª ¢ ª®­ä¨£ãà æ¨ïå
+Sprinter-1 ¨ Sprinter-2. ˆ¬¥¥â ¤®¯®«­¨â¥«ì­ë¥ ä㭪樨  ªá¥«¥à â®à .
+�®§¢®«ï¥â ¯à®¨§¢®¤¨âì ®¯¥à æ¨¨ AND, OR ¨ XOR á ¡«®ª ¬¨ ¤ ­­ëå. ˆ¬¥¥â 8-bit
+COVOX.
+        ‚ ¤ «ì­¥©è¥¬ ¯à¥¤¯®« £ ¥âáï ¯®¤ª«î祭¨¥ ¢ í⮩ ª®­ä¨£ãà æ¨¨
+á¯à¨­â¥à®¢áª®© §¢ãª®¢®© ª àâë.
+
+        Š®­ä¨£ãà æ¨ï Game-1.
+
+        �®å®¦  ­  ª®­ä¨£ãà æ¨î Sprinter-3. €ªá¥«¥à â®à ­¥ ¨¬¥¥â «®£¨ç¥áª¨å
+ä㭪権,   ¤«ï ¢ë¢®¤  §¢ãª  ¨¬¥¥â COVOX-Blaster - COVOX á ¡ãä¥à­ë¬ Ž‡“,
+¯®§¢®«ïî騬 ¢ë¢®¤¨âì §¢ãª ¯®¡«®ç­® ¨ ®á¢®¡®¦¤ âì ¯à®æ¥áá®à­®¥ ¢à¥¬ï ¤«ï
+¤à㣮© à ¡®âë. Š®­ä¨£ãà æ¨ï ®à¨¥­â¨à®¢ ­  ­  ¨á¯®«ì§®¢ ­¨¥ ¢ ¨£à å ¤«ï
+Sprinter- .
+
+
+        ‘奬  à á¯à¥¤¥«¥­¨ï ¯ ¬ïâ¨.
+
+        ‘奬ë à á¯à¥¤¥«¥­¨ï ¯ ¬ï⨠¢ ª®­ä¨£ãà æ¨ïå Sprinter-1 ¨ Sprinter-2
+®¤¨­ ª®¢ë ¨ ¤®áâ â®ç­® ¯à®§à ç­ë. ” ªâ¨ç¥áª¨ ®­  ¯à¥¤áâ ¢«ï¥â ᮡ®© á奬ã
+à á¯à¥¤¥«¥­¨ï ¯ ¬ï⨠ª®¬¯ìîâ¥à  Scorpion, á ­ «®¦¥­­®© ­  ­¥¥
+¤®¯®«­¨â¥«ì­®© á奬®©, ª®â®à ï ¯®§¢®«ï¥â ¯à®¨§¢®«ì­® ãáâ ­ ¢«¨¢ âì ¢á¥
+áâà ­¨æë ¯ ¬ïâ¨, ª ª �‡“, â ª ¨ Ž‡“.
+        Š ¦¤ ï áâà ­¨æ  �‡“ ¨«¨ Ž‡“ ¨¬¥¥â ᢮© ¯®àâ, ¢ ª®â®à®¬ 㪠§ë¢ ¥âáï
+¤¥©á⢨⥫ì­ë© ­®¬¥à áâà ­¨æë ¨§ 256-⨠áâà ­¨æ ¢á¥å 4Mb. ‘âà ­¨æë,
+¯à®¥æ¨àã¥¬ë¥ ¢ à §«¨ç­ë¥ ®ª­   ¤à¥á­®£® ¯à®áâà ­á⢠ ¯à®æ¥áá®à  ¨¬¥îâ ᢮¨
+ᮡá⢥­­ë¥ ¯®àâë. ’.¥. ‘âà ­¨æ , ¢ª«îç ¥¬ ï ¢  ¤à¥á  #4000..#7FFF, ¨
+áâà ­¨æ  ­®¬¥à 5 ®¡ëç­®£® Spectrum-®¢áª®£® à á¯à¥¤¥«¥­¨ï ¯ ¬ïâ¨, ¢ª«îç ¥¬ ï
+¢  ¤à¥á  #C000..#FFFF ¨¬¥îâ à §¤¥«ì­ë¥ ¯®àâë.
+        ‚ᥣ® â ª¨å ¯®à⮢ áâà ­¨æ ¯ ¬ï⨠- 32.
+        16 ¯®à⮢ ®â¢¥ç îâ §  ­®¬¥à  áâà ­¨æ Ž‡“, ¯®¤ª«îç ¥¬ë¥ ª  ¤à¥á ¬
+#C000..#FFFF. …é¥ âਠ¯®àâ  ®â¢¥ç îâ §  ¯®¤ª«î祭¨¥ áâà ­¨æ Ž‡“ ª  ¤à¥á ¬
+#0000..#3FFF, #4000..#7FFF ¨ #8000..#BFFF. ‚®á¥¬ì ¯®à⮢ ¨á¯®«ì§ãîâáï ¤«ï
+¯®¤ª«î祭¨ï à §«¨ç­ëå áâà ­¨æ �‡“. Ž¤¨­ ¯®àâ - ¤«ï ¯®¤ª«î祭¨ï áâà ­¨æë
+Š�˜-  ¢¬¥áâ® �‡“. ˆ ®¤¨­ ¯®àâ - íâ® ¯®àâ á¨á⥬­®£® �‡“, ¯®¤ª«îç ¥¬®£® ­ 
+¬¥áâ® �‡“ áࠧ㠯®á«¥ á¡à®á  ¬ è¨­ë ¯® ª« ¢¨è ¬ Ctrl+Alt+Del.
+        Žá⠢訥áï 3 ¯®àâ  áâà ­¨æ ¯ ¬ï⨠®áâ îâáï ­  ¤ ­­ë© ¬®¬¥­â ¢ १¥à¢¥.
+‘奬  à á¯à¥¤¥«¥­¨ï ¯ ¬ï⨠¯®§¢®«ï¥â ¯®¤ª«îç¨âì ¢  ¤à¥á­®¥ ¯à®áâà ­á⢮
+¯à®æ¥áá®à  ­¥ ⮫쪮 Ž‡“ ¨«¨ �‡“, ­® ¨ ¯®àâë ¨ ¯ ¬ïâì ISA ª àâ, ¢áâ ¢«ï¥¬ëå
+¢ á«®â.
+        �ਠ¯®¤ª«î祭¨¨ ¢  ¤à¥á  #C000..#FFFF ᪮௨®­®¢áª¨å à áè¨à¥­­ëå
+áâà ­¨æ Ž‡“, ­  ¨å ¬¥áâ® ¬®¦­® ¯¥à¥ ¤à¥á®¢ âì á«®âë. „«ï í⮣® ­ ¤® ¯à®áâ®
+§ ¯¨á âì ¢ ¯®àâ ®¤­®© ¨§ íâ¨å áâà ­¨æ §­ ç¥­¨¥, ᮮ⢥âáâ¢ãî饥 ISA-á«®âã,
+ª ª®â®à®¬ã ­¥®¡å®¤¨¬® ¯à®¨§¢¥á⨠®¡à é¥­¨¥. �â® §­ ç¥­¨¥ â ª ¦¥ 㪠§ë¢ ¥â
+ª 祬㠢¥¤¥âáï ®¡à é¥­¨¥, ª ¯®àâ ¬ ¨«¨ ¯ ¬ïâ¨.
+
+
+                ‘奬  à á¯à¥¤¥«¥­¨ï ¯ ¬ï⨠Sprinter- .
+
+  €¤à¥á­®¥ ¯à®áâà ­á⢮       ‘âà ­¨ç­ë¥ ¯®àâë             �‡“ ª®¬¯ìîâ¥à 
+  ¯à®æ¥áá®à                  ¯®¤ª«îç ¥¬ëå áâà ­¨æ          áâà ­¨æë ¯® 16k
+ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿  ÚÄÄÄÄÄÄÄ¿   ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿            ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
+ ³ #0000..#3FFF ÃÄ>´ ¯®àâë ÃÄÄ>´ ROM_BASIC    ÃÄÄ>ÂÄÄÂÄÄÂÄ>´ EXPANSION    ³
+ ³              ³  ³ #7FFD,³   ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´   ³  ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³              ³  ³ #1FFD ÃÄ¿ ³ ROM_TR-DOS   ÃÄÄ>´  ³  ÃÄ>´ TR-DOS       ³
+ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´  ÀÄÄÄÄÄÄÄÙ ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´   ³  ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³ #4000..#7FFF ÃÄÄÄÄÄÄÄÄÄÄ¿ ³ ³              ³   ³  ³  ÃÄ>´ BASIC128     ³
+ ³              ³          ³ ³ ÃÄ Ä Ä Ä Ä Ä Ä ´   ³  ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³              ³          ³ ³ ³ ROM_SYSTEM   ÃÄÄ>Ù  ³  ÃÄ>´ BASIC48      ³
+ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´          ³ ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´      ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³ #8000..#BFFF ÃÄÄÄÄ¿     ³ À>´ RAM_0000     ÃÄÄÄ>¿ ³  ÃÄ>´ SYSTEM ROM   ³
+ ³              ³    ³     ³   ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ    ³ ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³              ³    ³     ³   ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿    ³ ³  ÃÄ>´ SYSTEM ROM2  ³
+ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´    ³     ÀÄÄ>´ RAM_4000     ÃÄÄÄ>´ ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³ #C000..#FFFF ÿ   ³         ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ    ³ ³  ÃÄ>´ CONFIG 2     ³
+ ³              ³³   ³                             ³ ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+ ³              ³³   ³         ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿    ³ ³  ÀÄ>´ CONFIG 1     ³
+ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ³   ÀÄÄÄÄÄÄÄÄ>´ RAM_8000     ÃÄÄÄ>´ ³     ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
+                 ³             ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ    ³ ³
+                 ³                                 ³ ³      Ž‡“ ª®¬¯ìîâ¥à 
+                 ³ ÚÄÄÄÄÄÄÄ¿   ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿    ³ ³     áâà ­¨æë ¯® 16k
+                 ³ ³ �®àâë ÃÄÄ>´ RAM_0        ÃÄÄÄ>´ ³     ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
+                 ³ ³ #7FFD,³   ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´    ÃÄÄÄ>ÂÄ>´ RAM_00       ³
+                 À>´ #1FFD ÃÄÄ>´              ÃÄÄÄ>´ ³  ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+                   ³       ³   ÃÄ Ä Ä Ä Ä Ä Ä ³    ³ ³  ÃÄ>´ RAM_01       ³
+                   ³       ÃÄÄ>´ RAM_7        ÃÄÄÄ>´ ÀÄ>´  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+                   ³       ³   ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´    ³    ³  ³              ³
+                   ³       ÃÄÄ>´ RAM_8        ÃÄ>ÂijÄÄÄ>´  ÃÄ Ä Ä Ä Ä Ä Ä ´
+                   ³       ³   ÃÄ Ä Ä Ä Ä Ä Ä ´  ³ ³    ÀÄÄ´ RAM_7F       ³
+                   ³       ÃÄÄ>´              ÃÄ>´ ³       ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+                   ³       ³   ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´  ³ ÀÄÄÄ>ÂÄ>´ RAM_80       ³
+                   ³       ÃÄÄ>´ RAM_F        ÃÄ>ÁÄ>¿   ³  ÃÄ Ä Ä Ä Ä Ä Ä ´
+                   ÀÄÄÄÄÄÄÄÙ   ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ     ³   ³  ³              ³
+                              ‚­¥è­¨¥ ãáâனá⢠    ³   ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+      ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿     ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿     ³   ÃÄ>´ RAM_FE       ³
+             �®àâë       ÃÄÄÄÄ>´ ISA_1        Ã<ÄÄÄÄ´   ³  ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
+             ª®¬¯ìîâ¥à   ³     ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´     ³   ÀÄ>´ RAM_FF       ³
+                         ÃÄÄÄÄ>´ ISA_2        Ã<ÄÄÄÄ´      ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
+                         ³     ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´     ³
+                         ÃÄÄÄÄ>´ HDD          Ã<ÄÄÄÄ´
+                         ³     ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´     ³
+                         ÃÄÄÄÄ>´ OVER DEVICES Ã<ÄÄÄÄÙ
+      ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ     ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
+
+                                �¨áã­®ª 2.
+
+
+
+        ‚ ¤àã£¨å ª®­ä¨£ãà æ¨ïå á奬  à á¯à¥¤¥«¥­¨ï ¯ ¬ï⨠ã¯à®é ¥âáï ¤«ï
+®á¢®¡®¦¤¥­¨ï à¥áãàᮢ ��‹Œ. Œ®£ãâ ®âáãâá⢮¢ âì ¯®àâë #1FFD ¨ #7FFD,   â ª
+¦¥ ã¯à®é ¥âáï á奬  à ¡®âë á ãáâனá⢠¬¨, ®â®¡à ¦ ¥¬ë¬¨ ­  ¯ ¬ïâì.
+
+
+        ‘奬  à á¯à¥¤¥«¥­¨ï ¯®à⮢.
+
+        Sprinter ¨¬¥¥â ¤¢¥ ®¡®á®¡«¥­­ë¥ £àã¯¯ë ¯®à⮢. �¥à¢ ï £à㯯 , íâ®
+¢­ãâ७­¨¥ ¯®àâë ¯à®æ¥áá®à  Z84C15, ¢â®à ï - ¢­¥è­¨¥ ¯®àâë. €¤à¥á æ¨ï
+¯®à⮢ ¯¥à¢®© £àã¯¯ë ­¥ ¬®¦¥â ¡ëâì ¨§¬¥­¥­ , â ª ª ª í⨠¯®àâë ­  ®¤­®¬
+ªà¨áâ ««¥ á ¯à®æ¥áá®à®¬. ‚â®à ï £à㯯  ¯®£ª«îç ¥âáï ç¥à¥§ ��‹Œ ¨ ¨å  ¤à¥á 
+¬®£ãâ ¨§¬¥­ïâìáï ª ª 㣮¤­®, á ¥¤¨­á⢥­­ë¬ ãá«®¢¨¥¬, ­¥¯¥à¥á¥ç¥­¨ï á
+ ¤à¥á ¬¨ ¯¥à¢®© £à㯯ë.
+        Ž ⮬ ª ª¨¥ ¯®àâë ¨¬¥îâáï ­  ªà¨áâ ««¥ Z84C15 ¬®¦­® ¯à®ç¨â âì ¢
+¤®ªã¬¥­â æ¨¨ ¯® í⮬㠯à®æ¥áá®àã ¨ §¤¥áì ï 㯮¬ï­ã ­¥ª®â®àë¥ ¨§ ­¨å. Ž¤¨­
+¨§ ¯®á«¥¤®¢ â¥«ì­ëå ¯®à⮢ ¨á¯®«ì§ã¥âáï ¤«ï ¢¢®¤  ¤ ­­ëå á  ªâ¨¢­®© ¬ëè¨.
+Ž¤¨­ ¨§ ¯ à ««¥«ì­ëå ¨á¯®«ì§ã¥âáï ¤«ï ¢ë¢®¤  ¤ ­­ëå, ­  ¢â®à®© ¯ à ««¥«ì­ë©
+¯®àâ § ¢¥¤¥­ë ᨣ­ «ë ¯à¥à뢠­¨© ¨ § ¯à®á®¢ ¯àאַ£® ¤®áâ㯠 ᮠ᫮⮢ ISA.
+� à ««¥«ì­ë© ¯®àâ ¯à®æ¥áá®à  Z84C15 ãáâ஥­ â ª¨¬ ®¡à §®¬, çâ® ­  ­¥¬
+¢®§¬®¦­  ®à£ ­¨§ æ¨ï ¯à¥à뢠­¨© ¯® ᨣ­ « ¬ ¯à¨å®¤ï騬 ç¥à¥§ ¯ à ««¥«ì­ë©
+¯®àâ. ” ªâ¨ç¥áª¨ ¢â®à®© ¯ à ««¥«ì­ë© ¯®à⠨ᯮ«ì§ã¥âáï ª ª ª®­â஫«¥à
+¯à¥à뢠­¨©.
+        ‘奬  à á¯à¥¤¥«¥­¨ï ¯®à⮢ ¢â®à®© £àã¯¯ë ¨¬¥¥â á¢®î ®á®¡¥­­®áâì.
+ƒ« ¢­®© ¨¤¥¥© ¡ë«® ¯®«ã祭¨¥ ¢®§¬®¦­®á⨠¡ëáà® ¨§¬¥­ïâì ª®­ä¨£ãà æ¨î ¯®à⮢
+¡¥§ ¯¥à¥£à㧪¨ ��‹Œ. �â® ¤®á⨣­ãâ® ¯ã⥬ ¯à¨¬¥­¥­¨ï ª àâë à á¯à¥¤¥«¥­¨ï
+¯®à⮢, à á¯®« £ î饩áï ­  ᯥ樠«ì­®© áâà ­¨æ¥ Ž‡“.
+        �ਠ¯®ï¢«¥­¨¨ 横«  ®¡à é¥­¨ï ª ¯®àâã á­ ç «  ¯à®¨á室¨â ®¡à é¥­¨¥
+ª Ž‡“ ª àâë ¯®à⮢. ‚ ª à⥠¯®à⮢ § ¯¨á ­® ª ª®© ¨¬¥­­® ¯®àâ ¯®¤ª«î祭 ª
+¤ ­­®¬ã  ¤à¥áã. „ «¥¥ ¯à®¨á室¨â ¢­ãâ७­ïï ¤¥è¨äà æ¨ï ¯® ¡ ©âã ¨§ ª àâë
+¯®à⮢ ¨ ®¡à é¥­¨¥ ª ¢ë¡à ­­®¬ã ¯®àâã. ‚ ०¨¬¥ ­¥âãà¡® íâ® ¯à®¨á室¨â ¡¥§
+ª ª¨å «¨¡® § ¤¥à¦¥ª,   ¢ ०¨¬¥ âãà¡® ¯à®æ¥áá®àã ¢ëáâ ¢«ï¥âáï ᨣ­ « WAIT ¢
+§ ¢¨á¨¬®á⨠®â ­¥®¡å®¤¨¬®© ¤«¨­ë 横«  ®¡à é¥­¨ï ª ¯®àâã.
+        „«ï ¯®¤ª«î祭¨ï ª ª ª®¬ã «¨¡®  ¤à¥áã ¨«¨ ®âª«î祭¨ï ®â ­¥£® ª ª®£®
+«¨¡® ¯®àâ  ¤®áâ â®ç­® ®âªàëâì ª àâã ¯®à⮢ ¨ ¢¯¨á âì ¢ ­ã¦­®¥ ¬¥áâ® ®¤¨­
+¡ ©â.
+        ‚ áâà ­¨æ¥ ª àâë ¯®à⮢ ᮤ¥à¦¨âáï ç¥âëॠª àâë, ª®â®àë¥ ¬®£ãâ
+¯¥à¥ª«îç âìáï ç¥à¥§ á¨á⥬­ë© ¯®àâ. ’ ª¨¬ ®¡à §®¬ ¬®¦­® ®áãé¥á⢨âì ¡ëáâ஥
+¯¥à¥ª«î祭¨¥ ª®­ä¨£ãà æ¨¨ ¯®à⮢, çâ® ¬®¦¥â ¡ëâì ¯®«¥§­® ¯à¨ à ¡®â¥
+Spectrum-®¢áª¨å ¯à®£à ¬¬ ᮢ¬¥áâ­® á® Sprinter-®¢áª¨¬ ¡¨®á®¬.
+
+
+        Š®­ªà¥â­ë¥  ¤à¥á  ¯®à⮢, ¨á¯®«ì§ã¥¬ë¥ ¢ Sprinter-¥.
+
+        ‡¤¥áì ï ¯à¨¢¥¤ã  ¤à¥á æ¨î ¯®à⮢ ¤«ï ª®­ä¨£ãà æ¨© Sprinter-1 ¨
+Sprinter-2. ‘ࠧ㠮⬥çã, çâ® í⨠ ¤à¥á  «¥£ª® ¬®£ãâ ¡ëâì ¨§¬¥­¥­ë ¯à®á⮩
+¯à®£à ¬¬®©, ¢ á«ãç ¥ ¯®ï¢«¥­¨ï â ª®© ­¥®¡å®¤¨¬®áâ¨.
+
+
+        ‘â ­¤ àâ­ë¥ ¯®àâë.
+
+        #FE - RD_KBD - ¯®àâ ª« ¢¨ âãàë
+        #FE - WR_BRD - ¯®àâ ¡®à¤îà 
+        #7FFD - ¯®àâ à áè¨à¥­¨ï ZX-Spectrum 128k
+        #1FFD - ¯®àâ à áè¨à¥­¨ï Scorpion ZS-256
+        #1F,#0F - RD_KEMPS - ¯®àâ ¤¦®©á⨪ . ‚ ª®­ä¨£ãà æ¨¨ Sprinter-1 ¯®àâ
+                #1F  ¯¯ à â­® ¯¥à¥ ¤à¥áã¥âáï ­  ¯®àâ #0F
+        #BFFD,#FFFD - AY-PORTS - ¯®àâë AY-ᮯà®æ¥áá®à  (ZX-Spectrum-256/AY)
+
+        �¥ ᮢᥬ áâ ­¤ àâ­ë¥ ¯®àâë.
+
+        #FB,#4F - ¯®àâ COVOX- .
+
+
+        „®¯®«­¨â¥«ì­ë¥ 8-¡¨â­ë¥ ¯®àâë Sprinter- .
+
+        #82 - PAGE0 - áâà ­¨æ  Ž‡“, ¯®¤ª«îç ¥¬ ï ¢¬¥áâ® �‡“ ç¥à¥§ ¯®àâ #1FFD
+        #A2 - PAGE1 - áâà ­¨æ  Ž‡“, ¯®¤ª«î祭­ ï ¯®  ¤à¥áã #4000
+        #C2 - PAGE2 - áâà ­¨æ  Ž‡“, ¯®¤ª«î祭­ ï ¯®  ¤à¥áã #8000
+        #E2 - PAGE2 - áâà ­¨æ  Ž‡“, ¯®¤ª«î祭­ ï ¯®  ¤à¥áã #C000
+        ‡¤¥áì ­ ¤® ®â¬¥â¨âì ®á®¡®, ç¥à¥§ ¯®àâ #E2 ¬®¦­® ¨§¬¥­¨âì «î¡ãî ¨§
+        16-⨠áâà ­¨æ ᪮௨®­®¢áª®£® à á¯à¥¤¥«¥­¨ï ¯ ¬ïâ¨.
+        #89 - PORT_Y - ¢¥à⨪ «ì­ ï ª®®à¤¨­ â  â®çª¨ ­  £à ä¨ç¥áª®¬ íªà ­¥
+        ¨«¨ áâà ­¨æ  VIDEO-RAM ¤«ï ᯥªâà㬮¢áª®£® ०¨¬ 
+        #C9 - RGMOD - ¯®àâ ०¨¬  íªà ­ . �¥à¥ª«îç ¥â áâà ­¨æë ०¨¬  íªà ­ .
+        #3C,#7C - SYS_PORT - á¨á⥬­ë© ¯®àâ âண âì ­¥ ४®¬¥­¤ã¥âáï
+
+        #10..#1F,#EE,#EF,#F0,#F1,#F4  - ¢­ãâ७­¨¥ ¯®àâë Z84C15
+
+        �®àâë áâà ­¨æ Ž‡“ ®âªàëâë ª ª ­  § ¯¨áì, â ª ¨ ­  ç⥭¨¥. �â®
+¯®§¢®«ï¥â «¥£ª® ¢ë¯®«­ïâì ¯à®£à ¬¬ë, ¨á¯®«ì§ãî騥 ¯¥à¥ª«î祭¨¥ áâà ­¨æ,  
+§ â¥¬ ¢®§¢à é âì í⨠áâà ­¨æë ­ § ¤. �ਠࠡ®â¥ BIOS-  ¢á¥ áâà ­¨æë
+á®åà ­ïîâáï.
+
+
+        „®¯®«­¨â¥«ì­ë¥ 16-⨡¨â­ë¥ ¯®àâë Sprinter- .
+
+        #xx50..#xx55 - ¯®àâë HDD - ¨á¯®«ì§®¢ âì ¢­¥è­¨¬¨ ¯à®£à ¬¬ ¬¨ ­¥
+        ४®¬¥­¤ã¥âáï. ”㭪樨 à ¡®âë á HDD § ¯¨á ­ë ¢ �‡“.
+
+
+        ‘ªàëâë¥ ¯®àâë Sprinter- .
+
+        ‘ªàëâ묨 ïîâáï ¯®àâë ª®â®àë¥ ­¤®áâã¯­ë ¢ ª®­ªà¥â­ë© ¬®¬¥­â
+¢à¥¬¥­¨, ­® ¬®£ãâ áâ âì ¤®áâ㯭묨 ¯®á«¥ ¯à®¢¥¤¥­¨ï ¨§¬¥­¥­¨© ¢ ª à⥠¯®à⮢.
+ˆå  ¤à¥á  ­¥ 㪠§ë¢ îâáï, â ª ª ª ®­¨ ¬®£ãâ ¡ëâì ¢ëáâ ¢«¥­ë ¢ «î¡®¥ ¬¥áâ®.
+
+        �®àâ �‡“ BASIC48
+        �®àâ �‡“ BASIC128
+        �®àâ �‡“ TR-DOS
+        �®àâ �‡“ EXPANSION
+        �®àâ �‡“ SYSTEM
+
+        —¥à¥§ í⨠¯®àâë ¬®¦­® ãáâ ­®¢¨âì ­®¢ë¥ ¯à®è¨¢ª¨ �‡“. „«ï í⮣® ¨å
+¤®áâ â®ç­® § ¯¨á âì ¢ Ž‡“ á ­®¬¥à ¬¨ áâà ­¨æ ¬¥­ìè¥ #80 ¨ § ¯¨á âì ¢
+ᮮ⢥âáâ¢ãî騩 ¯®àâ ­®¬¥à í⮩ áâà ­¨æë. �ਠ⠪®¬ ¯®¤ª«î祭¨¨ áâà ­¨æë
+�⨠áâà ­¨æë ¡ã¤ãâ § é¨é¥­ë ®â § ¯¨á¨.
+        — áâ¨ç­® áªàëâ묨, â ª ¦¥ ïîâáï ¨ ¯®àâë #7FFD,#1FFD ¢ ®¡ëç­®¬
+á®áâ®ï­¨¨ ®­¨ ¤®áâ㯭ë ⮫쪮 ­  § ¯¨áì, ­® §­ ç¥­¨ï, § ¯¨á뢠¥¬ë¥ ¢ íâ¨
+¯®àâë ¬®¦­® ¯à®ç¨â âì, ®âªàë¢ á®®â¢¥âáâ¢ãî騥 ¯®àâë ­  ç⥭¨¥.
+        ‚ ¤àã£¨å ª®­ä¨£ãà æ¨ïå ¬®¦¥â ®âáãâá⢮¢ âì ç áâì ¯®à⮢ ¨«¨
+¯à¨áãâá⢮¢ âì ­®¢ë¥ ¯®àâë.
+
+
+        Žà£ ­¨§ æ¨ï ¢¨¤¥®¯ ¬ï⨠¨ ¢¨¤¥®à¥¦¨¬®¢.
+
+        ‚¨¤¥®-Ž‡“ Sprinter-  á®áâ ¢«ï¥â 256 ª¨«®¡ ©â. ‚ ¤ «ì­¥©è¥¬
+¯à¥¤¯®« £ ¥âáï ¥£® à áè¨à¥­¨¥ ¤® 512 ª¨«®¡ ©â, ¤«ï ¯®«ã祭¨ï ¡®«¥¥
+¢ë᮪¨å ०¨¬®¢ à §à¥è¥­¨ï.
+        ‚ ०¨¬¥ Spectrum-®¢áª®£® íªà ­  ¢áï ®à£ ­¨§ æ¨ï â ª ï ¦¥ ª ª ¢
+áâ ­¤ àâ­®¬ ZX-Spectrum. ‚ ®áâ «ì­ëå ०¨¬ å ¢ª«îç ¥âáï Sprinter-®¢áª¨©
+íªà ­, áâàãªâãà  ª®â®à®£® ¢ª«î砥⠢ á¥¡ï ‘¯¥ªâà㬮¢áª¨© íªà ­ ª ª ç áâì
+á奬ë.
+
+        “áâனá⢮ íªà ­ .
+
+        ‚¥áì íªà ­ à §¡¨â ­  ª¢ ¤à âë, à §¬¥à®¬ ¢ áâ ­¤ àâ­®¥
+‘¯¥ªâà㬮¢áª®¥ §­ ª®¬¥áâ®. „«ï ª ¦¤®£® ª¢ ¤à â  ãáâ ­ ¢«¨¢ ¥âáï ᢮©
+ᮡá⢥­­ë© ०¨¬ ¢ë¢®¤ ,   â ª ¦¥  ¤à¥á ¢¨¤¥®-Ž‡“, ®âªã¤  ¯à®¨§¢®¤¨âáï
+¢ë¢®¤ ¢ íâ®â ª¢ ¤à â.
+        ‚ ª ¦¤®¬ §­ ª®¬¥á⥠¬®¦¥â ¡ëâì § ¤ ­ ᢮© ᮡá⢥­­ë© ०¨¬ ¢ë¢®¤ .
+‚ ¤ ­­ë© ¬®¬¥­â ¬®¦­® ãáâ ­ ¢«¨¢ âì â ª¨¥ ०¨¬ë:
+        ZX-40 - ®¡ëç­ë© ᯥªâà㬮¢áª¨© ०¨¬ á ®¤­¨¬ ¡¨â¯« ­®¬ ¨
+®¤­¨¬  âਡã⮬ ­  §­ ª®¬¥áâ®.
+        ZX-80 - �¥¦¨¬, ¯®å®¦¨© ­  ᯥªâà㬮¢áª¨© ¯® áâ஥­¨î
+ᨬ¢®«®¢, ­® ¢ ª ¦¤®¬ §­ ª®¬¥á⥠®ª §ë¢ ¥âáï ¤¢  ᨬ¢®« , ᦠâë¥ ¯®
+£®à¨§®­â «¨.
+        G256-8 - ƒà ä¨ç¥áª¨© ०¨¬. Š¢ ¤à â ¯à¥¤áâ ¢«ï¥â ᮡ®© ¬ áᨢ 8x8
+â®ç¥ª. ‚ ª ¦¤®© â®çª¥ § ¤ ¥âáï ®¤¨­ ¨§ 256-⨠梥⮢, ¢ë¡¨à ¥¬ëå ¨§ ¯ «¨âàë
+16 ¬¨««¨®­®¢ 梥⮢. Š¢ ¤à âë ¬®£ãâ ¨¬¥âì à §­ë¥ ¯ «¨âàë. ’ ª¨å ¯ «¨âà ¤«ï
+०¨¬  G256-8 - ç¥âëà¥.
+        G16-16 - ƒà ä¨ç¥áª¨© ०¨¬. Š¢ ¤à â ¯à¥¤áâ ¢«ï¥â ᮡ®© ¬ áᨢ
+16x8 â®ç¥ª. Š ¦¤ ï â®çª  ¨¬¥¥â ®¤¨­ ¨§ 16 梥⮢, ¢ë¡¨à ¥¬ëå ¨§ ¯ «¨âàë 16
+¬¨««¨®­®¢ 梥⮢. ’ ª ¦¥, ª ª ¨ G256-8 ¢ ª¢ ¤à â¥ ¬®¦¥â ¡ëâì ãáâ ­®¢«¥­ 
+®¤­  ¨§ 4-å ¯ «¨âà. � «¨âàë £à ä¨ç¥áª¨å ०¨¬®¢ ¯¥à¥á¥ª îâáï ¤àã£ á ¤à㣮¬.
+� «¨âà  16-â¨æ¢¥â­®£® ०¨¬  íâ® ¯¥à¢ë¥ 16 梥⮢ ¨§ ¯ «¨âàë 256-â¨æ¢¥â­®£®.
+        BORDER - ‚ ª¢ ¤à â ¢ë¢®¤¨âáï 梥⠡®à¤¥à .
+        BLANK - Š¢ ¤à â £ á¨âáï - áâ ­®¢¨âáï ç¥à­ë¬.
+
+        Ž¡ê¥¬ ¤ ­­ëå ०¨¬  ª¢ ¤à â  á®áâ ¢«ï¥â 2 ¡ ©â ,
+¯®í⮬㠨§¬¥­¥­¨¥ ०¨¬  ¢á¥£® íªà ­  ᢮¤¨âáï ª ¯¥à¥§ ¯¨á¨ 2.5 ª¨«®¡ ©â
+¤ ­­ëå ¢ ¢¨¤¥®-Ž‡“.
+        �®¤®¡­ ï áâàãªâãà  íªà ­  ¯®§¢®«ï¥â «¥£ª® ¯à®¨§¢®¤¨âì áªà®««¨­£¨
+ª ª ¢á¥£®, â ª ¨ ç á⥩ íªà ­  ¯® §­ ª®¬¥áâ ¬.
+
+        �¥¦¨¬ íªà ­  ãáâ ­ ¢«¨¢ ¥âáï ¯à¨ ¢ª«î祭¨¨,   â ª ¦¥ á ¯®¬®éìî
+ä㭪権 ¡¨®á . ”㭪樨 ¡¨®á  ¯®§¢®«ïîâ ®âªà뢠âì ­  íªà ­¥ £à ä¨ç¥áª¨¥ ¨
+⥪áâ®¢ë¥ ®ª­  ¢ ­ã¦­ëå ¬¥áâ å ¨ ­ã¦­®£® à §¬¥à .
+
+        ‚ ¡¨®á¥ ¨¬¥îâáï ä㭪樨 ®âªàëâ¨ï £à ä¨ç¥áª®£® íªà ­  ­  ¢¥áì íªà ­
+320x256 â®ç¥ª. �®á«¥ ®âªàëâ¨ï í⮣® ०¨¬  íªà ­ ¯à¥¤áâ ¢«ï¥â ᮡ®©.
+­ ¡®à ¨§ 256-⨠«¨­¨©, ¤«¨­®© ¯® 320 ¡ ©â. ‘®á¥¤­¨¥ â®çª¨ ¢ «¨­¨¨ - íâ®
+á®á¥¤­¨¥ ¡ ©âë. �¥à¥ª«î祭¨¥ «¨­¨© ¯à®¨§¢®¤¨âáï ç¥à¥§ PORT_Y, ¢ ª®â®à®¬
+ãáâ ­ ¢«¨¢ ¥âáï ­®¬¥à «¨­¨¨, ¢ë¢®¤¨¬®© ­  íªà ­. �®¬¥à  «¨­¨© áç¨â îâáï
+ᢥàåã íªà ­ , ­ ç¨­ ï á ­ã«¥¢®©.
+        „«ï ¢ë¢®¤  ¢ £à ä¨ç¥áª¨© íªà ­ â ª ¦¥ âॡã¥âáï ®âªàëâì
+ᮮ⢥âáâ¢ãîéãî áâà ­¨æ㠮᭮¢­®£® Ž‡“. ‚ í⮩ áâà ­¨æ¥ ¡ã¤¥â ᮤ¥à¦ âìáï
+ª®¯¨ï ¢¨¤¥®¨§®¡à ¦¥­¨ï.
+        ‚¨¤¥®-Ž‡“ ï¥âáï ⥭¥¢ë¬ Ž‡“, ¯®í⮬㠨­ä®à¬ æ¨ï, ­ å®¤ïé ïáï ¢
+®á­®¢­®¬ Ž‡“, ¯®¤ ª®â®àë¬ ­ å®¤¨âáï ¢¨¤¥®-Ž‡“ ­¥ ®¡ï§ â¥«ì­® ¡ã¤¥â
+ᮢ¯ ¤ âì á ¨­ä®à¬ æ¨¥©, ­ å®¤ï饩áï ¢ í⮬ ¢¨¤¥®-Ž‡“. ‡ ¯¨áì ¢¨¤¥®-¤ ­­ëå
+¬®¦¥â ¯à®¨§¢®¤¨âìáï ¨ ¡¥§ ¯¥à¥§ ¯¨á¨ ¤ ­­ëå ¢ ®á­¢­®¬ Ž‡“, çâ® ®ª §ë¢ ¥âáï
+¯®«¥§­ë¬ ¯à¨ à ¡®â¥, ­ ¯à¨¬¥à, á® á¯à ©â ¬¨. „«ï à ¡®âë á® á¯à ©â ¬¨ â ª ¦¥
+¯à¥¤ãᬮâ७ ०¨¬ § ¯¨á¨ ¢ ¢¨¤¥®-Ž‡“ á ¯à®§à ç­ë¬ 梥⮬. ‚ í⮬ ०¨¬¥
+¨­ä®à¬ æ¨ï, ¯¥à¥¤ ¢ ¥¬ ï ¢ ¢¨¤¥®-Ž‡“ ¯à®¢¥àï¥âáï ­  ­ «¨ç¨¥ ¡ ©â  #FF. …᫨
+íâ®â ¡ ©â ®¡­ à㦨¢ ¥âáï, ⮠横« § ¯¨á¨ ¯à®¯ã᪠¥âáï ¨ ­  íªà ­¥ ¢ í⮬
+¬¥á⥠®áâ ¥âáï ⥠¤ ­­ë¥, ª ª¨¥ ¡ë«¨ à ­¥¥. ’ ª¨¬ ®¡à §®¬ ­  íªà ­¥ ¬®¦­®
+¡ëáâà® ¯à®à¨á®¢ë¢ âì á¯à ©âë, ¯à¥¤áâ ¢«ïî騥 ¨§ á¥¡ï ¯àאַ㣮«ì­ë¥ ª à⨭ª¨
+á "¯à®§à ç­ë¬¨" 梥⠬¨.
+
+        �ਬ¥à ¯à®£à ¬¬ë ¢ë¢®¤  ¯àאַ㣮«ì­®© ª à⨭ª¨ ­  íªà ­:
+
+PAGE3   EQU #E2
+RGADR   EQU #89
+
+        LD A,#50        ; áâà ­¨æ  £à ä¨ç¥áª®£® ¢¨¤¥®íªà ­ 
+        OUT (PAGE3),A   ; ãáâ ­®¢¨âì ¢ PAGE3
+        LD HL,Pucture   ;  ¤à¥á ª à⨭ª¨ (�àï¬ë¥ „ ­­ë¥)
+        LD DE,#C040+HorPlace  ; ¯®«®¦¥­¨¥ ª à⨭ª¨ ­  íªà ­¥ ¯® £®à¨§®­â «¨
+        LD A,VerPlace   ; ¯®«®¦¥­¨¥ ª à⨭ª¨ ­  íªà ­¥ ¯® ¢¥à⨪ «¨
+        OUT (RGADR),A
+        LD B,VerSize    ; ¢ëá®â  ª à⨭ª¨
+LOOP:   PUSH DE         ; § ¯®¬­¨âì ¯®«®¦¥­¨¥ ­  «¨­¨¨
+        PUSH BC         ; § ¯®¬­¨âì áç¥â稪 ¢ëá®âë
+        LD BC,HorSize   ; ¤«¨­  ª à⨭ª¨
+        LDIR            ; ª®¯¨à®¢ âì «¨­¨î
+        POP BC
+        POP DE
+        INC A           ; á«¥¤ãîé ï ª®®à¤¨­ â  ¯® Y
+        OUT (RGADR),A
+        DJNZ LOOP       ; ¯®¢â®àïâì ­ã¦­®¥ ª®«¨ç¥á⢮ à §
+
+        “¯à ¢«¥­¨¥ ०¨¬®¬ ¢ë¢®¤  ­  íªà ­ (¢ª«î祭¨¥ ¢ë¢®¤  á ¯à®§à ç­ë¬¨
+梥⠬¨, ®âª«î祭¨¥ ª®¯¨à®¢ ­¨ï ¢ ®á­®¢­®¥ Ž‡“) ®áãé¥á⢫ï¥âáï ç¥à¥§
+¬« ¤è¨¥ ¡¨âë ¯®àâ  áâà ­¨æë £à ä¨ç¥áª®£® íªà ­ .
+
+
+        €ªá¥«¥à â®à ®¯¥à æ¨© á Ž‡“.
+
+        €ªá¥«¥à â®à ®¯¥à æ¨© á Ž‡“ ¯à¥¤­ §­ ç¥­ ¤«ï ã᪮७¨ï ®¯¥à æ¨©
+¯® ¯¥à¥á뫪¥ ¤ ­­ëå ¨«¨ ¯® § ¯®«­¥­¨î Ž‡“ ®¤­¨¬ ¡ ©â®¬. €ªá¥«¥à â®à
+¯à¨áãâáâ¢ã¥â ¢ ç¨áâ® Sprinter-®¢áª¨å ª®­ä¨£ãà æ¨ïå ¨ ¯®í⮬㠭¨ª ª ­¥
+¬¥è ¥â à ¡®â¥ ®¡ëç­ëå Spectrum-®¢áª¨å ¯à®£à ¬¬.
+        Žá­®¢®©  ªá¥«¥à â®à  ï¥âáï ¡ëáâ஥ ¢­ãâ७­¥¥ Ž‡“ ¢ ��‹Œ.
+Ž¯¥à æ¨¨ ¯® ¯¥à¥á뫪¥ ¤ ­­ëå ¯à®¨§¢®¤ïâáï ¯ã⥬ § ¯¨á¨ ¡«®ª  ¤ ­­ëå ¢ íâ®
+¢­ãâ७­¥¥ Ž‡“,   § â¥¬ ª®¯¨à®¢ ­¨¨ ¥£® ¢ ­ã¦­®¥ ¬¥áâ® ¯ ¬ï⨠¨§ í⮣® Ž‡“.
+�®á«¥ ®¤­®© § ¯¨á¨ ª®¯¨à®¢ ­¨¥ ¬®¦¥â ¯à®¨§¢®¤¨âìáï ­¥áª®«ìª® à § ¨ â ª¨¬
+®¡à §®¬ ¬®¦­® ¯à®¨§¢®¤¨âì § ¯®«­¥­¨¥ íªà ­  ⥪áâãà ¬¨.
+        „«ï § ¯®«­¥­¨ï íªà ­  ®¤­¨¬ 梥⮬ ¨á¯®«ì§ã¥âáï ¤à㣮© ०¨¬
+ ªá¥«¥à â®à . ‚ ­¥¬ ¢¬¥áâ® ª®¯¨à㥬®£® ¡«®ª  ¤ ­­ëå ¨§ ¢­ãâ७­¥£® Ž‡“
+¯à®¨§¢®¤¨âáï § ¯¨áì ¤ ­­ëå á è¨­ë ¯à®æ¥áá®à , ª®â®àë¥ ¢ íâ®â ¬®¬¥­â ­¥
+¨§¬¥­ïîâáï.
+        �«®ª ¤ ­­ëå, § ¯¨á뢠¥¬ë© ¢ Ž‡“  ªá¥«¥à â®à  ¬®¦¥â ¨¬¥âì à §«¨ç­ãî
+¤«¨­­ã ¨§ ¤¨ ¯ §®­  1..256 ¡ ©â.
+        “¯à ¢«¥­¨¥  ªá¥«¥à â®à®¬ ¯à®¨§¢®¤¨âáï ­¥¯®á।á⢥­­® ¨§ ¯à®£à ¬¬ë.
+„«ï í⮣® ¨§¯®«ì§ãîâáï ª®¬ ­¤ë ¯à®æ¥áá®à , ª®â®àë¥ ä ªâ¨ç¥áª¨ ïîâáï
+®¯¥à æ¨ï¬¨ ⨯  NOP.
+        �â® ª®¬ ­¤ë LD A,A; LD B,B; LD C,C; LD D,D; LD E,E; LD H,H, LD L,L
+        � §­ ç¥­¨¥ ª®¬ ­¤ á«¥¤ãî饥:
+        LD B,B - ¢ëª«îç¨âì  ªá¥«¥â à®à.
+        LD D,D - ¢ª«îç¨âì  ªá¥«¥à â®à ¢ ०¨¬ ¯à¨¥¬  ¡ ©â  à §¬¥à  ¡«®ª 
+                ¤ «¥¥ á«¥¤ã¥â ª®¬ ­¤  ⨯  LD A,dat, £¤¥ dat ¨ ¡ã¤¥â ­®¢ë¬
+                à §¬¥à®¬ ¡«®ª . …᫨ à §¬¥à ¡«®ª  ¡ë« ãáâ ­®¢«¥­ à ­¥¥,
+                ¥£® ¬®¦­® ­¥ ãáâ ­ ¢«¨¢ âì.
+        LD C,C - Ž¯¥à æ¨ï Fill - § ¯®«­¥­¨¥ ®¤­¨¬ ¡ ©â®¬. �®á«¥¤ãîé ï
+                ª®¬ ­¤  ⨯  LD (HL),A ¯à¨¢¥¤¥â ª § ¯®«­¥­¨î 㪠§ ­­®£®
+                à ­¥¥ ª®«¨ç¥á⢠ ¡ ©â §­ ç¥­¨¥¬ A
+        LD E,E - Ž¯¥à æ¨ï Fill ¤«ï £à ä¨ç¥áª®£® íªà ­  - § ¯®«­¥­¨¥
+                ¢¥à⨪ «ì­ëå «¨­¨©.
+        LD H,H - rezerved
+        LD L,L - ª®¯¨à®¢ ­¨¥ ¡«®ª . �®á«¥¤ãîé ï ª®¬ ­¤  ⨯  LD A,(HL)
+                ¯à¨¢¥¤¥â ª § ¯®«­¥­¨î Ž‡“  ªá¥«¥à â®à  ¤ ­­ë¬¨ ¨§  ¤à¥á  (HL),
+                  ª®¬ ­¤  ⨯  LD (DE),A ¯à¨¢¥¤¥â ª ¯¥à¥§ ¯¨á¨ ¤ ­­ëå ¨§ Ž‡“
+                 ªá¥«¥à â®à  ¢ ®á­®¢­®¥ ¨«¨ ¢¨¤¥®-Ž‡“.
+        LD A,A - ª®¯¨à®¢ ­¨¥ ¡«®ª  ¤«ï £à ä¨ç¥áª®£® íªà ­  ¯®¤®¡­  ª®¬ ­¤¥
+                LD L,L, ­® à ¡®â ¥â á ¢¥à⨪ «ì­ë¬¨ «¨­¨ï¬¨ íªà ­ .
+
+        �ਬ¥à ¨á¯®«ì§®¢ ­¨ï  ªá¥«¥à â®à :
+
+        ; ‘ç¨â ¥¬, çâ® íªà ­­ ï áâà ­¨æ  㦥 ®âªàëâ  ¯®  ¤à¥áã #C000
+        LD HL,#C040     ;  ¤à¥á ­ ç «  «¨­¨¨ ¯¥à¢®£® íªà ­ 
+        LD DE,#C180     ;  ¤à¥á ­ ç «  «¨­¨¨ ¢â®à®£® íªà ­ 
+        LD BC,#140      ; ¤«¨­  íªà ­  ¯® £®à¨§®­â «¨
+        DI              ; § ¯à¥â¨âì ¯à¥à뢠­¨ï ¤«ï à ¡®âë á  ªá¥«¥à â®à®¬
+        LD D,D          ; ¢ª«îç¨âì  ªá¥«¥à â®à ­  ãáâ ­®¢ªã à §¬¥à  ¡«®ª 
+        LD A,0          ; ãáâ ­®¢¨âì à §¬¥à ¡«®ª  - 256 ¡ ©â
+        LD A,A          ; ãáâ ­®¢¨âì  ªá¥«¥à â®à ­  ª®¯¨à®¢ ­¨¥
+                        ; ¢¥à⨪ «ì­ëå «¨­¨©.
+        LDIR            ; ª®¯¨à®¢ âì !
+        LD B,B          ; ¢ëª«îç¨âì  ªá¥«¥à â®à
+        EI              ; ¢ª«îç¨âì ¯à¥à뢠­¨ï
+
+        �â®â ®â१®ª ¯à®£à ¬¬ë ¯à®¨§¢¥¤¥â ª®¯¨à®¢ ­¨¥ ¢á¥£® íªà ­  á ®¤­®£®
+íªà ­  ­  ¤à㣮©. ‚à¥¬ï ¥£® ¨á¯®«¥­¨ï á®áâ ¢«ï¥â ¯à¨¬¥à­® 1.2 ¨­â .
+
+        „®¯®«­¨â¥«ì­ë¥ ä㭪樨  ªá¥«¥à â®à  ¯®ï¢«ïî騥áï ¢ ª®­ä¨£ãà æ¨¨
+Sprinter-3 à ¡®â îâ ¯®¤®¡­ë¬ ¦¥ ®¡à §®¬. „«ï ¢ë¯®«­¥­¨ï «®£¨ç¥áª¨å ä㭪権
+¨á¯®«ì§ãîâáï ª®¬ ­¤ë XOR (HL); OR (HL); AND (HL).
+
+        �ਬ¥à ªá®àª¨ ¡«®ª  ¢ 256 ¡ ©â.
+
+        LD HL,ADRES_1
+        LD DE,XOR_DAT
+        DI
+        LD D,D
+        LD A,0     ; ç¨á«® ¡ ©â, ª®â®àë¥ ­ ¤® ¯à®ªá®à¨âì
+        LD L,L
+        LD A,(DE)  ; ‚§ïâì ¡«®ª ¢ Ž‡“  ªá¥«¥à â®à 
+        XOR (HL)   ; ¯à®¨§¢¥á⨠®¯¥à æ¨î XOR á ¤ ­­ë¬¨  ªá¥«¥à â®à 
+        LD (HL),A  ; § ¯®¬­¨âì ¢ Ž‡“ १ã«ìâ â ®¯¥à æ¨¨
+        LD B,B
+        EI
+
+        ‘ª®à®áâì à ¡®âë  ªá¥«¥à â®à  ®£à ­¨ç¨¢ ¥âáï ⮫쪮 䨧¨ç¥áª®©
+᪮à®áâìî à ¡®âë ®á­®¢­®£® Ž‡“. Ž¯à¥¤¥«¨âì ¢à¥¬ï à ¡®âë ª®¬ ­¤ë á
+ ªá¥«¥à â®à®¬ ¬®¦­® ¯® â ª®© ¯à¨¬¥à­®© ä®à¬ã«¥:
+
+        ‚६ï à ¡®âë = ¢à¥¬ï à ¡®âë ª®¬ ­¤ë ¡¥§  ªá¥«¥à â®à  + ¢à¥¬ï
+                       à ¡®âë  ªá¥«¥à â®à 
+        ‚६ï à ¡®âë  ªá¥«¥à â®à  = ç¨á«® ¯¥à¥áë« ¥¬ëå ¡ ©â /7000000 (ᥪ㭤)
+
+        Žâª«î祭¨¥ ¯à¥à뢠­¨© ¢® ¢à¥¬ï à ¡®âë  ªá¥«¥à â®à  ­¥®¡å®¤¨¬®, â ª
+ª ª ¢ íâ®â ¬®¬¥­â ç áâ¨ç­® ¬¥­ï¥âáï á¨á⥬  ª®¬ ­¤ ¯à®æ¥áá®à  ¨ ¯à®£à ¬¬ 
+­  ¯à¥à뢠­¨¨ ­¥ ᬮ¦¥â à ¡®â âì ­®à¬ «ì­®.
+
+
+        ‡ ª«î祭¨¥.
+
+        � ¡®â  ­ ¤ Sprinter-®¬ ¯à®¤®«¦ ¥âáï. ‘®¢¥à襭áâ¢ã¥âáï ¦¥«¥§® ¨
+¡¨®á. �¨è¥âáï á®äâ, ¯®¤¤¥à¦¨¢ î騩 à áè¨à¥­­ë¥ ०¨¬ë à ¡®âë ª®¬¯ìîâ¥à .
+
+        �® ¢á¥¬ ª®¬¬¥àç¥áª¨¬ ¢®¯à®á ¬ á¢ï§ ­­ë¬ á ¯à¨®¡à¥â¥­¨¥¬ ª®¬¯ìîâ¥à 
+¬®¦­® ®¡à é âìáï ¢ ä¨à¬ã "�¥â¥àá":
+
+              Adress: ‘ ­ªâ-�¥â¥à¡ãà£, ã«. ‚®ááâ ­¨ï, ¤. 35, ®ä. 31.
+               Phone: (812)-327-35-31
+              E-mail: peters@atlant.ru
+
+        �® â¥å­¨ç¥áª¨¬ ¢®¯à®á ¬ ®¡à é âìáï ª® ¬­¥:
+
+                Fido: Ivan Mak (2:5030/529.24)
+              E-mail: ivan_mak@yahoo.com (¢à¥¬¥­­® § ªàëâ)
+

docs/TODO.md

@@ -1,436 +1,434 @@
 # TODO / Roadmap
 
-Открытые задачи в порядке убывания приоритета. По мере появления реальных программ — приоритеты будут смещаться.
-
-## Этап 5 — malloc / free + banking-aware page allocator ✅ ГОТОВО
-
-- [x] SDCC's `malloc`/`free` + наш `runtime/heap.s` (полностью заменяет library heap.rel, 14000-байтный heap в окне 2)
-- [x] `libc/mem/mem_alloc.c` — page allocator: `mem_alloc_pages`/`mem_free_block`/`mem_get_page`/`mem_info` через ESTEX `$3C/$3D/$3E` + BIOS `$C4`
-- [x] `libc/mem/bank_io.c` — HOME-резидентные `bank_read`/`bank_write`/`bank_load_byte`/`bank_store_byte` со свопом W3 внутри
-- [x] `examples/malloc_test/` — проверка SDCC's malloc (~210 64-байтных allocations через всю heap)
-- [x] `examples/mem_test/` — проверка page allocator: 3 страницы, разные паттерны через bank_write, верификация через bank_read
-
-## Этап 6 — argv parsing + sprinter-cc wrapper ✅ ГОТОВО
-
-- [x] crt0 парсит ESTEX command-line из IX-prefix (inline asm в `runtime/crt0.s`)
-- [x] Strip leading CP/M-style space (DSS quirk)
-- [x] Передача `argc`/`argv` в main() через HL/DE (SDCC __sdcccall(1) ABI)
-- [x] argv[0] = basename .EXE через ESTEX APPINFO ($47 subfn 2)
-- [x] `runtime/crt0_minimal.s` — opt-out для очень маленьких программ
-- [x] `runtime/crt0_banked.s` — теперь тоже парсит argv (parse_argv + get_progname скопированы из crt0.s; будет factored в argv.s когда возьмёмся за libsprinter.lib)
-- [x] Bash-обёртка `bin/sprinter-cc`: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций: `--memory`, `--memory-manual`, `--stack-size`, `--crt0=`, `--bank N=FILE.c`, `--debug`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-
-## Этап 8 — графика (320×256×256 + 640×256×16 + accel + bitmap font) ✅ ГОТОВО
-
-- [x] **8a** Graphics core: `gfx_init`/`gfx_done`/`gfx_clear`/`gfx_putpixel`/`gfx_pal_load`/`gfx_pal_set` (libc/gfx/gfx_core.c). Палитра через BIOS PIC_SET_PAL ($A4). Verified 320×256×256.
-- [x] **8b** Линии/прямоугольники/fill через accelerator (libc/gfx/gfx_lines.c): `gfx_hline`/`gfx_vline` через accel Fill (LD C,C / LD E,E + SMC block-size), `gfx_rect`/`gfx_fill_rect` с heuristic выбором ориентации (h/v bursts count), `gfx_line` с Bresenham для диагоналей. `gfx_clear` тоже переписан на column-major accel (~4× быстрее).
-- [x] **8c** 640×256×16 mode (libc/gfx/gfx_16.c): `gfx_*16` API, HIGH nibble = LEFT pixel (документация misleading), per-row RMW для vline (один байт = 2 горизонтальных пикселя).
-- [x] **8d** Bitmap font + gfx_text (libc/gfx/gfx_text.c): шрифт через BIOS WIN_GET_ZG ($B8), interleaved layout `font[row*256+char]`, `gfx_text`/`gfx_putchar` для 320 mode, `gfx_text16`/`gfx_putchar16` для 640 mode с pair-table lookup.
-
-См. memory/sprinter_graphics.md, sprinter_accelerator.md, sprinter_graphics_16.md, sprinter_font_format.md.
-
-Открытые мелочи (не блокируют):
-- [ ] Шрифт-quad для 640: per-cell палитра (mode 0x82 разрешает 1 из 4 палитр per 16×8 cell) — через прямой доступ к area-описания экрана 0x0300..0x039F
-
-## Auto-banking (см. `memory/banking_roadmap.md` для деталей)
-
-Phase 1 — file-level bin-packing — реализовывать когда проект перерастёт ~30 KB кода.
-
-- [ ] `toolchain/auto_bank.py`:
-    - Парсит размеры из `.rel`-файлов (или из .map после dry-run link'а)
-    - First-fit-decreasing bin-packing
-    - Уважает `#pragma codeseg BANKn` как manual override
-    - Перелинковывает с новыми `-Wl-b_BANKn=...` параметрами
-    - Печатает план распределения
-
-Phase 2-5: incremental rebalance, declarative `banks.toml`, function-level, call-graph-aware. Только если/когда понадобится.
-
-## Bank-local static data (mutable data в том же банке что и код) — ✅ ГОТОВО
-
-- [x] Пример `examples/bank_local_data/` — функция в BANK1 со своим writable BSS array + const table + malloc-тест
-- [x] `mkexe -p 0` для нулевого padding банков (BSS-storage обнуляется при загрузке)
-- [x] Канонический рецепт: `--codeseg BANK1 --constseg BANK1 --dataseg BANK1` для bank1.c + `-Wl-b_BANK1=0x1C000` для линковки. **`--dataseg BANK1` РАБОТАЕТ** — раньше казалось обратное из-за trampoline bug который маскировал результат.
-- [x] **Критичный фикс trampoline'a в runtime/bank.s** — старый `pop af; out (n), a` клобберил A → все banked-функции возвращающие uint8_t тихо возвращали мусор. Новый `pop bc; out (c), b` сохраняет A.
-- [x] **malloc из banked-функции работает прозрачно** — heap живёт в W2 (HOME), W2 никогда не свапается trampoline'ом, pointer валиден из любого контекста. См. memory/bank_local_data_pattern.md.
-- [x] Документация в memory: `memory/bank_local_data_pattern.md` (полный рецепт + malloc + nuances), `memory/sdcc_banking.md` (trampoline fix)
-- [ ] Опционально — расширить `check_banks.py` чтобы показывать разбивку size = code + const + bss per bank (cosmetic)
-
-Зачем: для модулей с большим private state (level loader, audio engine, scene data). Экономит W2 heap для динамики, а статика остаётся в бэке.
-
-## Подсказки из solid-c (нативный Sprinter C — `third_party/solid-c/`)
-
-После анализа solid-c'овской libc (см. `memory/solid_c_findings.md`) выявлены готовые паттерны для следующих недостающих функций. Приоритет от **высокого** к низкому:
-
-### High-priority gaps (легко портировать, большая польза)
-- [x] **`errno` + `strerror`/`perror`** — табличка 32 ошибок (libc/io/errno.c)
-- [x] **Расширенный `open()`** для O_CREAT/O_TRUNC/O_APPEND/O_EXCL state machine
-- [x] **`atexit`** — 8-callback LIFO + `exit()` + `_exit()` (libc/io/atexit.c)
-- [x] **`setjmp`/`longjmp`** — 6-байт jmp_buf={sp,ix,pc} (libc/io/setjmp.c)
-- [x] **`sleep(seconds)`** — 50Hz halt-loop (libc/io/sleep.c)
-- [x] **ESTEX ENV API** ($46, getenv/putenv) — libc/io/env.c. Учли doc-bug: реально A=0 это NOT FOUND
-
-### Medium-priority (нужно для shell-like утилит)
-- [ ] **Mouse driver** — `rst $30h`, 17 функций. **Сначала тест что работает в MAME**.
-- [x] **`ffirst`/`fnext` + ffblk_t struct** для directory listing — реализовано, demo: ls.exe
-- [x] **`getdatetime`/`setdatetime`** через ESTEX $21/$22 — libc/io/time.c, demo: time_dir_test
-- [x] **`chdir`/`getcwd`/`mkdir`/`rmdir`** — wrappers для ESTEX $1B-$1E — libc/io/fsdir.c
-- [x] **conio: `kbhit`/`getch`/`getche`/`cputs`/`clrscr`/`gotoxy`** — реализовано
-- [x] **conio extras**: `wherex`/`wherey` ($53), `wrchar`/`rdchar` ($58/$57), `textmode_get/set` ($50/$51), `clrscr_attr` ($56) + COLOR macros
-
-### Low-priority — ✅ FILE* stack ГОТОВО
-
-- [x] **Минимальный unbuffered FILE\*** — `libc/stdio/file.c` + `libc/include/stdio.h`. fopen/fclose/fputs/fgets/fread/fwrite/fseek/ftell/rewind/feof/ferror/clearerr/fflush + stdin/stdout/stderr как pseudo-streams. См. `memory/file_star_design.md` и `examples/filetest`.
-- [ ] fprintf / fscanf — нужна printf-через-callback machinery. Пока пользователь может `sprintf(buf, ...) + fputs(buf, fp)`.
-- [ ] Опциональный buffered mode (setvbuf, line/block buffering) — если когда-то понадобится.
-
-### POSIX time API — ✅ ГОТОВО
-- [x] `libc/io/posix_time.c` — time/localtime/gmtime/mktime/asctime/ctime поверх getdatetime. SDCC's time.rel избегаем (нельзя override _RtcRead). См. `examples/ptime`.
-
-### sys/stat — ✅ ГОТОВО
-- [x] `libc/io/stat.c` — POSIX stat/fstat. Гибрид open+fstat для файлов, ffirst+iter для папок (включая "."/".."). См. `examples/stattest` и `memory/estex_ffirst_dotdot.md`.
-
-### assert — ✅ ГОТОВО (используем SDCC's __assert через fallback include path)
-
-## libc/stdlib — ✅ не нужно делать (см. memory/sdcc_stdlib_works.md)
-
-Проверено через `examples/stdlib_test/`: SDCC z80.lib содержит работающие реализации:
-- `atoi/atol/atof, strtol/strtoul, rand/srand, qsort/bsearch, abs/labs, div/ldiv`
-- Полный `<string.h>` (memchr/cmp/set/cpy, strcat/cmp/cpy/len/chr/spn/etc.)
-- `<ctype.h>` (toupper/tolower)
-- `<math.h>` (sinf/cosf/sqrtf/etc.)
-
-Линкер автоматически тянет из z80.lib когда нужно. **НЕ переписывать**.
-
-Наши Sprinter-specific обязательные модули остаются: atexit, env, errno, setjmp, putchar/puts/getchar, conio, fsdir, time, mouse, open/read/lseek/close.
-
-## Build-system: libsprinter.lib + sprinter-cc — ✅ ГОТОВО
-
-- [x] `lib/Makefile` — собирает каждый libc/*.c в `.rel`, архивирует через sdar в `lib/sprinter.lib`
-- [x] Включает runtime/bank.s и runtime/heap.s (auto-pulled при __banked/malloc)
-- [x] `bin/sprinter-cc` — bash-wrapper: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций `--crt0=default|minimal|banked`, `--bank N=FILE.c`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-- [x] `examples/hello_sccc/` — демо: `hello.c` собирается за один shell-вызов, размер совпадает с ручным Makefile (925 байт)
-- [x] Split `putchar.c` → `putchar.c` + `puts.c` для per-function granularity (puts override SDCC's z80.lib version)
-- [x] Включён в `make all` (зависимость `lib` перед `examples`)
-
-Возможные улучшения (опционально):
-- [ ] Мигрировать остальные examples на sprinter-cc вместо ручных Makefile (косметика)
-- [ ] Дальнейшая декомпозиция libc/*.c per-function (но текущая granularity уже даёт нужный размер — линкер пакетует .rel целиком, и для большинства файлов это одна функция)
-
-## Этап 9 — memory modes для sprinter-cc
-
-DSS выделяет страницы памяти по размеру приложения: < 16 KB → одна страница, в остальные окна подключается «страница #FF» (read=0xFF, write игнорится). Из-за этого CODE-в-W1 + DATA-в-W2 для маленькой программы молча ломается. См. [memory/sprinter_memory_modes.md](../../.claude/projects/-Volumes-SAM8-Projects-DIY-Z80-Sprinter-C-Compiler/memory/sprinter_memory_modes.md).
-
-- [x] **`tiny`**: всё (CODE+DATA+стек) в W2. Default. Verified hello/argv/conio/malloc/file/etc.
-- [x] **`--memory MODE` флаг в sprinter-cc**: parser + per-mode дефолты CODE_LOC/DATA_LOC, override через явные `--code-loc`/`--data-loc`. tiny работает; small/big/huge компилируются с warning'ом (runtime не готов). Реализовано 2026-05-30.
-- [x] **`--memory-manual SPEC`**: парсит `CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3`. Реализовано 2026-05-30.
-- [x] **`small` runtime**: `runtime/crt0_small.s` использует ESTEX `$3D GETMEM` + `$3A SETWIN2` чтобы выделить и замапить W2-страницу ДО gsinit. **НЕ** BIOS `$C4` — стек на этом этапе в W1 (boot_stack в HOME), а BIOS требует стек в W2. После маппинга SP переключается на 0xBFFE, дальше стандартный flow. Реализовано 2026-05-30, verified hello.exe.
-- [x] **`small` auto-detect для >16 KB программ**: `crt0_small.s` читает порт `0xC2` (текущая страница в W2 — не `0xA2`! это W1). Если 0xFF — выделяет page; иначе DSS уже сделала это (программа сама вылезла в W2). Один crt0 покрывает 0..30 KB. mkexe также разрешает HOME span W1+W2 (0x4000..0xBFFF). Verified hello: small (5 KB файл, SETWIN2 path) + 32 KB файл (auto-skip). Реализовано 2026-05-30.
-- [x] **`big` runtime** (tiny + banked code в W1): параметризовали `crt0_banked.s` + `bank.s` через `.ifdef BANK_W1` — другой banking port (0xA2 vs 0xE2), другой load-addr (0x4000 vs 0xC000). sprinter-cc prepend'ит `BANK_W1 = 1` при `--memory big`, передаёт `mkexe -B 0x4000`. Пример `examples/banked_big/`. Реализовано 2026-05-30.
-- [x] **`huge` runtime** (small + banked code в W3): merge W2-detect логики из `crt0_small.s` в `crt0_banked.s`. Существующий пример `examples/banked/` теперь использует MEMORY=huge. Реализовано 2026-05-30.
-- [x] **`--debug` флаг**: prepend `DEBUG_RT = 1` в crt0 + `-DDEBUG_RT` в sdcc. Открывает symbol `_w2_self_allocated` (uint8_t) — runtime diagnostic кто аллоцировал W2. Реализовано 2026-05-30.
-
-### Дизайн-решения по libc и crt0
-
-**Одна `sprinter.lib`** работает для всех memory mode — `.rel`-члены relocatable, SDLD делает dead-code elimination per-member (без графики не подтягивает `gfx_core.rel` и т.д.). Verified hello vs malloc_test через map-файлы.
-
-**`gfx.lib` отдельно — НЕ нужен**: dead-code elimination уже работает.
-
-**`libc_banked` (libc в bank вместо HOME)** — идея на потом, когда HOME (16 KB) забит user-кодом + libc в `huge` mode. Реализуется через `--codeseg BANK0` при компиляции libc; trade-off: trampoline ~30 циклов на каждый libc-вызов. Триггер: реальная программа упрётся в HOME budget.
-
-**HW-зависимые модули — `sprinter_home.lib` отдельно.** Часть libc физически не может быть забанкована в W3, потому что она РАБОТАЕТ с W3:
-- `gfx_*` — пишет в видеопамять `0xC000+` после swap W3 на video page
-- `bank_io` (mem_alloc_pages/bank_read/bank_write) — swap'ит W3 через `OUT (0xE2)`
-- Будущие ISR — прерывание может прийти когда W3 на чём угодно
-
-В huge mode эти модули ДОЛЖНЫ остаться в HOME (W1). Когда будем делать `libc_banked`, **одновременно** выделяем `sprinter_home.lib` (HOME-only) из `sprinter.lib` (bankable). Финальная схема:
-```
-sprinter_home.lib    HOME-only:   gfx, bank_io, ISR shims
-sprinter.lib         bankable:    printf, malloc, string, conio, stdio, env, ...
-sprinter_banked.lib  тот же sprinter.lib но --codeseg BANK0 (для huge)
-```
-Триггер: реализация `--memory huge` runtime.
-
-**crt0 — по одному на mode:**
-- `crt0.s` — текущий, для **tiny/big**: SP=0xBFFE, парсит argv (W2-ресурс уже выделен DSS).
-- `crt0_minimal.s` — текущий, для tiny без argv.
-- `crt0_small.s` — **новый, step 3**: для **small/huge**, аллоцирует W2 через `mem_alloc_pages` ДО gsinit, маппит в порт `0xA2`, потом стандартный flow.
-- `crt0_banked.s` — текущий, для **big**: trampoline-таблица для W3 банков, CODE в W2.
-- `crt0_banked_small.s` — **новый**: huge = small (W2-alloc) + banked (W3 trampolines).
-
-sprinter-cc подбирает crt0 по `--memory` mode (сейчас `--crt0=` это override).
-- [x] **Настраиваемый размер стека**: флаг `sprinter-cc --stack-size BYTES`. Wrapper генерирует `heap_top.s` с `___sdcc_heap_end = stack_top + 1 - stack_size`, отдельный .rel линкуется per-program. Default ≈1278 байт (heap_top=0xBB00) из `runtime/heap_top.s`. Реализовано 2026-05-30.
-
-Интерфейс: `sprinter-cc --memory [tiny|small|big|huge|manual] [--memory-manual SPEC] [--stack-size N] foo.c`. `--memory-manual` имеет смысл только с `--memory manual`.
-
-## Known issues / quirks
-
-- **ESTEX $46 ENV API**: ✅ работает. Док-ция в `DiskSyscalls.txt v1.6` ошибочно описывает return-status — A=0 это NOT FOUND, не FOUND. Зафиксировано в `memory/sprinter_platform.md`.
-
-## ОБЯЗАТЕЛЬНЫЕ ЗАДАЧИ ДЛЯ V2 (после релиза v1)
-
-### Turbo-C-style graphics API (BGI-like) — **MUST для v2**
-
-Расширить наш `gfx_*` API до уровня **Turbo-C `<graphics.h>`** (BGI) для MS-DOS.
-Программисты привыкшие к Turbo-C должны переносить графический код 1-в-1.
-
-**Что должно быть** (на основе Borland BGI):
-
-Setup/teardown:
-- `initgraph()` / `closegraph()` — у нас сейчас `gfx_init`/`gfx_done`, добавить alias
-- `getmaxx()` / `getmaxy()` — макрос на GFX_WIDTH-1 / GFX_HEIGHT-1
-- `cleardevice()` — alias to gfx_clear
-- `getgraphmode()` / `setgraphmode()` — у нас get_videomode/set_videomode
-
-Color/palette:
-- `setcolor(c)`, `getcolor()` — current draw color
-- `setbkcolor(c)`, `getbkcolor()` — background color
-- `setpalette(idx, c)` — палитра entry
-- `getpalette(&info)` — read all palette
-
-Primitives (мы уже имеем эквиваленты — добавить BGI-имена как aliases):
-- `putpixel(x, y, c)` — есть как gfx_putpixel
-- `getpixel(x, y)` — нужно реализовать (RMW обратное — IN)
-- `moveto(x, y)`, `lineto(x, y)`, `linerel(dx, dy)` — current point + line drawing
-- `line(x1, y1, x2, y2)` — есть как gfx_line
-- `rectangle(x1, y1, x2, y2)` — есть как gfx_rect (но другой API: x1,y1,x2,y2 vs x,y,w,h!)
-- `bar(x1, y1, x2, y2)` — есть как gfx_fill_rect
-- `bar3d(x1, y1, x2, y2, depth, topflag)` — новое: rect + 3d edges
-- `circle(x, y, r)`, `arc(...)`, `ellipse(...)`, `pieslice(...)` — новые primitives
-- `fillpoly()`, `drawpoly()` — полигоны
-- `floodfill(x, y, border_color)` — заливка
-
-Text on graphics screen:
-- `outtext(s)` / `outtextxy(x, y, s)` — есть как gfx_text (alias)
-- `settextstyle(font, dir, size)` — multiple bitmap fonts
-- `gettextsettings(&info)`
-- `textwidth(s)` / `textheight(s)` — measure
-
-Image manipulation:
-- `imagesize(x1, y1, x2, y2)` — bytes needed for getimage
-- `getimage(x1, y1, x2, y2, buf)` — save rect to buffer
-- `putimage(x, y, buf, op)` — paste back with COPY_PUT/XOR_PUT/AND_PUT/OR_PUT/NOT_PUT
-
-Clipping/viewport:
-- `setviewport(x1, y1, x2, y2, clip)` — drawing clip rect
-- `getviewsettings(&info)`
-- `clearviewport()`
-- `setactivepage(p)` / `setvisualpage(p)` — двойная буферизация (Sprinter имеет 2 screen)
-
-Line style:
-- `setlinestyle(style, pattern, thickness)` — SOLID_LINE / DOTTED_LINE / etc.
-- `getlinesettings(&info)`
-
-**Acceptance:** перенос типичной Turbo-C BGI программы (рисующей с использованием
-moveto/lineto/circle/bar/setcolor) должен работать без существенных правок.
-
-**Notes:**
-- BGI fonts (TRIPLEX/SANS_SERIF/GOTHIC) — у нас один BIOS font, остальные нужно
-  добавить (как bitmap data в lib)
-- imagesize/getimage/putimage — самые востребованные для game/animation
-- Active/visual page (двойная буферизация) — Sprinter поддерживает 2 graphics pages,
-  нужен API switching
-
-См. также `examples/` Turbo C 2.x BGIDEMO как reference что нужно.
-
-### IM2 Interrupt Handlers — **MUST для v2**
-
-User-задаваемые ISR через Z80 IM 2 mode.  Нужны для:
-- Timer ticks (50 Hz frame counter, плавная анимация)
-- Music playback (AY, COVOX)
-- Real-time games (input + game logic + render в interrupt-driven)
-- Async keyboard / mouse handling
-
-**Status:** ОТЛОЖЕНО до v2.  Полный research + design в `docs/im2_isr_design.md`.
-
-**Решение по архитектуре:** реализовать как отдельный memory mode `--memory im2`
-(вместо того чтобы лезть во все существующие crt0).  Detail'и в design-doc.
-
-**Резюме research'а** (полный текст в `docs/im2_isr_design.md`):
-- Vector 0xFF — frame + keyboard + CBL.  Disambiguation по портам 0x19 / 0xFE
-- Mouse hardware-IRQ не приходит (на текущей плате)
-- Vector table / ISR / stack ОБЯЗАНЫ быть в W2 (0x8000..0xBFFF)
-- DSS имеет свой IM 2 handler — нужно chain'иться (иначе клавиатура / SYSTIME ломаются)
-
-### Прочие крупные пункты для v2
-
-- [ ] **FILE API rewrite — buffered streams** — текущая реализация в
-  `libc/stdio/file.c` это provisional unbuffered shim (каждый fputc/fgetc
-  = один read/write syscall).  Нужна полноценная buffered семантика
-  как в Solid-C:
-
-  ```c
-  typedef struct {
-      uint   flags;     // +0..1   file status flags
-      int    level;     // +2..3   empty/fill level of buffer
-      char  *curp;      // +4..5   current active pointer
-      int    fd;        // +6..7   underlying low-level fd
-      char  *buffer;    // +8..9   data transfer buffer
-      char   hold;      // +10     ungetc byte if no buffer
-      short  token;     // +11..12 reserved
-      char   dummy;     // +13     reserved
-  } FILE;
-  ```
-
-  stdin/stdout/stderr — fd-маркеры `0 / -1 / -2`.  Отрицательные для
-  stdout/stderr выбраны намеренно: ESTEX OPEN может вернуть positive
-  small fd (1, 2, …) для обычного файла → если бы stdout=1, реальный
-  fd=1 сталкивался бы с идентификатором.  fd=0 для stdin безопасно
-  (ESTEX 0 не возвращает).  Сами fd не передаются в syscall'ы —
-  диспетчеризация по флагам `_F_CONIN/_F_CONOUT`.
-
-  Принтер-потоки (stdaux/stdprn) НЕ реализуем — Sprinter принтерной
-  API не имеет.
-
-  Альтернатива — взять реализацию из third_party/solid-c (sources в
-  `SRC/CLIB/`); там есть готовый buffered FILE + fopen/fread/fwrite/
-  fseek/setvbuf и т.д.  Адаптировать к нашим open/read/write/lseek.
-
-  При rewrite заодно решить deferred issues stdio-review:
-  - `fwrite` short-write должен ставить `_F_ERROR`
-  - `fgets(buf, 1, fp)` — стандарт говорит "empty string", мы вернули NULL
-  - `mode_to_flags` — break-out на '+' (cosmetic)
-
-- [ ] **Audio API** — AY-3-8910 + COVOX через прерывания (требует IM2)
-- [ ] **ISA-8 slot support** — ZX-Bus карты (sound, network, etc.) — требует IM2 + чтения portов
-
-## Прочие задачи (v1 backlog, не блокирующие)
-
-- [x] **#9: text I/O split (Turbo-C style)** — stdio (puts/printf/putchar) теперь fast no-attr через PCHARS/PUTCHAR. conio (cputs/cprintf/putch) применяет attr через textcolor/textbackground/textattr. KEEP_EXIST_ATTR → conio fallback на fast path. Verified в hello.exe. См. `memory/text_output_api_split.md`. Реализовано 2026-05-31.
-- [x] **Mouse API полный** (резидентный driver, RST 30h) — все 14 функций обёрнуты (init/show/hide/refresh/read/goto/bounds/text_cursor/load_cursor/get_cursor/get/set_sensitivity/video_mode_changed). См. `memory/mouse_api.md`. Verified в MAME 2026-05-31. Sensitivity = divider (меньше = быстрее).
-- [ ] Interrupt handlers — IM 2 vector table в HOME для user ISR'ов
-- [ ] Поддержка `restore SP on EXIT` (паттерн из z88dk +pps) — проверить нужно ли
-- [ ] CI: автоматически запускать MAME с `-aviwrite` для screenshot-сравнения, чтобы тесты примеров проходили без человека
-
-## Идеи на потом
-
-- Поддержка `<setjmp.h>` (есть в SDCC stdlib — нужно протестировать что наш crt0 совместим)
-- `<time.h>` через ESTEX SYSTIME (`$21`) и CMOS BIOS-функции
-- ZX Spectrum-совместимый режим как отдельный target (для портирования спектрумовских программ)
-- Поддержка ZX-Bus карт (sound, network, etc.) — нужны драйверы
-- Profile-guided optimization tools (hot/cold detection) для крупных программ
-
-## Linker duplicate-symbol warnings (благоприятные, отфильтрованы)
-
-Когда мы сознательно overrides'им SDCC z80.lib функции собственной версией в `sprinter.lib`, `sdldz80` пишет `?ASlink-Warning-Definition of public symbol '...' found more than once`. Линкер берёт первое найденное определение (наше), поэтому поведение корректное — warning только noise.
-
-Текущие overrides:
-- `_puts` — наша версия через PCHARS+\r\n vs SDCC posix puts
-- `___sdcc_heap` — наш heap в W2 vs SDCC's стандартный
-- `_asctime`, `_localtime` (и возможно другие из time) — наш `posix_time.c` через ESTEX SYSTIME vs SDCC's `time.rel` который зависит от `_RtcRead`
-
-**Текущее решение:** `bin/sprinter-cc` отфильтровывает warning-блок (warning + 2 follow-up `Library:` строки) из вывода `sdc
-
-c`. Через `-v` (verbose) всё показывается. Реализовано через awk-pipe.
-
-**Возможные улучшения:**
-- Перейти на explicit `--nostdlib` + ручной список нужных модулей из z80.lib (string, math, stdlib без override'нутых) — убрать ИСТОЧНИК warning'ов, не маскировать
-- Или: переименовать наши `_puts` → `_puts_sprinter` + alias через linker flag (не уверен что SDCC поддерживает)
-- Или: оставить как сейчас (рабочее и benign) — приоритет низкий
-
-## TODO: проверить на реальном железе
-
-- [ ] **Port_Y banking trick** (`docs/part2/SprinterGraphics programming.txt`):
-      доку утверждает что после `OUT (0x89), Y` адреса 0xC000+0x400*N в окне W3
-      маппятся на строки Y..Y+15 (одно программирование → 16 строк).
-      Empirical 2026-06-01 в MAME 0.283 этот trick **не работает** — пиксели
-      по адресам выше 0xC000+row_width уходят в невидимую область.  Канонический
-      `docs/samples/plasma2.asm` тоже не использует banking, переустанавливает
-      Port_Y per row.
-      План:
-      1. Получить доступ к реальному Sprinter
-      2. Запустить тест dual-write (`_gfx_putpixel_raw` + второй write в `0xD000+x`)
-      3. Если на железе видны двойные линии → бага MAME, открыть issue с
-         минимальным репро
-      4. Если на железе тоже одна линия → документ неверный, удалить упоминание
-         из доки и просто оставить текущую реализацию (Port_Y per pixel)
-      5. Если banking работает на железе → внедрить кэширование Port_Y в
-         `_gfx_putpixel_raw` (sentinel out-of-range, см. memory/gfx_port_y_banking.md)
-
-      Связанный выигрыш для Bresenham (60-pixel диагональ) — около 8× меньше
-      OUT (0x89) операций, для `gfx_fill_rect 320x256` — 16× меньше.  Не блокирует
-      release v1.
-
-## GFX: расширения по `docs/part2/accelerator_doc.txt`
-
-После прочтения детального accelerator doc выявлены незакрытые направления.
-Сейчас в коде используется только горизонтальный/вертикальный Fill mode.
-
-### Quick wins для текущих primitives
-
-- [ ] **Заменить SMC на `LD A, (var)` для block-size**.  Документ явно
-      разрешает `LD A, (HL)`, `LD A, (BC)`, `LD A, (DE)` (но не `LD A, r`).
-      Это уберёт SMC complexity в `gfx_lines.c:hfill_chunk/vfill_chunk` и
-      `gfx_16.c:g16_hfill_chunk`.  Запрещено только register-to-register.
-- [ ] **Кэширование block-size**.  Документ показывает что accel запоминает
-      block size между bursts (см. `Horizontal_Line_Fill`: устанавливают
-      size + `LD B,B` отключение, потом включают Fill mode и используют
-      сохранённый size).  Для `gfx_fill_rect` с 100 одинаковыми
-      строками — установить size 1 раз, а не 100.
-
-### Bank-prefix modes (port 0xE2 bits)
-
-Документ показывает три варианта банка видеостраницы помимо стандартного 0x50:
-
-| Bank byte | Effect |
-|---|---|
-| 0x50 | Normal write — пишется в shadow + видимый |
-| 0x54 | "no copy in main shadow RAM" |
-| 0x58 | **"FF is transparent"** — байт 0xFF при write оставляет background |
-| 0x5C | both |
-
-Bank 0x58 объясняет почему mouse cursor рисуется с 0xFF-прозрачностью.
-Это путь к **sprite-blending через accel block copy**:
-
-- [ ] **`gfx_set_bank_transparent(on)`** или флаг в `gfx_set_bank` для
-      выбора 0x50/0x58 при отрисовке sprite'ов
-- [ ] Использовать в новом `gfx_blit()` чтобы по факту получать
-      transparent sprites через accel-копию
-
-### Block copy mode (sprite blit'ы)
-
-`LD L,L` (horizontal) и `LD A,A` (vertical) — режим копирования блока через
-256-байтную accel memory.  Это базис для blit'ов.
-
-- [ ] **`gfx_blit(src_data, x, y, w, h)`** — копирование sprite'а
-      (произвольный размер, через accel)
-- [ ] **`gfx_blit_transparent(src, x, y, w, h)`** — с использованием bank 0x58
-
-См. `Draw_Restangle_Data` в accelerator_doc.txt как референс.
-
-### AND / OR / XOR operations через accel
-
-Документ показывает что accel поддерживает логические операции с блоками
-данных.  Применения:
-- XOR — инверсия области (выделение selection в UI)
-- OR / AND — masking, alpha-style blending
-- См. пример в accelerator_doc.txt: "256 bytes block coding via XOR"
-
-- [ ] **`gfx_xor_rect`** / **`gfx_or_rect`** / **`gfx_and_rect`** —
-      примитивы логических операций над прямоугольником
-- [ ] **`gfx_invert_rect(x, y, w, h)`** — alias на xor с 0xFF
-
-### Bitmap fonts разных размеров
-
-Сейчас `gfx_text` / `gfx_putchar` хардкоженно работают с 8×8 шрифтом
-(BIOS WIN_GET_ZG возвращает 256×8 байт).  Для будущих UI / титульников
-нужны:
-- [ ] **`gfx_set_font_size(w, h)`** — переключить ширину/высоту glyph'а
-- [ ] **`gfx_set_font_data(ptr, w, h, advance)`** — заменить указатель
-      на пользовательский шрифт + размеры
-- [ ] Поддержка **proportional** (advance != w) шрифтов — добавить
-      array advance[256] на ширину каждого glyph'а
-- [ ] **Big-font режимы**: 8×16, 16×16, 16×8 (для титульников)
-- [ ] Возможно отдельный API `gfx_text_ex(x, y, str, font_id)` где
-      font_id выбирает один из загруженных шрифтов
-- [ ] **Anti-alias 2-bit шрифты** (бит фон / бит граница / 2-бит alpha?)
-      — far future, для smooth UI
-
-## Финальный этап оптимизаций (не сейчас)
-
-- **`gfx_line` через accel для пологих диагоналей** — Bresenham для линии с |dy| << |dx| (или наоборот) выдаёт длинные runs одинакового Y (или X): пиксель, пиксель, пиксель, шаг Y, пиксель, пиксель... Каждый такой run — это готовый аргумент для `gfx_hline` (или `vline`).  
-  План исследования: посчитать длину runs как функцию от наклона; решить минимальный run length, при котором выгоднее accel hline чем N×putpixel (overhead accel ~20µs, putpixel ~5µs — accel выгоднее при run ≥ 4-5 px); для крутых диагоналей (dx ≈ dy) оставить Bresenham, для пологих — run-length-based fill.
-  Сейчас `gfx_line` orthogonal cases уже через accel — оптимизировать только косые.
-
-- **`gfx_fill_rect` с одним W3-swap на всю операцию** — сейчас каждый внутренний `gfx_hline`/`gfx_vline` делает свой DI/save-W3/restore-W3/EI. Можно сделать internal `_fill_rect_inner` который держит W3 замапленным и DI весь цикл; ~20µs × количество строк/столбцов экономии. Применимо ко всем композитным примитивам.
+Открытые задачи в порядке убывания приоритета; закрытые этапы — в
+«Истории» внизу.  Текущий срез libc-работ: docs/libc-roadmap.md.
+
+## Ближайшее
+
+- [ ] **Дополнить `<errno.h>` полным списком кодов DSS после 32.**
+      Исходники DSS 1.71 подтверждают как минимум код 35
+      `TOO_MANY_FILES_IN_DIR`: `F_FIRST/F_NEXT` возвращают его в `A` при
+      `CF=1`, а libc правильно переносит число в `errno`, но публичного
+      символического имени и строки `strerror()` сейчас нет. Сверить весь
+      список с `Shared_Includes/DSS_Errors.inc`, добавить константы без
+      перенумерации существующих кодов, расширить таблицу `strerror`,
+      `docs/libc-reference.md` и тест на преобразование `CF/A -> errno`.
+      До этого Commander использует локальную константу со значением 35.
+
+- [ ] **Перевести новые EMM/W0-функции libc/libbgi на Z80 asm:**
+      `bank_load_file()`, `bank_save_file()` и `gfx_w0_page_prepare()`.
+      Сейчас универсальная C-обвязка (четыре аргумента, IX-frame, проверки
+      диапазона и сохранение временных значений) съедает часть выигрыша от
+      унификации загрузчиков PoP.  Сделать компактные `__naked`-реализации
+      по образцу остальных низкоуровневых функций библиотек, строго сохранив
+      `__sdcccall(1)`, IX, W3 до возврата и семантику `-1 + errno`; fast-
+      вариант может вырезать проверки диапазона, safe обязан их оставить.
+      После правки: `make -C libc`, `make -C libbgi`, `make size-check` и
+      MAME-проверка Atlas/Kid/Level/Sound + QuickSave/QuickLoad.
+
+- [ ] **Модульные тесты libc и libbgi под ucsim_z80** — план:
+      `docs/host-tests-plan.md`.  Обвязка уже готова и обкатана
+      (`testkit/`, первый потребитель — PoP/roomtest).  Не срочно, но
+      обязательно: это основной продукт репозитория, а покрыт он сейчас
+      только интеграционными тестами в MAME.  Начинать с `time/` и
+      `stdio/` (нулевые швы), затем геометрия `libbgi/common`, затем
+      фейковые ESTEX/BIOS в тестовом crt0 — они открывают `file/`, `io/`,
+      `conio/` и проверку гардов (`_fd_guard`).
+
+Порядок реализации связки: **сначала цепочка irq, потом FPS-делитель
+поверх неё** (делитель — просто один слот цепи; так снимается EBUSY
+на сосуществование со своим тиком приложения).
+
+- [x] **(1) irq: цепочка кадровых обработчиков** — СДЕЛАНО 2026-07-15.
+      Массив `isr_t _irq_chain[4]` + `_irq_chain_n` в W2-data (заменили
+      `_irq_user`); трамплин `tr_frame` проходит слоты (один тяжёлый сейв
+      на всю цепь, пустой слот пропускается); API `irq_chain_add`
+      (0/-1+ENOMEM), `irq_chain_remove(h)`; `irq_install` → обёртка
+      chain_add (EBUSY исчез), `irq_remove()` рвёт всю цепь; refcount
+      таблицы на первом/последнем слоте; мутации под IRQ_DISABLE.
+      All-modes W1-remap: трамплин копируется в W2 (`_irq_tramp_w2buf`,
+      copy-safe — только jr/djnz + литерал jp 0x0038), вокруг вызова
+      восстанавливает базовую W1-страницу (`_irq_app_w1_page` = IN 0xA2
+      при install).  ПРОВЕРЕНО в MAME (tests/irqtest, 2 хендлера):
+      tiny/big/huge — chain 97=97 → remove h2 → 48/0; **huge = код в W1,
+      remap работает** (цепочка тикает синхронно).  Дизайн:
+      docs/im2_isr_design.md.
+      FOLLOW-UP: (а) CTC-трамплин пока требует код в W2 → в small/huge
+      `irq_ctc_install` = EINVAL (нужна такая же W2-копия _irq_ctc_tramp);
+      (б) small для мелких программ (BSS в W1) → irq_install EINVAL
+      (safe; снять резервом area _IM2 в верхней W2).
+- [x] **(2) FPS-делитель (frame pacing)** — СДЕЛАНО 2026-07-15.
+      gfx_set_fps_div(n): логический кадр = ровно n кадровых интервалов
+      (1=50/2=25/3=~16.7 fps); при переполнении слота — выравнивание на
+      ближайший фронт (без дрейфа фазы).  Счётчик кадров _gfx_frame_tick
+      через irq_chain_add(_gfx_frame_isr) — свой слот цепи (n<=1 снимает
+      его через irq_chain_remove, не трогая хендлер приложения).
+      gfx_wait_vsync: ветка n>=2 (счётчик+halt) перед лучевым поллингом.
+      Файлы: common/_gfx_fps_state.c, _gfx_frame_isr.c, gfx_set_fps_div.c,
+      правка gfx_wait_vsync.c.  Работает tiny/big/huge (цепочка all-modes);
+      small для мелких программ = EINVAL.  ПРОВЕРЕНО MAME (tests/fpsdiv):
+      n=1/2/3 → 20/40/60 кадров на 20 wait'ов (drift=0); n=2 с рендер-
+      заглушкой ~1 кадр → период держится 2 (поглощение перерасхода,
+      наивный путь дал бы ~60); huge идентично; small = EINVAL graceful.
+      ПЛАН: docs/sprite-api-design.md §9е.
+- [ ] **П6/железо**: MAME-смоук всех тестов после libc-сплита (conio,
+      ptime, stattest, mouse, gfx_demo/gfx_d16/gfx_text/gfx_mous —
+      трогался asm акселератора); затем прогон на реальном Sprinter
+      (mdview2 + FILE* v2 + fdmax — подтвердить лимит 8 манипуляторов
+      и зависание DSS на 9-м OPEN)
+- [ ] Мигрировать оставшиеся examples на sprinter-cc вместо ручных
+      Makefile (косметика)
+- [ ] check_banks.py: разбивка size = code + const + bss per bank
+
+## Auto-banking (memory/banking_roadmap.md)
+
+- [x] **Генерировать `n_banks` из реальной раскладки банков.**
+      `sprinter-cc` вычисляет максимальный N из `--bank N=…`, проверяет диапазон
+      1..15 и отсутствие дыр, затем линкует сгенерированный `_n_banks`.
+      Раньше число задавалось ещё и вручную в приложении; рассогласование давало зависание в
+      рантайме: `_bank_pages[N]` остаётся нулём, трамплин отображает в
+      окно страницу 0 и прыгает по 0xC000 в мусор (предупреждение об этом
+      уже есть в шапке `runtime/bank.s`).
+      **Найдено 2026-08-05** на PoP/roomtest: добавили пятый банк
+      (`--bank 5=pop_ctrl.c`), забыли `n_banks` — игра доходила до конца
+      загрузки ресурсов и вставала намертво в дисковом коде DSS.  Диагноз
+      занял заметно больше, чем сама правка: симптом (зависание в чужом
+      коде) никак не указывает на причину.
+      Берётся не число опций (в одном банке может быть несколько модулей), а
+      **максимальный индекс**. Дыры запрещены, поскольку `crt0_banked` и `mkexe`
+      обрабатывают `_bank_pages[1..n_banks]` подряд.
+
+Phase 1 — file-level bin-packing (`toolchain/auto_bank.py`) — когда
+проект перерастёт ~30 KB кода: парсинг размеров из .rel/.map,
+first-fit-decreasing, уважение `#pragma codeseg BANKn`, перелинковка,
+печать плана.  Phase 2-5 (rebalance, banks.toml, function-level) —
+по потребности.
+
+## ОБЯЗАТЕЛЬНОЕ ДЛЯ V2
+
+### Turbo-C-style graphics API (BGI-like) — Фаза 1 ГОТОВА (256, 2026-07-08)
+
+Архитектура: `graphics.h` — mode-agnostic слой (libc/bgi/*.c в
+sprinter.lib), режим задаёт driver-архив; выбор линковкой через
+`sprinter-cc --gfx 256` (16 — позже, тем же leaf-split'ом; см.
+memory/bgi_two_lib_design).
+
+**Фаза 1 (256, реализовано и проверено в MAME — tests/bgitest):**
+initgraph/closegraph/graphresult/cleardevice, setcolor/getcolor/
+setbkcolor/getbkcolor, getmaxx/getmaxy/getmaxcolor, putpixel/getpixel,
+moveto/moverel/getx/gety, line/lineto/linerel, rectangle, bar, circle,
+outtext/outtextxy.  initgraph грузит EGA-палитру 0..15.  Пакетные
+примитивы (circle) — одна W3-скобка на весь примитив (raw-плот), иначе
+на порядок медленнее.
+
+**Фаза 2a/2b/2c ГОТОВЫ (2026-07-08, проверено в MAME tests/bgitest):**
+- 2a: arc, ellipse, drawpoly (Q7-тригонометрия, БЕЗ 32-бит).
+- 2b: setfillstyle/getfillsettings + 10 паттернов Borland, bar (с
+  паттерном), bar3d, fillpoly (scanline min/max), fillellipse (isqrt).
+- 2c: floodfill (scanline span; медленный — self-bracket чтение, но
+  корректный), pieslice, sector.
+
+**Фаза 2d-1/2/3 ГОТОВЫ (2026-07-08, MAME tests/bgitest):**
+- 2d-1: getimage/putimage/imagesize (COPY/XOR/OR/AND/NOT_PUT), raw-блит
+  в одной W3-скобке (_gfx_getpixel256_raw).
+- 2d-2: setlinestyle/getlinesettings (SOLID/DOTTED/CENTER/DASHED/USERBIT
+  + NORM/THICK) — line/lineto/linerel/rectangle/drawpoly.
+- 2d-3: settextstyle/gettextsettings/textwidth/textheight — масштаб
+  1..10, HORIZ/VERT, прозрачный фон (свой scaled-рендер поверх 8×8).
+
+**Фаза 2d (осталось):** setviewport/clearviewport + клиппинг (инвазивно —
+трогает все примитивы), settextjustify, setaspectratio (пиксели 320×256
+неквадратные — круги визуально эллиптичны), setfillpattern (USER_FILL),
+setactivepage/setvisualpage (2 страницы в gfx уже есть).  Оптимизации:
+floodfill на raw-чтении; ellipse/arc в одной W3-сессии.  Потом drv16 +
+sprinter_gfx16.lib (--gfx 16).
+Acceptance: типичная BGI-программа переносится без существенных
+правок.  Референс: Turbo C 2.x BGIDEMO.
+
+### IM2 Interrupt Handlers — Phase 1 ГОТОВ (2026-07-06, libc/irq, tests/irqtest; Phase 2: CBL/ISA/цепочки)
+
+User-ISR через IM 2 — timer ticks, музыка (AY/COVOX), real-time
+игры, async input.  Phase 1 реализован БЕЗ отдельного memory mode:
+libc/irq (<irq.h>: irq_install/irq_remove), таблица в BSS с runtime-
+выравниванием, jp-заглушка внутри таблицы, чейн к DSS всегда;
+работает в tiny/big, в small/huge — EINVAL.  Детали и отличия от
+исходного плана: docs/im2_isr_design.md.
+
+### Прочее v2
+
+- [ ] **Audio API** — AY-3-8910 + COVOX (требует IM2)
+- [ ] **ISA-8 slot support** — ZX-Bus карты (требует IM2)
+
+## GFX: расширения по accelerator_doc.txt
+
+Quick wins:
+- [ ] block-size через `LD A,(nn)` вместо SMC (док разрешает LD A,(HL/BC/DE))
+- [ ] кэширование block-size между burst'ами (accel помнит размер)
+
+Новые возможности:
+- [x] ~~пакетное чтение/запись массива байт через акселератор~~ —
+      сделано 2026-07-11 (Фаза A спрайтового дизайна,
+      docs/sprite-api-design.md): leaf `_bgi_copy_rows_raw` (accel
+      block-copy LD L,L, до 256 байт/burst, размер блока армируется
+      один раз) + ядро `gfx_blit_part` (клиппинг, полосы ≤256);
+      putimage(COPY_PUT) и getimage переведены (регресс tests/bgi_img
+      1:1 с per-pixel эталоном, подрежимы банков на accel-пути —
+      tests/gfxbanks).
+- [ ] **вертикальный copy-leaf `_bgi_copy_cols_raw`** (режим LD A,A —
+      вертикальная копия, Port_Y двигается сам как у vfill).  Анализ
+      2026-07-12: для СПРАЙТОВ требует column-major хранения (читать
+      линейный буфер вертикально нельзя — Port_Y не действует вне
+      видеоокна; референс docs/samples/balls пишет колонками и потому
+      выводит спрайт ТРАНСПОНИРОВАННЫМ — незаметно только на
+      симметричном шаре) → формат несовместим с getimage, не делать.
+      А вот **вертикальный HEAL формат-независим** (экран→экран) и
+      выгоден для узких высоких областей: L-полоска 2×16 при
+      горизонтальном движении спрайта = 2 burst'а вместо 16 (8×
+      меньше оверхеда); выбор ориентации по форме — как в
+      _gfx_rectfill256.  Нюанс: между read и write колонки Port_Y
+      надо вернуть на y0 (стоп → OUT → ре-арм, ~20Т/колонку).
+      Делать вместе с L-strip оптимизацией heal.
+- [ ] **паттерны через акселератор + FF-прозрачность** (идея 2026-07-11):
+      всё, что сейчас рисуется по-пиксельно из-за «дырок», можно гнать
+      burst'ами через банк 0x58 — дырки паттерна кодируются 0xFF и
+      отбрасываются железом на записи:
+      - стилизованные линии (_bgi_styled_line: DOTTED/DASHED/CENTER/
+        USERBIT сейчас per-pixel): построить 16-байтовый шаблон строки
+        из 16-бит маски (бит=цвет, 0=0xFF) и повторять accel-copy;
+      - fill-паттерны (_bgi_fill_span, LTSLASH_FILL и пр.): 8-байтовые
+        строки-шаблоны 8×8 паттерна тем же способом;
+      - ВНИМАНИЕ: на MAME 0.283 запись FF через 0x58 портит теневое
+        ОЗУ (частичный скип, см. sprite-api-design «Результаты Фазы 0»)
+        — включать после подтверждения полного подавления на железе,
+        либо через 0x5C + пере-heal.
+- [x] ~~gfx_blit / putsprite / gfx_heal / movesprite~~ — Фаза B
+      сделана 2026-07-11 (docs/sprite-api-design.md §3): GFX_BANK_*
+      константы + gfx_blit/gfx_blit_part/gfx_heal в gfx.h,
+      putsprite/movesprite в graphics.h; проверено tests/sprites
+      (прозрачность, клиппинг 4 краёв, heal src==dst, чистый след
+      movesprite, атлас).  Осталась Фаза C — пример-курсор.
+- [x] ~~**managed-движок спрайтов v2**~~ — СДЕЛАН 2026-07-12/13
+      (sprite.h: retained-модель + batch-пасс, см. пункт batch-пасса
+      ниже) и расширен: W0-атласы (.atl, atlas_load/atlas_sprite_init,
+      ISR-стаб — §9в), авто-анимация кадровая + tween (sprite_anim/
+      sprite_moveto/sprite_update тикер — §9г), gfx_pal_sync/fload/
+      fsave.  Замерен бюджет: ~26К тактов на спрайт 16×16, лимит 14
+      спрайтов на стабильные 48 fps (§9д); демо examples/space,
+      examples/rpgwalk (+rpgprof — профайлер кадра).
+- [ ] `gfx_xor_rect` / `gfx_or_rect` / `gfx_and_rect` / `gfx_invert_rect`
+- [ ] шрифты ≠ 8×8: gfx_set_font_data(ptr,w,h,advance), proportional,
+      8×16/16×16, отдельный font_id API; font-quad для 640×256
+      (per-cell палитра через дескрипторы 0x0300..0x039F)
+
+Оптимизации (не сейчас):
+- [x] ~~stride-арифметика в _bgi_copy_rows_raw — вон из горячего
+      цикла~~ — сделано 2026-07-12 (профиль examples/balls vs
+      docs/samples/balls): универсальный leaf — SMC-патч страйдов в
+      8-битные add/adc-цепочки при входе (140Т → 73Т/строку, BC/push/
+      pop/ex ушли); heal — отдельный `_bgi_heal_rows_raw` без адресной
+      арифметики вообще (77Т/строку против 204Т; референсный уровень).
+      Шар 16×16: ~9.6 → ~6.6 кТ (heal 16×173 + блит 16×236).  Регресс:
+      blitw/bgi_img/sprites/balls — 1:1.  Остатки разрыва с asm-
+      референсом — C-обвязка вызовов (batch-пасс, см. ниже) и спец-
+      blit-leaf (dstride 0: −30Т/строку — делать по замеру).
+- [x] ~~**batch-пасс для спрайтов** (движок v2, §9.1)~~ — СДЕЛАНО
+      2026-07-12/13: движок v2 (sprite.h: sprite_init/update/flip,
+      retained per-page dirty), два прохода heal→blit под одной
+      W3-скобкой/банком, спец-leaf'ы `_bgi_blit_rows_raw` (dstride 0,
+      SMC sstride) и `_bgi_heal_rows_raw`, лин-ядра ≤64×64, ОДИН DI на
+      спрайт (санкция 2026-07-12), noclip-ядра + funcptr-диспетч
+      `_gfx_blit_fn`/`_gfx_heal_fn` (см. sprite-api-design §9б).
+      Замер dev-MAME 16 шаров uncapped: clip 50 → noclip 60-61 fps
+      (+20-22%); с vsync-капом кадр < 20 мс.  Исходный уровень был
+      24 fps.  (Диагноз разрыва с asm-референсом — per-call C-обвязка,
+      не W3-скобка — и путь оптимизации описаны в sprite-api-design
+      §9-9б.)  На железе перепроверить снятие src[0]-фикса (§9а).
+- [ ] клип fast-path «прямоугольник целиком на экране» в gfx_blit_part
+      (4 сравнения вместо полного пути) — делается в _gfx_blit_full/
+      _gfx_heal_full вместе с batch-пассом.
+- [ ] размер: общий clip-хелпер для gfx_blit_part (528 Б) и gfx_heal
+      (362 Б) — клиппинг сейчас продублирован; кандидат −300..400 Б.
+- [ ] gfx_line через accel для пологих диагоналей (runs ≥ 4-5 px)
+- [ ] композитные примитивы с одним W3-swap на операцию
+- [ ] ~~**спрайт-анимация: heal только открывшейся L-полоски**~~ —
+      ОТВЕРГНУТО 2026-07-12 для ПРОЗРАЧНЫХ спрайтов (наш случай).
+      L-полоска (bbox старой позиции минус новой) корректна ТОЛЬКО для
+      непрозрачного full-box спрайта: тогда зону перекрытия целиком
+      перекрашивает новый блит.  У прозрачного спрайта (0xFF через
+      0x5C) в перекрытии дырки нового кадра НЕ перекрывают старые
+      непрозрачные пиксели → на хвосте остаётся «полумесяц» старого
+      изображения ВНУТРИ bbox-перекрытия, куда L-полоска не достаёт.
+      Точный «новооткрытый» набор = old_opaque AND NOT new_opaque —
+      это heal-с-маской по форме, а не по bbox, на Z80 дороже самого
+      heal.  Подтверждено чтением референса docs/samples/balls:
+      restore_bg лечит ПОЛНЫЙ 16×16 (ld b,16 + 16 байт/строку),
+      L-полоску не использует.  Итог: heal остаётся full-box; экономия
+      только через batch-пасс (амортизация обвязки), не через L-полоску.
+      L-полоска годна лишь для непрозрачных тайлов фона — не спрайтов.
+      Дисциплина «heal ВСЕ → блит ВСЕ» по-прежнему обязательна (слияние
+      heal+блит per-sprite выкусывает соседа на перекрытии — проверено
+      examples/balls 2026-07-11).
+- [ ] **span-примитивы для узких прямоугольников**: при узкой стороне
+      ≤ 8 линий chunked-rectfill проигрывает простому циклу
+      _bgi_hspan_raw/_bgi_vspan_raw (подготовка+precompute ~340Т уходят
+      впустую; break-even n≈9 — docs/accel-fill-budget.md).  Варианты:
+      fast-path в диспетчере _gfx_rectfill256 («узкая сторона ≤ 8 →
+      цикл span'ов») или просто задокументировать рецепт для
+      пользователя.  Делать по результатам профиля — если узкие
+      прямоугольники реально встречаются в горячем коде.
+
+## Прочий backlog
+
+- [ ] **Несколько одновременных экземпляров MAME и MCP bridge (отдельная
+      задача, позже).** Проверить два изолированных процесса с разными
+      дискетами/CHD/state и двумя MCP-сессиями; в протоколе явно связывать
+      команду с PID/session ID, не допускать ответа от чужого процесса,
+      проверить сброс/exit и одновременные команды. До успешного end-to-end
+      теста параллельная работа MAME через MCP не гарантируется.
+- [ ] factoring parse_argv из crt0/crt0_banked в общий argv.s
+- [ ] `restore SP on EXIT` (паттерн z88dk +pps) — проверить нужность
+- [x] ~~CI: MAME с -aviwrite для screenshot-сравнения без человека~~ —
+      `toolchain/mame_interactive.py`: авто-запуск .exe вводом с
+      эмуляцией клавиатуры + Lua-таймер для скриншотов/выхода; сравнение
+      визуальное (Claude читает скриншот), не автоматический diff.
+      Полный справочник: docs/mame-autotest.md.
+- [ ] linker duplicate-symbol warnings: сейчас фильтруются в
+      sprinter-cc (наши overrides _puts/___sdcc_heap/_asctime/…);
+      радикально — --nostdlib с ручным списком модулей z80.lib
+- [ ] ZX Spectrum-совместимый target; ZX-Bus драйверы; PGO-tools
+
+## Проверить на реальном железе
+
+- [ ] **Port_Y banking trick** (адреса 0xC000+0x400*N → строки
+      Y..Y+15): в MAME 0.283 НЕ работает (2026-06-01).  На железе:
+      dual-write тест → если работает, кэшировать Port_Y в putpixel
+      (~8× меньше OUT для Брезенхэма); если нет — вычистить из доков.
+- [ ] **Подрежимы видеостраниц #50..#5F** (tests/gfxbanks +
+      tests/sprites, дизайн docs/sprite-api-design.md): перепрогнать
+      на железе и сверить со скриншотами MAME.  Три открытых вопроса: (1) 0x58 — полное
+      подавление FF-записи (док/master-MAME) или FF протекает в
+      теневое ОЗУ (MAME 0.283)?  (2) FF в VRAM — цвет 255 (MAME) или
+      display-подстановка фона из ОЗУ (тогда дешёвое стирание
+      FF-заливкой, tests/fferase)?  (3) accel-путь = CPU-пути (в ПЛМ
+      пути физически разные).
+- [ ] fdmax: лимит манипуляторов и зависание 9-го OPEN — MAME vs железо.
+- [ ] CBL: щелчок перед первым проигрыванием звука за сессию (tests/
+      cbltest, tests/cblwav) — воспроизводится ТОЛЬКО на первом запуске
+      программы за сессию MAME, не зависит от содержимого потока
+      (тон/тишина/речь одинаково).  Похоже на разовый прогрев звуковой
+      подсистемы MAME при первой активации канала — на реальном железе
+      скорее всего отсутствует.  Проверить и закрыть либо описать как
+      реальный аппаратный эффект.
+- [ ] **CBL: помехи в звуке при движении мыши** (tests/cblstream,
+      2026-07-07) — при потоковом воспроизведении движение мыши даёт
+      слышимые артефакты.  Гипотеза (НЕ подтверждена): мышь может
+      делить SIO-канал/детект-бит с клавиатурой (порт 0x19 бит 0,
+      см. _irq_tramp.c), и трамплин классифицирует байты мыши как
+      «клавиатура» → сразу chain на DSS (0x0038), пропуская проверку
+      CBL-хука для ЭТОГО прерывания — при движении мыши часть тиков,
+      которые должны были обслужить CBL-насос, уходят мимо, кольцо
+      недоливается.  Нужно исследование (MAME-дамп/лог трамплина).
+- [ ] **kbd_raw: частые Rx-overrun в MAME при тапах** (roomtest,
+      2026-07-22) — замеры watchpoint-счётчиками: при стабильном
+      удержании клавиши overrun'ов ноль, но каждый быстрый тап (5 байт:
+      E0 74 + E0 F0 74 при FIFO 3) даёт overrun.
+      **Уточнение 2026-08-01 (по коду драйвера, прежняя гипотеза
+      НЕВЕРНА):** dev-MAME per-byte INT ДАЁТ —
+      `mame/sources/MAME/src/mame/sinclair/sprinter.cpp`
+      `on_kbd_data()` ставит `m_irqs->in_set<1>()` на каждый принятый
+      байт.  Но тут же заводит `m_irq_off_timer` на **32 такта CPU**, и
+      `irq_off()` снимает линию — то есть импульс, пришедшийся на наше
+      DI-окно, теряется НАСОВСЕМ (байт остаётся в FIFO до следующего
+      IRQ или кадрового 50 Гц).  А DI-окна у нас длинные: ядра
+      акселератора держат `di` на весь блит (`libbgi/bgi256/
+      _bgi_blit_cols_raw.c`), это сотни микросекунд против 32 тактов.
+      **Замерено 2026-08-01 (PoP roomtest, счётчики в MAME): обе
+      «наши» гипотезы отпали.**  (а) `kbd_raw_poll()` из главного цикла
+      не меняет ничего (9/10 с ним и без); (б) снятие `di` в accel-ядрах
+      УРОНИЛО машину — режим «акселератор при EI» тут недоступен; и сама
+      длина DI ни при чём (в замороженном кадре без блитов потерь
+      БОЛЬШЕ).  Байт теряется ДО чтения порта: на 49 прочитанных байт
+      только 28 входов в клавиатурную ветку, т.е. ~44 % импульсов
+      запроса не обслужены и 3-байтовый FIFO переполняется.  Главный
+      подозреваемый — `m_irq_off_timer` в sprinter.cpp: он ОДИН на два
+      источника (экран + клавиатура), `irq_off()` гасит обе линии, так
+      что кадровое прерывание способно обрезать клавиатурный импульс.
+      **ЗАКРЫТО в рабочем объёме 2026-08-01:** лечится ПЛОТНЫМ опросом —
+      `kbd_raw_poll` повешен idle-хуком графики (`gfx_set_idle_hook`,
+      новый API libbgi) на ожидание кадра, где процессор всё равно
+      простаивает ~2/3 периода.  35 нажатий с зажатым Shift → 35
+      дошедших make против 9 из 10 без хука.  Пользователь на ручной
+      проверке отмечает, что редкие пропуски всё же ощущаются — остаток
+      отложен до финальной полировки, следующий шаг описан там же.
+      Полный протокол — applications/PoP/roomtest/TASKS_CLOSED.md, KBD-1.
+      Recovery-политика уже терпима к частым overrun'ам (селективный
+      wipe, docs/kbd-games.md), но аккорды «держу →, тапнул ↑» и
+      «держу Shift, тапаю ←» остаются уязвимы.
+
+## Known quirks (зафиксированы, обходы в libc)
+
+- ESTEX $46 ENV: A=0 это NOT FOUND (док врёт) — memory/sprinter_platform
+- ESTEX WRITE $14: на успехе DE=0, не счётчик; успех = CF=0 & A=0 —
+  memory/estex_write_de_quirk
+- DSS: 8 манипуляторов, 9-й OPEN вешает систему; _fd_guard в libc —
+  memory/dss_fd_limit
+- SDCC z80 `if(n!=g)g=n;` пишет (n-g) — memory/sdcc_z80_cmp_store_a_bug
+
+---
+
+# История — закрытые этапы
+
+## Этап 10 — libc: сплит + FILE v2 + Solid-C (2026-07-05/06) ✅
+
+Полный план/итоги: docs/libc-roadmap.md.  Кратко:
+- вся libc разложена «1 функция = 1 модуль» (~250 модулей, wildcard-
+  сборка, DCE на уровне файлов): gfx_text −4.4 КБ, timedir/ls/stattest
+  −3 КБ и т.д.; правила asm-связок: docs/libc-split-asm-cases.md
+- **FILE* v2 (B+)**: ленивый буфер 512 на чтение/запись с
+  автопереключением, таблица OPEN_MAX=8, flush-on-exit, ungetc,
+  fprintf/vfprintf, fdopen/freopen/fclosall/fgetpos/fsetpos; горячие
+  пути fgetc/fputc/fgets на asm (fgets 100 КБ: 144с unbuffered-оценка
+  → ~1 с).  Дизайн: docs/file-buffering-design.md
+- **scanf/fscanf/sscanf** — своё C-ядро (в SDCC z80 нет)
+- **Solid-C совместимость закрыта**: <dos.h> (даты/диски/absread),
+  errno-алиасы, <sprinter_solid.h> — docs/solid_c_compatibility.md
+- гигиена: stale .rel чистка, все 43 теста в make all, размерный
+  регресс (make size-check), контракт заголовков docs/libc-headers.md
+- справочник API: docs/libc-reference.md
+
+## Этап 9 — memory modes (tiny/small/big/huge/manual) ✅ 2026-05-30
+
+`--memory MODE` в sprinter-cc; crt0-семейство (crt0/minimal/small/
+banked); small: ESTEX GETMEM+SETWIN2 до gsinit, auto-detect W2 по
+порту 0xC2; big/huge: параметризация crt0_banked/bank.s через
+BANK_W1; --debug, --stack-size.  Детали: memory/memory_modes_
+implemented, memory/sprinter_memory_modes.
+
+Дизайн-решения: одна sprinter.lib на все режимы (DCE per-member);
+gfx.lib отдельно не нужен; libc_banked + sprinter_home.lib — идея
+на потом (триггер: HOME забит user-кодом).
+
+## Этап 8 — графика ✅
+
+320×256×256 + 640×256×16, акселератор (Fill h/v, SMC block-size),
+Брезенхэм, bitmap font (WIN_GET_ZG, interleaved), gfx_text.
+memory/sprinter_graphics*, sprinter_accelerator, sprinter_font_format.
+
+## Bank-local data ✅
+
+--codeseg/--constseg/--dataseg BANKn + mkexe -p 0; фикс трамплина
+(pop bc/out (c),b — сохраняет A); malloc из банка прозрачен (heap в
+W2).  memory/bank_local_data_pattern.
+
+## Этапы 5-7 и ранняя libc ✅
+
+- malloc/free (SDCC + runtime/heap.s в W2), page allocator
+  (mem_alloc_pages, ESTEX $3C-$3E + BIOS $C4), bank_read/bank_write
+- crt0 argv-парсинг (IX-prefix, CP/M-space quirk, APPINFO basename),
+  sprinter-cc wrapper со всеми опциями
+- errno+strerror/perror, open state-machine, atexit, setjmp/longjmp,
+  sleep, ENV API ($46), ffirst/fnext, getdatetime/setdatetime,
+  chdir/getcwd/mkdir/rmdir, conio (полный), mouse (RST 30h, 14 ф-й),
+  POSIX time API, sys/stat, assert
+- text I/O split (stdio fast / conio attr) — memory/text_output_api_split
+- SDCC stdlib НЕ переписываем — memory/sdcc_stdlib_works

docs/accel-fill-budget.md

@@ -0,0 +1,120 @@
+# Акселератор: бюджет тактов и размеров chunked-заливок (rectfill/clear)
+
+2026-07-10, после рефактора 2c414da (chunked-заливки v3 на мульти-триггере
+акселератора).  Семантика FSM акселератора — memory/accel_multitrigger_fill,
+регресс-тест — tests/accfill.  Такты — стандартные Z80; пересчёт в мкс —
+для 21 МГц без учёта wait-state'ов видеопамяти.
+
+## Архитектура v3 (что считаем)
+
+`_gfx_rectvfill256` / `_gfx_recthfill256`: заливка чанками ≤16 линий на одну
+DI/EI-скобку.  В скобке размер блока армируется один раз; на линию — OUT
+Port_Y (при выключенном акселераторе) + 1 опкод режима (LD E,E / LD C,C) +
+выстрел + LD B,B.  Счётчик чанков precompute'ится один раз на входе в
+байт-регистр E (`n>>4`), хвост `n&15` SMC-патчится в отдельную хвостовую
+скобку со своим армированием (в окне EI между чанками CBL-ISR армирует
+акселератор своим размером блока — поэтому армирование в каждой скобке).
+
+## Бюджет v3
+
+### 1) Подготовка — один раз на прямоугольник (~325–340Т)
+
+| блок                                                  | тактов  |
+|-------------------------------------------------------|---------|
+| пролог: push ix / ld ix,#0 / add ix,sp + база+x + цвет | 102     |
+| SMC размера в обе скобки (19+13+13)                    | 45      |
+| precompute: хвост n&15 → SMC + чанки n>>4 → E          | 108–118 |
+| проверка «есть ли полные чанки»                        | 15–20   |
+| эпилог: pop ix / 3×pop / inc sp / jp (hl)              | 54      |
+
+### 2) На блок 16 линий — 46Т
+
+ld b,#16 (7) + di (4) + арм ld d,d / ld a,#n / ld b,b (15) + ei (4) +
+dec e / jr nz (16) = 46Т ≈ 2.9Т/линию.  Хвостовая скобка ≈ 45Т (заход
+22 + арм 23).
+
+### 3) На линию — 53Т (vertical) / 51Т (horizontal)
+
+ld a,d (4) + out (11) + режим (4) + ld a,c (4) + ld (hl),a (7) +
+ld b,b (4) + inc hl (6) / inc d (4) + djnz (13).
+
+**Формула:** T(n) ≈ 340 + 46·⌈n/16⌉ + 53·n  (vertical; horizontal 51·n).
+
+## Альтернативы: каждая линия в своей DI/EI-скобке
+
+**А — байтовый счётчик в B + djnz** (арм на линию, всё в одном цикле):
+подготовка ~210Т, линия 72Т (h) / 74Т (v).  Ограничение: счётчик ≤ 256 —
+для vertical с w до 320 нужен двухпроходный костыль (~+10 байт).
+Бонус: DI-окно = 1 линия (≤37 мкс) — минимальная латентность прерываний.
+
+**Б — 16-бит счётчик в IX-слотах** (стиль per-line v1, без call):
+подготовка ~190Т, линия ~206Т (135Т из них — декремент+проверка 16-бит
+числа через 19Т-обращения к IX-слотам).
+
+### Тотализатор (vertical, тактов на прямоугольник n линий)
+
+| линий | v3      | А (djnz)  | Б (IX)   |
+|-------|---------|-----------|----------|
+| 1     | ~420    | **~280**  | ~395     |
+| 4     | ~580    | **~500**  | ~1015    |
+| 8     | ~790    | **~785**  | ~1840    |
+| 9     | ~845    | ~855      | ~2045    |
+| 16    | ~1215   | ~1365     | ~3490    |
+| 64    | ~3895   | ~4820     | ~13 375  |
+| 256   | ~14 620 | ~18 640   | ~52 930  |
+
+**Break-even v3 против А: n ≈ 9 линий** (340+53n+2.9n = 210+72n → n≈8.3).
+При n ≤ 8 простейший А быстрее (максимум выигрыша +140Т ≈ 6.7 мкс на n=1 —
+precompute уходит впустую); при n ≥ 9 v3 впереди, дальше ~19Т/линию (~26%
+CPU-оверхеда; полный экран — экономия ~4000Т ≈ 190 мкс).
+Б проигрывает v3 уже с n = 2 — от него и уходили.
+
+## Размер кода (активные инструкции, на один leaf)
+
+| вариант      | байт   | разбивка                                        |
+|--------------|--------|-------------------------------------------------|
+| v3 (текущий) | ~107   | пролог 18 + SMC 9 + precompute 26 + вход 4 + чанк-цикл 21 + хвост 22 + эпилог 7 |
+| А (djnz)     | ~53–63 | пролог 18 + SMC 6 + счётчик 7 + линия 15 + эпилог 7 (+~10 двухпроходность vertical) |
+| Б (IX)       | ~70    | пролог 18 + SMC 6 + цикл 39 + эпилог 7          |
+
+Диспетчер `_gfx_rectfill256` ≈ 40 байт (проверка ориентации 160–245Т,
+break-even |w−h| ≥ ~4 линии — при известной форме звать leaf напрямую).
+Переход пары leaf'ов на А дал бы ~−100 байт на программу ценой −26%
+скорости на n ≥ 9.
+
+**Решение: оставлена v3** — в графическом коде такты дороже сотни байт;
+для узких прямоугольников (≤8 линий) есть span-примитивы
+_bgi_hspan_raw/_bgi_vspan_raw (одна линия одной скобкой без precompute).
+
+## Идеи (не реализовано)
+
+- **Отказаться от поддержки сторон > 256 точек.**  Сейчас vertical тащит
+  ветку «старший байт w = +16 чанков» (precompute) ради 257..320; если
+  ограничить контракт стороной ≤ 256 и оставить пользователю выводить
+  широкие прямоугольники в два приёма самому — упрощается precompute
+  (~−15Т подготовки, −5..8 байт), исчезает UB-зона w>511, контракты
+  обеих leaf-функций становятся симметричными.  Цена: bar() на полную
+  ширину экрана обязан сам разбить вызов на два (или это делает
+  диспетчер — тогда экономии в диспетчерном пути нет, только в прямых
+  вызовах leaf'ов).
+
+- **Два варианта рисования + переключение опцией сборки.**  Реализовать
+  оба: поблочный (v3, быстрый при n ≥ 9, DI-окно ≤0.7 мс) и построчный
+  (А: per-line di/ei + djnz, −100 байт на пару leaf'ов, быстрый при
+  n ≤ 8, DI-окно = 1 линия ≤37 мкс — идеально при активном CBL) — и
+  выбирать опцией сборки в духе существующего GFX_NOCHECK / safe-fast
+  вариантов libbgi.  Кандидат для size-critical сборок (small 32КБ,
+  как mdview2) и для программ с жёсткими требованиями к латентности
+  прерываний.
+
+- **Span-примитивы для узких прямоугольников (узкая сторона ≤ 8).**
+  Break-even n≈9 означает: прямоугольник в 2..8 линий по узкой стороне
+  дешевле нарисовать циклом готовых span-примитивов
+  (_bgi_hspan_raw/_bgi_vspan_raw — одна линия одной скобкой, без
+  подготовки/precompute), чем через rectfill, где ~340Т подготовки
+  уходят впустую.  Варианты: fast-path в диспетчере _gfx_rectfill256
+  («узкая сторона ≤ 8 → цикл span'ов»; удорожает проверку диспетчера
+  на ~20-30Т) или оставить на усмотрение пользователя, задокументировав
+  рецепт.  Делать по результатам профиля — если такие прямоугольники
+  встречаются в горячем коде (рамки, тонкие полосы, разделители).
+  Продублировано в docs/TODO.md (GFX: оптимизации).

docs/bugs/sdcc-z80-ret-const-lost/REPORT-ru.md

@@ -0,0 +1,88 @@
+# SDCC 4.5 z80: `return <константа>` из ветки теряется — функция возвращает мусор
+
+**Компилятор:** SDCC 4.5.0 (z80), флаги `-mz80 --std-c99 --opt-code-size`
+(воспроизводится и с `--no-std-crt0`, и в `__banked`, и без него).
+
+**Симптом.** У функции, возвращающей `uint8_t`, ветка с `return 1;` НЕ кладёт
+1 в A.  Вызывающий читает A (`__sdcccall(1)`: uint8 возвращается в A) и
+получает то, что там осталось от предыдущей операции — то есть мусор.
+
+## Репро
+
+`repro.c` (полный текст рядом; собран в `repro.asm`):
+
+```c
+uint8_t pop_level_guard(uint8_t room, uint8_t *tile, int8_t *dir,
+                        uint8_t *color, uint8_t *skill) __banked
+{
+    if (room < 1 || room > TK_ROOMS) return 0;
+    if (tk_gs_tile[room - 1] < 30) {
+        *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+        return 1;                      /* <-- значение теряется */
+    }
+    if (room == tk_guard_room) {
+        *tile = 11; *dir = 0; *color = 0; *skill = 1;
+        return 1;                      /* <-- и здесь */
+    }
+    return 0;
+}
+```
+
+Сгенерированный хвост второй ветки (`repro.asm`):
+
+```
+;repro.c:15: *tile = 11; *dir = 0; *color = 0; *skill = 1;
+	ld	a, #0x0b
+	ld	(de), a
+	xor	a, a          ; A := 0  (это *dir = 0)
+	ld	(bc), a
+	pop	hl
+	ld	(hl), #0x00
+;repro.c:16: return 1;
+	ex	de,hl
+	pop	hl
+	push	hl
+	push	de
+	ld	(hl), #0x01   ; это *skill = 1, НЕ возврат
+	jr	00108$
+00107$:
+	xor	a, a
+00108$:
+	ld	sp, ix
+	pop	ix
+	ret                   ; A = 0 — вернулась ЛОЖЬ вместо 1
+```
+
+Кода `ld a, #0x01` для самого `return 1` нет ни в одной из двух веток.
+
+## Когда прячется, когда стреляет
+
+Баг присутствует и БЕЗ `__banked`, но там часто маскируется: если последним
+в ветке A случайно оказался ненулевой байт (например `ld a,#0x0b` для
+`*tile = 11`), вызывающий с проверкой «истина/ложь» получает правильный
+ответ.  `__banked` меняет распределение регистров (указатели уезжают в
+IX-кадр, `*dir = 0` компилируется в `xor a,a`), A обнуляется — и та же
+функция начинает возвращать 0 вместо 1.
+
+Именно так это и вылезло у нас: набор `tests-host/t_char` годами был зелёным
+и покраснел ровно в тот момент, когда стаб пометили `__banked` — хотя код
+стаба не менялся.
+
+## Обход
+
+Один выход и явная переменная результата (`workaround.c` / `workaround.asm`):
+
+```c
+uint8_t res = 0;
+...
+    res = 1;
+...
+return res;      /* -> ld a, -5 (ix) — корректно */
+```
+
+## Признак для аудита
+
+Грепать функции, у которых `return <константа>` стоит в ветке, где
+последней операцией была запись по указателю или `xor a,a`.  Проверять по
+сгенерированному `.asm`: перед `jr` на общий выход обязан быть `ld a,#…`
+(или загрузка результата), иначе возврат — мусор.

docs/bugs/sdcc-z80-ret-const-lost/repro.asm

@@ -0,0 +1,140 @@
+;--------------------------------------------------------
+; File Created by SDCC : free open source ISO C Compiler
+; Version 4.5.0 #15242 (Mac OS X x86_64)
+;--------------------------------------------------------
+	.module bt2
+	
+	.optsdcc -mz80 sdcccall(1)
+;--------------------------------------------------------
+; Public variables in this module
+;--------------------------------------------------------
+	.globl b_pop_level_guard
+	.globl _pop_level_guard
+	.globl _tk_gs_tile
+	.globl _tk_guard_room
+;--------------------------------------------------------
+; special function registers
+;--------------------------------------------------------
+;--------------------------------------------------------
+; ram data
+;--------------------------------------------------------
+	.area _DATA
+_tk_guard_room::
+	.ds 1
+_tk_gs_tile::
+	.ds 8
+;--------------------------------------------------------
+; ram data
+;--------------------------------------------------------
+	.area _INITIALIZED
+;--------------------------------------------------------
+; absolute external ram data
+;--------------------------------------------------------
+	.area _DABS (ABS)
+;--------------------------------------------------------
+; global & static initialisations
+;--------------------------------------------------------
+	.area _HOME
+	.area _GSINIT
+	.area _GSFINAL
+	.area _GSINIT
+;--------------------------------------------------------
+; Home
+;--------------------------------------------------------
+	.area _HOME
+	.area _HOME
+;--------------------------------------------------------
+; code
+;--------------------------------------------------------
+	.area _CODE
+;bt2.c:6: uint8_t pop_level_guard(uint8_t room, uint8_t *tile, int8_t *dir,
+;	---------------------------------
+; Function pop_level_guard
+; ---------------------------------
+	b_pop_level_guard	= 0
+_pop_level_guard::
+	call	___sdcc_enter_ix
+	push	af
+	push	af
+;bt2.c:9: if (room < 1 || room > TK_ROOMS) return 0;
+	ld	a, 7 (ix)
+	sub	a, #0x01
+	jr	C, 00101$
+	ld	a, #0x08
+	sub	a, 7 (ix)
+	jr	NC, 00102$
+00101$:
+	xor	a, a
+	jr	00108$
+00102$:
+;bt2.c:10: if (tk_gs_tile[room - 1] < 30) {
+	ld	bc, #_tk_gs_tile+0
+	ld	a, 7 (ix)
+	dec	a
+	ld	l, a
+	rlca
+	sbc	a, a
+	ld	h, a
+	add	hl, bc
+	ld	l, (hl)
+;bt2.c:11: *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+	ld	e, 8 (ix)
+	ld	d, 9 (ix)
+	ld	c, 10 (ix)
+	ld	b, 11 (ix)
+	ld	a, 12 (ix)
+	ld	-4 (ix), a
+	ld	a, 13 (ix)
+	ld	-3 (ix), a
+	ld	a, 14 (ix)
+	ld	-2 (ix), a
+	ld	a, 15 (ix)
+	ld	-1 (ix), a
+;bt2.c:10: if (tk_gs_tile[room - 1] < 30) {
+;bt2.c:11: *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+	ld	a,l
+	cp	a,#0x1e
+	jr	NC, 00105$
+	ld	(de), a
+	xor	a, a
+	ld	(bc), a
+	pop	hl
+	ld	(hl), #0x00
+;bt2.c:12: return 1;
+	ex	de,hl
+	pop	hl
+	push	hl
+	push	de
+	ld	(hl), #0x01
+	jr	00108$
+00105$:
+;bt2.c:14: if (room == tk_guard_room) {
+	ld	a, 7 (ix)
+	ld	hl, #_tk_guard_room
+	sub	a, (hl)
+	jr	NZ, 00107$
+;bt2.c:15: *tile = 11; *dir = 0; *color = 0; *skill = 1;
+	ld	a, #0x0b
+	ld	(de), a
+	xor	a, a
+	ld	(bc), a
+	pop	hl
+	ld	(hl), #0x00
+;bt2.c:16: return 1;
+	ex	de,hl
+	pop	hl
+	push	hl
+	push	de
+	ld	(hl), #0x01
+	jr	00108$
+00107$:
+;bt2.c:18: return 0;
+	xor	a, a
+00108$:
+;bt2.c:19: }
+	ld	sp, ix
+	pop	ix
+	ret
+	.area _CODE
+	.area _INITIALIZER
+	.area _CABS (ABS)

docs/bugs/sdcc-z80-ret-const-lost/repro.c

@@ -0,0 +1,19 @@
+#include <stdint.h>
+#define TK_ROOMS 8
+uint8_t  tk_guard_room;
+uint8_t  tk_gs_tile[TK_ROOMS];
+
+uint8_t pop_level_guard(uint8_t room, uint8_t *tile, int8_t *dir,
+                        uint8_t *color, uint8_t *skill) __banked
+{
+    if (room < 1 || room > TK_ROOMS) return 0;
+    if (tk_gs_tile[room - 1] < 30) {
+        *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+        return 1;
+    }
+    if (room == tk_guard_room) {
+        *tile = 11; *dir = 0; *color = 0; *skill = 1;
+        return 1;
+    }
+    return 0;
+}

docs/bugs/sdcc-z80-ret-const-lost/workaround.asm

@@ -0,0 +1,142 @@
+;--------------------------------------------------------
+; File Created by SDCC : free open source ISO C Compiler
+; Version 4.5.0 #15242 (Mac OS X x86_64)
+;--------------------------------------------------------
+	.module bt4
+	
+	.optsdcc -mz80 sdcccall(1)
+;--------------------------------------------------------
+; Public variables in this module
+;--------------------------------------------------------
+	.globl b_pop_level_guard
+	.globl _pop_level_guard
+	.globl _tk_gs_tile
+	.globl _tk_guard_room
+;--------------------------------------------------------
+; special function registers
+;--------------------------------------------------------
+;--------------------------------------------------------
+; ram data
+;--------------------------------------------------------
+	.area _DATA
+_tk_guard_room::
+	.ds 1
+_tk_gs_tile::
+	.ds 8
+;--------------------------------------------------------
+; ram data
+;--------------------------------------------------------
+	.area _INITIALIZED
+;--------------------------------------------------------
+; absolute external ram data
+;--------------------------------------------------------
+	.area _DABS (ABS)
+;--------------------------------------------------------
+; global & static initialisations
+;--------------------------------------------------------
+	.area _HOME
+	.area _GSINIT
+	.area _GSFINAL
+	.area _GSINIT
+;--------------------------------------------------------
+; Home
+;--------------------------------------------------------
+	.area _HOME
+	.area _HOME
+;--------------------------------------------------------
+; code
+;--------------------------------------------------------
+	.area _CODE
+;bt4.c:6: uint8_t pop_level_guard(uint8_t room, uint8_t *tile, int8_t *dir,
+;	---------------------------------
+; Function pop_level_guard
+; ---------------------------------
+	b_pop_level_guard	= 0
+_pop_level_guard::
+	call	___sdcc_enter_ix
+	ld	hl, #-5
+	add	hl, sp
+	ld	sp, hl
+;bt4.c:9: uint8_t res = 0;
+	ld	-5 (ix), #0x00
+;bt4.c:10: if (room < 1 || room > TK_ROOMS) return 0;
+	ld	a, 7 (ix)
+	sub	a, #0x01
+	jr	C, 00101$
+	ld	a, #0x08
+	sub	a, 7 (ix)
+	jr	NC, 00102$
+00101$:
+	xor	a, a
+	jr	00109$
+00102$:
+;bt4.c:11: if (tk_gs_tile[room - 1] < 30) {
+	ld	bc, #_tk_gs_tile+0
+	ld	a, 7 (ix)
+	dec	a
+	ld	l, a
+	rlca
+	sbc	a, a
+	ld	h, a
+	add	hl, bc
+	ld	l, (hl)
+;bt4.c:12: *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+	ld	c, 8 (ix)
+	ld	b, 9 (ix)
+	ld	e, 10 (ix)
+	ld	d, 11 (ix)
+	ld	a, 12 (ix)
+	ld	-4 (ix), a
+	ld	a, 13 (ix)
+	ld	-3 (ix), a
+	ld	a, 14 (ix)
+	ld	-2 (ix), a
+	ld	a, 15 (ix)
+	ld	-1 (ix), a
+;bt4.c:11: if (tk_gs_tile[room - 1] < 30) {
+;bt4.c:12: *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+	ld	a,l
+	cp	a,#0x1e
+	jr	NC, 00107$
+	ld	(bc), a
+	xor	a, a
+	ld	(de), a
+	ld	l, -4 (ix)
+	ld	h, -3 (ix)
+	ld	(hl), #0x00
+	ld	l, -2 (ix)
+	ld	h, -1 (ix)
+	ld	(hl), #0x01
+;bt4.c:13: res = 1;
+	ld	-5 (ix), #0x01
+	jr	00108$
+00107$:
+;bt4.c:14: } else if (room == tk_guard_room) {
+	ld	a, 7 (ix)
+	ld	hl, #_tk_guard_room
+	sub	a, (hl)
+	jr	NZ, 00108$
+;bt4.c:15: *tile = 11; *dir = 0; *color = 0; *skill = 1;
+	ld	a, #0x0b
+	ld	(bc), a
+	xor	a, a
+	ld	(de), a
+	ld	l, -4 (ix)
+	ld	h, -3 (ix)
+	ld	(hl), #0x00
+	ld	l, -2 (ix)
+	ld	h, -1 (ix)
+	ld	(hl), #0x01
+;bt4.c:16: res = 1;
+	ld	-5 (ix), #0x01
+00108$:
+;bt4.c:18: return res;
+	ld	a, -5 (ix)
+00109$:
+;bt4.c:19: }
+	ld	sp, ix
+	pop	ix
+	ret
+	.area _CODE
+	.area _INITIALIZER
+	.area _CABS (ABS)

docs/bugs/sdcc-z80-ret-const-lost/workaround.c

@@ -0,0 +1,19 @@
+#include <stdint.h>
+#define TK_ROOMS 8
+uint8_t  tk_guard_room;
+uint8_t  tk_gs_tile[TK_ROOMS];
+
+uint8_t pop_level_guard(uint8_t room, uint8_t *tile, int8_t *dir,
+                        uint8_t *color, uint8_t *skill) __banked
+{
+    uint8_t res = 0;
+    if (room < 1 || room > TK_ROOMS) return 0;
+    if (tk_gs_tile[room - 1] < 30) {
+        *tile = tk_gs_tile[room - 1]; *dir = 0; *color = 0; *skill = 1;
+        res = 1;
+    } else if (room == tk_guard_room) {
+        *tile = 11; *dir = 0; *color = 0; *skill = 1;
+        res = 1;
+    }
+    return res;
+}

docs/fast_ram.md

@@ -0,0 +1,289 @@
+# Fast RAM (Быстрое ОЗУ / «КЭШ-ОЗУ») на Sprinter
+
+Сводка по результатам изучения документации платформы. Источники:
+
+- `docs/converted/Architecture.txt` — официальное «Описание архитектуры» (раздел
+  «Распределение основной памяти»).
+- `docs/converted/ARHITECT.txt` — ранняя редакция того же документа (про загрузку
+  конфигураций ППЛМ).
+- `docs/converted/IvanMak.txt` / `docs/converted/Parinov.txt` / `docs/converted/Forum.txt`
+  и `docs/part2/forum.txt` — форумные ответы Дениса Паринова (Sprinter Team) и
+  руководство Ивана Мака (раздел «7 КЭШ-ОЗУ»).
+- `docs/part2/accelerator_doc.txt` — ограничение акселератора.
+- `docs/samples/sprinterIntLib.asm` — практический пример temporary-off / restore.
+
+> **Терминология.** В документации одно и то же ОЗУ называется тремя именами:
+> **Fast RAM**, **Быстрое ОЗУ** и **«КЭШ-ОЗУ»**. Это *не* кэш в формальном смысле
+> (нет автоматического заполнения/вытеснения) — это отдельный массив статической
+> памяти, в котором процессор работает на полной частоте **без тактов ожидания**.
+> Имя «КЭШ» — историческое, по аналогии с кэшем на КР537РУ10 в Pentagon-128.
+
+---
+
+## 1. Что это и зачем
+
+* **Объём:** 64 КБ статической памяти (SRAM), отдельной от основного DRAM-SIMM
+  (4 МБ) и от видео-ОЗУ (256 КБ).
+* **Скорость:** процессор обращается к Fast RAM на полной тактовой частоте
+  (21 МГц) **без wait-state'ов**. Основное ОЗУ (DRAM) требует тактов ожидания,
+  поэтому код и данные в Fast RAM исполняются/читаются заметно быстрее.
+* **Назначение:** разместить «горячий» код или данные (внутренние циклы,
+  таблицы, буферы), которые критичны по скорости.
+* **Системная роль:** Fast RAM также используется механизмом
+  переконфигурирования ППЛМ — именно в неё BIOS грузит данные новой
+  конфигурации и флаг `ACEX_30K_LOADING` (старое имя `FLEX_10K_LOADING`) перед
+  программным сбросом. Поэтому к Fast RAM нельзя относиться как к «своей» памяти,
+  которая всегда сохраняется (см. §5).
+
+---
+
+## 2. Карта физических страниц
+
+Память делится на 16 КБ-блоки с однобайтовым физическим номером:
+
+| Тип памяти    | Физические номера страниц |
+|---------------|---------------------------|
+| Основное ОЗУ  | `#00..#4F`, видео-область `#50..#5F`, ... |
+| ПЗУ (ROM)     | `#E0..#EF`                |
+| **Fast RAM**  | `#F0..#FF`                |
+
+> Хотя диапазон номеров Fast RAM — `#F0..#FF` (16 значений), **реально
+> используются только биты 1 и 2** номера страницы. То есть адресуются 4
+> страницы × 16 КБ = **64 КБ**: `#F0`, `#F2`, `#F4`, `#F6`.
+
+---
+
+## 3. Как включать Fast RAM
+
+Есть **два способа** подключить Fast RAM в адресное пространство Z80.
+
+### Способ A. Pentagon-style через порт `#FB` / `#7B` (в окно 0)
+
+Включается «как кэш в Pentagon»: подключает 16 КБ Fast RAM в **окно 0**
+(`#0000..#3FFF`) вместо ПЗУ. Переключение — *побочный эффект чтения порта*
+(значение в `A` после `IN` — мусор, важен сам факт обращения):
+
+```asm
+        DI
+        IN   A,(#FB)    ; включить Fast-RAM — 16 КБ в окно 0 (#0000..#3FFF)
+        ; ... ваш код / работа с Fast RAM ...
+        IN   A,(#7B)    ; выключить Fast-RAM (вернуть ПЗУ в окно 0)
+        EI
+```
+
+* `IN A,(#FB)` — **включить**.
+* `IN A,(#7B)` — **выключить**.
+
+> **Конфликт портов.** Порт `#FB` (и `#4F`) — это также порт COVOX/Blaster-а.
+> Вывод (`OUT`) в `#FB` управляет звуком, а *чтение* (`IN`) — переключает
+> Fast RAM. Не путать направления обращения.
+
+### Способ B. Как ПЗУ — через PAGE0 (`#82`) + порт `#1FFD`
+
+Fast RAM-страница (`#F0..#FF`) выбирается в PAGE0 и подключается на место ПЗУ
+в окно 0 через спец-порт `#1FFD`:
+
+```asm
+        ; выбрать физическую страницу Fast RAM в PAGE0
+        LD   A, #F0          ; номер страницы Fast RAM
+        OUT  (#82), A        ; PAGE0 = страница в окно 0
+
+        LD   A,1             ; 1 → ОЗУ (выбранная страница) в #0000..#3FFF
+        LD   BC,#1FFD
+        OUT  (C),A
+        ; ...
+        LD   A,0             ; 0 → вернуть ПЗУ в #0000..#3FFF
+        LD   BC,#1FFD
+        OUT  (C),A
+```
+
+* Порты PAGE: `PAGE0=#82`, `PAGE1=#A2`, `PAGE2=#C2`, `PAGE3=#E2`.
+  **Чтение** порта PAGE возвращает текущий номер страницы.
+* Эти адреса портов формально могут отличаться в других конфигурациях ППЛМ —
+  правильнее запрашивать их у BIOS и сверять (см. `docs/part2/bios_doc.txt`,
+  ~строка 1033).
+
+---
+
+## 4. Преимущества
+
+1. **Скорость без wait-state.** Главное и единственное предназначение — код и
+   данные исполняются на полной частоте 21 МГц без тактов ожидания, в отличие от
+   основного DRAM.
+2. **Идеально для горячих участков.** Внутренние циклы, lookup-таблицы,
+   временные буферы рендера — то, к чему обращаются интенсивно и многократно.
+3. **Отдельный массив.** Не отнимает страницы основного 4 МБ ОЗУ и не пересекается
+   с видео-областью.
+
+---
+
+## 5. Ограничения и подводные камни ⚠️
+
+Это **самая важная часть** — Fast RAM небезопасна в обращении и легко даёт
+«молча не работает».
+
+1. **Акселератор НЕ работает с Fast RAM.**
+   Акселератор поддерживает пересылку блоков только для основного ОЗУ и
+   видео-ОЗУ. Пересылку **ROM и FastRAM он не поддерживает**. То есть нельзя
+   использовать accel-Fill/Copy для заполнения или копирования в/из Fast RAM —
+   только обычные `LD`-циклы процессора.
+
+2. **Содержимое не сохраняется между процессами.**
+   Fast RAM может быть использована другими программами. При запуске любого
+   процесса через DSS (а также самим механизмом переконфигурирования ППЛМ)
+   **содержимое Fast RAM может быть затёрто**. Нельзя рассчитывать на
+   персистентность данных между вызовами системы.
+
+3. **Перед вызовами DSS и BIOS Fast RAM надо ОТКЛЮЧАТЬ.**
+   Системные функции рассчитывают на стандартную карту памяти (ПЗУ в окне 0).
+   Вызывать `RST 10h` (ESTEX/DSS) или `RST 8` (BIOS) при включённой Fast RAM в
+   окне 0 — нельзя.
+
+4. **Прерывания.**
+   Fast RAM (способ A) подключается в окно 0, перекрывая ПЗУ и системный вектор.
+   Если используются прерывания, программа **обязана установить свой обработчик
+   по адресу `#0038`**. На практике работу с Fast RAM ведут с `DI`, а на время
+   ожидания кадра/`halt` Fast RAM временно выключают и восстанавливают (см. §6).
+
+5. **Окно 0 занято под DSS.**
+   В нашем C-toolchain'е окно 0 (`#0000..#3FFF`) — это ESTEX/DSS система
+   (см. `release_docs/ru/platform_reference.md`). Подключение Fast RAM в окно 0
+   вытесняет именно её, что усиливает требование п.3.
+
+6. **Конфликт `#FB` с COVOX.** См. §3, способ A.
+
+---
+
+## 6. Канонический паттерн temporary-off / restore
+
+Из реального резидента (`docs/samples/sprinterIntLib.asm`): перед `ei: halt`
+(ожидание кадрового прерывания) Fast RAM временно выключается, после —
+восстанавливается прежнее состояние:
+
+```asm
+_intWaitVsyncSys
+        call  memCacheOffTemporary   ; временно выключаем Fast RAM
+        ei
+        halt
+        jp    memCacheRestoryState   ; восстанавливаем прежнее состояние подключения
+```
+
+Идея паттерна: библиотека хранит флаг «было ли Fast RAM включено», умеет
+безопасно его снять на время системных операций (прерывания, DSS/BIOS) и вернуть
+обратно. При интеграции в C-toolchain эту логику следует обернуть так же:
+сохранять состояние, отключать вокруг любого `RST`/`halt`, восстанавливать.
+
+---
+
+## 7. Выводы для нашего C-toolchain (SDCC + target-слой)
+
+* **Из коробки сейчас не используется.** В `runtime/`, `lib/`, `libc/` обращений
+  к Fast RAM нет (порт `#FB`/`#7B` нигде не задействован под эту задачу).
+* **Где могло бы пригодиться:** разместить «горячую» функцию или таблицу в
+  Fast RAM для ускорения. Но 64 КБ перекрывают окно 0, конфликтуют с DSS и не
+  переживают системные вызовы — это узкоспециализированный, ручной режим, не
+  кандидат на общий механизм линковки.
+* **Реалистичный сценарий:** короткий самодостаточный inner-loop без вызовов
+  системы, с `DI`, со своим вектором `#0038`, скопированный в Fast RAM обычным
+  `LD`-циклом (не акселератором), исполняемый из окна 0, с гарантированным
+  восстановлением карты памяти перед любым `RST`.
+* **Несовместимость с акселератором** означает, что для графики/блочных операций
+  Fast RAM бесполезна — там выигрывает accel по основному/видео-ОЗУ.
+
+Если будем добавлять поддержку — делать это отдельным opt-in механизмом
+(по аналогии с banked-режимами), с обязательной обёрткой off/restore вокруг всех
+точек входа в систему.
+
+---
+
+## 8. Разбор двух предложений по спрайтовому движку (обсуждение 2026-07-14)
+
+Итог двух обсуждений (эмуляция FastRAM в dev-MAME подтверждена
+разработчиками MAME как полная).
+
+### 8.1. Предложение «W0/FastRAM как код-банк `__banked`»
+
+Идея: выделить 1-2 FastRAM-страницы в crt0, научиться размещать в них
+`__banked`-код с целью W0 и контрактом «такой код не зовёт DSS/BIOS»;
+критичным функциям указывать размещение в W0/FastRAM.
+
+**Framing правильный** (переиспользовать трамплин `__banked` +
+контракт), но W0-банк — НЕ «ещё один bank id», а тяжелее по трём осям:
+
+1. **Своп W0 сносит всё окно 0 с RST-векторами** (ESTEX RST10, BIOS
+   RST8, IM1 RST38, RST0). Пока FastRAM в W0: сисколлы невозможны (это
+   и есть контракт — ок), но прерывание фатально (`#0038` → мусор
+   FastRAM) → обязателен `DI` на весь интервал. `DI` бьёт ISR-счётчик
+   кадров (см. FPS-делитель, [[sprite-engine-perf]]).
+2. **Загрузку нельзя сделать как в `crt0_banked`** (там `ESTEX READ`
+   прямо в окно, строки 165-173): сам READ вектрится через W0. Нужен
+   2-шаг — READ в DRAM-буфер, затем `DI` + FastRAM в W0 + **`LD`-копия**
+   (акселератор с FastRAM не работает!) + выкл. Плюс FastRAM затирается
+   запуском дочернего DSS-процесса — нужна перезагрузка.
+3. **16 КБ окно против 64 КБ**: кросс-страничные вызовы внутри FastRAM
+   тянут вложенный W0-своп. Вызовы в W1/W2/W3 — свободны (те окна
+   замаплены).
+
+Плюс **пер-вызовная такса трамплина** (~40-60Т: DI/toggle/EI/restore)
+съедает выигрыш именно на горячих inner-листьях, которые от FastRAM
+выигрывают больше всего. Per-function `__banked` — неправильная
+гранулярность.
+
+**Выгода** мала: FastRAM ускоряет только выборку инструкций. Из бюджета
+спрайта 19.5К (blit 9.7 + heal 6.4 + тик 3.0) blit и heal —
+акселератор/видео-ОЗУ, не выигрывают; выигрывает только тик+сорт по
+fetch: ~15-20К/кадр ≈ +1 спрайт (3-4% бюджета в самом узком месте).
+
+**Рекомендация:** если вообще трогать — модель «горячий остров», а не
+«функция-в-банке»: одна 16-КБ FastRAM-страница с самодостаточным
+кластером (тик + сортировщик + их листья), вход один раз за кадр через
+единственную обёртку `DI / своп-в / вызов / своп-обратно / EI`, внутри
+острова обычные `call`, никаких RST. Убирает таксу, сводит связку с
+прерываниями к одному DI-интервалу на кадр (мы и так HALT-ждём между
+кадрами; ISR-счётчик кадров тикает во время HALT-ожидания ПОСЛЕ EI, а
+не во время острова → совместимо с FPS-делителем, пока остров < 1
+кадра).
+
+### 8.2. Данные в FastRAM вместо кода?
+
+Вывод неожиданный: **для нашей нагрузки данные — более СЛАБЫЙ рычаг,
+чем код.** Wait-state вставляется на КАЖДЫЙ доступ к DRAM, а на Z80
+большинство обращений к памяти — выборка инструкций, не операндов. Тик
+= IX-индексный код (`ld a,(ix+d)` — DD-префикс: 3 байта fetch + 1 байт
+данных) → ¾ штрафа на fetch, ¼ на операнде. Значит `sprite_t` в FastRAM
+убирает лишь ¼, а код тика — ¾.
+
+По данным движка:
+- **Пиксели/атласы — жёсткое НЕТ** (их читает акселератор; с FastRAM не
+  работает → блит откатился бы на LD-циклы).
+- **Массив `sprite_t` — не стоит:** тик его трогает, но выигрыш мал (см.
+  выше), а хуже того — его читают и heal/blit под акселератор, которым
+  нужна нормальная карта памяти. `sprite_t` в W0-FastRAM → весь
+  `sprite_update` под `DI` + непроверенный вопрос «работает ли
+  акселератор при W0=FastRAM». Не кандидат, пока это не подтверждено
+  артефактом в MAME.
+- **Таблица Y-сорта + чисто-CPU скретч — да, но не отдельное решение:**
+  живут в той же 16-КБ странице «горячего острова» с кодом сортировщика
+  (сорт не трогает ни акселератор, ни сисколлы). Отдельного рычага
+  «данные» тут нет.
+
+**Единственный сильный независимый кейс для данных-в-FastRAM:**
+CPU-bound алгоритм с большим LUT случайного доступа (fetch внутреннего
+цикла крошечный, чтений таблицы — тьма). У движка такого нет (тяжёлая
+графика = акселератор). Но если добавим CPU-side эффект (программный
+per-pixel шейдинг, палитровый remap, софт-скейлер) — его LUT станет
+главным кандидатом на FastRAM-данные. На будущее.
+
+**Ограничения именно для FastRAM-данных:** лежат в окне 0
+(#0000-#3FFF) → буфер под BIOS/ESTEX туда нельзя (нужно #4000-#BFFF);
+стек остаётся в W2; не переживают дочерний DSS-процесс; заполняются
+только `LD`-копией (акселератор мимо).
+
+### 8.3. Общий вердикт
+
+Оба варианта реализуемы, но бьют по 3-4% бюджета в самом узком месте
+(тик+сорт fetch), мимо доминирующих blit/heal. Остаётся **последним
+резервом** ([[fast_ram]] в памяти). Перед любой реализацией — дешёвый
+бенч в dev-MAME: один и тот же CPU-loop в DRAM vs FastRAM по
+`totalcycles`, чтобы измерить реальный коэффициент wait-state, который
+эмулятор моделирует, и подтвердить, что овчинка стоит выделки.

docs/file-buffering-design.md

@@ -0,0 +1,161 @@
+# FILE*: буферизация — анализ solid-c и варианты (2026-07-06)
+
+Статус: **вариант B+ РЕАЛИЗОВАН 2026-07-06** (решение пользователя).
+Единый ленивый буфер BUFSIZ=512 на чтение/запись с автопереключением
+направления (_F_DIROUT), статическая таблица OPEN_MAX=8 слотов
+(без malloc для FILE), _fclosall через atexit, ungetc через hold,
+fprintf/vfprintf через vsprintf+fwrite, fflush(NULL) = все потоки.
+Внутренности: libc/file/_file.h (+_file_sync/_file_buf/_file_slots/
+_fclosall).  Фактическая цена: filetest 7411→9929 Б _CODE (доля
+только-читающих потребителей ~+1.3 КБ, включая malloc); программы
+без FILE* не платят.  Верификация: MAME filetest + fdmax + fbench.
+Ниже — исходный анализ, на основании которого принималось решение.
+
+## Как сделано в solid-c (SRC/CLIB/STDIO.ASM)
+
+Структура FILE — 14 байт, статический массив `_iob[8]` (без malloc
+для самих FILE; псевдопотоки stdout/stderr/stdaux/stdprn лежат ПЕРЕД
+массивом и адресуются отрицательными индексами — трюк, нам не нужен):
+
+    flags(2), level(2), curp(2), fd(2), buffer(2), hold(1), token(2), dummy(1)
+
+Механика:
+
+- **Буфер 512 Б, ленивый malloc** при первом буферизуемом fgetc/fputc
+  (флаг `_F_BUF` = «буфер наш, free при fclose»).  Программа без
+  файлового I/O не платит ничего.
+- **Чтение** (`_fgetc`): `level == 0` → `read(fd, buffer, 512)`,
+  `curp = buffer`; отдача — `*curp++`, `level--`; ставится `_F_IN`.
+- **Запись** (`_fputc`): `*curp++ = c`, `level++`; при `level == 512` —
+  fflush (один `write` всего буфера); ставится `_F_OUT`.
+- **Полудуплекс**: fputc при взведённом `_F_IN` — ОШИБКА (не
+  авто-flush); направление сбрасывает только fflush.
+- **fflush входного потока**: `lseek(fd, -level, SEEK_CUR)` — откат
+  непрочитанного readahead, буфер инвалидируется.  Выходного —
+  `write(buffer, level)`.
+- **fseek/ftell** = fflush + голый lseek/ltell по fd (после flush
+  позиция fd совпадает с логической позицией потока).
+- **ungetc**: буфер не пуст → `*--curp = c`; пуст/отсутствует → символ
+  в поле `hold`, `curp` указывает на hold.
+- **fclosall через atexit** — сброс буферов при exit.
+- Консольные потоки минуют буфер (RST-вызовы напрямую).
+- **fread/fwrite — ПОБАЙТОВЫЙ цикл** через _fgetc/_fputc: большие блоки
+  платят call+IY-доступ за каждый байт.  Это слабое место порта.
+
+## Варианты для нас
+
+**A. Полный порт solid-c** (буфер на чтение и запись).
+Плюсы: ускоряются и писатели через fputc/fprintf.  Минусы: полудуплекс
+(«запись после чтения без fflush — ошибка») — источник тонких багов;
+обязателен flush в exit (сцепка atexit+file); больше кода во всех
+модулях; наши блочные fread/fwrite пришлось бы защищать от деградации.
+
+**B. Буферизовать ТОЛЬКО чтение (рекомендую).**
+FILE += `buf(2), level(2), curp(2), hold(2)`; буфер 512 Б лениво.
+
+- fgetc: hold → буфер → refill.  fgets остаётся циклом по fgetc
+  (теперь дешёвым).
+- fread: сначала хвост буфера (memcpy), остаток ≥ 512 — прямой read()
+  в ptr одним syscall (обходя буфер), мелкий остаток — refill.
+- Запись НЕ буферизуется — как сейчас: fputc = write(1 байт),
+  fputs/fwrite = один write() на блок.  Нечего терять при аварии,
+  fflush остаётся no-op по данным, полудуплекса нет.
+- Согласование позиций: перед write/fseek/ftell на потоке с readahead —
+  `lseek(fd, -(level), SEEK_CUR)` + инвалидация буфера (один общий
+  хелпер `_file_sync`).  ftell = lseek(0,CUR) − level (без syscall не
+  выйдет — lseek и так syscall).
+- ungetc: через hold, работает и до первого заполнения буфера.
+
+Плюсы: решает главную боль (парсеры), запись остаётся простой и
+надёжной, никакого flush-on-exit, r+ работает через _file_sync.
+Минусы: fputc-писатели остаются медленными (редкий паттерн — fputs/
+fwrite блочные и так быстрые).
+
+**B+. Единый буфер на чтение И запись с АВТОпереключением направления
+(предложение 2026-07-06, кандидат в целевой дизайн).**
+Схема solid-c, но без ловушки: направление переключает сама библиотека.
+
+- флаг направления в FILE: буфер сейчас «readahead» или «накопитель
+  записи»;
+- fputc при направлении «чтение»: `_file_sync` (отмотка fd на -level,
+  буфер пуст) → режим записи → накопление; сброс write() при
+  заполнении;
+- fgetc при направлении «запись»: flush (write(buf, level)) → режим
+  чтения → refill;
+- fwrite больших блоков: flush + прямой write мимо буфера; мелких —
+  memcpy в буфер.  fread симметрично;
+- fseek/ftell/fclose: flush-или-sync по направлению; ftell = позиция
+  fd − level (чтение) / + level (запись);
+- **обязателен реестр открытых потоков**: поле next в FILE
+  (регистрация в fopen, снятие в fclose) + _fclosall через atexit —
+  стандарт требует flush всех потоков в exit(); без этого
+  `fputs(...); exit(1);` теряет данные;
+- цена-семантика: ошибки записи становятся ОТЛОЖЕННЫМИ (вылезают при
+  flush/fclose, не в момент fputc) — проверять результат fclose;
+- цена-код: ~+350–500 Б против ~+200–300 у B (тянется только
+  использующими FILE*).
+
+**C. Оставить небуферизованным** («большие файлы читаются целиком в
+EMM», паттерн mdview).  Для приложений-парсеров среднего размера
+неудобно; отвергается самим существованием П2-пункта.
+
+**D. Полная стандартная буферизация + setvbuf** — отвергнуто ранее
+решением file_star_design (минимальный FILE*).
+
+## Что взять у solid-c при варианте B
+
+- ленивый malloc 512 Б + флаг «буфер наш»;
+- откат readahead lseek'ом (механика их fflush-на-вход) — как
+  `_file_sync` перед write/fseek/ftell;
+- ungetc с hold-байтом;
+- консольные потоки мимо буфера (у нас уже так).
+
+Чего НЕ брать: побайтовые fread/fwrite, полудуплекс, статический
+`_iob[]` с отрицательными индексами, буферизацию записи.
+
+## Лимит открытых файлов и статическая таблица FILE (2026-07-06)
+
+Факты: solid-c — OPEN_MAX = 8, статический массив из 8 FILE-структур
+(+5 псевдопотоков перед ним), fdopen отвергает fd > 8.  DSS-доки:
+FCB строятся «в рабочих областях ДОС», код ошибки 06h = «Too many
+open files» (наш EMFILE = 6 совпадает).
+
+**ПОДТВЕРЖДЕНО тестом fdmax (MAME, DSS 1.71.57, 2026-07-06)**:
+пользователю доступно 8 манипуляторов, fd 2..9 (fd 1 держит шелл DSS
+под запущенный .exe).  КРИТИЧНО: 9-й OPEN не возвращает 06h — он
+ВЕШАЕТ систему.  Поэтому в libc/io добавлен предохранитель _fd_guard
+(счётчик в open/close, отказ EMFILE на 9-м open без захода в DSS) —
+таблица fopen и guard вместе закрывают и высокий, и низкий уровень.
+
+Следствие для B+: вместо malloc-FILE + связного списка-реестра —
+**статическая таблица из 8 слотов** (свободный слот: flags == 0):
+- реестр для flush-on-exit бесплатен: _fclosall = цикл по таблице;
+- fopen без malloc — единственный отказ синхронен с отказом DSS
+  (EMFILE), утечка «fclose без free» невозможна;
+- цена: ~112–128 Б BSS (в exe не входит), только у программ с fopen;
+- буферы НЕ статические — остаются ленивыми malloc 512 Б (потолок
+  8×512 = 4 КБ heap в худшем случае);
+- объявить FOPEN_MAX 8 в stdio.h; если fdmax покажет лимит DSS < 8 —
+  уменьшить таблицу.
+
+## Семантика инвалидации (вариант B) — контрольный сценарий
+
+Буфер — только кэш опережающего чтения.  Правило: **любая запись и
+любой fseek обнуляют буфер; запись всегда идёт напрямую в файл после
+отмотки позиции** (`_file_sync`: `lseek(fd, -level, SEEK_CUR)` +
+`level = 0`).  Буфер при записи НЕ патчится — write-through с правкой
+окна отвергнут как сложный ради редкого паттерна.
+
+Сценарий «r+, чтение-запись-чтение» (обсуждено 2026-07-06):
+read 512 в буфер → 10×fgetc (логическая поз. 10, fd на 512) →
+первый fputc: sync отматывает fd на 10, буфер пуст, 10×write ложатся
+на 10..19 → fseek(0) → fgetc перечитывает буфер С ДИСКА и видит
+записанные байты.  Протечка старой копии невозможна — она уничтожена
+в момент первой записи.
+
+## Оценка/проверка
+
+Бенчмарк до/после: цикл fgets по tests/seek/big.txt с замером ptime
+(тест tests/fbench), плюс filetest-регресс в MAME.  Ожидание: чтение
+~512× меньше syscall'ов; код file-модулей +200–300 Б (тянется только
+использующими FILE*).

docs/host-tests-plan.md

@@ -0,0 +1,129 @@
+# План: модульные тесты libc и libbgi под ucsim_z80
+
+Статус: **не начато**, задача на будущее. Обвязка уже готова и обкатана —
+`testkit/` (см. `testkit/README.md`); первый потребитель —
+`../Applications/PoP-Archive/roomtest/tests-host/`. Этот документ — про то, как накрыть
+тем же способом основной продукт репозитория.
+
+## Что это НЕ заменяет
+
+В `tests/` уже лежат 62 каталога — это **интеграционные** тесты: одна фича =
+одна программа, которая пакуется на дискету и гоняется в MAME
+(`docs/mame-autotest.md`). Они проверяют, что API работает на живой машине:
+ESTEX, BIOS, диск, экран, тайминги.
+
+Модульные тесты их не отменяют, а дополняют с другой стороны:
+
+| | `tests/` (MAME) | `tests-host` (ucsim) |
+|---|---|---|
+| что проверяет | работает ли на машине | верна ли логика |
+| граничные случаи | 1–2 на фичу | десятки, дёшево |
+| время прогона | десятки секунд | миллисекунды |
+| ловит | железо, тайминги, банки | арифметику, краевые условия, регрессии |
+
+Правило разделения то же, что уже записано для PoP: **что можно проверить
+без железа — проверять в ucsim, MAME оставить железу.**
+
+## Три группы модулей
+
+### 1. Чистая логика — тестируется как есть, швов не нужно
+
+Здесь можно начинать в тот же день, когда задачу возьмут в работу.
+
+**libc:**
+
+- `time/` — `_tm_is_leap`, `_tm_mdays`, `_tm_month_days`, `_tm_year_days`,
+  `mktime`, `gmtime`, `localtime`, `asctime`, `ctime`. Классическая
+  календарная арифметика: високосные годы, границы месяцев, переходы через
+  год, круговой прогон `mktime(gmtime(t)) == t`. Идеальный первый набор —
+  много краевых случаев и ноль зависимостей.
+- `stdio/` — `dec_print`, `hex8/16/32`, `_scanf_core`, `sscanf`. Формат и
+  разбор: ширина, знак, переполнение, мусор на входе.
+- `string/`, `stdlib/` — `strlwr`, `strupr`, `max`, `min`.
+
+**libbgi/common** (115 модулей, почти всё mode-agnostic):
+
+- `_bgi_isqrt`, `_bgi_trig` — сверить с эталонной формулой на всём
+  диапазоне, ровно как сделано для LCG в `t_geom` у PoP;
+- `_bgi_lineseg`, `_bgi_styled_line`, `_bgi_poly_edge`, `_bgi_arc_draw` —
+  геометрия и отсечение: линия целиком вне окна, по диагонали через угол,
+  вырожденная в точку;
+- `_spr_ysort` — порядок сортировки спрайтов;
+- `_bgi_hspan`, `_bgi_fill_span` — заливка: краевые span'ы, нулевая ширина.
+
+### 2. Нужны швы — но швы дешёвые
+
+**Фейковый ESTEX и BIOS прямо в тестовом crt0.** Оба вызываются через
+`rst #0x10` и `rst #0x08`, то есть через фиксированные векторы в первых
+байтах памяти. В тестовом бинаре эти адреса наши: можно положить туда
+обработчик, который эмулирует крошечную файловую систему в ОЗУ и текстовый
+экран в буфере. Это открывает:
+
+- `file/` (32 модуля) и `io/` (21) — `fopen`/`fread`/`fwrite`/`fseek`,
+  буферизация (`docs/file-buffering-design.md`), поведение на EOF и
+  ошибках, `errno`;
+- `conio/` (38) — вывод в буфер вместо экрана, проверка атрибутов,
+  скроллинга, границ окна.
+
+Отдельно ценно: **гарды**, которые обязаны быть в обеих сборках. `_fd_guard`
+(девятый `OPEN` вешает DSS) — это ровно тот случай, где нужен тест, а не
+вера в комментарий: открыть восемь, убедиться, что девятый вернул ошибку и
+не дошёл до ESTEX.
+
+**Кадровый буфер в ОЗУ для libbgi.** Если рисующие ядра умеют писать в
+обычный буфер, а не только в видеопамять, растеризацию можно проверять
+снимком: нарисовать фигуру, сравнить с эталонным массивом. Начинать с
+маленьких (8×8, 16×16) — эталон читаемый прямо в исходнике.
+
+### 3. Только MAME
+
+Банки и W-окна, EMM, реальный ESTEX/DSS, клавиатурный трамплин и IM2,
+CBL-звук (`cbl/`), мышь (`mouse/`), `mem/` (это банки и страницы, а не
+куча), тайминги и бюджет кадра, ускоритель.
+
+## Обе сборки: fast и safe
+
+Библиотеки собираются в двух вариантах (`-D*_NOCHECK` вырезает
+валидацию параметров). Наборы стоит гонять **против обоих**:
+
+- в safe — что валидация ловит мусорные аргументы и ставит `errno`;
+- в fast — что вырезание валидации не поменяло поведение на корректных
+  входах.
+
+Это дешёвая параметризация Makefile (тот же набор, два `OBJS_*`), и она
+пресекает целый класс расхождений между вариантами.
+
+## Фазы
+
+1. **Календарь и формат.** `time/`, `stdio/`. Нулевые швы, максимальная
+   плотность краевых случаев. Цель — обкатать поток работы на libc.
+2. **Геометрия libbgi.** `common/`: isqrt, тригонометрия, отсечение линий,
+   рёбра полигонов. Тоже без швов.
+3. **Фейковые ESTEX/BIOS в crt0.** Открывает `file/`, `io/`, `conio/` и
+   гарды. Самый крупный кусок работы и самая большая отдача.
+4. **Растр libbgi по снимкам** — если окажется, что ядра можно нацелить на
+   буфер в ОЗУ без правок продукта; иначе отложить.
+5. **Параметризация fast/safe** — после того, как наборов станет заметно.
+
+## Критерии
+
+- Тест не считается написанным, пока не проверен мутацией: сломать
+  проверяемое место, убедиться, что набор краснеет. Пустые тесты хуже
+  отсутствующих.
+- Каждый закрытый баг libc/libbgi получает регрессионный кейс, если он
+  ловится без железа.
+- `make host-tests` остаётся быстрым: если суммарно перевалит за несколько
+  секунд, делить на быстрый и полный прогон.
+
+## Организация
+
+Наборы кладутся рядом с кодом, обвязка общая:
+
+```
+libc/tests-host/       наборы по областям: t_time.c, t_stdio.c, …
+libbgi/tests-host/     t_geom.c, t_raster.c, …
+```
+
+Каждому — `Makefile` на пять строк (`TESTKIT`, `ENGINE_DIR`, `OBJS_*`,
+`include`), и добавить каталог в `HOST_TEST_DIRS` корневого `Makefile`.
+Подробности — `testkit/README.md`.

docs/im2_isr_design.md

@@ -1,6 +1,233 @@
 # IM2 Interrupt Handlers — Design Document
 
-**Status:** РЕАЛИЗАЦИЯ ОТЛОЖЕНА (до пост-релизной версии). Обязательная фича для v2.
+**Status: Phase 1 (2026-07-06), Phase 2a CTC (2026-07-07), Phase 2b CBL
+(2026-07-07, редизайн на callback без кольца — см. ниже) РЕАЛИЗОВАНЫ**
+(libc/irq: irq_install/irq_remove + трамплин, irq_ctc_install/remove;
+libc/cbl: cbl_open/close/push_otir/push_accel + fill-callback; тесты
+tests/irqtest, tests/cbltest, tests/cblwav, tests/cblstream).
+Callback-редизайн **verified в MAME 2026-07-07**: все три CBL-теста
+(cbltest — матрица 64 комбинации; cblwav — banked-стрим, голос слышен;
+cblstream — собственное кольцо приложения) работают.
+
+## Результаты verification (2026-07-06, по docs/samples и исходникам MAME)
+
+Первая версия зависала на первом же прерывании после irq_install.
+Причины и проверенные факты:
+
+- **DSS работает в IM 1** (обработчик на 0x0038).  I=0x3F — наследие
+  Spectrum ROM, НЕ признак IM 2-таблицы.  Доказательства:
+  `docs/samples/sprinterIntLib.asm` (intRestoreDefaultInterrupt: `ld i,a`
+  + `im 1` безусловно, «обязательно перед функциями дос и биос») и
+  `docs/samples/SIO_CTC_KEY.asm` (выход: `LD I,A` + `IM 1`).  Чтение
+  «таблицы DSS» по [I<<8+0xFF] давало мусор (0x00BF) и было причиной
+  зависания.  Фикс: чейн из трамплина ВСЕГДА на 0x0038 (jp с
+  interrupted-PC на стеке = имитация RST 38); irq_remove всегда
+  восстанавливает IM 1 (I — только регистр).
+- **CBL-фильтр по биту 7 порта 0xFE убран из трамплина**: в MAME при
+  выключенном CBL бит 7 всегда = 1 (sprinter.cpp kbd_fe_r:
+  `data |= 0xE0`), и каждое кадровое прерывание ложно классифицировалось
+  как CBL — user-handler не вызывался бы никогда.  Признак «#fe.bit7=1»
+  (sprinterIntLib.asm) имеет смысл только при активном CBL — вернуть в
+  Phase 2 вместе с поддержкой CBL.
+- **Порт 0x19 = SIO-A RR0 (Z84C015), бит 0 = «Rx Character Available»** —
+  семантика клавиатурного пробника верна (подтверждено
+  sprinterIntLib.asm: `in a,(COM_A); bit 0,a; Z → кадровое`).
+- **Вектора встроенной периферии Z84C015**: SIO — 0x10..0x1E, CTC — 0x06
+  (базовые вектора задаются записью в WR2 SIO-B / CTC ch0).  Штатно их
+  прерывания выключены (сэмплы включают/выключают их сами); наша
+  заливка 257×H перехватывает любой вектор на трамплин, а чейн на
+  0x0038 безопасен для любого источника.
+- Внешний вектор действительно 0xFF (MAME sprinter.cpp:
+  `set_irq_acknowledge_callback` → 0xff).
+
+Отличия реализации от плана ниже:
+
+- **отдельный `--memory im2` НЕ понадобился**: таблица — статический
+  буфер 513 Б в BSS с выравниванием в рантайме; т.к. внешний вектор —
+  только 0xFF, значимы лишь байты [0xFF]/[0x100], и 3-байтовый
+  `jp _irq_tramp` лежит ВНУТРИ таблицы по смещению H (H = старший
+  байт её адреса, < 0xC0 — не пересекается).  Никаких linker-областей
+  и правок crt0;
+- работает в tiny/big (код и данные в W2); в small/huge irq_install
+  возвращает EINVAL (проверка адресов трамплина/буфера);
+- **чейн к DSS — ВСЕГДА и всегда на 0x0038** (и клавиатура, и кадр):
+  не нужно знать, что DSS делает в своём ISR — SYSTIME/клавиатура/мышь
+  живут.  User-handler зовётся только на кадровых (фильтр: бит 0
+  порта 0x19 → мимо); финальный jp — SMC-операнд;
+- W3-порт в трамплине НЕ сохраняется: gfx держит DI на время свопов,
+  а user-handler'у banking запрещён; DSS свои окна сохраняет сам;
+- irq_remove вешается на atexit (выход без снятия = IM 2/I указывают в
+  память умершего процесса = крах шелла); восстановление — всегда IM 1.
+
+## Phase 2a — CTC-таймер (РЕАЛИЗОВАН 2026-07-07)
+
+`irq_ctc_install(handler, div2, div3)` / `irq_ctc_remove()` — вектор
+0x06, ОТДЕЛЬНЫЙ от кадрового 0xFF (решает проблему «кадр и клавиатура
+неразличимы»).  Механика (по docs/samples/sprinterIntLib.asm и
+SIO_CTC_KEY.asm):
+
+- CTC Z84C015: канал 2 тактируется видеотактом **875 кГц (1 тик =
+  1 знакоместо)** и работает делителем; канал 3 считает от канала 2 и
+  прерывает.  f = 875000/(div2*div3), div 0 = 256;
+- пресет IRQ_CTC_VSYNC_DIV2/3 = 112×160 (2 пикс. линии × 160 = 320
+  линий) — точное начало кадра ~48.8 Гц;
+- порты: CH0=0x10, CH2=0x12, CH3=0x13; control-слова 0x57 (ch2:
+  counter, int off) / 0xD7 (ch3: counter, int on); базовый вектор
+  блока пишется в CH0 (0 → вектор ch3 = 0x06); стоп = 0x03 (reset);
+- **RETI обязателен** в CTC-трамплине: daisy chain Z84C015 снимает IUS
+  только по опкоду RETI — с RET следующее прерывание не придёт;
+- CTC-путь НЕ чейнится к DSS (личное прерывание); кадровые/клавиатурные
+  0xFF идут своим путём параллельно;
+- общая IM2-таблица под счётчиком ссылок (_irq_table.c): кадровый и
+  CTC-хендлеры ставятся/снимаются независимо, последний возвращает
+  I/IM 1; atexit-уборка глушит CTC ОБЯЗАТЕЛЬНО (иначе после выхода
+  прерывания кГц-частоты душат шелл).
+
+## Phase 2b — CBL/COVOX audio (РЕАЛИЗОВАН 2026-07-07, редизайн без кольца)
+
+`libc/include/cbl.h`: `cbl_open(freq_code, fmt, pump_mode,
+underrun_mode, fill)` / `cbl_close()` / `cbl_push_otir(src,n)` /
+`cbl_push_accel(src,n)` / `cbl_requests()` / `cbl_underruns()`.  По
+`docs/samples/Пример для CBL.asm`, разделу «Звук через COVOX-Blaster»
+в `docs/converted/Forum.txt`, официальной документации "5.3
+COVOX-Blaster" (see below) и `docs/converted/accel_r.txt`:
+
+**Архитектурный редизайн (2026-07-07)**: у CBL УЖЕ ЕСТЬ собственный
+аппаратный буфер 256 Б, разбитый на ДВЕ половины по 128 Б (double
+buffering целиком на стороне железа — см. официальную доку: "Блок ОЗУ
+256 байт условно разбит на две банки по 128 байт, и бит 7 порта #FE
+указывает какая из банок ОЗУ выводится в ЦАП... используется программой
+вывода для определения, нужно ли подгружать следующие 128 байт").
+Держать ЕЩЁ ОДНО кольцо в libc поверх этого — лишний второй буфер и
+лишняя копия.  Библиотека теперь НЕ хранит кольца: при cbl_open()
+регистрируется callback `fill(n)`, который ISR вызывает НАПРЯМУЮ, а
+callback сам пропихивает n байт ИЗ ДАННЫХ ПРИЛОЖЕНИЯ (статический
+массив, банковая EMM-страница, файл — что угодно) прямо в CBL через
+`cbl_push_otir()`/`cbl_push_accel()` — без промежуточной копии в libc.
+Пример из офиц. документации делает ровно это: `OUTI` читает прямо из
+HL, указывающего в банковую страницу с WAV-данными, без всякого
+стейджинга.
+
+`fill(n)` вызывается ИЗ ISR — ОБЯЗАН быть быстрым: никаких
+ESTEX/BIOS/gfx-вызовов (тот же констрейнт, что у `irq_install()`-
+хендлера).  В частности, диск (read() — ESTEX) читать из fill() НЕЛЬЗЯ
+— см. tests/cblstream ниже, где под это заведено собственное кольцо
+уровня приложения.  Возвращает ненулевое при успехе, 0 — недолив.
+
+- **Control-порт 0x004E — 16-битный** (`ld bc,#0x004E` / `out (c),a`,
+  не 8-битный `out (n),a`).  Биты: 7 = CBL on, 6 = stereo, 5 = 16-bit,
+  4 = interrupt enable, 3..0 = код частоты (8=7.8125 кГц…F=109.375 кГц,
+  0/1 — legacy-режим без сэмплирования).  `cbl_open` шлёт
+  `0x90|fmt|freq` (on + int + формат + частота) под DI, `cbl_close`
+  шлёт `0`.
+- **Формат — CBL_FMT_MONO8/MONO16/STEREO8/STEREO16** (2026-07-07):
+  биты 5(16-бит)/6(stereo) напрямую соответствуют константам, можно
+  OR'ить с freq.  Блок запроса — 128 Б для 8-бит, 256 Б для 16-бит
+  (НЕ зависит от моно/стерео — см. Forum.txt: «для каждых 128 байт
+  (256 в режиме 16 бит)»); тишина — 0x80 (8-бит unsigned) или 0x0000
+  (16-бит signed).  8-бит сэмплы центр 0x80, 16-бит центр 0x0000,
+  stereo — чередование L/R.  Runtime-размер блока — `_cbl_block`
+  (128 или 256), заполняется в `cbl_open` по fmt.
+- **Два насоса, выбор — CBL_PUMP_OTIR/CBL_PUMP_ACCEL** (2026-07-07):
+  - **OTIR** (`_cbl_pump_otir`) — блок в порт 0x4F через `otir`; B=младший
+    байт `_cbl_block` (128 остаётся 128, 256 идёт как 0 — Z80 OTIR:
+    B=0 значит 256 итераций).  Проверено в MAME (звук слышен, 0
+    underrun).
+  - **ACCEL** (`_cbl_pump_accel`) — запись через акселератор в
+    спец-страницу EMM 0xFD, замапленную в окно W3 на 0xC000 (Forum.txt:
+    «запись данных в COVOX-Blaster... 128/256 байт с адреса 0xC000»).
+    Последовательность (по accel_r.txt + рабочему прецеденту
+    libc/gfx/_gfx_hfill256.c): `LD D,D` (режим размера блока) →
+    immediate `LD A,n` (SMC-патч, 0 значит 256 — тот же трюк, что и в
+    OTIR) → `LD L,L` (режим "копирование блока") → `LD A,(HL)` /
+    `LD (DE),A` (блочное чтение источника → блочная запись в
+    0xC000@стр.0xFD) → `LD B,B` (выкл).  Акселератор НЕ продвигает
+    HL/DE сам — advance после пересылки делается вручную (`add hl,
+    (block)`).  W3 сохраняется/восстанавливается вокруг переключения
+    (как `bank_read`/`bank_write`); доп. DI/EI не нужны — весь насос
+    целиком уже внутри ISR (прерывания замаскированы до EI/RETI
+    трамплина).  **Verified в MAME 2026-07-07** — tests/cbltest, все
+    32 accel-комбинации матрицы прошли без ошибок/underrun.
+  - Общий каприз с CBL-примером из docs/samples: там для установки
+    размера блока акселератора используется `LD C,128` СРАЗУ ЗА
+    `LD D,D` — это противоречит и accel_r.txt («далее следует команда
+    типа LD A,dat»), и нашему же подтверждённому на gfx констрейнту
+    (CLAUDE.md: «block-size ОБЯЗАН быть immediate операндом LD A,n»).
+    Мы взяли ВЕРИФИЦИРОВАННЫЙ вариант (LD A,n), а не пример — вероятно,
+    у автора размер уже был установлен раньше (заметка в accel_r.txt:
+    «если размер блока был установлен ранее, его можно не
+    устанавливать»), и `LD C,128` в примере готовит BC для последующего
+    `ADD HL,BC`, а не для акселератора.
+- **Data-порт 0x4F** (для OTIR-насоса), блок 128/256 байт.
+- **Признак запроса блока — бит 7 порта 0xFE — валиден ТОЛЬКО когда
+  CBL реально активен.**  При выключенном CBL MAME (`kbd_fe_r`)
+  подтягивает этот бит к 1 всегда (`data |= 0xE0`) — поэтому трамплин
+  проверяет бит 0xFE.7 не напрямую, а через индирекцию
+  `_irq_cbl_hook`: пока `cbl_open` не установил хук, кадровые
+  прерывания даже не читают порт 0xFE (см. Phase 1 — по этой же
+  причине первая версия фильтра была убрана).  Официальная документация
+  описывает тот же бит как "старший бит счётчика" адреса аппаратного
+  буфера — по нему же программа определяет, какую половину доливать.
+- **Насос (`_cbl_pump_otir`/`_cbl_pump_accel`) теперь тривиален**:
+  `_cbl_reqs++; ok = _cbl_fill ? _cbl_fill(_cbl_block) : 0; if (!ok) {
+  _cbl_undr++; ...}`.  Обычные (не `__naked`) Си-функции — можно, т.к.
+  трамплин уже сохраняет ВЕСЬ контекст (оба регистровых набора + IX/IY)
+  вокруг вызова хука, что бы функция ни наделала с регистрами.
+- **Поведение при недоливе — CBL_UNDERRUN_APP/SILENCE** (4-й параметр
+  cbl_open, 2026-07-07): по умолчанию (`APP`, 0) недолив — не забота
+  библиотеки, буфер тишины НЕ аллоцируется вовсе, в CBL доигрывает то,
+  что уже лежало в его аппаратном буфере.  `SILENCE` (1) — насос сам
+  пропихивает тишину (`_cbl_silence`, malloc'ится В cbl_open() ТОЛЬКО
+  в этом режиме, размером `_cbl_block`, залит 0x80/0x0000 по формату) —
+  тот же приём, что раньше был жёстко вшит в насос, теперь опционален.
+  `cbl_underruns()` считает недоливы в ОБОИХ режимах — это только
+  диагностика.
+- **CBL-путь НЕ чейнится к DSS** — личное прерывание CBL, полный сейв
+  контекста (основной набор + теневой AF/BC/DE/HL + IX/IY, т.к. `fill()`
+  может клобберить что угодно) → `EI`/`RETI` напрямую, без 0x0038.
+- `cbl_open` держит те же анти-повторные гарантии, что и irq/ctc:
+  занятый хук → EBUSY, `atexit(cbl_close)` регистрируется один раз,
+  `_irq_table_ref()`/`_irq_table_unref()` для общей IM2-таблицы.
+- **tests/cbltest**: полная матрица (2 насоса × 8 форматов × 4 частоты
+  = 64 комбинации) пилообразного тона, ~1 с каждая; `fill_tone()`
+  всегда возвращает 1 (period-64 тон никогда не "кончается") —
+  CBL_UNDERRUN_APP без буфера тишины достаточно.  Main не поллит
+  ничего — просто ждёт halt()'ом.  OTIR+16-бит (16/64) пропускаются
+  заранее (cbl_open вернул бы EINVAL).
+- **tests/cblwav**: потоковая речь (78 КБ) с ДИСКЕТЫ через banked EMM
+  (диск слишком медленный для realtime — клип предзагружается в RAM
+  ДО cbl_open).  `fill_speech()` делает `bank_read()` из уже загруженной
+  страницы в стейджинг и `cbl_push_otir()` — физические номера страниц
+  кэшированы в массиве ЗАРАНЕЕ (на этапе загрузки, в main-контексте):
+  `mem_get_page()` — BIOS-вызов, сам управляет EI/DI, и звать его ИЗ
+  fill() (то есть из ISR) нельзя — его `ei` при возврате может
+  преждевременно снять маску прерываний, пока мы ещё внутри ISR.
+- **tests/cblstream**: без banked-предзагрузки — чтение с диска
+  ОДНОВРЕМЕННО с воспроизведением; рассчитан на быстрый носитель (HDD).
+  Единственный из трёх тестов, где приложению НУЖНО собственное кольцо:
+  `read()` — ESTEX-вызов, а `fill()` зовётся из ISR, где ESTEX/BIOS под
+  запретом — поэтому диск читается ТОЛЬКО в main (в кольцо уровня
+  приложения), а `fill_stream()` лишь копирует уже готовые байты и
+  пропихивает `cbl_push_otir()`.  НЕ входит в общую сборку (`make`/
+  `make floppy`) — только `cd tests/cblstream && make run`, свой образ
+  диска.
+
+ISA-вектора, цепочки нескольких хендлеров на одном векторе — не
+реализовано (см. «Phase 2 (когда понадобится)» ниже).
+
+**Щелчок перед первым звуком за сессию (2026-07-07, A/B/C-стенд)**:
+на РЕАЛЬНОМ файле (tests/cblwav, потоковая речь) перед началом
+воспроизведения был слышен щелчок/призвук.  Диагностика через
+tests/cblwav (banked-стрим с пилой, затем с чистой тишиной вместо
+речи, в одном запуске) показала: щелчок слышен ТОЛЬКО на первом
+запуске программы после старта MAME и НЕ зависит от содержимого потока
+(тон / тишина / речь — одинаково).  Проверенное на macOS (`afplay`)
+воспроизведение исходного speech.pcm — чистое, артефактов в самом
+файле нет.  Разбивка `cbl_open()` на две записи в порт 0x004E (сначала
+код частоты, потом enable, с паузой) не повлияла — отменена.  Вывод:
+это одноразовый прогрев звуковой подсистемы MAME при первой активации
+канала CBL за сессию эмулятора, не баг протокола/драйвера; на реальном
+железе, скорее всего, отсутствует (см. docs/TODO.md).
 
 Этот документ собирает всё, что мы знаем о прерываниях Sprinter и план реализации user-задаваемых ISR через Z80 IM 2 mode. Когда возьмёмся за реализацию — читать этот файл, чтобы не повторять research.
 
@@ -160,7 +387,7 @@ User's ISR НЕ должен:
 
 ## Phase 1 acceptance
 
-- `examples/irq_test/` — счётчик тиков растёт с 50 Hz
+- `../Examples/irq_test/` — будущий пример: счётчик тиков растёт с 50 Hz
 - Клавиатура продолжает работать через DSS chain (можно прервать тест клавишей)
 - Корректный exit — DSS shell получает управление обратно без crash
 - Работает во всех memory modes (tiny, small, big, huge)
@@ -168,9 +395,219 @@ User's ISR НЕ должен:
 
 ## Phase 2 (когда понадобится)
 
-- CBL/COVOX prerequisite handler (для audio playback)
+- ~~CBL/COVOX prerequisite handler~~ — реализован, см. «Phase 2b» выше
 - ISA interrupt handler (для ZX-Bus карт)
-- Multiple user handler chain (e.g. tick + sound)
+- Multiple user handler chain (e.g. tick + sound) — ДИЗАЙН ниже
+
+## Цепочка кадровых обработчиков (план, 2026-07-14)
+
+Мотив: сейчас кадровый слот один (`_irq_user`), второй `irq_install`
+даёт `EBUSY`. Как только в программе сойдутся ≥2 потребителя кадрового
+прерывания (FPS-делитель `gfx_set_fps_div` + свой тик/звук приложения),
+одного слота мало. Решение — фиксированный массив слотов, по которому
+трамплин проходит на каждом кадре.
+
+### Модель
+
+- `isr_t _irq_chain[IRQ_CHAIN_MAX]` (`IRQ_CHAIN_MAX = 4`) + счётчик
+  занятости `uint8_t _irq_chain_n` — в `_irq_state.c` (W2-data;
+  ЗАМЕНЯЮТ нынешний `isr_t _irq_user`).
+- Порядок вызова = порядок индексов 0..3. Взаимный порядок хендлеров
+  **НЕ гарантируется** после remove/add (переиспользуется первая дыра)
+  → хендлеры обязаны быть независимы. Наш `_gfx_frame_isr` (инкремент
+  байта) независим по построению.
+- Дисциплина ISR прежняя (`irq.h`): без ESTEX/BIOS/gfx/банков/акселератора.
+
+### Трамплин (`_irq_tramp.c`, секция `_irq_frame`)
+
+Полный сейв теневого+индексного набора делается ОДИН раз (амортизируется
+на всю цепь), затем цикл по слотам с пропуском NULL:
+
+```
+_irq_frame:
+    push bc/de/hl
+    ld   a, (__irq_chain_n)      ; ранний выход: цепь пуста → без сейва
+    or   a, a
+    jr   Z, _irq_pop3
+    ... сейв shadow + IX/IY ...
+    ld   hl, #_irq_chain
+    ld   b, #IRQ_CHAIN_MAX
+_irq_chain_loop:
+    ld   e,(hl) / inc hl / ld d,(hl) / inc hl   ; DE = слот
+    ld   a,d / or a,e / jr Z, _irq_chain_skip    ; NULL → пропуск
+    push bc / push hl
+    call _irq_call_de           ; jp (de)-обёртка (как _irq_call_hl)
+    pop  hl / pop bc
+_irq_chain_skip:
+    djnz _irq_chain_loop
+    ... restore ...
+_irq_pop3:
+    pop hl/de/bc
+_irq_chain:  ... jp DSS ...      ; как сейчас
+```
+
+Пустой проход 4 слотов ≈ 4×(load+or+skip) ≈ 40Т — копейки на кадре.
+Ранний выход по `_irq_chain_n==0` сохраняет текущую оптимизацию «нет
+хендлера → без тяжёлого сейва» (трамплин может быть установлен ради
+CBL/CTC при пустой кадровой цепи).
+
+### API (`irq.h`)
+
+```c
+#define IRQ_CHAIN_MAX 4
+int  irq_chain_add(isr_t h);     /* 0 / -1+ENOMEM (слоты кончились)   */
+void irq_chain_remove(isr_t h);  /* снять ОДИН слот (по указателю)     */
+```
+
+Совместимость (без изменения существующих call-sites):
+- `irq_install(h)` → тонкая обёртка `return irq_chain_add(h)`. `EBUSY`
+  исчезает (двойной install теперь легален); при 4 занятых — `ENOMEM`.
+- `irq_remove()` (без аргумента) — снимает **ВСЮ** кадровую цепь и
+  возвращает IM 1. Семантика exit/atexit сохранена (exit рвёт всё перед
+  возвратом в DSS).
+- `gfx_set_fps_div` использует `irq_chain_add`/`irq_chain_remove`
+  (ТАРГЕТНО свой `_gfx_frame_isr`), НЕ `irq_remove` — чтобы выключение
+  делителя не снесло собственный хендлер приложения.
+
+### Refcount таблицы
+
+`irq_chain_add`: если `_irq_chain_n == 0` (первый слот) → `_irq_table_ref()`
+(ставит IM2). `irq_chain_remove`: если слот был последним (`_irq_chain_n`
+уходит в 0) → `_irq_table_unref()` (возврат IM1). CBL/CTC-ссылки на
+таблицу считаются отдельно, как сейчас.
+
+### Гонка чтения слота (ОБЯЗАТЕЛЬНО)
+
+Трамплин читает слот двумя байтовыми `ld`; запись указателя в
+add/remove — 16-бит store. Порванное чтение (низкий байт новый, старший
+старый) = прыжок в мусор. Поэтому мутации слота+счётчика в
+`irq_chain_add`/`irq_chain_remove` ОБЯЗАНЫ идти под `IRQ_DISABLE()` /
+`IRQ_ENABLE()`. Дёшево и обязательно.
+
+### Файлы (канон 1 модуль = 1 функция)
+
+- `_irq_state.c` — `_irq_user` → `_irq_chain[IRQ_CHAIN_MAX]` + `_irq_chain_n`.
+- `_irq_tramp.c` — переписать секцию `_irq_frame` на цикл (выше).
+- `_irq.h` — объявить `_irq_chain`, `_irq_chain_n`, `IRQ_CHAIN_MAX`.
+- `irq_chain_add.c`, `irq_chain_remove.c` — НОВЫЕ.
+- `irq_install.c` — обёртка над chain_add; `irq_remove.c` — teardown-all
+  (чистит все слоты + unref до нуля).
+- `include/irq.h` — публичные объявления + документировать «порядок не
+  гарантирован, хендлеры независимы; двойной install легален; 4 слота».
+- `tests/irqtest` — добавить кейс двух хендлеров (оба тикают свои
+  счётчики; remove одного не глушит другого; exit рвёт оба).
+
+### Ограничения (СНИМАЮТСЯ — см. «все режимы» ниже)
+
+- ~~Только tiny/big~~ — цель теперь **все режимы**, дизайн ниже.
+- CTC-цепочка (`irq_ctc_*`) — тем же паттерном, ОТДЕЛЬНЫЙ массив
+  (вектор 0x06); делать по потребности, не сейчас.
+
+## Вариант «работает во всех режимах памяти» (план 2026-07-14)
+
+Постановка: IM2-прерывания должны работать и в small/huge, где CODE
+лежит в W1. Нельзя просто «загнать всё в W2» — обработчик пишет
+пользователь как обычный C, и он компилируется в `_CODE` (=W1 в
+small/huge). Задача — разложить *путь прерывания* так, чтобы он был
+корректен при ЛЮБОМ содержимом W1/W3 в момент прихода прерывания.
+
+### Что на пути прерывания и что реально требует W2
+
+Прерывание фетчит и исполняет по цепочке: **вектор-таблица → трамплин →
+обработчик(и) → chain на DSS 0x0038**. В момент прерывания стабильно
+замаплены только W0 (ROM/DSS) и **W2** (там стек — DSS это требует,
+окно не перемапливается). W1 перемапливается банками кода (big) и самим
+DSS при iff=1 во время сисколлов (подтверждено артефактом). W3 — банки
+(huge).
+
+Ревизия по компонентам:
+1. **Вектор-таблица** — УЖЕ в W2 (`_irq_vec_buf`, BSS; BSS садится в W2
+   во всех режимах). Ничего менять не надо.
+2. **Трамплин** (`_irq_tramp`) — сейчас в `_CODE` (=W1 в small/huge).
+   ЕДИНСТВЕННОЕ, что валит проверку `tramp < 0x8000` в
+   `_irq_table_ref()`. Нужно сделать W2-резидентным.
+3. **Обработчик пользователя** — обычный C в W1/W3. НЕ трогаем — решаем
+   через remap (см. ниже).
+4. **Данные цепи** (`_irq_chain`, `_irq_chain_n`, …) — BSS → W2. ОК.
+
+### Ключевой приём: не двигать обработчик, а подсунуть ему страницу
+
+ВАЖНО (уточнение 2026-07-14): в small/huge программа видит **плоские
+32 КБ 0x4000–0xBFFF** — две статические страницы (W1+W2 подряд), их
+номера фиксированы на всё время работы. Обработчик может лежать ГДЕ
+УГОДНО в этом диапазоне: в W1 (0x4000–0x7FFF), в W2 (0x8000–0xBFFF)
+или даже НА СТЫКЕ через 0x8000. Значит не нужно знать, в каком окне
+хендлер — нужно лишь на время его вызова сделать весь плоский регион
+адресуемым.
+
+Обработчик оставляем на месте. Трамплин (в W2) ПЕРЕД вызовом каждого
+хендлера восстанавливает базовую W1-страницу приложения — паттерн
+`__banked`-трамплина (bank.s: `in a,(0xA2)` / set / call / restore).
+W2 всегда = страница приложения (там стек, DSS не перемапливает), так
+что достаточно вернуть только W1 — и весь плоский 0x4000–0xBFFF
+корректен. Это работает, потому что:
+- в small/huge **базовая W1-страница статична** (пользователь её не
+  переключает — модель памяти); её номер crt0 фиксирует один раз при
+  старте (`IN A,(0xA2)`) в W2-переменную `_irq_app_w1_page`;
+- если прерывание пришло вне сисколла — W1 уже = базовая, set/restore
+  это no-op; если ВНУТРИ сисколла (DSS подменил W1) — трамплин ставит
+  базовую на время хендлера и возвращает DSS-страницу перед chain на
+  0x0038, прерванный сисколл продолжается корректно.
+
+Единый «restore W1=base» покрывает все положения хендлера БЕЗ детекции:
+- целиком в W1 → W1=base делает его код валидным;
+- целиком в W2 → W1-restore безвреден (хендлер оттуда не фетчит), W2
+  и так = приложение;
+- на стыке 0x8000 → нижняя часть по W1=base, верхняя по W2=приложение
+  — обе корректны.
+
+Итог по режимам:
+- **tiny/big**: базовый код/данные в W2 (всегда замаплен) → remap НЕ
+  нужен и ВРЕДЕН (в tiny/big нет осмысленной «базовой W1»; W1 —
+  банк-окно в big). Как сейчас.
+- **small/huge**: плоские 32 КБ → трамплин ставит `_irq_app_w1_page`
+  в 0xA2 вокруг вызова.
+Флаг «нужен remap W1» = (mode ∈ {small,huge}); crt0/sprinter-cc его
+выставляет, трамплин честит.
+
+**Scope v1:** любые хендлеры в плоском образе приложения (не-banked) —
+т.е. обычный C где угодно в 0x4000–0xBFFF; покрывает практически все
+ISR (счётчик/звук-тик). `__banked`-хендлер (в W3 huge / отдельном
+банке big) потребовал бы хранить его страницу per-слот и мапить в его
+окно — отдельное расширение, не сейчас.
+
+### Как сделать трамплин W2-резидентным — два пути
+
+**(A) Резерв W2-области (проще, рекомендую для v1).** Трамплин
+(и, при желании, таблица) — в отдельной area `_IM2` с абсолютным
+адресом в верхней части W2 (напр. под стеком). Область НЕнулевая только
+если слинкованы irq-модули (DCE) → цена платится лишь при использовании
+IRQ; heap-top при слинкованном IRQ = `s__IM2`. В small/huge W2-часть
+статического образа грузится crt0 как есть — код окажется в W2 без
+рантайм-копирования. Правка `_irq_table_ref()`: снять проверку
+`tramp < 0x8000` (трамплин теперь по построению в W2).
+
+**(B) Рантайм-эмит стаба в W2-BSS (без резерва области).** Скопировать
+PIC-шаблон трамплина в BSS-буфер (W2) при первом install, пропатчив
+абсолютные само-ссылки (SMC, как `_irq_dss_target` уже сейчас). Плюс:
+никакой зарезервированной области, чисто DCE. Минус: трамплин надо
+писать позиционно-независимым (внутренний control-flow только `jr`;
+`call (hl)`-идиому инлайнить или патчить адрес хелпера при копии).
+Оптимизация поверх (A), если резерв области жмёт бюджет small.
+
+Ключевой приём (remap базовой страницы) от выбора (A)/(B) не зависит.
+
+### Изменения к плану цепочки (выше)
+
+- `_irq_table_ref()`: убрать EINVAL-проверку `tramp/buf < 0x8000` после
+  переезда трамплина в W2 (таблица уже там).
+- crt0 (все варианты): записать `_irq_app_w1_page = IN A,(0xA2)` при
+  старте (для small/huge; в tiny/big просто не используется).
+- Трамплин `_irq_frame`: вокруг `call` хендлера — save/set/restore
+  0xA2 под флагом remap; перед `jp 0x0038` вернуть прерванную W1.
+- Тест: собрать `tests/irqtest` во ВСЕХ четырёх режимах; критично —
+  small/huge прогон с активным сисколлом в main (файловый цикл), чтобы
+  словить прерывание при DSS-подменённой W1.
 
 ## Альтернатива: отдельный memory mode "im2"
 

docs/kbd-games.md

@@ -0,0 +1,133 @@
+# Клавиатура в играх на Sprinter (raw-канал, held-state)
+
+Как правильно читать клавиатуру в play-цикле: что даёт платформа, чего
+она НЕ даёт, и какие паттерны использовать.  Выжато из порта Prince of
+Persia (`../Applications/PoP-Archive/roomtest`) и отладки багов «залипание клавиш»
+(2026-07-16) и «отвал Shift» (2026-07-22).
+
+## Почему не ESTEX
+
+ESTEX-функции (kbhit/getch/getkey, WAITKEY/SCANKEY) — **событийные**:
+нажатие кладётся в буфер, отпускание не видно вообще.  Live-состояние
+есть только у модификаторов (CTRLKEY/kbd_mod_state) — и то с багом BIOS:
+для стрелок/Home/End/PgUp/PgDn признак Shift не выставляется
+(docs/converted/bugs.txt §4).  Игре же нужно «клавиша X зажата ПРЯМО
+СЕЙЧАС» для каждой клавиши.  Отсюда raw-канал `<kbd_raw.h>`.
+
+## Матчасть: как клавиатура устроена снизу
+
+- AT/PS-2 клавиатура сидит на SIO-A Z84C015: порт 0x18 — данные
+  (деструктивное чтение!), 0x19 — статус (RR0, бит 0 = «байт принят»).
+- Прерывание клавиатуры приходит с тем же IM2-вектором 0xFF, что и
+  кадровое; различаются битом 0 порта 0x19.
+- Приёмный FIFO — **3 байта**.  Обработчик ОБЯЗАН вычерпывать его в
+  цикле «пока бит 0 установлен» (docs/converted/IvanMak.txt §9.4), иначе
+  пачка байт переполнит FIFO и байты потеряются.
+- Поток — PS/2 Scan Code Set 2: `код` = нажатие (make), `F0 код` =
+  отпускание (break), `E0` — префикс расширенных клавиш (стрелки и
+  т.п.), т.е. отпускание стрелки = `E0 F0 код`.  Быстрый тап стрелки =
+  5 байт подряд.
+- **Typematic (автоповтор): повторяется только ПОСЛЕДНЯЯ нажатая
+  клавиша** — make-код шлётся снова и снова без break между ними.
+  Модификаторы, зажатые вместе с другой клавишей, не шлют НИЧЕГО.
+  Это ключевой факт для дизайна recovery (см. ниже).
+
+## API libc
+
+```c
+#include <kbd_raw.h>
+
+kbd_raw_open();               // забрать клавиатуру у DSS (весь поток наш)
+...
+while (!kbd_raw_down(KBD_ESC)) {   // выход проверяем САМИ — DSS слеп
+    kbd_raw_sync();                // раз в кадр, ДО чтения клавиш
+    if (kbd_raw_down(KBD_RIGHT)) ...
+    if (kbd_raw_down(KBD_LSHIFT) || kbd_raw_down(KBD_RSHIFT)) ...
+}
+kbd_raw_close();              // вернуть клавиатуру DSS (есть и на atexit)
+```
+
+- Пока канал открыт, DSS клавиатуру **не видит**: kbhit/getch/getkey/
+  kbd_mod_state заморожены.  Перед экраном с консольным вводом —
+  `kbd_raw_close()`.
+- Декодер живёт прямо в IM2-трамплине (libc/irq/_irq_tramp.c): drain-
+  цикл FIFO + FSM префиксов F0/E0 + битмап `_kbdraw_down[512]`
+  (0..255 обычные, 256..511 расширенные, `KBD_EXT`).
+- `kbd_raw_down(code)` — O(1) чтение битмапа, зовите сколько угодно.
+- Требование памяти: BSS модуля должен быть в W2 (в `--memory small`
+  у крошечных программ может уехать в W1 → kbd_raw_open вернёт EINVAL;
+  huge/big — всегда ок).
+
+## Rx-overrun и политика восстановления
+
+Если прерывания запрещены дольше ~3 байт-тактов (длинные DI-окна,
+тяжёлый кадр), FIFO переполняется, SIO теряет байты и взводит Rx Overrun
+(RR1 бит 5).  Потерянный break = залипшая клавиша.  Трамплин ловит это и
+взводит флаг; `kbd_raw_sync()` раз в кадр делает восстановление:
+
+- сбрасываются ВСЕ обычные клавиши — реально зажатые перечитаются
+  ближайшим typematic-повтором (~0.1 с), а залипшие исчезнут;
+- **модификаторы (Shift/Ctrl/Alt) НЕ сбрасываются** — их перечитать
+  нечем (typematic по ним не идёт), сброс превращался в «отвал» Shift
+  при каждом overrun (баг PoP: Shift+→ давал 1-4 осторожных шага, после
+  чего Кид начинал бежать — Shift пропадал из битмапа навсегда).
+
+Цена компромисса (осознанная):
+
+- залипший модификатор (если overrun потерял именно его break) живёт до
+  следующего нажатия этого модификатора — редкий случай;
+- дырка с аккордами: держим →, тапаем ↑ (run-jump) — теперь typematic
+  идёт по ↑, и если overrun случится ДО отпускания →, стрелка сбросится
+  и не перечитается (повтор к предыдущей клавише не возвращается).
+  По замерам в MAME overrun'ы при стабильном удержании не возникают
+  вовсе (они кластеризуются в момент пачек make/break при тапах),
+  поэтому на практике окно узкое.
+
+## Паттерны игрового цикла
+
+- **held-state против «свежего нажатия»**: битмап отвечает только на
+  «зажата ли».  Для действий «одно нажатие = одно срабатывание» нужен
+  edge-detect: `if (sp && !sp_prev) toggle(); sp_prev = sp;`
+  (roomtest.c, тумблер дабл-буфера по SPACE).
+- **Подавление автоповтора действий** — конечный автомат
+  RELEASED/HELD/IGNORE в стиле SDLPoP (pop_ctrl.c,
+  read_user_control): действие срабатывает на переходе RELEASED→HELD,
+  затем переводится в IGNORE и не повторяется, пока клавишу физически
+  не отпустят.  Битмап при этом остаётся level-triggered.
+- **Оси**: собирать `control_x/control_y` из пар клавиш каждый кадр из
+  битмапа заново, не копить дельты.
+- `kbd_raw_sync()` звать строго один раз в кадр и строго ДО опроса
+  клавиш этого кадра.
+
+## Тестирование в MAME (bridge)
+
+- Держать клавиши через `set_input` на `:kbd:ms_naturl:*` **защёлкой**:
+  `value=1` без `frames`, потом явный `value=0`.  Вариант с
+  `frames=N` для удержаний ненадёжен (холд может не породить ни одного
+  скан-кода).  Комбинации вида Shift+стрелка так подаются нормально
+  (LShift = `:kbd:ms_naturl:P1.7` mask 0x0002, Cursor Right =
+  `:kbd:ms_naturl:P2.4` mask 0x0040) — проверено 2026-07-22.
+- Наблюдать состояние — по символам map-файла: `_kbdraw_down` (+0x12 =
+  LShift, +0x174 = Right и т.д.), `_kbdraw_overrun`; счётчики событий —
+  watchpoint с действием `{tempN=tempN+1; g}` (не останавливает
+  эмуляцию).
+- **Не тестировать вдвоём одновременно** (человек за клавиатурой +
+  бридж-эмуляция): незакрытая защёлка `set_input` выглядит как
+  «залипшая» клавиша и съедает часы отладки.
+- Overrun'ы в MAME заметно чаще, чем ожидается на железе (пачка тапа
+  прилетает плотнее реальных ~1 мс/байт); открытый вопрос — эмулирует
+  ли MAME прерывание на каждый принятый байт SIO (см. TODO).
+
+## История багов (чтобы не повторять)
+
+1. **Залипание клавиш** (2026-07-16): трамплин читал 1 байт за
+   прерывание → FIFO(3) переполнялся пачкой break-кодов → break терялся
+   → клавиша зажата навсегда.  Фикс: drain-цикл в ISR (как эталоны
+   docs/samples/sprinterKeybLib.asm, SIO_CTC_KEY.asm).
+2. **Отвал Shift** (2026-07-22): recovery по overrun сбрасывал ВЕСЬ
+   битмап; модификаторы не перечитываются typematic'ом → Shift
+   «отпускался» до перенажатия.  Фикс: селективный сброс (модификаторы
+   сохраняются), см. libc/kbd/kbd_raw_sync.c.
+
+Связанные документы: docs/mame-autotest.md, docs/im2_isr_design.md,
+docs/converted/IvanMak.txt §9.4, `../Applications/PoP-Archive/docs/PORT_PLAN.md` §2.

docs/libc-headers.md

@@ -0,0 +1,54 @@
+# Заголовки libc: контракт затенения SDCC (2026-07-06)
+
+`libc/include` стоит в -I ПЕРЕД заголовками SDCC, поэтому наш файл с
+именем стандартного заголовка «затеняет» SDCC-шный.  Два разрешённых
+паттерна:
+
+## 1. Цепочка `#include_next` — только ДОБАВЛЯЕМ
+
+Наш заголовок первым делом делает `#include_next <имя>` (берёт
+SDCC-версию) и дальше только добавляет Sprinter-расширения.  Ничего
+из стандартной части не переобъявлять — malloc/strlen/… должны
+приходить из SDCC, иначе разъедутся прототипы с z80.lib (уже кусало:
+полный shadow stdlib.h терял malloc/free).
+
+| Заголовок | Что добавляем |
+|---|---|
+| `stdlib.h` | min/max (функции, int16_t — как `int min()` в Solid-C) |
+| `string.h` | strlwr/strupr (CP866-регистры) |
+
+## 2. Полная замена — обязаны продублировать контракт SDCC
+
+Наш заголовок полностью замещает SDCC-шный.  Он ОБЯЗАН объявить всё,
+что программы берут из z80.lib, с точными SDCC-сигнатурами:
+
+| Заголовок | Обязан объявлять (из z80.lib) | Наше |
+|---|---|---|
+| `stdio.h` | printf, sprintf, vprintf, vsprintf | FILE* API (буферизованный B+), puts/putchar/getchar (наши, ESTEX), scanf-семейство, dec*/hex*, gets |
+| `time.h` | struct tm, time_t, time, mktime, gmtime, localtime, asctime, ctime — **раскладка struct tm и __TIME_UNSIGNED=1 должны совпадать с SDCC ABI** (см. шапку time.h) | datetime_t, getdatetime/setdatetime, DOW_* |
+
+При апгрейде SDCC сверять сигнатуры этих двух заголовков с
+`third_party/sdcc/share/sdcc/include/`.
+
+## 3. Свои заголовки (SDCC-аналога нет — затенения нет)
+
+conio.h, dir.h, dos.h, errno.h, fcntl.h, mouse.h, palette.h,
+sprinter*.h, unistd.h, bios/*.
+
+Графика вынесена из libc в отдельную библиотеку libbgi/: её публичные
+заголовки gfx.h (mode-agnostic BGI_GFX) и graphics.h (BGI API) живут в
+libbgi/include/ и пробрасываются через -I libbgi/include (sprinter-cc
+добавляет его автоматически).  Внутренний заголовок графики —
+libbgi/_bgi.h (слияние старых libc/gfx/_gfx.h и libc/bgi/_bgi.h).
+
+## Правила
+
+- новый стандартный заголовок — сначала пробовать паттерн 1
+  (include_next); паттерн 2 — только если надо переопределить
+  реализацию (как puts/putchar на ESTEX);
+- в заголовках паттерна 2 — комментарий, какие декларации обслуживают
+  z80.lib;
+- internal-заголовки libc (`_conio.h`, `_file.h`, …) живут
+  РЯДОМ с исходниками в libc/<area>/, не в libc/include.  Internal
+  графики — в libbgi/_bgi.h (корень libbgi/, подключается из common/ и
+  bgi256/bgi16/ как `#include "../_bgi.h"`).

docs/libc-reference.md

@@ -0,0 +1,517 @@
+# libc — справочник API (2026-07-06)
+
+Сводка по заголовкам: сигнатура + одна строка + особенности ABI.
+Детали дизайна: docs/libc-headers.md (контракт затенения SDCC),
+docs/file-buffering-design.md (FILE*), docs/solid_c_compatibility.md.
+
+Общие соглашения:
+- ошибки: возврат -1/NULL/EOF + `errno` (код DSS as-is, см. errno.h);
+- SDCC `__sdcccall(1)`: 1-й аргумент HL (8-битный — A), 2-й — DE,
+  остальные на стеке; **int/указатель возвращается в DE**;
+- строки для BIOS-вызовов (rst 8) должны лежать в #4000–#BFFF;
+- стек при любых ESTEX/BIOS-вызовах — в W2 (обеспечено crt0).
+
+## <stdio.h> — полная замена SDCC (контракт: printf-семейство из z80.lib)
+
+Из SDCC z80.lib: `printf sprintf vprintf vsprintf`.
+
+Консоль (ESTEX, без атрибутов — быстрый путь; цветной вывод — conio):
+| Сигнатура | Описание |
+|---|---|
+| `int putchar(int c)` | символ через PUTCHAR $5B; '\n'→CR LF |
+| `int getchar(void)` | блокирующий WAITKEY $30, ASCII |
+| `char puts(const char *s)` | строка + '\n' (посимвольно через putchar) |
+| `char *gets(char *buf)` | строка с консоли, без контроля длины |
+| `void dec8/dec16/dec32(v)` | десятичная печать без ведущих нулей |
+| `void hex8/hex16/hex32(v)` | hex-печать фиксированной ширины |
+
+FILE* (буферизованный, вариант B+ — единый ленивый буфер BUFSIZ=512
+на чтение/запись с автопереключением; таблица `OPEN_MAX=8` слотов;
+exit() сбрасывает всё через atexit; **ошибки записи отложенные —
+проверять fclose**):
+| Сигнатура | Описание |
+|---|---|
+| `FILE *fopen(path, mode)` | "r/w/a" + '+', 'b/t' игнорируются |
+| `FILE *fdopen(fd, mode)` | завернуть готовый fd (закрывать fclose!) |
+| `FILE *freopen(path, mode, fp)` | переоткрыть тот же FILE* |
+| `int fclose(FILE*)` / `void fclosall(void)` | сброс+закрытие / все потоки |
+| `int fflush(FILE*)` | сброс записи / откат readahead; NULL = все |
+| `int fgetc/fputc(...)` | горячий путь на asm; getc/putc — макро-алиасы |
+| `char *fgets(buf, n, fp)` | до '\n' (сохраняется); блочный LDI-сканер |
+| `int fputs(s, fp)` | без '\n'; через fwrite |
+| `size_t fread/fwrite(p, sz, n, fp)` | блоки ≥ 512 идут мимо буфера |
+| `int ungetc(c, fp)` | 1 байт putback (и на stdin) |
+| `int fseek(fp, off, whence)` / `long ftell(fp)` | ftell без побочных эффектов |
+| `void rewind(fp)` | fseek(0) + сброс EOF/ERROR |
+| `int fgetpos/fsetpos(fp, &pos)` | fpos_t = long |
+| `int feof/ferror(fp)`, `void clearerr(fp)` | флаги потока |
+| `int fprintf/vfprintf(fp, fmt, ...)` | vsprintf в статический буфер 256 |
+| `int scanf/fscanf/sscanf(...)` | %d %u %x %o %c %s, `l`, ширина, %*, %% |
+| `int rename(old, new)` | ESTEX RENAME $10 |
+
+`stdin/stdout/stderr` — консольные псевдопотоки (fd 0/-1/-2), не
+буферизуются; freopen на них меняет только FILE*-операции (printf
+идёт в ESTEX напрямую).
+
+## <stdlib.h> — include_next + добавки
+
+Из SDCC: malloc/free/calloc/realloc (heap в W2), atoi/atol/strtol/
+strtoul, rand/srand, qsort/bsearch, abs/labs, div/ldiv, exit-типы.
+Наше: `int16_t min(a,b)`, `int16_t max(a,b)` (функции, как в Solid-C).
+
+## <string.h> — include_next + добавки
+
+Из SDCC: mem*/str* полностью. Наше: `char *strlwr/strupr(char *s)` —
+in-place регистр, латиница + кириллица CP866.
+
+## <time.h> — полная замена (struct tm в SDCC-ABI, __TIME_UNSIGNED=1)
+
+| Сигнатура | Описание |
+|---|---|
+| `void getdatetime(datetime_t*)` | RTC как есть (ESTEX SYSTIME $21) |
+| `int setdatetime(const datetime_t*)` | установка RTC ($22) |
+| `time_t time(time_t*)` | Unix-эпоха из RTC |
+| `mktime/gmtime/localtime/asctime/ctime` | POSIX поверх RTC (без TZ) |
+
+`datetime_t`: day/month/year(полный)/hour/minute/second/dow (1=Вс).
+
+## <unistd.h>, <fcntl.h> — fd-уровень (манипуляторы DSS)
+
+| Сигнатура | Описание |
+|---|---|
+| `int open(path, flags)` | O_RDONLY/WRONLY/RDWR + O_CREAT/TRUNC/EXCL/APPEND (ESTEX $11/$0A/$0B) |
+| `int creat(path, mode)` | open(W|CREAT|TRUNC); mode игнорируется |
+| `int read/write(fd, buf, n)` | ESTEX $13/$14. **Квирк WRITE: DE-возврат ненадёжен, успех = CF=0&A=0** (см. memory/estex_write_de_quirk) |
+| `int close(fd)` | ESTEX $12 |
+| `long lseek(fd, off, whence)` | 32-битная позиция (MOVE_FP $15) |
+| `int unlink(path)` | удалить (DELETE $0E) |
+| `int isatty(fd)` | fd <= 0 (файловые манипуляторы DSS с 1) |
+| `int mkdir/rmdir/chdir(path)` | ESTEX $1B/$1C/$1D |
+| `char *getcwd(buf, size)` | буфер 256 байт, size игнорируется |
+| `void sleep(seconds)` | калиброванный busy-wait (см. ниже) |
+| `void delayms(uint16_t ms)` | то же, гранулярность — миллисекунды (см. ниже) |
+
+**Лимит: 8 одновременных манипуляторов**; 9-й OPEN вешает DSS —
+libc отказывает сама (EMFILE, предохранитель _fd_guard).
+
+**`sleep()` (2026-07-07, редизайн)**: старая версия считала halt-
+пробуждения (50 = 1 c), предполагая, что КАЖДОЕ прерывание — кадровый
+тик; с CBL/клавиатурой на векторе 0xFF это уже не так (CBL прерывает
+намного чаще кадра — sleep() возвращался бы раньше срока). Теперь:
+лениво, один раз калибруется кратковременным `irq_install()` против
+РЕАЛЬНОГО кадрового тика (трамплин зовёт хук только на настоящих
+кадровых прерываниях — клавиатура/CBL уходят в свои ветки раньше),
+считая, сколько итераций тесного цикла умещается в один КАДР (не в
+секунду — калибровка на секунду переполняла `uint16_t`, был баг:
+`sleep(5)` отрабатывал быстрее секунды, найден пользователем на
+реальном прогоне и исправлен). `sleep(seconds)` — вложенный цикл:
+внешний по секундам, внутренний ровно 50 раз калиброванный busy-wait —
+без единого прерывания и БЕЗ умножения/32-битной арифметики (по духу
+`docs/samples/delayms.asm`, который тоже калибрует на 1 мс, а не на
+1 с). Погрешность ~5-10% (калибровочный и рабочий циклы не тактово-
+идентичны). Fallback на старое "50 halt" поведение, если фрейм-хук уже
+занят другим `irq_install()`-клиентом (EBUSY).
+**Cтоит дороже по размеру** (~+580 Б) — тянет весь модуль `irq`
+(install/remove/трамплин/IM2-таблицу), даже если программа больше
+ничего из irq не использует.
+
+**`delayms(ms)`** — тот же движок (`libc/time/_sleep_calib.c`), общий с
+`sleep()`: калибровка одна на двоих (первый вызов ЛЮБОЙ из функций
+калибрует, вторая просто использует готовое). Производная величина
+"итераций на 1 мс" — одно 16-битное деление (`__divuint`, НЕ
+`__mullong`) на константу 20, вычисляется один раз при калибровке;
+`delayms(ms)` — простой цикл `ms` раз, без умножения вообще. Fallback
+при EBUSY — грубый (одно кадровое `halt`), точной альтернативы для
+миллисекундной гранулярности без калибровки нет.
+
+**Квирк общий для sleep()/delayms()**: калибровка сама стоит ~20-40 мс
+(синхронизация на границу кадра + сам замер) — ПЕРВЫЙ вызов ЛЮБОЙ из
+двух функций в программе превысит запрошенное время на эту величину;
+для `delayms()` с маленьким `ms` это заметно (`delayms(5)` на первом
+вызове может растянуться на ~25-45 мс). Все последующие вызовы точны.
+Оставлено как есть по решению пользователя — не стали усложнять API
+отдельным calibrate()-примитивом.
+
+## <errno.h>
+
+`errno` (int), коды = коды DSS (EOK..EUNKERR) + POSIX-имена
+(ENOENT/EBADF/EMFILE/…) + алиасы Solid-C (EZERO/EINVFNC/ENOFILE/…).
+`const char *strerror(int)`, `void perror(const char*)`.
+
+## <dos.h> — DOS-слой Solid-C
+
+| Сигнатура | Описание |
+|---|---|
+| `void getdate/gettime(&d)` | struct date/time (Turbo-C; ti_hund=0) |
+| `int setdate/settime(&d)` | RMW полного datetime |
+| `uint8_t getdisk(void)` | текущий диск, 0=A (ESTEX $02) |
+| `int setdisk(uint8_t)` | смена диска; возврат = число дисков ($01) |
+| `int absread/abswrite(disk, sect, cnt, buf)` | секторы ЛОГИЧЕСКОГО диска (BIOS $55/$56); буфер в #4000–#BFFF; abswrite минует ФС! |
+
+## <dir.h>
+
+`int ffirst(pattern, ffblk_t*, attrib)` / `int fnext(ffblk_t*)` —
+поиск по шаблону (ESTEX $19/$1A). Квирк: "."/".." находятся только
+итерацией "*.*" (memory/estex_ffirst_dotdot). FA_*-атрибуты.
+
+## <sys/stat.h>
+
+`int stat(path, struct stat*)` / `int fstat(fd, ...)` — st_mode
+(S_ISREG/S_ISDIR), st_size, st_mtime (Unix-эпоха).
+
+## <conio.h> — текстовый экран с атрибутами (Turbo-C стиль)
+
+Клавиатура: `kbhit getch getche getkey` (+KEY_* коды позиций),
+`char *cgets(buf)`.
+`uint16_t kbd_mod_state(void)` — live-состояние модификаторов ПРЯМО
+СЕЙЧАС (ESTEX CTRLKEY $33h, не событие из буфера — держится, пока
+клавиша реально зажата); (mode<<8)|shift, расшифровка KBD_MOD_*.
+Покрывает только Shift/Ctrl/Alt/Rus-Lat/Lock — для обычных клавиш
+(стрелки и т.п.) live-state у ESTEX нет, см. `<kbd_raw.h>`.
+Вывод с атрибутом: `putch cputs cprintf` (~10× медленнее stdio-пути;
+'\n' НЕ транслируется — писать "\r\n").
+Атрибуты: `textcolor textbackground textattr`, `set/get_text_attr`,
+COLOR_*-enum, `COLOR(fg,bg)`, COLOR_BLINK; `set/get_putch_raw_mode`.
+Экран: `clrscr clrscr_attr gotoxy home() wherex wherey wherexy scroll
+wrchar rdchar`; режимы `gettextmode/settextmode` (0x02=40×32,
+0x03=80×32).
+Порты/IRQ: `inp outp enable() disable()`.
+Текстовая палитра: `text_pal_load/set_color/get/get_color/reset`
+(план 0..3 → страница BIOS 4..7).
+
+## <bios/text.h> — быстрый BIOS-вывод (rst 8, place-based)
+
+`bios_set_place/get_place`, `bios_write[attr][_until|_stop]`,
+`bios_fillchar/fillattr/fillcharattr`, `bios_clearwin[_ch]`,
+`bios_scrollwin`. Строка s — в #4000–#BFFF; place продвигается.
+
+## <gfx.h> — графика, mode-agnostic API (BGI_GFX); живёт в libbgi/include
+
+Рисование (putpixel/line/bar/circle/…) вынесено в BGI — см. `<graphics.h>`
+и driver-библиотеки lib/bgi256.lib / lib/bgi16.lib (выбор режима линковкой:
+`sprinter-cc --gfx 256` / `--gfx 16`).  В gfx.h остались только функции
+БЕЗ BGI-аналога (mode-agnostic, живут в libbgi/common/, .rel в обеих
+ driver-библиотеках):
+
+Setup: `gfx_init(mode,page)→prev`, `gfx_done(prev)`.
+Страницы/банк: `gfx_set/get_visible_page`, `gfx_set/get_draw_page`
+(double buffering), `gfx_set/get_bank` (GFX_BANK_NORMAL 0x50 /
+NOSHADOW 0x54 / TRANSPARENT 0x58 / SPRITE 0x5C — аппаратные подрежимы
+записи, действуют на ВСЕ примитивы; см. docs/sprite-api-design.md).
+Блиттинг (Фаза B, 2026-07-11): `gfx_blit(x,y,img)`,
+`gfx_blit_part(x,y,img,sx,sy,w,h)` (атлас), `gfx_heal(x,y,w,h)`
+(восстановить фон из ОЗУ-копии; стирание спрайтов без save-буфера);
+img — getimage-формат, буфер вне W3; клиппинг по экрану есть.
+
+`gfx_wait_vsync()` (2026-07-07, редизайн): ждёт переход бита 5 порта
+0xFE из 1 в 0 — реальное аппаратное состояние луча (Y>256 → начало
+кадра, см. MAME sprinter.cpp kbd_fe_r), а не прерывание — поэтому не
+путается с клавиатурой/CBL/CTC, деляющими вектор 0xFF.  Бит доступен
+только пока включён `cbl_mode()` (bit7 порта 0x004E) — если приложение
+уже играет через `cbl_open()`, бит достаётся бесплатно; иначе
+`gfx_wait_vsync()` лениво занимает bit7 "немым" кодом частоты через
+`_cbl_port_ref()`/`_cbl_port_unref()` (см. `<cbl.h>`, `_cbl_port.c`) —
+разделяемое владение портом 0x004E, безопасное при любом порядке
+использования с реальным CBL-звуком.  Фолбэк на одно кадровое
+прерывание (`halt`), если бит не ведёт себя как ожидается за разумное
+число попыток.
+Шрифт: `gfx_load_default_font`, `gfx_set_font(ptr)` (interleaved
+font[row*256+char]) — грузится лениво при первом использовании BGI-текста.
+Палитра: `gfx_pal_load/set/get/get_color/reset` (страницы 0..3).
+
+Константы режимов: `GFX_MODE_320x256x256` (0x81), `GFX_MODE_640x256x16`
+(0x82); размеры `GFX_WIDTH/HEIGHT` (320/256), `GFX_WIDTH_16/HEIGHT_16`
+(640/256).  Рисование через `<graphics.h>` (BGI).
+
+## <graphics.h> — Turbo-C BGI (функц. совместимость), Фаза 1, режим 256
+
+Слой поверх `<gfx.h>` со «текущим» цветом/позицией.  Режим задаётся
+driver-либой на линковке: `sprinter-cc --gfx 256` (→ 320×256×256; 16 —
+позже).  API mode-agnostic: код не меняется при смене режима.
+Setup: `initgraph()` (без аргументов — режим фиксирован либой; грузит
+EGA-палитру 0..15, цвет=WHITE, фон=BLACK, CP=(0,0));
+`initgraph_black()` задаёт то же состояние, но перед SETVMOD очищает обе
+VRAM-страницы и сохраняет заранее погашенную аппаратную палитру для
+собственного первого fade-in;
+`closegraph()`, `graphresult()`, `cleardevice()`.
+Границы/цвет: `getmaxx/getmaxy` (319/255), `getmaxcolor` (255),
+`setcolor/getcolor`, `setbkcolor/getbkcolor`.  Константы BLACK..WHITE.
+Точки: `putpixel(x,y,c)`, `getpixel(x,y)`.
+Позиция/линии: `moveto/moverel/getx/gety`, `lineto/linerel` (двигают
+CP), `line(x1,y1,x2,y2)` (не двигает).
+Фигуры: `rectangle` (контур), `bar` (заливка стилем), `circle`.
+Дуги (Ф2a): `arc`, `ellipse(x,y,st,end,xr,yr)`, `drawpoly(n,pts)`.
+Текст 8×8: `outtextxy(x,y,s)`, `outtext(s)` (двигает CP).
+Заливки (Ф2b): `setfillstyle(pattern,color)`/`getfillsettings` (10
+паттернов Borland: SOLID/EMPTY/LINE/…/HATCH/XHATCH/…), `bar3d`,
+`fillpoly(n,pts)`, `fillellipse(x,y,xr,yr)`.
+Заливка областей (Ф2c): `floodfill(x,y,border)` (медленно, но верно),
+`pieslice(x,y,st,end,r)`, `sector(x,y,st,end,xr,yr)`.
+Образы (Ф2d): `imagesize/getimage/putimage` (COPY/XOR/OR/AND/NOT_PUT;
+формат буфера: uint16 w,h + w*h байт).  COPY_PUT и getimage — через
+accel block-copy (2026-07-11, Фаза A sprite-api-design), COPY с
+клиппингом и текущим банком; XOR/OR/AND/NOT — per-pixel.
+Спрайты (2026-07-11, Фаза B sprite-api-design): `putsprite(x,y,img)` —
+блит getimage-буфера с аппаратной прозрачностью (0xFF =
+GFX_TRANSPARENT не пишется) банком GFX_BANK_SPRITE (0x5C, фон в
+ОЗУ-копии цел); `movesprite(ox,oy,x,y,img)` — heal старой позиции +
+putsprite новой (save-буфер не нужен).  Низкий уровень в <gfx.h>:
+`gfx_blit(x,y,img)`, `gfx_blit_part(x,y,img,sx,sy,w,h)` (атлас
+кадров), `gfx_heal(x,y,w,h)` (восстановление фона из ОЗУ-копии),
+константы GFX_BANK_NORMAL/NOSHADOW/TRANSPARENT/SPRITE.  Правило: фон
+рисовать банком 0x50, спрайты/оверлеи — putsprite/0x5C; буферы
+образов — вне W3 (< 0xC000).  Тесты: tests/sprites, tests/gfxbanks,
+tests/bgi_img.
+Скролл региона из НЕактивной страницы в активную (<sprite.h>):
+`gfx_scroll_h(area, dx, dirty)` — горизонтальный (dx>0 = вправо; быстрый
+построчный accel-скролл без страйдов, DI-банды по 16 строк),
+`gfx_scroll_v(area, dy, dirty)` — вертикальный (dy>0 = вниз; прямой
+колоночный accel-проход: STOP между чтением и записью позволяет безопасно
+сменить Port_Y, промежуточный RAM-буфер не нужен). Копия = скролл + heal
+цели (банк 0x50).  Открывшуюся полосу |d| не заполняют — возвращают в
+*dirty (NULL = не нужно).  Пример: `../Examples/scroll`.
+Для произвольных EMM-данных, которые затем маппятся в W0,
+`gfx_w0_page_prepare(page)` устанавливает IRQ/NMI-стабы в `0x38/0x66` и
+запоминает штатную DSS-страницу. `atlas_load()` вызывает её автоматически.
+Стиль линий (Ф2d): `setlinestyle(style,upattern,thick)`/`getlinesettings`
+(SOLID/DOTTED/CENTER/DASHED/USERBIT + NORM/THICK) — на line/rectangle/
+drawpoly.
+Стиль текста (Ф2d): `settextstyle(font,dir,size)`/`gettextsettings`,
+`textwidth`/`textheight` — масштаб 1..10, HORIZ/VERT, прозрачный фон
+(только DEFAULT_FONT 8×8).
+Реализация: libbgi/common/*.c (mode-agnostic math + BGI public API +
+BGI_GFX) + libbgi/bgi256/*.c (256-цветные leaf'ы) → lib/bgi256.lib
+(Фаза 2 добавит libbgi/bgi16/*.c → lib/bgi16.lib; common .rel одни и
+те же в обоих архивах).  Leaf'ы — реальные реализации (БЕЗ обёрток:
+putpixel/getpixel полностью inline, _bgi_plot_raw/_bgi_hspan_raw/...
+поглощают акселераторный asm).  Пакетные примитивы — одна W3-скобка
+на примитив; тригонометрия/эллипсы целочисленные (Q7/isqrt, БЕЗ 32-бит).
+Cross-lib: libbgi всегда линкуется с libc; _cbl_port_ref/unref
+объявлены extern в libbgi/_bgi.h (сверять с libc/cbl/_cbl.h).
+Ф2d (осталось): setviewport/клиппинг, settextjustify, setaspectratio —
+см. docs/TODO.md.
+
+## <irq.h> — user-ISR кадрового прерывания (IM 2)
+
+| Сигнатура | Описание |
+|---|---|
+| `int irq_install(isr_t h)` | h зовётся ~50 Гц на кадровых прерываниях; DSS-обработчик чейнится всегда (клавиатура/SYSTIME/мышь живы). 0 / -1+errno (EBUSY повтор, EINVAL — код не в W2: только tiny/big) |
+| `void irq_remove(void)` | вернуть таблицу DSS; идемпотентно; висит на atexit |
+| `int irq_ctc_install(h, div2, div3)` | периодический таймер CTC (вектор 0x06): f = 875000/(div2×div3), div 0=256; пресет кадра IRQ_CTC_VSYNC_DIV2/3 (112×160, ~48.8 Гц); независим от кадрового; трамплин завершает RETI |
+| `void irq_ctc_remove(void)` | глушит CTC (обязательно; atexit подстрахует) |
+| `IRQ_DISABLE()/IRQ_ENABLE()` | di/ei — скобки для чтения shared-переменных из main |
+
+Handler'у нельзя: ESTEX/BIOS-вызовы, gfx_*/своп окон, акселератор,
+banked-функции; только volatile-глобалы и быстрая работа (<1 мс).
+
+## <kbd_raw.h> — эксклюзивный raw-канал клавиатуры (вектор 0xFF, свой путь)
+
+Мотивация — `../Applications/PoP-Archive/docs/PORT_PLAN.md` §2: ESTEX
+kbhit/getch/getkey/kbd_mod_state — событийные, без held-state для
+обычных (не модификаторных) клавиш.  Decode make/break (PS/2 Scan Code
+Set 2: `0xF0` — префикс отпускания, `0xE0` — префикс расширенной
+клавиши) прямо в трамплине прерывания (libc/irq/_irq_tramp.c), по
+прецеденту приватного пути CBL (не чейнится к DSS, пока открыт).
+
+| Сигнатура | Описание |
+|---|---|
+| `int kbd_raw_open(void)` | включить: с этого момента ВЕСЬ поток клавиатурных байт достаётся нам, DSS его не видит. 0 / -1+errno (EBUSY повтор) |
+| `void kbd_raw_close(void)` | выключить, вернуть клавиатуру DSS; идемпотентно; висит на atexit |
+| `uint8_t kbd_raw_down(uint16_t code)` | зажата ли code ПРЯМО СЕЙЧАС (0/1); code вне 0..511 — 0 |
+| `uint8_t kbd_raw_any_down(void)` | зажата ли хотя бы одна клавиша raw-канала (0/1); для экранов «любой клавишей» |
+| `void kbd_raw_sync(void)` | звать РАЗ В КАДР до опроса: recovery после Rx-overrun SIO — сбрасывает held-состояние всех клавиш КРОМЕ модификаторов (те не перечитываются typematic'ом; docs/kbd-games.md) |
+| `uint8_t kbd_raw_poll(void)` | вычерпать FIFO ОПРОСОМ, не дожидаясь прерывания: 0 — было пусто (~40 тактов), 1 — что-то декодировано. Звать МЕЖДУ фазами кадра, после тяжёлых блитов — не раз в кадр (см. ниже, «почему одного прерывания мало») |
+| `KBD_EXT` | ИЛИ-флаг кода: клавиша была расширенной (0xE0-префикс на проводе) |
+| `KBD_UP/DOWN/LEFT/RIGHT/SPACE/ENTER/ESC/LSHIFT/RSHIFT` | позиционные коды PS/2 Set 2 — LEFT/ESC/UP подтверждены (см. ниже); остальные — по стандарту, не перепроверены поштучно |
+| `KBD_LCTRL/LALT/RCTRL/RALT` | коды модификаторов (R* — расширенные, с KBD_EXT); добавлены 2026-07-22 |
+
+**ИСПРАВЛЕНО 2026-07-15 (был неверный вывод, ниже — то, что реально
+подтвердилось):** изначально скриншот-тестирование (снимок экрана
+после `press_key('up')`) не показывало видимого эффекта на
+UP/DOWN/RIGHT — из этого сделан ОШИБОЧНЫЙ вывод «скрипт не может их
+нажать». На самом деле причина была в неудачном таймінге снимков
+относительно дуги прыжка, а не в отсутствии сигнала. Подтверждено
+брейкпоинтом в отладчике MAME (adress уровня приложения на входе в
+код `jumping=1` в `../Applications/PoP-Archive/poc/poc.c`): `press_key('up')`
+ЧЕСТНО доходит до raw-декодера и триггерит код прыжка — брейкпоинт
+сработал ровно один раз за одно удержание клавиши (это же заодно
+подтвердило фикс двойного триггера через `up_prev` edge-detect в
+`poc.c`). Так что скриптовый `press_key` для UP/DOWN/RIGHT РАБОТАЕТ
+корректно так же, как для LEFT — предыдущая запись про «ограничение
+именно в скриптовом инжекте» была неверной, оставлена в истории
+git как урок: при повторных «нет эффекта» на скриншотах — проверять
+брейкпоинтом/watchpoint'ом на конкретный адрес кода, не полагаться
+только на визуальный снимок с произвольным таймингом.
+
+**ПОЧЕМУ ОДНОГО ПРЕРЫВАНИЯ МАЛО (`kbd_raw_poll`, 2026-08-01).**  Приёмный
+FIFO SIO — 3 байта, и рассчитывать на «каждый байт разбудит нас» нельзя:
+запрос прерывания клавиатуры держится единицы микросекунд (в dev-MAME —
+32 такта CPU, `sprinter.cpp` `on_kbd_data` → `irq_off_timer`), а ядра
+акселератора держат `DI` на весь блит — сотни микросекунд.  Импульс,
+попавший в такое окно, теряется насовсем; байт лежит в FIFO до следующего
+прерывания (следующий байт либо кадровое, 50 Гц).  Трафик же идёт пачками:
+тап стрелки = 5 байт, а при УДЕРЖИВАЕМОМ Shift PS/2 обрамляет расширенный
+код «фиктивным шифтом» (`E0 F0 12` … `E0 12`) — по 5 байт и на нажатие, и
+на отпускание.  Три ячейки такую пачку не держат: потерянный make = «нажатие
+не сработало», потерянный break = залипание.  Отсюда `kbd_raw_poll()` —
+вычерпывание тем же декодером, но из главного цикла.  Тело идёт под `DI`
+(чтение порта 0x18 деструктивно, а read-modify-write карты гонится с
+трамплином) и БЕЗУСЛОВНО делает `EI` на выходе — из ISR звать нельзя.
+
+**Как её звать (замеры 2026-08-01, PoP roomtest — читать до применения!).**
+Расстановка «несколько вызовов за кадр, после тяжёлых фаз» **не даёт
+ничего**: 9 дошедших make-байт из 10 нажатий и с ней, и без неё — такие
+вызовы попадают ровно в участки с разрешёнными прерываниями и лишь
+дублируют трамплин.  Там же измерено, что длина DI-окон графики на потери
+НЕ влияет (в кадре вообще без блитов потерь больше), а теряется байт ДО
+чтения порта: примерно 44 % импульсов запроса прерывания не обслуживаются,
+и трёхбайтовый FIFO переполняется.
+
+**Работает только ПЛОТНЫЙ опрос — порядка раза в 0.5 мс.**  Штатный способ
+взять эту частоту даром — повесить функцию idle-хуком графики:
+`gfx_set_idle_hook()` (`<gfx.h>`) зовёт её, пока `gfx_wait_vsync` крутит
+опрос луча, а это ~2/3 периода кадра.  Проверено: 35 нажатий стрелки с
+зажатым Shift → 35 дошедших make против 9 из 10 без хука.  Остаточные
+редкие потери возможны (пачка целиком внутри DI-окна одного accel-прохода);
+полный протокол и что делать дальше — `../Applications/PoP-Archive/roomtest/TASKS_CLOSED.md`,
+задача KBD-1.
+
+**ГЛАВНОЕ СЛЕДСТВИЕ:** пока `kbd_raw_open()` активен, `kbhit/getch/getkey/
+kbd_mod_state` НЕ получают новых событий (в т.ч. CTRLKEY подряд отдаёт
+то же самое, что было на момент открытия — резидентный обработчик DSS,
+от которого зависит его live-state, во время raw не выполняется).
+ESC для выхода — через `kbd_raw_down(KBD_ESC)`, не через DSS.
+
+Верификация (tests/kbdraw, MAME, 2026-07-15): `press_key` в мосте
+MAME дёргает ОБЕ клавиатуры (PC ms_naturl + ZX-матрица `IO_LINE`)
+одновременно — наблюдался паразитный незатухающий бит от ZX-пути
+(обычный код без EXT-префикса, застревал в DOWN) — не воспроизводится
+на реальном сценарии (только PC/AT-клавиатура, без матрицы, см.
+`../Applications/PoP-Archive/docs/PORT_PLAN.md` §2 — пользователь подтвердил, что
+матрица на Sprinter давно не используется).  Для будущих MAME-тестов
+этой функции — бить только по `:kbd:ms_naturl:*`, не через
+удобный `press_key` (или перепроверить точную семантику полей моста).
+
+## <cbl.h> — потоковый звук CBL/COVOX (вектор 0xFF, свой ISR)
+
+Без собственного кольца (2026-07-07): у CBL уже есть аппаратный буфер
+256 Б (2×128, двойная буферизация на стороне железа — см. официальную
+доку "5.3 COVOX-Blaster"); библиотека просто зовёт `fill()` приложения
+ИЗ ISR, а оно само пропихивает данные (откуда угодно) через
+`cbl_push_otir/accel` — без промежуточной копии.
+
+| Сигнатура | Описание |
+|---|---|
+| `int cbl_open(freq_code, fmt, pump_mode, fill)` | включить CBL (`0x90\|fmt\|freq`), зарегистрировать callback; недолив — забота приложения; **malloc не тянет**; 0 / -1+errno (EBUSY повтор, EINVAL — freq/fmt/pump_mode плохие или OTIR+16-бит) |
+| `int cbl_open_silence(freq_code, fmt, pump_mode, fill)` | то же, но тишину при недоливе шлёт libc из своего буфера; ТОЛЬКО этот вариант тянет malloc (+ENOMEM).  Буфер не освобождается — живёт до выхода |
+| `void cbl_close(void)` | выключить CBL, снять хук, освободить буфер тишины (если был); висит на atexit |
+| `void cbl_push_otir(const void *src, uint16_t n)` | пропихнуть n байт через `otir` в порт 0x4F; звать ИЗ fill() |
+| `void cbl_push_accel(const void *src, uint16_t n)` | то же акселератором (страница EMM 0xFD@0xC000); единственный путь для 16-бит |
+| `uint16_t cbl_requests(void)` | счётчик запросов блока ISR (~fs/(сэмплов в блоке) в секунду) |
+| `uint16_t cbl_underruns(void)` | счётчик недоливов (`fill` вернул 0 или не задан) |
+| `CBL_FREQ_7K8 .. CBL_FREQ_109K` | коды частоты (биты 3..0 control-порта) |
+| `CBL_FMT_MONO8/MONO16/STEREO8/STEREO16` | формат (биты 5/6 control-порта); блок 128 Б (8-бит) или 256 Б (16-бит), не зависит от моно/стерео; тишина 0x80 (8-бит) / 0x0000 (16-бит, знаковый) |
+| `CBL_PUMP_OTIR / CBL_PUMP_ACCEL` | способ выдачи — см. ниже |
+| `CBL_UNDERRUN_APP / CBL_UNDERRUN_SILENCE` | поведение при недоливе — см. ниже |
+
+`typedef int (*cbl_fill_fn)(uint16_t n);` — callback, зовётся ИЗ ISR за
+очередным блоком (n = `_cbl_block`, 128/256).  **Обязан быть быстрым**
+— никаких ESTEX/BIOS/gfx-вызовов (тот же констрейнт, что у
+`irq_install()`-хендлера); вернуть ненулевое, если реально пропихнул n
+байт.  Диск (read()) читать из fill() НЕЛЬЗЯ — см. tests/cblstream,
+где под это заведено кольцо уровня приложения.
+
+Два насоса (3-й параметр `cbl_open`):
+- **OTIR** (`_cbl_pump_otir`) — `cbl_push_otir()` в порт 0x4F; базовый.
+  **НЕ умеет 16-бит** — `cbl_open(..., MONO16/STEREO16, CBL_PUMP_OTIR,
+  ...)` вернёт EINVAL: по исходнику MAME (sprinter.cpp) порт данных
+  ВСЕГДА кладёт байт как есть в один слот, не собирая пару байт в
+  16-бит значение и не сверяясь с 16-бит флагом вообще.
+- **ACCEL** (`_cbl_pump_accel`) — `cbl_push_accel()` через акселератор
+  в спец-страницу EMM 0xFD, замапленную в окно W3 на 0xC000 (см.
+  docs/converted/accel_r.txt, Forum.txt); размер блока патчится SMC
+  (`LD D,D` + immediate `LD A,n` + `LD L,L` — тот же паттерн, что и в
+  libc/gfx/_gfx_hfill256.c); единственный путь для 16-бит.
+  **Verified в MAME 2026-07-07** (tests/cbltest, вся accel-половина
+  матрицы прошла без ошибок/underrun).
+
+Поведение при недоливе (4-й параметр `cbl_open`):
+- **CBL_UNDERRUN_APP** (по умолчанию, 0) — не забота библиотеки, буфер
+  тишины НЕ аллоцируется, в CBL доигрывает то, что уже лежало в его
+  аппаратном буфере.
+- **CBL_UNDERRUN_SILENCE** (1) — насос сам пропихивает тишину; буфер
+  (128/256 Б по формату) аллоцируется malloc'ом ВНУТРИ `cbl_open()`
+  только в этом режиме.
+`cbl_underruns()` считает недоливы в обоих режимах — диагностика,
+поведение не меняет.
+
+Приватное прерывание, к DSS не чейнится; бит 7 порта 0xFE (запрос
+блока) читается только пока `cbl_open` не закрыт (при выключенном CBL
+бит всегда 1 — MAME-квирк).
+
+**Разделяемое владение портом 0x004E** (2026-07-07): бит 5 порта 0xFE
+(позиция луча — см. `<gfx.h>` `gfx_wait_vsync()`) доступен только пока
+включён bit7 порта 0x004E, независимо от того, играет ли реальный
+звук.  `_cbl_port_ref()`/`_cbl_port_unref()` (internal, `_cbl_port.c`)
+дают gfx-модулю занять bit7 "немым" кодом частоты (не заводящим таймер
+CBL — без звука/прерываний), не мешая реальной `cbl_open()`-сессии,
+если она уже идёт (и наоборот — `cbl_close()` возвращает "немой" режим
+вместо полного выключения порта, если gfx его ещё держит).
+
+## <palette.h> — низкий уровень (BIOS $A4/$A6)
+
+`pal_load pal_get pal_set_color pal_get_color` (страница 0..7,
+записи B,G,R,0), `pal_reset(type)` / `pal_reset_at(type,page,graph)`;
+PAL_GRAPH/PAL_SINCLAIR/PAL_CGA.
+
+## <mouse.h> — драйвер RST 30h
+
+`mouse_init show hide refresh read(mouse_state_t*) goto bounds_x/y
+text_cursor load_cursor/get_cursor(mouse_cursor_t*) set_sensitivity
+get_sensitivity_x/y video_mode_changed`. Sensitivity = делитель
+(меньше = быстрее). Solid-C алиасы ms_* включены.
+
+## <sdbg.h> — логи source debugger без кода вывода Sprinter
+
+`SDBG_LOG(tag, "text={global}")` и
+`SDBG_LOGIF(tag, global_flag, "text={global}")` создают авторские
+точки журналирования в выбранном `--src-debug` TU. `tag` — уникальный
+C-идентификатор внутри TU; условие `LOGIF` пока только имя поддержанной
+global/static переменной, ненулевое значение означает вывод. Подстановки
+`{name}` читаются отладчиком при попадании; локальные и C-выражения пока
+не поддержаны. Обычная сборка превращает макросы в пустое выражение.
+Полный контракт и планы форматирования —
+[руководство по SDBG_LOG](sdbg-log-macros.md).
+Аргументы не вычисляются кодом приложения, поэтому побочные эффекты в них
+недопустимы. Сообщение видно в MAME debugger console и VS Code Debug Console
+при подключённой source-debug сессии; без неё макрос сам ничего не печатает.
+
+## <sprinter.h> — платформа
+
+Константы портов (PORT_PAGE_W0..W3, PORT_RGADR, PORT_RGMOD), номера
+всех ESTEX-функций (ESTEX_*), BIOS EMM ($C0..$C7); `__sfr`-доступ и
+inline `sprinter_page_w0..w3(page)`; ENV: `getenv putenv sysenv`.
+
+## <sprinter_mem.h> — EMM-страницы и банковый I/O
+
+`mem_alloc_pages(n)→blk_id, mem_free_block, mem_get_page(blk,idx),
+mem_info(&total,&free)` (реализации _bios/_estex; макро-выбор
+MEM_MANAGE_MODE_*). HOME-резидентный доступ к чужим страницам:
+`bank_load_byte/store_byte/read/write` (своп W3 внутри; *_w1 —
+вариант через окно W1). `bank_read_page(fd,page,off,size)` и
+`bank_write_page(fd,page,off,size)` обмениваются данными с уже открытым
+файлом в его текущей позиции. `bank_load_file(page,off,path,max_size)` сам
+открывает файл для чтения, а `bank_save_file` создаёт файл и записывает
+диапазон одним WRITE. Файловые функции возвращают фактический размер либо
+-1, восстанавливают W3 до возврата и безопасны для вызова из huge-банка.
+
+## <sprinter_exit.h>
+
+`atexit` (LIFO, 8 слотов), `exit` (хендлеры+сброс FILE), `_exit`.
+
+## <sprinter_compat.h> / <sprinter_solid.h>
+
+Типы (BYTE/BOOL/WORD/uint/FD/f_point), TRUE/FALSE/OK/ERROR,
+`setmem movmem` (порядок аргументов!), `strerr seek tell ltell
+remove _ffirst _setargv abort()`, isascii. `<sprinter_solid.h>` —
+зонтичный: один include для портирования Solid-C программ.

docs/libc-roadmap.md

@@ -0,0 +1,122 @@
+# libc — план работ (на рассмотрение, 2026-07-06)
+
+Анализ после сплита четвёрки лидеров (time/stat/file/conio, итог −19.6 КБ
+суммарно по _CODE приложений). Ниже — что ещё стоит сделать, по приоритетам.
+
+---
+
+## П1. Досплит остальной libc — СДЕЛАНО 2026-07-06
+
+Всё из таблицы ниже посплитано (кроме dec_print — осознанно оставлен).
+gfx: 40 модулей (внутренний заголовок `libc/gfx/_gfx.h`, скретчи в
+data-модулях `_gfx_state/_gfx_w3_state/_gfx_acc256/_gfx_g16_state/
+_gfx_font_state`, helpers `_gfx_hfill256/_gfx_hfill16/_gfx_rmw16/
+_gfx_text16`); video/palette → 7 модулей + `_palette.h`;
+conio/text_palette → 5 модулей.  Эффект (_CODE, Б):
+gfx_demo 3769→3227, gfx_d16 3869→3327, gfx_text 6986→2568,
+gfx_mous 7287→5542.  Не-gfx тесты не изменились.
+
+Правило было: 1 публичная функция = 1 модуль, state/helpers — в отдельные
+internal-модули, комментарии на русском, без `= 0`.
+
+| Файл | Ф-ий | _CODE | Замечания |
+|---|---|---|---|
+| gfx/gfx_256.c + gfx_16.c | 13+13 | 1277+1159 Б | самый жирный кусок; резать по примитивам (putpixel/line/hline/vline/rect/fill/clear/text). Учесть SMC-паттерны акселератора и кэш Port_Y — state в data-модули |
+| gfx/gfx_raw_16 / raw_256 / raw_common / core / palette / font / text_* | ~40 | ~2.7 КБ | вместе с предыдущим — весь gfx |
+| mouse/mouse.c | 16 | 308 Б | state mb_*/mc_* → data-модули |
+| bios/text.c | 14 | 264 Б | все `__naked`, сплит чистый |
+| io/open.c | 3+3 | 216 Б | open/creat/close; asm-хелперы `_estex_*_raw` у единственных потребителей |
+| errno/errno.c | 2 | 680 Б | strerror + таблица строк неразделимы (один модуль); perror — отдельно, зовёт strerror |
+| video/palette.c | 6 | 348 Б | |
+| conio/text_palette.c | 5 | 140 Б | |
+| io/read.c | 2 | 60 Б | read + write — обязательно врозь (write-only приложения) |
+| io/fsdir.c | 4 | 80 Б | mkdir/rmdir/chdir/getcwd |
+| env/env.c | 3 | 78 Б | getenv/putenv/sysenv + общий env_buf → data-модуль |
+| mem/mem_bios, mem_estex, bank_io_w1/w3 | 3–4 каждый | ~430 Б | |
+| sys/atexit.c | 3 | 106 Б | atexit/exit/_exit; общий стек хендлеров → data-модуль (exit тянется всегда из crt0, выигрыш небольшой но правильный) |
+| io/dir.c | 2 | 53 Б | ffirst/fnext |
+| stdlib/minmax.c | 2 | 27 Б | min/max врозь |
+| stdio/hex_print.c | 3 | 38 Б | сплит чистый (call/jp по именам) — см. docs/libc-split-asm-cases.md |
+| stdio/dec_print.c | 3 | 176 Б | НЕ резать (общее тело); открытое решение: вариант «3 независимых цикла» — п. отложен |
+
+Ожидаемый эффект: графические приложения −1–2 КБ, mouse/BIOS-text — сотни байт.
+
+## П2. FILE* — отложенные баги и недостающее
+
+Из шапки бывшего file.c («PROVISIONAL», stdio-review issues 3/4/5):
+
+- [x] fwrite: короткая запись ставит _F_ERROR (issue 3) — сделано 2026-07-06
+- [x] fgets(n=1): возвращает пустую строку по стандарту (issue 4) — сделано 2026-07-06
+- [x] mode_to_flags: проверено — парсер сканирует весь хвост режима, «rb+» работает (issue 5, уже был исправлен)
+- [x] **fprintf/vfprintf** — сделаны 2026-07-06 (vsprintf в статический 256-байтовый буфер + fwrite)
+- [x] ungetc — 1-байтный putback через поле hold; работает и на stdin — сделано 2026-07-06
+- [x] Буферизация FILE v2 — **реализован вариант B+** (2026-07-06): единый ленивый буфер BUFSIZ=512 на чтение и запись с автопереключением направления, статическая таблица OPEN_MAX=8 слотов, _fclosall через atexit, fflush(NULL) = все потоки. Дизайн: docs/file-buffering-design.md. Цена: filetest (использует всё) 7411→9929 Б _CODE; не-FILE программы не платят ничего. **Ждёт MAME-прогона: filetest, fdmax (лимит DSS), fbench (замер скорости)**
+- [ ] fdopen/freopen/fclosall/fgetpos/fsetpos — по мере надобности (Solid-C категория C)
+
+## П3. Solid-C совместимость — ЗАКРЫТ 2026-07-06
+
+Всё сделано (детали в docs/solid_c_compatibility.md): getdisk/setdisk,
+getdate/gettime/setdate/settime + <dos.h>, ltell/_setargv, errno-алиасы,
+<sprinter_solid.h>, div из SDCC (проверено), absread/abswrite (BIOS
+$55/$56 — номера найдены в solid-c DOS.ASM), **scanf/fscanf/sscanf**
+(своё C-ядро _scanf_core, 22 хост-теста), fdopen/freopen/fclosall/
+fgetpos/fsetpos (хвост П2).  bdos/brk/ioctl — отказ решением.
+Тест tests/solidt ждёт MAME-прогона.
+
+## П4. Недостающие POSIX-мелочи — ЗАКРЫТ 2026-07-06
+
+- [x] rename() — ESTEX RENAME $10 (HL=старое, DE=новое), libc/io/rename.c
+- [x] isatty(fd) — fd < 2 (манипуляторы DSS с 2; консольные псевдо-fd 0/-1/-2)
+
+## П5. Заголовки и гигиена сборки — ЗАКРЫТ 2026-07-06
+
+- [x] Контракт затенения — **docs/libc-headers.md**: include_next
+      (stdlib.h + новый string.h со strlwr/strupr) vs полная замена
+      (stdio.h, time.h — обязаны дублировать сигнатуры z80.lib);
+      из sprinter_compat.h убраны макросы min/max (конфликтовали с
+      функциями из stdlib.h; в Solid-C это тоже функции)
+- [x] libc/Makefile: stale .rel чистятся сверкой списка перед упаковкой;
+      штамп .modules триггерит перелинковку при смене состава (и сносит
+      архив — mtime на exFAT грубый)
+- [x] Все extra-тесты в top-level TESTS (43 программы: + hello2, simple,
+      banktest (переименован из banked.exe), conio2, dec_test, gets,
+      stest2, winrest, bios_text, text_palette, gfx_dbuf) и mdview2 в APPS
+- [x] Размерный регресс: toolchain/size_check.py + docs/size_baseline.tsv;
+      `make size-check` (выход 1 при росте) / `make size-baseline`
+
+## П6. Верификация после сплита — ЗАКРЫТ 2026-07-06 (MAME; железо — отдельно)
+
+- [ ] `make floppy` + прогон в MAME ключевых тестов (conio, filetest, ptime,
+      stattest, mouse, gfx_demo) — линковка прошла, но поведение надо
+      подтвердить на эмуляторе
+- [ ] Потом на железе (mdview2 и так ждёт проверки на железе — совместить)
+
+## П7. Документация — ЗАКРЫТ 2026-07-06
+
+- [x] **docs/libc-reference.md** — справочник API по всем заголовкам
+- [x] docs/TODO.md переписан: открытое наверху, закрытые этапы (5-10)
+      в «Истории»; протухшие пункты (FILE rewrite «для v2») сняты
+- [x] **CLAUDE.md** создан: сборка/проверка, правила libc (1 ф-я =
+      1 модуль, `_`-модули, русские комментарии, без `= 0`,
+      asm-правила), ABI-шпаргалка, квирки, структура
+
+## П8. Смежное (не libc, из TODO.md — чтобы не потерялось)
+
+- auto-banking Phase 1 (toolchain/auto_bank.py) — когда проект перерастёт ~30 КБ
+- IM2 ISR v2 (docs/im2_isr_design.md) — отложено решением 2026-06-01
+- font-quad для 640×256 (per-cell палитра)
+- factoring parse_argv из crt0/crt0_banked в общий argv.s
+- check_banks.py: разбивка code/const/bss per bank (косметика)
+
+---
+
+## Предлагаемый порядок
+
+1. **П1-лайт**: io/env/errno/atexit/minmax/mem/dir/fsdir (мелкие, час работы,
+   выигрыш для всех CLI-приложений) + mouse + bios/text.
+2. **П6**: MAME-смоук — подтвердить, что сплит ничего не сломал в рантайме,
+   до того как менять что-то ещё.
+3. **П1-gfx**: разбор графики (самый большой кусок, отдельный заход).
+4. **П2**: баги FILE* (3 шт.) + fprintf + ungetc.
+5. **П3/П4**: solid-c остатки + rename/isatty.
+6. **П5/П7**: гигиена сборки и документация — фоном, по кусочку.

docs/libc-split-asm-cases.md

@@ -0,0 +1,52 @@
+# libc split: asm-связки между функциями
+
+Журнал случаев, найденных при разбиении libc на «1 публичная функция = 1 модуль»
+(2026-07-05). Сюда записывается каждый обнаруженный переход `jr _func` или
+`jr/jp/call` на метку **внутри другой функции** — такие связки нельзя разрывать
+механически, разбираем каждую отдельно.
+
+## Правила (справка)
+
+| Паттерн | Через границу модулей |
+|---|---|
+| `call/jp _func` (публичная C-функция) | работает — метка глобальная (`::`) |
+| `call/jp _label` на метку в чужой функции | работает, только если метка объявлена `_label::` |
+| `jr` / `djnz` в другой модуль | **запрещено** — ±128 байт, разложение модулей не гарантировано |
+| fall-through (без перехода, в надежде на соседство) | **не работает никогда** |
+
+## Случаи
+
+### 1. stdio/dec_print.c — dec8/dec16/dec32: разделяемое тело (НЕ разрывать)
+
+Статус: **оставлены в одном файле, решение отдельно.**
+
+- `dec8` → `jp __dec_entry3` — прыжок в середину тела `dec32`;
+- `dec16` → `jp __dec_entry5` — то же;
+- метки уже глобальные (`__dec_entry3::`, `__dec_entry5::`) — линковаться будет,
+  но выигрыша от сплита нет: dec8 всё равно притянет модуль с телом dec32;
+- внутри хвоста: `_dec_get_d16` **fall-through** в `_dec_emit_or_skip`,
+  `_dec_get_d32` → `jr _dec_emit_or_skip`, общий флаг `_dec_flag`.
+
+Это осознанный дизайн из solid-c: тройка делит per-digit код. Варианты на потом:
+(а) оставить как есть (176 Б тянутся целиком — терпимо);
+(б) развести на 3 независимых цикла — dec8 станет ~40 Б, но исходник длиннее
+и суммарно в exe, использующем dec8+dec32, станет хуже. Решение отложено.
+
+### 2. stdio/hex_print.c — чист
+
+`hex16` → `call _hex8` / `jp _hex8` (tail), `hex32` → `_hex16`: переходы по
+именам публичных функций. Разъезжается на hex8.c/hex16.c/hex32.c без правок.
+`_hex8_digit` — self-call внутри hex8, не мешает.
+
+### 3. conio/conio.c — jp _clrscr_attr (чист)
+
+`clrscr` → `jp _clrscr_attr` — tail-call публичной функции, работает через
+модули как есть.
+
+### 4. mem/mem_bios.c, mem/mem_estex.c — jp __errno_set (чист)
+
+Tail-call публичного internal-хелпера `_errno_set` — кросс-модульный уже сейчас.
+
+---
+Все прочие `jr`-переходы в libc (проверены все `jr`, включая условные формы,
+2026-07-05) ведут на метки внутри своей же функции — сплиту не мешают.

docs/mame-autotest.md

@@ -0,0 +1,285 @@
+# Автотестирование в MAME
+
+Единый справочник: как запускать программы Sprinter в эмуляторе MAME
+**без участия человека**, вводить команды, снимать скриншоты, завершать
+сессию и анализировать результат.  Если нужно что-то про автотесты в
+MAME — смотреть сюда.
+
+Весь механизм собран в одном инструменте: **`toolchain/mame_interactive.py`**.
+
+---
+
+## 1. TL;DR
+
+```bash
+# собрать .exe (пример)
+make -C tests/bgitest
+
+# запустить в MAME, снять экран, выйти по таймауту
+python3 toolchain/mame_interactive.py tests/bgitest/bgitest.exe \
+    --mame-home /путь/к/MAME/runtime --snap 12,14 --timeout 16
+```
+
+Инструмент сам:
+1. соберёт отдельную временную FAT12-дискету с `.exe`;
+2. создаст отдельные каталоги MAME для cfg/NVRAM/diff/snapshot;
+3. запустит MAME с драйвером `sprinter`;
+4. в момент `--launch-at` **напечатает `a:\bgitest.exe` + Enter**
+   (эмулируя нажатия клавиш); выбирайте время после загрузки DSS;
+5. снимет скриншоты в указанные секунды эмулированного времени;
+6. завершит сессию по таймауту;
+7. выведет пути к PNG-скриншотам.
+
+Скриншоты лежат в `build/mame-autotest/<session>/sprinter/` (`0000.png`,
+`0001.png`, …) относительно каталога запуска. Их можно читать визуально — текст с экрана
+программно НЕ распознаётся.
+
+---
+
+## 2. Инструмент: `mame_interactive.py`
+
+```
+python3 toolchain/mame_interactive.py [exe] [--data f ...] \
+    [--mame-home DIR] [--mame-bin FILE] [--launch-at T] \
+    [--step "T:TEXT" ...] [--snap t1,t2,...] [--timeout N]
+```
+
+| Аргумент | Назначение |
+|----------|-----------|
+| `exe` | `.exe` кладётся на A: и **авто-запускается** (печатается `a:\<exe>`+Enter в момент `--launch-at`). Без `exe` работаем на голой командной строке. |
+| `--data f ...` | доп. файлы на дискету A: (данные для теста). |
+| `--launch-at T` | секунда, когда печатается запуск `exe` (по умолчанию **8**). |
+| `--step "T:TEXT"` | в момент `T` сек напечатать `TEXT`. Можно много раз — диалог с уже запущенной программой. В `TEXT`: `\n`=Enter, `\t`=Tab; заглавные и символы через Shift — автоматически. |
+| `--snap t1,t2,...` | секунды эмуляции для скриншотов. По умолчанию: `launch_at+4` и `+6` (для `exe`), либо сразу после последнего ввода. |
+| `--timeout N` | секунд эмуляции до принудительного выхода. По умолчанию — чуть позже последнего скриншота. |
+| `--mame-home DIR` | установленная среда MAME; можно задать переменной `MAME_HOME`. |
+| `--mame-bin`, `--mame-rompath`, `--mame-dss-image`, `--mame-system-hdd-image`, `--mame-bios` | выбор отдельных частей профиля; соответствуют `MAME_*` из окружения. |
+| `--snapshot-dir DIR` | локальный каталог кадров вместо `build/mame-autotest`. |
+
+**Важно:** все времена — это **секунды эмулированного времени от старта
+машины** (не от нажатий, их «нет»).  Загрузка DSS до `C:\>` занимает
+~7 секунд, поэтому `--launch-at 8` и скриншоты с ~12 с.
+
+### Типовые рецепты
+
+```bash
+# 1. Запустить тест и снять результат (самый частый случай)
+python3 toolchain/mame_interactive.py tests/rt_test/rt_test.exe \
+    --snap 12,14 --timeout 16
+
+# 2. Набрать команду на голой командной строке (без exe)
+python3 toolchain/mame_interactive.py --step "8:dir\n" \
+    --snap 10,11 --timeout 12
+
+# 3. Запустить программу и ответить на её ввод (например, выбор пункта меню)
+python3 toolchain/mame_interactive.py tests/menu/menu.exe \
+    --step "13:2\n" --snap 15 --timeout 17
+
+# 4. Тест с файлом-данными на дискете
+python3 toolchain/mame_interactive.py /путь/к/Examples/mdview2/mdview2.exe \
+    --data doc.md --step "13:mdview2 doc.md\n" --snap 16 --timeout 18
+```
+
+---
+
+## 3. Как это работает внутри
+
+### 3.1 Запуск MAME
+
+Профиль `MAME_HOME` выбирает `mame.arm`, `roms/`, DSS-дискету и системный
+CHD. A: — временная дискета этого запуска; B: — DSS. При наличии в
+установленной среде CD/NeoGS/медиа скрипт подключает их как необязательные
+устройства. `-cfg_directory`, `-nvram_directory`, `-diff_directory` и
+`-snapshot_directory` указывают в изолированный каталог сессии;
+`-autoboot_script` получает сгенерированный Lua-файл.
+
+### 3.2 Ввод с клавиатуры — ключевой момент
+
+У Sprinter в MAME **две** клавиатуры:
+
+- `IO_LINE0..7` — легаси ZX-Spectrum-матрица (порт `0xFE`). DSS её для
+  командной строки **НЕ читает**.
+- `root:kbd:ms_naturl` — **настоящая AT/PS-2 клавиатура**, подключённая
+  последовательно к SIO Z84C015 (`sprinter.cpp:2037`). Именно её DSS
+  читает как поток scancode'ов.
+
+Поэтому **не работают** (проверено многократно): `natkeyboard:post`,
+`-autoboot_command`, а также `set_value` по полям `:IO_LINE*`.  Всё это
+бьёт в ZX-матрицу, которую DSS игнорирует.
+
+**Работает** — прямое управление полями AT-клавиатуры из Lua:
+```lua
+manager.machine.ioport.ports[":kbd:ms_naturl:P1.4"].fields["D"]:set_value(1)  -- нажать
+... подождать ~0.06с ...
+manager.machine.ioport.ports[":kbd:ms_naturl:P1.4"].fields["D"]:set_value(0)  -- отпустить
+```
+`at_keyboard` сам сгенерит make/break scancode'ы → SIO → DSS.
+
+Скрипт хранит раскладку `char → (порт, битовая маска)` (словарь `PHYS` +
+`SHIFTED` для Shift-символов) и разворачивает строку в список
+timed-событий `(время, порт, маска, значение)`.  Backslash `\` в
+AT-клавиатуре есть (поле `P2.1`/0x4) — путь `a:\name.exe` вводится
+полностью.
+
+### 3.3 Тайминг (Lua)
+
+Временный Lua-файл через
+`emu.register_periodic` на каждом кадре сверяет **эмулированное время** и
+проигрывает события ввода, снимает скриншоты и завершает сессию.
+
+Время берётся как `t.seconds + t.attoseconds/1e18`, потому что
+`attotime.seconds` — **целое** (дробную часть отбрасывает); если считать
+по нему, все события схлопнутся в 1-секундную сетку.
+
+Старт отсчёта — `emu.add_machine_reset_notifier` (НЕ `emu.register_start`
+— он deprecated).
+
+### 3.4 Скриншоты
+
+`manager.machine.video:snapshot()` пишет PNG в каталог из
+`-snapshot_directory` внутри `build/mame-autotest/<session>/sprinter/`.
+Каждый запуск создаёт свой каталог и печатает пути к PNG; другие сессии не
+затрагиваются.
+
+### 3.5 Завершение сессии
+
+Два рубежа, чтобы MAME гарантированно завершился:
+- в Lua: при `elapsed >= timeout` → `manager.machine:exit()` (чистый
+  выход);
+- снаружи: `subprocess` ожидает с ограничением wall-clock времени, затем
+  завершает только собственный процесс MAME.
+
+---
+
+## 4. Предпосылки (окружение)
+
+- **MAME**: задайте `MAME_HOME=/путь/к/MAME/runtime` с бинарником,
+  `roms/`, `IMG/dss171u.img` и `IMG/sp_hdd_sys.chd`. Исходники fork не нужны.
+- **Загрузка должна доходить до `C:\>`.**  `system.bat` на системном
+  диске НЕ должен автоматически запускать Flex Navigator или приложение —
+  иначе мы не попадём на командную строку и ввод уйдёт в чужую программу.
+  (Это файл на HDD-образе, вне репозитория; правится один раз.)
+- **Одновременный запуск нескольких MAME не проверялся.** Автотест создаёт
+  отдельные A:, state и снимки и при необходимости копирует системный CHD,
+  но это ещё не доказывает корректность параллельной работы. Особенно не
+  гарантируется работа нескольких процессов через MCP bridge: выбор процесса,
+  идентификатор сессии и арбитраж требуют отдельной проверки.
+
+---
+
+## 5. Как выбирать времена
+
+- **Загрузка до `C:\>`:** ~7 секунд → `--launch-at 8` безопасно.
+- **Набор пути `a:\name.exe`:** ~13 символов × 0.14с ≈ 1.8с → команда
+  уходит около 9.8с, программа стартует ~10с.
+- **Скриншот:** давайте программе дорисоваться.  Быстрая программа —
+  снимать с ~12с; если рисует долго/по частям, снимайте несколько кадров
+  (`--snap 12,16,20`) и смотрите, где картинка «дособралась».
+- **Диалог с программой (`--step`):** времена шагов ставьте ПОСЛЕ старта
+  программы (например, запуск на 8с, ответ на ввод на 13–15с).
+
+---
+
+## 6. Анализ результата
+
+- Скриншоты — **единственный** способ проверки: программного чтения
+  текстового/графического VRAM нет, OCR нет.  Claude читает PNG глазами
+  (инструмент Read с картинкой).
+- Лог MAME фильтруется по строкам `[interactive]` (моменты снимков и
+  выхода) — видно, в какие секунды сделаны кадры.
+- Если картинка «не дособралась» — снять более поздний кадр (увеличить
+  `--snap`/`--timeout`).
+
+---
+
+## 7. Раскладка клавиатуры (справочно)
+
+Раскладка снята дампом ioport-полей `:kbd:ms_naturl:*` живой машины.
+Она зашита в `PHYS`/`SHIFTED` внутри `mame_interactive.py`.  Поддержаны:
+буквы (a–z, A–Z через Shift), цифры, пробел, Enter (`\n`), Tab (`\t`),
+и символы ``- = [ ] \ ; ' , . / ` `` плюс их Shift-версии
+`! @ # $ % ^ & * ( ) _ + { } | : " < > ? ~`.
+
+Если понадобится клавиша вне списка — снять её поле дампом (пример
+Lua-пробы ниже) и добавить в `PHYS`:
+
+```lua
+-- дамп всех полей клавиатуры в лог
+for tag, port in pairs(manager.machine.ioport.ports) do
+  if tostring(tag):find("kbd") then
+    for fname, field in pairs(port.fields) do
+      print(string.format("%s  mask=0x%x  %q", tag, field.mask, fname))
+    end
+  end
+end
+```
+
+---
+
+## 8. Квирки и грабли (все, на которые уже наступали)
+
+- **`attotime.seconds` — целое.** Субсекундный тайминг только через
+  `seconds + attoseconds/1e18`.
+- **Автоповтор (typematic).** Клавишу держать коротко (~0.06с). Если
+  держать ~1с — `d` превратится в `dddddd`.
+- **Слипание scancode'ов.** Между символами ~0.14с.
+- **Не та клавиатура.** Ввод — только в `:kbd:ms_naturl`, НЕ в
+  `:IO_LINE*`, НЕ через `natkeyboard`/`-autoboot_command`.
+- **Загрузка мимо `C:\>`.** Если `system.bat` что-то автозапускает —
+  ввод уходит в чужую программу; вернуть чистую командную строку.
+- **Висящие копии MAME.** Всегда проверять перед запуском.
+- **macOS-специфика (справочно):** известный баг MAME
+  (mamedev/mame#10612 — потеря ввода в fullscreen при движении мыши на
+  старте) к нам НЕ относится: работаем в `-window`, ввод скриптовый.
+
+---
+
+## 9. На будущее (заметки, ещё не в инструменте)
+
+- **Быстрый накопитель.** Тестам, которым важна скорость диска (напр.
+  потоковое чтение), имеет смысл копировать файлы с медленной дискеты A:
+  на HDD `C:\TEMP` перед запуском.
+- **Видео+звук.** MAME умеет писать AVI (`-aviwrite`) — для тестов с
+  анимацией/звуком, где скриншотов мало.  Пока не подключено к скрипту.
+- **Ручная отладка ввода.** Запуск MAME с `-console` даёт интерактивный
+  Lua-REPL — удобно нащупывать поля/тайминги вживую перед скриптованием.
+- **Второй видеорежим/варианты BIOS** — выбирать `MAME_BIOS` или отдельные
+  аргументы профиля.
+
+## 10. Архивные тайминги старого MCP-моста
+
+Ниже сохранены измерения прежнего ручного запуска через `run_bridge.sh` и
+`bridge_cmd.sh`. Они не задают таймауты нового автотеста и DAP: автотест
+использует изолированные носители, а DAP ждёт стабильный prompt DSS в VRAM.
+
+| шаг | пауза ПОСЛЕ шага |
+|-----|------------------|
+| запустили `run_bridge.sh` | **6 с** → машина поднялась, можно слать `go` |
+| `go` (снять с дебаггерного стопа) | **8 с** → DSS догрузился, принимает ввод |
+| `keyseq d:{ENTER}` + `keyseq roomtest{ENTER}` | **5 с** → программа уже стартовала |
+
+То есть весь цикл «перезапуск + старт теста» укладывается в ~20 секунд.
+
+Пересобрал HDD-образ (`make hdd`) → MAME **обязан** полный рестарт
+(`chdman -f` даёт новый inode; см. memory `mame_hdd_rebuild_restart`):
+остановка через `exit` в дебаггере, затем `run_bridge.sh` заново.
+
+## 11. Карта C/asm для отладки
+
+`SRC_DEBUG=1` в app.mk создаёт проверенный пакет исходников и адресов без
+изменения EXE в проверенных конфигурациях. Пер-модульный вариант:
+`SRC_DEBUG_FILES=helper.c`. Команды карты и результаты живых экспериментов:
+[mame-source-debug-status.md](mame-source-debug-status.md); полный план:
+[mame-source-debug.md](mame-source-debug.md). Базовый C-attach/where/точки и
+чтение простых переменных доступны через `toolchain/sdbg_session.py`.
+`sdbg_server.py`, DAP MVP, VS Code launch и development-расширение уже есть;
+безопасный restart и MCP C-уровня пока не готовы. `-debugger none`
+автоматически продолжает CPU и не подходит для ожидания команд пошаговой
+сессии.
+
+Source-debug launcher ждёт до 10-й секунды эмулируемого времени, сохраняет
+снимок готового DSS, только затем вооружает entry breakpoint и вводит команду
+EXE. Пользовательские точки создаются после проверенного `main`, когда
+`_bank_pages` уже заполнена. В обычной конфигурации это даёт 0 попаданий на
+адрес entry во время загрузки DSS. Автоматического распознавания приглашения
+`C:\\>` пока нет; `launchAt` в VS Code можно увеличить.

docs/mame-source-debug-status.md

@@ -0,0 +1,329 @@
+# Отладка исходников: реализация и результаты
+
+Дата: 2026-09-15. План: [mame-source-debug.md](mame-source-debug.md).
+Реализованы сборка/карта, проверенный транспорт, базовая C-сессия,
+постоянный session server, DAP MVP, VS Code launch и build task. MCP C-уровня,
+безопасный restart и расширенная отладка ещё не готовы.
+Этапы плана не считаются завершёнными целиком по одному успешному репро.
+
+## Статус платформ
+
+- **macOS:** текущий end-to-end цикл проверен, включая backend `sdbg` и
+  одновременную работу VS Code со штатным `osx` debugger MAME.
+- **Linux:** ожидается работа через `sdbg`, `qt` или `imgui`, но полный
+  живой прогон ещё не выполнен.
+- **Windows:** весь функционал пока работать не будет. Provider
+  `debugger: "windows"` открывает штатный debugger MAME, однако host-часть
+  использует `fcntl`, Unix domain sockets и Unix launcher. Native Windows
+  launch/attach из VS Code официально не поддерживается до реализации
+  переносимого транспорта, блокировки, запуска и end-to-end тестов.
+
+## Доступно сейчас
+
+- `bin/sprinter-cc --src-debug` и повторяемый `--src-debug-file FILE`.
+- `app.mk`: `SRC_DEBUG=1` либо `SRC_DEBUG_FILES=...`; выбор интерпретатора
+  через `PYTHON` в make и `SPRINTER_PYTHON` у обёртки. В проекте используется
+  local pyenv Python 3.12 (`.python-version`); личный путь не зашит в код.
+- Уникальные имена CDB-позиций и TU, включая повторные метки внутри одного
+  модуля. Публичные C/asm-символы и инструкции не переименовываются.
+- Сборка в отдельном временном каталоге с проверкой пакета перед публикацией.
+  Ошибка compiler/linker/парсера сохраняет предыдущие EXE и пакет.
+  Конкурентные debug-сборки одного output сериализованы; одновременная
+  обычная и debug-сборка одного output пока не поддерживается.
+- Manifest: build ID, хеш EXE/артефактов/исходников/включённых заголовков,
+  сохранённые исходники, параметры памяти, команды, версия SDCC и выбранные TU.
+  Зависимости собираются также для TU без карты в пер-модульном режиме.
+- Проверяемый JSON-индекс `.sdbg.json`, offline CLI функций, переменных,
+  символов и соответствия C/asm/адресов. Банковые адреса учитывают секцию
+  и окно huge/big; банк данных не трактуется как резидентная память.
+- Пересборка make при смене команды/содержимого зависимостей. Быстрая правка
+  заголовка не зависит от секундной точности mtime; повторный make без
+  изменений не вызывает compiler.
+- Отдельный плагин `toolchain/mcp/sdbgbridge`, загружаемый непосредственно
+  из репозитория через pluginspath. Он не заменяет существующий mamebridge
+  и не требует копирования изменённых файлов в игнорируемое дерево MAME.
+- Версия протокола, ID сессии, generation, атомарные файловые ответы,
+  ограниченный журнал событий, stopped snapshots, чтение logical memory
+  с отключёнными side effects, pause/continue/instruction step и точки
+  с проверкой владения. FileBridge запрещает повтор mutations после timeout.
+- `DebugSession` проверяет EXE, Intel HEX и исполняемые байты реально
+  загруженного resident/current-bank образа перед интерпретацией PC. Он читает
+  `_bank_pages`, отвергает нули/дубликаты и учитывает, что state MAME хранит
+  старшие флаги над 8-битным значением page-port.
+- Точки по строке и функции, удаление логической группы, `where` и чтение
+  поддержанных 1/2/4-байтных global/static. Банковская точка получает условие
+  по I/O page-port (`ib@e2==...` для W3), формируемое самим plugin; произвольная
+  debugger expression через этот вызов не принимается. Resident-объект или
+  bank-data не читается, если его физическая страница сейчас закрыта.
+- Bootstrap живого теста не держит entry-breakpoint во время загрузки DSS.
+  Он активирует единственную service-точку перед вводом команды запуска,
+  сверяет сигнатуру/образ на `main`, а исходные точки ставит после attach.
+  Банковые пользовательские точки нельзя безопасно активировать до заполнения
+  `_bank_pages`, поэтому они намеренно создаются после runtime init.
+- `sdbg_server.py` — единственный долгоживущий владелец backend. Локальный
+  Unix JSON-RPC допускает несколько клиентов, сериализует команды, хранит
+  логические группы и события. `set_source_breakpoints` и
+  `set_function_breakpoints` создают новый disabled-набор, при ошибке удаляют
+  его, затем заменяют прежний набор и активируют точки.
+- DAP MVP и минимальное VS Code-расширение: attach к session server,
+  source/function breakpoints, один достоверный frame, registers,
+  поддержанные globals/statics, evaluate одного имени, continue/pause и
+  instruction step. F11 идёт до другой C-позиции, F10 использует MAME `over`,
+  Shift+F11 выходит через bank trampoline до C-позиции caller. Автомат имеет
+  предел 512 машинных операций и сохраняет приоритет пользовательской точки.
+  Длинный вызов с ожиданием внешнего ввода не блокирует DAP; Pause доступен.
+  Неподдержанные setVariable, disassemble, restart/terminate не рекламируются
+  либо возвращают явную ошибку.
+- Собственное расширение является обязательной Sprinter-частью интеграции:
+  готовые C/C++ или clangd можно добавить для редактирования, но они не знают
+  source-debug package, DSS, банки и MAME DAP. Версия 0.2.0 даёт TaskProvider
+  для приложений с `app.mk`, команду Build Active Project и автоматическую
+  debug-сборку перед F5. Она использует `make SRC_DEBUG=1` и local Python 3.12;
+  ошибки SDCC с файлом/строкой попадают в Problems. Код сборки проверяется
+  самим расширением: при ошибке MAME не запускается. Run-команда, расширенные
+  linker/assembler diagnostics, выбор profile/EXTRA_DATA и VSIX остаются
+  следующими шагами.
+- DAP `logMessage` без пересборки: разрешены литералы, `{{`/`}}` и только
+  подстановки `{variable}`. Session server читает типизированное значение,
+  отправляет `output` и продолжает CPU. Совпавшая обычная точка имеет
+  приоритет остановки, поэтому logpoint её не проглатывает. Произвольные
+  выражения, format specifier и conversion намеренно отвергаются.
+- `<sdbg.h>`: `SDBG_LOG(tag, "total={total}")` и ограниченный
+  `SDBG_LOGIF(tag, flag, "...")` создают нулевые asm-якоря только в
+  выбранном debug-TU. Метаданные приходят из активного препроцессорного
+  потока; package содержит связанный адрес/причину unverified. Session server
+  автоматически ставит эти точки после attach, зеркалирует текст в MAME
+  debugger console и DAP Debug Console, затем продолжает CPU. Совпавшая
+  пользовательская точка по-прежнему останавливает исполнение. Локальные,
+  C-выражения и printf-форматы пока не доступны; значения читаются из
+  поддержанных global/static объектов, исходное приложение не печатает в DSS.
+  DAP event ring ограничен 1024 событиями; если клиент отстал, Debug Console
+  показывает число пропущенных событий. Частые logpoints останавливают CPU
+  при каждом попадании, их overhead пока не измерен. DAP хранит точный UTF-8
+  текст; MAME `printf` получает безопасную проекцию: кавычки заменяются
+  апострофом, управляющие символы — пробелами.
+  Практический контракт и таблица типов —
+  [руководство по SDBG_LOG](sdbg-log-macros.md). Decimal/hex formatter,
+  форматированный адрес и значение по ненулевому указателю — задачи финального
+  этапа, сейчас не поддерживаются. Для него `char *` задан как строка,
+  `int8_t *`/`uint8_t *` — как один 8-битный объект; текущий CDB не
+  различает `char *` и `uint8_t *`, поэтому нужна metadata declared type.
+- `sdbg_launcher.py` реализует VS Code launch: создаёт временную дискету,
+  копию системного HDD и отдельные state-каталоги, показывает окно Sprinter,
+  ждёт DSS, ставит только service-точку `main`, вводит `a:\\NAME.EXE`,
+  проверяет сигнатуру entry и запускает session server. Закрытие DAP
+  завершает только созданные им server/MAME и удаляет временный каталог.
+
+## Использование карты
+
+В shell без инициализированных pyenv shims используйте `pyenv exec`:
+
+```sh
+pyenv exec make -C tests/hello SRC_DEBUG=1
+pyenv exec python toolchain/sdbg.py --build tests/hello/.sprinter-cc-hello verify
+pyenv exec python toolchain/sdbg.py --build tests/hello/.sprinter-cc-hello map
+pyenv exec python toolchain/sdbg.py --build tests/hello/.sprinter-cc-hello vars
+pyenv exec python toolchain/sdbg.py --build tests/hello/.sprinter-cc-hello line2addr hello.c 33
+```
+
+`addr2line` принимает адрес **линковщика** с префиксом `0x`, например
+`0x1c00c`, а не логический PC без информации о банке. Ответ включает
+logical_address, bank, window, функцию, инструкцию `.asm` и все найденные
+исходные позиции. Неизвестный адрес возвращает unknown. Неоднозначности
+не скрываются; изменённый исходник имеет stale-статус, сохранённый текст
+собранной версии остаётся в пакете.
+
+Для одной TU: `pyenv exec make -C tests/banked SRC_DEBUG_FILES=bank1.c`.
+Режимы all/selected взаимоисключающие. `--debug` по-прежнему означает
+runtime DEBUG_RT и не включает карту C.
+
+Низкоуровневый live CLI работает с уже запущенным `sdbgbridge`; его IPC и
+session ID должны совпадать с окружением процесса MAME:
+
+```sh
+pyenv exec python toolchain/sdbg_session.py \
+  --build tests/hello/.sprinter-cc-hello \
+  --ipc "$SDBG_IPC_DIR" --session "$SDBG_SESSION_ID" attach
+```
+
+Доступны `where`, `step`, `continue`, `break-line`, `break-function`,
+`read-variable`, `activate-breakpoints` и `deactivate-breakpoints`.
+Это диагностический однооперационный CLI: логические ID групп точек живут
+только внутри процесса. Постоянное владение и DAP добавятся в общем session
+server; до него для долгой ручной работы нужен один Python-процесс с
+`DebugSession`.
+
+Предпочтительный режим для нескольких клиентов — один server:
+
+```sh
+pyenv exec python toolchain/sdbg_server.py \
+  --build tests/hello/.sprinter-cc-hello \
+  --ipc "$SDBG_IPC_DIR" --session "$SDBG_SESSION_ID" \
+  --socket /tmp/sprinter-sdbg.sock
+
+pyenv exec python toolchain/sdbg_client.py \
+  --socket /tmp/sprinter-sdbg.sock status
+```
+
+VS Code-расширение находится в `toolchain/vscode-sprinter-debug/`. В
+Extension Development Host используется attach-конфигурация:
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "attach",
+  "name": "Sprinter MAME: Attach",
+  "socket": "/tmp/sprinter-sdbg.sock"
+}
+```
+
+В VS Code расширение `0.2.0` запускает адаптер через абсолютный путь к local
+pyenv shim `~/.pyenv/shims/python` и задаёт корень workspace как `cwd`.
+Это устраняет зависимость от `PATH` процесса VS Code, открытого из Dock.
+Выбранные пути видны в Output → `Sprinter MAME Debug`; при раннем сбое
+launcher сообщает stderr и последние строки MAME log.
+Интегрированный запуск:
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "launch",
+  "name": "Sprinter MAME: Launch",
+  "build": "${workspaceFolder}/tests/hello/.sprinter-cc-hello"
+}
+```
+
+Launcher читает text-mode descriptors из VRAM и ждёт стабильный пустой prompt
+`X:…>` 0,25 секунды. `dssTimeout` по умолчанию равен 30 эмулируемым секундам;
+`launchAt` теперь только необязательная нижняя граница. Перед вводом launcher
+сохраняет снимок DSS.
+Пошаговый запуск development-расширения описан в
+[vscode-sprinter-debug.md](vscode-sprinter-debug.md).
+
+## Воспроизводимые проверки
+
+```sh
+pyenv exec python -m unittest discover -s tests/sdbg -v
+pyenv exec python tests/sdbg/run_mame_probe.py
+pyenv exec python tests/sdbg/run_mame_probe.py --bridge
+pyenv exec python tests/sdbg/run_mame_probe.py --bridge --banked
+pyenv exec python tests/sdbg/run_mame_probe.py --bridge --banked --server
+pyenv exec python tests/sdbg/run_mame_probe.py --banked --launcher
+pyenv exec python tests/sdbg/run_mame_probe.py --banked --launcher --native-debugger
+pyenv exec python tests/sdbg/run_mame_probe.py --banked --launcher --source-step
+pyenv exec python tests/sdbg/run_mame_probe.py --banked --launcher --step-out
+pyenv exec python tests/sdbg/run_vscode_dap_probe.py
+pyenv exec python tests/sdbg/run_vscode_dap_probe.py --waitkey --manual-key
+```
+
+Живой тест использует отдельную дискету, копию системного HDD и отдельные
+каталоги состояния в `build/sdbg-live/`. Общие media и запущенный вручную
+MAME не изменяются. Без `--bridge` проверяется шаг из Lua callback;
+с `--bridge` — отдельный протокол и файловый клиент. `--native-debugger`
+добавляет родное окно к тому же DAP-сценарию. Скрипт, запущенный системным Python <3.12,
+перезапускает себя через local pyenv. Результаты — `result.jsonl`, `mame.log`.
+Остановка процесса в конце bridge-теста относится только к MAME этого теста.
+
+Зафиксировано на SDCC 4.5.0 #15242 и MAME v0.287,
+commit `b0c4527c2edb1ee177fd09b3c412b65b385bf35b`:
+
+| Проверка | Результат |
+|---|---|
+| Обычная debug-линковка двух TU с общим inline | Воспроизводится rc != 0, `Multiple definition of C$...` |
+| Уникализация debug-символов | Успешная линковка; функции обоих экземпляров различаются |
+| Повторные метки sprinter.h:111 | Сохранены начало и эпилог в каждом из трёх TU: 6 адресов |
+| debug/non-debug probe, banked huge и big | Полные EXE идентичны |
+| Одинаковые basename двух utils.c | Две функции и два независимых статика |
+| bank-data в big | Переменная разрешена в банке 1, окне W1 |
+| Ошибка линковки поверх опубликованной сборки | Предыдущие EXE и manifest не изменились |
+| Испорченный артефакт / изменённый source | Ошибка проверки / явный stale; старый текст сохранён |
+| Пер-модульная карта | Только выбранная TU в карте, все компиляционные зависимости учтены |
+| Быстрая правка header / переключение debug | Пересборка; без изменений повторной компиляции нет |
+| Архив с libc/string/strlwr.c | L-записи попадают в общий CDB, F/S из архивного adb не импортируются |
+| Lua step на main | PC=0x8218 сразу после запроса; PC=0x821B на следующем callback |
+| Порядок DSS → arm → launch | VRAM-detector нашёл стабильный prompt в строке 22 на 4,69 с; только затем включена entry-точка, ложных попаданий 0 |
+| Новый мост, родной debugger | Проверены образ, регистры, `total`: 0 → 42, C-line breakpoint; instruction step около 32–124 мс в отдельных прогонах |
+| Банковская точка huge | Условие через W3 page-port; остановка PC=0xC000 разрешена как linker 0x1C000, bank 1 |
+| Session server + DAP | Owner lock удержан; DAP function breakpoint остановил `worker`; frame сохранил bank 1 |
+| Production launcher | DSS prompt → `main` с `false_hits=0`; backend `sdbg` и опциональный `osx` прошли одинаковый DAP-сценарий, штатный terminate без нового crash report |
+| DAP logpoint + breakpoint | В bank 1 напечатано `bank_value=0`; совпавшая function breakpoint сохранила остановку |
+| Авторский `SDBG_LOG`, 2026-09-15 | Fixture `logmacro`: EXE с/без macro побайтово равны, сообщение отсутствует в EXE; активный wrapper и склейка литералов привязаны к linked-якорю, `#if 0` исключён. Живой DAP launch в `sdbg` и `osx`: `total=1` одновременно в MAME debugger console и VS Code Debug Console, `false_hits=0` |
+| Source F11/F10 | `main`: `0x42bb` → `0x42c1`; F10 выполнил банковский `worker` и остановился в caller на `0x42c9` |
+| Source Shift+F11 | Из `worker` bank 1 выполнен выход через trampoline в `main:6`, `0x42c9` |
+| VS Code stdio DAP launch, 2026-09-15 | Local pyenv shim → DAP → изолированный MAME/DSS → `hello` → `main:17`, PC=`0x8224`; `false_hits=0`, штатный disconnect |
+| F10 через `getchar()`, 2026-09-15 | Асинхронный `next` ответил за 21,49 мс; при ручном `x` в окне MAME `hello.c:62` → `:63`, возврат `DE.low=0x78`; обе клавиатуры включены в изолированном cfg |
+| VS Code TaskProvider Build, 2026-09-15 | Одиннадцать Node-проверок: выбор Makefile рядом с пакетом/в `build/`, команда make с Python shim, SDCC matcher, успешный и неуспешный код задачи, pyenv вне workspace; реальный make в `tests/hello` прошёл, VS Code показал Build → MAME/DSS → `main` |
+| Ошибочная debug-сборка, 2026-09-15 | Изолированный `fault.c` вернул код 2 от make, `file:1: error 20` сохранился, Python traceback удалён; MAME не участвует |
+| Владение и generation | Второй FileBridge и чтение со stale generation отклоняются |
+
+Полный host-набор: 29 тестов прошли, один Unix-socket тест пропущен только
+из-за запрета `bind` в sandbox. Тот же socket path проверен живым DAP-запуском.
+
+Это репро доступности механизма, а не полный benchmark или проверка всех
+runtime/mapping/lifecycle. Отдельная публикация debug-библиотек требует
+добавления метаданных извлечённых архивных модулей; одних флагов --debug
+недостаточно. Режим библиотек пока не включён.
+
+## Новое ограничение MAME
+
+`src/osd/modules/debugger/none.cpp::wait_for_debugger()` вызывает `go()`.
+Поэтому `-debugger none` автоматически продолжает CPU при остановке.
+Автономные logpoint actions с ним возможны, ожидание интерактивных команд
+в stopped-состоянии — нет. Поэтому добавлен provider `sdbg`: он возвращается
+в stopped-loop после короткого sleep, а ядро вызывает Lua periodic перед каждой
+итерацией. Во время остановки CPU обычная обработка событий окна не работает:
+ранний `sdbg` только спал, отчего macOS помечала MAME «не отвечает» и окно
+не открывалось через Cmd-Tab/Dock. Provider теперь опрашивает события
+активного OSD примерно 100 раз в секунду (в текущем macOS SDL3 build:
+`input_update(false)` и `process_events()`; в native macOS OSD:
+`MacPollInputs()`). Новый бинарник проходит DAP launch до `main`; пользователь
+подтвердил, что при остановке в `main` окно снова открывается через
+Cmd-Tab/Dock. Регрессионный DAP-проход через `getchar()` с клавишей `x`
+также завершился на следующей строке с кодом `0x78`.
+Воспроизводимый patch и идемпотентный установщик находятся в
+`toolchain/mame-patches/` и `toolchain/apply-mame-sdbg-patch.sh`;
+`make mame-sdbg` собирает и устанавливает бинарник. Provider `osx` остаётся
+доступной launch-опцией и проверен одновременно с DAP. Для непатченного MAME
+можно использовать `auto`: штатные варианты — `osx` на macOS, `windows` в
+native Windows build, `qt` или `imgui` в Linux. `qt` зависит от
+`USE_QTDEBUG=1`, а `imgui` требует графическое окно. Windows-версия самого
+host-моста пока не готова: FileBridge использует `fcntl`, server — Unix socket.
+
+Также startup debugscript с `g` может продолжить первое реальное попадание;
+живой bridge-тест не использует такой скрипт. Повторная загрузка autoboot
+на reset защищена от дублирования callback. Старый mamebridge параллельно
+с sdbgbridge не загружать: общая арбитрирующая сессия ещё не реализована.
+Два одновременно запущенных процесса MAME через MCP bridge не проверялись;
+корректная маршрутизация команд между ними не гарантируется. Это отдельная
+отложенная задача в [TODO.md](TODO.md).
+
+## Размерный регресс и оставшаяся работа
+
+`make size-check` запущен: сообщает рост у 12 программ относительно текущего
+эталона, отсутствующие и новые сборки. В списке роста нет пересобранного
+hello. Дополнительно cat и hello собраны исходной обёрткой из HEAD и новой
+на тех же runtime/библиотеках: EXE попарно идентичны. Эталон не изменялся.
+Этот общий check пока не считается прошедшим; расхождение существующих
+сборок с baseline отделено от побайтовых регрессий новой debug-сборки.
+
+Hard reset из RPC был удалён после воспроизводимого падения MAME 0.287:
+старый Lua periodic callback обращался к `debugger_manager` во время нового
+`running_machine::start()`. Reset notifier теперь только инвалидирует plugin,
+а live-пробник прекращает работу callback до рестарта. До отдельного
+безаварийного репро reset/restart capability не публикуется.
+Crash reports в 19:22/19:23 относились к неподдержанному register symbol в
+условии MAME; публичный протокол теперь принимает только window/page и plugin
+строит проверенное условие через I/O port. После штатных прогонов в 20:43 и
+позже новых `mame.arm-*.ips` не появилось.
+
+Далее по плану: завершить инвалидацию на exit/state load, MCP-адаптер,
+безопасный restart, расширенные выражения
+и упаковку VS Code-расширения. Для IDE ещё нужны Run-команда, выбор профиля
+сборки/данных и расширенная диагностика assembler/linker.
+Базовый attach уже проверяет принадлежность resident/current-bank к build,
+но не умеет читать неотображённую physical RAM. Нет автоматического чтения
+неотображённого bank-data, локальных или backtrace.
+
+Пути исходников в текущем пакете абсолютные. Снимки и уникальные TU уже
+есть, переносимый source mapping — следующая доработка. Пока библиотечные
+описания и отдельные форматы CDB не поддержаны, карта сообщает ограничения.

docs/mame-source-debug.md

@@ -0,0 +1,819 @@
+# Отладка C-приложений Sprinter в MAME и VS Code
+
+Редакция: **2026-09-14**, после технического ревью плана от 2026-09-13.
+Статус: **ЧАСТИЧНАЯ РЕАЛИЗАЦИЯ**. Сборка/оффлайновая карта, транспорт,
+live C-сессия, постоянный server, DAP и VS Code launch MVP реализованы; результаты —
+[mame-source-debug-status.md](mame-source-debug-status.md).
+Полный lifecycle/restart и расширенная отладка ещё не реализованы.
+Основной маршрут включает CLI/MCP и VS Code через DAP;
+GDB — самостоятельное расширение по отдельной потребности.
+
+### Статус платформ
+
+- **macOS** — полный текущий цикл build → DSS → MAME → DAP → VS Code
+  проверен живыми запусками. Доступны backend `sdbg` и совместный режим
+  VS Code + штатное окно debugger через `debugger: "osx"`.
+- **Linux** — архитектура и используемые host-механизмы совместимы; для
+  штатного окна MAME выбирается `qt` либо `imgui`. Полный живой прогон на
+  Linux ещё требуется, поэтому статус остаётся экспериментальным.
+- **Windows** — полный функционал пока **не поддерживается**. Значение
+  `debugger: "windows"` выбирает только штатное окно debugger MAME, но
+  текущие owner lock (`fcntl`), Unix domain socket, shell-команды запуска и
+  тесты рассчитаны на macOS/Linux. Нужны Windows-реализации блокировки и
+  локального RPC, переносимый launcher и отдельные end-to-end тесты. До
+  этого launch/attach из VS Code на native Windows не считаются рабочими.
+
+Прежние фазы 0–5A/5B заменены этапами §10. IDE учитывается в архитектуре
+с самого начала; прежняя «опциональная фаза 4» теперь распределена между
+этапами IDE и расширенной диагностики. Это изменение состава плана,
+а не разрешение выполнять ранее отложенную реализацию.
+
+## 1. Цель и критерий доверия
+
+Целевой цикл: редактирование C → сборка sprinter-cc → упаковка приложения
+и данных → запуск MAME/DSS → остановка на main → отладка из VS Code,
+CLI или MCP.
+
+Планируемые возможности:
+
+- Точки по функции/строке C, условия, счётчики попаданий, логпоинты без
+  пересборки, watchpoint на поддержанные объекты.
+- Текущий исходник, сгенерированный `.asm`, реальные инструкции, регистры.
+- Чтение/изменение глобалов и статиков с учётом типов, банков и окон.
+- Шаг по инструкции и исходнику; затем next/stepOut, проверенные локальные
+  переменные и восстановление стека в поддержанных случаях.
+- Структурированные логи для автотестов/IDE, комментарии в родном
+  дизассемблере; позднее покрытие и профилирование.
+- Общая семантика адресов и одна сессия для всех интерфейсов.
+
+**Критерий доверия:** неизвестная строка, неподтверждённая точка или
+недоступная переменная лучше правдоподобного неверного результата.
+Карта оптимизированного кода не обещает отдельную инструкцию для каждого
+оператора C и наличие всех переменных в любой момент исполнения.
+
+Связанные файлы: [mame-autotest.md](mame-autotest.md),
+[sprinter-cc](../bin/sprinter-cc), [app.mk](../app.mk),
+[mame_interactive.py](../toolchain/mame_interactive.py),
+[bank.s](../runtime/bank.s), [crt0_banked.s](../runtime/crt0_banked.s).
+MAME fork теперь самостоятельный проект: `MAME/plugins/mamebridge/init.lua`,
+`MAME/src/mame_mcp.py`; среда запуска задаётся `MAME_HOME`, а исходники
+fork приложению не нужны. Расширение VS Code находится в отдельном
+`VSCode-Sprinter`; Python DAP backend остаётся в SDK.
+
+## 2. Доказательства и пределы выводов
+
+### 2.1 Результаты первоначальной разведки
+
+Ниже сохранены результаты редакции 2026-09-13. При обновлении плана
+сборочные эксперименты не повторялись. Перед реализацией их требуется
+воспроизвести с сохранением репро, команд и версий.
+
+| Эксперимент | Зафиксированный результат | Предел вывода |
+|---|---|---|
+| `sdcc --debug`, probe | `.exe` идентичен; `_CODE` 3354 → 3354 | Один пример, не гарантия для всех программ |
+| `tests/banked`, huge, 3 TU, 2 банка | `.ihx` идентичен сборке без debug | rc=1 из-за C$; корректность карты не доказана |
+| `.globl _dbg_x` и `_dbg_x:` в inline asm | Ошибка локальных меток `NNNNN$` в проверенных циклах/ветвлениях | Такую форму якоря не используем |
+| `.globl _dbg_x` и `_dbg_x = .` | Релоцируемый символ; в probe байты идентичны, якорь у `ret` | Отдельно проверить влияние inline asm на оптимизацию |
+| `;;SDBG x` | Код идентичен, адреса в `.map` нет | Для адреса нужен листинг/дополнительная привязка |
+| SDCC 4.5.0 z80, `--out-fmt-elf` | Неизвестная опция | Готового ELF/DWARF этого target ожидать нельзя |
+
+SDCC сам использует `sym = .`. Это подтверждает пригодность ассемблерной
+формы, но не доказывает отсутствие влияния пользовательского inline asm
+на оптимизатор C и peephole. Раздельно проверяем идентичность бинарника,
+точность карты и скорость программы под debugger.
+
+Примеры `.cdb` из первоначальной разведки:
+
+```text
+L:C$probe.c$18$3_0$48:8236                  C-строка → адрес линковщика
+L:A$probe$111:8236                         строка .asm → адрес
+L:G$main$0$0:8222                          начало функции
+L:Fprobe$counter$0_0$0:8E40                статик модуля
+L:G$total$0_0$0:8E42                       глобал
+S:G$total$0_0$0({2}SI:S),E,0,0             описание типа
+S:Lprobe.add$s$1_0$44({2}SI:S),R,0,0,[e,d]  описание регистровой локальной
+```
+
+Парсер разбирает семейства `L:`, `S:`, `F:` и диагностирует неизвестные
+записи. Построчная форма не делает семантику типов, scope, инлайнинга
+и границ функций тривиальной. Семантику конечных адресов установить репро,
+внутренние диапазоны нормализовать к `[start, end)`.
+
+### 2.2 Проверено чтением текущих локальных исходников
+
+- MAME поддерживает breakpoint с condition/action, printf/logerror/tracelog,
+  source/debugscript, comadd и debugger без окна (`-debugger none`).
+  `none` автоматически вызывает go() при остановке: он пригоден для
+  автономных logpoint actions, но не для ожидания интерактивных команд.
+  Подтверждено исходниками и живым репро; прототип использует osx debugger.
+- `device_debug::compute_opcode_crc32` в `src/emu/debug/debugcpu.cpp`
+  считает CRC **одной инструкции**. Одинаковый `ret` по одному адресу
+  в двух банках имеет одинаковый ключ комментария. CRC не определяет банк.
+- `execute_trace` в `src/emu/debug/debugcmd.cpp` включает трассировку CPU,
+  а не просто открывает файл для сообщений.
+- Мост содержит `clog` и обслуживает `register_periodic` при stopped.
+  Комментарий у `do_step` прямо указывает: инструкция выполняется после
+  возврата callback, поэтому чтение PC сразу после step даст старый PC.
+- `emu.symbol_table` в `luaengine_debug.cpp` создаёт отдельную таблицу;
+  готового symadd для консоли нет. C-имена разрешаем на своей стороне.
+- В штатных debug views нет окна C-исходника. Для родного UI используем
+  комментарии, для полноценного исходника — IDE.
+- sprinter-cc размещает банки по `(bank << 16) | 0xC000` в huge и
+  `(bank << 16) | 0x4000` в big. Есть `--bank-data`: банки содержат и данные.
+- `_bank_pages[1..N]` заполняется crt0 при загрузке банков, а не до entry.
+  Драйвер экспортирует PG0..PG3 и другие состояния отображения.
+- `bootstrap_r/w` в sprinter.cpp при обычном исполнении перенаправляют
+  логический адрес в `0x10000 | addr`; загрузочный режим отличается.
+  Адрес CPU и адрес пространства MAME нельзя смешивать.
+
+### 2.3 Пакет доказательств этапа 0
+
+Сохранить небольшие исходники-репро, команды, полные диагностики,
+версии SDCC/ассемблера/линкера, commit MAME и патчи, хеши бинарников,
+выбранные фрагменты `.asm/.map/.cdb`, протокол живой проверки MAME.
+Большие артефакты допускается хранить вне Git с командой воспроизведения.
+Ссылки на меняющиеся номера строк MAME заменять именами функций и
+закреплённой ревизией в отчёте эксперимента.
+
+## 3. Реестр решений: что заменено и почему
+
+| ID | Риск / прежнее предложение | Решение и обоснование |
+|---|---|---|
+| R01 | Игнорировать rc=1 при C$, если есть `.ihx` | Устранить конфликт debug-имён; исправность кода не доказывает карту, старый `.ihx` может пережить ошибку |
+| R02 | «Полная карта, ноль влияния» | Раздельные регрессии бинарника, карты и overhead; гарантия ограничена проверенными конфигурациями |
+| R03 | Адрес — одно число, банки только у кода | Типизированные адреса и snapshot отображения, включая bank-data |
+| R04 | Первый адрес строки / следующая строка вместо якоря | Все доказанные позиции, фактическое разрешение и unverified; другой путь исполнения не заменяет удалённую точку |
+| R05 | Арминг по совпадению PC с entry | Проверка образа, готовности runtime/банков и выхода; DSS использует те же адреса |
+| R06 | Цикл step внутри Lua | Асинхронный автомат с лимитами/отменой: шаг исполняется после callback |
+| R07 | Разные ID файлов достаточно для нескольких клиентов | Общая сессия и арбитраж; ID не устраняют гонки run/stop |
+| R08 | Безусловный `g` в логпоинте, clear-all | Реестр владельцев и диспетчер попаданий; логи не отменяют остановку |
+| R09 | `trace` по умолчанию для логов | Отдельный журнал; instruction trace имеет другое назначение и стоимость |
+| R10 | Формат C printf можно передать MAME | Ограниченная грамматика, типы, знак, длина строк и CP866; форматы различаются |
+| R11 | CRC скрывает чужой банк | Сначала резидентные комментарии; затем обновление при remap или расширение ключа |
+| R12 | Каталог сборки достаточен для attach | Manifest, хеши и фиксированный пакет сессии; исключить смешение сборок |
+| R13 | Все DAP-запросы сразу, стек эвристикой | Честные capabilities и один достоверный frame в MVP; сложные функции отдельно |
+| R14 | GDB не имеет логов/банков | Учесть dprintf/overlays; DAP выбран за модель Sprinter и общую сессию |
+| R15 | Сокет автоматически ускорит шаг | Сначала измерить RTT и execution latency; callback сокетом не исправляется |
+| R16 | Ручные правки в игнорируемом mame/ | Версионируемые исходники/патчи и установщик с проверкой расхождений |
+| R17 | Библиотеки/локальные автоматически следуют из CDB | Эксперимент архивной линковки и доказанные location ranges |
+| R18 | Один launch.json завершает интеграцию | Сборка, диагностики, язык, упаковка данных, запуск DSS и повторный F5 |
+| R19 | debugger none держит stopped для IDE | В none wait_for_debugger вызывает go(); использовать родной debugger, для режима без окон реализовать отдельный backend ожидания |
+| R20 | `debugger: "windows"` означает поддержку всей цепочки на Windows | Разделить MAME provider и host-инструменты: Windows provider существует, но Python/DAP launch/attach остаются неподдержанными до замены `fcntl`/Unix sockets, переноса launcher и живых тестов |
+| R21 | Короткий sleep в `sdbg` достаточно для окна MAME | При stopped CPU обычный frame loop не обрабатывает события GUI, и macOS помечает приложение «не отвечает». В `wait_for_debugger` периодически вызывать event pump выбранного OSD (SDL3: `input_update` + `process_events`, native macOS: штатный poll), ограничив частоту; проверить Cmd-Tab/Dock при длительной остановке и сохранение DAP/клавиатурного ввода |
+| R22 | CDB pointee type достаточен для выбора строки или скаляра | SDCC 4.5 кодирует проверенные `char *` и `uint8_t *` одинаково (`DG,SC:U`). В финальном debug-пакете сохранять исходный declared type/typedef chain, сверять его с CDB и размером; при неопределённости явно `unavailable` либо запросить типовую аннотацию. Отдельный fixture должен доказать, что `char *` читается как строка, а `int8_t *`/`uint8_t *` — как один 8-битный объект |
+
+## 4. Архитектура, сборка и пакет
+
+```text
+sprinter-cc → .exe + отладочный пакет + manifest
+                         │
+                 sdbg: карта и типы
+                         │
+CLI ────────┐            │
+MCP ────────┼──→ общая сессия отладки ──→ мост MAME ──→ CPU/debugger
+VS Code/DAP ┘       состояние, точки,
+                    события, загрузка
+```
+
+### 4.1 Ответственность компонентов
+
+- `toolchain/sdbg.py` — публичный CLI; реализацию разделить на модули
+  пакета/парсера, адресов, типов, точек, сессии и транспорта по мере роста.
+- Карта — чистые преобразования артефактов без команд MAME.
+- Общая сессия — процесс для подключения CLI/MCP/DAP, хранит build ID,
+  generation, состояние, владельца управления и реестр точек.
+- Мост — низкоуровневые действия, согласованные снимки, асинхронные
+  операции и события; второго парсера CDB в Lua нет.
+- DAP/MCP — тонкие адаптеры; существующие input/screenshots сохраняются,
+  команды изменения исполнения проходят арбитраж.
+- `.dbgs` — ограниченный автономный экспорт, не второй менеджер сессии.
+  Неподдержанную семантику экспорт отклоняет с объяснением.
+
+### 4.2 Флаги и manifest
+
+`--src-debug` включает debug для всех пользовательских TU;
+повторяемый `--src-debug-file FILE` — для выбранных. Режимы взаимоисключающие,
+неизвестный FILE — ошибка. Необязательный аргумент прежнего флага убран,
+поскольку он неоднозначен рядом с позиционными `.c`.
+`--debug` остаётся DEBUG_RT. В app.mk: `SRC_DEBUG := 1` либо
+`SRC_DEBUG_FILES := a.c b.c`. Обычные сборки прежние; профиль IDE явно
+включает карту, а не меняет defaults всего проекта.
+
+Пакет в `.sprinter-cc-<name>/`: `.cdb/.map/.noi/.ihx/.asm`, нужные листинги,
+manifest и индекс `.sdbg.json`. Конфигурация и содержимое входов входят
+в ключ пересборки: смена debug/fast/safe/memory не оставляет stale artifacts.
+Параллельные сборки одного output сериализуются или используют разные
+каталоги. Пакет публикуется только после успешных проверок, атомарно.
+
+Manifest: schema version, build ID, хеш `.exe` и артефактов, версии
+инструментов, команды/флаги, библиотеки, TU и исходники/заголовки с хешами,
+соответствующие `.asm`, entry, секции, окна, банки и полнота debug-покрытия.
+Адрес `>=0x10000` не объявляется банком без проверки секции.
+Неподдержанное размещение диагностируется, не угадывается по имени режима.
+
+Пути относительно корня сборки, уникальный TU ID, поддержка одинаковых
+basename и source path mapping при переносе проекта. IDE проверяет хеши;
+при расхождении показывает stale source или сохранённый снимок через DAP
+source. Сессия фиксирует пакет: новая сборка не меняет карту старого образа.
+
+### 4.3 Ошибки CDB
+
+Основное решение R01: проверить уникализацию отладочных имён по TU до
+линковки в `.asm` с согласованным преобразованием всех связанных CDB-записей.
+Если формат не позволяет надёжный внешний проход, подготовить патч SDCC.
+Не изменять публичные C/asm-символы и инструкции. Выбор способа — результат
+репро этапа 0, а не утверждение, что простое переименование уже достаточно.
+
+До исправления допустим пер-модульный режим только при успешной линковке;
+manifest перечисляет отсутствующие TU. Неполный выбранный набор отличается
+от повреждённой карты. Повреждённая карта не публикуется.
+Автоматического превращения rc=1 в успех по наличию `.ihx` не будет.
+Неуспешные артефакты можно сохранять для исследования отдельно, но обычный
+attach их не принимает. Полные диагностики сохраняются, включая pipefail.
+
+### 4.4 Библиотеки
+
+Проверить извлечение `S/F/L` и путей из архивов libc/libbgi. После успеха
+добавить явный режим debug-артефактов библиотек с отдельным ключом кэша,
+сохранив fast/safe и «одна функция — один модуль». Проверить DCE, типы,
+строки, отсутствие коллизий и идентичность кода. До этого библиотечный
+код доступен как asm/символы без выдуманных C-строк.
+
+## 5. Адреса, исходники, переменные и выражения
+
+### 5.1 Адресная модель
+
+`CodeLocation/DataLocation`: build ID, секция, адрес линковщика, logical
+CPU address, bank ID приложения при наличии, окно и offset.
+Физическая страница — свойство сессии, не константа пакета.
+`MappingSnapshot`: generation остановки, PC/SP, регистры, PG0..PG3,
+остальные нужные биты отображения, готовность `_bank_pages`.
+
+```text
+line_locations(source_id, line, function_id=None) → список CodeLocation
+resolve_pc(pc, mapping_snapshot) → SourceLocation | Unknown
+asm_at(code_location) → номер/текст asm и происхождение
+function_at(code_location) → функция | Unknown
+resolve_symbol(name, module_id=None) → Symbol | Ambiguous | Unknown
+read_variable(symbol, snapshot) → TypedValue | Unavailable
+```
+
+Backend различает logical CPU memory, пространство MAME и physical RAM.
+Преобразование `0x10000 | addr` инкапсулировано в драйверном backend.
+Bootstrap/configuration имеет отдельную семантику и не допускает обычный
+attach приложения.
+
+Банковая точка проверяет страницу окна против `_bank_pages[N]` после
+подтверждения таблицы и резидентного контекста приложения. huge — W3,
+big — W1. Проверить достаточность PGn с учётом CNF и других битов драйвера;
+простое равенство — базовый случай, не доказанный полный контракт.
+Manual-размещения допускаются по фактической карте и поддержке backend.
+
+### 5.2 Разрешение строк
+
+Хранить все позиции строки и диапазоны инструкции/функции/секции.
+Breakpoint строки по умолчанию покрывает все доказанные позиции исполнения;
+дополнительно можно выбрать функцию/экземпляр. Resolver возвращает реальные
+адреса, фактическую строку и причины неоднозначности/переноса.
+Для пустой или удалённой строки можно предложить ближайшую позицию в том
+же контексте, но не подтверждать её молча как точное совпадение.
+Без допустимого соответствия — unverified с объяснением.
+
+addr2line не распространяет предыдущую метку через конец функции, дыру,
+секцию или банк. Inline-экземпляры и неоднозначности сохраняются, вместо
+выбора первого TU. Привязка точного макроса рассматривается отдельно (§7.2).
+
+### 5.3 Типы, память и watchpoint
+
+MVP: доказанные целочисленные типы, указатели, глобалы/статики. Одинаковые
+имена требуют квалификации модулем. Затем массивы, структуры, битовые поля
+и другие типы с fixtures. Размеры, знак, byte order и ABI задаёт target
+SDCC, не хост. Неподдержанный тип отображается raw bytes с диагностикой.
+
+Регистры/память/mapping читаются в одной остановке, пакетные запросы
+привязаны к generation. После resume старые handles и snapshots недействительны.
+Запись требует stopped, актуальную generation, проверку диапазона/типа
+и известного отображения. Порты показывать по экспортированному состоянию;
+отладочные чтения отключают side effects там, где backend это поддерживает.
+
+Неотображённый банк читается через проверенный доступ к physical RAM без
+переключения страниц приложения; до реализации — Unavailable. Один
+16-битный указатель не содержит достаточного bank ID: его нельзя выдумывать.
+Чтение/запись через границу окна обрабатывается явно.
+
+Для watchpoint экспериментом установить пространство/alias реального пути
+CPU и момент остановки до/после записи. PC-источник, старое и новое значение
+показывать лишь при достоверном получении: текущий PC может отличаться от
+адреса записавшей инструкции. Банковый watchpoint учитывает mapping;
+до доказательства не объявлять его поддержанным.
+
+### 5.4 Выражения
+
+Один парсер для condition/logMessage/evaluate/watches: имена, integer
+literals, `$`-регистры, ограниченные арифметические/битовые/сравнительные
+операции. Документировать грамматику, приоритеты, знаковость и ошибки.
+Поля/индексы/разыменование добавлять по поддержке типов. По умолчанию
+evaluate без присваиваний, вызовов C и других побочных эффектов.
+
+Raw MAME expressions/commands — отдельный явно обозначенный режим;
+это не C. Изменяющие команды также требуют управления и синхронизации.
+Команды генерировать из проверенного AST с экранированием строк/путей,
+не конкатенацией произвольного текста в action.
+
+## 6. Общая сессия и управление исполнением
+
+### 6.1 Жизненный цикл
+
+```text
+disconnected → waiting_load → verifying_image → runtime_initializing
+                                              → stopped ↔ running
+                                              → exited
+reset / state load / потеря связи → invalidated → повторная проверка
+```
+
+Совпадение PC с entry — только кандидат загрузки. Подтверждение сочетает
+build ID выбранного файла, протокол запуска и сравнение неизменяемых
+участков RAM по карте. Хеш `.exe` на хосте сам по себе RAM не проверяет.
+Изменяемые crt0 данные/таблицы исключаются; сигнатуры и точки проверки
+определяются для конкретного runtime.
+
+На entry активируются только доказанные резидентные точки. Банковые —
+после загрузки и проверки `_bank_pages`. На main runtime должен быть готов.
+Отладка crt0 — отдельный режим с asm и постепенным появлением областей.
+Частичная ошибка загрузки не переводит сессию в ready.
+
+Выход через runtime/ESTEX и возврат в DSS деактивируют точки приложения.
+Проверить обычный/аварийный выход и обход штатного exit. Если контекст
+невозможно уверенно распознать — invalidated, а не продолжение со старой картой.
+Reset/state load/restart сбрасывают mapping, temporary points, handles,
+generation. Attach к работающей программе сначала останавливает CPU,
+проверяет образ и runtime; неизвестную сборку не принимает молча.
+
+### 6.2 Управление и реестр точек
+
+Один клиент владеет run/step/write/input; остальные наблюдают согласованные
+данные. Передача управления явная. Потеря клиента снимает lease и отменяет
+его незавершённые операции согласно политике сессии. Screenshots доступны
+наблюдателям; ввод влияет на приложение и арбитрируется. Изменения run/stop
+из родного UI MAME отражаются событиями.
+
+Реестр: logical breakpoint ID, MAME IDs, owner, build ID/generation,
+вид (user/log/temporary/service), адреса/условия. Clear-all ограничен owner.
+Повторная загрузка файла точек заменяет его набор, не дублирует его.
+
+Совпавшие точки обслуживает диспетчер: вычислить условия, записать логи,
+собрать причины остановки, продолжить только если их нет. User breakpoint,
+pause и ошибка шага имеют приоритет над автоматическим `g`.
+Изменения точек в родном UI требуют сверки; если backend не может
+гарантировать совместное управление, сообщить конфликт.
+
+### 6.3 Протокол и транспорт
+
+Protocol version/capabilities, session ID, request ID, generation,
+ответы и упорядоченные события stop/run/output/reset/exit/error.
+Ответ на установку шага значит «принят», не «CPU уже шагнул».
+Нужны timeout/cancel, snapshot/varbatch, EOF/disconnect и защита от повторного
+исполнения: write/continue после timeout не повторяется вслепую.
+
+Сначала измерить файловый IPC: RTT, pause→snapshot, step→stopped,
+periodic при running/stopped. Файловый backend: отдельный каталог сессии,
+один писатель backend, атомарная публикация запросов/ответов, очистка stale
+и журнал событий с курсором. Разделение диапазонов ID независимых MCP
+заменяется одним владельцем backend: оно не решало гонки состояния.
+
+Сокет реализует тот же протокол при подтверждённом выигрыше. MAME имеет
+пример `emu.file` socket в plugins/gdbstub, но неблокирующий ввод/вывод
+при stop проверяется отдельно. Framing, частичные сообщения, лимит очереди,
+reconnect, loopback по умолчанию обязательны. Callback не ждёт клиента
+блокирующим чтением. Сокет не исправляет задержку исполнения инструкции.
+
+### 6.4 Шаги
+
+Сначала надёжный instruction step. Source-step — асинхронный автомат:
+задать действие, вернуть управление MAME, дождаться фактической остановки,
+получить snapshot, решить следующий шаг. Для скорости применить temporary
+breakpoints на доказанных границах либо C++ hook, если Lua periodic
+недостаточен по измерениям.
+
+StepIn идёт к следующей доступной позиции исходника с заходом в вызов.
+Next обходит вызов только при распознанной семантике; stepOut требует
+достоверного контекста возврата. Сравнивать source/TU/function/bank и
+исполняемую позицию, не один номер строки. Повтор строки в цикле не должен
+вечно ждать смены номера.
+
+Составной шаг имеет предел инструкций/wall time, отмену и итоговую причину.
+Код без исходников, HALT, ISR, рекурсия, tail call, bank trampolines,
+BIOS rst 08 и ESTEX rst 10 имеют явную политику. Для неизвестного случая
+допустим отказ или переход к asm с объяснением; stepIn не выдаётся за next.
+Системный код пропускается только при безопасном способе дождаться возврата.
+
+## 7. Логи, макросы и расширенная диагностика
+
+### 7.1 Внешние точки и журнал
+
+Основной путь — версионируемый внешний файл: ID, source/function/location,
+condition, hit condition, сообщение и выражения. Тот же resolver и реестр,
+что у VS Code; пересборка не требуется. Адреса пересчитываются для новой
+сборки из сохранённой исходной привязки. DAP logMessage переводится в эту
+модель, не образует отдельный движок.
+
+Журнал: sequence, build/session ID, host time, доступное emulated time,
+PC, bank/page, location, tag и типизированные значения. JSONL — автотестам,
+текст — CLI, DAP output — IDE, курсор — MCP. Ограничить объём/частоту,
+предусмотреть ротацию или bounded buffer, счётчик потерь, flush на stop/exit.
+clog остаётся для сообщений MAME, но хвост консоли не считается полным
+надёжным журналом приложения.
+
+Форматирование — задача финального этапа §10, а не свойство текущего
+`{name}`. Целевой ограниченный набор включает decimal/hex, ширину,
+символ и строку; MAME `%d/%x/%X/%c/%s/%%` может быть форматом совместимого
+экспорта, но не передаётся напрямую как C-макрос. Принято это разделение,
+потому что formatter обязан проверять тип/знак, размер, pointer против
+массива, границы и кодировку, а CDB не отличает `char *` от `uint8_t *`
+(R22). Для строк нужны bounded read до NUL и проверка CP866→UTF-8;
+raw bytes имеют отдельное представление. Значения собираются до resume.
+Горячие логи могут исполняться в мосте по скомпилированному описанию;
+стоимость измеряется отдельно.
+
+Console/logerror допустимы для совместимого экспорта. Trace/tracelog —
+явный режим instruction tracing, не default для логов. Экспорт `.dbgs`
+указывает ограничения и не ставит безусловный resume в общей сессии.
+
+### 7.2 SDBG_LOG и SDBG_LOGIF
+
+Практический синтаксис, типы, ограничения и примеры описаны в отдельном
+[руководстве по SDBG_LOG](sdbg-log-macros.md). Этот документ — источник
+истины для пользовательского контракта макросов: при изменении грамматики,
+типов, регистров, чтения указателей или вывода в MAME/DAP обновлять его
+вместе с кодом и проверками, затем синхронизировать краткие описания здесь.
+
+Первый поддержанный вариант реализован в `<sdbg.h>`: `SDBG_LOG(tag,
+"total={total}")` и `SDBG_LOGIF(tag, flag, "total={total}")`.
+Обычная сборка получает `((void)0)`; выбранный `--src-debug` TU —
+символ `sym = .` без инструкции. `tag` обязан быть уникальным в TU,
+условие пока только имя поддержанной global/static переменной, а
+`{name}` соответствует ограниченной грамматике DAP logMessage.
+Сборщик извлекает только активные вызовы из отдельного препроцессорного
+metadata-прохода, проверяет единственный asm-якорь и linked address.
+Автоматически установленный logpoint пишет в журнал debugger MAME и DAP
+`output`, затем продолжает CPU; совпавшая обычная точка сохраняет остановку.
+Событийный буфер DAP ограничен 1024 записями и сообщает разрыв курсора с
+числом пропусков; overhead горячих macro-logpoints ещё требуется измерить.
+Десятичный/hex formatter и чтение типизированного значения по указателю
+отложены до финального этапа §10: сначала нужны доказанные тип, контекст
+банка, границы и безопасное чтение памяти, иначе лог может показать неверный
+объект. Текущий `{name}` выводит десятичное число и никогда не разыменовывает
+указатель.
+Если якорь не совпал с началом доказанной инструкции, он помечен unverified
+и не активируется. В проверенном fixture EXE совпал побайтово с обычной
+сборкой; это доказательство конкретного случая, не гарантия для всех
+оптимизаций SDCC и inline asm.
+
+Макросы остаются расширением для авторских устойчивых точек. Без
+anchors — `((void)0)`, с anchors — символ `sym = .` без инструкции.
+Аргументы логирования не исполняются приложением и не имеют C-побочных
+эффектов; это явно документируется, чтобы counter++ не считался кодом C.
+
+Точная точка требует найденного и проверенного якоря. Без него — missing/
+unverified; приблизительная привязка выбирается отдельно с показом
+фактической позиции. Якорь задаёт машинную границу перед инструкцией,
+но не гарантирует материализацию локальной или порядок всех вычислений C.
+
+ID включает TU и tag. Повторные/inline экземпляры имеют отдельные ID либо
+отклоняются до линковки; уникальный tag в тексте программы не предотвращает
+повторное разворачивание inline.
+
+Реализованный препроцессорный проход учитывает активные #if, include,
+wrappers, многострочные вызовы, комментарии и склейку литералов; связывает
+SDBG-описания с единственным реально собранным якорем. Текущая грамматика
+намеренно отклоняет вычисляемый tag/condition, нестроковое сообщение и
+повторные tag; поддержку сложных C-выражений и локальных добавлять только
+после доказанного location range и ограниченного парсера.
+
+Приёмка сравнивает полные бинарники с/без anchors и без макроса на циклах,
+ветках, inline и multi-TU. Если оптимизация меняется, внешние логпоинты
+остаются путём без пересборки, anchors обозначаются инструментированным
+режимом с измеренной дельтой. Без доказательства «ноль влияния» не обещать.
+При добавлении sdbg.h обновить публичный справочник API.
+
+### 7.3 Комментарии, стек, локальные, покрытие
+
+Резидентные comadd ставятся после проверки образа и обновляются при смене
+сборки. Банковые включаются после поддержки remap-обновления с удалением
+старых либо патча ключа `(address, page/context, opcode CRC)`.
+Оффлайновый cmt допустим для проверенного резидентного образа; CRC из ihx
+не решает банковые коллизии. Учитывать владение пользовательскими комментариями.
+
+Backtrace сначала даёт текущий достоверный frame. Затем поддержать
+распознанные прологи/эпилоги, SDCC __sdcccall(1), callee-pops, IX,
+trampolines и ISR. Сканирование стека на похожие адреса — отдельная
+маркированная эвристика, не основание для stepOut/локальных. Возможная
+альтернатива — история call/return, но attach посреди исполнения не знает
+прошлого, а нестандартные переходы требуют инвалидирования истории.
+
+Локальные доступны лишь при доказанном location range (регистр/стек/память).
+Лексический scope не равен live-range. Неизвестные/оптимизированные
+значения — unavailable/optimized out. CFI/location lists из asm — отдельное
+исследование, а не автоматически доступная возможность CDB.
+
+Покрытие различает посещение адреса, число исполнений и время. Trackpc
+сам по себе не даёт времени и требует проверки банковых коллизий.
+Ключ покрытия включает build ID/bank/location, знаменатель — доказанные
+исполняемые позиции. Профиль использует измеренный источник cycles/time
+или sampling с указанной погрешностью и overhead.
+
+## 8. MCP, DAP и полный цикл VS Code
+
+### 8.1 CLI/MCP
+
+Интерфейсы: attach/status/detach, where, disassemble_src, break_at,
+clear_owned_breakpoints, read_var/write_var, watch_var, registers/memory,
+step_instruction/step_in/next/step_out/pause/continue, logs с курсором,
+console_log и загрузка набора точек. Возвращать build ID/generation,
+фактическое разрешение и ограничения там, где они нужны для интерпретации.
+Неподдержанное — явная ошибка. Старые низкоуровневые команды интегрируются
+в арбитраж, а не обходят его.
+
+### 8.2 DAP MVP и развитие
+
+MVP: initialize, attach, configurationDone, disconnect, setBreakpoints,
+setFunctionBreakpoints, threads, stackTrace, scopes, variables,
+ограниченный evaluate, continue/pause, проверенный instruction step,
+disassemble и logMessage/output. Один Z80 — один thread; stackTrace
+сначала содержит один текущий frame. Source-step, если ещё не готов,
+отвечает отказом с объяснением; instruction granularity включается
+только при реализации.
+
+Соблюдать initialize→initialized→configurationDone; stopped содержит
+причину/ID точек, continued сообщает внешний resume, breakpoint — новое
+разрешение. Terminated означает конец сессии; exited выдаётся только при
+установленном завершении приложения и достоверном коде выхода.
+SetBreakpoints заменяет набор данного source, включая очистку пустым
+списком, а не добавляет точки бесконечно.
+
+Capabilities отражают реальную поддержку. Расширения: breakpointLocations,
+instruction/conditional/hit breakpoints, readMemory/writeMemory, setVariable,
+dataBreakpointInfo вместе с setDataBreakpoints, source-step/next/stepOut,
+cancel и сложные типы. Frame/variables references привязаны к остановке,
+memory references различают банк/пространство. Предусмотреть пагинацию.
+Stdout адаптера содержит только DAP, диагностики — stderr/log.
+
+### 8.3 Разработка и запуск из редактора
+
+**Архитектурное решение:** Sprinter-специфичный цикл реализуется собственным
+расширением `VSCode-Sprinter`. Готовые C/C++ или clangd можно
+использовать для подсветки, completion и навигации, а VS Code Tasks и Debug UI
+— как стандартные интерфейсы. Они не знают ABI SDCC/Z80, пакет
+`.sprinter-cc-*`, DSS, банковую адресацию и протокол MAME, поэтому не могут
+заменить project extension и не считаются источником истины для диагностики
+компилятора или отладки.
+
+Мини-расширение уже содержит `contributes.debuggers`, точки для C, схему и
+шаблоны конфигурации. Следующий уровень переносит в него build/run/debug
+оркестрацию: `DebugConfigurationProvider` проверяет конфигурацию и при
+необходимости запускает выбранную build task; команды расширения выбирают
+target/profile/EXTRA_DATA; TaskProvider и problem matcher переводят ошибки
+SDCC/линкера в Problems. Сборку всё равно выполняют `make`/`sprinter-cc`, а
+запуск — общий Python launcher: расширение не дублирует их логику.
+
+Установка через VSIX, разработка через Extension Development Host. Наличие
+VS Code, pyenv Python и необязательного языкового расширения проверяется при
+настройке, а не считается постоянным свойством конкретной машины.
+
+Включить в поставку:
+
+- TaskProvider и/или tasks.json: make/sprinter-cc и problem matcher
+  SDCC/ассемблера/линкера; debug не стартует после неуспешной сборки.
+- Языковые настройки: include/defines/gfx/safe/memory из той же сборочной
+  конфигурации. SDCC-расширения вроде __naked требуют совместимых редакторских
+  определений; generic clang/GCC-анализ не равен полному анализу SDCC.
+- launch.json: приложение/пакет, MAME/ROM/media, EXTRA_DATA, timeout,
+  stopOnEntry/stopOnMain, source mappings; без личных абсолютных путей.
+- Launch: успешная сборка → упаковка → MAME → загрузка DSS → проверка образа
+  → готовность runtime → main. Переиспользовать текущую упаковку/launcher,
+  не дублировать сценарии ввода клавиатуры.
+- Attach к подготовленной сессии без второго MAME; restart с новым build ID
+  и пересчётом точек после новой сборки/загрузки.
+- Disconnect не закрывает чужой MAME; terminate запущенного адаптером
+  процесса имеет явную политику. Выход приложения отличается от выхода
+  MAME. Ошибки сборки/ROM/media показываются в редакторе с причиной.
+
+## 9. Альтернативный маршрут GDB
+
+DAP выбран за прямую модель Sprinter, reuse сессии MCP и отсутствие
+обязательного DWARF-писателя/target GDB. GDB полезен для его скриптов и
+фронтендов; маршрут сохранён как самостоятельное расширение.
+
+Первоначальная разведка: OSD gdbstub знает z84c015, но объявляет mame.z80
+и другой порядок регистров; исследованный GDB ожидает org.gnu.gdb.z80.cpu
+и набор с объединённым IR. Повторить проверку выбранной пары версий.
+Lua gdbstub с i386-картой не является готовым backend Z80. Оценка патча
+«20 строк» заменяется проверкой полного контракта.
+
+1. Собрать/закрепить target GDB; проверить handshake. Патч feature/регистров
+   и IR проходит round-trip всех регистров, включая альтернативные,
+   byte order и семантику R.
+2. Проверить RSP step/continue/interrupt, logical memory read/write,
+   break/watch и отсутствие патчинга инструкций. Разведка сообщала, что
+   Z0/Z2..Z4 используют точки MAME; включить это в регрессию.
+3. sdbg_elf.py на общей карте: ELF32 EM_Z80, секции по реальному размещению,
+   symtab, debug_line, затем CU/subprogram/variable и базовые типы DWARF.
+   Дыры/банки не склеивать в ложный text. Сначала binutils/GDB offline,
+   затем live. ELF с symtab остаётся полезным самостоятельным экспортом.
+4. debug_frame/CFI и locations — только по доказанным данным; строки DWARF
+   сами по себе не исправляют unwinder SDCC.
+5. VS Code cppdbg/target GDB/app.elf — отдельная MI-конфигурация. Банки
+   сначала вручную/ограниченно; затем исследовать overlays и синхронизацию
+   с runtime, а не обещать автоматическую поддержку.
+
+GDB имеет dprintf без пересборки и поддержку overlays. Редакторский
+logMessage зависит от frontend; overlays требуют интеграции Sprinter.
+Поэтому прежние «логпоинтов нет» и «банки невозможны» заменены конкретными
+ограничениями. Области Registers/Ports также возможны поверх GDB,
+но в DAP непосредственно используют нашу target-модель.
+
+RSP и DAP не управляют исполнением независимо одновременно. Режим GDB
+получает отдельного владельца; наблюдающие функции MCP проверяются отдельно.
+Общую карту можно переиспользовать без совместного run/stop.
+
+## 10. Этапы реализации и условия перехода
+
+Календарные оценки прежнего плана считаются оценками демонстрационного
+прототипа: надёжность lifecycle/банков/DAP ими не покрыта. После этапа 0
+оценить каждый этап по репро и измерениям, раздельно прототип, поддержанный
+выпуск и исследовательские функции. Проход этапа определяется приёмкой.
+
+### Этап 0 — проверка предположений
+
+Сохранить §2.3; воспроизвести общий inline в двух вызываемых TU и проверить
+адреса обоих экземпляров/решение R01. Проверить anchors, huge/big/bank-data,
+библиотечную CDB, memory aliases/watchpoint PC, lifecycle crt0, async step,
+задержки моста и CRC банков. Закрепить версии и baseline производительности.
+
+**Выход:** доказанный способ R01 либо явный ограниченный пер-модульный
+режим; таблица проверенных/непроверенных возможностей. Общую карту не
+объявлять готовой при скрытом конфликте.
+
+### Этап 1 — сборка, manifest и карта
+
+Флаги/app.mk, публикация пакета, исправление CDB, типизированные адреса,
+resolver и CLI map/addr2line/line2addr/vars/asm. Debug-библиотеки добавляются
+после успешного эксперимента. Обновить документацию сборки/mame-autotest.
+
+**Выход:** fixtures, одинаковые basename, inline multi-TU, huge/big и
+bank-data разрешаются достоверно; unknown явен. Полный cmp debug/non-debug;
+make size-check без необъяснённой дельты. Baseline не обновляется ради
+скрытия регрессии.
+
+### Этап 2 — сессия и мост
+
+Lifecycle/image verification, snapshot/generation, арбитраж, реестр точек,
+событийный протокол. Сначала файловый backend/измерения, затем socket
+по необходимости. Pause/continue/instruction step и ограниченный async
+stepIn. Версионировать мост/патчи и установщик (§12). Новый самостоятельный плагин
+можно загружать прямо из toolchain/mcp через pluginspath без копирования
+в vendor. Для интерактивного режима без окон требуется решение R19.
+
+**Выход:** нет ложных точек DSS, банки активируются после готовности,
+exit/reset/reload инвалидируют состояние; потеря клиента не блокирует MAME,
+конкурентные операции не читают смешанный snapshot.
+
+### Этап 3 — полезная CLI/MCP-отладка и логи
+
+Внешние точки/условия/логи, диспетчер совпадений, базовые типы, чтение/запись
+резидентных объектов, доказанные watchpoint, where/disassemble_src/clog.
+Интегрировать пакет/журнал в автотестовый launcher; проверить headless debugger.
+
+**Выход:** значения совпадают с эталонными байтами, логи воспроизводимы
+и ограничены, breakpoint не проглатывается логпоинтом, повторная загрузка
+набора не дублирует точки.
+
+### Этап 4 — VS Code MVP
+
+DAP §8.2 и мини-расширение, сначала attach. Source/asm, break/logMessage,
+globals/registers, pause/continue/instruction step. Source-step включить
+после его приёмки, другие запросы не рекламировать заранее.
+
+**Выход:** редакторская точка показывает фактическое разрешение,
+остановка — верные строку/банк/значения; lifecycle DAP, удаление точек,
+disconnect и stale references проверены протокольными тестами.
+
+### Этап 5 — полный цикл разработки и расширенная отладка
+
+Собственное расширение получает команды Build/Run/Debug, TaskProvider,
+problem matcher, выбор target/profile/EXTRA_DATA и проверку инструментов.
+Языковой сервис C/C++ либо clangd остаётся необязательной внешней
+зависимостью с генерируемыми include/defines; его диагностика не подменяет
+SDCC. Добавить launch/restart/stopOnMain и упаковку VSIX. Довести next,
+доступные stepOut, memory/setVariable, data breakpoints, physical bank-data,
+массивы/структуры и резидентные комментарии.
+
+**Выход:** новый рабочий каталог проходит документированную настройку/F5
+на обычной и банковой программе; restart не использует старую карту.
+У каждой расширенной функции свой тест/capability; недоступная функция
+не мешает использовать поддержанные.
+
+### Этап 6 — якоря и исследовательские функции
+
+Первый `SDBG_LOG` и ограниченный `SDBG_LOGIF` уже реализованы; продолжить
+§7.2 проверкой сложных inline/оптимизаций и условных выражений только после
+появления соответствующего evaluator. Независимые подэтапы: банковые комментарии,
+доказанные stack frames/локальные, coverage/profiling. GDB §9 — отдельный
+подэтап по потребности.
+
+Финальные задачи для макросов, **без реализации в текущем этапе**:
+
+- Добавить явные десятичные и hex-форматы для 8/16/32-битных signed/unsigned
+  объектов и адресов, с проверкой типа, знака, ширины и ограниченной общей
+  грамматикой для SDBG_LOG, внешних logpoints и DAP. Проверить значения на
+  реальных SDCC-сборках; не передавать Python format specifier в MAME `printf`.
+- Для указателя выводить его собственное значение (логический/банковый адрес)
+  в decimal/hex и отдельно значение по адресу только если указатель не `NULL`.
+  `char *` трактовать как строку с bounded read до NUL и проверенной кодировкой;
+  `int8_t *`/`uint8_t *` — как один 8-битный signed/unsigned объект (для
+  16/32-битных typed pointers — соответствующий размер). Не выбирать режим
+  по одному CDB: `char *` и `uint8_t *` там неразличимы (R22); сохранить
+  объявленный тип/typedef chain из исходника и сверить с CDB. Чтение только
+  без side effects, после проверки размера, доступного банка, границ и image
+  identity; `NULL`, закрытая страница, отсутствие NUL в лимите и неизвестный
+  pointee дают явный `unavailable`/truncated, а не неверное значение.
+
+**Выход:** доказательства и ограничения каждой функции опубликованы.
+Эвристика не выдаётся за стек, anchors — за гарантированную идентичность,
+посещения адресов — за время CPU.
+
+## 11. Матрица приёмки и регрессий
+
+| Сценарий | Проверяемое свойство | Этап / риски |
+|---|---|---|
+| hello/probe debug и обычный | Полный cmp exe, размеры, карта main | 0–1, R02 |
+| Два TU с общим вызываемым inline | Нет коллизий, адреса/строки обоих экземпляров | 0–1, R01/R04 |
+| Ошибка линковки при старом ihx | Ошибка сохранена, новый пакет не опубликован | 1, R01/R12 |
+| Два utils.c и перенесённый проект | TU identity и source mapping | 1, R12 |
+| Цикл/ветка/удалённая строка/много адресов | Все позиции или unverified, без ложного переноса | 1–4, R04 |
+| Два банка с одинаковыми PC и ret | Верная строка/точка, нет чужого комментария | 0–6, R03/R11 |
+| huge W3, big W1, поддержанные manual | Адреса/guards из фактической карты | 1–5, R03 |
+| bank-data, невключённый банк, граница окна | Physical чтение или Unavailable | 1–5, R03 |
+| Watchpoint через CPU/alias | Адрес, момент и PC-источник корректны | 0–5, R03 |
+| Entry до банков, ошибка loader | Нет ранней активации/ложного ready | 2, R05 |
+| DSS/exit/restart/reset/state load | Нет чужих попаданий и stale handles | 2–5, R05/R12 |
+| Изменённый source или чужой exe | Явное расхождение карты | 1–5, R12 |
+| Log + user + temporary по одному PC | Лог есть, остановка сохранена | 2–4, R08 |
+| Два клиента, ручной resume, reconnect | Арбитраж/события, нет повторных mutations | 2–4, R07/R15 |
+| Одна строка в цикле, HALT/ISR/рекурсия/trampoline | Ограниченный отменяемый шаг | 2–5, R06/R13 |
+| Signed 8/16, pointer/array, CP866, нет NUL | Знак/тип/кодировка, bounded read | 3–5, R10 |
+| Горячий лог, переполнение, выход | Overhead, счётчик потерь, flush | 3, R09 |
+| Debug libc/libbgi fast/safe, DCE | Строки/типы, нет роста кода | 0–1, R17 |
+| Anchors с #if/include/wrappers/inline | Метаданные совпадают, unsupported отклонён | 6, R02/R04 |
+| DAP replace/empty/events/references | Протокол и честные capabilities | 4, R13 |
+| F5 с данными, ошибка ROM/build, restart | Полный цикл и диагностика | 5, R18 |
+| MAME update с ручными изменениями | Установщик не затирает расхождение | 2, R16 |
+
+Тесты карты/протокола — небольшие fixtures без MAME; CPU/банки/lifecycle —
+живые интеграционные сценарии. Golden-карта сверяется независимо с
+листингом, байтами и фактическими остановками, не только выводом парсера.
+Tests/hello и tests/banked — стартовые кандидаты, не вся приёмка.
+
+Замеры: без debugger, debugger без точек, resident/bank breakpoints,
+горячий лог, instruction trace, transport RTT, end-to-end step.
+Записывать хост/версию, emulation speed, объём журнала, latency p50/p95.
+Пороги зафиксировать после baseline этапа 0 до выбора backend;
+«21 МГц терпимо» не критерий приёмки.
+
+## 12. Размещение и воспроизводимость
+
+Исходники моста/MCP — `toolchain/mcp/`, патчи MAME —
+`toolchain/mame-patches/`; патч SDCC при необходимости отдельно с версией.
+`toolchain/install-mame-bridge.sh` проверяет upstream revision/хеши,
+показывает diff при расхождении и не затирает неизвестные ручные изменения.
+Повторная установка идемпотентна; protocol version проверяется handshake.
+
+Самостоятельный sdbgbridge загружается прямо из toolchain/mcp через
+pluginspath: это устраняет необходимость копировать его в vendor и риск
+потери изменений. Установщик остаётся нужен для патчей существующего
+MAME/моста, если они потребуются. Игнорируемое mame/ не источник истины. Документировать сборку/применение
+патчей, проверку установленного бинарника и откат. Не хранить личные пути,
+ROM и большие образы в исходниках расширения.
+
+Defaults вместо прежних открытых вопросов: source debug явный/профиль IDE;
+CDB errors не подавляются; отдельный журнал; общий ограниченный язык;
+DAP — основной IDE-путь; одна сессия владеет backend; socket по измерениям;
+debug-библиотеки после эксперимента. Технически открыты: способ R01,
+наблюдение загрузки/выхода, полная mapping-формула, physical RAM и стоимость
+hooks. У каждого — репро этапа 0 и условие допуска, а не молчаливое
+предположение следующих этапов.
+
+## 13. Внешние спецификации
+
+Локальные версии исходников и репро первичны для конкретной сборки.
+Online-документация задаёт общую семантику; при реализации фиксировать
+использованную версию.
+
+- [DAP specification](https://microsoft.github.io/debug-adapter-protocol/specification): запросы, события, capabilities и references.
+- [DAP specification source](https://github.com/microsoft/debug-adapter-protocol/blob/main/specification.md): полный контракт.
+- [VS Code debugger extension](https://code.visualstudio.com/api/extension-guides/debugger-extension): регистрация/упаковка адаптера.
+- [MAME general commands](https://docs.mamedev.org/debugger/general.html): printf/tracelog/source/trackpc.
+- [MAME execution commands](https://docs.mamedev.org/debugger/execution.html): шаги и трассировка.
+- [MAME Lua debugger classes](https://docs.mamedev.org/luascript/ref-debugger.html): низкоуровневый API.
+- [GDB Dynamic Printf](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Dynamic-Printf.html): логирование без пересборки.
+- [GDB Overlays](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Overlays.html): перекрывающиеся размещения и target-интеграция.

docs/mdview_guide_and_test_patterns.md

@@ -41,7 +41,7 @@
 
 ## Сборка и запуск
 ```bash
-make -C examples/mdview
+make -C ../Examples/mdview
 ```
 
 Запуск на целевой системе:

docs/memory management

@@ -1,67 +0,0 @@
-
-1) если я и DATA и CODE размещаю в одном окне (W1 - #4000 или W2 - #8000, неважно),
-то при вызове set_videomode глобальные переменные (errno, g_text_attr) не меняют 
-своих значений.
-если же DATA и CODE находятся в разных окнах (не важно где DATA - в W1 или W2, главное
-что не в том где CODE) - то при вызове se_videomode значения глобальных переменных меняются
-
-То есть похоже что для DATA не назначается отдельный блок памяти а назначается только для CODE
-Это полностью соответствует документации - если приложение менее 16К (как у нас) то ему выделяется
-только одна страница. И получается что работа со второй страницей идет несанкционированно (ей память 
-не выделена).
-
-Потому предлагается
-1) сейчас размещать ВСЕ в одной странице (и DATA и CODE и стек) - в W2.
-
-2) дальше - добавить в нашу обертку sprinter-cc режимы памяти -
--tiny - все приложение помещается в одну страницу - в W2 (и DATA и CODE и стек)
--small - приложение помещается в две страницы - CODE в W1, DATA и стек - в W2.
-в этом режиме над отдельно выделять и маппить страницу в W2 для DATA и стека
--big - DATA, CODE и стек помещаются в одну страницу W2 как в -tiny, добавляется поддержка banked в W1, 
-страница W3 остается служебной и для работы с граффикой из banked code
--huge - приложение помещается в двух страницах как и -small но так же добавляется поддержка banked но
-уже в страницу W3
-
-Из документации -
-
-            > Теперь адресса #4000..#7FFF,#8000..#BFFF,#C000..#FFFF, когда ДСС
-            передаёт управление эти прогораммам, какие банки там нахадятся по
-            умолчанию?
-
-            В зависимости от адреса загрузки и размера приложения DSS выделяет
-            необходимое число страниц памяти. Так при размере меньше 16К будет
-            выделена
-            одна страница, при размере больше 16К - две, и т.д. В окна с
-            "неиспользуемым" адресном пространством будет подключатся
-            специальная страница #FF.Если приложению требуется памяти больше чем
-            зарезервировано в exe-файле, оно должно выделить себе дополнительный
-            блок памяти самостоятельно.
-
-
-            > В конфигурации спринтер
-            > по #0000..#3FFF, при работе ДСС находится сама ДСС с её Резетами,
-            > чтоб использывать когда сюда подставленна страница пользователся
-            > резеты не доступны!.
-
-            Это так в нижних 16K находится DSS / BIOS в остальных 48К
-            приложение, но с
-            определенными особенностями. Стек не должен быть выше #BFFF при
-            вызове DSS и ниже #8000 при вызове некоторых функций BIOS.
-
-
-Так же посмотри вот сюда - возможно нам придется для режимов -small и -huge делать свой первичным загрузчиком -
-Из документации -
-
-    Выполнение EXE-файла осуществляется по следующим пунктам:
-    1)      Открывает exe-файл на чтение;
-    2)      Считывает в рабочую область префикс exe-файла;
-    3)  Выделяет блок памяти, требуемый для загрузки всего файла или первичного
-    загрузчика, если его размер не равен нулю;
-    4)      Сохраняет стек;
-    5)      Подключает страницы из выделенного блока;
-    6)      Строит префикс запуска программы и устанавливает на него регистр IX;
-    7)  Считывает файл по адресу указанному в смещении 16 (Адрес расположения кода в
-    памяти);
-    8)      Закрывает exe-файл, если это не первичный загрузчик;
-    9)      Устанавливает стек равным значению из смещения 20 (Адрес расположения стека);
-    10)      Передает управление по адресу указанному в смещении 18 (Адрес запуска);

docs/memory-management.md

@@ -0,0 +1,308 @@
+# Управление памятью в sprinter-cc
+
+Документ описывает модель памяти Sprinter (Sp2000), режимы памяти обёртки
+`sprinter-cc` и способы размещения кода/данных: single-page, split, банки
+(трамплины) и резидентный код окна W3 (`--w3`).
+
+Всё в этом документе подтверждено сборкой и прогоном в MAME v3.06 / DSS 1.71.57
+(см. `tests/w3probe`, `tests/banktest`, `tests/banklocl`).
+
+---
+
+## 1. Аппаратная модель памяти
+
+Z80 видит 64 КБ, разбитые на **четыре окна по 16 КБ**. Каждое окно независимо
+маппится на физическую страницу через порт-регистр страницы:
+
+| Окно | Адреса        | Порт страницы | Назначение по умолчанию |
+|------|---------------|---------------|--------------------------|
+| W0   | `0x0000-0x3FFF` | `0x82`      | **DSS / BIOS** (RST-ы, системные вызовы) |
+| W1   | `0x4000-0x7FFF` | `0xA2`      | приложение |
+| W2   | `0x8000-0xBFFF` | `0xC2`      | приложение |
+| W3   | `0xC000-0xFFFF` | `0xE2`      | приложение / графика / банки |
+
+- Запись в порт `0x{8/A/C/E}2` меняет физ-страницу окна; чтение возвращает
+  текущую страницу.
+- **W0 занят DSS/BIOS** — там живут RST-обработчики (`RST #08` BIOS, `RST #10`
+  ESTEX). Пока в W0 стоит системная страница, вызовы доступны; подменять W0
+  нельзя без потери RST-ов.
+- «Неиспользуемое» окно маппится на **специальную страницу `#FF`**: чтение даёт
+  `0xFF`, запись игнорируется. Это ключевая причина «молчаливой» порчи данных —
+  см. §7.
+
+### Порты в C
+
+`<sprinter.h>` даёт SFR-обёртки: `_io_page_w0..w3` (чтение/запись порта),
+`sprinter_page_w0..w3(page)`.
+
+---
+
+## 2. Как DSS загружает EXE
+
+Из документации DSS, последовательность `EXEC`:
+
+1. Открыть exe-файл на чтение.
+2. Считать префикс exe в рабочую область.
+3. **Выделить блок памяти** размером под весь файл (если `loader==0`) или под
+   первичный загрузчик (`loader>0`).
+4. Сохранить стек.
+5. **Подключить страницы** выделенного блока в окна (последовательно от окна
+   адреса загрузки: W1→W2→W3…).
+6. Построить префикс запуска → регистр `IX`.
+7. Считать файл по адресу загрузки (смещение 16 в заголовке).
+8. Закрыть exe, **если это не первичный загрузчик** (`loader==0`).
+9. Установить `SP` = значение из смещения 20 (адрес стека).
+10. Передать управление по адресу из смещения 18 (entry).
+
+**Следствия, на которых стоит вся схема памяти:**
+
+- DSS выделяет **число страниц по размеру образа**: `<16 КБ` → 1 страница,
+  `16..32 КБ` → 2, `32..48 КБ` → 3. Лишние окна = страница `#FF`.
+- Страницы маппятся **подряд** начиная с окна адреса загрузки. Образ, тянущийся
+  `0x4100..0xFFFF` (3 страницы), даёт W1+W2+W3 замапленными автоматически —
+  **это и есть база для резидентного кода W3** (§6, подход A).
+- `loader>0` (multi-bank .exe) → DSS грузит только HOME-часть и **оставляет
+  файл открытым** (handle в `IX-3`), а crt0 дочитывает банки сам (§5).
+
+Упаковкой в этот формат занимается `toolchain/mkexe`.
+
+---
+
+## 3. Правила стека (критично)
+
+- **`SP ≤ 0xBFFF`** при вызовах DSS (ESTEX, `RST #10`).
+- **`SP ≥ 0x8000`** при вызовах некоторых функций BIOS (`RST #08`).
+- Пересечение этих требований → **стек обязан жить в W2** (`0x8000-0xBFFF`).
+  По умолчанию `SP` инициализируется в `0xBFFE`.
+
+Проверено (`tests/w3probe`): во всех режимах на входе `main` `SP ≈ 0xBFFC`, т.е.
+в W2.
+
+**Chicken-and-egg для split-режимов** (small/huge): DSS ставит `SP=0xBFFE` из
+заголовка, но для программ `<16 КБ` окно W2 ещё не выделено (там `#FF`). Пуши
+туда теряются, первый `call` возвращается в мусор. Поэтому `crt0_small`/
+`crt0_banked` сначала работают на **загрузочном стеке в W1** (реальное ОЗУ),
+маппят W2 и только потом переставляют `SP=0xBFFE`. Маппинг W2 делается через
+**ESTEX `$3A SETWIN2`** (не BIOS `$C4`+OUT — тому нужен стек уже в W2).
+
+---
+
+## 4. Режимы памяти
+
+Выбираются флагом `sprinter-cc --memory MODE` (по умолчанию `tiny`). Режим задаёт
+адрес кода, размещение данных, crt0 и наличие банков.
+
+| Режим  | CODE | DATA/BSS | Стек | Банки | crt0 | Первичный загрузчик |
+|--------|------|----------|------|-------|------|----------------------|
+| `tiny`   | W2 `0x8100` | за кодом (W2) | W2 | — | `crt0.s` | нет (1 страница) |
+| `small`  | W1 `0x4100` | за кодом (W1→W2) | W2 | — | `crt0_small.s` | да (сам маппит W2) |
+| `big`    | W2 `0x8100` | за кодом (W2) | W2 | W1 (трамплины) | `crt0_banked.s` (BANK_W1) | да |
+| `huge`   | W1 `0x4100` | за кодом (W1→W2) | W2 | W3 (трамплины) | `crt0_banked.s` | да |
+| `manual` | явно | явно | W2 | — | `crt0.s` | зависит |
+
+Во всех режимах **DATA цепляется линкером сразу за кодом** (`--data-loc 0`), а не
+кладётся по фиксированному адресу. Раньше `huge` использовал фиксированный
+`DATA=0x8000`, что ломалось при коде `>16 КБ` (код перетекал в W2 и накрывал
+DATA); сейчас DATA динамически идёт за концом кода.
+
+### 4.1 `tiny` — всё в одной странице
+
+```
+0x8000..0x80FF  зарезервировано (startup-prefix)
+0x8100          _start / _CODE … _DATA … _BSS … _HEAP
+0xBB00          heap top (по умолчанию)
+0xBFFE          стек ↓
+```
+
+- Один блок 16 КБ, DSS маппит его в W2. W1 и W3 = `#FF`.
+- Ничего выделять/маппить не надо; `crt0.s` предполагает, что W2 уже дан DSS.
+- Практический потолок кода+данных+кучи+стека ≈ 14 КБ.
+- `--code-loc 0x8100 --data-loc 0`; mkexe `-L 0x8100 -E 0x8100 -S 0xBFFE`.
+
+### 4.2 `small` — CODE в W1, данные перетекают в W2
+
+```
+0x4100          _CODE …            (W1)
+  … за кодом →  _DATA _BSS _HEAP   (W1, перетекает в W2)
+0xBB00          heap top
+0xBFFE          стек ↓             (W2)
+```
+
+- Покрывает ~0..30 КБ (код+данные вместе).
+- `crt0_small.s` авто-определяет W2: читает порт `0xC2`. Если `≠0xFF` — DSS уже
+  дал W2 (образ `>16 КБ`), маппить не надо. Если `=0xFF` — сам выделяет страницу
+  (`ESTEX $3D GETMEM`) и маппит (`ESTEX $3A SETWIN2`).
+- `--code-loc 0x4100 --data-loc 0`.
+
+### 4.3 `big` — tiny + банки в W1
+
+- База как `tiny` (CODE+DATA+стек в W2, `0x8100`).
+- **Свапаемые банки в W1** (`0x4000-0x7FFF`, порт `0xA2`), вызываются через
+  трамплины (§5). `crt0_banked.s` собирается с `BANK_W1=1`.
+- mkexe получает `-B 0x4000` (банки живут в W1). Виртуальный адрес банка N =
+  `0x{N}4000`.
+- W3 свободно — доступно под графику или резидентный код (`--w3`).
+
+### 4.4 `huge` — small + банки в W3
+
+- База как `small` (CODE `0x4100`, DATA за кодом, авто-детект W2).
+- **Свапаемые банки в W3** (`0xC000-0xFFFF`, порт `0xE2`), через трамплины.
+  Виртуальный адрес банка N = `0x{N}C000`.
+- `crt0_banked.s` (без `BANK_W1`) грузит банки из .exe после старта.
+
+### 4.5 `manual` — явное размещение
+
+`--memory manual --memory-manual SPEC`, где SPEC = список `KEY=VAL`:
+`CODE=W1|W2`, `DATA=W1|W2|SAME`, `BANKED=W1|W3`. Плюс прямые `--code-loc` /
+`--data-loc` / `-L` / `-E` / `-S` перекрывают дефолты любого режима.
+
+---
+
+## 5. Банки и трамплины (`--bank`)
+
+Для `big`/`huge`. Модуль-банк собирается в отдельную область и линкуется по
+**виртуальному 24-битному адресу** (`bank_id` в старшем байте):
+
+```
+sprinter-cc --memory huge --bank 1=engine.c --bank 2=audio.c -o app.exe main.c
+```
+
+- Банк N компилируется `--codeseg/--constseg/--dataseg BANKN`, линкуется
+  `-Wl-b_BANKN=0x{N}C000` (huge) или `0x{N}4000` (big).
+- `main.c` обязан объявить `const uint8_t n_banks = N;` — `crt0_banked` читает
+  это **до gsinit**, поэтому только `const` (инициализатор ещё не скопирован).
+- Функции банка помечаются `__banked` — SDCC генерирует вызов через трамплин
+  `___sdcc_bcall_ehl` (в `_CODE`/W1, всегда замаплен): он сохраняет текущую
+  страницу окна, маппит нужный банк (`_bank_pages[id]`), `jp` в функцию, по
+  возврату восстанавливает страницу.
+- Загрузка: mkexe пакует `header + HOME + bank1(16К) + bank2(16К)…`,
+  `loader=размер HOME`; `crt0_banked` выделяет страницы (`GETMEM`), маппит и
+  дочитывает каждый банк `ESTEX READ` из открытого файла.
+- Проверка размеров банков — `toolchain/check_banks.py` (часть отчёта
+  раскладки, см. §10).
+
+Writable bank-local данные возможны, но с оговорками — см.
+`memory/bank_local_data_pattern`.
+
+---
+
+## 6. Резидентный код окна W3 (`--w3`)
+
+**Альтернатива банкам без трамплинов.** Модуль размещается резидентно в W3
+(`0xC000`) и вызывается **прямым `call`** — как обычная функция. Работает во
+**всех режимах** (`tiny|small|big|huge`); по умолчанию подразумевает `small`.
+
+```
+sprinter-cc --w3 render.c -o app.exe main.c            # → small
+sprinter-cc --memory huge --w3 render.c --bank 1=lvl.c -o app.exe main.c
+```
+
+**Как работает (подход A):** образ с областью `W3CODE`@`0xC000` тянется до `0xC0xx`
+(≥3 страницы), и DSS сам маппит W3 при загрузке (§2) — **загрузчик в crt0 не
+нужен** (кроме huge). Прямые вызовы резолвятся линкером в реальные `0xC0xx`.
+
+**Механизм сборки:**
+- W3-модуль компилируется `--codeseg W3CODE --constseg W3CODE` — код и rodata в
+  W3. **`--dataseg` НЕ переопределяется**: писучие статики уходят в обычный
+  `_DATA` (W2). Отсюда правило «в W3 только код + rodata».
+- Линк `-Wl-b_W3CODE=0xC000`.
+
+**Раскладка страниц по режимам (проверено MAME):**
+
+| Режим | W1 | W2 | W3 |
+|-------|----|----|----|
+| tiny  | `#FF` (не исп.) | код+данные | **резидент** |
+| small | код | данные | **резидент** |
+| big   | банк (трамплин) | код+данные | **резидент** |
+| huge  | код | данные | **резидент делит окно с трамплин-банками** |
+
+**huge — особый случай (резидент + банки в одном окне W3):**
+- `crt0_banked` под `.ifdef W3_RESIDENT` захватывает физ-страницу резидента
+  (`in a,(0xE2)`) сразу после загрузки DSS и **возвращает её дефолтом** после
+  цикла загрузки банков (иначе в W3 остался бы последний банк).
+- Трамплин на каждый `__banked`-вызов сам сохраняет/восстанавливает страницу
+  W3 — поэтому дефолтная страница обязана быть резидентной.
+- mkexe получает флаг `-W` (разрешить HOME тянуться в W3 при наличии W3-банков —
+  намеренное совмещение).
+
+**Правила разработчика:**
+- Код в W3 **не переключает** страницу W3.
+- Код в W1/W2, свапающий W3 на другую страницу (скретч, графика), обязан
+  **вернуть исходную** (`in a,(0xE2)` → работа → `out (0xE2),a`); оборачивать в
+  `DI/EI`, если есть ISR, дёргающий W3.
+- В W3 — **только код + rodata**, писучих переменных там быть не должно.
+- Из `__banked`-контекста (пока в W3 замаплен банк) резидентный W3-код
+  **недостижим** транзитивно. Обратное — резидент → `__banked` через трамплин
+  W1 — **работает** (трамплин вернёт резидентную страницу перед `ret`).
+
+Подробности и артефакты — `memory/w3_resident_code`, тест `tests/w3probe`.
+
+---
+
+## 7. Куча и стек
+
+- **Стек**: init `SP=0xBFFE`, растёт вниз. Меняется через `-S 0xADDR`.
+- **Куча**: от конца `_BSS` вверх до `___sdcc_heap_end` (по умолчанию `0xBB00` →
+  ~1278 байт под стек). `malloc` берёт `&___sdcc_heap_end` как потолок.
+- `runtime/heap.s` — динамическая куча (авто-размер = зазор BSS…heap_top), НЕ
+  фиксированный `.ds`.
+- `--stack-size N` регенерирует `heap_top` как `HEAP_TOP = 0xBFFF - N`, зажимая
+  рост кучи ради стека.
+
+---
+
+## 8. Семейство crt0
+
+Выбирается режимом; `--crt0=TYPE` перекрывает.
+
+| crt0 | Файл | Для чего |
+|------|------|----------|
+| `default` | `runtime/crt0.s` | tiny/manual; парсит argv, argv[0] через APPINFO |
+| `minimal` | `runtime/crt0_minimal.s` | tiny без argv (меньше размер) |
+| `small`   | `runtime/crt0_small.s` | small; авто-детект/выделение W2 |
+| `banked`  | `runtime/crt0_banked.s` | big/huge; авто-детект W2 + загрузка банков |
+
+`crt0`/`bank.s` собираются **пер-сборка** внутри `sprinter-cc` (с префиксами
+`BANK_W1` / `W3_RESIDENT` / `DEBUG_RT`), а не бандлятся в библиотеку.
+
+---
+
+## 9. Типовые грабли
+
+- **`static`-переменные читаются как `0xFF` / не меняются** — DATA попала в
+  невыделенное окно (`#FF`). Причина: код и данные в разных окнах при образе
+  `<16 КБ`, где DSS дал только одну страницу. Лечится правильным режимом
+  (`small`/`huge`) или единым окном (`tiny`). См.
+  `memory/sprinter_memory_modes`.
+- **Крэш после первого `call` в split-режиме** — стек ещё в невыделенном W2.
+  Решает загрузочный стек в W1 (уже в crt0).
+- **Банк «прыгает в мусор»** — таблица `_bank_pages[]` в `_DATA` занулилась
+  gsinit’ом; она обязана жить в `_CODE`. Уже исправлено в `bank.s`.
+- **`--w3`: резидент недоступен из банка** — ожидаемо (см. §6); держи вход в
+  резидент только из W1/W2 или из самого W3-кода.
+
+---
+
+## 10. Отчёт по раскладке памяти (после линковки)
+
+`sprinter-cc` печатает отчёт `toolchain/check_banks.py` для **любой** модели
+памяти (по `.map`).  Показывает, где легли код/данные и **сколько свободно**
+в каждом окне и банке:
+
+```
+memory: huge — CODE в W1 (0x4100), DATA→W2, банки в W3
+  _CODE         @ 0x4100  size   3767  (W1)  → 0x4FB7
+  данные        @ 0x4FB7  size    336  (W1)  → 0x5107   [_DATA/_BSS/_INITIALIZED/…]
+  статика до 0x5107  —  куча 0x5107..0xBB00 (27129 Б), стек 0xBB00..0xBFFE (1279 Б)
+  _W3CODE       @ 0xC000  size    249  (резидент W3)  → 0xC0F9, 16135 Б свободно до 0x10000  OK
+  _BANK1        @ 0x0001C000  size    219 / 16384 ( 1.3%)  → 16165 Б свободно  OK
+```
+
+- `_CODE` / `данные` — окно (W1/W2), размер, конец; строка `статика … куча …
+  стек …` = свободное место в W1/W2 (под кучу malloc до `___sdcc_heap_end` и
+  под стек).
+- `_W3CODE` — только при `--w3`: остаток окна W3.
+- `_BANKn` — только при `--bank`: занятость/остаток каждого 16 КБ-банка.
+- Ненулевой выход (проглатывается `|| true`), если банк > 16 КБ или статика
+  заехала за `heap_top`/`0xC000`.
+```

docs/new/01-architecture.md

@@ -0,0 +1,272 @@
+# 1. Архитектура компьютера Sprinter Sp2000
+
+## 1.1 Общие сведения
+
+ZX Sprinter — универсальный компьютер на базе 8-битного процессора Z80. Основой является перепрограммируемая логическая матрица (ППЛМ/CPLD/FPGA), что обеспечивает гибкую изменяемую архитектуру — конфигурация схемы может меняться непосредственно во время работы.
+
+Материнская плата — Sp2000 (разработана в конце 2000 г.).
+
+| Параметр | Значение |
+|---|---|
+| Процессор | Z84C15 (Z80-совместимый, внутренние PIO/SIO/CTC) |
+| Тактовая частота | 21 МГц (turbo) / 3.5 МГц (slow) |
+| ОЗУ (main) | 4 МБ (72-pin SIMM) |
+| Быстрое ОЗУ (КЭШ-ОЗУ) | 64 КБ (SRAM, без wait states) |
+| ПЗУ | 256 КБ (8 страниц по 32 КБ) |
+| Видео-ОЗУ | 256 КБ |
+| Контроллер дисков | КР1818ВГ93 (аналог WD1793) |
+| Поддержка НЖМД | IDE/AT |
+| Контроллер клавиатуры | AT-совместимая (101 key), PS/2 |
+| Контроллер мыши | Serial MS-Mouse (RS-232 через Z84C15 SIO) |
+| Слоты расширения | 2 × ISA-8 |
+| Звук | AY-3-8910 (в ППЛМ), 16-бит ЦАП TDA1543 (COVOX + AY) |
+| COVOX-Blaster (CBL) | 16-bit с буферным ОЗУ 256 байт, 15/22 кГц |
+| CMOS-часы | Dallas DS12887A (опционально, эмулируется при отсутствии) |
+| Видеовыход | Аналоговый CGA-монитор, RGB, TV (SCART) |
+
+
+## 1.2 Системная архитектура
+
+Упрощённая структура:
+
+```
+                  ┌─────────────┐
+  ┌──────────┐    │   ISA-8     │
+  │ Принтер  │    │  слот 1..2  │
+  │ Мышь     │    └──────┬──────┘
+  │ Джойстик │           │
+  └─────┬────┘     ┌─────┴──────┐
+        │          │  Буферы и  │
+  ┌─────┴──────┐   │ дешифраторы│
+  │  Z84C15    │   └──────┬─────┘
+  │ (CPU +     │◄─────────┤
+  │  PIO/SIO/  ├──────────┤
+  │  CTC)      ├──────────┤
+  └─────┬──────┘          │
+        │            ┌────┴──────────┐
+  ┌─────┴──────┐     │  EP1K30QC208  │
+  │ ROM 256K   │◄───►│   (CPLD/FPGA) │◄───► VRAM 256K
+  │ Cache 64K  │     │               │◄───► Main RAM
+  └────────────┘     │               │
+                     │  AY-3-8910    │
+                     │  COVOX/CBL    │
+                     │  Accel.       │
+                     └──────┬────────┘
+                        ┌───┴───┐
+                        │TDA1543│
+                        │ ЦАП   │
+                        └───────┘
+```
+
+Периферия (FDD, HDD, Kempston, клавиатура AT) подключается через ППЛМ. Вспомогательная ППЛМ (EPM7064 на Sp2000) обеспечивает синхронизацию и начальный запуск. Дешифрация адресов портов выполняется через ППЛМ, что позволяет перепрограммировать адреса портов.
+
+## 1.3 ППЛМ и загрузка конфигураций
+
+### Механизм конфигурирования
+
+При включении или RESET информация в ППЛМ стирается. ППЛМ переходит в режим ожидания загрузки блока данных конфигурации. Процессор отключён от периферии, в его адресное пространство включено ПЗУ и возможно КЭШ-ОЗУ. Любая запись процессора в адресное пространство в этот момент записывает данные в ППЛМ.
+
+Программа загрузчика в ПЗУ:
+1. Проверяет флаг в КЭШ-ОЗУ по смещению `#80` (последняя страница КЭШа)
+2. Если флаг (строка `ACEX_30K_LOADING`) установлен → загружает конфигурацию из КЭШ-ОЗУ (смещение `#100`)
+3. Если флаг сброшен → загружает конфигурацию из ПЗУ
+
+### Смена конфигурации программно
+
+1. Загрузить файл прошивки в последнюю страницу КЭШ-ОЗУ (смещение `#100`)
+2. Записать флаг `ACEX_30K_LOADING` по смещению `#80`
+3. Выполнить программный сброс записью в страницу RESET_PAGE (`#A0`),
+4. После сброса загрузчик находит флаг, загружает прошивку в ППЛМ и стирает флаг
+
+При аппаратном RESET флаг отсутствует — загружается начальная конфигурация из ПЗУ.
+
+### Ограничения
+
+- Внутренний формат данных ППЛМ — закрытая информация Altera
+- Программа разводки схем — MAX+Plus II — не работает на ZX-Spectrum/Sprinter (требуется PC)
+
+
+
+## 1.4 Конфигурации ППЛМ
+
+### Sprinter-1
+Максимально совместима с ZX-Spectrum. Включает:
+- Режимы Spectrum-128/Scorpion-256/Pentagon-512
+- Расширенная память до 4 МБ
+- Расширенный экран: Spectrum, Text-80×32, Graf-320×256×256
+- Контроллер дисковода (ВГ93), контроллер IDE
+- AT-клавиатура, подключённая как ZX-Keyboard (через порт `#FE`)
+- COVOX 8-bit
+- AY-3-8910 (доступен)
+
+### Sprinter-2
+Требования к совместимости жёстче. Добавляет:
+- Акселератор операций с ОЗУ (fill, copy, AND, OR, XOR)
+- AT-клавиатура через внутренний последовательный порт Z84C15 (сканкоды, не ZX-матрица)
+
+### ZX-Spectrum+AY
+Максимальное приближение к ZX-Spectrum-128/256. AY-3-8910 (3-я версия, в ППЛМ): 3 голоса, шум, амплитуда, огибающая (обнаружена ошибка в формирователе огибающей [IvanMak.txt:224–229]).
+
+### Game-1
+На базе Sprinter-2. Акселератор без логических функций. COVOX-Blaster (15 кГц).
+
+### DooM
+Развитие Game-1. Акселератор с аппаратным растяжением/сжатием вертикальных и горизонтальных линий.
+
+### Video
+Похожа на Game-1, добавлена возможность передачи данных с HDD прямо в видео-память. Режим `GR-256-4×4` — 160×128 с аппаратным удвоением пикселя.
+
+### Плата Sp2000
+Конфигурации Sprinter-1, Sprinter-2 и ZX+AY объединены в одну прошивку. Переключение — через системный порт. Game-1, DooM, Video также планируется свести в одну.
+
+## 1.5 Система памяти (обзор)
+
+Адресное пространство Z80 (64 КБ) разделено на 4 окна по 16 КБ:
+
+| Окно | Адреса | Название | Назначение (по умолчанию) |
+|---|---|---|---|
+| W0 | `#0000..#3FFF` | PAGE0 | ПЗУ (системное) |
+| W1 | `#4000..#7FFF` | PAGE1 | ОЗУ, страница 5 |
+| W2 | `#8000..#BFFF` | PAGE2 | ОЗУ, страница 2 |
+| W3 | `#C000..#FFFF` | PAGE3 | ОЗУ, любая страница (0..N) |
+
+Основная память — 4..64 МБ — делится на блоки по 16 КБ. Управление через порты страниц (`#82`, `#A2`, `#C2`, `#E2` для окон 0..3). ПЗУ: `#E0..#EF`. КЭШ-ОЗУ: `#F0..#FF`.
+
+Детально — `04-memory.md`.
+
+## 1.6 Видеосистема (обзор)
+
+Основа — ППЛМ + 256 КБ видео-ОЗУ. Два режима адресации VRAM:
+- **Спектрумовский** — экран 32 блока по 8 КБ, адрес через RGADR
+- **Графический** — 256 строк × 1024 байта, линейная адресация; страницы `#50..#5F`
+
+Режимы вывода (задаются для каждого квадратика 8×8):
+- ZX-40 — текстовый 40×32 (Spectrum-совместимый)
+- ZX-80 — текстовый 80×32, до 36 знакогенераторов
+- GR-256-8 — графический 320×256×256 цветов
+- GR-16-16 — графический 640×256×16 цветов
+
+Палитра: 8 палитр по 256 цветов из 16 млн. Цвет: 3 байта RGB (BGR) на цвет.
+
+четыре из этих восьми палитр используются для графических режимов и оставшиеся четыре для текстовой палитры — 4 текстовые палитры (paper, ink, flash-paper, flash-ink) по адресам `#03F0..#03FE`.
+
+Детально — `05-graphics.md`.
+
+## 1.7 Акселератор (обзор)
+
+Акселератор — быстрое внутреннее ОЗУ в ППЛМ. Присутствует в Sprinter-2 и выше. Управляется через NOP-команды процессора (`LD D,D`, `LD L,L`, `LD C,C` и др.), которые ППЛМ распознаёт как инструкции акселератора.
+
+Операции: fill, copy, AND, OR, XOR.
+
+**время копирования полного экрана.** - «~1.2 инта» (~24 мс при 50 Гц)
+
+**формула скорости.**
+«Время работы акселератора = число пересылаемых байт / 7000000 (секунд)»
+
+**акселератор и прерывания.** требуется DI/EI (акселератор сильно меняет систему команд).
+
+Детально — `06-accel.md`.
+
+## 1.8 Быстрое ОЗУ (КЭШ-ОЗУ)
+
+64 КБ SRAM с доступом без wait states на частоте 21 МГц. Физические страницы `#F0..#FF`, реально 4 страницы по 16 КБ.
+
+Подключается через порт `#FB` (стандартный Pentagon-овский), чтение `IN A,(#FB)` — включает, `IN A,(#7B)` — выключает.
+
+Ограничения:
+- Несовместимо с акселератором
+- Не сохраняется между процессами
+- Конфликт с COVOX по порту `#FB`
+- На Sp2000 используется для загрузки прошивок ППЛМ и как временное хранилище
+
+Детально — `04-memory.md`.
+
+## 1.9 ISA-слоты
+
+Два 8-битных ISA-слота.
+
+Возможны два способа доступа к ISA — вероятно, разные конфигурации ППЛМ:
+
+- Через страницы памяти `#D0..#DF` [IvanMak.txt:855–858]: «Бит 1 номера означает выбор доступа к порту или памяти ISA, а бит 2 определяет к какому из двух слотов осуществляется доступ.»
+- Через управляющие порты [Parinov.txt:798–857]: (1) запись `#10` в порт `1FFDh`, (2) запись управляющего байта в порт `0E2h` (бит D2=слот, D1=порт/память), (3) использование порта `9FBDh` для старших адресов.
+
+## 1.10 Звук (обзор)
+
+COVOX: ЦАП TDA1543 — 16-битный стерео, COVOX — 8-битный, реально используется 10 бит для одновременного вывода COVOX и AY.
+
+**порт CBL.**
+«Порт управления: 004Eh (16-bit port!!!, писать только через OUT (C),reg)» — 16-бит, требуется `OUT (C),A`.
+
+Компоненты звукового тракта:
+- **16-битный ЦАП TDA1543** (реально 10 бит) — подключён к ППЛМ
+- **AY-3-8910** — эмуляция в ППЛМ (3-я версия: 3 голоса + шум + огибающая)
+- **COVOX 8-bit** — порты `#FB` / `#4F`, через TDA1543
+- **Бипер** — бит 3 порта `#FE`
+- **COVOX-Blaster (CBL)** — COVOX с буферным ОЗУ 256 байт, 15/22 кГц. Управление порт `#4E`
+
+Детально — `08-io.md`.
+
+## 1.11 Клавиатура (обзор)
+
+В Sprinter-1 — ZX-клавиатурная матрица через порт `#FE`. В Sprinter-2 и выше — AT-клавиатура через внутренний SIO Z84C15 (порты `#18`/`#19`). Сканкоды напрямую, FIFO на 3 байта.
+
+Детально — `08-io.md`.
+
+## 1.12 Мышь
+
+Microsoft Mouse (2 кнопки) через последовательный порт Z84C15. Порт команд: `#1B`, порт данных: `#1A`.
+
+Детально — `08-io.md`.
+
+## 1.13 Дисковая подсистема
+
+- **FDD**: КР1818ВГ93 (WD1793). Порт `#1F` перенаправляется на `#0F` в ПЗУ. Поддержка 720 КБ / 1.44 МБ.
+- **HDD**: IDE/AT. Порты `#XX50..#XX55`, регистры `#20..#29`.
+- **CMOS Dallas DS12887A**: порты `#FFBD` (read), `#BFBD` (write), `#DFBD` (address).
+
+Детально — `08-io.md`.
+
+## 1.14 Система прерываний (обзор)
+
+Поддерживаются IM1 и IM2. Генерация INT — через бит 0 порта `#FE`. CTC Z84C15 — таймер, SIO — клавиатура. ISA-слоты — IRQ через PIO порт B (`#1F`).
+
+Детально — `07-irq.md`.
+
+## 1.15 Сброс и старт машины
+
+Программный сброс (без перезагрузки ППЛМ) [IvanMak.txt:1385–1394]:
+```
+DI
+LD A, 16
+LD BC, 1FFDh
+OUT (C), A
+LD A, 0A0h
+OUT (PAGE3), A  ; PAGE3 = #E2
+LD (0C000h), A  ; в этот момент происходит RESET
+DI
+HALT
+```
+
+Сброс с перезагрузкой ППЛМ — через функции BIOS (`02-bios.md`). Аппаратный RESET — начальная конфигурация из ПЗУ.
+
+## 1.16 Плата Sp2000 — особенности
+
+- Конфигурации объединены в две прошивки ППЛМ (Sprinter-1+Sprinter-2+ZX+AY — одна; Game-1+DooM+Video — другая)
+- AY-сопроцессор доступен и в Sprinter-1, и в Sprinter-2
+- ОЗУ: 72-pin SIMM, от 4 до 64 МБ
+- Внутренние порты Z84C15: `#10..#1F`, `#EE`, `#EF`, `#F0`, `#F1`, `#F4` — их адреса вне ППЛМ
+- Обнаружена ошибка в формирователе огибающей AY (3-я версия)
+
+## 1.17 Кросс-ссылки
+
+- BIOS: `02-bios.md`
+- DSS/ESTEX: `03-dss.md`
+- Память, режимы, банки: `04-memory.md`
+- Видео, палитра: `05-graphics.md`
+- Акселератор: `06-accel.md`
+- Прерывания: `07-irq.md`
+- Диски, джойстик, принтер, ISA: `08-io.md`
+- Клавиатура, мышь: `09-input.md`
+- Звук: `10-sound.md`
+- Карта портов: `11-ports.md`
+- Баги: `12-bugs.md`

docs/new/04-memory.md

@@ -0,0 +1,387 @@
+# 4. Управление памятью Sprinter Sp2000
+
+## 4.1 Аппаратная модель памяти
+
+Z80 видит 64 КБ, разбитые на **четыре окна (window) по 16 КБ**. Каждое окно независимо маппится на физическую страницу (page) ОЗУ или ПЗУ через порт-регистр страницы:
+
+| Окно | Адреса | Порт страницы | Назначение |
+|------|--------|---------------|------------|
+| W0 | `#0000..#3FFF` | `#82` (PAGE0, ROM.SLOT0) | RST-обработчики, BIOS/DSS ядро |
+| W1 | `#4000..#7FFF` | `#A2` (SLOT1, PAGE1) | Приложение |
+| W2 | `#8000..#BFFF` | `#C2` (SLOT2, PAGE2) | **Стек — обязательно здесь** |
+| W3 | `#C000..#FFFF` | `#E2` (SLOT3, PAGE3) | Разделяемые страницы DSS, графика, резидентный код |
+
+- Запись в порт `#82`/`#A2`/`#C2`/`#E2` меняет физическую страницу окна; чтение возвращает текущую.
+- Для совместимости со старыми моделями (ZX-Spectrum 128, Scorpion, Pentagon) работают также порты `#7FFD`, `#1FFD`, `#DFFD`, `#EFF7`:
+
+| Порт | Описание |
+|------|----------|
+| `#7FFD` | Биты 0-2: страница W3; бит 3: выбор ПЗУ (0=DOS, 1=Basic/48) |
+| `#1FFD` | Биты 0-2: страница W0; бит 3: дополнительная память; бит 4: турбо |
+| `#DFFD` | Страница W1 (Pentagon, когда бит 5 порта `#7FFD`=0) |
+| `#EFF7` | Страница W2 (Pentagon) |
+
+> **Страница `#FF`:** если окно не выделено программе (образ меньше 16/32 КБ), DSS маппит его на специальную страницу `#FF`. Чтение даёт `#FF`, запись игнорируется. Это ключевая причина «молчаливой» порчи данных — см. §4.9.
+
+> **Физические страницы:** порты `#82`/`#A2`/`#C2`/`#E2` адресуют физические 16-КБ страницы в адресном пространстве Sprinter. Диапазон страниц зависит от установленной памяти (обычно 0..127 для 2 МБ, 0..255 для 4 МБ). Старшие страницы заняты видео-ОЗУ и ПЗУ.
+
+---
+
+## 4.2 Окно W0 (#0000..#3FFF) — системное
+
+W0 — критическое окно: в нём живут обработчики `RST 08h` (BIOS), `RST 10h` (DSS/ESTEX) и `RST 18h` (BIOS-EXP). Пока в W0 стоит системная страница, вызовы доступны.
+
+**ROM/RAM switching:**
+
+| Действие | Код |
+|----------|-----|
+| Включить ПЗУ в W0 | `OUT (#7C),A` (SYS_PORT.ROM) |
+| Выключить ПЗУ, вернуть ОЗУ | `OUT (#3C),A` (SYS_PORT.RAM) |
+
+При включённом ПЗУ в W0 отображается системная страница BIOS. Для вызова RST-функций W0 должен быть в ПЗУ — BIOS сам переключает его при входе через `RST 08h`.
+
+**Требования к прерываниям:**
+
+Sprinter работает в режиме **IM1** — вектор прерывания фиксирован на `#0038` (всегда в ПЗУ/ОЗУ W0). Обработчик EXP.asm по адресу `#0038`:
+
+1. Переключает W3 на SYS_PAGE.
+2. Проверяет флаг `INT_ID` = `#AA`.
+3. Если есть пользовательский обработчик — вызывает его (адрес из SYS_PAGE).
+4. Восстанавливает W3, `EI`, `RETI`.
+
+Регистр `I` инициализирован в `#3F` (наследие ZX-Spectrum), но при IM1 не используется для диспетчеризации. Если программа переключается в **IM2** — `I` и расположение таблицы векторов определяются программой произвольно, стандартного расположения нет.
+
+**DSS и W0:** при вызове `RST 10h` DSS переключает W0 на свою рабочую страницу (COREPAGE = 4), выполняет функцию и восстанавливает W0. Если в W0 до вызова была ОЗУ, DSS восстановит её; если ПЗУ — вернёт ПЗУ.
+
+**Практические рекомендации:**
+- Для вызова системных функций держите W0 в ПЗУ (или не заботьтесь — RST 08h и RST 10h его переключат сами).
+- При IM1 (режим по умолчанию) прерывание идёт на `#0038` — это ПЗУ, переключение W0 не требуется.
+- При IM2 программа сама управляет таблицей векторов — не забывайте про `DI`/`EI` при переключении W0.
+
+**Размещение своей RAM-страницы в W0:**
+
+Если программе нужно дополнительное окно (например, для атласов спрайтов или кода,
+не требующего системных вызовов), можно временно маппить свою страницу в W0. Для
+безопасной работы страница должна содержать корректную таблицу RST-векторов в
+первые `#40` байт:
+
+| Адрес | Инструкция | Назначение |
+|-------|-----------|------------|
+| `#0000` | `JP boot` или `RST 00h` (обычно не используется) | |
+| `#0008` | `JP rst08_stub` | RST 08h — BIOS |
+| `#0010` | `JP rst10_stub` | RST 10h — ESTEX/DSS |
+| `#0018` | `JP rst18_stub` | RST 18h — BIOS-EXP |
+| `#0020..#0030` | `JP _w0_unused_stub` | RST 20h-30h — не используются |
+| `#0038` | `JP isr_stub` | IM1 (RST 38h) |
+| `#0066` | `RETN` или `JP nmi_stub` | NMI |
+
+Каждый стаб (в этой же странице, выше `#40`) выполняет одну задачу: сохранить
+текущий номер страницы W0, переключить W0 обратно на ПЗУ (`OUT (#7C),A` —
+SYS_PORT.ROM), выполнить настоящий системный вызов, после чего восстановить
+страницу программы и вернуться к исходному caller'у. Типовой паттерн для ESTEX
+(`RST 10h`):
+
+```asm
+rst10_stub:
+    IN    A, (#82)        ; сохранить свою страницу W0
+    PUSH  AF
+    OUT   (#7C), A        ; включить ПЗУ в W0 (SYS_PORT.ROM)
+    ; теперь в W0 — системная страница, RST 10h будет обработан корректно
+    RST   #10             ; вызвать настоящий ESTEX (DSS сам переключит W0
+                          ; на COREPAGE и восстановит ПЗУ на выходе)
+    POP   BC
+    LD    A, B
+    OUT   (#82), A        ; вернуть свою страницу в W0
+    RET                   ; возврат к исходному caller'у
+```
+
+Такой же паттерн для RST 08h и RST 18h. Для IM1 (`RST 38h`) — аналогично, но
+прерывание может прийти в любой момент, поэтому критические секции (своя
+страница в W0) обязаны быть обёрнуты в `DI`/`EI` (или проверять вложенность
+через счётчик), иначе повторное прерывание при уже замапленной странице
+попадёт в стаб, а не в EXP.asm.
+
+**Важно:** пока в W0 стоит ваша страница, системные вызовы (`RST 08h`/`10h`/`18h`)
+проходят через стабы и работают корректно, но с накладными расходами
+(~10+ тактов на каждый вызов). Код на странице не должен вызывать DSS/BIOS
+напрямую — только через RST. При этом сам стаб не должен использовать
+RST-инструкции, так как они адресуют W0, который в момент вызова стаба
+всё ещё содержит вашу страницу, а не ПЗУ — сначала переключите ПЗУ через
+`OUT (#7C),A`.
+
+Перед первым маппингом своей страницы в W0 сохраните текущее значение порта
+`#82` (`IN A,(#82)` — оно даёт номер системной/ПЗУ-страницы). Эта страница
+понадобится стабам для восстановления после вызова во время прерываний,
+когда ПЗУ уже может быть в W0, а стаб не успел его переключить.
+Подтверждённая реализация: `tests/w0page` (см. `sprite-api-design.md §9в`).
+
+---
+
+## 4.3 Окно W1 (#4000..#7FFF) — приложение
+
+W1 — основное окно для кода и данных приложения. По умолчанию содержит страницу 5 (RAM, инициализируется BIOS).
+
+**Использование BIOS/DSS:**
+
+BIOS и DSS могут **временно** переключать W1 на свою рабочую страницу. Это происходит:
+
+- При файловых операциях DSS: чтении FAT, загрузке секторов — DSS маппит одну из страниц разделяемого пула в W1 (DIRPAGE, FATPAGE, TXTPAGE, DRVPAGE).
+- При графических операциях BIOS: `PIC_FN2`/`PIC_FN3` (блоковые копии) могут переключать W1 на страницу видео-ОЗУ.
+- **Важно:** перед возвратом из вызова BIOS/DSS **восстанавливает** предыдущую страницу W1. Типовой паттерн в исходниках DSS:
+
+  ```asm
+  IN A,(SLOT1)    ; сохранить текущую страницу W1
+  PUSH AF
+  ... работа с разделяемым буфером ...
+  POP BC
+  LD C,SLOT1
+  OUT (C),B       ; восстановить W1
+  ```
+
+  Для вызывающей программы переключение W1 полностью прозрачно — после возврата из любой функции DSS/BIOS содержимое W1 идентично тому, что было до вызова.
+
+**Практические рекомендации:**
+- Размещайте код и данные в W1, рассчитывая, что он остаётся стабильным между вызовами.
+- При длительных файловых операциях (последовательный `READ` больших объёмов) W1 может быть затронут только в моменты внутреннего обращения DSS к FAT/буферам, но не во время собственно чтения данных в буфер программы.
+- Если нужно гарантированно сохранить данные через вызов DSS — используйте W2, который BIOS/DSS **никогда не трогают**.
+
+---
+
+## 4.4 Окно W2 (#8000..#BFFF) — стек (критично)
+
+W2 — **единственное окно, которое BIOS и DSS гарантированно не трогают**. Поэтому стек ОБЯЗАН находиться здесь:
+
+- **SP ≤ #BFFF** при вызовах DSS (`RST 10h`).
+- **SP ≥ #8000** при вызовах BIOS (`RST 08h`).
+- Пересечение → стек в `#8000..#BFFF`.
+- По умолчанию SP инициализируется в `#BFFE` (значение из EXE-заголовка, §4.7).
+
+**Почему W2 — единственное стабильное окно:**
+
+| Окно | Может быть переключено BIOS/DSS | Почему |
+|------|--------------------------------|--------|
+| W0 | Да | DSS переключает на COREPAGE при `RST 10h`; BIOS переключает на ПЗУ |
+| W1 | Да, временно | DSS маппит разделяемые буферы для FAT/директорий; BIOS при графических операциях — и **восстанавливает** перед возвратом |
+| W2 | **Нет** | **Никогда. Стек должен быть доступен всегда.** |
+| W3 | Да, временно | DSS маппит разделяемые буферы; BIOS при графике переключает на видео-ОЗУ; оба **восстанавливают** исходную страницу перед возвратом |
+
+**EXEC и W2:** при загрузке новой программы (`EXEC`, функция 40h) DSS сохраняет страницу W2 в EXSTACK (вместе с W1 и W3). После завершения программы (`EXIT`, функция 41h) W2 восстанавливается.
+
+**Практические рекомендации:**
+- Размещайте стек строго в W2. Стандартное значение `SP = #BFFE` — начало стека с запасом ~14 КБ до `#8000`. Можно уменьшить, если программа неглубокая.
+- W1 и W3 при вызовах DSS и BIOS **сохраняются и восстанавливаются** (см. §4.3, §4.5), но W2 — единственное окно, которое **никогда не трогается** ни DSS, ни BIOS.
+- Если программе нужно больше памяти, чем даёт W2 (например, для хранения больших массивов), выделяйте блоки через DSS `GETMEM` (функция 3Dh) и мапьте их в W1 или W3.
+
+---
+
+## 4.5 Окно W3 (#C000..#FFFF) — разделяемые страницы
+
+W3 — окно, в которое DSS временно маппит страницы своего разделяемого пула для дисковых буферов и служебных данных (адрес `#C000`):
+
+| Страница | Назначение | Адрес в W3 |
+|----------|------------|-------------|
+| DIRPAGE (0) | Буфер директории | `#C000` |
+| FATPAGE (1) | Кеш FAT | `#C000` |
+| TXTPAGE / ENVPAGE (2) | Буфер строки/окружения | `#C000..` (PATH_PNT_ARRAY `#FC80`, ENVTEMP `#FE00`) |
+| DRVPAGE (3) | Страница драйвера | `#C000` |
+| COREPAGE (4) | Ядро DSS (маппится в W0 при `RST 10h`) | — |
+
+**DSS СОХРАНЯЕТ и ВОССТАНАВЛИВАЕТ W3** после каждой операции. Типовой паттерн в исходниках:
+
+```asm
+IN A,(SLOT3)    ; сохранить текущую страницу W3
+PUSH AF
+... работа с разделяемым буфером ...
+POP BC
+LD C,SLOT3
+OUT (C),B       ; восстановить W3
+```
+
+Это означает, что для вызывающей программы переключение W3 полностью прозрачно — после возврата из любой функции DSS содержимое W3 идентично тому, что было до вызова.
+
+**Какие функции трогают W3:**
+
+Функции, обращающиеся к файловой системе, временно маппят разделяемые страницы в W3: поиск файла (`F_FIRST`/`F_NEXT`), чтение FAT (`OPEN`, `READ`, `WRITE`), работа с каталогами (`CHDIR`, `MKDIR`), буферы драйвера диска. Функции без дисковой активности (`VERSION`, `CURDISK`, `WAITKEY`, `LOCATE`, `SYSTIME`, `ENVIRON` и т.п.) W3 не трогают вообще.
+
+BIOS при графических операциях также временно переключает W3 на страницы видео-ОЗУ (например, `PIC_SET_PAL`, `PIC_FN2`) — и тоже восстанавливает.
+
+**Практические рекомендации:**
+- W3 можно использовать для данных программы — после возврата из любой функции DSS содержимое W3 не меняется.
+- Единственное исключение — `EXEC` (функция 40h): она загружает новую программу, и W3 получает страницы загруженного образа. Это ожидаемое поведение.
+- Если программа не вызывает дисковых и графических функций — W3 полностью стабилен.
+- **Стек нельзя размещать в W3** — не потому что W3 «теряется», а потому что переключение W3 происходит ВО ВРЕМЯ вызова. Если `SP` указывает на W3, то в момент, когда DSS временно маппит свой буфер, все push/pop внутри DSS будут обращаться к буферной странице, а не к данным программы. Кроме того, при прерывании IM1 обработчик EXP.asm сам переключает W3 на SYS_PAGE — что также сломает стек, если он в W3.
+
+---
+
+## 4.6 Физическая память и страницы
+
+Физическая память Sprinter — не сплошной массив RAM. Разные области адресного
+пространства зарезервированы под видео-ОЗУ, ПЗУ и кеш. Номер страницы — это
+значение, которое записывается в порт окна (`#82`/`#A2`/`#C2`/`#E2`);
+8-битный порт даёт **256 значений** (`#00..#FF`).
+
+**Фиксированная карта страниц:**
+
+| Диапазон | Страниц | Назначение |
+|----------|---------|------------|
+| `#00..#4F` (0..79) | 80 (1,25 МБ) | RAM общего назначения |
+| `#50..#5F` (80..95) | **16 (256 КБ)** | **Видео-ОЗУ (VRAM) — фиксировано в железе** |
+| `#60..#DF` (96..223) | 128 (2 МБ) | RAM общего назначения (верхний диапазон) |
+| `#E0..#EF` (224..239) | **16 (256 КБ)** | **ПЗУ: BIOS + EXP + ZX ROMs + bitstream — фиксировано** |
+| `#F0..#FF` (240..255) | 16 (256 КБ) | **Fast RAM (кеш) / системные страницы** |
+
+**Выделенные страницы:**
+
+| Страница | Назначение |
+|----------|------------|
+| `4` | **COREPAGE** — ядро DSS (маппится в W0 при `RST 10h`) |
+| `5` | Стандартная страница приложения W1 (по умолчанию) |
+| `#41` (65) | **Spec_Page** — сохранение состояния при soft-reset [EXP.asm:859,1019] |
+| `#FE` (254) | **SYS_PAGE** — системные данные BIOS (INT_ID, INT_ADRESS, буферы) [MAIN.asm:58] |
+| `#FF` (255) | **Dummy-страница**: чтение → `#FF`, запись игнорируется |
+
+**Ключевые моменты:**
+
+- **VRAM (`#50..#5F`) фиксирована аппаратно**, независимо от объёма RAM. Эти
+  16 страниц не являются частью RAM SIMM — это отдельная микросхема 256 КБ.
+  Биты 2-3 номера страницы кодируют режим записи: `#50` normal, `#54` без
+  ОЗУ-тени, `#58` прозрачный (байт `#FF` не пишется), `#5C` оба режима.
+- **ПЗУ (`#E0..#EF`)** — 256 КБ флеш-памяти с BIOS, EXP, ZX Spectrum 48/128 ROM,
+  TR-DOS, логотипом и битстримом для CPLD.
+- **Fast RAM (`#F0..#FF`)** — до 512 КБ быстрого SRAM (0 wait-states),
+  доступна через порт `#FB`. `#FE` (SYS_PAGE) и `#FF` (dummy) — часть этого
+  диапазона. При включённом кеше порт `#FB` конфликтует с CBL-звуком.
+- Для 2 МБ RAM: `#60..` заполнены до `#7F` (32 стр. = 512 КБ); остаток
+  `#80..#DF` — неиспользуемые страницы (отображаются как `#FF`).
+- Для 4 МБ RAM: `#60..#DF` целиком заполнены RAM (128 стр. = 2 МБ).
+
+> **Нумерация:** порты `#82`/`#A2`/`#C2`/`#E2` дают прямой доступ по
+> физическому номеру (#00..#FF). Порты `#7FFD`/`#1FFD` (совместимость с
+> ZX-Spectrum 128) используют сквозную нумерацию: номер в `#7FFD` (0..7)
+> маппится на физические страницы видеоОЗУ `#50..#5F` младшими 3 битами;
+> для работы с произвольными страницами используйте порты `#82`/`#A2`/`#C2`/`#E2`.
+
+---
+
+## 4.7 EXE-файл: формат и загрузка
+
+Загрузка исполняемых файлов выполняется функцией DSS `EXEC` (40h). Формат EXE-файла:
+
+**Заголовок (512 байт):**
+
+| Смещение | Размер | Поле | Описание |
+|----------|--------|------|----------|
+| +0 | 3 | `EXE_EXT` | Сигнатура `"EXE"` |
+| +3 | 1 | `VERSION` | Минимальная версия DSS (1 = v1.xx, 0 = без пути/аргументов) |
+| +4 | 2 | `OFFCOD1` | Младшее слово смещения образа в файле |
+| +6 | 2 | `OFFCOD2` | Старшее слово смещения (OFFCOD2 << 16 + OFFCOD1 = offset) |
+| +8 | 2 | `LOADER` | Размер первичного загрузчика (0 = весь образ сразу) |
+| +10 | 6 | `RESERVED` | Зарезервировано |
+| +16 | 2 | `LD_ADDR` | Адрес загрузки (`#4100..#FFFF`, старший байт маскирован `#3F`) |
+| +18 | 2 | `PC_REG` | Точка входа (entry point) |
+| +20 | 2 | `SP_REG` | Начальный SP (по умолчанию `#BFFE`) |
+| +22 | 1 | `UnUsedPoint` | Не используется |
+| +23 | 489 | `RESERVED2` | Зарезервировано (обнуляется; используется как временный стек EXEC) |
+
+**Процесс загрузки (EXEC, функция 40h):**
+
+1. Открыть файл на чтение.
+2. Считать 512-байтный заголовок в буфер ядра.
+3. Проверить сигнатуру `"EXE"` и версию (≥ минимальной 1).
+4. Если `LOADER=0`: seek на смещение `OFFCOD2:OFFCOD1`, считать весь образ по адресу `LD_ADDR`.
+5. Если `LOADER>0`: считать только первичный загрузчик по адресу `LD_ADDR` (он дочитает остальные сегменты).
+6. Выделить блок памяти через `GETMEM` (функция 3Dh), зарегистрировать в таблице RAM.
+7. Сохранить текущие страницы окон (SLOT1-3) в EXSTACK.
+8. Определить, сколько страниц нужно, и замаппить их через `SETWIN1`/`SETWIN2`/`SETWIN3`:
+   - Если `LD_ADDR ≥ #C000`: маппится только W3.
+   - Если `LD_ADDR ≥ #8000`: маппятся W2 и W3.
+   - Иначе: маппятся W1, W2 и W3.
+9. Построить **PSP** (Program Segment Prefix) — блок данных сразу ниже `LD_ADDR`:
+   - `LD_ADDR-3`: файловый манипулятор (file handle).
+   - `LD_ADDR-2`: идентификатор блока памяти.
+   - `LD_ADDR-1`: номер задачи.
+   - `LD_ADDR+0`: размер CLP (командной строки).
+   - `LD_ADDR+1..+128`: CLP-буфер.
+   - После CLP: строка пути `"A:\DIR\FILE.EXE",0`.
+10. Установить SP из заголовка (`SP_REG`), сохранить IX → адрес PSP.
+11. Если `VERSION=0` — установить текущий каталог из пути PSP.
+12. Затолкать в стек адрес возврата (RETFAR к DSS), **EI**, JP на точку входа.
+
+**Multi-bank EXE:**
+
+При наличии нескольких банков (`LOADER>0`) файл устроен так:
+
+```
+[512-байт заголовок] [HOME-сегмент] [Банк 1 (16 КБ)] [Банк 2 (16 КБ)] ...
+```
+
+- HOME-сегмент: образ, загружаемый DSS по `LD_ADDR`.
+- Банки: 16-КБ блоки, каждый на своей физической странице.
+- `LOADER` = размер HOME-сегмента (DSS загружает только его; первичный загрузчик сам дочитывает банки через `READ` из оставшегося открытым файла).
+
+---
+
+## 4.8 Прерывания и память
+
+**Обработчик IM1 (`RST 38h`):**
+
+Вектор фиксирован на `#0038` (W0). Реализация в EXP.asm:
+
+1. Переключает W3 на SYS_PAGE (BIOS).
+2. Проверяет флаг `INT_ID` = `#AA` (установлен при инициализации BIOS).
+3. Если флаг совпадает — вызывает пользовательский обработчик, адрес которого хранится в SYS_PAGE (`INT_ADDRESS`, `INT_PAGE`).
+4. После возврата восстанавливает W3 и выполняет `EI; RETI`.
+
+Это позволяет пользовательским программам устанавливать свои обработчики INT без полного перехвата вектора.
+
+**Обработчик IM1 (системный):**
+
+При возникновении прерывания Z80 исполняет `RST 38h` → вызов по адресу `#0038`. Реализация в EXP.asm (всегда доступна, т.к. `#0038` в W0):
+
+1. Переключает W3 на SYS_PAGE (BIOS).
+2. Проверяет флаг `INT_ID` = `#AA` (установлен при инициализации BIOS).
+3. Если флаг совпадает — вызывает пользовательский обработчик, адрес и страница которого хранятся в SYS_PAGE (`INT_ADDRESS`, `INT_PAGE`). Это позволяет программам устанавливать свои ISR без полного перехвата вектора.
+4. После возврата восстанавливает W3 и выполняет `EI; RETI`.
+
+**Обработчик IM2 (опционально, для продвинутых программ):**
+
+Sprinter по умолчанию не использует IM2. Исходники содержат шаблон `IM2_INT.asm` для программ, желающих переключиться на IM2:
+
+1. Сохраняет AF, BC, DE, HL, IX, IY и теневые регистры.
+2. Включает ПЗУ (`OUT (#7C),A`) — KEYSCAN требует ПЗУ в W0.
+3. Вызывает KEYSCAN (опрос AT-клавиатуры).
+4. Восстанавливает все регистры, `EI`, `RETI`.
+
+При переходе на IM2 программа сама выбирает значение `I` и размещает таблицу векторов в соответствующем диапазоне памяти.
+
+**Рекомендации:**
+- Если программа не использует прерывания — держите W0 в ПЗУ.
+- Если программа использует IM1 — можно переопределить обработчик через структуру в SYS_PAGE (флаг `INT_ID`, поля `INT_ADDRESS`/`INT_PAGE`).
+- Если программа использует IM2 — переключение полностью на ответственности программы; ядро Sprinter не предоставляет стандартного расположения таблицы векторов.
+
+---
+
+## 4.9 Типовые грабли
+
+- **Данные читаются как `#FF` / не сохраняются** — код или данные попали в незамапленное окно (страница `#FF`). Причина: образ программы меньше 16 КБ, DSS выделил только одну страницу, а код/данные распределены линкером в незамапленные окна. Лечение: убедитесь, что код и данные укладываются в одно окно, или явно выделяйте и мапьте остальные окна через `GETMEM`/`SETWIN1`-`SETWIN3`.
+
+- **Крэш при вызове RST при нестандартном W0** — если перед вызовом W0 содержал произвольную страницу ОЗУ, DSS при `RST 10h` переключит его, но может не восстановить корректно. Решение: перед вызовом RST включите ПЗУ (`OUT (#7C),A`), если не уверены в состоянии W0.
+
+- **Стек в W3 (не-рабочий вариант)** — если стек размещён в W3, при любом дисковом вызове W3 будет переключён на разделяемый буфер DSS, и стековые данные будут забиты. Результат: мгновенное зависание при возврате из функции. Единственное рабочее место для стека — W2.
+
+- **CBL не работает при включённом кеше** — порт `#FB` используется как кеш-память (Fast RAM) и как порт CBL-звука. Если кеш включён, запись в `#FB` уходит в кеш, а не в CBL. Детали: `11-ports.md`, `12-bugs.md`.
+
+- **Прерывание уходит не туда при IM2** — если программа переключилась в IM2 с неинициализированной таблицей векторов, любое прерывание приведёт к исполнению мусора. Решение: используйте IM1 (режим по умолчанию) или инициализируйте таблицу перед переключением.
+
+- **Не путать W3 с «теряется после вызова»** — многие источники утверждают, что DSS сбрасывает W3. На самом деле DSS **сохраняет и восстанавливает** W3 после каждой операции. Стек всё равно нельзя размещать в W3 (см. §4.5), но для данных W3 полностью стабилен между вызовами. Если ваша программа полагается на старый миф — проверьте код.
+
+---
+
+## 4.10 Кросс-ссылки
+
+- Порты страниц и детали регистров: `11-ports.md`
+- BIOS (графика, окна): `02-bios.md`
+- DSS/ESTEX (EXEC, GETMEM, SETWIN): `03-dss.md`
+- Прерывания: `07-irq.md`
+- Баги (CBL vs кеш, порт #FB): `12-bugs.md`
+- EXE-формат и PSР: `memory/exe-format.md`

docs/new/05-graphics.md

@@ -0,0 +1,279 @@
+# 5. Графика и видеосистема
+
+## 5.1 Общие сведения
+
+Видеосистема Sprinter Sp2000 реализована в ППЛМ. Видео-ОЗУ — 256 КБ
+(512 КБ на некоторых платах [Architecture.txt:17]).
+
+| Параметр | Значение |
+|---|---|
+| VRAM | 256 КБ, независимая микросхема (не часть RAM SIMM) |
+| Физические страницы | `#50..#5F` (16 страниц × 16 КБ), фиксировано в железе |
+| Видеорежимы | ZX-40, ZX-80, GR-256-8, GR-16-16 |
+| Палитра | 8 палитр × 256 цветов из 16 млн (RGB, BGR) |
+| Видеовыход | CGA-монитор, RGB, TV (SCART) |
+
+**Теневая память (Shadow RAM):** Видео-ОЗУ Спринтера является теневой памятью
+(§5.4). Программа управляет режимом записи через номер подключаемой страницы
+(§5.3): банк `0x50` пишет одновременно в VRAM и в основное ОЗУ; банк `0x54`
+пишет только в VRAM, не трогая ОЗУ. На экране **всегда** отображается
+содержимое VRAM, независимо от режима записи [IvanMak.txt:317–322].
+
+---
+
+## 5.2 Режимы адресации видео-ОЗУ
+
+Видео-ОЗУ может адресоваться двумя способами — **спектрумовским** и
+**графическим** [IvanMak.txt:296–300]. Спектрумовский режим используется для
+Spectrum-совместимого вывода и загрузки знакогенераторов; графический — для
+всех остальных видеорежимов (320×256×256, 640×256×16, текст 80×32).
+
+### 5.2.1 Спектрумовский режим адресации
+
+В этом режиме VRAM разбивается на **32 блока по 8 КБ**. Адрес блока задаётся
+через порт `RGADR` (`PORT_Y`, `#89`):
+
+| Бит | Назначение |
+|-----|-----------|
+| 4..0 | Номер блока (0..31) |
+| 5 | Не используется |
+| 6 | Запрет вывода (1 = отключить спектрумовский вывод) |
+| 7 | Разрешение 16-КБ страницы (1 = два блока в `#4000..#7FFF`) |
+
+Бит 0 RGADR вместе с битом 1 порта `#7FFD` определяет чётность подключаемого
+блока VRAM: чётный RGADR → блок N в `#4000..#5FFF`, блок N+1 в `#C000..#DFFF`;
+нечётный → наоборот [IvanMak.txt:333–339].
+
+Для записи в определённую пару спектрумовских блоков:
+1. Записать номер блока в `RGADR` (`OUT (#89),A`).
+2. Убедиться, что в окне (`#4000` или `#C000`) стоит подходящая страница
+   основного ОЗУ (любая, кроме `#50..#5F`).
+3. Чтение/запись по спектрумовским адресам (`#4000..#5FFF`,
+   `#C000..#DFFF`) попадает в VRAM через текущий блок.
+
+**Выключение спектрумовского вывода:** Если программа не использует
+Spectrum-совместимую графику, `RGADR` рекомендуется установить в `#C0..#FF`
+(бит 6 = 1). В этом случае вывод в VRAM через спектрумовский режим не
+производится [IvanMak.txt:346–348].
+
+### 5.2.2 Графический режим адресации
+
+В графическом режиме видео-ОЗУ организовано как матрица **256 строк
+(rows) × 1024 байта** [IvanMak.txt:357–358]. Адресация:
+
+```
+VRAM_адрес = (RGADR << 10) | (Z80_A[9:0])
+  где RGADR[7:0] = Y (номер строки, 0..255)
+      Z80_A[9:0] = X (смещение в строке, 0..1023)
+```
+
+Страницы `#50..#5F` при маппинге в любое окно Z80 включают графическую
+адресацию. При этом младшие 4 бита номера страницы не влияют на адрес
+памяти, а задают подрежим вывода (§5.3).
+
+**Важная особенность:** Z80-адрес внутри окна (биты A[13:10] для окна W3)
+**игнорируется** — весь 16-КБ диапазон окна отображает **одну и ту же
+строку**, выбранную `RGADR`. Доступ к другим строкам — только через смену
+`RGADR`. Это означает, что утверждение из SprinterGraphics programming.txt
+о доступе к строкам 18..31 через адреса `#C400..#FC00` **неверно**.
+
+**Структура 1-КБ строки (1024 байта):**
+
+| Смещение в строке | Назначение |
+|-------------------|-----------|
+| `#000..#13F` (0..319) | Экранная страница 0 (первые 320 байт) |
+| `#140..#27F` (320..639) | Экранная страница 1 (следующие 320 байт) |
+| `#280..#3FF` (640..1023) | Не используется / данные палитры |
+
+Две экранные страницы (0 и 1) переключаются битом 0 порта `RGMOD` [IvanMak.txt:409].
+
+**Работа с адресацией из программы:**
+
+```asm
+; Установить страницу VRAM (0x50) в W3
+IN    A, (#E2)          ; сохранить текущую W3
+LD    (old_page), A
+LD    A, #50
+OUT   (#E2), A          ; W3 = VRAM страница 0x50
+
+; Выбрать строку Y
+LD    A, Y              ; Y = 0..255
+OUT   (#89), A          ; RGADR = Y
+
+; Чтение/запись пикселя (X,Y) для экранной страницы 0
+LD    HL, #C000 + X     ; X = 0..319
+LD    (HL), colour      ; запись байта пикселя
+
+; Восстановить страницу
+LD    A, (old_page)
+OUT   (#E2), A
+```
+
+---
+
+## 5.3 Подрежимы вывода (страницы `#50..#5F`)
+
+Биты 2 и 3 номера страницы (из диапазона `#50..#5F`) задают подрежимы вывода
+[IvanMak.txt:364–386]:
+
+| Бит | Страницы | Эффект |
+|-----|----------|--------|
+| 3 | `#58..#5F` | **Прозрачный цвет** — запись байта `#FF` игнорируется (для спрайтов) |
+| 2 | `#54..#57`, `#5C..#5F` | **Без тени** — запись только в VRAM, не в основное ОЗУ (для курсора мыши) |
+
+Биты 0 и 1 должны быть 0 для совместимости с будущими прошивками
+[IvanMak.txt:384–386].
+
+---
+
+## 5.4 Теневая память (Shadow RAM) и двойная запись
+
+Видео-ОЗУ Спринтера является теневой памятью по отношению к основному ОЗУ
+[IvanMak.txt:317–322]. Видеоконтроллер **всегда** читает изображение из VRAM
+для вывода на экран; основное ОЗУ в формировании изображения не участвует.
+Однако при записи через графические банки `#50..#5F` поведение зависит от
+выбранного подрежима:
+
+- **Банк `0x50` (normal):** запись идёт **одновременно** в VRAM и в
+  соответствующую область основного ОЗУ. Чтение из того же Z80-адреса
+  возвращает данные из основного ОЗУ, а не из VRAM — VRAM для процессора
+  на чтение не видна.
+- **Банк `0x54` (noshadow):** запись — только в VRAM, основное ОЗУ не
+  изменяется. Чтение — из основного ОЗУ (там хранится «фон»).
+- **Банк `0x58` (transparent):** как normal, но байт `#FF` не пишется.
+- **Банк `0x5C` (sprite):** transparent + noshadow.
+- **Обычные банки (не `#50..#5F`):** никакого доступа к VRAM нет,
+  чтение/запись идут напрямую в основное ОЗУ.
+
+**Зачем это нужно:**
+
+1. **Восстановление после переключения видеорежима:** данные в основном ОЗУ
+   остаются нетронутыми, так что при возврате в графический режим экран можно
+   восстановить без перерисовки [IvanMak.txt:325].
+2. **Heal спрайтов** (libbgi): фон, на который был выведен спрайт в банке
+   `GFX_BANK_SPRITE` (`0x5C`, без тени), остался в основном ОЗУ. После
+   перемещения спрайта фон копируется из основного ОЗУ обратно в VRAM
+   (операция heal), стирая спрайт.
+3. **Курсор мыши** без сохранения/восстановления: временный вывод через
+   `GFX_BANK_NOSHADOW` (`0x5C`) — в основном ОЗУ данные под курсором не
+   портятся, достаточно при следующем обновлении просто перерисовать фон.
+
+**Режимы записи (см. §5.3):**
+
+| Режим | Пишет в VRAM | Пишет в осн. ОЗУ | Применение |
+|-------|:---:|:---:|-----------|
+| `0x50` (normal) | Да | Да | Обычный вывод |
+| `0x54` (noshadow) | Да | **Нет** | временные эффекты |
+| `0x58` (transparent) | Да (кроме `#FF`) | Да | Спрайты с прозрачностью без heal |
+| `0x5C` (sprite) | Да (кроме `#FF`) | **Нет** | Курсор, спрайты (прозрачность + heal) |
+
+---
+
+## 5.5 Видеорежимы
+
+Система поддерживает независимую установку режима для каждого квадратика
+8×8 (или 16×8 для 640-режимов) на экране [IvanMak.txt:405–469].
+
+### Режимы вывода
+
+| Режим | Разрешение | Цветов | Описание |
+|-------|-----------|--------|----------|
+| ZX-40 | 320×256 | 16 | Текстовый 40×32, Spectrum-совместимый |
+| ZX-80 | 640×256 | 16 | Текстовый 80×32, до 36 знакогенераторов |
+| GR-256-8 | 320×256 | 256 | Графический, 1 байт/пиксель |
+| GR-16-16 | 640×256 | 16 | Графический, 4 бита/пиксель |
+
+### Формат пикселей
+
+**GR-256-8 (320×256×256):** один байт = один пиксель. Строка содержит
+320 байт для экранной страницы 0 (смещения `#000..#13F`) и 320 байт для
+страницы 1 (`#140..#27F`). Полный экран: 320 × 256 = 81 920 байт на страницу.
+
+**GR-16-16 (640×256×16):** один байт = два пикселя: младший полубайт —
+левый/первый пиксель, старший — правый/второй. Строка содержит 320 байт на
+экранную страницу, что даёт 640 пикселей (320 × 2). Структура строки та же:
+320 байт на страницу 0, 320 на страницу 1.
+
+### Установка режима
+
+Режим задаётся 4 байтами `Mode0..Mode3` в области режимов VRAM
+(`#0300..#039F`). Полное описание формата Modei — [IvanMak.txt:448–469].
+
+Для переключения видеорежима из программ используется функция DSS `SETVMOD`
+(50h) [DiskSyscalls.txt:345–349]:
+
+| A (режим) | Описание |
+|-----------|----------|
+| 02h | Текстовый 40×32×16 |
+| 03h | Текстовый 80×32×16 |
+| 81h | Графический 320×256×256 |
+| 82h | Графический 640×256×16 |
+
+B — страница экрана (0/1). Вызов: `RST 10h` с C=50h. Флаг C = ошибка
+(например, режим не поддерживается данным монитором).
+
+---
+
+## 5.6 Палитра
+
+8 палитр по 256 цветов, каждая занимает 1 КБ в VRAM по адресам
+`#03E0..#03FE` [IvanMak.txt:540–568].
+
+| Адреса | Палитра | Назначение |
+|--------|---------|-----------|
+| `#03E0..#03E2` | Граф. 0 | Графические режимы |
+| `#03E4..#03E6` | Граф. 1 | —//— |
+| `#03E8..#03EA` | Граф. 2 | —//— |
+| `#03EC..#03EE` | Граф. 3 | —//— |
+| `#03F0..#03F2` | Текст. 4 | Цвет бумаги |
+| `#03F4..#03F6` | Текст. 5 | Цвет символа |
+| `#03F8..#03FA` | Текст. 6 | Цвет мерцания бумаги |
+| `#03FC..#03FE` | Текст. 7 | Цвет мерцания символа |
+
+Каждый четвёртый байт в каждой палитре не используется — не может попасть
+на ЦАП [IvanMak.txt:545–547]. Выбор палитры для каждого квадратика — через
+биты 7..6 байта Mode1 [BIOS_v3.txt:348].
+
+> **Примечание:** Architecture.txt упоминает всего 5 палитр (4 графические +
+> 1 текстовая), но IvanMak описывает все 8: 4 графические (0–3) и 4 текстовые
+> (4–7: бумага, символ, мерцание бумаги, мерцание символа)
+> [IvanMak.txt:547–548, 561–568].
+
+---
+
+## 5.7 Структура VRAM в терминах BIOS
+
+При использовании BIOS распределение VRAM [IvanMak.txt:387–404]:
+
+| Адреса (линии) | Назначение |
+|----------------|-----------|
+| `#0000..#003F` | Спектрумовский экран (блоки 0..1) |
+| `#0040..#017F` | Первый графический экран (блоки 2..11) |
+| `#0180..#02BF` | Второй графический экран (блоки 12..21) |
+| `#02C0..#02FF` | Знакогенераторы текстового режима |
+| `#0300..#039F` | Область описания режимов экрана |
+| `#03A0..#03DF` | Зарезервировано |
+| `#03E0..#03FF` | Палитра |
+
+---
+
+## 5.8 Заблуждения и неподтверждённое
+
+**Миф о строках 18–31:** В документе SprinterGraphics programming.txt
+утверждается, что после выбора строки Y через RGADR, по адресам
+`#C400..#FC00` доступны строки Y+1..Y+15 (с шагом 1 КБ). В эмуляторе MAME
+это **не работает** — весь 16-КБ диапазон страницы `#50..#5F` отображает
+только строку Y, независимо от бит A[13:10] адреса Z80. Требуется проверка
+на реальном Sprinter Sp2000.
+
+---
+
+## 5.9 Кросс-ссылки
+
+- Палитра и видеорежимы BIOS: `02-bios.md §2.7`
+- SETVMOD (DSS): `03-dss.md §3.10`
+- Акселератор: `06-accel.md`
+- Быстрое ОЗУ и конфликт с акселератором: `04-memory.md §4.6`
+- Порты RGADR/RGMOD: `11-ports.md`
+- Баги акселератора: `12-bugs.md`
+- Проектные документы: `sprite-api-design.md`, `accel-fill-budget.md`

docs/new/06-accel.md

@@ -0,0 +1,221 @@
+# 6. Акселератор
+
+## 6.1 Общие сведения
+
+Акселератор — внутреннее устройство, реализованное в ППЛМ. Присутствует почти
+во всех конфигурациях Sprinter (Sprinter-2 и выше). Предназначен для ускорения
+пересылки блоков данных между RAM и VRAM (до физического предела скорости ОЗУ).
+Не поддерживает ПЗУ и Fast RAM [accelerator_doc.txt:5].
+
+**Возможности:**
+
+- Быстрая заливка горизонтальной или вертикальной линии экрана (1..256 пикселей)
+  одним цветом; в режиме 640×256 — линия 1..512 пикселей.
+- Быстрое копирование горизонтальной или вертикальной линии (1..256 пикселей).
+- Логические операции AND, OR, XOR с блоками данных.
+
+**Внутренняя память:** 256 байт в ППЛМ. Данные загружаются в эту память,
+затем копируются в выбранный участок RAM/VRAM. Операция копирования может
+повторяться многократно — это позволяет заполнять экран текстурой без
+перезагрузки данных.
+
+**Автоматический инкремент адреса:**
+
+- **Горизонтальные** операции (`LD L,L` — копирование, `LD C,C` — заливка):
+  акселератор автоматически инкрементирует регистр HL (адрес приёмника) на
+  каждом шаге. Для копирования источник (DE) также инкрементируется.
+- **Вертикальные** операции (`LD A,A` — копирование, `LD E,E` — заливка):
+  акселератор автоматически меняет порт `RGADR` (`#89`) — координату Y.
+  После завершения операции `RGADR` содержит новое значение
+  (Y + размер_блока, если не было переполнения).
+- **Комбинированный** режим (горизонтальный источник + вертикальный приёмник):
+  сначала загружается байт из последовательных данных, затем выполняется
+  вертикальная запись. `RGADR` инкрементируется; регистр-источник (DE)
+  тоже инкрементируется — можно последовательно читать спрайт и рисовать
+   его вертикальными строками (§6.3, пример «Спрайт»).
+
+## 6.2 Команды
+
+Акселератор управляется специальными инструкциями Z80, которые выполняются
+как NOP обычным процессором, но распознаются ППЛМ [IvanMak.txt:810–848].
+
+| Инструкция | Код | Действие |
+|-----------|:---:|----------|
+| `LD B,B` | `#40` | **Выключить** акселератор |
+| `LD D,D` | `#52` | **Включить** + режим «задать размер блока» |
+| `LD A,size` | `#3E size` | Установить размер блока (сразу после `LD D,D`) |
+| `LD C,C` | `#4F` | **Горизонтальная заливка** одним байтом |
+| `LD E,E` | `#5B` | **Вертикальная заливка** одним байтом |
+| `LD L,L` | `#6D` | **Горизонтальное копирование** блока |
+| `LD A,A` | `#7F` | **Вертикальное копирование** блока |
+| `LD H,H` | `#64` | Зарезервировано |
+
+**Логические операции** (AND, OR, XOR) выполняются командами
+`AND (HL)`, `OR (HL)`, `XOR (HL)` после загрузки блока в память акселератора.
+
+## 6.3 Примеры
+
+### Копирование экрана (страница 0 → страница 1)
+
+```asm
+; страница VRAM уже открыта по адресу #C000
+LD   HL, #C000       ; адрес начала линии первого экрана
+LD   DE, #C140       ; адрес начала линии второго экрана
+LD   BC, #140        ; длина строки по горизонтали (320)
+DI                   ; запретить прерывания
+LD   D,D             ; включить акселератор: режим размера блока
+LD   A, 0            ; размер блока = 256 байт (0 = 256)
+LD   A,A             ; вертикальное копирование
+LDIR                 ; копировать
+LD   B,B             ; выключить акселератор
+EI                   ; разрешить прерывания
+```
+
+Время исполнения: ~1.2 прерывания (~24–26 мс на полный экран)
+[IvanMak.txt:822–823], [accelerator_doc.txt:37].
+
+### Заливка блока одним цветом
+
+```asm
+LD   DE, #C000 + X   ; X — смещение по горизонтали
+LD   A, Y
+OUT  (#89), A        ; RGADR = Y
+DI
+LD   D,D             ; режим размера блока
+LD   A, width        ; ширина блока
+LD   B,B             ; стоп
+LD   A, colour       ; цвет заливки
+LD   C,C             ; горизонтальная заливка
+LD   (DE), A         ; залить
+LD   B,B             ; стоп
+EI
+```
+
+### XOR блока данных
+
+```asm
+LD   HL, addr_1
+LD   DE, xor_data
+DI
+LD   D,D
+LD   A, 0            ; 256 байт
+LD   L,L             ; горизонтальное копирование
+LD   A, (DE)         ; загрузить блок в память акселератора
+XOR  (HL)            ; XOR с данными в RAM
+LD   (HL), A         ; сохранить результат
+LD   B,B             ; стоп
+EI
+```
+
+### Копирование вертикальной линии с разделением load/write
+
+Загрузка байта в буфер акселератора и запись из буфера в VRAM разнесены —
+между ними можно выполнять произвольный код (например, сменить Y).
+
+Буфер акселератора и размер блока **сохраняются** между включениями и
+выключениями (`LD B,B`), что позволяет гибко разделять чтение
+и запись.
+
+```asm
+LD   HL, #C000 + X1     ; источник
+LD   DE, #C000 + X2     ; приёмник
+
+DI
+LD   D,D                ; акселератор вкл, режим размера
+LD   A, size            ; размер блока
+LD   B,B                ; выключить (размер запомнен)
+
+LD   A, Y1
+OUT  (#89), A           ; RGADR = Y1
+
+LD   A,A                ; вертикальное копирование
+LD   A, (HL)            ; загрузить байт из (HL) в буфер акселератора
+LD   B,B                ; выключить (буфер запомнен)
+
+LD   A, Y2
+OUT  (#89), A           ; RGADR = Y2 (смена Y между load и write)
+
+LD   A,A                ; вертикальное копирование
+LD   (DE), A            ; записать буфер в (DE) — акселератор пишет
+                        ; вертикальную линию size пикселей
+LD   B,B                ; выключить
+EI
+```
+
+### Спрайт вертикальными строками из последовательных данных
+
+Спрайт хранится как последовательность байт вертикальных линий. Для каждой
+колонки спрайта: загружается байт из последовательных данных, затем
+акселератор пишет его вертикально (автоинкремент `RGADR`). После завершения
+колонки — сдвиг по X (`INC HL`) и повтор.
+
+```asm
+LD   DE, sprite_data      ; DE → последовательные данные спрайта
+LD   HL, #C000 + X_COORD  ; HL → начальная позиция на экране
+LD   B, sprite_width      ; ширина спрайта в колонках
+
+LD   D,D                  ; акселератор вкл, режим размера
+LD   A, sprite_height     ; высота одной вертикальной линии
+LD   B,B                  ; акселератор выключили (размер акселератор запомнил)
+
+row:
+LD   A, Y_COORD
+OUT  (#89), A             ; RGADR = стартовая Y
+DI
+LD   L,L                  ; режим «загрузить из последовательных данных»
+LD   A, (DE)              ; загрузить байт спрайта в буфер акселератора
+LD   A,A                  ; вертикальное копирование
+LD   (HL), A              ; записать — акселератор копирует байт
+                          ; вертикально, RGADR++ на каждом шаге
+LD   B,B                  ; выключить акселератор
+EI
+INC  HL                   ; следующая колонка по X
+DJNZ row
+```
+
+## 6.4 Скорость
+
+Время работы акселератора ограничено только физической скоростью ОЗУ
+[IvanMak.txt:840–843]:
+
+```
+Время ≈ время команды без акселератора + число_байт / 7 000 000 (сек)
+```
+
+## 6.5 Комбинированный режим: общая схема
+
+Общий паттерн для работы с акселератором в комбинированном режиме
+(горизонтальный источник + вертикальный приёмник):
+
+```
+LD   D,D            ; 1. Включить акселератор, режим размера
+LD   A, size        ; 2. Задать размер блока (1..256)
+LD   L,L            ; 3. Режим «горизонтальный источник»
+<чтение байта>      ; 4. Загрузить байт в буфер акселератора (LD A,(DE) и т.п.)
+LD   A,A            ; 5. Режим «вертикальный приёмник»
+<запись байта>      ; 6. Записать — акселератор делает вертикальное копирование
+                    ;    с автоинкрементом RGADR и приёмника
+LD   B,B            ; 7. Выключить акселератор
+```
+
+После шага 6 `RGADR` содержит Y + size, HL — X + 1 (если был `INC HL`).
+
+## 6.6 Прерывания
+
+**Старая прошивка:** DI обязателен на время работы акселератора — система
+команд Z80 сильно меняется, и ISR не сможет корректно выполниться
+[IvanMak.txt:844–846].
+
+**Новая прошивка:** акселератор может работать с EI. По приходу прерывания
+он отключается, а по `RETI` включается обратно [IvanMak.txt:846–848].
+Использовать этот режим следует с осторожностью — без проверки на реальном
+железе неизвестно, какая версия прошивки установлена.
+
+---
+
+## 6.7 Кросс-ссылки
+
+- Баги акселератора: `12-bugs.md`
+- Использование акселератора в libbgi: `sprite-api-design.md`
+- Ограничение скорости: `accel-fill-budget.md`
+- Fast RAM и конфликт с портом CBL: `04-memory.md §4.6`

docs/new/07-irq.md

@@ -0,0 +1,92 @@
+# 7. Прерывания (IRQ)
+
+## 7.1 Общие сведения
+
+Sprinter Sp2000 поддерживает режимы прерываний IM1 и IM2.
+
+### Источники прерываний
+
+| Источник | Происхождение | Описание |
+|----------|---------------|----------|
+| Кадровые (INT) | Видеоконтроллер | Квадратик экрана в 8-й линии |
+| CTC | Z84C15 | Таймерные прерывания |
+| SIO | Z84C15 | AT-клавиатура |
+| PIO | Z84C15 (бит 0 порта B, `#1F`) | ISA-слоты |
+| CBL | COVOX-Blaster | Запрос данных |
+
+### Различение источников
+
+Кадровые и клавиатурные прерывания приходят с вектором `0FFh` [Parinov.txt:956]. Способ различения:
+
+- Клавиатура выставляет бит 0 в порте `19h` — признак приёма байта [Parinov.txt:1049]
+- Если бит 0 порта `19h` не установлен — прерывание кадровое
+
+> **Примечание:** [Parinov.txt:956] описывает альтернативный метод — «отличать по биту приема байта в порте клавиатуры». Оба метода сводятся к проверке бита 0 в порте `19h`.
+
+### Выбор режима прерываний (IM1 vs IM2)
+
+| Режим | Контекст | Источник |
+|-------|----------|----------|
+| IM2 | Рекомендован для работы с BIOS через RST | IvanMak.txt:1469–1473 |
+| IM1 | Используется DSS для своих обработчиков | — |
+| IM1 | Fast-RAM секция предполагает обработчик по `#0038` | Parinov.txt:601 |
+| IM2 | Рекомендован при выставленных прерываниях от CBL | Parinov.txt:762–763 |
+
+> **Примечание:** разные подсистемы рекомендуют разные режимы. IM2 предпочтителен при интенсивной работе с прерываниями (CBL, BIOS). IM1 используется DSS по умолчанию.
+
+## 7.2 Кадровые прерывания (INT)
+
+Генерируются в момент прохождения 8-й строки квадратика (настраивается через бит 0 порта `#FE`). Положение INT подстраивается под стандарт Pentagon (320 строк) или Scorpion (312 строк).
+
+> **Мышь — есть ли аппаратные прерывания?** [Parinov.txt:956] утверждает: «От мыши прерывания не приходят. Сделать можно, но сейчас их нет.» [ProgrammerManual.txt:1784–1786] описывает драйвер мыши, где «каждое нажатие и отпускание клавиш или перемещение мыши вызывает прерывание», и документирует функцию «80h MOUSE HARDWARE INTERRUPT» [ProgrammerManual.txt:1930–1937]. Parinov (разработчик драйвера) отрицает их наличие — возможно, ProgrammerManual описывает планируемую функциональность.
+
+## 7.3 CTC (Z84C15)
+
+Таймер CTC используется для:
+
+- Генерации периодических прерываний
+- Задания частоты CBL (COVOX-Blaster)
+- Синхронизации звука
+
+## 7.4 SIO (Z84C15)
+
+Внутренний SIO Z84C15 обслуживает:
+
+- AT-клавиатуру (порты `#18`/`#19`)
+- RS-232 (для мыши и других последовательных устройств)
+
+## 7.5 IM1 — вектор #0038
+
+Стандартный Z80-режим. Все INT ведут на адрес `#0038`. Используется DSS для своих обработчиков.
+
+## 7.6 IM2 — таблица векторов
+
+IM2 использует таблицу векторов (256 байт) в фиксированной странице (обычно W3). Вектор прерывания — `0FFh`.
+
+Для работы IM2 требуется:
+
+1. Таблица векторов в резиденте (W3)
+2. Регистр I = старший байт адреса таблицы
+3. Каждый вектор — адрес обработчика (2 байта)
+
+## 7.7 Акселератор и прерывания
+
+При работе акселератора система команд Z80 сильно меняется.
+
+| Режим | Описание | Источник |
+|-------|----------|----------|
+| Старый | DI обязателен | IvanMak.txt:844–846, Parinov.txt:954 |
+| Новый | EI/RETI: по INT акселератор отключается, по RETI включается | IvanMak.txt:846–848 |
+
+> **Примечание:** IvanMak описывает два режима (старый — DI, новая прошивка — EI/RETI). Parinov знает только старый. Без тестирования на железе неизвестно, какая версия прошивки установлена.
+
+## 7.8 Цепочка обработчиков
+
+TODO (проектный `im2_isr_design.md`): цепочка irq_install/remove, FPS-делитель, обработчики клавиатуры.
+
+## 7.9 Кросс-ссылки
+
+- Порты прерываний: `11-ports.md`
+- Проектный документ по IM2/ISR: `im2_isr_design.md`
+- Клавиатура: `09-input.md §9.1`
+- CBL (прерывания): `10-sound.md §9.4.6`

docs/new/08-io.md

@@ -0,0 +1,197 @@
+# 8. Ввод-вывод
+
+## 8.1 Клавиатура и мышь
+
+Клавиатура и мышь вынесены в отдельный документ: `09-input.md`.
+
+Сводная информация по портам и прерываниям — `09-input.md §§9.1–9.6`.
+
+## 8.2 Звук
+
+Звуковая подсистема (AY-3-8910, COVOX, COVOX-Blaster, бипер) вынесена
+в отдельный документ: `10-sound.md`.
+
+Сводная карта звуковых портов: `11-ports.md §11.6`.
+
+## 8.3 Дисковая подсистема
+
+### 8.3.1 FDD (WD1793 / КР1818ВГ93)
+
+Контроллер дисковода — стандартный Beta Disk Interface (WD1793).
+Аппаратное перенаправление `#1F → #0F` (см. §8.4).
+
+**Регистры (по данным MAME sprinter.cpp):**
+
+| Z80-адрес | Регистр |
+|-----------|---------|
+| `#0F` | Status (чт) / Command (зп) |
+| `#1F` | —//— (аппаратный ремап на `#0F`) |
+| `#3F` | Track |
+| `#5F` | Sector |
+| `#7F` | Data |
+| `#FF` | Drive Control (выбор дисковода) |
+
+**Противоречие: адресация регистров ВГ93.**
+> - [IvanMak.txt:1270–1274]: 4 регистра + `#FF` — управление дисководом.
+> - [Parinov.txt:963]: 3 регистра (data-регистр `#7F` пропущен).
+>
+> MAME реализует полный набор по IvanMak: Status/Command (`#0F`), Track (`#3F`),
+> Sector (`#5F`), Data (`#7F`). Data-регистр важен — через него читаются/пишутся
+> сектора. Parinov, вероятно, упустил его.
+
+**Turbo-режим FDD (DCP 0x16/0x17, биты):**
+- Бит 0 = скорость (0=норм, 1=турбо)
+- Бит 1 = отключение FDD [sprinter.cpp:914–920]
+
+### 8.3.2 HDD (IDE/ATA)
+
+Два ATA-интерфейса: первичный и вторичный. Доступ — через DCP-декодер
+(внутренние коды 0x20–0x2b).
+
+**Регистры ATA CS0 (по sprinter.cpp):**
+
+| DCP код | Z80-адрес (старш.) | Регистр |
+|---------|-------------------|---------|
+| 0x20 | `#xx50` | Data (16-bit через защёлку байтов) |
+| 0x21 | `#xx51` | Error (чт) / Features (зп) |
+| 0x22 | `#xx52` | Sector Count |
+| 0x23 | `#xx53` | Sector Number |
+| 0x24 | `#xx54` | Cylinder Low |
+| 0x25 | `#xx55` | Cylinder High |
+| 0x26 | `#xx56` | Device/Head |
+| 0x27 | `#xx57` | Status (чт) / Command (зп) |
+| 0x28 | `#xx58` | Alt Status (чт) / Device Control (зп) (CS1) |
+| 0x2a | HDD1 select (вторичный) |
+| 0x2b | HDD2 select (первичный) |
+
+**16-битный data-порт:** MAME реализует защёлку байтов: чтение `#xx50`
+возвращает младший байт (bit8=0), затем старший (bit8=1) [sprinter.cpp:958–972].
+
+**Противоречие: HDD — разные адреса для чтения и записи.**
+> - [IvanMak.txt:1366]: кратко: «#xx50..#xx55 – порты HDD»
+> - [Parinov.txt:958–959]: таблица с разными адресами для R/W:
+>   `0050h` (чт) / `0150h` (зп) — data, `4053h` (чт) / `4153h` (зп) — status/command.
+>
+> MAME использует единую карту DCP-кодов (0x20–0x28) без разделения R/W.
+> Parinov описывает реальное поведение на Sprinter-2, где адресная линия A8
+> управляет направлением — это внешняя особенность конкретной ППЛМ-прошивки.
+> IvanMak упрощает до базовых DCP-кодов.
+
+Доступ к IDE открыт в режиме Sprinter-ZX, в режимах Pentagon/Scorpion — закрыт.
+
+### 8.3.3 CMOS (Dallas DS12887A)
+
+Микросхема DS12887A (RTC + 114 байт NV RAM). Совместима с MC146818A.
+Доступ через DCP-коды 0x1c–0x1e.
+
+| Z80-адрес | DCP код | Функция |
+|-----------|---------|---------|
+| `#DFBD` | 0x1d | Запись адреса регистра CMOS |
+| `#FFBD` | 0x1c | Чтение данных из выбранного регистра |
+| `#BFBD` | 0x1e | Запись данных в выбранный регистр |
+
+При отсутствии микросхемы CMOS эмулируется BIOS [BIOS_v3.txt:308–310].
+
+**Карта регистров RTC (совместимо с MC146818A):**
+
+| Рег. | Назначение | Формат |
+|------|-----------|--------|
+| 0x00 | Секунды | BCD |
+| 0x01 | Секунды (будильник) | BCD |
+| 0x02 | Минуты | BCD |
+| 0x03 | Минуты (будильник) | BCD |
+| 0x04 | Часы | BCD |
+| 0x05 | Часы (будильник) | BCD |
+| 0x06 | День недели (1=воскресенье) | BCD |
+| 0x07 | Число | BCD |
+| 0x08 | Месяц | BCD |
+| 0x09 | Год | BCD |
+| 0x0a | Регистр A (UIP, divider, rate) | биты |
+| 0x0b | Регистр B (SET, PIE, AIE, UIE, SQWE, DM, 24/12, DSE) | биты |
+| 0x0c | Регистр C (IRQF, PF, AF, UF) | биты (чт) |
+| 0x0d | Регистр D (VRT) | биты (чт) |
+| 0x0e–0x7f | 114 байт NV RAM | пользовательские |
+
+---
+
+## 8.4 Джойстик
+
+**Два Kempston-совместимых джойстика** [sprinter.cpp:1106–1175]:
+
+- **JOY1** — через CIO_DTRB (DCP 0x15, совмещён с Beta state при чтении)
+- **JOY2** — через PIO PB
+
+**Формат данных (Kempston):**
+
+| Бит | Кнопка |
+|:---:|--------|
+| 0 | Вправо |
+| 1 | Влево |
+| 2 | Вниз |
+| 3 | Вверх |
+| 4 | Fire |
+| 5 | — |
+| 6 | — |
+| 7 | — |
+
+**Противоречие: джойстик #1F vs #0F.**
+> - [IvanMak.txt:1344]: «#1F,#0F — RD_KEMPS — порт джойстика.
+>   В Sprinter-1 порт #1F аппаратно переадресуется на порт #0F.»
+> - [IvanMak.txt:861–868]: команды `OUT (#1F),A` не срабатывают
+>   из-за перенаправления. Надо использовать `LD BC,#1F : OUT (C),A`.
+>
+> В Sprinter-1 включено аппаратное перенаправление `#1F → #0F`,
+> из-за чего `IN A,(#1F)` не читает джойстик. MAME подтверждает:
+> на Sp2000 (`m_cnf` bit 0) перенаправление отключается
+> [sprinter.cpp:1106]. Ремап действует только на запись: при OUT
+> порт `#1F` маппится на `#0F` через DCP [sprinter.cpp:1080].
+
+JOY2 читается через PIO port A [sprinter.cpp:1136–1140].
+
+---
+
+## 8.5 Параллельный порт (принтер)
+
+Centronics-совместимый через ППЛМ. BIOS-функции печати: 082h–08Ch
+(см. `02-bios.md`).
+
+---
+
+## 8.6 Шина ISA
+
+Два 8-битных ISA-слота на частоте X_SP/5 (~7 МГц). Доступ — через
+DCP-декодер и страницы памяти.
+
+**Управляющие порты ISA (DCP 0xD0–0xDF, 0xF8–0xFF):**
+
+| Бит | Назначение |
+|:---:|-----------|
+| 2 | 0 = ISA memory access, 1 = ISA I/O access |
+| 1 | Выбор слота (0 = slot 0, 1 = slot 1) |
+
+Адресное расширение: `m_isa_addr_ext` (запись через DCP 0x1b) — биты
+расширения адреса для ISA-циклов [sprinter.cpp:1032–1039].
+
+**Memory-маппинг ISA:** При pg3 & 0xF9 == 0xD0 (бит 10 окна W3 = 1,
+BANK_ISA_MASK) обращения к окну W3 (`#C000–#FFFF`) направляются на ISA-шину
+вместо RAM [sprinter.cpp:178–181, 530–532]. Длина — 16 КБ.
+
+**I/O-доступ к ISA:** через тот же DCP-декодер. Устройства устанавливают
+сигнал `m_io_input_wait` = true при совпадении адреса.
+
+> **Примечание:** В MAME есть TODO: «ISA memory slots» — ISA memory-циклы
+> пока не эмулируются [sprinter.cpp:576]. На реальном Sprinter поддержка
+> зависит от прошивки ППЛМ.
+
+Слот 0 обычно занят ZX-Bus-адаптером [sprinter.cpp:26].
+
+---
+
+## 8.7 Кросс-ссылки
+
+- BIOS-функции: `02-bios.md`
+- Клавиатура, мышь: `09-input.md`
+- Звук: `10-sound.md`
+- Порты: `11-ports.md`
+- Акселератор: `06-accel.md`
+- Прерывания: `07-irq.md`

docs/new/09-input.md

@@ -0,0 +1,595 @@
+# 9. Клавиатура и мышь
+
+## 9.1 Общие сведения
+
+Клавиатура Sprinter — AT-совместимая (101 key, PS/2). В Sprinter-1
+дополнительно присутствует ZX-клавиатурная матрица через порт `#FE`
+(скан-код через AT-контроллер преобразуется в ZX-матрицу). Sprinter-2+
+использует AT-клавиатуру через внутренний SIO Z84C15 (канал A).
+
+Мышь — Microsoft Serial Mouse (2 кнопки) через RS-232 на SIO-B (канал B
+Z84C15).
+
+### Порты SIO
+
+| Порт | Назначение |
+|------|-----------|
+| `#18` | SIO-A data — клавиатура |
+| `#19` | SIO-A control — статус/управление |
+| `#1A` | SIO-B data — мышь |
+| `#1B` | SIO-B control — мышь |
+
+Бит 0 порта `#19` — признак прерывания от клавиатуры (используется в IM2
+для различения источников с общим вектором `#FF`).
+
+### Прерывания
+
+Клавиатура и мышь работают в IM2, общий вектор `#FF` (совместно с
+кадровым и CBL). Различение источника — по портам SIO и флаговым битам
+(`07-irq.md §7.2`).
+
+---
+
+## 9.2 Клавиатура: BIOS и ESTEX
+
+### FN_KBD_OUT (BIOS $EA)
+
+Отправляет байт непосредственно на AT-клавиатуру [BIOS_v3.txt:0EAh].
+
+```
+Вход:  C = $EA
+       A = байт команды/данных для AT-клавиатуры
+Выход: нет
+```
+
+Используется для низкоуровневой настройки клавиатуры (LED-индикаторы,
+повтор, задержка).
+
+### ESTEX: функции клавиатуры (30h–37h)
+
+Через `RST 10h` с C=30h–37h [DiskSyscalls.txt:30h–37h].
+
+**WAITKEY (30h):** ждёт нажатия, возвращает код.
+
+```
+Вход:  C = 30h
+Выход: A = код символа
+       D = скан-код
+       E = ASCII-код (0 для функциональных клавиш)
+```
+
+**SCANKEY (31h):** опрос без ожидания.
+
+```
+Вход:  C = 31h
+Выход: A = код символа (0 если нажатий нет)
+       D = скан-код
+       E = ASCII-код
+```
+
+**ECHOKEY (32h):** ждёт + эхо-вывод.
+
+```
+Вход:  C = 32h
+Выход: A = код символа
+       D = скан-код
+       E = ASCII-код
+```
+
+**CTRLKEY (33h):** состояние модификаторов и режимов. libc: `kbd_mod_state()`.
+
+```
+Вход:   C = 33h
+Выход:  C = mode (биты режимов — см. ниже)
+        B = shift (биты зажатых модификаторов)
+```
+
+| Бит C | Режим |
+|-------|-------|
+| 0 | РУС/ЛАТ (0=ЛАТ, 1=РУС) |
+| 1 | NumLock |
+| 2 | ScrollLock |
+| 3 | CapsLock |
+| 4 | Insert |
+
+| Бит B | Модификатор |
+|-------|------------|
+| 0 | Left Shift |
+| 1 | Right Shift |
+| 2 | Ctrl (любой) |
+| 3 | Alt (любой) |
+| 4 | Left Ctrl |
+| 5 | Left Alt |
+| 6 | Right Ctrl |
+| 7 | Right Alt |
+
+**K_CLEAR (35h):** сбросить буфер клавиатуры.
+
+```
+Вход: C = 35h
+```
+
+**K_SETUP (36h):** настройка раскладки. [DiskSyscalls.txt:36h]
+
+```
+Вход: C = 36h
+       A = 0 — получить текущий номер раскладки
+       A = 1 — установить раскладку по номеру из B
+       A = 2 — получить имя текущей раскладки (адрес HL)
+Выход: при A=0: A = номер раскладки
+       при A=2: HL = адрес строки с именем
+```
+
+| Номер | Раскладка |
+|-------|----------|
+| 0 | Английская (US) |
+| 1 | Русская |
+| 2 | Английская (UK) |
+| 3 | Украинская |
+
+Переключение раскладки по Ctrl+Space (если не переназначено).
+
+**TESTKEY (37h):** тест на нажатие (без извлечения из буфера).
+
+```
+Вход:  C = 37h
+Выход: A = код символа (0 если нет)
+       D = скан-код
+       E = ASCII-код
+```
+
+---
+
+## 9.3 Клавиатура: необработанный (raw) доступ
+
+Штатный DSS (WAITKEY/SCANKEY/CTRLKEY) даёт событийный интерфейс —
+нажатия, а не состояния клавиш. Для игр и real-time приложений требуется
+чтение **зажатых клавиш в каждый момент**. Это реализуется через
+перехват SIO-A напрямую в обработчике IM2, минуя DSS.
+
+### 9.3.1 Принцип
+
+1. Установить свой обработчик IM2 (общий вектор `#FF`).
+2. В обработчике читать байты с SIO-A (порт `#18`), декодировать
+   PS/2 Scan Code Set 2, обновлять битовую карту held-состояний.
+3. Основной код по кадровому прерыванию (или раз в кадр) читает карту
+   опросом — без ожидания.
+4. DSS не получает байт с клавиатуры, пока обработчик их забирает.
+   Для восстановления нормального ввода — временно отключить перехват.
+
+### 9.3.2 SIO-A и прерывания
+
+SIO-A (порт данных `#18`, управление `#19`) работает в IM2.
+
+**Инициализация SIO-A** (выполняется BIOS при загрузке, повторно не требуется):
+
+| WR | Значение | Эффект |
+|:--|:---------|--------|
+| WR0 | `0x10` | Сброс RR1 (ошибка) |
+| WR1 | `0x07` | Прерывания по Rx готовности |
+| WR3 | `0xC1` | Rx 8 бит, без CRC |
+| WR4 | `0x44` | ×1 клок, 1 стоп-бит, без паритета |
+| WR5 | `0xEA` | Tx 8 бит, DTR+RTS=1 |
+
+**Различение в IM2:** при входе в обработчик проверить бит 0 порта `#19`.
+Если 0 — прерывание не от SIO-A (кадровое, CBL — пропустить).
+
+### 9.3.3 PS/2 Scan Code Set 2 — протокол
+
+SIO-A передаёт скан-коды PS/2 Set 2. Каждый байт с порта `#18` —
+один байт протокола. Размер сообщения:
+
+| Последовательность | Значение |
+|:------------------|:---------|
+| `<code>` | Make — клавиша нажата (код < 0xF0) |
+| `0xF0 <code>` | Break — клавиша отпущена |
+| `0xE0 <code>` | Extended — расширенная клавиша (стрелки, RAlt, RCtrl) |
+| `0xE0 0xF0 <code>` | Extended break |
+
+Make-байт устанавливает бит клавиши в held-карте.
+Break-байт сбрасывает.
+
+**FSM декодирования (2 состояния):**
+
+```
+PEND_MAKE:
+  получить байт B
+  if B == 0xF0 → переход PEND_BREAK
+  if B == 0xE0 → переход PEND_EXT, Bзап = B
+  иначе → make(B)
+
+PEND_BREAK:
+  получить байт B
+  переход PEND_MAKE
+  if (ext_flag) → break_ext(B); ext_flag = 0
+  иначе → break(B)
+
+PEND_EXT:
+  получить байт B
+  if B == 0xF0 → ext_flag = 1, переход PEND_BREAK_EXT
+  иначе → make_ext(B); переход PEND_MAKE
+
+PEND_BREAK_EXT:
+  получить байт B
+  ext_flag = 0
+  break_ext(B)
+  переход PEND_MAKE
+```
+
+### 9.3.4 Битовая карта held-состояний
+
+Массив 128 байт (1024 бита для кодов 0..1023, расширенные — с битом
+`0x0100`).
+
+Простая реализация:
+
+```asm
+; HL = code (0..0x1FF)
+; IX = base адреса карты
+LD   A, H
+AND  A, 0x07       ; номер бита 8..10
+LD   D, A
+LD   A, L
+RRCA               ; HL/8 (3 сдвига)
+RRCA
+RRCA
+AND  A, 0x1F
+LD   L, A
+LD   A, H
+AND  A, 0x07
+ADD  A, A          ; +8*...
+ADD  A, A
+ADD  A, A
+ADD  A, L
+LD   L, A
+LD   H, 0x00
+ADD  IX, HL        ; IX = &bitmap[code / 8]
+LD   A, D
+INC  A
+LD   B, A          ; B = номер бита в байте + 1
+XOR  A
+SCF                ; carry=1 для make, 0 для break
+RL   A
+DJNZ $-2           ; A = 1 << (code & 7)
+; make: OR (IX), A   ; break: CPL + AND (IX), A
+```
+
+### 9.3.5 Overrun recovery
+
+SIO FIFO глубиной 3 байта. Если обработчик прерывания не успевает
+забрать байты (длинная DI-секция, акселератор), FIFO переполняется —
+RR1 bit5 = 1. С этого момента цепочка make+break нарушена, возможны
+залипшие клавиши.
+
+**Алгоритм восстановления:**
+
+1. Обнаружить overrun (читать SIO RR1, бит 5).
+2. Сбросить held-карту **всех клавиш, кроме**:
+
+   | Код PS/2 | Клавиша | Почему |
+   |:--------:|:--------|:-------|
+   | `0x12` | Left Shift | PS/2 автоповтор — только последняя |
+   | `0x59` | Right Shift | нажатая клавиша. Если сбросить |
+   | `0x14` | Left Ctrl | модификатор, он не восстановится до |
+   | `0x11` | Left Alt | физического отпускания. Игра «теряет» |
+   | `0xE014` | Right Ctrl | шифт/контрол/альт при каждом overrun. |
+   | `0xE011` | Right Alt | |
+
+3. Взвести флаг «был overrun» — основной код может проигнорировать
+   held-состояние на этот кадр.
+
+### 9.3.6 Координация с DSS
+
+Пока обработчик забирает байты с SIO-A, FIFO пуст — DSS не видит
+клавиатуру. Для вызова DSS-функций (консоль, диалоговые окна):
+
+1. Переключить флаг «raw active = 0» в IM2-обработчике.
+2. Обработчик начинает пропускать байты в DSS (JP `0038h` или
+   через штатный трамплин).
+3. После завершения ввода — переключить флаг обратно.
+
+**Внимание:** если обработчик просто перестаёт читать SIO-A, но не
+возвращает управление DSS, порт SIO-A перестанет генерировать
+прерывания (FIFO полон, Rx готов = 0). Для корректной передачи
+управления нужно разрешить DSS-обработчику читать SIO-A.
+
+### 9.3.7 Пример: минимальный raw-обработчик
+
+```asm
+; Флаги: raw_active = 1 — перехватывать, 0 — пропускать в DSS
+; Карта: kbd_held — 128 байт, занулена при старте
+; FSM:   kbd_state — 0=PEND_MAKE, 1=PEND_BREAK, 2=PEND_EXT, 3=PEND_BREAK_EXT
+;        kbd_ext — флаг extended (0/1)
+
+KBD_ISR:
+  ; Проверить, что прерывание от SIO-A
+  IN   A, (#19)     ; SIO-A RR0
+  BIT  0, A         ; бит 0 = прерывание от SIO-A?
+  RET  Z            ; нет — пропустить
+
+  IN   A, (#18)     ; прочитать байт скан-кода
+  BIT  raw_active   ; перехват активен?
+  JP   Z, DSS_IRQ   ; нет — пусть DSS обработает
+
+  ; FSM: текущее состояние в kbd_state
+  LD   HL, kbd_state
+  LD   A, (HL)
+  AND  A, 3
+  JP   Z, .pend_make
+  DEC  A
+  JP   Z, .pend_break
+  DEC  A
+  JP   Z, .pend_ext
+  ; .pend_break_ext
+  LD   (HL), 0      ; → PEND_MAKE
+  LD   A, B         ; код клавиши
+  CALL break_ext
+  EI
+  RETI
+
+.pend_make:
+  LD   A, B         ; байт с SIO-A (уже в B из IN)
+  CP   0xF0
+  JR   Z, .set_break
+  CP   0xE0
+  JR   Z, .set_ext
+  CALL make          ; обычный make
+  LD   (HL), 0       ; остаёмся PEND_MAKE
+  EI
+  RETI
+
+.set_break:
+  LD   (HL), 1       ; → PEND_BREAK
+  EI
+  RETI
+
+.set_ext:
+  LD   (HL), 2       ; → PEND_EXT
+  EI
+  RETI
+
+.pend_break:
+  LD   (HL), 0       ; → PEND_MAKE
+  CALL break
+  EI
+  RETI
+
+.pend_ext:
+  LD   A, B
+  CP   0xF0
+  JR   Z, .set_ext_break
+  CALL make_ext
+  LD   (HL), 0
+  EI
+  RETI
+
+.set_ext_break:
+  LD   (HL), 3       ; → PEND_BREAK_EXT
+  EI
+  RETI
+```
+Размер кода — ~60 байт.
+
+---
+
+## 9.4 Мышь
+
+Драйвер мыши установлен в системном shell Sprinter и доступен через
+SST-вызов `RST 30h`.
+
+### 9.4.1 SST-функции мыши
+
+Вызов: `RST 30h` с A = номер функции. Выход в зависимости от функции
+(см. таблицу).
+
+| № | Назначение | Вход | Выход |
+|:-:|:-----------|:-----|:------|
+| `$00` | Инициализация | A=$00 | — |
+| `$01` | Показать курсор | A=$01 | — |
+| `$02` | Спрятать курсор | A=$02 | — |
+| `$03` | Читать состояние | A=$03 | DE=X, HL=Y, A=buttons (b0=left, b1=right) |
+| `$04` | Переместить курсор | A=$04, DE=X, HL=Y | — |
+| `$05` | Установить границы X | A=$05, DE=min, HL=max | — |
+| `$06` | Установить границы Y | A=$06, DE=min, HL=max | — |
+| `$07` | Вид курсора (текст) | A=$07, DE=sym_and:sym_xor, HL=attr_and:attr_xor | — |
+| `$09` | Загрузить курсор (граф.) | A=$09, IX=pointer | — |
+| `$0B` | Прочитать курсор | A=$0B | IX=pointer (копия) |
+| `$0C` | Чувствительность X | A=$0C, D=value (1..255) | — |
+| `$0D` | Чувствительность Y | A=$0D, D=value (1..255) | — |
+| `$0E` | Прочитать чувств. X | A=$0E | D=value |
+| `$0F` | Прочитать чувств. Y | A=$0F | D=value |
+| `$11` | Уведомить о смене режима | A=$11, D=режим (0=текст, 1=граф-256, 2=граф-16) | — |
+
+**Пример: прочитать состояние мыши в asm:**
+
+```asm
+  LD   A, $03        ; READ
+  RST  30h
+  ; DE = X, HL = Y, A = buttons
+  LD   (mouse_x), DE
+  LD   (mouse_y), HL
+  AND  A, 3
+  LD   (mouse_btn), A
+```
+
+### 9.4.2 Чувствительность
+
+Значение — **делитель**: драйвер считает N raw-шагов мыши, прежде чем
+сдвинуть курсор на 1 пиксель. **Меньше = быстрее** (чувствительнее).
+Рекомендуемое начальное значение: 2 по обеим осям.
+
+```asm
+  LD   A, $0C        ; SET_SENS_H
+  LD   D, 2
+  RST  30h
+  LD   A, $0D        ; SET_SENS_V
+  LD   D, 2
+  RST  30h
+```
+
+### 9.4.3 Порядок инициализации
+
+После загрузки драйвер мыши уже инициализирован shell. Если программа
+начинает «с чистого листа» (без shell), инициализация обязательна:
+
+```asm
+  LD   A, $00        ; INIT — инициализировать драйвер
+  RST  30h
+  LD   A, $05        ; BOUNDS_X: границы экрана
+  LD   DE, 0
+  LD   HL, 319       ; для 320×256
+  RST  30h
+  LD   A, $06        ; BOUNDS_Y
+  LD   DE, 0
+  LD   HL, 255
+  RST  30h
+  LD   A, $01        ; SHOW — показать курсор
+  RST  30h
+```
+
+### 9.4.4 Смена видеорежима
+
+После переключения видеорежима (графический → текстовый и обратно)
+обязательно вызвать `$11`:
+
+```asm
+  LD   A, $11
+  LD   D, 1          ; 0=текст, 1=граф-256, 2=граф-16
+  RST  30h
+```
+
+Иначе драйвер применяет старые координаты, и курсор рисуется
+неправильно.
+
+### 9.4.5 Прямой доступ к SIO-B (raw mouse)
+
+Мышь подключена через SIO-B (порты `#1A`/`#1B`), Microsoft Serial Mouse,
+1200 бод 7E1. Если программа хочет читать мышь напрямую, минуя
+SST-драйвер (например для нестандартного протокола или экономии на
+SST), SIO-B нужно инициализировать самостоятельно:
+
+**Инициализация SIO-B (1200 7E1):**
+
+```asm
+  LD   HL, .sio_init
+  LD   B, 6
+  LD   C, #1B        ; SIO-B control
+  OTIR
+  JR   .done
+.sio_init:
+  DB   #10           ; WR0: сброс RR1
+  DB   #04           ; WR1: прерывания выкл
+  DB   #44           ; WR4: ×1 клок, 1 стоп, без паритета
+  DB   #C1           ; WR3: Rx 8 бит
+  DB   #EA           ; WR5: Tx 8 бит, DTR+RTS=1
+  DB   #15           ; WR0: сброс ошибки + выбран RR1
+.done:
+```
+
+**Чтение байта с мыши (опрос, без прерываний):**
+
+```asm
+  IN   A, (#1B)      ; SIO-B RR0
+  BIT  0, A          ; бит 0 = Rx готов?
+  JR   Z, .no_data
+  IN   A, (#1A)      ; прочитать байт
+  ; обработать ...
+```
+
+**Формат пакета Microsoft Serial Mouse:**
+
+Длина: 3 байта.
+
+| Байт | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+|:----:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| 0 | 1 | 0 | 0 | 0 | L | R | Y7 | Y6 |
+| 1 | 0 | X6 | X5 | X4 | X3 | X2 | X1 | X0 |
+| 2 | 0 | Y5 | Y4 | Y3 | Y2 | Y1 | Y0 | X7 |
+
+- Координаты X/Y — **относительные** (приращения с последнего пакета), знаковые.
+- `X7` — старший бит X (знак), `X6..X0` — младшие.
+- `Y7..Y6` — старшие биты Y, `Y5..Y0` — младшие.
+- `L` — левая кнопка (1 = нажата), `R` — правая.
+
+**Декодирование:**
+
+```asm
+; B = байт 0, C = байт 1, D = байт 2
+; X:
+  LD   A, C          ; байт 1: X6..X0
+  LD   E, A
+  LD   A, D          ; байт 2: X7
+  RLCA
+  RLCA
+  AND  A, 0x80
+  OR   A, E          ; A = X (7 бит + знак)
+  ; знаковое расширение в HL
+  LD   L, A
+  RLCA
+  SBC  A, A
+  LD   H, A          ; HL = X (знаковое 16-бит)
+
+; Y:
+  LD   A, B          ; байт 0: Y7..Y6
+  RLCA
+  RLCA               ; A[1:0] = Y7..Y6
+  AND  A, 0xC0
+  LD   E, A
+  LD   A, D          ; байт 2: Y5..Y0
+  RLCA
+  RLCA               ; A[7:2] = Y5..Y0
+  AND  A, 0xFC
+  OR   A, E          ; A = Y (7 бит + знак)
+  ; знаковое расширение в DE
+  LD   E, A
+  RLCA
+  SBC  A, A
+  LD   D, A          ; DE = Y (знаковое 16-бит)
+
+; Кнопки:
+  LD   A, B
+  AND  A, 0x30       ; биты L (4) и R (5)
+  RRCA               ; A = 0..3
+  RRCA
+  RRCA
+  RRCA
+  LD   (buttons), A
+```
+
+---
+
+## 9.5 Особенности игровой клавиатуры
+
+Документ: `kbd-games.md`. Ниже — ключевые паттерны для реализации.
+
+- **Held-state vs edge-detect:** DSS — событийный (сообщает только момент
+  нажатия). Raw-канал (§9.3) — state-based (зажата/не зажата прямо сейчас).
+  Играм нужен второй.
+- **Sync once per frame:** раз в кадр (по кадровому прерыванию) проверять
+  held-карту. Между кадрами карта обновляется только в IM2-обработчике.
+- **Edge-detect:** для одноразовых действий (прыжок, выстрел) — запоминать
+  предыдущее held-состояние и сравнивать:
+  ```
+  pressed = held & ~prev_held
+  prev_held = held
+  ```
+- **Типоматик:** игнорировать повторные make, пока не придёт break.
+  Реализация: при make — установить бит только если он ещё не был
+  установлен; при break — сбросить.
+- **Автоотмена (reject):** если за кадр нажато больше N клавиш (например
+  4) — игнорировать все (защита от баунса и мусора).
+- **Recovery:** при overrun — очистить held-карту всех клавиш, кроме
+  модификаторов (LShift 0x12, RShift 0x59, LCtrl 0x14, LAlt 0x11,
+  RCtrl 0xE014, RAlt 0xE011).
+
+---
+
+## 9.6 Кросс-ссылки
+
+- Прерывания (IM2, вектор #FF): `07-irq.md §7.2`
+- DSS-функции клавиатуры: `03-dss.md §3.6`
+- BIOS FN_KBD_OUT: `02-bios.md §2.7`
+- Порт клавиатуры `#FE`: `11-ports.md §11.3`
+- Игровая клавиатура: `kbd-games.md`
+- Баги: `12-bugs.md`
+- SIO и порты прерываний: `11-ports.md §11.2`

docs/new/10-sound.md

@@ -0,0 +1,377 @@
+# 10. Звук
+
+## 10.1 Общие сведения
+
+> Документ описывает звуковую подсистему платы **Sp2000** и более новых моделей.
+> Информация о Sprinter-97 не рассматривается.
+
+Звуковая подсистема Sprinter Sp2000 включает три компонента:
+
+| Компонент | Тип | Описание |
+|-----------|-----|----------|
+| GM80C760 (AY-3-8910 совм.) | Музыкальный сопроцессор | 3 голоса + шум + огибающая, эмуляция в ППЛМ |
+| COVOX | 8-битный ЦАП | Прямой вывод сэмплов через порт `#FB`/`#4F` |
+| CBL (COVOX-Blaster) | COVOX с буфером | 256 байт буфера, прерывания, разные режимы |
+
+Весь звук выводится через **16-битный ЦАП TDA1543** (двухканальный, стерео).
+Реально используется 10 бит для одновременного смешивания 8-bit COVOX и AY
+[IvanMak.txt:632–634].
+
+**На Sp2000 все три компонента присутствуют в основной прошивке ППЛМ.**
+CBL включается через порт `#4E` (бит 7 = 1). При выключенном CBL (бит 7 = 0)
+работает обычный 8-bit COVOX [IvanMak.txt:662–666].
+
+## 10.2 GM80C760 (AY-3-8910)
+
+### 10.2.1 Реализация
+
+AY-функция реализована на микросхеме **GM80C760** (ППЛМ ALTERA EP1K30),
+AY-3-8910/8912 совместимая. Это не отдельная дискретная микросхема
+[IvanMak.txt:636–637].
+
+На EP1K30 (Sp2000) реализована **3-я версия** AY. Включает три голоса,
+шум и генератор огибающей (envelope). В формирователе огибающей обнаружена
+небольшая ошибка, детали не документированы [IvanMak.txt:224–229],
+[12-bugs.md §11.2].
+
+### 10.2.2 Порты
+
+| Порт | Назначение |
+|------|-----------|
+| `#BFFD` | AY-8910 — запись номера регистра (address) |
+| `#FFFD` | AY-8910 — чтение/запись данных регистра (data) |
+
+Внутренние номера в карте дешифратора ППЛМ: `90h` (`#BFFD`), `91h` (`#FFFD`)
+[IvanMak.txt:1298–1299].
+
+### 10.2.3 Программирование
+
+Программирование — **стандартное для AY-3-8910/8912**
+[IvanMak.txt:636–637]:
+
+```asm
+; Установить регистр AY
+LD   BC, #BFFD
+OUT  (C), A           ; A = номер регистра (0..15)
+LD   BC, #FFFD
+OUT  (C), A           ; A = значение
+
+; Прочитать регистр AY (3-я версия)
+LD   BC, #BFFD
+OUT  (C), A           ; A = номер регистра
+LD   BC, #FFFD
+IN   A, (C)           ; читать данные
+```
+
+**Регистры AY-3-8910** (стандартные):
+
+| № | Назначение |
+|:-:|-----------|
+| 0 | Частота канала A (младший байт) |
+| 1 | Частота канала A (старшие 4 бита) |
+| 2 | Частота канала B (младший байт) |
+| 3 | Частота канала B (старшие 4 бита) |
+| 4 | Частота канала C (младший байт) |
+| 5 | Частота канала C (старшие 4 бита) |
+| 6 | Период шума |
+| 7 | Микшер (включение каналов и шума) |
+| 8 | Громкость A |
+| 9 | Громкость B |
+| 10 | Громкость C |
+| 11 | Период огибающей (младший байт) |
+| 12 | Период огибающей (старшие 8 бит) |
+| 13 | Форма огибающей |
+| 14 | Порт I/O A (не используется на Sprinter) |
+| 15 | Порт I/O B (не используется на Sprinter) |
+
+**Стерео:** AY имеет два выходных канала, но в стандартной конфигурации
+Sprinter оба канала получают монофонический сигнал.
+
+---
+
+## 10.3 COVOX (8-бит)
+
+### 10.3.1 Порты
+
+| Порт | Назначение |
+|------|-----------|
+| `#FB` | COVOX data (он же порт включения КЭШ-ОЗУ по IN) |
+| `#4F` | COVOX data (альтернативный адрес) |
+
+[IvanMak.txt:642, 1347]
+
+### 10.3.2 Программирование
+
+Простейший вывод сэмплов — последовательная запись байтов в порт `#FB`
+или `#4F`:
+
+```asm
+; Цикл вывода сэмплов (8 бит, моно)
+LD   HL, sample_data
+LD   BC, sample_length
+loop:
+LD   A, (HL)
+OUT  (#FB), A
+INC  HL
+DEC  BC
+LD   A, B
+OR   C
+JR   NZ, loop
+```
+
+### 10.3.3 Конфликт с Fast RAM (КЭШ-ОЗУ)
+
+Порт `#FB` используется **для двух целей**:
+- `OUT (#FB), A` — запись в COVOX
+- `IN A, (#FB)` — включение КЭШ-ОЗУ
+
+Если КЭШ-ОЗУ включено, запись в `#FB` уходит в кэш, а не в COVOX.
+Перед работой с COVOX кэш нужно отключать: `IN A, (#7B)`
+[IvanMak.txt:850–851], [12-bugs.md §11.4].
+
+---
+
+## 10.4 COVOX-Blaster (CBL)
+
+### 10.4.1 Общее описание
+
+**CBL (COVOX-Blaster)** — COVOX с буферным ОЗУ на **256 байт**. Позволяет
+выводить звук поблочно, освобождая процессор для другой работы
+[IvanMak.txt:647], [Parinov.txt:688].
+
+### 10.4.2 Порт управления `#4E`
+
+**Порт `#4E` — 16-битный! Только через `OUT (C),A`** (с `LD BC,004Eh`)
+[Parinov.txt:692–693].
+
+> **Примечание:** IvanMak.txt упоминает его как 8-битный, но Parinov.txt явно
+> указывает 16-битный доступ. Современный код использует `OUT (C),A`.
+
+**Биты порта `#4E`** [Parinov.txt:695–698]:
+
+| Бит | Мнемоника | Назначение |
+|-----|-----------|-----------|
+| 7 | **CBL_ON** | 1 = CBL включён, 0 = обычный COVOX |
+| 6 | **STEREO** | 1 = стерео, 0 = моно |
+| 5 | **16BIT** | 1 = 16-битные сэмплы, 0 = 8-битные |
+| 4 | **IRQ_EN** | 1 = включить прерывания от CBL |
+| 3–0 | **FREQ** | Частота дискретизации (см. таблицу) |
+
+### 10.4.3 Частоты дискретизации
+
+[Parinov.txt:700–718]:
+
+| Код | Частота | Примечание |
+|:---:|---------|-----------|
+| 0 | 16 kHz | старые режимы, **НЕ ИСПОЛЬЗОВАТЬ** |
+| 1 | 22 kHz | старые режимы, **НЕ ИСПОЛЬЗОВАТЬ** |
+| 2–7 | — | зарезервировано |
+| **8** | **7.8125 kHz** | mono/stereo, 8/16-bit |
+| **9** | **10.9375 kHz** | mono/stereo, 8/16-bit |
+| **A** | **15.625 kHz** | mono/stereo, 8/16-bit |
+| **B** | **21.875 kHz** | mono/stereo, 8/16-bit |
+| **C** | **31.25 kHz** | mono/stereo, 8/16-bit |
+| **D** | **43.75 kHz** | mono/stereo, 8/16-bit |
+| **E** | **54.6875 kHz** | mono/stereo, 8/16-bit |
+| **F** | **109.375 kHz** | mono/stereo, 8/16-bit |
+
+> **Важно:** коды 0 и 1 — старые режимы из первых прошивок, несовместимы с
+> новыми режимами (8–F). Использовать только коды 8–F.
+
+### 10.4.4 Режимы и формат данных
+
+[Parinov.txt:767–783]:
+
+| Режим | Нулевой уровень | Размер блока | Формат данных |
+|-------|:---------------:|:------------:|--------------|
+| mono 8-bit | `80h` | 128 байт | `DB 80h, 81h, 7Fh, ...` |
+| mono 16-bit | `0000h` | 256 байт | `DW 0, 1000, -1000, ...` |
+| stereo 8-bit | `80h,80h` | 128 байт | `DB 80h,80h, 81h,80h, ...` (L, R чередуются) |
+| stereo 16-bit | `0000h,0000h` | 256 байт | `DW 0,0, 1000,0, ...` (L, R чередуются) |
+
+Формат данных выбран так, чтобы WAV-файлы можно было пересылать в CBL
+простой `OTIR` [Parinov.txt:791].
+
+### 10.4.5 Буфер CBL и механизм банок
+
+CBL имеет буферное ОЗУ на **256 байт**, организованное как кольцевой буфер
+[Parinov.txt:758–760]:
+
+- Счётчик CBL считает **«назад»** — из-за особенности команды `OUTI`, где `B`
+  уменьшается и попадает на A15..A8.
+- Для 8-битных режимов буфер условно разбит на **две банки по 128 байт**.
+- Для 16-битного режима блок = **256 байт** (весь буфер).
+
+**Механизм работы:**
+
+1. Процессор записывает блок данных (128 байт для 8-бит, 256 байт для 16-бит)
+   в буфер CBL.
+2. Аппаратный счётчик CBL автоматически считывает данные из буфера и
+   отправляет в ЦАП на заданной частоте.
+3. Бит 7 порта `#FE` указывает, какая банка сейчас выводится в ЦАП.
+4. Когда банка переключается — CBL запрашивает следующую порцию данных
+   (через прерывание или polling).
+5. Запрос данных возникает для **каждых 128 байт (256 в 16-битном режиме)**.
+
+### 10.4.6 Порт статуса `#FE`
+
+**Бит 7 порта `#FE`** — запрос данных для CBL [Parinov.txt:720–724]:
+
+| Бит | Назначение |
+|-----|-----------|
+| 7 | **CBL data request** — 1 = CBL запрашивает новую порцию данных |
+| 5 | **Frame sync** — кадровый импульс (4 мс длиной, 20 мс период) |
+
+> **Примечание:** В MAME при выключенном CBL бит 7 порта #FE всегда = 1.
+> Это следует учитывать при разработке обработчика прерываний
+> [`im2_isr_design.md:26–31`].
+
+**Противоречие** [08-io.md §8.3]:
+- IvanMak.txt описывает бит 7 как старший бит счётчика CBL для polling
+  (определение, какая половина буфера выводится).
+- Parinov.txt описывает его как запрос прерывания.
+- Оба описывают одну физическую линию, но в разных режимах (polling vs interrupt).
+
+### 10.4.7 Прерывания и IM2
+
+- При включённых прерываниях CBL (бит 4 порта `#4E` = 1) необходим **режим IM 2**.
+- Если остаться на IM1, DOS-процедура прерываний будет вызываться слишком часто,
+  что вызовет тормоза на высоких частотах [Parinov.txt:762–764].
+- **Вектор прерывания CBL — `#FF`** (как и у клавиатуры, и у кадрового).
+  Отличать — по биту 7 порта `#FE` [`sprinterIntLib.asm:24–26`].
+
+**Обработчик прерываний на IM2:**
+
+```asm
+; Проверка источника
+IN   A, (#FE)
+RLCA                   ; бит 7 → CF
+JR   NC, not_cbl       ; не CBL — на другой обработчик
+
+; CBL запрашивает данные
+LD   BC, 804Fh         ; B = 128 (счётчик), C = 4Fh (порт CBL data)
+LD   HL, next_block
+OTIR                   ; вывести 128 байт в буфер CBL
+...
+```
+
+### 10.4.8 Запись данных в CBL
+
+**Способ 1: OTIR/OUTI через порт `#4F`**
+
+```asm
+LD   BC, 804Fh         ; B = 128 (счётчик), C = #4F (CBL data)
+LD   HL, data_block
+OTIR                   ; вывести 128 байт
+```
+
+**Способ 2: через страницу ОЗУ `#FD` с акселератором**
+
+Страница `#FD`, отображённая в окно `#C000`, аппаратно связана с буфером CBL.
+Для 8-битного режима — записать 128 байт; для 16-битного — 256 байт
+[Parinov.txt:727–731].
+
+```asm
+; Запись блока данных в CBL через страницу #FD с акселератором
+IN   A, (#E2)           ; сохранить текущую страницу W3
+LD   (.save_page), A
+LD   A, #FD
+OUT  (#E2), A           ; W3 = страница CBL
+
+LD   DE, #C000          ; приёмник (CBL buffer)
+LD   B, 0               ; B = 0 → 256 байт (или 128 для 8-bit)
+LD   D,D                ; ACC_ON: включить акселератор
+LD   L,L                ; ACC_CopyBlock_Horizontal
+LD   A, (HL)            ; загрузить байт в буфер акселератора
+LD   (DE), A            ; записать в CBL
+LD   B,B                ; ACC_OFF: выключить акселератор
+
+LD   A, (.save_page)
+OUT  (#E2), A           ; восстановить страницу
+```
+
+### 10.4.9 Полный пример
+
+Из `docs/samples/Пример для CBL.asm` [sprinterIntLib.asm]:
+
+```asm
+; Инициализация IM2
+LD   A, #BE
+LD   I, A              ; таблица векторов по #BE00
+IM   2
+
+; Вектор прерывания CBL = #BEFF
+; (Interrupt_Vector OR 0FFh)
+
+; Включение CBL
+LD   BC, #4E
+LD   A, %10011000b     ; bit7=1 CBL on, bit4=1 IRQ en, bits3-0=1000 = 7.8125 kHz
+OUT  (C), A
+
+; В ISR:
+; IN   A, (#FE)
+; RLCA
+; JR   NC, .NoSound
+; ... копировать 128 байт через страницу #FD с акселератором
+
+; После проигрывания:
+; Установить NumberPage=2, подождать HALT
+
+; Выключение CBL:
+LD   BC, #4E
+LD   A, 0
+OUT  (C), A
+```
+
+### 10.4.10 Известные проблемы
+
+1. **CBL vs Fast RAM:** порт `#FB` используется и для COVOX/CBL, и для
+   включения КЭШ-ОЗУ (см. §10.3.3).
+2. **Щелчок перед первым звуком:** известная проблема при старте CBL
+   [`TODO.md:263`].
+3. **Помехи при движении мыши:** часть тиков прерываний, обслуживающих
+   CBL-насос, уходит на обслуживание мыши [`TODO.md:270–277`].
+4. **Порт #4E — 8-бит vs 16-бит:** IvanMak подразумевает 8-битный,
+   Parinov требует 16-битный `OUT (C),A` (см. §10.4.2).
+5. **MAME: бит 7 порта #FE = 1 при выключенном CBL:** может вызвать
+   ложные срабатывания обработчика (см. §10.4.6).
+
+---
+
+## 10.5 Бипер
+
+Стандартный Spectrum-бипер — бит 3 (в некоторых конфигурациях бит 5)
+порта `#FE`. Выведен через ту же схему TDA1543, что COVOX и AY
+[IvanMak.txt:639–640].
+
+```asm
+; Включить бипер
+LD   A, %00001000       ; бит 3 = 1
+OUT  (#FE), A
+
+; Выключить бипер
+LD   A, %00000000       ; бит 3 = 0
+OUT  (#FE), A
+```
+
+---
+
+## 10.6 SSC (Sprinter Sound Card)
+
+Разрабатывалась, но **не реализована** ни в одной прошивке Sp2000
+из-за большого объёма ПЛМ [IvanMak.txt:763–772].
+
+Параметры проекта:
+- 2 канала
+- 16 восьмибитных голосов
+- 256-байтные Wave-таблицы для каждого голоса
+- 8-битный регулятор амплитуды
+
+---
+
+## 10.7 Кросс-ссылки
+
+- Порты звука: `11-ports.md`
+- Баги AY и CBL: `12-bugs.md`
+- Fast RAM и конфликт с COVOX: `04-memory.md §4.6`
+- 08-io.md (остальной ввод-вывод): `08-io.md`

docs/new/11-ports.md

@@ -0,0 +1,103 @@
+# 11. Карта портов
+
+## 11.1 Системные порты Z84C15 (внутренние)
+
+Эти адреса изменить невозможно — находятся вне ППЛМ [IvanMak.txt:869–870].
+
+| Порт | Назначение | Доступ |
+|------|-----------|--------|
+| `#10` | SIO A data / CTC channel 0 | R/W |
+| `#11` | SIO A control / CTC channel 1 | R/W |
+| `#12` | SIO B data / CTC channel 2 | R/W |
+| `#13` | SIO B control / CTC channel 3 | R/W |
+| `#14` | PIO A data | R/W |
+| `#15` | PIO A control | R/W |
+| `#16` | PIO B data | R/W |
+| `#17` | PIO B control | R/W |
+| `#18` | SIO data channel A (клавиатура) | R/W |
+| `#19` | SIO control channel A (статус клавиатуры) | R/W |
+| `#1A` | SIO data channel B (мышь) | R/W |
+| `#1B` | SIO control channel B (мышь) | R/W |
+| `#1E` | PIO B бит 0 — IRQ от ISA | R |
+| `#1F` | PIO B + джойстик (Kempston) | R/W |
+| `#EE` | CTC channel 2 (альтернативный) | R/W |
+| `#EF` | CTC channel 3 (альтернативный) | R/W |
+| `#F0` | CTC channel 0 (альтернативный) | R/W |
+| `#F1` | CTC channel 1 (альтернативный) | R/W |
+| `#F4` | CTC — альтернативный доступ | |
+
+## 11.2 Управление памятью
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#7FFD` | Основной: W3 page (0–2), RAM/ROM select, lock | IvanMak.txt:1343 |
+| `#1FFD` | Расширенный: W0 page (0–2), turbo, extended RAM, VRAM segment | IvanMak.txt:1345 |
+| `#DFFD` | W1 page select (Pentagon-512) | IvanMak.txt:1346 |
+| `#EFF7` | W2 page select (Pentagon-512) | IvanMak.txt:1346 |
+| `#82` | W0 page (PAGE0) — всегда доступен | IvanMak.txt:1348 |
+| `#A2` | W1 page (PAGE1) — всегда доступен | IvanMak.txt:1348 |
+| `#C2` | W2 page (PAGE2) — всегда доступен | IvanMak.txt:1348 |
+| `#E2` | W3 page (PAGE3) — всегда доступен | IvanMak.txt:1348 |
+
+## 11.3 Видео
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#89` | RGADR (PORT_Y) — номер строки/блока видео-ОЗУ | IvanMak.txt:1349 |
+| `#C9` | RGMOD — страница режима экрана (бит 0: 0/1) | IvanMak.txt:1350 |
+
+## 11.4 Управление конфигурацией/прошивкой
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#FB` | Включение КЭШ-ОЗУ (IN), COVOX data | IvanMak.txt:1351 |
+| `#7B` | Выключение КЭШ-ОЗУ (IN) | Parinov.txt:598 |
+
+## 11.5 Дисковая подсистема
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#0F` | ВГ93 Command/Status (после ремапинга #1F → #0F) | IvanMak.txt:1270 |
+| `#1F` | ВГ93 Command/Status (оригинал, ремапится) | IvanMak.txt:1344 |
+| `#3F` | ВГ93 Track register | IvanMak.txt:1271 |
+| `#5F` | ВГ93 Sector register | IvanMak.txt:1272 |
+| `#7F` | ВГ93 Data register | IvanMak.txt:1273 |
+| `#FF` | ВГ93 Drive Control (write); IRQ/джойстик (read) | IvanMak.txt:1274 |
+| `#BD` | Переключение режима FDD (720K/1.44M) | IvanMak.txt:1347 |
+| `xx50` | IDE Data | Parinov.txt:958 |
+| `xx51` | IDE Error/Features | Parinov.txt:958 |
+| `xx52` | IDE Sector Count | Parinov.txt:958 |
+| `xx53` | IDE Sector Number | Parinov.txt:958 |
+| `xx54` | IDE Cylinder Low | Parinov.txt:958 |
+| `xx55` | IDE Cylinder High | Parinov.txt:958 |
+| `4052h` (R) / `4152h` (W) | IDE Device/Head | Parinov.txt:959 |
+| `4053h` (R) / `4153h` (W) | IDE Status/Command | Parinov.txt:959 |
+| `FFBD` | CMOS data read | BIOS_v3.txt:308 |
+| `BFBD` | CMOS data write | BIOS_v3.txt:308 |
+| `DFBD` | CMOS address write | BIOS_v3.txt:308 |
+
+## 11.6 Звук
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#FB` | COVOX data (also КЭШ-ОЗУ enable) | IvanMak.txt:642 |
+| `#4F` | COVOX/CBL data | IvanMak.txt:642 |
+| `#4E` | CBL control (8/16-bit — см. `10-sound.md §9.4.2`) | IvanMak.txt:662, Parinov.txt:692 |
+
+## 11.7 Джойстик и системные
+
+| Порт | Назначение | Источник |
+|------|-----------|----------|
+| `#FE` | ZX-клавиатурная матрица, бипер, CBL статус | IvanMak.txt:1344 |
+| `#1F` | Джойстик (Kempston) / PIO B | IvanMak.txt:1344 |
+
+## 11.8 Кросс-ссылки
+
+- BIOS-функции: `02-bios.md`
+- DSS-функции: `03-dss.md`
+- Управление памятью: `04-memory.md`
+- Звук (AY, COVOX, CBL): `10-sound.md`
+- Видео/палитра: `05-graphics.md`
+- Прерывания: `07-irq.md`
+- Детали I/O: `08-io.md`
+- Баги: `12-bugs.md`

docs/new/12-bugs.md

@@ -0,0 +1,54 @@
+# 12. Баги BIOS, DSS и железа Sp2000
+
+## 12.1 DRV_VERIFY (54h) не существует
+
+Функция `54h DRV_VERIFY` описана во всей документации BIOS, но в реальности отсутствует — всегда возвращает CF=1.
+
+> [bugs.txt:58–59]: «Нет биосной функции "54h" (DRV_VERIFY) верификации секторов, описанной в документации. Поэтому она всегда возвращает установленный флаг "Carry".»
+
+Источники, содержащие описание несуществующей функции:
+- [BIOS_v3.txt:258–261]
+- [IvanMak.txt:2198–2210]
+
+## 12.2 AY-3-8910 — ошибка в формирователе огибающей
+
+Третья версия AY в ППЛМ Sp2000 содержит ошибку в схеме формирователя огибающей (envelope generator). Детали не документированы.
+
+> [IvanMak.txt:224–229]: «Третья версия схемы AY ... включает в себя ... генератор огибающей. ... В схеме формирователя огибающей обнаружена небольшая ошибка. ... В следующей версии AY предполагается данный недостаток исключить.»
+
+## 12.3 Акселератор — конфликт с прерываниями
+
+При работе акселератора система команд Z80 сильно меняется, что может приводить к сбоям в обработчиках прерываний.
+
+> [IvanMak.txt:844–846]: «Отключение прерываний во время работы акселератора необходимо, так как в этот момент сильно меняется система команд процессора и программа на прерывании не сможет работать нормально.»
+
+Новая прошивка акселератора позволяет работать с прерываниями — при приходе INT акселератор отключается и включается обратно по RETI [IvanMak.txt:846–848]. Без тестирования на реальном железе неизвестно, какая версия прошивки установлена.
+
+## 12.4 Быстрое ОЗУ — конфликт с COVOX
+
+Порт `#FB` используется как для включения КЭШ-ОЗУ (IN), так и для вывода данных в COVOX (OUT). Если КЭШ-ОЗУ включено, запись в COVOX может давать неожиданные результаты.
+
+> [IvanMak.txt:850–851, 642]
+
+Перед вызовом RST или выходом в DOS КЭШ-ОЗУ обязательно отключать (`IN A,(#7B)`).
+
+## 12.5 STA_VID — потеря старшего байта (0A8h?)
+
+> [bugs.txt:33]: «В БИОСе в функции STA_VID (возможно 0A8h) теряется старший байт параметра. В v2.12 функцию рекомендуется вызывать с учетом этого.»
+
+Относится к BIOS v2.12. Не проверялось, исправлено ли в v3.00.
+
+## 12.6 Несовместимость с реальным железом — только MAME
+
+Многие перечисленные баги и квирки зафиксированы в документации, но не подтверждены на реальном Sprinter Sp2000. Все тесты тулчейна выполняются в MAME. Актуальность багов для реального железа неизвестна.
+
+> [TODO.md]: «Проверка на реальном железе — в планах»
+
+## 12.7 Кросс-ссылки
+
+- BIOS v3.00: `02-bios.md`
+- DSS/ESTEX: `03-dss.md`
+- Акселератор: `06-accel.md`
+- Fast RAM: `04-memory.md §4.6`
+- Проектный TODO: `TODO.md`
+- Проектный список багов: `converted/bugs.txt`

docs/new/13-telegram.md

@@ -0,0 +1,169 @@
+# 13. Информация из Telegram-чатов (Sp2022 и развитие Sprinter)
+
+## 13.1 Источники
+
+Данные извлечены из 319 HTML-файлов чатов Telegram, выгруженных из чата по Sprinter (n/w). Обработано 317 602 сообщения, отфильтровано технических — 72 307 (15 МБ текста).
+
+Основные авторы технических сообщений: RomanRom2, KromosS, solegstar, nzeemin, holub.
+
+## 13.2 BIOS 3.06 / DSS 1.71.57
+
+KromosS (23 января 2026): «I am running the DSS 1.71.57 / Bios 3.06».
+
+Зафиксированные версии BIOS:
+- 3.05 — предыдущая стабильная
+- 3.06 — текущая, 23.01.2026
+- Прошивка ППЛМ и ROM собираются через Intel Quartus
+
+BIOS 3.06 собрана из ROM-файла, загружаемого через загрузчик. Процесс сборки:
+1. Конфигурация ППЛМ через Quartus
+2. Сборка ROM-образа (IS28F020 — 256 КБ flash)
+3. Программирование через специальный загрузчик
+
+## 13.3 Эволюция аппаратных платформ
+
+RomanRom2 (11 ноября 2025) подробно описал историю развития Sprinter в 10 пунктах:
+
+| Этап | Платформа | Описание | Период |
+|------|-----------|----------|--------|
+| 1 | Sp2000 | Оригинальная плата, 8 DIP VRAM | 2000–2001 |
+| 2 | Sp2000s | Баг в разводке ALTERA: ISA зеркалированы | ~2001 |
+| 3 | Sp2000s Light | Баг фикс с MGTF, ISA распаяны не полностью | ~2002 |
+| 4 | Sp2021s | Новая ревизия от solegstar | ~2021 |
+| 5 | Sp2022s/d | Собственный дизайн (Zeal Hardware / RomanRom2) | 2022 |
+| 6+ | Sp2024d/du | Планируется, с USB-контроллером | ~2024 |
+
+### Детали:
+
+**Sp2000 (оригинал)**
+- Плата 2000–2001 года
+- ПЗУ 256 КБ, VRAM 256 КБ (8 DIP-микросхем)
+- ALTERA ACEX 1K EP1K30
+
+**Sp2000s**
+- ALTERA-баг: в оригинальной плате зеркально разведены ISA-слоты, на Sp2000s исправлено
+- Новый баг разводки: ISA адреса «перевёрнуты» — при устанавке платы в слот слоты просто не видятся. В Sp2000s Light фикс с MGTF (соединительная плата), один ISA-слот не распаян
+
+**Sp2022 (Zeal Hardware)**
+- Новая разработка на современной элементной базе
+- Варианты: Sp2022s (Sp2000 layout, SMD), Sp2022d (две платы, digitized)
+- SMD-компоненты, технология 2022 года
+- Расширенная память, улучшенное питание
+- Sp2022du — вариант с USB-контроллером (планируется для Sp2024)
+
+**Sp2024**
+- Sp2024d — следующее поколение
+- Sp2024du — с интегрированным USB для клавиатуры/мыши
+- Планируется USB-контроллер
+
+### Sp2022 — модификации
+
+| Модификация | Описание |
+|-------------|----------|
+| sp2022s | SMD, layout аналогичен Sp2000 |
+| sp2022d | Две платы (digitized), расширенная память |
+| sp2022d-black | Чёрная текстолит |
+| sp2022release | Готовая плата для пользователей |
+| sp2022m | Мобильная версия (будущее) |
+| sp2022i | ITX-формфактор |
+| sp2022atx | ATX-формфактор |
+| sp2022t | Новая ревизия |
+| sp2022du | С USB-контроллером |
+
+## 13.4 Изменения компонентов
+
+### ПЗУ и загрузка
+- ROM: IS28F020 (256 КБ Flash, 5V)
+- Загрузка через Quartus → ROM-образ → загрузчик
+- ROM-файлы обсуждаются в чате
+
+### VRAM
+- Оригинал Sp2000: CY7C109D-10VXI (5V, 128K×8)
+- Sp2022: CY7C1019DV33-10VXI (3.3V, 128K×8)
+- Переход на 3.3V логику
+
+### Video-DAC
+- Sp2022: обсуждаются TDA8772 (трипл 8-бит video-DAC) или ADV7120/ADV7125
+- Некоторые платы используют ADV7125 (трипл 10-бит) ???
+
+### CMOS
+- DS12887A (оригинал)
+- На Sp2022 — замена на современный аналог
+
+### КЭШ-ОЗУ
+- W24512 (64K×8) — для Sp2022
+
+### SDRAM
+- Оригинал: 72-pin SIMM
+- Sp2022: SDRAM (DDR) на плате
+
+## 13.5 Аппаратные баги
+
+### Sp2000s — ALTERA routing bug
+При переразводке Sp2000 под Sp2000s допущена ошибка в разводке ALTERA (ACEХ 1K). ISA-адреса оказались «зеркальными» — при установке платы в слот половинка линий данных перевёрнута, из-за чего слоты не видятся CPU. Исправлено на Sp2000s Light с помощью MGTF (мезонинная плата-переходник).
+
+### Sp2000s Light — ISA unsoldered
+На Sp2000s Light один ISA-слот не распаян, второй — через MGTF.
+
+### IDE active short
+В некоторых ревизиях — короткое замыкание на линиях IDE при активном доступе. Требует подтягивающих резисторов.
+
+### FDISK CHS-LBA
+Типовые проблемы с разметкой дисков — ошибки пересчёта CHS в LBA в утилитах FDISK для Sprinter.
+
+## 13.6 MAME-эмуляция
+
+- holub разрабатывает форк MAME для Sprinter
+- Timing issues: Z80 Z84C15 эмулируется не полностью (внутренние PIO/SIO/CTC)
+- Работа над корректной эмуляцией Sp2022
+
+## 13.7 Статистика по платформам
+
+| Платформа | Упоминаний | Период |
+|-----------|-----------|--------|
+| sp2000 | 243 | 2000–2001 |
+| sp2022 | 122 | 2022–2024 |
+| sp2022d | 66 | 2022–2024 |
+| sp2000s | 44 | 2001–2002 |
+| sp2022s | 43 | 2022–2024 |
+| sp2024d | 6 | 2024+ |
+| sp2024du | 4 | 2024+ (план) |
+| sp2022i | 3 | 2022–2024 |
+| sp2022m | 1 | будущее |
+
+## 13.8 Компонентная статистика
+
+| Компонент | Упоминаний |
+|-----------|-----------|
+| Z80 | 1317 |
+| USB | 800 |
+| BIOS v3.xx | 813 |
+| MAME | 496 |
+| DDR | 172 |
+| ACEX | 147 |
+| ALTERA | 115 |
+| CY7C | 82 |
+| Z84C15 | 87 |
+| TDA1543 | 55 |
+| SDRAM | 48 |
+| IS28F020 | 30+ |
+| Quartus | упоминается |
+
+## 13.9 Противоречия с docs/new/
+
+### BIOS v3.06 / DSS 1.71.57
+Основные источники (BIOS_v3.txt, IvanMak.txt) документируют BIOS 3.00, не 3.06. Версия 3.06 обнаружена только в Telegram. DSS 1.71.57 значительно новее, чем 1.60 в документации.
+
+### Sp2022 — новое железо
+Вся документация в docs/converted/, part2/ и reference/ описывает Sp2000 (2000–2001). Sp2022 — полностью новая платформа с современной элементной базой (SMD, 3.3V VRAM, USB, SDRAM). Документация отсутствует.
+
+### Состав BIOS
+Неизвестно, какие функции из IvanMak.txt (HDD, RAM-disk, конфигурационные, портовые) реализованы в BIOS 3.06, а какие нет. Также неизвестно, исправлены ли баги (DRV_VERIFY, AY envelope).
+
+## 13.10 Кросс-ссылки
+
+- Аппаратная архитектура Sp2000: `01-architecture.md`
+- BIOS v3.00: `02-bios.md`
+- Проектный TODO: `TODO.md`
+- Сырые данные: `docs/tg/_messages.jsonl`, `docs/tg/_technical.txt`
+- Фильтр: `docs/tg/_filter.py`

docs/new/INDEX.md

@@ -0,0 +1,112 @@
+# INDEX — сводный указатель документации Sp2000
+
+## Документы
+
+| № | Файл | Содержание |
+|---|------|-----------|
+| 01 | `01-architecture.md` | Общая архитектура: процессор, ППЛМ, конфигурации, обзор памяти/видео/акселератора/звука/ISA/клавиатуры/мыши/дисков/прерываний |
+| 02 | `02-bios.md` | BIOS v3.00: вызовы (RST 8/18h, CALL 3D13h), полная таблица функций, видео/палитра/диск/принтер |
+| 03 | `03-dss.md` | DSS/ESTEX v1.60: файловые функции, диски, память, консоль, коды ошибок |
+| 04 | `04-memory.md` | Память: 4 окна, страницы, порты (#7FFD/#1FFD/#DFFD/#EFF7), EXE-формат, Fast RAM |
+| 05 | `05-graphics.md` | Графика: VRAM, адресация (спектрумовская/графическая), видеорежимы, палитра, shadow RAM |
+| 06 | `06-accel.md` | Акселератор: команды, примеры, скорость, прерывания |
+| 07 | `07-irq.md` | Прерывания: IM1/IM2, INT, CTC, SIO, CBL, цепочка обработчиков |
+| 08 | `08-io.md` | Ввод-вывод: FDD, HDD, CMOS, джойстик, принтер, ISA, карта портов |
+| 09 | `09-input.md` | Клавиатура (BIOS/DSS/raw) и мышь (RST 30h): API, протоколы, прерывания |
+| 10 | `10-sound.md` | Звук: AY-3-8910, COVOX, COVOX-Blaster (CBL), бипер, SSC |
+| 11 | `11-ports.md` | Сводная карта портов: Z84C15, память, видео, диски, звук, конфигурация |
+| 12 | `12-bugs.md` | Баги: DRV_VERIFY, AY envelope, акселератор+IRQ, Fast RAM+COVOX |
+| 13 | `13-telegram.md` | Telegram-чаты: BIOS 3.06, эволюция Sp2000→Sp2022, Sp2022 варианты, Sp2024, аппаратные баги, MAME |
+
+## Противоречия — сводка
+
+### Критические (меняют ABI)
+
+| Тема | Файл | Источники |
+|------|------|-----------|
+| SETWIN2: 39h vs 3Ah | `03-dss.md` | DiskSyscalls.txt vs ProgrammerManual.txt |
+| EXCMDLN subfunc 5: смещения | `03-dss.md` | Все источники дают неверные DE+3/DE+4 |
+
+### Средние
+
+| Тема | Файл | Источники |
+|------|------|-----------|
+| WIN_RESTORE_WIN: C=0B2h (опечатка) | `02-bios.md` | BIOS_v3.txt vs IvanMak.txt |
+| WIN_MOVE_WIN: C=0B2h (опечатка) | `02-bios.md` | IvanMak.txt vs BIOS_v3.txt |
+| WIN_GET_SYM: A=0 обязательно? | `02-bios.md` | Parinov.txt vs BIOS_v3.txt |
+| PIC_SET_PAL: битфилд vs номер | `02-bios.md` | BIOS_v3.txt vs IvanMak.txt |
+| LP_PRINT_SYM: 082h=(131) неверно | `02-bios.md` | Ошибка десятичной аннотации |
+| FN_VERSION: значения BC | `02-bios.md` | BIOS_v3.txt vs IvanMak.txt |
+
+### Низкие
+
+| Тема | Файл | Источники |
+|------|------|-----------|
+| CBL порт 8/16-бит | `10-sound.md` | IvanMak vs Parinov |
+| CBL bit7 #FE: статус vs IRQ | `10-sound.md` | IvanMak vs Parinov |
+| Адресация ВГ93: #7F data reg | `08-io.md` | IvanMak vs Parinov; MAME подтверждает IvanMak |
+| HDD: R/W разные адреса | `08-io.md` | IvanMak vs Parinov; MAME использует единую карту DCP |
+| Джойстик #1F vs #0F | `08-io.md` | IvanMak: ремап #1F → #0F; MAME на Sp2000 отключает |
+
+
+## Кросс-ссылки между документами
+
+```
+01-architecture.md ← 02-bios.md (BIOS call conventions)
+                    ← 04-memory.md (memory overview)
+                    ← 05-graphics.md (video overview)
+                    ← 06-accel.md (accel overview)
+                    ← 07-irq.md (interrupt overview)
+                    ← 08-io.md (disk, joystick, printer, ISA overview)
+                    ← 09-input.md (keyboard, mouse overview)
+                    ← 10-sound.md (sound overview)
+                    ← 11-ports.md (ISA ports)
+
+02-bios.md ← 05-graphics.md (PIC_SET_PAL, SET_MODE)
+           ← 11-ports.md
+           ← 12-bugs.md (DRV_VERIFY)
+
+03-dss.md ← 04-memory.md (SETWIN/SETWIN1/SETWIN2)
+           ← 11-ports.md
+           ← 12-bugs.md
+
+04-memory.md ← 06-accel.md (Fast RAM conflict with accel)
+             ← 11-ports.md
+             ← 03-dss.md (window functions)
+
+05-graphics.md ← 02-bios.md (PIC_SET_PAL, SETVMOD)
+                ← 06-accel.md (accelerator for fast pixel ops)
+                ← 10-sound.md (CBL for video)
+                ← 11-ports.md (RGADR, RGMOD)
+
+07-irq.md ← 10-sound.md (CBL interrupt sources)
+           ← 11-ports.md
+           ← 08-io.md (disk I/O interrupt sources)
+           ← 09-input.md (keyboard, mouse interrupt sources)
+
+08-io.md ← 02-bios.md (printer functions)
+           ← 09-input.md (keyboard, mouse moved here)
+           ← 10-sound.md
+           ← 11-ports.md
+           ← 07-irq.md (mouse IRQ)
+
+11-ports.md → все документы
+```
+
+## Проектные документы (не входят в docs/new/)
+
+| Файл | Связь |
+|------|-------|
+| `memory-management.md` | C-specific memory models (legacy, перекрывается `04-memory.md`) |
+| `fast_ram.md` | Детальный анализ Fast RAM — уточняет `04-memory.md §4.6` |
+| `file-buffering-design.md` | FILE* дизайн — уточняет `03-dss.md` |
+| `im2_isr_design.md` | IM2/ISR дизайн — уточняет `07-irq.md` |
+| `sprite-api-design.md` | Спрайтовое расширение BGI |
+| `kbd-games.md` | Клавиатура в играх — уточняет `09-input.md §9.5` |
+| `libc-reference.md` | API libc |
+| `libc-roadmap.md` | План работ по libc |
+| `libc-split-asm-cases.md` | Правила сплита asm |
+| `libc-headers.md` | Стратегия заголовков |
+| `accel-fill-budget.md` | Бюджет тактов акселератора |
+| `TODO.md` | Roadmap проекта |
+| `bugs/` | Баг-репорт SDCC z80 |

docs/project-reorganization.md

@@ -0,0 +1,287 @@
+# Разделение Sprinter-CC, MAME и приложений
+
+Статус: физическое разделение выполнено; завершаются локальные коммиты,
+проверка документов и публикация Sprinter-CC. Дата обновления: 2026-09-16.
+
+## Цель и границы
+
+Тулкит, эмулятор, примеры и реальные приложения должны разрабатываться и
+версионироваться независимо. Приложение собирается из собственного клона,
+если ему указан только путь к установленному Sprinter-CC. Для запуска в
+эмуляторе дополнительно указывается путь к подготовленной среде MAME либо
+необходимые отдельные пути. Ни соседний репозиторий Examples, ни исходники
+MAME приложению не нужны.
+
+Предлагаемая раскладка на машине разработчика:
+
+```text
+~/Projects/DIY/Z80/Sprinter/
+├── C-Compiler/                  # Sprinter-CC
+├── MAME/                        # fork MAME, сборки и локальная среда запуска
+├── Examples/                    # один Git-репозиторий примеров
+├── Applications/                # каталог без собственного Git
+│   ├── SprPoP/                  # самостоятельный Git-репозиторий
+│   ├── Volkov/                  # самостоятельный Git-репозиторий
+│   └── PoP-Archive/             # архивный проект, если история нужна отдельно
+└── VSCode-Sprinter/             # Git-репозиторий расширения VS Code
+```
+
+Имена `C-Compiler`, `Volkov` и `PoP-Archive` приняты для локальной раскладки;
+адреса Git remote новых репозиториев будут добавлены после создания доступных
+для записи URL.
+Отсутствие remote не мешает сохранить независимую локальную историю. Папка
+`Applications/` не становится общим репозиторием: каждый продукт имеет свою
+историю, релизы, игнорируемые ресурсы и тесты. Физическое расположение рядом
+удобно, но не входит в контракт сборки.
+
+Локальные точки истории после разделения:
+
+| Репозиторий | Split/base | Итоговый локальный commit |
+|---|---|---|
+| Examples | `502d735` | `a76852d` |
+| SprPoP | `4507ba9` | `bd300b3` |
+| Volkov | `a71e3c5` | `3c1956b` |
+| PoP-Archive | `716c639` | `54d0b3d` |
+| VSCode-Sprinter | `68a821e` | `901d91a` |
+| MAME | baseline `b0c4527c`, backend/MCP `fe7ee37a` | `37b89b78` |
+
+Первые пять base-коммитов получены из подготовительного коммита Sprinter-CC
+через `git subtree split`; поэтому их история прослеживается до исходного
+монорепозитория. У выделенных репозиториев пока нет настроенных remote.
+
+## Что принадлежит каждому проекту
+
+| Проект | Что остаётся/переходит | Причина |
+|---|---|---|
+| Sprinter-CC | `bin/`, `runtime/`, `libc/`, `libbgi/`, `lib/`, общие `toolchain/`, `tests/`, `testkit/`, `app.mk`, справочник API, платформенные исследования, `release_docs/`, рецепт SDCC в `third_party/` | Это target SDK, его ABI, инструменты и собственные регрессионные тесты. libc/libbgi пока остаются вместе: их версия и ABI тесно связаны с `sprinter-cc`; дальнейшее выделение возможно после стабильного интерфейса. |
+| MAME | Выделенный `../MAME` со своим Git, изменения драйвера/OSD, патч debugger backend, общие `mamebridge` и `mame_mcp.py`, рецепты stock/sdbg сборок | Изменения ядра и общий транспорт MCP должны проверяться и выпускаться вместе с конкретной ревизией MAME. |
+| Examples | Выделенный `../Examples`: `balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`, `space` и относящиеся к ним ресурсы/документы | Это демонстрации SDK с общей версией. Один репозиторий избегает множества мелких релизов. |
+| SprPoP | Всё из прежнего `applications/SprPoP/`: исходники, конверторы, тесты, собственные ресурсы и планы | Уже почти автономное приложение; оригинальные ресурсы и дальше остаются внешними. |
+| Volkov | Всё из прежнего `applications/Volkov/`: исходники, сценарии MAME, собственные тестовые носители и документы | Продукт и его проверки должны развиваться без дерева тулкита. |
+| PoP-Archive | Прежний `applications/PoP/` как архив PoC/roomtest и исследований | Не смешивать прежнюю историю с активным SprPoP. Архив сохранён самостоятельным рабочим репозиторием. |
+| VSCode-Sprinter | Выделенный `../VSCode-Sprinter`: extension, задачи сборки, конфигурации и тесты клиентской части | У расширения свои версии, упаковка VSIX и цикл обновления. Отладочный Python backend остаётся в SDK. |
+
+`applications/DN/DosNavigator` и вложенные чужие клоны в PoP/Volkov —
+референсы, не Sprinter-приложения. Их не превращать в продуктовые репозитории
+и не коммитить вместе с портами. Локально их можно хранить в `References/`
+или получать по воспроизводимой инструкции с указанием upstream и revision.
+`docs/sources/`, `docs/extra/` и скачанный SDCC также не являются новым
+проектом: это игнорируемые справочные/загруженные материалы. Отдельно
+проверить, какие tracked файлы `third_party/16x16-RPG-characters` нужны
+`rpgwalk` и старому PoP; каждый потребитель получает собственный ресурс или
+явный рецепт его загрузки. Лицензии и происхождение сохранить.
+
+## Контракт сборки и запуска приложения
+
+`SPRINTER_ROOT` указывает на готовый Sprinter-CC. Это единственный внешний
+путь, обязательный для сборки `.exe`, host-тестов и собственных генераторов
+ресурсов. В `app.mk` убрать вывод MAME из `PROJ_ROOT`; оставить
+совместимый alias `PROJ_ROOT := $(SPRINTER_ROOT)` там, где это необходимо на
+переходный период. Приложения проверяют, что по пути существуют
+`bin/sprinter-cc`, `app.mk` и нужные библиотеки, и сообщают ошибку до начала
+сборки. При отсутствии `SPRINTER_ROOT` не угадывать прежнее `../..`: после
+переноса такой путь может случайно указывать на чужой каталог.
+
+`MAME_HOME` — необязательный для сборки путь к подготовленной **среде запуска**
+MAME, а не к его исходникам. Стандартные пути внутри `MAME_HOME` задают
+контракт установленной среды и допускают переопределение из окружения, аргументов `make` или
+локального игнорируемого файла настроек. Если `MAME_HOME` не задан,
+необходимые пути можно указать отдельно; отсутствие обоих источников
+диагностировать в цели запуска, не превращая пустое значение в `/mame.arm`:
+
+```make
+MAME_BIN              ?= $(MAME_HOME)/mame.arm
+MAME_ROMPATH          ?= $(MAME_HOME)/roms
+MAME_DSS_IMAGE        ?= $(MAME_HOME)/IMG/dss171u.img
+MAME_SYSTEM_HDD_IMAGE ?= $(MAME_HOME)/IMG/sp_hdd_sys.chd
+MAME_BIOS             ?= v3.06
+```
+
+`MAME_BIOS` — имя варианта для аргумента `-bios`; ROM-файлы MAME ищет в
+`MAME_ROMPATH`. `MAME_SYSTEM_HDD_IMAGE` добавлен потому, что системный CHD
+нужен существующим сценариям. Если используется CD, NeoGS или второй
+системный носитель, пути к ним сделать отдельными необязательными настройками
+профиля запуска; не прибивать их к Makefile каждого приложения. Уточнить по
+фактическим сценариям, когда нужен `MAME_DSS_IMAGE`: обычный `run`, тест и
+DAP-launch должны брать один источник настройки, даже если конкретный профиль
+не монтирует DSS-дискету.
+
+`MAME_HOME/mame.arm` — стандартный установленный бинарник, а stock/sdbg
+сборки находятся отдельно и выбираются явным `MAME_BIN`. Сборка одного
+варианта не перезаписывает другой и не меняет молча активный бинарник.
+Для запуска с нетипичной установкой можно переопределить каждый путь, не
+копируя ROM/CHD в каталог приложения. Все цели запуска валидируют свои
+фактически используемые файлы и выводят проверенный путь в диагностике.
+
+Собственный `.img`/`.chd`, результаты сценариев, снимки, Lua-скрипты и
+журнал приложения лежат в его `build/` (или другом локальном выходном
+каталоге). MAME получает готовый образ аргументом `-flop1`/`-hard2`. Общие
+`IMG/mc.img` и `IMG/test_hdd.chd` больше не являются выходами сборки
+приложения. `make hdd` готовит локальный образ; `make run` запускает его
+без `mame-link`. Для нескольких сценариев создавать отдельные носители и
+state-каталоги, чтобы один запуск не перезаписывал чужие файлы. Одновременная
+работа нескольких процессов MAME, особенно с MCP bridge, не проверялась и
+не гарантируется; отдельная отложенная задача есть в [TODO.md](TODO.md).
+Конфигурация разработчика не содержит абсолютных личных путей в Git.
+Для `.img` нужен упаковщик из SDK; для `.chd` нынешний `make_hdd.sh`
+дополнительно использует внешние `mtools` и `chdman`. Зафиксировать эти
+host-зависимости и проверять их перед упаковкой. `chdman` можно находить
+через `PATH` либо переопределяемый `CHDMAN_BIN`; путь к исходникам MAME или
+полная установка эмулятора для самой сборки `.exe` не нужны.
+
+Временное состояние MAME (`cfg`, `nvram`, `diff`, `snapshot`, IPC) создаётся
+в отдельном каталоге сессии. Обычный запуск, автотест и DAP используют одну
+функцию/профиль разрешения путей, но разные режимы жизненного цикла и
+разные локальные диски. Не требовать закрывать все чужие процессы MAME по
+общему шаблону: предотвращать конфликт только за конкретный изменяемый
+носитель/IPC-сеанс. Закрытие MAME не должно терять лог и снимки теста.
+
+## Граница MAME и отладки
+
+В репозитории MAME держать точную базовую ревизию fork, stock сборку и
+патченный `sdbg` backend как явную ветку/патч с рецептом сборки. Локальный
+checkout уже имеет отдельный `.git` и remote
+`https://git.snark13.com/snark13/MAME.git`; переносить его как источник,
+не копировать `.git` внутрь нового репозитория тулкита. ROM, DSS, CHD,
+скачанные assets, исполняемые файлы и пользовательский state игнорировать.
+Инструкция установки создаёт стандартный `MAME_HOME`; она проверяет
+наличие/версию файлов, но не распространяет их через Git без отдельной
+проверки лицензий и источника.
+
+В Sprinter-CC остаются `--src-debug`, C/asm-карта, debug package,
+`toolchain/sdbg*`, Python DAP, launcher и Sprinter-специфичный плагин
+`sdbgbridge`. Приложение знает только debug build и свои файлы. Launcher
+принимает `MAME_HOME` и все переопределяемые пути из общего профиля;
+`-pluginspath`, IPC, ожидание DSS, установка точек и `sdbg` протокол — его
+внутренняя работа. Сочетание с родным окном MAME остаётся опцией:
+`osx` на macOS, `qt`/`imgui` на Linux по возможностям сборки. Stock MAME
+можно выбрать для поддержанного штатного backend; режим `sdbg` требует
+соответствующей патченной сборки и должен проверять её до запуска.
+Native Windows launch/attach пока не обещать: текущий host transport зависит
+от Unix sockets/`fcntl` и не прошёл полный Windows сценарий.
+
+Общий `mamebridge` и `mame_mcp.py` остаются с fork MAME, пока используются
+как общие инструменты MAME. Sprinter-специфичному `sdbgbridge` отдельный Git
+репозиторий сейчас не нужен: он версионируется с DAP-протоколом в SDK и
+загружается через `-pluginspath`. Текущий `toolchain/run-mame-mcp.sh` и
+`.codex/config.toml` убрать от предположения `mame/sources/MAME` внутри
+тулкита; для общего MCP использовать путь к установленному MCP-серверу
+MAME, а для Sprinter C-уровня — DAP/session server SDK. Зафиксировать версию
+протокола bridge и совместимость SDK ↔ MAME; несовпадение показывать как
+ошибку, а не как зависание отладки.
+
+Репозиторий VSCode-Sprinter содержит только extension и клиентские тесты.
+По умолчанию он обнаруживает DAP-инструмент из `SPRINTER_ROOT` либо получает
+явную настройку пути; не ищет `toolchain/sdbg_dap.py` в открытом workspace.
+Build task выполняет `make SRC_DEBUG=1 SPRINTER_ROOT=...` в каталоге
+приложения, F5 передаёт debug package, MAME-профиль и собственные data файлы
+адаптеру SDK. Поиск проектов не должен зависеть только от буквального
+`include $(PROJ_ROOT)/app.mk`: определить простой стабильный признак проекта
+или явный каталог в `launch.json`. Версии VSIX, SDK и поддержанной ревизии
+MAME документируются вместе; extension не копирует Python backend.
+
+## Известные связи, которые нужно заменить
+
+| Сейчас | Замена и причина |
+|---|---|
+| Корневые `Makefile` и `app.mk` собирают examples/MAME и пишут общую floppy/HDD под `mame/v306` | В SDK оставить `make`/`size-check`/собственные тесты; упаковщик принимает выходной путь и MAME-профиль. Примеры собираются в Examples, MAME — в MAME. Удаление корневых целей без замены лишило бы пользователя привычного run: документировать новые команды и при необходимости оставить переходные targets с явной подсказкой. |
+| `make host-tests` SDK запускает `applications/SprPoP/tests/host` | Тесты игры вызываются из SprPoP по `SPRINTER_ROOT`; SDK тестирует только SDK. При этом общий `testkit` остаётся SDK. |
+| SprPoP `mame-link` меняет `MAME_HOME/IMG/test_hdd.chd` | `make run` передаёт `build/hdd/sprpop.chd` как `-hard2`; состояние установки MAME не меняется. |
+| Volkov `hdd-p5-viewer` собирает `examples/mdview2` | Сохранить зафиксированный исходный viewer fixture внутри Volkov с лицензией и исходным revision: сценарий проверяет fullscreen/raw/PgDn/EMM и восстановление Commander после реального EXEC; упрощённая заглушка не покрыла бы эти свойства. Локальный fixture уже добавлен. |
+| Volkov `tests/run_mame_hdd.sh` и другие сценарии считают MAME `../../mame/v306` | Принять общие переменные MAME и локальный образ, не менять сценарные Lua-файлы без необходимости. |
+| PoP `roomtest`, `bgtest`, `poc` ищут собственные `toolchain/` и `SDLPoP` через корень SDK | Ввести `POP_ROOT`/`APP_ROOT` внутри PoP и локальные пути к референсам; общие SDK-инструменты оставить по `SPRINTER_ROOT`. Не переносить чужие источники и оригинальные игровые данные в Git. |
+| Examples Makefiles и `rpgwalk/conv_sprites.py` рассчитаны на `../..` и тулкитский `third_party/` | Подключать SDK по `SPRINTER_ROOT`, resource fixture держать рядом с примером либо получать по зафиксированному рецепту. |
+| `toolchain/mame_interactive.py`, `tests/sdbg/run_mame_probe.py`, `sdbg_launcher.py` выводят MAME из `PROJECT_ROOT` | Ввести общий профиль путей, локальные образы и явные аргументы; offline `sdbg-tests` не должен требовать MAME. |
+| `toolchain/make_release.sh` включает `examples/` в архив SDK, а README описывает общий диск | Выпускать Examples отдельно либо собирать составной release по зафиксированной версии Examples; сначала определить контракт релиза, затем изменить архив и обе документации. |
+| Исследовательские docs и код библиотек ссылаются на `applications/PoP/...` и `mame/sources/...` | Сохранять контекст исследования, но заменять рабочие инструкции и относительные ссылки ссылками на соответствующий репозиторий/revision. Архивные наблюдения не удалять. |
+
+## История Git, внешние ресурсы и совместимость
+
+Перед выделением были инвентаризированы незакоммиченные/неотслеживаемые
+файлы в корне и отдельный dirty checkout MAME. Работу DAP, extension,
+MCP-плагина, MAME patch и документов сначала сохранили в подготовительном
+коммите. Истории `examples/`, `applications/SprPoP/`,
+`applications/Volkov/` и PoP выделены через `git subtree split`, после чего
+каждый результат импортирован как `main` самостоятельного Git-репозитория.
+MAME сохранил свою исходную историю и не получил историю родительского SDK.
+
+Новый `.gitignore` каждого проекта покрывает собственные `.exe`, объекты,
+debug packages, носители, снимки, внешние источники и секреты локального
+конфига. Не переносить автоматически вложенные сторонние `.git` как gitlinks
+или submodules. Для ресурсов, которые не входят в Git, указать источник,
+контрольную сумму/revision и способ восстановления; релиз и CI не должны
+молча зависеть от файлов конкретной машины. Если приложению нужен SDK с
+определённым ABI, фиксировать поддерживаемый релиз/commit SDK в его README
+или manifest, не пытаться угадывать его по соседнему каталогу.
+
+Во время перехода обеспечить минимальный период совместимости старой
+структуры: сначала добавить переменные и альтернативные пути, проверить
+старые вызовы, затем переносить деревья. После миграции убрать fallback на
+старые относительные пути и диагностировать устаревшие команды. Это не
+должно оставлять два параллельных способа записи в общий носитель.
+
+## Порядок работ и критерии готовности
+
+1. **Выполнено — зафиксировать текущую базу.** Список tracked/untracked файлов,
+   отдельный Git MAME, лицензии/внешние ресурсы, базовые результаты сборок
+   и smoke-тестов. Сохранить незавершённую отладочную и прикладную работу.
+   Критерий: никакой исходник не теряется при выделении истории.
+2. **Выполнено — стабилизировать контракт SDK.** В `app.mk` разделить build и run,
+   реализовать `SPRINTER_ROOT`, `MAME_HOME` и переопределения, упаковку
+   локального образа с проверкой `mtools`/`chdman`, общий профиль путей
+   и диагностику отсутствующих файлов. Перевести автотесты/launcher без
+   переноса дерева.
+   Критерий: приложение собирается без MAME и запускается с нестандартным
+   `MAME_BIN`/ROM/DSS/System HDD.
+3. **Выполнено локально — подготовить MAME отдельно.** Сохранить fork с точной baseline-revision,
+   stock/sdbg сборки и проверенным способом подготовки `MAME_HOME`.
+   Перенести MAME patch/общий MCP к их владельцу, проверить обоих провайдеров.
+   Критерий: два бинарника существуют одновременно, ROM/CHD и state не
+   коммитятся, patched DAP launch проверен.
+4. **Выполнено — выделить Examples.** Переписать относительные пути и источник RPG
+   графики, определить формат релиза SDK+Examples. Критерий: каждый пример
+   собирается из собственного клона Examples при одном `SPRINTER_ROOT`,
+   локальные диски не затрагивают MAME или соседние проекты.
+5. **Выполнено — выделить приложения по одному.** Сначала SprPoP как наиболее близкий
+   к автономному контракту, затем Volkov с локальным viewer fixture, затем
+   архив PoP с его референсами. Переписать тесты и run-скрипты, сохраняя
+   их документы и историю. Критерий: каждый продукт собирается и проходит
+   доступные host/MAME проверки из изолированного клона без Examples и
+   других приложений.
+6. **Реализовано; остаётся ручная проверка установленного VSIX после разделения — выделить extension.** Научить VS Code находить SDK DAP независимо от
+   workspace, запускать build/run/debug приложения и показывать ошибки
+   разрешения путей/версий. Проверить VSIX в отдельном workspace SprPoP
+   или Volkov, а не только в `C-Compiler`. Критерий: F5 строит debug package,
+   ждёт DSS, доходит до `main`, принимает breakpoint/logpoint и клавиатуру;
+   опция родного окна MAME работает на macOS. Windows остаётся явно
+   ограниченной до отдельной реализации host transport.
+7. **Завершается — очистить SDK и документы.** Заменить корневые цели, release-скрипт,
+   README, `AGENTS.md`, инструкции автотеста/отладки и рабочие ссылки.
+   Проверить `make`, `make -C libc`, `make -C libbgi`, `make size-check`,
+   SDK host/sdbg tests и отдельные проекты. Критерий: в SDK нет tracked
+   приложений/примеров и игнорируемого вложенного MAME; инструкции используют
+   новые пути, а архивные исследования остаются доступны.
+
+## Проверка реализации на 2026-09-16
+
+Успешно выполнены сборка SDK (`make`), отдельные сборки libc/libbgi,
+создание `build/media/toolkit-tests.img`, release-smoke, 36 Python-тестов
+source debugger (один platform skip), 12 тестов extension, все Examples,
+SprPoP в обычном и `SRC_DEBUG=1` режимах с локальным CHD, 17 host-наборов
+SprPoP, Volkov и PoP-Archive PoC. Живые последовательные DAP-прогоны
+подтвердили patched `sdbg`, stock MAME с `osx`, клавиатурный ввод,
+`SDBG_LOG` в обеих консолях и запуск SprPoP с собственного `hard2` до
+`main`.
+
+`make size-check` пока не принят: текущий baseline показывает 12 старых
+увеличений (обычно +9 байт, `openenv` +188) и несколько исчезнувших прежних
+тестов. Реорганизация не меняла libc/libbgi, поэтому эталон автоматически не
+перезаписывался; расхождения нужно разобрать отдельно. После разделения ещё
+нужна ручная проверка установленного VSIX в чистом workspace. Несколько
+одновременных MAME, маршрутизация MCP между ними и Windows transport остаются
+явно непроверенными сценариями.
+
+Каждый этап заканчивается проверкой в отдельном репозитории и просмотром Git
+diff. Новые Git remote для выделенных репозиториев и публикация их релизов
+остаются отдельной задачей. MAME пока не публикуется: существующий `origin`
+доступен только для чтения. Sprinter-CC публикуется в своём прежнем remote.

docs/samples/balls/balls.asm

@@ -0,0 +1,721 @@
+;-------------------------------------------------------------------------------
+; Balls mini-demo
+; (c) Sayman 2015
+;-------------------------------------------------------------------------------
+; ïðîöåäóðà ìîäóëÿ ñîâñåì íå îïòèìàëüíà, âçÿòà èç èñõîäíèêà áèáëèîòåêè C.
+;-------------------------------------------------------------------------------
+
+tbuf_addr:	equ 4000h
+screen_addr:	equ 0xc000
+
+
+balls_pgn	equ 1
+bgspr_pgn	equ 6
+savescr_pgn	equ 6
+tbuf_pgn	equ 1
+
+MAX_BALLS	equ 32		; ïðè 96 øàðèêàõ ñòðóêòóðà balls_cfg áóäåò 576 áàéò
+
+balls_pal_size	equ 128
+bgspr_pal_size	equ 128
+
+balls_struct:
+.x		equ 0		; u16_t
+.y		equ 2		; u8_t
+.dx		equ 3		; i8_t
+.dy		equ 4		; i8_t
+.radius		equ 5		; u8_t
+
+balls_struct_bkp:
+.x		equ 0		; u16_t
+.y		equ 2		; u8_t
+
+
+
+		include "dss.inc"
+		include "head.inc"
+
+
+entry:		push ix
+		call init
+		call read_bgspr
+		ld a,(pg_tbl.tbuf)
+		out (cpu_w1),a
+		ld a,(tmp_hndl)
+		call close
+		call read_bgpal
+		call read_balls_spr
+		call read_balls_pal
+		call vinit
+		call balls_reindex
+		call balls_init
+		call draw_bgspr
+		call CopySCR_1to2
+		ld a,0xc0
+		out (port_y),a
+		ld a,(pg_w3)
+		out (cpu_w3),a
+		call balls_main
+		sub a
+		jp quit0
+		
+
+
+		include "misc.asm"
+		include "math.inc"
+
+
+rand16	ld	de,.seed		; Seed is usually 0
+	ld	a,d
+	ld	h,e
+	ld	l,253
+	or	a
+	sbc	hl,de
+	sbc	a,0
+	sbc	hl,de
+	ld	d,0
+	sbc	a,d
+	ld	e,a
+	sbc	hl,de
+	jr	nc,.rand
+	inc	hl
+.rand	ld	(rand16+1),hl
+	ret
+
+.seed:	dw 0
+
+
+
+inc_pg1:	ld a,(ix)
+		out (cpu_w1),a
+		inc ix
+		ret
+
+inc_pg3:	ld a,(ix)
+		out (cpu_w3),a
+		inc ix
+		ret
+
+
+init:		ld c,balls_pgn
+		ld hl,pg_tbl.balls
+.loop0:		push bc
+		push hl
+		call gmem
+		pop hl
+		pop bc
+		jp c,gmem_err
+		ld (hl),a
+		inc hl
+		dec c
+		jr nz,.loop0
+		ld c,bgspr_pgn
+.loop1:		push bc
+		push hl
+		call gmem
+		pop hl
+		pop bc
+		jp c,gmem_err
+		ld (hl),a
+		inc hl
+		dec c
+		jr nz,.loop1
+		ld c,savescr_pgn
+.loop2:		push bc
+		push hl
+		call gmem
+		pop hl
+		pop bc
+		jp c,gmem_err
+		ld (hl),a
+		inc hl
+		dec c
+		jr nz,.loop2
+		ld c,tbuf_pgn
+.loop3:		push bc
+		push hl
+		call gmem
+		pop hl
+		pop bc
+		jp c,gmem_err
+		ld (hl),a
+		inc hl
+		dec c
+		jr nz,.loop3
+		ex af,af
+		in a,(cpu_w1)
+		ld (pg_w1),a
+		in a,(cpu_w3)
+		ld (pg_w3),a
+		in a,(port_y)
+		ld (old_y),a
+		ex af,af
+		out (cpu_w1),a
+		ret
+
+
+
+set_scr_w3:	out (cpu_w3),a
+		ret
+
+set_scr_w1:	out (cpu_w1),a
+		ret
+
+
+
+vinit:		ld a,81h
+		ld bc,50h
+		rst 10h
+		call cls
+		call set_global_pal
+		call CopySCR_1to2
+		ld a,norm_scr
+		call set_scr_w3
+		ret
+
+
+CopySCR_1to2:	sub	a
+		out	(port_y), a
+		ld	hl, 0xc000
+		ld	de, 0xc140
+		ld	bc, 320
+		ld	d, d
+		ld	a, 0		; 256 bytes
+		ld	a, a
+;		ldir
+.loop:		REPT 64
+		ldi
+		ENDM
+		jp pe,.loop
+	
+		ld	b, b
+		ld	hl, 0xc3E0
+		ld	de, 0xc3E4
+;		ld	bc, 0004h
+		ld	a, a
+                ldi
+                ldi
+                ldi
+                ldi
+;		ldir	
+		ld	b, b
+		ret
+
+
+cls:		ld hl,0xc3E0
+		ld de,0
+		ld d,d
+		ld a,0
+		ld b,b
+		ld b,4
+.loop1:		ld a,d
+		out (port_y),a
+		ld e,e
+		ld (hl),e
+		ld b,b
+		inc hl
+		djnz .loop1
+
+		ld hl,0xc000
+		ld de,0
+		ld bc,320
+		ld d,d
+		ld a,0
+		ld b,b
+.loop2:		ld a,d
+		out (port_y),a
+		ld e,e
+		ld (hl),e
+		ld b,b
+		inc hl
+		dec bc
+		ld a,b
+		or c
+		jr nz,.loop2
+		ret
+
+set_global_pal:	ld bc,0ffa4h
+		ld hl,pal
+                ld de,0
+                sub a
+		rst 8
+                ret
+
+
+
+read_bgspr:	ld hl,data_files.bgspr
+		push hl
+		call open
+		pop hl
+		ld (open_err.err_file+1),hl
+		jp c,open_err
+		ld (rd_err.err_file+1),hl
+		ld (tmp_hndl),a
+		ld ix,pg_tbl.bgspr
+.loop:		call inc_pg1
+		ld a,(tmp_hndl)
+		ld hl,tbuf_addr
+		ld de,16320
+		push ix
+		call read
+		pop ix
+		jp c,rd_err
+		or a
+		ret nz
+		jr .loop
+
+read_bgpal:	ld hl,data_files.bgpal
+		push hl
+		call open
+		pop hl
+		ld (open_err.err_file+1),hl
+		jp c,open_err
+		ld (rd_err.err_file+1),hl
+		ld (tmp_hndl),a
+		ld hl,pal
+		ld de,bgspr_pal_size*4
+		call read
+		jp c,rd_err
+		ld a,(tmp_hndl)
+		call close
+		ret
+
+read_balls_spr:	ld hl,data_files.balls
+		push hl
+		call open
+		pop hl
+		ld (open_err.err_file+1),hl
+		jp c,open_err
+		ld (rd_err.err_file+1),hl
+		ld (tmp_hndl),a
+		ld hl,balls_spr
+		ld de,1024
+		call read
+		jp c,rd_err
+		ld a,(tmp_hndl)
+		call close
+		ret
+
+read_balls_pal:	ld hl,data_files.balls_pal
+		push hl
+		call open
+		pop hl
+		ld (open_err.err_file+1),hl
+		jp c,open_err
+		ld (rd_err.err_file+1),hl
+		ld (tmp_hndl),a
+		ld hl,pal+bgspr_pal_size*4
+		ld de,balls_pal_size*4
+		call read
+		jp c,rd_err
+		ld a,(tmp_hndl)
+		call close
+		ret
+
+
+balls_reindex:	ld hl,balls_spr
+		ld c,128
+		ld de,1024
+.loop0:		ld a,(hl)
+		inc a
+		jr z,.loop1
+		dec a
+		add a,c
+		ld (hl),a
+.loop1:		inc hl
+		dec de
+		ld a,e
+		or d
+		jr nz,.loop0
+		ret
+
+
+balls_init:	ld hl,balls_cfg
+		ld de,balls_cfg+1
+		ld bc,MAX_BALLS*6
+		xor a
+		ld (hl),a
+		ldir
+		ld hl,balls_bkp
+		ld de,balls_bkp+1
+		ld bc,MAX_BALLS*3
+		xor a
+		ld (hl),a
+		ldir
+		ld iy,MAX_BALLS
+		ld ix,balls_cfg
+.loop0:		ld de,320-16		; ðàçìåðû êàæäîãî øàðèêà 16íà16
+		push de
+		call rand16		; áåð¸ì ñëó÷àéíóþ êîîðäèíàòó X
+		pop de
+		inc hl
+		push de
+		call lmod
+		pop de
+		ex de,hl
+.next0:		ld (ix+balls_struct.x),e
+		ld (ix+balls_struct.x+1),d
+		ld de,256-16
+		push de
+		call rand16
+		pop de
+		inc hl
+		push de
+		call lmod
+		pop de
+		ex de,hl
+.next1:		ld (ix+balls_struct.y),e
+		call rand16
+		ld a,l
+		and 1
+		jr nz,.next2
+		ld a,-1
+.next2:		ld (ix+balls_struct.dx),a
+		call rand16
+		ld a,l
+		and 1
+		jr nz,.next3
+		ld a,-1
+.next3:		ld (ix+balls_struct.dy),a
+		ld de,6
+		add ix,de
+		dec iy
+		ld a,iyl
+		or iyh
+		jr nz,.loop0
+		ret
+
+
+draw_bgspr:	ld ix,pg_tbl.bgspr
+		call inc_pg1
+		ld hl,tbuf_addr
+		ld c,51
+		ld a,0
+.loop:		ld de,screen_addr
+		out (port_y),a
+		ex af,af
+		di
+		ld d,d
+		ld a,0
+		ld l,l
+		ld a,(hl)
+		ld (de),a
+		ld b,b
+		inc h
+		inc d
+		ld d,d
+		ld a,64
+		ld l,l
+		ld a,(hl)
+		ld (de),a
+		ld b,b
+		ld a,64
+		add a,l
+		ld l,a
+		adc a,h
+		sub l
+		ld h,a
+		dec c
+		call z,nextpage
+		ex af,af
+		inc a
+		jr nz,.loop
+		ei
+		halt
+		di
+		ret
+
+nextpage:	call inc_pg1
+		ld hl,tbuf_addr
+		ld c,51
+ 		ret
+
+
+balls_main:
+
+.loop1:		ld iy,MAX_BALLS
+		ld ix,balls_cfg
+		call save_coords
+		push ix
+		push iy
+.loop0:		ld e,(ix+balls_struct.x)
+		ld d,(ix+balls_struct.x+1)
+		ld hl,320-16
+		call check_x
+		ld c,(ix+balls_struct.y)
+		ld hl,256-16
+		call check_y
+		ld a,(ix+balls_struct.dx)
+		ld h,0
+		ld l,a
+		rlca
+		jr nc,.a1
+		dec h
+.a1:		rrca
+		add hl,de
+		ex de,hl
+		ld (ix+balls_struct.x),e
+		ld (ix+balls_struct.x+1),d
+		ld a,(ix+balls_struct.dy)
+		add a,c
+		ld (ix+balls_struct.y),a
+		ld de,6
+		add ix,de
+		dec iy
+		ld a,iyl
+		or iyh
+		jr nz,.loop0
+		pop iy
+		pop ix
+
+		ld a,norm_scr|trans_scr|tmp_scr
+		call set_scr_w3
+
+.loop2:		ld hl,balls_spr
+		ld a,iyl
+		and 3
+		ld e,(ix+balls_struct.x)
+		ld d,(ix+balls_struct.x+1)
+		ld c,(ix+balls_struct.y)
+		call draw_balls
+		ld de,6
+		add ix,de
+		dec iy
+		ld a,iyl
+		or iyh
+		jr nz,.loop2
+
+		ei
+		halt
+		di
+		in a,(rgmod)
+		and 1
+		xor 1
+		out (rgmod),a
+
+		ld a,norm_scr
+		call set_scr_w3
+		ld iy,MAX_BALLS
+		ld ix,balls_bkp
+.loop3:		ld e,(ix+balls_struct.x)
+		ld d,(ix+balls_struct.x+1)
+		ld c,(ix+balls_struct.y)
+		call restore_bg
+		ld de,3
+		add ix,de
+		dec iy
+		ld a,iyl
+		or iyh
+		jr nz,.loop3
+
+.blah:		call check_key
+		jr c,._ret_
+		jp .loop1
+._ret_:		ret
+
+save_coords:	push ix
+		push iy
+		ld hl,balls_bkp
+.loop:		ld e,(ix+balls_struct.x)
+		ld d,(ix+balls_struct.x+1)
+		ld c,(ix+balls_struct.y)
+		ld (hl),e
+		inc hl
+		ld (hl),d
+		inc hl
+		ld (hl),c
+		inc hl
+		ld de,6
+		add ix,de
+		dec iy
+		ld a,iyh
+		or iyl
+		jr nz,.loop
+		pop iy
+		pop ix
+		ret
+
+
+restore_bg:
+		in a,(rgmod)
+		or a
+		ld a,0xc0
+		jr nz,.restore_to_0
+		ld a,0xc1
+		jr .restore_to_1		
+.restore_to_0:	add a,d
+		ld d,a
+		ld h,d
+		ld l,e
+		jr .restore
+.restore_to_1:	add a,d
+		ld d,a
+		ld a,0x40
+		add a,e
+		ld e,a
+		adc a,d
+		sub e
+		ld d,a
+		ld h,d
+		ld l,e
+.restore:	ld a,c
+		out (port_y),a
+		ld b,16
+		di
+.loop:		ld d,d
+		ld a,16
+		ld l,l
+		ld a,(hl)
+		ld (de),a
+		ld b,b
+		in a,(port_y)
+		inc a
+		out (port_y),a
+		djnz .loop
+		ret
+		
+		
+
+draw_balls:	ld b,a
+		in a,(rgmod)
+		or a
+		ld a,0xc1
+		jr z,.draw_to_1			; åñëè âêëþ÷¸í 0é ýêðàí, ðèñóåì íà 1é
+		ld a,0xc0			; èíà÷å (1é) ðèñóåì â 0é
+.draw_to_0:	add a,d
+		ld d,a
+		jr .draw
+.draw_to_1:	add a,d
+		ld d,a
+		ld a,0x40
+		add a,e
+		ld e,a
+		adc a,d
+		sub e
+		ld d,a
+
+.draw:		ld a,b
+		add a,a
+		add a,a
+		add a,a
+		add a,a
+		add a,l
+		ld l,a
+		adc a,h
+		sub l
+		ld h,a			; íîìåð ñïðàéòà*256 = àäðåñ ñïðàéòà â êàðòèíêå
+		ld a,c
+		out (port_y),a
+		ld b,16
+		di
+.loop:
+		ld d,d
+		ld a,16
+		ld l,l
+		ld a,(hl)
+		ld a,a
+		ld (de),a
+		ld b,b
+		ld a,c
+		out (port_y),a
+		ld a,l
+		add a,64
+		ld l,a
+		ld a,0
+		adc a,h
+		ld h,a
+		inc de
+		djnz .loop
+		ret
+
+check_x:	ld a,e
+		or d
+		jr z,.next0
+		sbc hl,de
+		jr z,.next1
+		jr c,.next1
+		ret
+.next0:		ld a,1
+		ld (ix+balls_struct.dx),a
+		ret
+.next1:		ld a,-1
+		ld (ix+balls_struct.dx),a
+		ret
+
+
+check_y:	ld a,c
+		or a
+		jr z,.next0
+		ld a,l
+		sub c
+		jr z,.next1
+		jr c,.next1
+		ret
+.next0:		ld a,1
+		ld (ix+balls_struct.dy),a
+		ret
+.next1:		ld a,-1
+		ld (ix+balls_struct.dy),a
+		ret
+
+
+sync:		ei
+		halt
+		di
+		ret
+
+
+check_key:	push hl
+		push de
+		push bc
+		push ix
+		push iy		
+		ld c,scankey
+		rst 10h
+		pop iy
+		pop ix
+		pop bc
+		pop de
+		pop hl
+		xor 1bh			; êîä Esc...
+		ret nz
+.esc:		scf
+		ret
+		
+
+
+
+pg_tbl:
+.balls:		db 0
+.bgspr:		ds 6
+.savescr:	ds 6
+.tbuf:		db 0
+
+pg_w0:		db 0
+pg_w1:		db 0
+pg_w2:		db 0
+pg_w3:		db 0
+old_y:		db 0
+
+
+data_files:
+.balls:		db "balls.spr",0
+.balls_pal:	db "balls.act",0
+.bgspr:		db "bgspr.spr",0
+.bgpal:		db "bgspr.act",0
+
+tmp_hndl:	db 0
+
+
+open_err_str:	db "Can't open file ",0
+read_err_str:	db "Failed to read file ",0
+gmem_err_str:	db "PANIC: Can not allocate memory!",cr,lf,0
+vm_err_str:	db "PANIC: Unable to set videomode!",cr,lf,0
+
+crlf0:		db " ",cr,lf,0
+
+
+pal:		equ ($/80h)*80h+80h
+balls_spr:	equ ((pal+1024)/80h)*80h+80h
+balls_cfg:	equ ((balls_spr+1024)/80h)*80h+80h
+balls_bkp:	equ (((balls_cfg)+6*MAX_BALLS)/80h)*80h+80h

docs/samples/balls/balls.spr

@@ -0,0 +1,58 @@
+�������������������������������������������������������						���������������
+
+
+
+
+����					���������
+
+
+
+
+
+
+
+
+��			������
+
+
+
+
+
+
+��			���
+
+
+
+
+			
+
+
+			
+
+
+		
+
+
+
+	
+



+
+	
+


+
+	���
+

+
+��������
+


+
+��	���������
+





+
+�������������������
+
+
+������	������������������������
+
+
+����������			���������������

docs/samples/balls/balls.txt

@@ -0,0 +1,38 @@
+Демка была написана как альтернатива аналогичной на evo-sdk (язык C) для zx-evo,
+но написано на асме. При этом так же пока писал, разбирался в особенностях работы
+графических режимов. Содержание архива:
+
+balls.asm - исходник
+dss.inc - различные константы
+head.inc - заголовок для формирования exe файла
+misc.inc - некоторые "прочие" процедурки.
+math.inc - математика, причём тормозная (сдёрнутая из исходника либы для HTC)
+make.bat - собиралка. Использование как make src_name.
+sjasm.exe - компилятор. Этот меня устраивает.
+balls.exe - основной exeшник. На экране 32 шарика.
+balls64.exe - 64 шарика.
+balls128.exe - 128 шариков.
+balls225.exe - 225 шариков.
+balls.ect - файл с палитрой для шариков. Хранится в формате 32бита. Выдернуто
+            из заголовка для bmp шариков.
+balls.spr - собсвтенно файл с шариками (спрайты). Ранее это был обычный bmp.
+bgspr.act - палитра для фоновой картинка. Так же 32бита выдернутые из bmp.
+bgspr.spr - фоновая картинка, тоже бывшая bmp.
+
+Спрайт шариков имеет разрешение 64*16 (т.е. 4 шарика в линию, каждый шарик
+16*16), каждый шарик по 32 цвета, т.е. сама картнка с шариками 128 цветов.
+Фоновая картинка имеет разрешение 320*256, 128 цветов.
+Чтобы получить эти файлы я в фотошопе что нужно было вырезал, отмасштабировал,
+"перецветовал" в 8бит на точку, 128 цветов. Шарики собирал по отдельности из
+фоновой картинки (просто вырезал из оригинального файла "молекулы", масштабировал,
+собирал в одну картинку и потом извращался с цветами. Потом выдернул палитру
+через winhex для шариков и фона из их bmp файлов, а из самих bmp потом вырезал
+весь заголовок, оставив только данные спрайтов.
+Можно спокойно подсунуть свои спрайты фона и шариков.
+В демке есть процедура переиндексирования цветов. Первым файлом загружается
+фоновая картинка и палитра. Цвета в файле имеют индексы от 0 до 7fh.
+Шарики загружаются уже после. Поскольку палитра 256 цветов, а первые 128 уже
+заняты под фон, то после загрузки спрайта шариков я делаю переиндексацию. Просто
+по всему размеру файла если цвет != 0xff, тогда цвет +=128.
+
+за тормоза в математике сильно не пинать!!!

docs/samples/balls/dss.inc

@@ -0,0 +1,68 @@
+;-------------------------
+;dss functions defines
+;file functions
+fopen		equ 11h
+fclose		equ 12h
+fread		equ 13h
+fwrite		equ 14h
+move_fp		equ 15h
+fgetattr	equ 16h
+fgetdt		equ 17h
+fsetdt		equ 18h
+fcreate		equ 0ah
+fcreaten	equ 0bh
+chdir		equ 1dh
+curdir		equ 1eh
+;memory functions
+setwin1         equ 39h
+getmem		equ 3dh
+setmem		equ 3fh
+freemem		equ 3eh
+;keyb functions
+waitkey		equ 30h
+scankey		equ 31h
+quit            equ 41h
+getarg		equ 43h
+;vmode functions
+setvmode	equ 50h
+getvmode	equ 51h
+selvpage	equ 54h
+;screen and text functions
+pchar		equ 5bh
+pchars		equ 5ch
+;other
+getver		equ 0
+;end dss defines
+;-------------------------
+;hardware defines
+port_y		equ 89h		;port for Y coord
+_320p		equ 81h		;320 pixels mode
+rgmod		equ 0c9h
+border		equ 0feh
+rgscr		equ 0e9h
+rgacc		equ 0a9h
+
+norm_scr	equ 50h
+;trans_scr	equ 54h
+trans_scr	equ 00001000b
+tmp_scr		equ 00000100b
+
+
+e_cache		equ 0fbh
+d_cache		equ 7bh
+sys_port3c	equ 3ch
+sys_port7c	equ 7ch
+
+cpu_w0		equ 82h		;cpu window 0 = addr 0000h
+cpu_w1		equ 0a2h	;... 1 = 4000h
+cpu_w2		equ 0c2h	;... 2 = 8000h
+cpu_w3		equ 0e2h	;... 3 = 0c000h
+;end hardware defines
+;-------------------------
+;characters
+cr		equ 0dh
+lf		equ 0ah
+tab		equ 9
+space		equ 20h
+;------------------------
+

docs/samples/balls/head.inc

@@ -0,0 +1,20 @@
+;		.Z80
+;		ASEG
+;		org 100h
+		org 8100h-512
+
+		db "EXE"
+		db 0
+		dw 200h
+		dw 0
+		dw 0
+		dw 0
+		dw 0
+		dw 0
+		dw entry
+		dw entry
+		dw 0bfffh
+		ds 490
+		
+;		.PHASE 8100h
+		   

docs/samples/balls/make.bat

@@ -0,0 +1,20 @@
+@echo off
+if "%1" == "" goto error
+
+if EXIST %1.exe (
+	del %1.exe
+)
+sjasm.exe -L %1.asm %1.exe %1.lst
+if errorlevel 1 goto ERR
+echo Ok!
+goto END
+
+:ERR
+del %1.exe
+pause
+echo ®è¨¡ª¨ ª®¬¯¨«ï樨...
+goto END
+
+:error
+echo usage: make sourcefile
+:END

docs/samples/balls/math.inc

@@ -0,0 +1,89 @@
+;Input: H = Multiplier, E = Multiplicand, L = 0, D = 0
+;Output: HL = Product
+mul8_8: 	ld b,7
+		sla h		; optimised 1st iteration
+		jr nc,$+3
+		ld l,e
+.loop:		add hl,hl		; unroll 7 times
+		jr nc,$+3		; ...
+		add hl,de		; ...
+                djnz .loop
+                ret
+
+
+lmod:		call ldiv
+		ex de,hl
+		ret
+
+ldiv:		xor a
+		ex af,af'
+		ex de,hl
+		jr dv1
+
+adiv:		ld a,h
+		xor d		;set sign flag for quotient
+		ld a,h		;get sign of dividend
+		ex af,af'
+		call negif
+		ex de,hl
+		call negif
+dv1:		ld b,1
+		ld a,h
+		or l
+		ret z
+dv8:		push hl
+		add hl,hl
+		jr c,dv2
+		ld a,d
+		cp h
+		jr c,dv2
+		jp nz,dv6
+		ld a,e
+		cp l
+		jr c,dv2
+dv6:		pop af
+		inc b
+		jp dv8
+
+dv2:		pop hl
+		ex de,hl
+		push hl
+		ld hl,0
+		ex (sp),hl
+
+dv4:		ld a,h
+		cp d
+		jr c,dv3
+		jp nz,dv5
+		ld a,l
+		cp e
+		jr c,dv3
+
+dv5:		sbc hl,de
+dv3:		ex (sp),hl
+		ccf
+		adc hl,hl
+		srl d
+		rr e
+		ex (sp),hl
+		djnz dv4
+		pop de
+		ex de,hl
+		ex af,af'
+		call m,negat
+		ex de,hl
+		or a			;test remainder sign bit
+		call m,negat
+		ex de,hl
+		ret
+
+negif:		bit 7,h
+		ret z
+negat:		ld b,h
+		ld c,l
+		ld hl,0
+		or a
+		sbc hl,bc
+		ret
+
+

docs/samples/balls/misc.asm

@@ -0,0 +1,113 @@
+; îáùàÿ ïðîöåäóðà âûõîäà.
+; â A ïîìåñòèòü êîä âîçâðàòà.
+; Åñëè áûëà îøèáêà, òî ëó÷øå -1 (255)
+; Åñëè îøèáêè íåáûëî, òî 0.
+quit0:		pop ix
+		ld b,a
+		ld c,quit
+		rst 10h
+		jp $			; çàãëóøêà
+
+;-[]------------------------------------------------------------
+; misc procedures and functions...
+;---------------------------------------------------------------
+open:		ld a,1
+		ld c,fopen
+		rst 10h
+		ret
+
+close:		ld c,fclose
+		rst 10h
+		ret
+
+read:		ld c,fread
+		rst 10h
+		ret
+
+;dir_ret:	ld hl,cur_dir
+;		ld c,chdir
+;		rst 10h
+;		ret
+
+gmem:		ld c,getmem
+		ld b,1
+		rst 10h
+		ret
+
+; ïðîöåäóðà ñîõðàíåíèÿ ñòðàíèöû â óêàçííîì îêíå.
+; C = îêíî (ïîðò)
+; HL = êóäà ñîõðàíÿòü.
+save_pg:	in a,(c)
+		ld (hl),a
+		ret
+
+; ïðîöåäóðà âîññòàíîâëåíèÿ ñòðàíèöû â óêàçííîì îêíå.
+; C = îêíî (ïîðò)
+; HL = îò êóäà âîññòàíîâèòü.
+restore_pg:	ld a,(hl)
+		out (c),a
+		ret
+
+
+; îáðàáîòêà îøèáêè îòêðûòèÿ ôàéëà
+open_err:
+		ld hl,open_err_str
+		ld c,pchars
+		rst 10h
+.err_file:	ld hl,0
+		ld c,pchars
+		rst 10h
+		ld hl,crlf0
+		ld c,pchars
+		rst 10h
+		ld a,-1
+		jp quit0
+
+
+; îáðàáîòêà îøèáêè ÷òåíèÿ ôàéëà
+rd_err:
+		ld hl,read_err_str
+		ld c,pchars
+		rst 10h
+.err_file:	ld hl,0
+		ld c,pchars
+		rst 10h
+		ld hl,crlf0
+		ld c,pchars
+		rst 10h
+		ld a,-1
+		jp quit0
+	
+
+; îáðàáîòêà îøèáêè çàïðîñà ïàìÿòè
+gmem_err:	ld hl,gmem_err_str
+		ld c,pchars
+		rst 10h
+		ld a,-1
+		jp quit0
+
+; îáðàáîòêà îøèáêè îòêðûòèÿ âèäåîðåæèìà
+vm_err:		ld hl,vm_err_str
+		ld c,pchars
+		rst 10h
+                jp quit0
+
+	IFDEF debug
+debug_print:	ld c,pchars
+		rst 10h
+		ret
+	ENDIF
+
+; îáðàáîòêà îøèáêîê òîêåíîâ
+;tok_err:
+;		ld hl,token_err_str
+;		ld c,pchars
+;		rst 10h
+;.token_ptr:	ld hl,0
+;		ld c,pchars
+;		rst 10h
+;		ld hl,crlf0
+;		ld c,pchars
+;		rst 10h
+;		ld a,-1
+;		jp quit0

docs/sdbg-log-macros.md

@@ -0,0 +1,204 @@
+# Логи C-приложения через `SDBG_LOG`
+
+Этот документ описывает **работающий контракт** макросов из `<sdbg.h>`.
+Они ставят авторские logpoints в MAME debugger без вызовов DSS/BIOS и без
+кода печати в приложении. Сообщение попадает в Debug Console VS Code и в
+журнал debugger MAME. Отдельное окно MAME debugger видно при launch с
+`"debugger": "osx"`; режим `sdbg` оставляет окно Sprinter и журнал MAME,
+но не открывает штатное debugger-окно.
+
+## Быстрый пример
+
+```c
+#include <stdint.h>
+#include <sdbg.h>
+
+volatile uint16_t frame_no;
+volatile uint8_t ready;
+
+void draw_frame(void)
+{
+    ++frame_no;
+    SDBG_LOG(frame_counter, "frame={frame_no}");
+    SDBG_LOGIF(frame_ready, ready, "ready={ready}, frame={frame_no}");
+}
+```
+
+Соберите приложение с `make SRC_DEBUG=1` либо запустите F5 в VS Code:
+расширение выполняет debug-сборку перед запуском. Для прямого вызова
+обёртки подходит `bin/sprinter-cc --src-debug ...`; в режиме
+`--src-debug-file FILE` якоря создаются только в выбранных единицах
+трансляции. После загрузки DSS launcher останавливается в `main`, проверяет
+образ, и session server активирует макросные точки. При попадании он читает
+поддержанные значения, выводит текст и продолжает CPU. Если на том же
+адресе есть обычный breakpoint, сообщение печатается, а CPU остаётся
+остановленным.
+
+В обычной сборке оба макроса раскрываются в `((void)0)`: без source-debug
+сессии они сами ничего не печатают. Строка сообщения не хранится в EXE;
+в проверенных обычном и банковом fixture бинарники с макросом и без него
+побайтово совпали. Inline asm может влиять на оптимизацию в других случаях,
+поэтому одинаковый размер/код каждой программы следует проверять отдельно.
+
+## Параметры и место вызова
+
+`SDBG_LOG(tag, message)` принимает два аргумента.
+
+| Параметр | Что передать | Ограничение |
+|---|---|---|
+| `tag` | Имя точки, например `frame_counter` | C-идентификатор `[A-Za-z_][A-Za-z_0-9]*`, **без кавычек**, уникальный внутри `.c`/TU |
+| `message` | Строковый литерал C, например `"frame={frame_no}"` | От 1 до 1024 символов после декодирования, поддержана склейка соседних литералов |
+
+Одинаковый `tag` в разных `.c` допустим: сборщик добавляет к символу
+уникальный ID TU. Повторный `tag` в одном TU, в том числе из повторно
+развёрнутого inline-макроса, отклоняется при сборке. Вычисляемый tag,
+строка вместо tag и автоматический `__LINE__` пока не поддержаны.
+Используйте название, которое остаётся понятным после правки строк файла.
+
+`SDBG_LOGIF(tag, condition, message)` принимает третий смысловой компонент:
+между tag и сообщением указывается **одно имя** поддержанной global/static
+переменной. Если её значение при попадании равно нулю, запись пропускается,
+CPU продолжается. Ненулевое значение включает запись. Например:
+
+```c
+SDBG_LOGIF(after_load, ready, "ready={ready}");
+```
+
+`ready != 0`, `!ready`, вызов функции, локальная переменная и регистр CPU
+как `condition` сейчас не поддержаны. Условие не исполняется кодом C:
+отладчик читает значение при остановке. Если переменная недоступна, запись
+пропускается и отладчик один раз сообщает причину. Значения с побочными
+эффектами (`counter++`, вызовы функций) нельзя использовать и в шаблоне:
+аргументы макроса не вычисляются на Sprinter.
+
+Якорь привязан к текущему адресу ассемблера без инструкции. Он обозначает
+машинную границу рядом с вызовом макроса, а не обещает точный порядок всех
+выражений C после оптимизации. Ставьте вызов отдельным statement после
+интересующего действия и проверяйте фактический адрес/значение на нужной
+сборке. Если адрес не совпал с началом доказанной инструкции, точка
+получает статус `unverified` и не активируется. Макрос в неактивном `#if`
+не создаёт точку; wrappers, многострочные вызовы и склейка литералов
+обрабатываются активным препроцессорным проходом.
+
+## Синтаксис сообщения сейчас
+
+После обработки C-escape-последовательностей шаблон состоит из литералов
+и подстановок `{name}`. `name` — имя **одной** доступной переменной;
+значение выводится десятичным числом. Например:
+
+```c
+SDBG_LOG(progress, "step={step}, total={total}");
+SDBG_LOG(braces, "literal {{value}}; actual={total}");
+SDBG_LOG(multiline, "step={step}, " "total={total}");
+```
+
+`{{` и `}}` дают буквальные `{` и `}`. `%` сейчас обычный символ: `%d`,
+`%x` и `%s` **не являются** форматами макроса. Синтаксис `{name:04X}`,
+`{name!r}`, `{name+1}`, индексы массивов и разыменование указателя
+отклоняются во время debug-сборки, до запуска MAME. Не добавляйте префикс
+`0x` перед `{name}`: значение пока десятичное, и результат будет неверно
+выглядеть как шестнадцатеричный.
+
+Подстановки разрешаются в контексте TU, где расположен макрос. Можно
+прочитать единственную поддержанную global или file-static переменную этого
+TU. Если имя не найдено/неоднозначно, тип неподдержан или физический банк
+сейчас не отображён, вместо значения выводится `<unavailable: причина>`.
+Локальные/параметры функции не имеют доказанных location ranges и пока
+не читаются. Resident-страница, закрытая банком, тоже недоступна.
+
+Текст DAP сохраняет символы UTF-8. Перед отправкой в MAME debugger `printf`
+кавычки заменяются апострофами, а управляющие символы — пробелами;
+проценты и обратные слэши экранируются. Очень длинный сформированный текст
+может не пройти ограничение MAME console 2048 байт, но DAP output остаётся.
+При частом попадании CPU останавливается каждый раз, поэтому эмуляция может
+замедлиться. DAP хранит до 1024 событий и показывает число пропусков,
+если клиент отстал; скорость горячих logpoints ещё не измерена.
+
+## Какие значения можно подставить
+
+Источник истины — тип и размер глобального/file-static объекта в debug-карте
+SDCC. Доступны целые скаляры размером 1, 2 или 4 байта, а также проверенный
+обычный 16-битный указатель. Значение читается из памяти без side effects.
+Ниже приведены результаты реальной debug-сборки SDCC 4.5 для этих типов.
+
+| C-тип объекта | Сейчас в `{name}` | Что остаётся недоступным |
+|---|---|---|
+| `uint8_t` / `unsigned char` | Десятичное 0…255 | Hex/битовая маска |
+| `int8_t` / `signed char` | Десятичное −128…127 | Принудительный unsigned/hex |
+| `uint16_t` / `unsigned int` | Десятичное 0…65535 | Hex с 4 цифрами |
+| `int16_t` / `int` | Десятичное со знаком | Иной числовой формат |
+| `uint32_t` / `unsigned long` | Десятичное 0…4294967295 | Hex с 8 цифрами |
+| `int32_t` / `long` | Десятичное со знаком | Иной числовой формат |
+| `char` | **Числовой код** байта согласно signedness SDCC; в проверенной сборке `char` был unsigned | Вывод как символ, CP866→UTF-8 |
+| `char *` | **Числовой 16-битный адрес** указателя | По принятому для финального API правилу это строка, а не один `char`: bounded read до NUL, границы, кодировка |
+| `int8_t *` / `uint8_t *` | **Числовой 16-битный адрес** указателя | По финальному API — один знаковый/беззнаковый 8-битный объект по ненулевому адресу, decimal/hex |
+| `char[]`, другие массивы, struct/union, float/double | Не поддержаны | Элементы/поля/значение объекта |
+| Локальные и параметры функции | Не поддержаны | Нужны доказанные регистр/стек и live-range |
+| Регистры CPU (`PC`, `HL`, `DE`, `AF`, `PG0`…) | Не являются подстановками макроса | Они видны в scope Registers VS Code и MAME debugger, но `{PC}` сейчас не читает регистр |
+
+Для `char *` вывод адреса **не доказывает**, что память по нему доступна.
+Сам массив `char[]` сейчас не выводится даже если его размер 1/2/4 байта.
+Числовые коды `char` не декодируются как символы Sprinter. Поддержка
+конкретного объекта зависит и от того, есть ли он в карте: оптимизированное
+или неразрешённое объявление может быть недоступно.
+
+Тип указателя нельзя выбирать только по текущему CDB: SDCC 4.5 записал
+проверенные `char *` и `uint8_t *` одинаково как `DG,SC:U` (2 байта),
+а `int8_t *` как `DG,SC:S`. Для финального вывода строки или скаляра нужны
+метаданные **исходного объявленного типа**, сохранённые в debug-пакете и
+сверенные с CDB/размером. Неоднозначные typedef/объявления должны давать
+`unavailable` либо требовать явную аннотацию формата, а не угадывать по CDB.
+
+## Форматирование, которое рассматривается
+
+Эта таблица описывает **предложение для следующей версии**, а не действующий
+синтаксис. В текущей версии все записи справа вызовут ошибку сборки.
+
+| Предлагаемый шаблон | Назначение | Что нужно реализовать и проверить |
+|---|---|---|
+| `{u8:02X}`, `{u16:04X}`, `{u32:08X}` | Hex с шириной по типу | Ограниченный formatter, signed/unsigned и ширина 8/16/32 бит |
+| `{value:d}`, `{value:x}`, `{value:X}` | Одну переменную можно вывести в десятичном и hex виде в одном сообщении | Проверка типа/знака, 8/16/32-битной ширины и недопущение произвольных Python format specifier |
+| `{letter:c}` | Символ из `char` | CP866→UTF-8, различие числового кода и отображения символа |
+| `{ptr:p}` | Значение самого указателя: логический/банковый адрес | Типизированный адрес, явный `NULL`, различие числового decimal/hex отображения |
+| `{p8:*d}`, `{p8:*x}` **условно** | Один 8-битный scalar по `int8_t *`/`uint8_t *` при ненулевом адресе; decimal/hex, окончательный синтаксис ещё не утверждён | Исходный тип и signedness, side-effect-free чтение одного байта, границы/банк; `NULL`/закрытая страница → `unavailable` |
+| `{text:s}` | Строка по `char *` при ненулевом адресе, а не один `char`; прямой `char[]` — отдельный случай | Сохранить declared type, bounded read до NUL, доступный банк, отсутствие NUL/кодировка/лимит вывода |
+| `{reg:PC}` | Значение регистра CPU | Отдельное пространство имён, чтобы не спутать регистр с C-global `PC` |
+
+Форматирование должно использовать один и тот же ограниченный движок для
+C-макросов, внешних logpoints и DAP output. До реализации предпочтительнее
+выводить десятичное значение и читать hex/регистры в штатных views debugger,
+чем имитировать `printf` в тексте сообщения.
+
+Обе задачи — decimal/hex вывод и чтение значения по указателю — записаны
+в финальный [этап 6 плана](mame-source-debug.md).
+Сейчас `{ptr}` показывает только десятичное значение адреса; разыменование
+не выполняется даже при ненулевом указателе. В финальном API `char *`
+обозначает строку, а указатель на один 8-битный объект записывается как
+`int8_t *` или `uint8_t *`. Адрес любого указателя должен выводиться
+отдельно от значения по адресу. Для строки нужна отдельная проверка NUL,
+лимита и кодировки (CP866→UTF-8 либо явное представление raw bytes).
+Целевой результат можно представить как `text=<адрес>, value=<строка>` для
+`char *` и `p8=<адрес>, value=<одно 8-битное число>` для `uint8_t *`;
+показанные выше `{text:s}`/`{p8:*d}` ещё нельзя вставлять в рабочий C-код.
+
+## Если лог не появился
+
+| Симптом | Причина и действие |
+|---|---|
+| Нет лога после обычной сборки | Макрос пуст; запустите `SRC_DEBUG=1`/F5 и проверьте, что TU выбран для карты |
+| Сборка сообщает о повторном `tag` | Дайте каждой точке отдельный идентификатор; повторные inline-развёртки в одном TU требуют отдельного решения |
+| Сборка сообщает «только подстановки» | Уберите `:04X`, `%d` не подставляет значение; используйте `{name}` |
+| `unverified`/«не активирован» в Debug Console | Якорь не совпал с исполняемой инструкцией; переместите макрос к доказанной границе и пересоберите |
+| `<unavailable: …>` | Проверьте global/static тип и отображение страницы банка; локальные пока не поддерживаются |
+| Нет сообщения в окне MAME при `sdbg` | Штатное debugger-окно в этом режиме скрыто; Debug Console VS Code работает, для окна выберите `osx` |
+| При частом логе программа заметно медленнее | Каждое попадание останавливает CPU; уменьшите частоту или используйте условный макрос |
+
+## Актуализация контракта
+
+При изменении `<sdbg.h>`, парсера/форматтера шаблона, набора читаемых типов,
+источников значений, условий, поведения breakpoint или маршрутов MAME/DAP
+сначала обновляйте этот документ и проверяемые примеры. Затем синхронизируйте
+краткое описание в `docs/mame-source-debug.md`, `docs/vscode-sprinter-debug.md`,
+`docs/mame-source-debug-status.md` и `docs/libc-reference.md`. Реальные
+проверки: `tests/sdbg/test_sdbg.py`, `test_server.py`, `test_dap.py` и живой
+`tests/sdbg/run_macro_log_probe.py` для `sdbg`/`osx`.

docs/size_baseline.tsv

@@ -0,0 +1,67 @@
+# Эталон размеров _CODE (байт); обновление: python3 toolchain/size_check.py --update
+accfill	3797
+accop	7067
+argv	3445
+assrtest	3861
+atlas	9627
+attrprob	4101
+banked	1070
+bankedbg	1081
+banklocl	4697
+banktest	3781
+bgi_img	8691
+bgitest	3762
+bios_text	4475
+blitperf	5860
+blitw	4939
+cat	927
+cblstream	5944
+cbltest	6090
+cblwav	6183
+conio	4619
+conio2	3943
+convbench	3508
+dec_test	874
+errno	5980
+fbench	8149
+fdmax	6087
+filetest	10611
+fpsdiv	4870
+gets	523
+gfx_dbuf	5207
+gfx_demo	4128
+gfxbanks	6044
+hello	4181
+hello2	4258
+irqtest	6754
+kbdpoll	1282
+kbdraw	4911
+ls	4849
+malloc	4475
+mem_test	4569
+mouse	4396
+openenv	6138
+pageflip	6334
+palfile	5406
+ptime	5758
+rt_test	5216
+scroll	6744
+seek	4202
+simple	969
+solidt	11595
+spranim	9431
+spriteclip	4119
+sprites	6791
+stattest	7563
+stdlib	6657
+stest2	3658
+strtest	1354
+text_palette	5038
+timedir	5468
+w0page	8831
+w3bgfx	5243
+w3big	3673
+w3huge	3700
+w3probe	3556
+w3tiny	3471
+winrest	4473

docs/solid_c_compatibility.md

@@ -130,6 +130,31 @@ These will be in `docs/solid_c_diff.md`:
 
 To make porting easier, add a single `<sprinter_solid.h>` that includes all the standard headers (`stdio.h`, `string.h`, `conio.h`, etc.) — Solid-C programs can `#include <sprinter_solid.h>` and have most functions available.
 
+## Status 2026-07-06 — Phase 1/2/3 ЗАКРЫТЫ
+
+Всё из категорий A/B/C реализовано или закрыто решением:
+
+- **A (алиасы)**: все на месте в sprinter_compat.h (+ ltell, _setargv
+  добавлены 2026-07-06); div/ldiv — из SDCC z80.lib (проверено).
+- **B**: getdisk/setdisk (ESTEX $02/$01, libc/io), getdate/gettime/
+  setdate/settime (обёртки над getdatetime, структуры Turbo-C в
+  <dos.h>), остальное было готово ранее.
+- **C**: fdopen/freopen/fclosall/fgetpos/fsetpos — реализованы поверх
+  таблицы FILE v2 (libc/file); ungetc — есть (FILE v2);
+  **absread/abswrite — BIOS $55/$56** (rst 8, A=диск, HL:IX=сектор,
+  DE=буфер, B=счётчик; найдено в solid-c DOS.ASM) — реализованы в
+  libc/io; **scanf/fscanf/sscanf — реализованы** (своё C-ядро
+  _scanf_core с семантикой Solid-C: %d %u %x %o %c %s, l, ширина, %*;
+  в SDCC z80 scanf нет); isatty — fd < 2 (см. memory/dss_fd_limit).
+  bdos/bdosh/intdos — НЕ экспонируем (решение: типизированные
+  обёртки); brk/sbrk — НЕ нужны (heap SDCC); ioctl — скип.
+- **errno**: Solid-C имена (EZERO/EINVFNC/ENOFILE/…) — алиасы в errno.h.
+- **Зонтичный заголовок**: <sprinter_solid.h>.
+- Тест: tests/solidt (MAME).
+
 ## History
 
+- 2026-07-06 — Phase 1/2/3 закрыты: dos.h (даты/диски/сектора),
+  scanf-семейство, fdopen/freopen/fclosall/fgetpos/fsetpos,
+  rename/isatty (П4), errno-алиасы, sprinter_solid.h, тест solidt
 - 2026-06-01 — initial gap analysis vs Solid-C v2004

docs/turboc.txt

@@ -0,0 +1,284 @@
+Функция puts()
+Функция puts() записывает символьную строку в стандартный
+поток данных (т.е. выводит ее на экран). Функция puts()
+возвращает код символа «\п».
+	int puts(const char *string);
+После выполнения функции puts() курсор переводится на
+новую строку.
+
+
+Функция putchar()
+Функция putchar() записывает символ в стандартный поток
+данных (т.е. выводит его на экран). Функция putchar() возвращает
+выведенный на экран символ.
+	int putchar(int ch);
+
+
+Функция gets()
+Функция gets() считывает символьную строку стандартного
+входного потока и помещает ее по адресу, заданному указателем
+buffer; прием строки заканчивается, если функция обнаруживает
+символ конца строки «\п», данный символ удаляется и
+заменяется нуль-терминатором «\0».
+	char *gets (char*buffer);
+Функция gets() возвращает указатель на считанную строку.
+
+
+Функция getchar()
+Функция getchar() считывает символ из стандартного
+входного потока.
+	int getchar(void);
+Функция getchar() возвращает считанный символ.
+
+
+
+=== Функции консольного ввода
+
+	char *cgets(char *str) 
+- помещает в буфер, на начало которого
+указывает str, строку символов со стандартного ввода.
+Запись символов начинается с str[l]; str[0] должен содержать
+максимальное число символов, которое должно быть прочитано
+и записано в строку. Функция возвращает указатель на начало
+буфера str.
+
+	int getch(void) 
+- выполняет ввод символа с клавиатуры.
+Turbo С не выполняет «эхо» ввода. В этой связи полезна для
+организации интерфейса с пользователем, при котором нажатие
+той или иной клавиши вызывает немедленную реакцию программы
+без отображения введённого символа на экране.
+
+	int getche(void) 
+- выполняет небуферизуемый ввод символа
+с клавиатуры. Turbo С «эхоирует» ввод на экране. Перевод
+строки происходит при достижении правой вертикальной
+границы текущего активного окна.
+
+	int kbhit(void) 
+- проверяет, пуст ли буфер клавиатуры.
+Если в буфере есть символы, функция возвращает ненулевое
+значение, в противном случае она возвращает О. Является
+удобным средством предотвращения «зацикливания» или «по-
+висания» при ожидании невозможного в данный момент события.
+Кроме того, осуществляется проверка нажатия комбинации
+клавиш «Ctrl-Break», что позволяет выполнить аварийное завершение
+программы.
+
+	int ungetch(int ch) 
+- записывает непосредственно в буфер
+клавиатуры символ ch. Он будет доступен при выполнении следующей
+операции чтения с консоли (функциями файла
+«conio.h»). Разрешает помещать только один символ, который
+не должен совпадать с константой EOF, описанной в файле
+«stdio.h». В случае успеха функция возвращает ch; в противном
+случае возвращается -1.
+
+
+=== Функции консольного вывода
+
+	void textmode(int newmode) 
+- изменяет текущий текстовый
+режим. Новый режим указывается единственным параметром
+newmode и может задаваться либо числом, либо с использованием
+символических констант, значения которых определяет
+перечислимый тип text_modes
+
+Функции консольного вывода используют понятие активного
+окна экрана. Активное окно - это прямоугольная область
+экрана, в границах которой в данный момент работают функции.
+Описание активного окна (или, как часто говорят, фрейм)
+хранится во внутренней структурной переменной Turbo С. Установку
+параметров активного текстового окна выполняет функция
+window ().
+
+	void window(int l_t_col, int l_t_row, int r_b_col, int r_b_row) 
+- описывает активное текстовое окно: первая пара
+аргументов задает столбец и строку левого верхнего угла, вторая
+пара - правого нижнего угла. Строки и столбцы нумеруются,
+начиная от 1. Поэтому, например, координаты левого верх-
+него и правого нижнего углов экрана в режимах «25 строк х 80
+столбцов» задаются парами (1,1) и (80,25). Ось X направлена
+слева направо, а ось Y направлена сверху вниз. Следует обратить
+внимание на то, как в Turbo С задаются координаты углов,
+сначала столбец, затем строка.
+
+Фрейм окна Turbo С имеет следующую структуру:
+	struct text_info {
+		unsigned char winleft; /* столбец, строка */
+		unsigned char wintop; /* левого верхнего угла */
+		unsigned char winright; /* столбец, строка */
+		unsigned char winbottom;/* правого верхнего угла */
+		unsigned char attribute; /* атрибуты */
+		unsigned char normattr; /* окна */
+		unsigned char screenheight; /* полная высота экрана */
+		unsigned char screenwidth; /* полная ширина экрана */
+		unsigned char curx; /* строка, столбец */
+		unsigned char сuгу /* текущей позиции курсора */
+	}
+
+
+	void gettextinfo(struct text_info *r) 
+- заполняет поля
+структурной переменной по шаблону text_info, на которую
+ссылается. Шаблон структуры text_info, описывающей текущее
+окно экрана, содержится в заголовочном файле «conio.h».
+
+Функция window() инициализирует поля координат фрейма
+окна. Функции textcolor(), textbackground(), textattr() и
+другие управляют цветом отображаемых символов окна.
+
+	void textattr(int newattr) 
+- устанавливает атрибут для
+функций, работающих с текстовыми окнами. Атрибут хранится в
+поле attribute структурной переменной по шаблону text_info,
+доступной через функцию gettextinfo()
+
+	void textcolor(int newcolor) 
+- задает цвет символов, не
+затрагивая установленный цвет фона. Цвет может быть или числом,
+или формироваться из символических констант, значения
+которых определяет перечисляемый тип COLORS.
+
+	void textbackground(int newcolor) 
+- задает цвет фона
+символов, не затрагивая установленный цвет символа. Цвет может
+быть или числом, или формироваться из символических
+констант
+
+	void gotoxy(int х, int у) 
+- устанавливает курсор в строку
+у и столбец х в текущем активном окне экрана. Верхний левый
+угол окна имеет координаты (1,1). При попытке позиционировать
+курсор за границы окна он останавливается на границе окна.
+Особенностью функции является то, что координаты х и у
+являются относительными, приведенными к левому верхнему
+углу. Например, если текущее окно было описано функцией
+window(1,8,80,25), обращение gotoxy(5,5); установит курсор
+в пятый относительный столбец окна (совпадает с абсолютным
+столбцом 4, отсчитываемым от О) в пятой относительной строке
+(так как верхняя строка окна задана равной 5, то абсолютная
+строка будет равна 5+8-1, если отсчет строк ведется от О)
+
+	int wherex(void), 
+	int wherey(void) 
+- сообщают столбец и
+строку текущей позиции курсора; возвращают целое число в
+диапазоне 
+
+	void clreol(void) 
+- стирает в текстовом окне строку, на которую
+установлен курсор, начиная с текущей позиции курсора и
+до конца строки (до правой вертикальной границы окна).
+
+	void clrscr(void) 
+- очищает все текстовое окно. Цвет «заливки»
+окна при очистке будет соответствовать значению, установленному
+символической переменной attribute в описании
+окна (структурная переменная по шаблону text_info).
+
+	void delline(void) 
+- стирает в текстовом окне всю строку
+текста, на которую установлен курсор.
+
+	void insline(void) 
+- вставляет пустую строку в текущей
+позиции курсора со сдвигом всех остальных строк окна на одну
+строку вниз. При этом самая нижняя строка текста окна теряется.
+
+	int cprintf(const char *format, ...) 
+- выполняет вывод
+информации с преобразованием по заданной форматной строке,
+на которую указывает format. Является аналогом функции
+стандартной библиотеки printf(), но выполняет вывод в пределах
+заданного окна. В отличие от printf() функция cprintf()
+иначе реагирует на специальный символ '\п' - курсор переводится
+на новую строку, но не возвращается к левой границе окна.
+Поэтому для перевода курсора на начало новой строки текстового
+окна следует вывести последовательность символов CR-
+LF (OxOd,OxOa). Остальные специальные символы воздействуют
+на курсор так же, как и в случае функций стандартного ввода-
+вывода. Функция возвращает число выведенных байтов, а не
+число обработанных полей, как это делает функция printf().
+
+	int cputs(const char *str) 
+- выводит строку символов в
+текстовое окно, начиная с текущей позиции курсора. На начало
+выводимой ASCIIZ-строки указывает str. Является аналогом
+функции стандартной библиотеки puts(), выполняет вывод в
+пределах заданного окна и при выводе не добавляет специальный
+символ '\п'. Реакция cputs() на специальный символ '\п'
+аналогична реакции cprintf(): курсор переводится на новую
+строку, но не возвращается к левой границе окна. Поэтому для
+перевода курсора на начало новой строки текстового окна следует
+вывести последовательность символов CR-LF (OxOd,OxOa).
+Остальные специальные символы воздействуют на курсор так
+же, как и в случае функций стандартного ввода/вывода. Функция
+возвращает ASCII-код последнего выведенного на экран
+символа. В отличие от puts() в функции отсутствует возврат
+символа EOF (вывод на экран происходит в любом случае).
+
+	int movetext(int left, int top, int right, int bottom, int destleft, int desttop) 
+- переносит окно, заданное координатами
+левого верхнего (left, top) и правого нижнего (right, bottom)
+углов, в другое место на экране, заданное координатами левого
+верхнего угла нового положения окна. Размеры окна по горизонтали
+и вертикали сохраняются. Все координаты задаются относительно
+координат верхнего левого угла экрана (1,1). Функция
+возвращает ненулевое значение, если перенос заданного
+окна выполнен. В противном случае возвращается О. Функция
+корректно выполняет перекрывающиеся переносы, т.е. переносы,
+в которых прямоугольная область-источник и область, в которую
+окно переносится, частично покрывают друг друга.
+
+	int putch(int ch) 
+- выводит символ в текущей позиции
+текстового окна экрана. Как и для функций cprintf(), cputs(),
+специальный символ '\п' вызывает только переход курсора на
+новую строку текстового окна без возврата к его левой вертикальной
+границе. Остальные специальные символы воздействуют
+на курсор так же, как и для функций стандартного ввода-
+вывода.
+
+	int puttext(int left, int top, int right, int bottom, void source) 
+- выводит на экран текстовое окно, заданное координатами
+левого верхнего (left, top) и правого нижнего (right,
+bottom) углов. Символы и атрибуты располагаются в буфере,
+адрес начала которого задаёт указатель source (функция «открывает»
+или «восстанавливает» текстовое окно экрана). Обычно
+используется вместе с функцией gettext(), выполняющей
+обратную операцию - запись в source символов/атрибутов,
+полностью описывающих все знакоместа текстового окна. Функция
+проверяет по заданным координатам окна, можно ли разместить
+окно на экране для текущего режима видеоадаптера и
+корректны ли эти координаты. В случае, когда окно успешно
+выведено, возвращается ненулевое значение.
+
+	int gettext(int left, int top, int right, int bottom, void destin) 
+- записывает в буфер destin символы и атрибуты текстового
+окна, заданного строкой и столбцом левого верхнего
+(left, top) и правого нижнего (right, bottom) углов. Первые два
+слова буфера занимают ширина и длина скопированного окна.
+Работает только в текстовых режимах видеоадаптера. Координаты
+задаются относительно верхнего левого угла экрана (1,1). В
+случае успеха возвращает ненулевое число.
+
+
+=== Файловый ввод/вывод
+
+Прототипы функций ввода-вывода и используемые для этого
+типы данных описаны в стандартном заголовочном файле
+«stdio.h».
+Для файлового ввода/вывода в Си предусмотрены две основные
+группы функций:
+• функции низкоуровневого ввода/вывода, использующие
+для доступа к файлам целочисленные файловые дескрипторы;
+• функции более высокого уровня, осуществляющие буферизованный
+ввод/вывод с применением потоков.
+Поток в Си - это объект, служащий для доступа к файлам
+как к упорядоченной последовательности символов.
+Поток представляется структурой типа FILE, с которой ассоциирован
+некоторый открытый файл. При необходимости несколько
+потоков могут ссылаться на один и тот же файл.
+
+

docs/vscode-sprinter-debug.md

@@ -0,0 +1,302 @@
+# Source-debug Sprinter в VS Code
+
+Статус: MVP для разработки самого отладчика. Поддержаны автоматический launch,
+ручной attach, точки по строкам и функциям, logpoints, один C-frame,
+регистры, простые global/static, continue/pause, instruction step и шаги
+по исходнику F10/F11/Shift+F11.
+
+> [!WARNING]
+> **Windows пока не поддерживает полный цикл отладки.** Значение
+> `debugger: "windows"` включает только штатное окно debugger MAME.
+> Текущие launcher, owner lock и DAP/session transport используют Unix
+> shell, `fcntl` и Unix domain sockets. Поэтому native Windows launch/attach
+> из VS Code пока не считается рабочим. Поддержка потребует отдельного
+> Windows transport и end-to-end проверки.
+
+## Какие расширения нужны
+
+Для build/run/debug используется отдельный проект `VSCode-Sprinter`. Только
+его расширение знает формат source-debug
+пакета, загрузку приложения через DSS, банки Sprinter и DAP-сессию MAME.
+
+Microsoft C/C++ или clangd можно поставить дополнительно ради completion,
+переходов по исходникам и подсветки. Оба анализируют код как близкий к
+обычному C и не являются точной моделью SDCC: параметры `__naked`, ABI и
+часть target-заголовков потребуют отдельных defines/configuration. Ошибки
+реальной сборки всегда определяет `sprinter-cc`.
+
+## Подготовка программы
+
+Соберите приложение с полной картой:
+
+```sh
+pyenv exec make -C tests/hello SRC_DEBUG=1
+```
+
+Рядом с EXE появится `.sprinter-cc-hello/manifest.json`. При изменении C,
+заголовка или опций `make` пересоберёт пакет по хэшу содержимого.
+
+## Загрузка development-расширения
+
+Из корня репозитория откройте VS Code с распакованным расширением:
+
+```sh
+code --extensionDevelopmentPath="/путь/к/VSCode-Sprinter" "$PWD"
+```
+
+Если команда `code` не добавлена в `PATH`, на macOS этого проекта доступен
+полный путь:
+
+```sh
+"/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" \
+  --new-window \
+  --extensionDevelopmentPath="/путь/к/VSCode-Sprinter" \
+  "$PWD"
+```
+
+В локальных настройках workspace задайте `sprinterDebugger.sdkRoot` и
+`sprinterDebugger.mameHome`. Первый указывает на установленный C-Compiler,
+второй — на среду `MAME/runtime` с бинарником, ROM и DSS/CHD. Для выбора
+stock/sdbg или нестандартной установки используются поля `mameBin`,
+`mameRompath`, `mameDssImage`, `mameSystemHddImage`, `mameBios` профиля launch.
+
+Расширение в режиме `auto` использует `~/.pyenv/shims/python` при наличии
+local `.python-version`; для внешнего workspace ищет установленный
+`~/.pyenv/versions/3.12*/bin/python`, затем `.venv/bin/python` и известные
+абсолютные пути Python 3.12. Local-версия передаётся задаче сборки через
+`PYENV_VERSION`, даже если приложение лежит вне workspace. Это не зависит от `PATH` процесса VS Code,
+который мог быть открыт из Dock. Выбор можно переопределить абсолютным путём
+в `sprinterDebugger.pythonCommand`; дополнительные аргументы задаются через
+`sprinterDebugger.pythonArguments`.
+
+## Автоматический launch
+
+Добавьте в локальный `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "sprinter-mame",
+      "request": "launch",
+      "name": "Sprinter MAME: hello",
+      "build": "${workspaceFolder}/tests/hello/.sprinter-cc-hello"
+    }
+  ]
+}
+```
+
+Launcher создаёт временные floppy/HDD/state-каталоги и видимое окно MAME.
+В отдельный `cfg/sprinter.cfg` он записывает только включение обеих клавиатур
+Sprinter: `:` и `:kbd:ms_naturl`. MAME по умолчанию активирует лишь первую,
+поэтому без этой настройки физические клавиши не доходят до DSS `getchar()`.
+Действующая пользовательская конфигурация MAME при этом не копируется.
+Он читает символы текстового экрана из VRAM, находит пустой prompt `X:…>` и
+требует, чтобы тот оставался готовым 0,25 секунды. Только затем ставится
+service-точка `main` и вводится `a:\\HELLO.EXE`. После совпадения PC и
+сигнатуры кода запускается session server, DAP принимает редакторские точки,
+а VS Code показывает остановку на entry. Завершение debug session останавливает
+только созданные ей MAME/server.
+
+`dssTimeout` задаёт предельное время ожидания prompt (30 эмулируемых секунд).
+`launchAt` можно задать как необязательную нижнюю границу времени запуска;
+наличие prompt всё равно обязательно. Перед вводом сохраняется диагностический
+снимок DSS.
+
+Для перенесённого SprPoP его workspace содержит локальный профиль F5:
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "launch",
+  "name": "Sprinter: SprPoP (VS Code)",
+  "build": "${workspaceFolder}/build/.sprinter-cc-sprpop",
+  "buildTarget": "hdd",
+  "appHdd": "${workspaceFolder}/build/hdd/sprpop.chd",
+  "launchPath": "d:\\games\\sprpop\\sprpop.exe"
+}
+```
+
+Расширение перед F5 запускает `make SRC_DEBUG=1 hdd` в каталоге игры,
+затем загружает EXE с её локального диска. Для такого профиля нужен
+`SPRINTER_ROOT` только на этапе сборки и `MAME_HOME` при запуске.
+
+Дополнительные файлы на floppy задаются массивом `data`; для приложения с
+собственным CHD задайте `appHdd`, `launchPath` и `buildTarget: "hdd"`.
+Launcher монтирует временную копию CHD как `-hard2`, а DSS вводит путь EXE
+из `launchPath`. Сам debug EXE остаётся также на временной A: для проверки
+сигнатуры; несовпадение кода на диске с пакетом отладки останавливает launch.
+
+## Ручная проверка VS Code
+
+В репозитории локально подготовлены два профиля `.vscode/launch.json`:
+`Sprinter: hello (VS Code)` и `Sprinter: hello (VS Code + MAME debugger)`.
+Файл `.vscode` намеренно игнорируется Git и не содержит личных путей.
+
+1. Соберите `hello` командой из раздела «Подготовка программы» и запустите
+   Extension Development Host одной из команд выше.
+2. Откройте `tests/hello/hello.c` и поставьте breakpoint на строке 31,
+   вызове `puts`.
+3. В Run and Debug выберите `Sprinter: hello (VS Code)` и нажмите F5.
+   Расширение сначала выполнит `make SRC_DEBUG=1` в `tests/hello` как задачу
+   Sprinter Build. После успешной сборки должно появиться окно Sprinter;
+   launcher дождётся prompt DSS, введёт
+   `A:\\HELLO.EXE` и VS Code остановится в `main`.
+4. Проверьте Call Stack, scope Registers и Debug Console. После Continue
+   должна сработать подтверждённая точка строки 31.
+5. На остановке проверьте F11 и F10. Курсор должен переходить только после
+   фактической остановки CPU, а не сразу после отправки команды. На строке 62
+   (`getchar`) нажмите F10, щёлкните окно Sprinter MAME и нажмите латинскую `x`:
+   выполнение должно перейти на строку 63. Пока программа ждёт клавишу,
+   кнопка Pause в VS Code должна останавливать CPU.
+6. Завершите сессию кнопкой Stop. Затем повторите профиль с `osx`: вместе с
+   тем же VS Code-сеансом должно открыться штатное Cocoa-окно debugger MAME.
+
+Команда палитры `Sprinter: Build Active Project` собирает приложение по
+Makefile открытого C-файла. Задачи `Sprinter: Build ...` доступны и в
+`Tasks: Run Task`. Для launch автоматическая сборка включена по умолчанию,
+если из `build` можно найти Makefile с `app.mk`; нестандартный каталог задаётся
+полем `project`, а уже собранный пакет запускается с `"autoBuild": false`.
+Ошибка SDCC с файлом и строкой видна в Problems; ненулевой код задачи
+останавливает F5 до запуска MAME. Явный `preLaunchTask` использует стандартное
+поведение VS Code и отключает автоматическую сборку расширения.
+
+Если F5 сообщает, что тип `sprinter-mame` неизвестен, окно запущено без
+`--extensionDevelopmentPath`. Сообщение `Couldn't find a debug adapter
+descriptor` означает, что extension manifest загружен, но расширение не
+активировалось; после изменения `package.json` выполните `Developer: Reload
+Window`. Канал Output → `Sprinter MAME Debug` показывает выбранные Python и
+DAP. При раннем завершении MAME ответ launch включает последние строки
+MAME log. Если сборочный пакет устарел, адаптер должен отказать до запуска
+программы и показать причину, а не использовать старую карту.
+
+Логи из исходника без вывода в DSS задаются в C через `<sdbg.h>`;
+полный синтаксис и таблица поддержанных типов — в
+[руководстве по SDBG_LOG](sdbg-log-macros.md):
+
+```c
+#include <sdbg.h>
+
+volatile int total;
+
+/* tag уникален в этом .c; total читает debugger, не приложение. */
+SDBG_LOG(after_increment, "total={total}");
+```
+
+При F5 debug-сборка привяжет нулевой asm-якорь к адресу и session server
+поставит logpoint после загрузки DSS. Попадание напишет `total=...` в
+Debug Console VS Code и в debugger console MAME, затем продолжит выполнение.
+В обычной сборке макрос пуст. Поддерживаются только global/static переменные
+доказанного типа, литералы и `{name}`; локальные, выражения и `%d` пока нет.
+`SDBG_LOGIF(tag, flag, "...")` выводит сообщение, если поддержанная
+global/static `flag` ненулевая. Аргументы не исполняются на Sprinter, поэтому
+выражения с побочными эффектами не имеют здесь смысла. В режиме `sdbg`
+журнал MAME существует, но его штатное окно не открывается; для видимого
+окна выберите `osx` ниже. Горячий logpoint может заметно замедлить эмуляцию:
+CPU останавливается на каждом попадании. Если DAP не успевает забрать
+события из ограниченного журнала, Debug Console сообщает число пропусков.
+Текст в VS Code сохраняется точно; MAME console заменяет двойные кавычки
+апострофами и управляющие символы пробелами из-за синтаксиса `printf`.
+
+## Родной debugger MAME вместе с VS Code
+
+По умолчанию используется project backend `sdbg`: видимо окно Sprinter,
+а отдельное Cocoa-окно debugger не создаётся. Для регистров, дизассемблера,
+памяти и console штатного MAME добавьте в launch-конфигурацию:
+
+```json
+"debugger": "osx"
+```
+
+Bridge и DAP продолжают работать параллельно. Ручные `go`, изменение точек и
+reset в native console обходят модель состояния VS Code; reset пока нельзя
+использовать из-за lifecycle-crash MAME 0.287.
+
+Для MAME без project patch выберите штатный provider:
+
+| Платформа/сборка | `debugger` |
+|---|---|
+| macOS | `osx` |
+| Windows native | `windows` |
+| Linux с Qt debugger | `qt` |
+| Linux/SDL без Qt | `imgui` |
+| Автоматический выбор доступного provider | `auto` |
+
+`imgui` использует основное графическое окно MAME; launcher уже запускает его
+с `-video soft -window`. `none` немедленно продолжает остановленный CPU, а
+`gdbstub` ждёт протокол GDB, поэтому они не подходят для sdbgbridge.
+
+Текущая host-часть sdbg использует `fcntl` и Unix domain sockets. Она работает
+на macOS/Linux. Для native Windows нужны отдельные реализации owner lock,
+локального RPC и launcher; выбор `windows` решает только сторону MAME и не
+обеспечивает работу VS Code-интеграции.
+
+Backend `sdbg` входит как воспроизводимый patch к MAME 0.287. Исходники и
+рецепты теперь принадлежат самостоятельному проекту MAME:
+
+```sh
+cd /путь/к/MAME
+scripts/sprinter/build-variants.sh stock
+scripts/sprinter/build-variants.sh sdbg
+```
+
+В fork patch уже зафиксирован в Git; для чистого baseline сохранён
+`scripts/sprinter/apply-sdbg-patch.sh`. Каждый вариант копируется в
+`MAME_HOME/bin/stock/mame.arm` или `MAME_HOME/bin/sdbg/mame.arm` без подмены
+активного `MAME_HOME/mame.arm`.
+
+## Logpoints
+
+Обычная команда VS Code **Add Logpoint…** работает без пересборки. В сообщении
+разрешены литералы и простые подстановки:
+
+```text
+frame={frame_counter} state={state}
+```
+
+Подстановка принимает только имя поддержанной переменной. Выражения,
+format specifier и conversion отклоняются. Если logpoint и обычная точка
+разрешились в один адрес, сообщение печатается, а CPU остаётся остановленным.
+
+## Шаги по исходнику
+
+F11 выполняет Z80-инструкции до следующей отличающейся C-позиции. F10 на
+каждом машинном шаге использует MAME `over`, поэтому банковский вызов проходит
+целиком. Shift+F11 сначала делает MAME `out`, затем проходит служебный bank
+trampoline до первой C-позиции вызывающей функции. Instruction granularity
+остаётся доступна для точного одиночного шага.
+
+Автомат ограничен 512 машинными операциями. Команда шага отвечает VS Code
+сразу; пока `getchar()` или другой вызов ждёт внешнего ввода, MAME продолжает
+работать, а пользователь может нажать клавишу в его окне либо выполнить Pause
+в VS Code. Время ожидания ввода не ограничивается таймаутом исходного шага.
+При достижении предела CPU остаётся остановленным, а Debug Console получает
+сообщение.
+Пользовательская точка внутри шага имеет приоритет; logpoint печатается и шаг
+продолжается с прежней семантикой.
+
+## Ручной attach
+
+Для общего MAME между CLI и VS Code сначала запустите `sdbg_server.py`, затем:
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "attach",
+  "name": "Sprinter MAME: Attach",
+  "socket": "/tmp/sprinter-sdbg.sock"
+}
+```
+
+Команды server и диагностического CLI приведены в
+[mame-source-debug-status.md](mame-source-debug-status.md).
+
+## Ограничения MVP
+
+- Reset/restart отключён после найденного crash MAME 0.287 на старом Lua
+  callback. Session завершается штатным terminate.
+- Локальные, backtrace, setVariable, watchpoints и чтение неотображённого
+  bank-data ещё не реализованы.
+- Если одна инструкция имеет несколько C-маркеров, frame помечается
+  `[ambiguous]`; адаптер не выбирает строку молча.

examples/mdview/Makefile

@@ -1,44 +0,0 @@
-# Build mdview.exe — Markdown viewer for Sprinter.
-#
-# small memory mode: code in W1, data/stack/heap in W2 (32 KB total).
-# W3 stays free for the file buffer (EMM-mapped).
-
-PROJ_ROOT  := $(abspath $(CURDIR)/../..)
-EXAMPLE    := mdview
-MEMORY     := small
-
-include $(PROJ_ROOT)/app.mk
-
-# ------------------------------------------------------------------
-# Образ дискеты: только mdview.exe + README.MD (перекодированный
-# из UTF-8 в CP866 — рабочую кодировку Sprinter).
-#
-# README.MD хранится в репозитории в UTF-8; iconv -c конвертирует
-# его в CP866, отбрасывая символы без аналога в целевой кодировке.
-# Результат кладётся в .disk_tmp/README.MD, чтобы make_disk.py
-# использовал правильное имя файла на диске.
-#
-# iconv -c возвращает ненулевой код, если хоть один символ отброшен
-# (даже с -c) — это ОЖИДАЕМО при потере символов без аналога в CP866,
-# не ошибка конвертации; вывод при этом всё равно корректно записан.
-# Поэтому код возврата iconv игнорируется (|| true).
-# ------------------------------------------------------------------
-DISK_TMP    := .disk_tmp
-README_DISK := $(DISK_TMP)/README.MD
-
-$(DISK_TMP):
-	mkdir -p $@
-
-$(README_DISK): README.MD | $(DISK_TMP)
-	iconv -c -f UTF-8 -t CP866 README.MD > $@ || true
-
-floppy: $(EXAMPLE).exe $(README_DISK)
-	python3 $(MAKE_DISK) $(FLOPPY_IMG) $(EXAMPLE).exe $(README_DISK)
-	@echo
-	@echo "Floppy ready: $(FLOPPY_IMG)"
-	@echo "Run:  cd $(MAME_DIR) && ./run_mame.sh"
-
-clean:
-	rm -rf .sprinter-cc-* $(EXAMPLE).exe $(DISK_TMP)
-
-.PHONY: all clean floppy run

examples/mdview/README.MD

@@ -1,133 +0,0 @@
-# MDView — Просмотрщик Markdown для Sprinter
-
-**MDView** — программа для просмотра документов в формате *Markdown* на компьютере
-Sprinter (процессор Z80). Документ хранится в отдельном W3 окне и не занимает
-основную RAM программы.
-
-## Возможности
-
-- Документы до **128 КБ** (8 страниц EMM по 16 КБ каждая)
-- До **16 384** экранных строк в индексе
-- Автоматический перенос слов по ширине экрана (80 столбцов)
-- Горизонтальный сдвиг для широких строк (блоки кода, таблицы)
-- Статус-бар: имя файла, диапазон строк, процент прокрутки
-- Спиннер в строке состояния во время загрузки и индексации
-- Поддержка «мягкого» склеивания строк в абзацах и цитатах
-
-## Запуск
-
-```
-mdview [имя_файла.md]
-```
-
-Если имя файла не задано, загружается `README.MD`.
-
-## Управление
-
-```
-Клавиша        Действие
-─────────────  ────────────────────────────────────────
-Up  Down       Прокрутка на одну строку вверх / вниз
-PgUp  PgDn     Прокрутка на страницу (30 строк)
-Home           Начало документа
-End            Конец документа
-Left Right     Горизонтальный сдвиг (только nowrap-строки)
-F1             Окно справки
-F10 / Esc      Выход из программы
-```
-
-## Синтаксис Markdown
-
-### Заголовки
-
-Поддерживаются уровни H1–H4. Уровни H5 и H6 отображаются как H4.
-
-    # Заголовок первого уровня  
-    ## Заголовок второго уровня  
-    ### Заголовок третьего уровня  
-    #### Заголовок четвёртого уровня  
-
-### Текстовое форматирование
-
-**Жирный текст** выделяется двойными звёздочками: `**текст**`
-
-*Курсив* выделяется одиночными звёздочками `*текст*` или знаком подчёркивания `_текст_`
-
-`Встроенный код` обозначается обратными кавычками
-
-~~Зачёркнутый текст~~ — двойные тильды: `~~текст~~`
-
-### Ненумерованный список
-
-Маркеры `-`, `*` или `+`:
-
-- Первый пункт списка
-- Второй пункт списка
-- Третий пункт с достаточно длинным текстом, который при необходимости
-  будет перенесён на следующую строку с сохранением отступа
-
-### Нумерованный список
-
-1. Первый элемент
-2. Второй элемент
-3. Третий элемент
-
-### Цитата
-
-> Блок цитаты начинается с символа `>`. Несколько последовательных
-> строк одной цитаты склеиваются в единый абзац с автоматическим
-> переносом слов.
-
-### Блок кода (verbatim)
-
-Блок кода заключается в тройные обратные кавычки. Внутри блока
-текст отображается «как есть» без разбора Markdown:
-
-```
-#include <stdio.h>
-#include <sprinter.h>
-
-int main(void) {
-    puts("Hello, Sprinter!");
-    return 0;
-}
-```
-
-### Горизонтальная линия
-
-Три или более символов `---`, `***` или `___` на отдельной строке:
-
----
-
-## Технические характеристики
-
-- **Платформа:** Sprinter, процессор Z80 @ 21 МГц
-- **Кодировка:** CP866 (DOS Cyrillic)
-- **Максимальный размер файла:** 128 КБ
-- **Максимальное число строк в индексе:** 16 384
-- **Режим памяти:** small
-  - Код программы, cтек, данные, куча — окнa W1-W2 (32 КБ, адреса 0x4000–0xBFFF).
-  - Буфер файла — страницы EMM, отображаемые в W3 (0xC000–0xFFFF)
-
-## TODO
-
-1. **Увеличение размера документов.** Снять лимит 128 КБ: Достаточно
-   разрешить работать с большим кол-вом страниц памяти, пока оттестированно
-   на работе с 8-мю страницами по 16Кб.
-
-2. **Форматированные таблицы.** Разбирать строки вида `| ячейка | ячейка |`
-   с автоматическим выравниванием столбцов и отрисовкой разделительных
-   линий (строки `|---|---|`). На текущий момент таблицы отображаются
-   как обычные nowrap-строки без выравнивания.
-
-3. **Поддержка кодировок CP1251 и UTF-8.** Автоопределение кодировки
-   по BOM, явное указание через аргумент командной строки (`--encoding cp1251`),
-   возможность переключения кодировки во время просмотра (`F8`).
-   Нужно прежде всего для документов на русском языке; CP866 кодировака уже поддерживается.
-
-4. **Ускорение рендеринга.** Кэш строк экрана. Оптимизация цикла вывода
-   символов через BIOS WRCHAR (пакетный вывод, DMA).
-
----
-
-*MDView v0.2 · (c) 2026 Петров А.Г.*

examples/mdview/docs/mdview-модель-документа-и-рендеринг.md

@@ -1,103 +0,0 @@
-# mdview — модель документа и рендеринг (единый смешанный режим)
-Дизайн-документ переработки `mdview.c` под новое ТЗ форматирования (`examples/mdview/todo2`). Описывает решение по хранению данных, разбор документа при загрузке, упрощение рендера и снятие лимита на число строк.
-## 1. Контекст и главный вопрос
-Мы отказываемся от двух режимов показа (Wrap/UnWrap-переключатель) и переходим к единому смешанному режиму: тип переноса задаётся типом блока (обычный текст/заголовки/списки/цитаты — Wrap; код/таблицы — UnWrap).
-Главный вопрос: нужно ли хранить оригинальный байтовый контент файла, или при загрузке сразу преобразовать его в «готовый к показу» текст (склеить строки параграфов, убрать маркеры, развернуть отступы и т.п.)?
-Ответ: **оригинал храним; отдельный «готовый» текстовый/ячеечный буфер не строим.** «Подготовка при загрузке» реализуется как построение компактного *индекса метаданных*, а не как преобразование *содержимого*.
-## 2. Решение по архитектуре
-### 2.1 Текущее состояние (база)
-* Файл целиком лежит в EMM-страницах (до 8×16 КБ). В окно W3 (`0xC000`) в каждый момент замаплена ровно одна страница; доступ к байту — через `fb()`/`map_page()` (`mdview.c:198-213`).
-* Индекс — это параллельные массивы по экранным сегментам: `line_offset[]` (смещение в файле) + битфлаги `cont/nowrap/blank/in_code`, 2-битный `line_kind[]`, `init_style[]` (`mdview.c:122-135`).
-* `index_lines()` за один проход уже делает склейку параграфов обычного текста, перенос по словам на 80 колонок и перенос emphasis через soft/hard break (`mdview.c:692-911`).
-* `render_line()` при каждой отрисовке заново читает байты из оригинала и заново парсит inline-разметку (`mdview.c:918-1156`).
-Вывод: «готовим при загрузке» мы уже делаем — но готовим **индекс**, а не текст.
-### 2.2 Почему не материализуем содержимое
-* **Одно свободное окно W3.** Режим памяти `small`: код в W1, данные/стек/куча в W2, для банкуемых данных свободен только W3. Преобразование «оригинал → готовый буфер» требует одновременно держать замапленными исходную страницу (чтение) и страницу-приёмник (запись). При единственном окне это поток swap-ов на каждую границу. In-place преобразование тоже невозможно: склейка меняет длины, смещения «съезжают», параграф пересекает границу 16 КБ.
-* **Удвоение памяти и срыв гарантии 128 КБ.** Оригинал может занимать все 8 страниц; готовой копии нужны свои страницы — гарантировать, что влезут обе, нельзя.
-* **Готовая форма не обязательно меньше.** Снятие маркеров экономит байты, но добавляются отступы-продолжения у переносов списков/цитат. В лучшем случае ≈ размер оригинала, в худшем — больше. Ячеечная модель (символ+атрибут) — это ×2 (до 256 КБ), невозможно.
-* **Покадровая стоимость и так мала.** За кадр рисуются только 30 видимых строк (~30×80 чтений). Единственный дорогой проход — `index_lines()` — неизбежен в любой архитектуре (нужен полный скан для `n_lines` и процента прокрутки).
-### 2.3 Что реально оптимизировать
-Не текст, а повторную работу `render_line()`:
-* вызов `classify_line()` на каждый кадр (`mdview.c:984`);
-* обратный проход к первому не-cont сегменту ради отступа продолжения (`mdview.c:944-970`).
-Это снимается переносом результата классификации (`kind`, ширина отступа/контент-колонка) в сам индекс на этапе `index_lines()`.
-## 3. Модель данных индекса
-### 3.1 Запись сегмента
-Единая запись на экранный сегмент полностью заменяет нынешние параллельные массивы (`line_offset`, `cont_flag`, `in_code`, `nowrap_flag`, `blank_flag`, `line_kind`, `init_style`); `index_lines()` переписывается с нуля под эту модель. Цель размера записи — 5–6 байт:
-* `offset` — 3 байта (24-битное смещение в файле, покрывает 128 КБ).
-* `flags` — 1 байт: биты `cont`, `nowrap`, `blank`, `in_code` + 2-битный `ckind` (тип продолжения: PLAIN/QUOTE/LIST/OTHER).
-* `style` — 1 байт: стартовый стиль сегмента (`init_style`, теперь включая STRIKE) + при необходимости глубина вложенности.
-* `indent` — 1 байт: предвычисленная контент-колонка/ширина префикса, чтобы рендер не вызывал `classify_line()` и не делал обратный проход.
-### 3.2 Размещение и снятие лимита `MAX_LINES`
-Проблема: `line_offset` сейчас `uint32_t[2048]` = 8 КБ, `init_style` = 2 КБ; суммарно статический индекс ~11.6 КБ near-памяти (W2). Рост лимита в near невозможен — W2 переполнится.
-Решение:
-* **Индекс храним в отдельном EMM-блоке** (свои страницы, помимо файловых), доступ — через тот же W3.
-* **Near-кэш viewport**: перед отрисовкой кадра разово вычитываем записи для `VIEW_H+1` видимых сегментов в маленький near-массив (≈ `(VIEW_H+1)×6` ≈ 186 байт). Рендер работает по near-кэшу + читает только контент-страницы. Это устраняет per-byte thrashing между страницей индекса и страницей контента: переключений на кадр — единицы, а не тысячи.
-* **Динамический размер**: число страниц под индекс выделяем пропорционально размеру файла (число сегментов ∈ размеру). `MAX_LINES` становится функцией от выделенных страниц индекса. Это прямо ложится на заметку v2 («чем больше банков под файл, тем больше буферы»).
-* **Без регресса скорости при индексе в EMM**: чтобы вынос индекса в банки не замедлил сборку (W3 делится между чтением контента и записью индекса), записи копим в near-буфере батчами и сбрасываем в EMM-блок через `bank_write()` (он сам сохраняет/восстанавливает маппинг W3). Переключений окна на всю сборку — единицы, а не на каждый сегмент.
-* Если индекс-страницы выделить не удалось — деградируем до текущего near-лимита и показываем явную диагностику обрезки (а не молчаливый обрыв в `emit_seg()` — `mdview.c:574`).
-## 4. `index_lines()` — разбор по новому ТЗ
-Единый проход по файлу строит сегменты. Деление на параграфы — по пустым строкам; несколько пустых строк подряд схлопываются в одну.
-### 4.0 Скорость подготовки — главный приоритет
-Требование: подготовка максимально быстрая (сейчас ~25 КБ готовятся 6–10 с). Две структурные причины медленности и их устранение:
-* **Per-byte `fb(uint32_t)`.** Каждый доступ к байту пересчитывает страницу 32-битными `p >> 14` и `p & 0x3FFF` (`mdview.c:209-213`). На Z80 32-битная арифметика — это программные подпрограммы на каждый символ. Замена: **потоковый разбор** — мапим страницу один раз, идём по окну `char *`/16-битным индексом, страницу переключаем только на границе 16 КБ. 32-битным остаётся лишь сохраняемый в индекс `offset`.
-* **Многократные пере-сканы.** На каждом `\n` внутри параграфа вызываются `is_fence_raw()`, `is_hr_raw()`, `classify_line()`, `is_line_blank()` (`mdview.c:800-809`) — каждая заново сканирует следующую строку, а `classify_line()` ещё и повторяет цикл детекции HR. Для параграфа из N строк — O(N×длина) лишней работы. Замена: **один проход** — каждую строку классифицируем ровно один раз в момент её начала, lookahead — минимальный (несколько первых байт).
-* **32-битные сравнения.** Курсор скана — (страница:8 бит, смещение:16 бит); сравнение с концом — сначала по странице, потом 16-битно.
-Ожидаемый эффект: подготовка — по сути один линейный проход с 16-битными операциями, кратное ускорение относительно текущего multi-pass + 32-bit. (`render_line()` может остаться на `fb()` — там только ~30×80 байт за кадр.)
-### 4.1 Обычный текст (Wrap)
-* **Soft break** (одиночный `\n`): склейка, следующая строка продолжается через пробел.
-* **Wide break**: 2+ пробелов перед `\n` **или** символ `\` перед `\n` → принудительный перенос внутри параграфа, стиль сохраняется. (Текущий код ловит только 2 пробела — `mdview.c:813-818`; добавить ветку для `\`.)
-* **Hard break** (пустая строка): новый параграф, отделяется ОДНОЙ пустой строкой независимо от числа пустых строк в оригинале.
-* **Модификаторы** bold/italic/strike/code действуют через soft/wide break внутри параграфа и сбрасываются на границе параграфа. (Добавить STRIKE `~~…~~` — сейчас его нет в `INIT_STYLE_*`/`ATTR_*`.)
-### 4.2 Заголовки (Wrap)
-Один оригинальный абзац-строка; стартовый стиль по уровню. Во входе распознаём H1–H6, но H4/H5/H6 далее обрабатываются одинаково как H4 (сливаются в один стиль; `classify_line()` уже сворачивает `lvl>4` → `LK_H4`, `mdview.c:488`). Внутри допустимы bold/italic/code/strike. После заголовка всегда пустая строка.
-### 4.3 Горизонтальный разделитель HR
-Всегда одна строка, после неё всегда пустая строка (новый абзац).
-### 4.4 Списки (Wrap) — НОВОЕ: многострочная склейка
-* Пункт может занимать несколько оригинальных строк; soft break внутри пункта склеивается через пробел (как обычный текст). Сейчас списки эмитятся построчно (`mdview.c:762-772`) — переписать на paragraph-модель.
-* Новая строка с префиксом пункта → новый пункт.
-* Пустая строка завершает пункт. Следующая непустая НЕ-пункт строка не является продолжением.
-* **Группировка**: если после ОДНОЙ пустой строки идёт снова пункт — это тот же список, пустая строка в показе подавляется (пункты идут вплотную). Только ДВЕ+ пустые строки между пунктами разрывают на разные списки (в показе — одна пустая строка между ними).
-* Перенос продолжения пункта печатается с отступом до контент-колонки (для уровня 1 — 2 пробела).
-* Незакрытые модификаторы НЕ переносятся на следующий пункт (каждый пункт — свой параграф).
-* Вложенные списки поддерживаются (отступ растёт с ведущими пробелами).
-* Отдельные стили: префикс маркера и текст списка.
-Пример соответствует разделу «Списки» в `todo2` (строки 1–6).
-### 4.5 Цитаты (Wrap)
-* Отдельный параграф; перед текстом — префикс цитаты, перенесённые строки тоже предваряются префиксом.
-* Многострочная склейка как у текста; пустая строка-цитата (`>`) показывается как пустая строка с префиксом.
-* Вложенность (`> >` → двойной префикс). Отдельные стили: префикс и текст цитаты.
-### 4.6 Блок кода ``` ``` ``` (UnWrap)
-Весь блок одним стилем кода, без inline-модификаторов. После блока обязательна пустая строка. Строки не переносятся (truncate + горизонтальный скролл).
-### 4.7 Таблицы (UnWrap)
-Пока as-is, без переноса. Выравнивание столбцов — v2.
-## 5. `render_line()` — упрощение
-* Убрать ветку truncate-режима и `wrap_mode` (уже частично снято; `toggle_wrap()` — мёртвая заглушка `mdview.c:1286-1291`, удалить вместе с упоминаниями F2).
-* Не вызывать `classify_line()` и не делать обратный проход: использовать `kind`/`indent`/`style` из индекса.
-* Для cont-сегментов списков/цитат — печать отступа/префикса по `kind`+`indent` из записи сегмента.
-* Inline-парсинг emphasis выполняется только в пределах видимого сегмента (дёшево); для кода/таблиц — отключён.
-## 6. Горизонтальный скроллинг (UnWrap)
-* Скроллится только UnWrap-текст (код/таблицы). Грануляция 8 символов (`HPAN_STEP`).
-* Правый край: индикатор `>` своим стилем, если есть скрытый контент справа (есть — `mdview.c:1135-1155`).
-* **Добавить** левый индикатор `<` в первой колонке, когда `viewport_x > 0`.
-* **Границы скролла по факту**: текущий кламп жёстко до 240 (`mdview.c:1275`). Заменить на вычисление максимального переполнения среди UnWrap-строк в текущем viewport, чтобы вправо нельзя было уйти за самую длинную строку, а влево — до колонки 0.
-## 7. Чеклист расхождений с текущим кодом
-* [индекс] Перейти на запись-на-сегмент в EMM-банке + near-кэш viewport; снять `MAX_LINES=2048`.
-* [скорость] Потоковый разбор: один проход, 16-битный курсор в окне (без per-byte `fb()` с 32-битной арифметикой), классификация строки один раз, минимальный lookahead; батч-флеш индекса.
-* [текст] Wide break по символу `\`.
-* [текст] Модификатор strikethrough `~~…~~` (+ стиль).
-* [списки] Многострочная склейка пунктов и правило группировки по одной/двум пустым строкам.
-* [цитаты] Многострочная склейка и повтор префикса (в т.ч. вложенные) на переносах.
-* [заголовки] Читать H1–H6; H4/H5/H6 трактовать как H4 (частично уже есть — `mdview.c:488`).
-* [скролл] Индикатор `<` и корректные границы по фактическому переполнению.
-* [рендер] Снять per-кадровый `classify_line()` и обратный проход (данные — из индекса).
-* [очистка] Удалить `toggle_wrap()` и упоминания F2 (`mdview.c:1286-1291`, `1311`).
-## 8. Память: бюджет
-* near (W2): текущий статический индекс ~11.6 КБ — у предела окна. После переноса `line_offset`/`init_style` в EMM в near остаётся near-кэш viewport (~0.2 КБ) + мелкие флаги → запас под стек/кучу растёт.
-* EMM: файл до 8 страниц + индекс ~1–2 страницы (при 5–6 байт/сегмент и нескольких тысячах сегментов). Перед выделением проверять `mem_info()` на доступность страниц.
-## 9. Заметки для v2
-* **Прогрессивный показ**: отрисовать первую страницу (первые ~30 сегментов) ДО завершения полной подготовки; остальное доиндексировать дальше или по мере прокрутки. Процент и `End` показывать как «вычисляется», пока не готов полный `n_lines`. (Синергия с потоковым разбором §4.0: первый экран готов после разбора лишь нескольких КБ.)
-* Разделители переноса Wrap: точка/запятая/`!`/`?`/дефис; правило «новая строка не начинается с разделителя», серия разделителей остаётся на первой строке.
-* Таблицы: вычисление ширины столбцов и выравнивание.
-* Подсветка синтаксиса внутри блоков кода.
-* URL/Images и прочие типы строк.

examples/mdview/mdview — унифицированный рендеринг (Unified Wrap + Paragraph Model).md

@@ -1,90 +0,0 @@
-# mdview — унифицированный рендеринг (Unified Wrap + Paragraph Model)
-
-
-## Цель
-Отказаться от двух режимов Wrap/Unwrap. Ввести единую модель отображения Markdown-документов, соответствующую стандарту CommonMark:
-* Обычный текст: параграфы склеиваются по soft breaks (`\n` → пробел), перенос по словам на 80 колонок.
-* Hard break (`  \n`): принудительный перенос внутри параграфа.
-* Paragraph break (`\n\n`): новый абзац (пустая строка между блоками).
-* Fenced code block и таблицы (будущее): не переносятся, работают как truncate + горизонтальный скроллинг + индикатор `>`.
-* Горизонтальный скроллинг активен только когда в текущем viewport есть nowrap-строки.
-
-## Текущее состояние
-* `mdview.c` использует `wrap_mode` (0 = truncate, 1 = wrap) и `toggle_wrap()` (F2).
-* `index_lines()` делает два разных прохода: truncate (1 строка файла = 1 строка экрана) и wrap (сегментация по SCREEN_W).
-* `render_line()` имеет ветвление по `wrap_mode` и `cont`.
-* `line_offset[]`, `cont_flag[]`, `in_code[]`, `init_style[]` — существующие структуры.
-
-## Предлагаемые изменения
-
-### 1. Новые структуры данных
-* Добавить `nowrap_flag[]` (битмап, аналогично `cont_flag[]`): строка не должна переноситься (code block, HR, таблица).
-* Добавить `line_kind[]` (2 бита на строку, 512 байт для 2048 строк): хранит классификацию (PLAIN, H1-H4, HR, ULIST, OLIST, QUOTE, CODE, TABLE). Нужен для continuation-сегментов, чтобы render_line знал, какой префикс/отступ повторять.
-* Убрать `wrap_mode` и `toggle_wrap()`.
-* Убрать truncate-ветку из `index_lines()` и `render_line()`.
-* `viewport_x` остаётся глобальным, но применяется только к `nowrap` строкам.
-
-### 2. Новый `index_lines()` — paragraph scanner
-Единый проход по файлу, без двух режимов.
-
-#### 2.1 Сканирование «сущностей»
-Walk по файлу от `p = 0` до `file_size`:
-1. Если `fb(p) == '`' × 3 → Fenced code block. Все строки до закрывающего ` ``` ` — `nowrap_flag = 1`, `in_code = 1` (для body), `line_kind = CODE`. Длинные строки не wrap'аются.
-2. Если строка начинается с `|...|` (будущее) → Table. `nowrap_flag = 1`, `line_kind = TABLE`.
-3. Если строка — HR (`---`/`***`/`___`) → `nowrap_flag = 1`, `line_kind = HR`. 1 строка экрана.
-4. Если строка — Header (`#...`), List (`- ` / `* ` / `+ ` / `N. ` / `N) `), Quote (`> `) → начало **Normal paragraph / block**. Обрабатывается как единый параграф до `\n\n` или EOF или code block.
-5. Иначе — Normal paragraph (plain text).
-
-#### 2.2 Normal paragraph — обработка
-Внутри параграфа символы читаются как единый поток (не прерываясь на `\n`):
-* `\n\n` → конец параграфа. Emit текущую сегментную строку (если есть). Добавить пустую строку (1 строка экрана с нулевой длиной, или offset указывающий на второй `\n`).
-* `  \n` (два пробела или таб + пробел перед `\n`) → **Hard break**. Emit текущую сегментную строку. Начать новую сегментную строку с того же абзаца, **сохранив `line_style`**. `prev_ch = ' '`.
-* Обычный `\n` → **Soft break**. Считаем как 1 пробел: `visible col++`, `prev_ch = ' '`. Продолжаем текущую сегментную строку.
-* Wrap at `SCREEN_W` — так же как сейчас, по `last_space`. При создании continuation-сегмента: `set_cont()`, `set_init_style_raw()` (carry emphasis), `set_line_kind()` (carry list/quote kind для отступа/префикса).
-* Emphasis tracking (`line_style`) работает через весь параграф, через soft/hard breaks.
-
-#### 2.3 Fenced code block — обработка
-* Delimiter строка (`  `): `line_kind = CODE`, `nowrap_flag = 1`, рендерится как пустая строка (или строка с `  ` — но сейчас пустая).
-* Body строки: каждая физическая строка = 1 строка экрана. `nowrap_flag = 1`, `in_code = 1`, `line_kind = CODE`. Нет inline parsing, нет wrap.
-* Если строка длиннее `SCREEN_W` — truncation (не wrap). `render_line()` рисует `>` в последней колонке, если есть content за пределами `SCREEN_W + viewport_x`.
-
-#### 2.4 List continuation
-* Первая строка list item: `line_kind = ULIST/OLIST`, `marker_visible_col` определяет отступ. Текст начинается после маркера.
-* Wrap внутри list item: `set_line_kind()` = тот же `ULIST`/`OLIST`. `render_line()` для continuation-сегмента не рисует маркер, но добавляет отступ = `marker_visible_col` (т.е. количество пробелов до текста первой строки).
-* Для вложенных списков отступ растёт, потому что `marker_visible_col` учитывает ведущие пробелы.
-
-#### 2.5 Quote continuation
-* Первая строка quote: `line_kind = QUOTE`, `marker_visible_col` = отступ + 2 (для `│ `).
-* Wrap внутри quote: `set_line_kind()` = `QUOTE`. `render_line()` для continuation рисует префикс `│ ` (или пробелы, если символ не нужен на всех кроме первой строки).
-
-### 3. Изменения в `render_line()`
-* Убрать ветку `if (!wrap_mode)` (truncate mode больше не существует).
-* Добавить `if (is_nowrap(line_idx))`: применяется `viewport_x`, отображается `>` в колонке 79 если контент выходит за пределы.
-* Для `cont` сегментов (wrap continuation):
-    * Если `line_kind` == `QUOTE`: повторить префикс отступа + `│ ` (или только отступ, если решено показывать `│` только на первой строке).
-    * Если `line_kind` == `ULIST`/`OLIST`: повторить отступ = `marker_visible_col` (без маркера/цифр). Текст начинается с той же колонки, что и на первой строке item.
-    * Для plain text: просто продолжить текст без префиксов.
-* Для `nowrap` строк: применять `viewport_x` как смещение. Текст сдвигается влево, скрытые символы не рисуются. Если за пределами видимой зоны есть ещё контент — `>` в колонке 79.
-
-### 4. Горизонтальный скроллинг
-* `scroll_h()` проверяет: есть ли в текущем viewport (top_line .. top_line+VIEW_H-1) хотя бы одна строка с `nowrap_flag == 1`. Если нет — return (no-op).
-* Для `nowrap` строк `render_line()` использует `viewport_x` при отображении: символы с `cc < viewport_x` пропускаются, `cc >= viewport_x` рисуются.
-* Для wrap-строк `viewport_x` игнорируется (эффективно = 0).
-* При `Home`/`End`/`PgUp`/`PgDn`/`Up`/`Down` — `viewport_x` не сбрасывается (пользователь может скроллить по вертикали, оставаясь на горизонтальном смещении для code block).
-
-### 5. Очистка и навигация
-* Убрать `wrap_mode`, `toggle_wrap()`.
-* Убрать F2 из меню и help.
-* `scroll_up`/`scroll_down`/`scroll_h`/`clamp_top` — обновить без ссылок на `wrap_mode`.
-* `calc_pct` и статусная строка — обновить, убрать ссылку на wrap/unwrap.
-
-### 6. Порядок реализации (по файлу mdview.c)
-1. **Структуры данных**: добавить `nowrap_flag[]`, `line_kind[]`, убрать `wrap_mode`.
-2. **`index_lines()`**: полностью переписать в paragraph scanner. Это самый сложный и объёмный блок.
-3. **`render_line()`**: убрать truncate, добавить nowrap/quote/list continuation, добавить `viewport_x` для nowrap.
-4. **`scroll_h()`**: добавить проверку наличия nowrap в viewport.
-5. **Очистка**: убрать toggle_wrap, обновить меню/help, обновить main() (убрать F2).
-6. **Тестирование**: soft breaks, hard breaks, paragraph breaks, emphasis через soft breaks, fenced code blocks, list wrap с отступом, quote wrap с префиксом, горизонтальный скролл только для code.
-
-## Orchestration
-План реализуется одним агентом (последовательно в одном файле), параллелизм не требуется. Дочерние агенты не используются.

examples/mdview/todo2

@@ -1,180 +0,0 @@
-Новое требование к первоначальной подготовке документа.
-
-Правила форматирования и показа -
-1) Деление на параграфы. Параграфы разделяются пустыми строками.
-2) Заголовки H1-H6 - отдельные параграфы (после них всегда пустые строки)
-3) Разделители 	(---) - тоже - после них всегда пустые строки.
-4) Таблица/код (через ```)/списки - это единый параграф. 
-
-Типы текста (строк) -
-
-Обычный текст
-
-Может в оригинале находиться на нескольких строках. 
-Строки могут разделяться 
-- обычный break - это когда на строке после текста идет перевод строки - 
-такой текст просто объединяется (в нашем случае если возможно то следующая строка продолжает 
-выводиться на той же строке что и предыдущая, только отделяется от нее уже не переводом строки
-а через пробел.
-- широкий break - это когда перед переводом строки есть два или более пробелов или перед переводом
-строки находится символ обратный слэш '\' - в этом случае и когда мы выводим текст на экран следующая 
-строка начинается с новой строки.
-- жесткий break - это когда две строки обычного текста разделяются двумя или более переводами
-стрки (то есть между ними как минимум есть одна пустая строка) - в этом случае вторая строка
-будет считаться новым параграфом и отделяться от предыдущей строки ОДНОЙ пустой строкой (вне
-зависимости от того сколько пустых строк в оригинале.
-Должно сохраняться действие модификатора bold/italic/strike начатое на одной строке на следующие
-если они так же находятся в этом параграфе. Новый параграф (после пустой строки) теряет воздействие
-незакрытого модификатора из предыдущего параграфа.
-Тип переноса строк - Wrap.
-
-Заголовки - 
-
-абзацы из одной оригинальной строки. Начальный стиль зависит от типа заголовка (в нем могут встречаться
-модификаторы bold/italic/code/strike. 
-Тип переноса строк - Wrap.
-
-Разделитель (horizontal rules) -
-
-Всегда одна строка. После нее выводим пустую строку всегда (следующий текст - новый абзац)
-
-Списки  
-
-как и в обычном тексте - один пункт списка может находиться в оригинале на нескольких строках.
-если появляется новая строка с префиксом пункта списка - это означает что с этой строки начинается
-новый пункт списка. если появляется пустая строка - это означает что следующая за пустой строкой
-непустая строка уже не является продолжением пункта списка.
-Если следующая за пустой строкой строка так же является пунктом списка то такая строка считается
-продолжением текущего списка. Только если две строки списков разделены ДВУМЯ и более пустыми 
-строками то вторая строка с пунктом списка будет считаться началом нового списка -
-Пример -
-
-- строка 1
-- строка 2
-строка 3
-- строка 4
-
-- строка 5
-
-
-- строка 6
-
-Должно отображаться так -
-
-- строка 1
-- строка 2 строка 3
-- строка 4
-- строка 5
-
-- строка 6
-
-Тип переноса строк - Wrap.
-Замечание - перенесенная строка продолжение пункта списка должна начинаться с отступа в 
-несколько пробелов (для списка первого уровня - два пробела) - то есть с той же позиции 
-что и начальный текст строки - 
-Пример -
-
-- длинная строка которая не может поместиться и будет перенесена по слову 'будет'
-
-Должно отображаться так -
-- длинная строка которая не может поместиться и 
-  будет перенесена по слову 'будет'
-
-Незакрытые модификаторы типа (bold/etc.) не переносят свою модификацию не последующие пункты списка.
-Действуют только в пределах одного пункта.
-(то есть фактически - пункт списка - это отдельный параграф но следующий пункт списка (тоже отдельный
-параграф) не отделяется от него пустой строкой.
-Вложенные списки - поддерживаются.
-Для отображения префиксов пунктов списка используется свой стиль. Так же для текста списков используется
-отдельный (от обычного текста) стиль. 
-
-Блок Кода -
-
-Весь блок кода отображается только одним стилем - стилем Кода. В нем не действуют модификаторы
-bold/italic/etc (возможно в дальнейшей использование парсера языка для кода что бы отобразить
-этот код с подсветкой синтаксиса этого языка, но сейчас весь блок рисуется только одним стилем)
-После блока кода - обязательна пустая строка.
-Тип переноса строк - UnWrap. - То есть строки НЕ ПЕРЕНОСЯТСЯ.
-
-Quoted -
-
-Отображается как отдельный параграф. Перед отображением текста отображается символ префикса Цитирования
-Способы переноса текста аналогичны обычному тексту, за исключение того что перенесенные строки так же
-предваряются префиксом Цитирования
-Для отображения префиксов Цитирования используется свой стиль. Так же для текста цитирования используется
-отдельный (от обычного текста) стиль. 
-Тип переноса строк - Wrap.
-Пример форматирования -
-
-> Первый параграф
->
-> Второй параграф
-> > Вложенный параграф
->
-> Продолжение основной цитаты - длинная строка (переносится по слову 'строка')
-
-Будет отображаться так -
-| Первый параграф
-|
-| Второй параграф
-| | Вложенный параграф
-|
-| Продолжение основной цитаты - длинная 
-| строка (переносится по слову 'строка')
-
-
-Таблицы -
-
-Пока отображаются as is.
-Дальше возможно предусмотрим вариант вычисления ширины столбцов и форматирование
-вывода что бы все ячейки столбца имели одинаковую ширину.
-Тип переноса строк - UnWrap.
-
-Типы переноса строк -
-
-Wrap -
-
-происходит перенос текста с одной строки на другую по разделителям пробелам (предусмотреть 
-во второй версии возможность использовать разделителем знаков точка, запятая, восклицательный 
-знак, вопросительный знак, дефис. Замечание - новая строка не может начинаться со знаков 
-разделителей - то есть если у нас идет многоточие (три точки) то нельзя что бы одна точка 
-была в конце первой строки а остальные две на другой - если идут несколько разделителей подряд 
-то они считаются как один и должны оставаться на первой строке).
-
-UnWrap -
-
-Текст НЕ ПЕРЕНОСИТСЯ.
-Если строка не помещается на экране - то в конец строки на экране выводим символ-знак наличия
-продолжения строки справа за краем экрана (свой стиль для этого символа).
-Символ '>'.
-Если есть хотя бы одна строка которая не помещается на экране - то разрешаем горизонтальный
-скроллинг.
-ЗАМЕЧАНИЕ - скроллируется только текст выводящийся в режиме UnWrap. 
-Если произведен скроллинг влево (строки UnWrap начинаются показываться не с первой позиции)
-то на первой позиции отображем другой символ '<' сообщающий пользователю что есть текст
-за левым краем экрана.
-Скроллирование не бесконечно - если на экране нет строк UnWrap для которых есть скрытый текст
-за правым краем экрана то скроллирование влево больше не возможно, и наоборот - если при 
-скроллировании вправо дошли до показа строк UnWrap с первой позиции то дальше скроллинг в этом
-направлении так же невозможен. Скроллинг идет с грануляцией по 8 символов.
-(сейчас UnWrap текст это только блоки кода и таблицы).
-
-
-Проанализируй данную постановку задачи.
-
-Что требуется -
-
-Мы более не поддерживаем два режима показа - Wrap/UnWrap - только один (смешанный).
-Потому вопрос - надо ли нам сохранять оригинальный контент считанного файла с диска ?
-Или при подготовке данных считываемых с диска можно сразу преобразовывать его в формат
-готовый для показа (объединять строки в одном параграфе и так далее) ?
-Ограничения - не забывать о том что это все работает на компьютере с 8-ми битным процессором.
-Потому очень экономно относимся к памяти и лишней работе процессора - все должно быть весьма
-быстрым и компактным.
-Требования для работы с файлами 128 Кб сохраняется.
-
-Для версии 2 - 
-Подумай о возможности использования банков памяти не только для содержимого файла а например 
-для буферов типа line_offset/init_style и прочих (тогда их размер может так же быть динамическим
-и чем больше банков памяти будет использовано для чтения файла тем больше станут размеры этих
-буферов.

examples/mdview2/Makefile

@@ -1,49 +0,0 @@
-# Build mdview2.exe — Markdown viewer for Sprinter (render-cache version).
-#
-# Фаза 0: скаффолдинг — копия mdview.c как baseline, без изменений
-# логики. План — docs/mdview2-plan.md.
-#
-# small memory mode: code in W1, data/stack/heap in W2 (32 KB total).
-# W3 stays free for the file buffer (EMM-mapped).
-
-PROJ_ROOT  := $(abspath $(CURDIR)/../..)
-EXAMPLE    := mdview2
-MEMORY     := small
-
-include $(PROJ_ROOT)/app.mk
-
-# ------------------------------------------------------------------
-# Образ дискеты: только mdview2.exe + README.MD (перекодированный
-# из UTF-8 в CP866 — рабочую кодировку Sprinter).
-#
-# README.MD хранится в репозитории в UTF-8; iconv -c конвертирует
-# его в CP866, отбрасывая символы без аналога в целевой кодировке.
-# Результат кладётся в .disk_tmp/README.MD, чтобы make_disk.py
-# использовал правильное имя файла на диске.
-#
-# iconv -c возвращает ненулевой код, если хоть один символ отброшен
-# (даже с -c) — это ОЖИДАЕМО при потере символов без аналога в CP866,
-# не ошибка конвертации; вывод при этом всё равно корректно записан.
-# Поэтому код возврата iconv игнорируется (|| true).
-# ------------------------------------------------------------------
-DISK_TMP    := .disk_tmp
-README_DISK := $(DISK_TMP)/README.MD
-
-$(DISK_TMP):
-	mkdir -p $@
-
-$(README_DISK): README.MD | $(DISK_TMP)
-	iconv -c -f UTF-8 -t CP866 README.MD > $@ || true
-
-# UTF8TEST.MD кладётся на диск КАК ЕСТЬ (в UTF-8, без перекодировки) —
-# это тестовый вход для проверки UTF-8 рендеринга (Фаза 2 кодировок).
-floppy: $(EXAMPLE).exe $(README_DISK)
-	python3 $(MAKE_DISK) $(FLOPPY_IMG) $(EXAMPLE).exe $(README_DISK) UTF8TEST.MD
-	@echo
-	@echo "Floppy ready: $(FLOPPY_IMG)"
-	@echo "Run:  cd $(MAME_DIR) && ./run_mame.sh"
-
-clean:
-	rm -rf .sprinter-cc-* $(EXAMPLE).exe $(DISK_TMP)
-
-.PHONY: all clean floppy run

examples/mdview2/README.MD

@@ -1,799 +0,0 @@
-# MDView — Просмотрщик Markdown для Sprinter
-
-**MDView** — программа для просмотра документов в формате *Markdown* на компьютере
-Sprinter (процессор Z80). Документ хранится в отдельном W3 окне и не занимает
-основную RAM программы.
-
-## Возможности
-
-- Документы до **128 КБ** (8 страниц EMM по 16 КБ каждая)
-- До **16 384** экранных строк в индексе
-- Автоматический перенос слов по ширине экрана (80 столбцов)
-- Горизонтальный сдвиг для широких строк (блоки кода, таблицы)
-- Статус-бар: имя файла, диапазон строк, процент прокрутки
-- Спиннер в строке состояния во время загрузки и индексации
-- Поддержка «мягкого» склеивания строк в абзацах и цитатах
-
-## Запуск
-
-```
-mdview [имя_файла.md]
-```
-
-Если имя файла не задано, загружается `README.MD`.
-
-## Управление
-
-```
-Клавиша        Действие
-─────────────  ────────────────────────────────────────
-Up  Down       Прокрутка на одну строку вверх / вниз
-PgUp  PgDn     Прокрутка на страницу (30 строк)
-Home           Начало документа
-End            Конец документа
-Left Right     Горизонтальный сдвиг (только nowrap-строки)
-F1             Окно справки
-F8             Кодировка: CP866 → CP1251 → KOI8-R → UTF-8 → ...
-F10 / Esc      Выход из программы
-```
-
-Кодировка определяется автоматически при открытии (BOM + эвристика по
-первым 4 КБ); `F8` переключает её вручную, если детекция ошиблась.
-8-битные кодировки (CP866/CP1251/KOI8-R) переключаются мгновенно (ремап на
-отрисовке). Второй набор индекс/кэша (например UTF-8) строится лениво — при
-первом переключении в него (короткая пауза со спиннером), дальше мгновенно.
-
-## Синтаксис Markdown
-
-### Заголовки
-
-Поддерживаются уровни H1–H4. Уровни H5 и H6 отображаются как H4.
-
-    # Заголовок первого уровня  
-    ## Заголовок второго уровня  
-    ### Заголовок третьего уровня  
-    #### Заголовок четвёртого уровня  
-
-### Текстовое форматирование
-
-**Жирный текст** выделяется двойными звёздочками: `**текст**`
-
-*Курсив* выделяется одиночными звёздочками `*текст*` или знаком подчёркивания `_текст_`
-
-`Встроенный код` обозначается обратными кавычками
-
-~~Зачёркнутый текст~~ — двойные тильды: `~~текст~~`
-
-### Ненумерованный список
-
-Маркеры `-`, `*` или `+`:
-
-- Первый пункт списка
-- Второй пункт списка
-- Третий пункт с достаточно длинным текстом, который при необходимости
-  будет перенесён на следующую строку с сохранением отступа
-
-### Нумерованный список
-
-1. Первый элемент
-2. Второй элемент
-3. Третий элемент
-
-### Цитата
-
-> Блок цитаты начинается с символа `>`. Несколько последовательных
-> строк одной цитаты склеиваются в единый абзац с автоматическим
-> переносом слов.
-
-### Блок кода (verbatim)
-
-Блок кода заключается в тройные обратные кавычки. Внутри блока
-текст отображается «как есть» без разбора Markdown:
-
-```
-#include <stdio.h>
-#include <sprinter.h>
-
-int main(void) {
-    puts("Hello, Sprinter!");
-    return 0;
-}
-```
-
-### Горизонтальная линия
-
-Три или более символов `---`, `***` или `___` на отдельной строке:
-
----
-
-## Технические характеристики
-
-- **Платформа:** Sprinter, процессор Z80 @ 21 МГц
-- **Кодировки:** CP866 / CP1251 / KOI8-R / UTF-8 (автоопределение, `F8`)
-- **Максимальный размер файла:** 128 КБ
-- **Максимальное число строк в индексе:** 16 384
-- **Режим памяти:** small
-  - Код программы, cтек, данные, куча — окнa W1-W2 (32 КБ, адреса 0x4000–0xBFFF).
-  - Буфер файла — страницы EMM, отображаемые в W3 (0xC000–0xFFFF)
-
-## TODO
-
-1. **Увеличение размера документов.** Снять лимит 128 КБ: Достаточно
-   разрешить работать с большим кол-вом страниц памяти, пока оттестированно
-   на работе с 8-мю страницами по 16Кб.
-
-Сделано: форматированные таблицы с рамкой; поддержка кодировок
-CP866 / CP1251 / KOI8-R / UTF-8 с автоопределением и переключением по `F8`
-(второй набор строится лениво, по первому переключению).
-
-4. **Ускорение рендеринга.** Кэш строк экрана. Оптимизация цикла вывода
-   символов через BIOS WRCHAR (пакетный вывод, DMA).
-
----
-
-*MDView v0.2 · (c) 2026 Петров А.Г.*
-
-
----
-
-# Sprinter C Compiler — v1.0
-
-C toolchain for **Sprinter** — the Z80-based home computer by Peters Plus, running
-ESTEX DSS.  Host: macOS / Linux.  Target: `.EXE` files in SprintEXE format.
-
-Built on top of **SDCC 4.5** (vendored in `third_party/sdcc/`).  This repository adds
-everything Sprinter-specific: crt0, linker integration, libc wrappers over ESTEX,
-banked-call trampolines, graphics & accelerator API, mouse driver wrappers, and the
-`mkexe` utility for producing SprintEXE images.
-
-## What you get
-
-* **`bin/sprinter-cc`** — one-line driver: `sprinter-cc -o foo.exe foo.c`
-* **Memory modes**: `tiny`, `small`, `big`, `huge`, `manual` — see below.
-* **stdio + conio**: printf, puts, putchar, getchar, fopen/fread/..., cprintf, cputs, putch, textcolor/textbackground/textattr, gotoxy, kbhit/getch.
-* **Graphics**: 320×256×256 and 640×256×16 modes, accelerator-backed primitives (hline / vline / rect / fill_rect / line via Bresenham, plus clear), bitmap-font text in both modes via BIOS character generator.
-* **File I/O**: POSIX (`open`/`read`/`write`/`close`/`lseek`/`unlink`/`creat`), FILE\* streams (`fopen`/`fgets`/`fwrite`/...), directory listing (`ffirst`/`fnext`), `chdir`/`getcwd`/`mkdir`/`rmdir`, `stat`/`fstat`.
-* **Memory**: 32 KB heap (W2-resident), banking-aware page allocator (`mem_alloc_pages`/`bank_read`/`bank_write`), explicit memory modes for sub-16 KB programs.
-* **Mouse**: full Sprinter driver wrapper (14 functions including custom cursor bitmaps).
-* **Environment**: `getenv`/`putenv`/`sysenv` over ESTEX `$46`.
-* **Time**: `getdatetime`/`setdatetime` + POSIX `time`/`localtime`/`mktime`/`asctime`/`ctime`.
-* **Misc**: `errno`/`strerror`/`perror`, `atexit`, `setjmp`/`longjmp`, `sleep`, full argv parsing in crt0.
-
-## Quick start
-
-```sh
-git clone <this repo> sprinter-c
-cd sprinter-c
-make sdcc                      # one-time: fetch SDCC 4.5 binary (~25 MB)
-make all                       # build mkexe + libsprinter.lib + 27 examples
-make floppy                    # pack everything into mame/v306/IMG/mc.img
-cd mame/v306 && ./run_mame.sh  # boot Sprinter in MAME
-```
-
-Compile a single program:
-
-```sh
-cat > hello.c <<EOF
-#include <stdio.h>
-int main(void) { puts("Hello, Sprinter!"); return 0; }
-EOF
-
-bin/sprinter-cc -o hello.exe hello.c
-```
-
-That's it — `hello.exe` is now a valid SprintEXE you can `RUN HELLO` from the ESTEX shell.
-
-## Memory modes
-
-Sprinter's address space is four 16 KB windows (W0 / W1 / W2 / W3).  DSS allocates
-pages by program size — small programs get only one page.  Pick a memory mode based
-on what your program needs:
-
-| Mode | Code lives in | Banking | Use when | Note |
-|---|---|---|---|---|
-| `tiny`  (default) | W2 (0x8100+) | no | code+data < 14 KB | |
-| `small` | W1-W2 (0x4100+) | no | code+data < 30 KB | |
-| `big`   | W2 + W1 banking | yes (W1) | tiny + extra code modules | |
-| `huge`  | W1-W2 + W3 banking | yes (W3) | small + extra code modules | |
-| `manual` | user-specified | optional | special layouts | Not implemented |
-
-```sh
-sprinter-cc --memory small  -o big.exe   bigprog.c
-sprinter-cc --memory huge   -o app.exe   main.c --bank 1=engine.c --bank 2=ai.c
-```
-
-Banked functions are declared with `__banked`:
-
-```c
-void engine_tick(int dt) __banked;   // lives in BANK1, automatically swapped
-```
-
-## Examples (27 total)
-
-| Example | What it demonstrates |
-|---|---|
-| `hello`    | Hello world with stdio + conio Turbo-C-style colors |
-| `argv`     | argv parsing in crt0 |
-| `cat`      | File I/O — read & print TEST.TXT |
-| `seek`     | 32-bit lseek over a 100 KB file |
-| `ls`       | Directory listing via ffirst/fnext |
-| `filetest` | FILE\* streams (fopen/fread/...) |
-| `stattest` | `stat`/`fstat` on files and directories |
-| `errno`    | errno / strerror / perror |
-| `mem_test` | Page allocator + bank\_read/bank\_write |
-| `malloc`   | Heap stress test (200+ allocations) |
-| `banked`   | Banked code in W3 (huge mode) |
-| `bankedbg` | Banked code in W1 (big mode) |
-| `banklocl` | Bank-local static data and BSS |
-| `mouse`    | Mouse driver in text mode |
-| `gfx_mous` | Mouse with custom bitmap cursor in graphics mode |
-| `gfx_demo` | 320×256×256 lines / rects / accelerator |
-| `gfx_d16`  | 640×256×16 same primitives |
-| `gfx_text` | Bitmap-font text on graphics screen |
-| `timedir`  | Date/time + directory listing |
-| `ptime`    | POSIX time API |
-| `openenv`  | open() flags + environment vars |
-| `conio`    | conio API smoke test |
-| `attrprob` | Probe Sprinter text attribute byte layout |
-| `strtest`  | string.h test (from SDCC's z80.lib) |
-| `stdlib`   | stdlib.h test (qsort / rand / strtol / etc.) |
-| `assrtest` | assert() |
-| `rt_test`  | Runtime helpers (sleep, setjmp, atexit) |
-
-## Headers
-
-Standard:
-* `<stdio.h>` — puts / printf / FILE\* + Sprinter-specific dec/hex helpers
-* `<stdlib.h>` — atoi / atof / malloc / qsort / ... (from SDCC z80.lib)
-* `<string.h>` / `<ctype.h>` / `<math.h>` — from SDCC z80.lib
-* `<unistd.h>` — read / write / close / lseek / unlink
-* `<fcntl.h>` — open / creat + O\_RDONLY / O\_CREAT / ...
-* `<errno.h>` — errno + error names + strerror
-* `<sys/stat.h>` — stat / fstat
-* `<setjmp.h>` / `<assert.h>` — from SDCC
-
-Sprinter-specific:
-* `<conio.h>` — putch / cputs / cprintf, textcolor / textbackground / textattr, kbhit / getch, clrscr, gotoxy, wherex/y
-* `<gfx.h>`   — gfx_init/done, palette, putpixel, hline/vline/rect/fill_rect/line, text — for both 320 and 640 modes (gfx_\*16 variants)
-* `<mouse.h>` — full 14-function driver wrapper + mouse_cursor_t with bitmap support
-* `<dir.h>`   — chdir / getcwd / mkdir / rmdir / ffirst / fnext / ffblk
-* `<time.h>`  — getdatetime / setdatetime + POSIX time / localtime / etc.
-* `<sprinter.h>`      — raw ports, ESTEX/BIOS function numbers, env API
-* `<sprinter_exit.h>` — exit / \_exit / atexit
-* `<sprinter_mem.h>`  — mem\_alloc\_pages / mem\_free\_block / bank\_read / bank\_write
-* `<sprinter_compat.h>` — Solid-C compatibility layer (aliases + BOOL/WORD/uint types)
-
-## Toolchain commands
-
-```sh
-make all              # build mkexe + lib + every example
-make floppy           # repack mame/v306/IMG/mc.img with all .exe files
-make check            # 17 mkexe unit-tests
-make clean            # remove all build artefacts
-make sdcc             # one-time: fetch SDCC 4.5 binary
-```
-
-### sprinter-cc options
-
-```
-sprinter-cc -o foo.exe foo.c [more.c ...] [options]
-
-  --memory MODE           tiny | small | big | huge | manual    (default: tiny)
-  --memory-manual SPEC    explicit placement (CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3)
-  --stack-size N          bytes reserved for the stack (default ~1278)
-  --crt0=TYPE             default | minimal | banked | small
-  --bank N=FILE.c         compile FILE.c into bank N (repeatable, max 15)
-  --debug                 enable runtime diagnostics (defines DEBUG_RT)
-  -I PATH                 extra include path
-  -L 0xADDR / -E / -S     override load / entry / stack addresses
-  -Wl FLAG                pass FLAG to sdldz80
-  --mkexe FLAG            pass FLAG to mkexe (e.g. --mkexe -p --mkexe 0 for bank padding)
-  -v                      verbose
-```
-
-## Status
-
-What works in v1.0:
-* Compile / link / pack to SprintEXE — verified on all 27 examples
-* Four memory modes (tiny / small / big / huge)
-* Graphics (both modes) with accelerator
-* Mouse (text + graphics cursor)
-* File I/O, directories, environment, time
-* All headers listed above
-
-Deferred to v2.0 (see `docs/TODO.md`):
-* **Turbo-C-style BGI graphics API** — `initgraph` / `setcolor` / `circle` /
-  `getimage` / `putimage` / etc. on top of our `gfx_*` primitives
-* Remaining Solid-C compatibility gaps (Phase 2/3) — see `docs/solid_c_compatibility.md`
-* Manual memory mode
-* Rewrite FILE\* stream API (current implementation is very primitive and doesn't use buffers)
-
-Deferred to v3.0:
-* **IM2 interrupt handlers** — research complete (`docs/im2_isr_design.md`),
-  implementation scheduled for v3
-* **Audio API** (AY-3-8910 + COVOX) — requires IM2
-* **ISA-8 slot drivers** — requires IM2 (???)
-
-## Documentation
-
-* `docs/TODO.md` — roadmap and open work items
-* `docs/solid_c_compatibility.md` — gap analysis vs Solid-C 2004
-* `docs/im2_isr_design.md` — interrupt handler design (v2)
-* `docs/converted/` — source documentation (ESTEX, BIOS, architecture)
-  converted to plain text for `grep`
-* `docs/reference/`, `docs/samples/`, `docs/memory management/` — original
-  Russian docs and code samples from Peters Plus
-
-## Repository layout
-
-```
-bin/sprinter-cc           one-line compiler driver (bash)
-toolchain/mkexe/          host-side tool: .ihx -> .exe SprintEXE
-toolchain/check_banks.py  post-link bank size enforcer
-runtime/                  crt0 variants (default, minimal, small, banked)
-                          bank trampolines, heap, heap_top
-libc/include/             headers
-libc/io|stdio|mem|gfx/    C and asm sources for libsprinter.lib
-lib/                      Makefile that archives libsprinter.lib via sdar
-examples/                 27 example programs
-mame/v306/                MAME binary + Sprinter ROM/HDD images + floppy script
-third_party/sdcc/         vendored SDCC 4.5 (fetched via `make sdcc`)
-third_party/solid-c/      reference: original Sprinter native C (for compat target)
-docs/                     documentation
-```
-
-## License
-
-This repository contains:
-* Original code in `bin/`, `toolchain/`, `runtime/`, `libc/`, `lib/`, `examples/` —
-  MIT-licensed.
-* `third_party/sdcc/` — SDCC 4.5 under GPLv2 with linking exception
-  (see `third_party/sdcc/COPYING.txt`)
-* `third_party/solid-c/` — original Sprinter Solid C, used only as a reference
-
-## Credits
-
-* **Sprinter / Peters Plus** — Иван Мак, Дмитрий Паринов and the original team
-* **SDCC** — for the underlying Z80 compiler
-* **MAME** — for the Sprinter Sp2000 emulation
-
----
-
-For questions / patches: see CONTRIBUTING.md (TBD) or open an issue.
-
----
-
-# TODO / Roadmap
-
-Открытые задачи в порядке убывания приоритета. По мере появления реальных программ — приоритеты будут смещаться.
-
-## Этап 5 — malloc / free + banking-aware page allocator ✅ ГОТОВО
-
-- [x] SDCC's `malloc`/`free` + наш `runtime/heap.s` (полностью заменяет library heap.rel, 14000-байтный heap в окне 2)
-- [x] `libc/mem/mem_alloc.c` — page allocator: `mem_alloc_pages`/`mem_free_block`/`mem_get_page`/`mem_info` через ESTEX `$3C/$3D/$3E` + BIOS `$C4`
-- [x] `libc/mem/bank_io.c` — HOME-резидентные `bank_read`/`bank_write`/`bank_load_byte`/`bank_store_byte` со свопом W3 внутри
-- [x] `examples/malloc_test/` — проверка SDCC's malloc (~210 64-байтных allocations через всю heap)
-- [x] `examples/mem_test/` — проверка page allocator: 3 страницы, разные паттерны через bank_write, верификация через bank_read
-
-## Этап 6 — argv parsing + sprinter-cc wrapper ✅ ГОТОВО
-
-- [x] crt0 парсит ESTEX command-line из IX-prefix (inline asm в `runtime/crt0.s`)
-- [x] Strip leading CP/M-style space (DSS quirk)
-- [x] Передача `argc`/`argv` в main() через HL/DE (SDCC __sdcccall(1) ABI)
-- [x] argv[0] = basename .EXE через ESTEX APPINFO ($47 subfn 2)
-- [x] `runtime/crt0_minimal.s` — opt-out для очень маленьких программ
-- [x] `runtime/crt0_banked.s` — теперь тоже парсит argv (parse_argv + get_progname скопированы из crt0.s; будет factored в argv.s когда возьмёмся за libsprinter.lib)
-- [x] Bash-обёртка `bin/sprinter-cc`: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций: `--memory`, `--memory-manual`, `--stack-size`, `--crt0=`, `--bank N=FILE.c`, `--debug`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-
-## Этап 8 — графика (320×256×256 + 640×256×16 + accel + bitmap font) ✅ ГОТОВО
-
-- [x] **8a** Graphics core: `gfx_init`/`gfx_done`/`gfx_clear`/`gfx_putpixel`/`gfx_pal_load`/`gfx_pal_set` (libc/gfx/gfx_core.c). Палитра через BIOS PIC_SET_PAL ($A4). Verified 320×256×256.
-- [x] **8b** Линии/прямоугольники/fill через accelerator (libc/gfx/gfx_lines.c): `gfx_hline`/`gfx_vline` через accel Fill (LD C,C / LD E,E + SMC block-size), `gfx_rect`/`gfx_fill_rect` с heuristic выбором ориентации (h/v bursts count), `gfx_line` с Bresenham для диагоналей. `gfx_clear` тоже переписан на column-major accel (~4× быстрее).
-- [x] **8c** 640×256×16 mode (libc/gfx/gfx_16.c): `gfx_*16` API, HIGH nibble = LEFT pixel (документация misleading), per-row RMW для vline (один байт = 2 горизонтальных пикселя).
-- [x] **8d** Bitmap font + gfx_text (libc/gfx/gfx_text.c): шрифт через BIOS WIN_GET_ZG ($B8), interleaved layout `font[row*256+char]`, `gfx_text`/`gfx_putchar` для 320 mode, `gfx_text16`/`gfx_putchar16` для 640 mode с pair-table lookup.
-
-См. memory/sprinter_graphics.md, sprinter_accelerator.md, sprinter_graphics_16.md, sprinter_font_format.md.
-
-Открытые мелочи (не блокируют):
-- [ ] Шрифт-quad для 640: per-cell палитра (mode 0x82 разрешает 1 из 4 палитр per 16×8 cell) — через прямой доступ к area-описания экрана 0x0300..0x039F
-
-## Auto-banking (см. `memory/banking_roadmap.md` для деталей)
-
-Phase 1 — file-level bin-packing — реализовывать когда проект перерастёт ~30 KB кода.
-
-- [ ] `toolchain/auto_bank.py`:
-    - Парсит размеры из `.rel`-файлов (или из .map после dry-run link'а)
-    - First-fit-decreasing bin-packing
-    - Уважает `#pragma codeseg BANKn` как manual override
-    - Перелинковывает с новыми `-Wl-b_BANKn=...` параметрами
-    - Печатает план распределения
-
-Phase 2-5: incremental rebalance, declarative `banks.toml`, function-level, call-graph-aware. Только если/когда понадобится.
-
-## Bank-local static data (mutable data в том же банке что и код) — ✅ ГОТОВО
-
-- [x] Пример `examples/bank_local_data/` — функция в BANK1 со своим writable BSS array + const table + malloc-тест
-- [x] `mkexe -p 0` для нулевого padding банков (BSS-storage обнуляется при загрузке)
-- [x] Канонический рецепт: `--codeseg BANK1 --constseg BANK1 --dataseg BANK1` для bank1.c + `-Wl-b_BANK1=0x1C000` для линковки. **`--dataseg BANK1` РАБОТАЕТ** — раньше казалось обратное из-за trampoline bug который маскировал результат.
-- [x] **Критичный фикс trampoline'a в runtime/bank.s** — старый `pop af; out (n), a` клобберил A → все banked-функции возвращающие uint8_t тихо возвращали мусор. Новый `pop bc; out (c), b` сохраняет A.
-- [x] **malloc из banked-функции работает прозрачно** — heap живёт в W2 (HOME), W2 никогда не свапается trampoline'ом, pointer валиден из любого контекста. См. memory/bank_local_data_pattern.md.
-- [x] Документация в memory: `memory/bank_local_data_pattern.md` (полный рецепт + malloc + nuances), `memory/sdcc_banking.md` (trampoline fix)
-- [ ] Опционально — расширить `check_banks.py` чтобы показывать разбивку size = code + const + bss per bank (cosmetic)
-
-Зачем: для модулей с большим private state (level loader, audio engine, scene data). Экономит W2 heap для динамики, а статика остаётся в бэке.
-
-## Подсказки из solid-c (нативный Sprinter C — `third_party/solid-c/`)
-
-После анализа solid-c'овской libc (см. `memory/solid_c_findings.md`) выявлены готовые паттерны для следующих недостающих функций. Приоритет от **высокого** к низкому:
-
-### High-priority gaps (легко портировать, большая польза)
-- [x] **`errno` + `strerror`/`perror`** — табличка 32 ошибок (libc/io/errno.c)
-- [x] **Расширенный `open()`** для O_CREAT/O_TRUNC/O_APPEND/O_EXCL state machine
-- [x] **`atexit`** — 8-callback LIFO + `exit()` + `_exit()` (libc/io/atexit.c)
-- [x] **`setjmp`/`longjmp`** — 6-байт jmp_buf={sp,ix,pc} (libc/io/setjmp.c)
-- [x] **`sleep(seconds)`** — 50Hz halt-loop (libc/io/sleep.c)
-- [x] **ESTEX ENV API** ($46, getenv/putenv) — libc/io/env.c. Учли doc-bug: реально A=0 это NOT FOUND
-
-### Medium-priority (нужно для shell-like утилит)
-- [ ] **Mouse driver** — `rst $30h`, 17 функций. **Сначала тест что работает в MAME**.
-- [x] **`ffirst`/`fnext` + ffblk_t struct** для directory listing — реализовано, demo: ls.exe
-- [x] **`getdatetime`/`setdatetime`** через ESTEX $21/$22 — libc/io/time.c, demo: time_dir_test
-- [x] **`chdir`/`getcwd`/`mkdir`/`rmdir`** — wrappers для ESTEX $1B-$1E — libc/io/fsdir.c
-- [x] **conio: `kbhit`/`getch`/`getche`/`cputs`/`clrscr`/`gotoxy`** — реализовано
-- [x] **conio extras**: `wherex`/`wherey` ($53), `wrchar`/`rdchar` ($58/$57), `textmode_get/set` ($50/$51), `clrscr_attr` ($56) + COLOR macros
-
-### Low-priority — ✅ FILE* stack ГОТОВО
-
-- [x] **Минимальный unbuffered FILE\*** — `libc/stdio/file.c` + `libc/include/stdio.h`. fopen/fclose/fputs/fgets/fread/fwrite/fseek/ftell/rewind/feof/ferror/clearerr/fflush + stdin/stdout/stderr как pseudo-streams. См. `memory/file_star_design.md` и `examples/filetest`.
-- [ ] fprintf / fscanf — нужна printf-через-callback machinery. Пока пользователь может `sprintf(buf, ...) + fputs(buf, fp)`.
-- [ ] Опциональный buffered mode (setvbuf, line/block buffering) — если когда-то понадобится.
-
-### POSIX time API — ✅ ГОТОВО
-- [x] `libc/io/posix_time.c` — time/localtime/gmtime/mktime/asctime/ctime поверх getdatetime. SDCC's time.rel избегаем (нельзя override _RtcRead). См. `examples/ptime`.
-
-### sys/stat — ✅ ГОТОВО
-- [x] `libc/io/stat.c` — POSIX stat/fstat. Гибрид open+fstat для файлов, ffirst+iter для папок (включая "."/".."). См. `examples/stattest` и `memory/estex_ffirst_dotdot.md`.
-
-### assert — ✅ ГОТОВО (используем SDCC's __assert через fallback include path)
-
-## libc/stdlib — ✅ не нужно делать (см. memory/sdcc_stdlib_works.md)
-
-Проверено через `examples/stdlib_test/`: SDCC z80.lib содержит работающие реализации:
-- `atoi/atol/atof, strtol/strtoul, rand/srand, qsort/bsearch, abs/labs, div/ldiv`
-- Полный `<string.h>` (memchr/cmp/set/cpy, strcat/cmp/cpy/len/chr/spn/etc.)
-- `<ctype.h>` (toupper/tolower)
-- `<math.h>` (sinf/cosf/sqrtf/etc.)
-
-Линкер автоматически тянет из z80.lib когда нужно. **НЕ переписывать**.
-
-Наши Sprinter-specific обязательные модули остаются: atexit, env, errno, setjmp, putchar/puts/getchar, conio, fsdir, time, mouse, open/read/lseek/close.
-
-## Build-system: libsprinter.lib + sprinter-cc — ✅ ГОТОВО
-
-- [x] `lib/Makefile` — собирает каждый libc/*.c в `.rel`, архивирует через sdar в `lib/sprinter.lib`
-- [x] Включает runtime/bank.s и runtime/heap.s (auto-pulled при __banked/malloc)
-- [x] `bin/sprinter-cc` — bash-wrapper: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций `--crt0=default|minimal|banked`, `--bank N=FILE.c`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-- [x] `examples/hello_sccc/` — демо: `hello.c` собирается за один shell-вызов, размер совпадает с ручным Makefile (925 байт)
-- [x] Split `putchar.c` → `putchar.c` + `puts.c` для per-function granularity (puts override SDCC's z80.lib version)
-- [x] Включён в `make all` (зависимость `lib` перед `examples`)
-
-Возможные улучшения (опционально):
-- [ ] Мигрировать остальные examples на sprinter-cc вместо ручных Makefile (косметика)
-- [ ] Дальнейшая декомпозиция libc/*.c per-function (но текущая granularity уже даёт нужный размер — линкер пакетует .rel целиком, и для большинства файлов это одна функция)
-
-## Этап 9 — memory modes для sprinter-cc
-
-DSS выделяет страницы памяти по размеру приложения: < 16 KB → одна страница, в остальные окна подключается «страница #FF» (read=0xFF, write игнорится). Из-за этого CODE-в-W1 + DATA-в-W2 для маленькой программы молча ломается. См. [memory/sprinter_memory_modes.md](../../.claude/projects/-Volumes-SAM8-Projects-DIY-Z80-Sprinter-C-Compiler/memory/sprinter_memory_modes.md).
-
-- [x] **`tiny`**: всё (CODE+DATA+стек) в W2. Default. Verified hello/argv/conio/malloc/file/etc.
-- [x] **`--memory MODE` флаг в sprinter-cc**: parser + per-mode дефолты CODE_LOC/DATA_LOC, override через явные `--code-loc`/`--data-loc`. tiny работает; small/big/huge компилируются с warning'ом (runtime не готов). Реализовано 2026-05-30.
-- [x] **`--memory-manual SPEC`**: парсит `CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3`. Реализовано 2026-05-30.
-- [x] **`small` runtime**: `runtime/crt0_small.s` использует ESTEX `$3D GETMEM` + `$3A SETWIN2` чтобы выделить и замапить W2-страницу ДО gsinit. **НЕ** BIOS `$C4` — стек на этом этапе в W1 (boot_stack в HOME), а BIOS требует стек в W2. После маппинга SP переключается на 0xBFFE, дальше стандартный flow. Реализовано 2026-05-30, verified hello.exe.
-- [x] **`small` auto-detect для >16 KB программ**: `crt0_small.s` читает порт `0xC2` (текущая страница в W2 — не `0xA2`! это W1). Если 0xFF — выделяет page; иначе DSS уже сделала это (программа сама вылезла в W2). Один crt0 покрывает 0..30 KB. mkexe также разрешает HOME span W1+W2 (0x4000..0xBFFF). Verified hello: small (5 KB файл, SETWIN2 path) + 32 KB файл (auto-skip). Реализовано 2026-05-30.
-- [x] **`big` runtime** (tiny + banked code в W1): параметризовали `crt0_banked.s` + `bank.s` через `.ifdef BANK_W1` — другой banking port (0xA2 vs 0xE2), другой load-addr (0x4000 vs 0xC000). sprinter-cc prepend'ит `BANK_W1 = 1` при `--memory big`, передаёт `mkexe -B 0x4000`. Пример `examples/banked_big/`. Реализовано 2026-05-30.
-- [x] **`huge` runtime** (small + banked code в W3): merge W2-detect логики из `crt0_small.s` в `crt0_banked.s`. Существующий пример `examples/banked/` теперь использует MEMORY=huge. Реализовано 2026-05-30.
-- [x] **`--debug` флаг**: prepend `DEBUG_RT = 1` в crt0 + `-DDEBUG_RT` в sdcc. Открывает symbol `_w2_self_allocated` (uint8_t) — runtime diagnostic кто аллоцировал W2. Реализовано 2026-05-30.
-
-### Дизайн-решения по libc и crt0
-
-**Одна `sprinter.lib`** работает для всех memory mode — `.rel`-члены relocatable, SDLD делает dead-code elimination per-member (без графики не подтягивает `gfx_core.rel` и т.д.). Verified hello vs malloc_test через map-файлы.
-
-**`gfx.lib` отдельно — НЕ нужен**: dead-code elimination уже работает.
-
-**`libc_banked` (libc в bank вместо HOME)** — идея на потом, когда HOME (16 KB) забит user-кодом + libc в `huge` mode. Реализуется через `--codeseg BANK0` при компиляции libc; trade-off: trampoline ~30 циклов на каждый libc-вызов. Триггер: реальная программа упрётся в HOME budget.
-
-**HW-зависимые модули — `sprinter_home.lib` отдельно.** Часть libc физически не может быть забанкована в W3, потому что она РАБОТАЕТ с W3:
-- `gfx_*` — пишет в видеопамять `0xC000+` после swap W3 на video page
-- `bank_io` (mem_alloc_pages/bank_read/bank_write) — swap'ит W3 через `OUT (0xE2)`
-- Будущие ISR — прерывание может прийти когда W3 на чём угодно
-
-В huge mode эти модули ДОЛЖНЫ остаться в HOME (W1). Когда будем делать `libc_banked`, **одновременно** выделяем `sprinter_home.lib` (HOME-only) из `sprinter.lib` (bankable). Финальная схема:
-```
-sprinter_home.lib    HOME-only:   gfx, bank_io, ISR shims
-sprinter.lib         bankable:    printf, malloc, string, conio, stdio, env, ...
-sprinter_banked.lib  тот же sprinter.lib но --codeseg BANK0 (для huge)
-```
-Триггер: реализация `--memory huge` runtime.
-
-**crt0 — по одному на mode:**
-- `crt0.s` — текущий, для **tiny/big**: SP=0xBFFE, парсит argv (W2-ресурс уже выделен DSS).
-- `crt0_minimal.s` — текущий, для tiny без argv.
-- `crt0_small.s` — **новый, step 3**: для **small/huge**, аллоцирует W2 через `mem_alloc_pages` ДО gsinit, маппит в порт `0xA2`, потом стандартный flow.
-- `crt0_banked.s` — текущий, для **big**: trampoline-таблица для W3 банков, CODE в W2.
-- `crt0_banked_small.s` — **новый**: huge = small (W2-alloc) + banked (W3 trampolines).
-
-sprinter-cc подбирает crt0 по `--memory` mode (сейчас `--crt0=` это override).
-- [x] **Настраиваемый размер стека**: флаг `sprinter-cc --stack-size BYTES`. Wrapper генерирует `heap_top.s` с `___sdcc_heap_end = stack_top + 1 - stack_size`, отдельный .rel линкуется per-program. Default ≈1278 байт (heap_top=0xBB00) из `runtime/heap_top.s`. Реализовано 2026-05-30.
-
-Интерфейс: `sprinter-cc --memory [tiny|small|big|huge|manual] [--memory-manual SPEC] [--stack-size N] foo.c`. `--memory-manual` имеет смысл только с `--memory manual`.
-
-## Known issues / quirks
-
-- **ESTEX $46 ENV API**: ✅ работает. Док-ция в `DiskSyscalls.txt v1.6` ошибочно описывает return-status — A=0 это NOT FOUND, не FOUND. Зафиксировано в `memory/sprinter_platform.md`.
-
-## ОБЯЗАТЕЛЬНЫЕ ЗАДАЧИ ДЛЯ V2 (после релиза v1)
-
-### Turbo-C-style graphics API (BGI-like) — **MUST для v2**
-
-Расширить наш `gfx_*` API до уровня **Turbo-C `<graphics.h>`** (BGI) для MS-DOS.
-Программисты привыкшие к Turbo-C должны переносить графический код 1-в-1.
-
-**Что должно быть** (на основе Borland BGI):
-
-Setup/teardown:
-- `initgraph()` / `closegraph()` — у нас сейчас `gfx_init`/`gfx_done`, добавить alias
-- `getmaxx()` / `getmaxy()` — макрос на GFX_WIDTH-1 / GFX_HEIGHT-1
-- `cleardevice()` — alias to gfx_clear
-- `getgraphmode()` / `setgraphmode()` — у нас get_videomode/set_videomode
-
-Color/palette:
-- `setcolor(c)`, `getcolor()` — current draw color
-- `setbkcolor(c)`, `getbkcolor()` — background color
-- `setpalette(idx, c)` — палитра entry
-- `getpalette(&info)` — read all palette
-
-Primitives (мы уже имеем эквиваленты — добавить BGI-имена как aliases):
-- `putpixel(x, y, c)` — есть как gfx_putpixel
-- `getpixel(x, y)` — нужно реализовать (RMW обратное — IN)
-- `moveto(x, y)`, `lineto(x, y)`, `linerel(dx, dy)` — current point + line drawing
-- `line(x1, y1, x2, y2)` — есть как gfx_line
-- `rectangle(x1, y1, x2, y2)` — есть как gfx_rect (но другой API: x1,y1,x2,y2 vs x,y,w,h!)
-- `bar(x1, y1, x2, y2)` — есть как gfx_fill_rect
-- `bar3d(x1, y1, x2, y2, depth, topflag)` — новое: rect + 3d edges
-- `circle(x, y, r)`, `arc(...)`, `ellipse(...)`, `pieslice(...)` — новые primitives
-- `fillpoly()`, `drawpoly()` — полигоны
-- `floodfill(x, y, border_color)` — заливка
-
-Text on graphics screen:
-- `outtext(s)` / `outtextxy(x, y, s)` — есть как gfx_text (alias)
-- `settextstyle(font, dir, size)` — multiple bitmap fonts
-- `gettextsettings(&info)`
-- `textwidth(s)` / `textheight(s)` — measure
-
-Image manipulation:
-- `imagesize(x1, y1, x2, y2)` — bytes needed for getimage
-- `getimage(x1, y1, x2, y2, buf)` — save rect to buffer
-- `putimage(x, y, buf, op)` — paste back with COPY_PUT/XOR_PUT/AND_PUT/OR_PUT/NOT_PUT
-
-Clipping/viewport:
-- `setviewport(x1, y1, x2, y2, clip)` — drawing clip rect
-- `getviewsettings(&info)`
-- `clearviewport()`
-- `setactivepage(p)` / `setvisualpage(p)` — двойная буферизация (Sprinter имеет 2 screen)
-
-Line style:
-- `setlinestyle(style, pattern, thickness)` — SOLID_LINE / DOTTED_LINE / etc.
-- `getlinesettings(&info)`
-
-**Acceptance:** перенос типичной Turbo-C BGI программы (рисующей с использованием
-moveto/lineto/circle/bar/setcolor) должен работать без существенных правок.
-
-**Notes:**
-- BGI fonts (TRIPLEX/SANS_SERIF/GOTHIC) — у нас один BIOS font, остальные нужно
-  добавить (как bitmap data в lib)
-- imagesize/getimage/putimage — самые востребованные для game/animation
-- Active/visual page (двойная буферизация) — Sprinter поддерживает 2 graphics pages,
-  нужен API switching
-
-См. также `examples/` Turbo C 2.x BGIDEMO как reference что нужно.
-
-### IM2 Interrupt Handlers — **MUST для v2**
-
-User-задаваемые ISR через Z80 IM 2 mode.  Нужны для:
-- Timer ticks (50 Hz frame counter, плавная анимация)
-- Music playback (AY, COVOX)
-- Real-time games (input + game logic + render в interrupt-driven)
-- Async keyboard / mouse handling
-
-**Status:** ОТЛОЖЕНО до v2.  Полный research + design в `docs/im2_isr_design.md`.
-
-**Решение по архитектуре:** реализовать как отдельный memory mode `--memory im2`
-(вместо того чтобы лезть во все существующие crt0).  Detail'и в design-doc.
-
-**Резюме research'а** (полный текст в `docs/im2_isr_design.md`):
-- Vector 0xFF — frame + keyboard + CBL.  Disambiguation по портам 0x19 / 0xFE
-- Mouse hardware-IRQ не приходит (на текущей плате)
-- Vector table / ISR / stack ОБЯЗАНЫ быть в W2 (0x8000..0xBFFF)
-- DSS имеет свой IM 2 handler — нужно chain'иться (иначе клавиатура / SYSTIME ломаются)
-
-### Прочие крупные пункты для v2
-
-- [ ] **FILE API rewrite — buffered streams** — текущая реализация в
-  `libc/stdio/file.c` это provisional unbuffered shim (каждый fputc/fgetc
-  = один read/write syscall).  Нужна полноценная buffered семантика
-  как в Solid-C:
-
-  ```c
-  typedef struct {
-      uint   flags;     // +0..1   file status flags
-      int    level;     // +2..3   empty/fill level of buffer
-      char  *curp;      // +4..5   current active pointer
-      int    fd;        // +6..7   underlying low-level fd
-      char  *buffer;    // +8..9   data transfer buffer
-      char   hold;      // +10     ungetc byte if no buffer
-      short  token;     // +11..12 reserved
-      char   dummy;     // +13     reserved
-  } FILE;
-  ```
-
-  stdin/stdout/stderr — fd-маркеры `0 / -1 / -2`.  Отрицательные для
-  stdout/stderr выбраны намеренно: ESTEX OPEN может вернуть positive
-  small fd (1, 2, …) для обычного файла → если бы stdout=1, реальный
-  fd=1 сталкивался бы с идентификатором.  fd=0 для stdin безопасно
-  (ESTEX 0 не возвращает).  Сами fd не передаются в syscall'ы —
-  диспетчеризация по флагам `_F_CONIN/_F_CONOUT`.
-
-  Принтер-потоки (stdaux/stdprn) НЕ реализуем — Sprinter принтерной
-  API не имеет.
-
-  Альтернатива — взять реализацию из third_party/solid-c (sources в
-  `SRC/CLIB/`); там есть готовый buffered FILE + fopen/fread/fwrite/
-  fseek/setvbuf и т.д.  Адаптировать к нашим open/read/write/lseek.
-
-  При rewrite заодно решить deferred issues stdio-review:
-  - `fwrite` short-write должен ставить `_F_ERROR`
-  - `fgets(buf, 1, fp)` — стандарт говорит "empty string", мы вернули NULL
-  - `mode_to_flags` — break-out на '+' (cosmetic)
-
-- [ ] **Audio API** — AY-3-8910 + COVOX через прерывания (требует IM2)
-- [ ] **ISA-8 slot support** — ZX-Bus карты (sound, network, etc.) — требует IM2 + чтения portов
-
-## Прочие задачи (v1 backlog, не блокирующие)
-
-- [x] **#9: text I/O split (Turbo-C style)** — stdio (puts/printf/putchar) теперь fast no-attr через PCHARS/PUTCHAR. conio (cputs/cprintf/putch) применяет attr через textcolor/textbackground/textattr. KEEP_EXIST_ATTR → conio fallback на fast path. Verified в hello.exe. См. `memory/text_output_api_split.md`. Реализовано 2026-05-31.
-- [x] **Mouse API полный** (резидентный driver, RST 30h) — все 14 функций обёрнуты (init/show/hide/refresh/read/goto/bounds/text_cursor/load_cursor/get_cursor/get/set_sensitivity/video_mode_changed). См. `memory/mouse_api.md`. Verified в MAME 2026-05-31. Sensitivity = divider (меньше = быстрее).
-- [ ] Interrupt handlers — IM 2 vector table в HOME для user ISR'ов
-- [ ] Поддержка `restore SP on EXIT` (паттерн из z88dk +pps) — проверить нужно ли
-- [ ] CI: автоматически запускать MAME с `-aviwrite` для screenshot-сравнения, чтобы тесты примеров проходили без человека
-
-## Идеи на потом
-
-- Поддержка `<setjmp.h>` (есть в SDCC stdlib — нужно протестировать что наш crt0 совместим)
-- `<time.h>` через ESTEX SYSTIME (`$21`) и CMOS BIOS-функции
-- ZX Spectrum-совместимый режим как отдельный target (для портирования спектрумовских программ)
-- Поддержка ZX-Bus карт (sound, network, etc.) — нужны драйверы
-- Profile-guided optimization tools (hot/cold detection) для крупных программ
-
-## Linker duplicate-symbol warnings (благоприятные, отфильтрованы)
-
-Когда мы сознательно overrides'им SDCC z80.lib функции собственной версией в `sprinter.lib`, `sdldz80` пишет `?ASlink-Warning-Definition of public symbol '...' found more than once`. Линкер берёт первое найденное определение (наше), поэтому поведение корректное — warning только noise.
-
-Текущие overrides:
-- `_puts` — наша версия через PCHARS+\r\n vs SDCC posix puts
-- `___sdcc_heap` — наш heap в W2 vs SDCC's стандартный
-- `_asctime`, `_localtime` (и возможно другие из time) — наш `posix_time.c` через ESTEX SYSTIME vs SDCC's `time.rel` который зависит от `_RtcRead`
-
-**Текущее решение:** `bin/sprinter-cc` отфильтровывает warning-блок (warning + 2 follow-up `Library:` строки) из вывода `sdcc`. Через `-v` (verbose) всё показывается. Реализовано через awk-pipe.
-
-**Возможные улучшения:**
-- Перейти на explicit `--nostdlib` + ручной список нужных модулей из z80.lib (string, math, stdlib без override'нутых) — убрать ИСТОЧНИК warning'ов, не маскировать
-- Или: переименовать наши `_puts` → `_puts_sprinter` + alias через linker flag (не уверен что SDCC поддерживает)
-- Или: оставить как сейчас (рабочее и benign) — приоритет низкий
-
-## TODO: проверить на реальном железе
-
-- [ ] **Port_Y banking trick** (`docs/part2/SprinterGraphics programming.txt`):
-      доку утверждает что после `OUT (0x89), Y` адреса 0xC000+0x400*N в окне W3
-      маппятся на строки Y..Y+15 (одно программирование → 16 строк).
-      Empirical 2026-06-01 в MAME 0.283 этот trick **не работает** — пиксели
-      по адресам выше 0xC000+row_width уходят в невидимую область.  Канонический
-      `docs/samples/plasma2.asm` тоже не использует banking, переустанавливает
-      Port_Y per row.
-      План:
-      1. Получить доступ к реальному Sprinter
-      2. Запустить тест dual-write (`_gfx_putpixel_raw` + второй write в `0xD000+x`)
-      3. Если на железе видны двойные линии → бага MAME, открыть issue с
-         минимальным репро
-      4. Если на железе тоже одна линия → документ неверный, удалить упоминание
-         из доки и просто оставить текущую реализацию (Port_Y per pixel)
-      5. Если banking работает на железе → внедрить кэширование Port_Y в
-         `_gfx_putpixel_raw` (sentinel out-of-range, см. memory/gfx_port_y_banking.md)
-
-      Связанный выигрыш для Bresenham (60-pixel диагональ) — около 8× меньше
-      OUT (0x89) операций, для `gfx_fill_rect 320x256` — 16× меньше.  Не блокирует
-      release v1.
-
-## GFX: расширения по `docs/part2/accelerator_doc.txt`
-
-После прочтения детального accelerator doc выявлены незакрытые направления.
-Сейчас в коде используется только горизонтальный/вертикальный Fill mode.
-
-### Quick wins для текущих primitives
-
-- [ ] **Заменить SMC на `LD A, (var)` для block-size**.  Документ явно
-      разрешает `LD A, (HL)`, `LD A, (BC)`, `LD A, (DE)` (но не `LD A, r`).
-      Это уберёт SMC complexity в `gfx_lines.c:hfill_chunk/vfill_chunk` и
-      `gfx_16.c:g16_hfill_chunk`.  Запрещено только register-to-register.
-- [ ] **Кэширование block-size**.  Документ показывает что accel запоминает
-      block size между bursts (см. `Horizontal_Line_Fill`: устанавливают
-      size + `LD B,B` отключение, потом включают Fill mode и используют
-      сохранённый size).  Для `gfx_fill_rect` с 100 одинаковыми
-      строками — установить size 1 раз, а не 100.
-
-### Bank-prefix modes (port 0xE2 bits)
-
-Документ показывает три варианта банка видеостраницы помимо стандартного 0x50:
-
-| Bank byte | Effect |
-|---|---|
-| 0x50 | Normal write — пишется в shadow + видимый |
-| 0x54 | "no copy in main shadow RAM" |
-| 0x58 | **"FF is transparent"** — байт 0xFF при write оставляет background |
-| 0x5C | both |
-
-Bank 0x58 объясняет почему mouse cursor рисуется с 0xFF-прозрачностью.
-Это путь к **sprite-blending через accel block copy**:
-
-- [ ] **`gfx_set_bank_transparent(on)`** или флаг в `gfx_set_bank` для
-      выбора 0x50/0x58 при отрисовке sprite'ов
-- [ ] Использовать в новом `gfx_blit()` чтобы по факту получать
-      transparent sprites через accel-копию
-
-### Block copy mode (sprite blit'ы)
-
-`LD L,L` (horizontal) и `LD A,A` (vertical) — режим копирования блока через
-256-байтную accel memory.  Это базис для blit'ов.
-
-- [ ] **`gfx_blit(src_data, x, y, w, h)`** — копирование sprite'а
-      (произвольный размер, через accel)
-- [ ] **`gfx_blit_transparent(src, x, y, w, h)`** — с использованием bank 0x58
-
-См. `Draw_Restangle_Data` в accelerator_doc.txt как референс.
-
-### AND / OR / XOR operations через accel
-
-Документ показывает что accel поддерживает логические операции с блоками
-данных.  Применения:
-- XOR — инверсия области (выделение selection в UI)
-- OR / AND — masking, alpha-style blending
-- См. пример в accelerator_doc.txt: "256 bytes block coding via XOR"
-
-- [ ] **`gfx_xor_rect`** / **`gfx_or_rect`** / **`gfx_and_rect`** —
-      примитивы логических операций над прямоугольником
-- [ ] **`gfx_invert_rect(x, y, w, h)`** — alias на xor с 0xFF
-
-### Bitmap fonts разных размеров
-
-Сейчас `gfx_text` / `gfx_putchar` хардкоженно работают с 8×8 шрифтом
-(BIOS WIN_GET_ZG возвращает 256×8 байт).  Для будущих UI / титульников
-нужны:
-- [ ] **`gfx_set_font_size(w, h)`** — переключить ширину/высоту glyph'а
-- [ ] **`gfx_set_font_data(ptr, w, h, advance)`** — заменить указатель
-      на пользовательский шрифт + размеры
-- [ ] Поддержка **proportional** (advance != w) шрифтов — добавить
-      array advance[256] на ширину каждого glyph'а
-- [ ] **Big-font режимы**: 8×16, 16×16, 16×8 (для титульников)
-- [ ] Возможно отдельный API `gfx_text_ex(x, y, str, font_id)` где
-      font_id выбирает один из загруженных шрифтов
-- [ ] **Anti-alias 2-bit шрифты** (бит фон / бит граница / 2-бит alpha?)
-      — far future, для smooth UI
-
-## Финальный этап оптимизаций (не сейчас)
-
-- **`gfx_line` через accel для пологих диагоналей** — Bresenham для линии с |dy| << |dx| (или наоборот) выдаёт длинные runs одинакового Y (или X): пиксель, пиксель, пиксель, шаг Y, пиксель, пиксель... Каждый такой run — это готовый аргумент для `gfx_hline` (или `vline`).  
-  План исследования: посчитать длину runs как функцию от наклона; решить минимальный run length, при котором выгоднее accel hline чем N×putpixel (overhead accel ~20µs, putpixel ~5µs — accel выгоднее при run ≥ 4-5 px); для крутых диагоналей (dx ≈ dy) оставить Bresenham, для пологих — run-length-based fill.
-  Сейчас `gfx_line` orthogonal cases уже через accel — оптимизировать только косые.
-
-- **`gfx_fill_rect` с одним W3-swap на всю операцию** — сейчас каждый внутренний `gfx_hline`/`gfx_vline` делает свой DI/save-W3/restore-W3/EI. Можно сделать internal `_fill_rect_inner` который держит W3 замапленным и DI весь цикл; ~20µs × количество строк/столбцов экономии. Применимо ко всем композитным примитивам.

examples/mdview2/UTF8TEST.MD

@@ -1,28 +0,0 @@
-# Тест UTF-8
-
-Это **проверка** кодировки _UTF-8_ в `mdview2`.
-Кириллица должна читаться: съешь же ещё этих мягких булок.
-
-## Символы и пунктуация
-
-Тире — длинное, и – короткое. Кавычки: «ёлочки» и “лапки”.
-Многоточие… стрелки → ← ↑ ↓, галочка ✓ и крестик ✗.
-Градус 25°, пункт списка • буллет, номер № 7.
-
-## Список
-
-- Первый пункт
-- Второй пункт с длинным текстом, чтобы проверить перенос строки по словам на границе экрана восемьдесят символов
-- Ёжик, ёлка, объём
-
-> Цитата: «Краткость — сестра таланта».
-
-## Таблица
-
-| Язык     | Привет        | Число |
-|----------|---------------|-------|
-| Русский  | Здравствуйте  | 42    |
-| English  | Hello         | 7     |
-| Deutsch  | Grüße         | 100   |
-
-Конец файла.

examples/mdview2/docs/encoding-plan.md

@@ -1,144 +0,0 @@
-# mdview2 — поддержка кодировок (CP866 / CP1251 / KOI8-R / UTF-8)
-
-Статус: РЕАЛИЗОВАНО (2026-06-25). Все фазы сделаны; Фаза 4 — eager-кооперативным
-вариантом (см. ниже), а не idle-build. Осталась только проверка на железе и
-возможная оптимизация «не строить заведомо бесполезный вторичный набор».
-
-## Цель
-
-- CP1251, KOI8-R — простой 1:1 маппинг байтов [128-255] в CP866 (кириллица
-  + основная пунктуация). KOI8-R равнозначна, входит в общий цикл.
-- UTF-8 — декодирование с маппингом кириллицы в CP866 + подстановка части
-  некириллических символов (стрелки, галочки, тире, буллеты, box-drawing) в
-  CP866/ASCII-глифы.
-- Автоопределение кодировки при открытии (BOM + дешёвая эвристика).
-- F8 (Codepage) — переключение по циклу CP866 → CP1251 → KOI8-R → UTF8.
-
-## Ключевые наблюдения (определяют архитектуру)
-
-1. **8-битные кодировки имеют ОДНУ структуру.** markdown-разметка вся в ASCII
-   (`# * | -` …); 8-битные различаются только глифами [128-255]. Значит индекс
-   и кэш (смещения, переносы, ширины таблиц) для CP866/CP1251/KOI8-R —
-   **общие**; переключение между ними = ремап глифов [128-255], БЕЗ
-   переиндексации.
-2. **UTF-8 — другая структура** (кириллица 2 байта). Нужен отдельный
-   конвертированный CP866-буфер со своим индексом/кэшем.
-3. **Проблема рамок таблиц / маркеров.** В кэше намешаны контентные глифы
-   (байты-из-источника [128-255] — НАДО ремапить) и вставленные нами CP866-
-   глифы (box `│─┼…`, маркер списка 0x07, цитата 0xB3, HR 0xC4 — ремапить
-   НЕЛЬЗЯ). По значению байта не различить → различаем по **атрибуту**.
-
-## Архитектура
-
-### Буферы
-- `src_phys[]` — оригинальные байты файла (грузим как сейчас; храним всегда —
-  под ремап и raw-view, см. memory/mdview2_file_phys_preserve).
-- 8-битный режим: `fb()` читает `src_phys` напрямую. Кэш контентных ячеек
-  хранит **исходный байт** (не пред-конвертированный).
-- UTF-8 режим: отдельные EMM-страницы `utf_phys[]` = UTF8→CP866 конвертация
-  src; свой индекс/кэш; `fb()` читает `utf_phys`.
-
-### Различение контент/структура по attr
-Каждый структурный глиф получает НЕ-контентный attr:
-- box-рамка таблиц → новый `ATTR_BOX` (сейчас TBL_ATTR=ATTR_TEXT — поменять);
-- HR (0xC4) → ATTR_HR; маркер списка (0x07) → ATTR_LIST_MARKER; цитата
-  (0xB3) → ATTR_QUOTE_MARKER — уже различимы.
-Правило ремапа: ремапить `char>=128` только если attr ∈ контентных
-(TEXT/BOLD/ITALIC/UNDER/CODE/STRIKE/TITLE1-4). Структурные — как есть.
-
-### Ремап на этапе отрисовки
-`draw_line_from_cache`:
-- encoding == CP866 или UTF-8: прямой `win_rest` из кэш-страницы (ремап не
-  нужен — CP866 identity; UTF-8-кэш уже CP866).
-- encoding == CP1251/KOI8-R: читаем кэш-строку в near-буфер, ремапим
-  контентные байты [128-255] через активную таблицу (структурные пропускаем
-  по attr), пишем в scratch-страницу, `win_rest` из неё. Только видимые ~30
-  строк, на скролле — дёшево.
-
-Итого: переключение между 8-битными — мгновенно (меняем активную таблицу +
-redraw, draw ремапит). Переиндексация только при переходе в/из UTF-8.
-
-## Детекция кодировки (дешёвый скан байтов, ДО построения)
-
-1. **BOM**: первые 3 байта EF BB BF → UTF8 (и пропустить BOM).
-2. **UTF-8 валидность** (если нет BOM): проход, проверка структуры
-   (лид-байты 0xC2-0xDF/0xE0-0xEF/0xF0-0xF4 + континюэйшны 0x80-0xBF;
-   одиночный 0x80-0xBF, 0xC0/0xC1, 0xF5+ → нарушение). 0 нарушений И есть
-   ≥1 multibyte → UTF8. Любое нарушение → 8-бит.
-3. **8-бит дизамбигуация** (CP866/CP1251/KOI8-R): счёт попаданий в байты
-   самых ходовых строчных русских букв (о е а и н т с р в л) каждой кодировки;
-   максимум выигрывает. (Предрасчёт байт-наборов по таблицам.)
-4. **Фолбэк**: нет байт ≥0x80 или неоднозначно → CP866 (родная).
-
-## Таблицы (static const, CODE/const-сегмент)
-
-- `cp1251_to_866[256]`, `koi8r_to_866[256]` — байт→байт (ASCII identity;
-  кириллица по раскладкам; en/em-dash, «ёлочки», … → CP866-аналоги или '?').
-- UTF-8: `utf_cyr_to_866[]` для U+0400..U+045F + компактная таблица символов
-  `utf_sym[]` (codepoint→CP866): U+2192→'>'/стрелка, U+2190→'<', U+2713/14 ✓
-  →'v'/box, U+2022 •→0x07/0xF9, U+2014/2013 —→'-', U+2026 …→"...",
-  U+00A0→' ', U+2500.. box→CP866 box; прочее → '?'.
-
-## Поток загрузки
-
-1. Грузим в `src_phys`. Детект-скан → кодировка E.
-2. Если E ∈ {UTF8}: строим UTF-8-набор (utf_phys + конвертация + индекс),
-   показываем UTF-8. Иначе: показываем 8-битный (общий индекс на src,
-   активная таблица = E).
-3. **Ленивый build второго набора в простое.** Главный цикл — НЕ блокирующий
-   getkey, а kbhit-поллинг: пока нет клавиш и второй набор (UTF-8 при
-   стартовом 8-бит, либо 8-бит при стартовом UTF-8) не построен — докручиваем
-   его инкрементально. После — F8 в любую сторону мгновенно.
-
-## F8 — переключение
-
-- Цикл g_encoding: CP866 → CP1251 → KOI8-R → UTF8 → CP866.
-- 8-бит↔8-бит: сменить активную таблицу + redraw (без переиндексации).
-- в/из UTF-8: переключить активный индекс/кэш на соответствующий набор
-  (если построен; иначе достроить — но при ленивом build обычно уже готов).
-- Статус-бар: имя кодировки; меню (строка 31): «F8 Codepage».
-
-## Фазы реализации (ИТОГ)
-
-1. ✅ **Ядро 8-бит**: ATTR_BOX; кэш хранит исходный байт; таблицы CP1251/KOI8R;
-   ремап в draw (`win_rest_remap`).
-2. ✅ **UTF-8 набор**: `alloc_and_convert_utf8` + `utf8_convert` (декодер 1/2/3-
-   байт, 4-байтные/битые → `?`); `utf_cyr_to_866[96]` + символьные подстановки
-   в `conv_emit_cp` (стрелки 0x18-0x1B, галка 0xFB, буллет 0xF9, тире/кавычки/
-   box/° и т.п.; «» → `<`/`>`, т.к. в CP866 гильеметов нет).
-3. ✅ **Детекция** (BOM + эвристика), сэмпл — первые **4 КБ** (быстро); хвост-
-   обрезка multibyte на границе сэмпла не штрафуется.
-4. ✅ **Сосуществование 2 наборов** (`docset_t g_doc[2]` + `doc_save/load/switch`,
-   свап «живых» глобалов). Сборка — **ленивая (build-on-demand)**: при старте
-   строится только первичный (показываемый) набор; UTF-8 конвертация тоже
-   ленивая (в `build_doc`, не до первого экрана → старт быстрый). Второй набор
-   достраивается `switch_encoding()` при первом F8-переходе в него (спиннер,
-   потом кэш). Eager-вариант отвергнут: удваивал старт и блокировал F8 на время
-   фоновой сборки.
-5. ✅ **F8** полный цикл CP866→CP1251→KOI8R→UTF8→CP866 (внутри 8-бит — ремап,
-   на границе — `doc_switch`/ленивая сборка). Статус: `enc_name` кол.37. Меню
-   «F8 Codepage» показывается только когда переключение возможно (`g_f8_enabled`):
-   во время сборки 8-битного первичного F8 разрешён в `load_key` (только цикл
-   8-бит); во время сборки UTF-8 первичного метка F8 скрыта. F1-справка: секция
-   Encoding.
-
-NB: меню-строка разбита на 10 блоков по 8 колонок, метки Fn кладутся в блок
-(n-1)*8 (F1→0, F8→7, F10→9).
-
-## Память
-- 8-бит: src + scratch-страница для ремапа (1 стр.). Доп. индекса нет.
-- UTF-8 набор: utf_phys (≤8 стр.) + свой индекс/кэш-контент. Строится лениво.
-- Бюджет 215 свободных страниц (sprinter_emm_budget) — с запасом.
-
-## Открытые вопросы (к реализации)
-1. Имя кодировки в статусе — где (зона имени файла / отдельный слот).
-2. Набор UTF-8-подстановок символов — приоритет (→ ← ✓ ✗ • — … « » box).
-3. Глубина таблиц пунктуации CP1251/KOI8 (минимум кириллица+dash или полнее).
-4. Объём детект-сэмпла (весь файл или первые N КБ).
-
-## Риски
-- Корректность различения контент/структура по attr — нужно, чтобы ВСЕ
-  вставленные глифы имели не-контентный attr (проверить box/markers).
-- Два набора индекс/кэш (8-бит + UTF-8) + переключение активного — учёт
-  страниц, чтобы не течь и не путать.
-- Точность таблиц (особенно UTF-8 символы) — итеративно по факту.

examples/mdview2/docs/mdview2-plan.md

@@ -1,164 +0,0 @@
-# mdview2 — план: рендер-кэш вместо живого парсинга на каждый скролл
-
-Контекст и обоснование — см. обсуждение 2026-06-23 (после оптимизации mdview через
-`<bios/text.h>`, см. `mdview-модель-документа-и-рендеринг.md`). Идея: вместо того
-чтобы при каждом скролле повторно идти в файл (`fb()`, W3-банкинг) и гонять
-markdown inline-парсер (`handle_inline_marker`/emphasis state machine), один раз
-отрендерить каждую логическую строку в готовый байтовый буфер и дальше выводить
-его на экран напрямую — без парсинга, без обращения к исходному файлу.
-
-Ключевые подтверждённые факты (эмпирически в MAME, не из документации):
-
-- **Формат буфера ESTEX `WINCOPY`(59h)/`WINREST`(5Ah)** — пара байт `(char, attr)`
-  на ячейку, по строкам, шаг строки = `width*2`, без паддинга. Можно генерировать
-  самим, не вызывая `WINCOPY`. `WINREST` копирует сразу `H` строк одним вызовом.
-  Детали ABI и регистров — см. `tests/winrest/winrest.c`.
-- **Бюджет EMM**: 256 страниц (4 МБ) total, 215 (3440 КБ) free на старте программы.
-  Файл+индекс в худшем случае (128 КБ файл) съедают 16 страниц (256 КБ) — остаётся
-  ≈199 страниц (3184 КБ). Кэш всего документа целиком (даже худший случай:
-  16384 строк × 160 байт = 2.6 МБ) укладывается без LRU/частичного кэша.
-
-## Единый формат строки (пересмотрено 2026-06-23)
-
-Исходно планировалось два типа строк (тип 1 — многоцветные, помещающиеся;
-тип 2 — nowrap/code, один стиль, чистый текст для экономии памяти). От этого
-деления отказались: строки таблиц (`IF_NOWRAP`, но не `IF_CODE`) всё равно
-проходят inline-парсер и могут содержать несколько атрибутов (bold/italic в
-ячейках) — предположение "один стиль" для них неверно. Бюджет EMM
-([[sprinter_emm_budget]]) с большим запасом покрывает (char,attr)-формат для
-ВСЕХ строк без исключения, поэтому усложнение не оправдано.
-
-**Единый формат**: кэш-запись = `len` пар `(char,attr)` — реальная длина
-контента в ячейках, без паддинга до 80, капается на `MAX_CACHE_LINE_LEN`=255.
-Вывод: `bios_fillcharattr(' ', base_attr, SCREEN_W)` (очистить строку) →
-`win_rest(row, left_margin, 1, len, page)` (контент). Для широких nowrap-строк
-горизонтальный скролл (Фаза 5) — это просто смещение НАЧАЛА среза внутри ТОГО
-ЖЕ (char,attr)-буфера на `hscroll*2` байт, тот же `win_rest`, без отдельного
-плain-текстового формата и без необходимости на лету "разворачивать" текст+
-атрибут в пары.
-
-## Фазы реализации
-
-### Фаза 0 — скаффолдинг `examples/mdview2/` [СДЕЛАНО 2026-06-23]
-Новая директория со своим `Makefile`/`app.mk` (по аналогии с `mdview/`, не
-модифицируем `mdview.c`). `mdview2.c` — копия `mdview.c` без изменений логики
-(только usage-строка/заголовок комментария). Собирается чисто, дискета собрана.
-
-### Фаза 1 — формат кэша и директория строк [СДЕЛАНО и ЗАКРЫТО 2026-06-23]
-Реализовано в `mdview2.c`:
-- `cache_rec_t` (РОВНО 8 байт: `page`, `off` (uint16_t), `len`, `flags`,
-  `reserved`, `pad[2]`; размер задаётся `CACHE_DIR_REC_SIZE = sizeof(cache_rec_t)`,
-  НЕ хардкодом — см. разобранный инцидент ниже) — **отдельная** директория
-  (`cache_dir_phys[]`/`cache_dir_get`/`cache_dir_put`), своя ёмкость =
-  `file_pages+1` страниц (как у индекса). **Важное уточнение к исходному тексту
-  плана ниже**: директория НЕ переиспользует слоты `idx_rec_t` in-place —
-  рендер-воркер (Фаза 2) при обработке строки N может заглядывать в idx-записи
-  СОСЕДНИХ строк (откат cont-сегментов, line_idx+1 для границы сегмента); если
-  бы строка N-1 была перезатёрта сразу после своего рендера, воркер строки N
-  прочитал бы уже не исходные off/flags, а указатель в кэш — поломав откат.
-  Бюджет EMM ([[sprinter_emm_budget]]) позволяет отдельный массив — он безопаснее.
-- Пул контента — отдельные EMM-страницы (`cache_content_phys[]`), ленивый рост
-  по 1 странице в `cache_reserve()` (bump-allocator, запись никогда не
-  разбивается через границу страницы; длина капается на `MAX_CACHE_LINE_LEN`=255
-  ячеек).
-- `cache_commit()` = один `bank_write()` на строку (буфер строки собирается
-  локально в W1/W2 заранее, не в W3 — иначе конфликт с `fb()` при чтении
-  исходника во время рендера).
-- `win_rest()` (ESTEX WINREST 5Ah) — вывод готового буфера на экран.
-- `phase1_selftest()` — самопроверка (резервирует/коммитит 4 тестовые ячейки,
-  кладёт запись в директорию по индексу 0, рисует через `win_rest` дважды
-  подряд с координатами через параметры функции) — убрать в Фазе 2.
-
-**Подтверждено визуально в MAME (2026-06-23)**: оба квадрата 2×2 на месте, без
-единой задержки, с координатами через переменные — Фаза 1 полностью закрыта.
-
-**Разобранный инцидент (НЕ платформенный квирк)**: по пути долго казалось, что
-`win_rest()` после "всплеска" обычных BIOS print-вызовов рисует буфер в
-неправильном месте, причём воспроизводилось только когда `row`/`col` приходили
-через переменные, а не как константы — это и было ключом. Настоящая причина:
-`cache_rec_t` фактически занимал 7 байт (SDCC z80 не паддит структуры), а
-`CACHE_DIR_REC_SIZE` был захардкожен как 8 — `bank_read`/`bank_write` копировали
-8 байт в 7-байтный буфер на стеке, затирая соседнюю переменную (параметр `col`)
-вызывающей функции. Фикс — `cache_rec_t` явно до 8 байт + размер через
-`sizeof()`. Полная история и общий урок — [[sprinter_winrest_format]] и
-[[defer_unexplained_quirks]].
-
-### Фаза 2 — рендер-воркер (бывший `render_line`) [СДЕЛАНО 2026-06-23]
-`render_line_to_cache(line_idx)` — адаптация `render_line()`: та же классификация
-строк/префиксов/inline-парсинг (`handle_inline_marker`, emphasis state machine,
-soft-wrap join) БЕЗ ИЗМЕНЕНИЙ, но вместо `bios_writeattr`/`flush_run`/`wrchar`/
-`bios_fillcharattr` на экран — пишем `(char,attr)` пары через `cc_put`/`cc_fill`
-в локальный `cellbuf` (без батчинга через `runbuf`/`flush_run` — тот паттерн был
-нужен только чтобы минимизировать число BIOS-вызовов, при записи в локальный
-буфер смысла нет, пишем посимвольно сразу по месту), затем ОДНИМ
-`cache_reserve()`+`cache_commit()`+`cache_dir_put()` коммитим всю строку.
-Кэшируется ПОЛНЫЙ контент строки до `MAX_CACHE_LINE_LEN`, без обрезки по
-`SCREEN_W` и без среза по `viewport_x` (view/scroll-time понятия, Фаза 4-5).
-Также найден и исправлен по ходу баг в `win_rest()`: `IX` всегда указывал на
-начало страницы (`#0xC000`), полностью игнорируя `off` — работало только в
-Фазе 1, где в кэше была ровно одна запись со смещением 0; как только Фаза 2
-начала пакетировать много строк на одной странице с разными `off`, все строки
-стали читаться с начала страницы. Фикс: `win_rest()` принимает `off`
-(uint16_t), `IX = 0xC000 + off` (новая раскладка ABI сверена через `sdcc -S`
-с непустым телом — у `__naked` с пустым телом SDCC не генерирует код доступа
-к параметрам, нужен пробный non-naked враппер). Подтверждено визуально в MAME.
-
-### Фаза 3 — фоновый пре-рендер с прогрессом [СДЕЛАНО 2026-06-23]
-`emit_seg()` вызывает `render_line_to_cache()` **interleaved** с построением
-индекса — но с отставанием на одну строку: рендер строки N требует уже
-существующей idx-записи N+1 (источник `seg_end`), которой ещё нет в момент,
-когда строка N только создана. Поэтому `emit_seg()` для новой строки рендерит
-ПРЕДЫДУЩУЮ (`n_lines-2` после инкремента) — её флаги (`IF_NOWRAP`/`IF_CODE`/
-`IF_BLANK`) к этому моменту уже дописаны вызовом `set_*_cur()` на предыдущей
-итерации `index_lines()`. Последнюю строку файла (у которой "следующей" не
-будет) дорендеривает сам `index_lines()` после выхода из цикла, как и
-`render_line()` делал для последней строки при живом рендере (`seg_end =
-file_size`). Требует, чтобы `cache_dir_phys[]` был выделен ДО `index_lines()` —
-это уже так (`load_file()` выделяет директорию кэша, затем вызывается
-`index_lines()`).
-
-**Важное сужение скоупа относительно исходного текста плана ниже**: пункты
-"спиннер крутится, пока `rendered_up_to < n_lines`" и "скролл ограничен
-диапазоном `[0, rendered_up_to]`" **не реализованы и не нужны** в этой
-архитектуре — рендеринг происходит СИНХРОННО внутри той же однопроходной
-`index_lines()`, без событийного цикла во время загрузки; пользователь
-физически не может начать скроллить, пока `index_lines()` не вернёт
-управление, а к этому моменту весь документ уже полностью в кэше. Спиннер
-из `index_lines()` (каждые 16 строк) сохранён как есть — он покрывает
-индексацию+рендер вместе, отдельный прогресс-индикатор не нужен.
-
-### Фаза 4 — cache-only draw path при скролле
-Цикл перерисовки видимой области (после пре-рендера) идёт **только** по
-директории строк → `win_rest` (тип 1) или срез текста+`bios_writeattr` (тип 2).
-Никаких обращений к `fb()`/исходному файлу в steady-state скролле.
-
-### Фаза 5 — горизонтальный скролл для широких nowrap-строк
-Срез ТОГО ЖЕ (char,attr)-кэш-буфера по текущему `hscroll`-офсету (смещение
-начала на `hscroll*2` байт внутри буфера строки), `win_rest(row, col, 1,
-visible_len, page)` с новым `off`. Никакого отдельного плоско-текстового
-формата не нужно (см. пересмотр "Единый формат строки" выше).
-
-### Фаза 6 — тестирование в MAME
-Тот же набор паттернов, что использовался для mdview1 (заголовки/списки/цитаты/
-code-block/bold-italic/nowrap-обрезка), ПЛЮС: реальный замер EMM на большом
-документе (не синтетика — проверить, что бюджет из [[sprinter_emm_budget]]
-действительно держится на чём-то близком к 128 КБ); UX пре-рендера (спиннер +
-ограничение скролла, отсутствие "дыр" в недорендеренной области); проверка
-`win_rest` на РЕАЛЬНОМ отрендеренном контенте (не только синтетический A/B/C/D
-тест из `tests/winrest`).
-
-## Открытые вопросы (решить по ходу, не блокируют старт Фазы 0)
-
-- ~~Хранение длины строки в директории~~ — решено в Фазе 1: поле `len` (uint8_t)
-  прямо в `cache_rec_t`.
-- ~~Деление строк на тип 1/тип 2~~ — отказались (см. "Единый формат строки"
-  выше): единый (char,attr)-формат для всех строк, капается на
-  `MAX_CACHE_LINE_LEN`=255 ячеек (с тем же индикатором обрезки на этапе вывода,
-  что уже есть в рендере для nowrap-строк).
-- Освобождать ли страницы исходного файла после того, как все его строки
-  отрендерены (вернуть EMM в пул) — даёт больше места про запас, но усложняет
-  (нужна гарантия, что назад к файлу обращаться больше не придётся — а это не
-  так, если позже добавится поиск по тексту). Не делать в v1.
-- BIOS-вариант `WIN_COPY_WIN`/`WIN_RESTORE_WIN` (0B2h/0B3h, RST 8) не проверен
-  (см. [[sprinter_winrest_format]]) — ESTEX-варианта достаточно для v1, проверять
-  BIOS-вариант только если понадобится экономия на RST-диспетчеризации.