Поддержать MAME.HT/sprinter в SDK и документации

2026-09-17 10:23:18 +03:00
parent 9ad5a018a2
commit 7970a27c98
15 changed files with 96 additions and 31 deletions
@@ -55,7 +55,8 @@ $(error SPRINTER_ROOT=$(SPRINTER_ROOT): bin/sprinter-cc не найден)
 endif

 MAME_HOME   ?=
-MAME_BIN    ?= $(if $(strip $(MAME_HOME)),$(MAME_HOME)/mame.arm,)
+# Пустое значение выбирает MAME_HOME/sprinter или старый mame.arm в профиле.
+MAME_BIN    ?=
 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,)
@@ -486,7 +486,9 @@ global/static переменной, ненулевое значение озна
 недопустимы. Сообщение видно в MAME debugger console и VS Code Debug Console
 при подключённой source-debug сессии, а MCP-клиент читает тот же журнал
 через `recent_events` ([руководство по MCP](sdbg-mcp.md)); без сессии макрос
-сам ничего не печатает.
+сам ничего не печатает. Новый `MAME.HT/sprinter` 0.289 проверен с тем же
+DAP-маршрутом в `sdbg`/`osx`; выбор бинарника описан в
+[руководстве VS Code](vscode-sprinter-debug.md).

 ## <sprinter.h> — платформа

@@ -86,8 +86,10 @@ python3 toolchain/mame_interactive.py /путь/к/Examples/mdview2/mdview2.exe

 ### 3.1 Запуск MAME

-Профиль `MAME_HOME` выбирает `mame.arm`, `roms/`, DSS-дискету и системный
-CHD. A: — временная дискета этого запуска; B: — DSS. При наличии в
+Профиль `MAME_HOME` выбирает `sprinter` (новый MAME.HT) либо `mame.arm`
+(прежняя установка), `roms/`, DSS-дискету и системный CHD. `MAME_BIN` явно
+выбирает бинарник независимо от каталога ресурсов. A: — временная дискета
+этого запуска; B: — DSS. При наличии в
 установленной среде CD/NeoGS/медиа скрипт подключает их как необязательные
 устройства. `-cfg_directory`, `-nvram_directory`, `-diff_directory` и
 `-snapshot_directory` указывают в изолированный каталог сессии;
@@ -11,6 +11,10 @@ stdio MCP-адаптер C-уровня. Эксклюзивное владени

 - **macOS:** текущий end-to-end цикл проверен, включая backend `sdbg` и
  одновременную работу VS Code со штатным `osx` debugger MAME.
+  Новый `MAME.HT/sprinter` (0.289, Holub/Tolik) прошёл живой DAP launch с
+  прежними ROM/DSS: prompt на строке 22, `false_hits=0`, остановка в
+  `hello.c:17` (`main`, PC `0x8224`). У него уже были те же исходники
+  `sdbg` и `mamebridge`; рецепты сборки перенесены с новым именем бинарника.
 - **Linux:** ожидается работа через `sdbg`, `qt` или `imgui`, но полный
  живой прогон ещё не выполнен.
 - **Windows:** весь функционал пока работать не будет. Provider
@@ -279,13 +283,15 @@ commit `b0c4527c2edb1ee177fd09b3c412b65b385bf35b`:
 | 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 |
+| MAME.HT 0.289, 2026-09-17 | Чистая сборка `make SUBTARGET=sprinter SOURCES=src/mame/sinclair/sprinter.cpp` и отдельные рецепты `stock`/`sdbg` создали `sprinter`; DAP в `sdbg` и `osx` на patched, а также `osx` на stock дождался DSS и остановился в `hello.c:17` без ложных точек. `getchar()` получил `x`, общий DAP/MCP сохранил ownership точек. Raw `mamebridge` после исправления раннего callback ответил `state=stop` через файловый IPC |
 | 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-набор: 44 теста (43 прошли, один Unix-socket тест пропущен только
-из-за запрета `bind` в sandbox). Тот же socket path проверен живым DAP-запуском.
+Полный host-набор в этом коммите: 45 тестов (44 прошли, один Unix-socket
+тест пропущен только из-за запрета `bind` в sandbox). Тот же socket path
+проверен живым DAP-запуском.
 После разделения репозиториев установленный VSIX в изолированном профиле
 VS Code запустил сборку SprPoP и остановился в `src/sprpop.c:264` (`main`)
 через API extension host. Новый живой пробник закрытия собственного MAME
@@ -55,8 +55,9 @@ CLI или MCP.
 [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`, а исходники
+MAME fork теперь самостоятельный проект: новый `MAME.HT` содержит
+`plugins/mamebridge/init.lua`, `src/mame_mcp.py` и backend `sdbg`;
+среда запуска задаётся `MAME_HOME`, бинарник — `MAME_BIN`, а исходники
 fork приложению не нужны. Расширение VS Code находится в отдельном
 `VSCode-Sprinter`; Python DAP backend остаётся в SDK.

@@ -18,7 +18,8 @@ MAME приложению не нужны.
 ```text
 ~/Projects/DIY/Z80/Sprinter/
 ├── C-Compiler/                  # Sprinter-CC
-├── MAME/                        # fork MAME, сборки и локальная среда запуска
+├── MAME/                        # прежний fork MAME 0.287, локальные ресурсы
+├── MAME.HT/                     # новый fork Holub/Tolik, сборка sprinter
 ├── Examples/                    # один Git-репозиторий примеров
 ├── Applications/                # каталог без собственного Git
 │   ├── SprPoP/                  # самостоятельный Git-репозиторий
@@ -45,6 +46,7 @@ MAME приложению не нужны.
 | PoP-Archive | `716c639` | `54d0b3d` |
 | VSCode-Sprinter | `68a821e` | `abfc29d` (`901d91a` — функциональные изменения) |
 | MAME | baseline `b0c4527c`, backend/MCP `fe7ee37a` | `37b89b78` |
+| MAME.HT | Holub/Tolik `7f64914880f`, backend `46e89112836`, plugin `1188177a516` | `e0c509c7150` (перенос рецептов и исправление раннего MCP callback) |

 Первые пять base-коммитов получены из подготовительного коммита Sprinter-CC
 через `git subtree split`; поэтому их история прослеживается до исходного
@@ -55,7 +57,8 @@ MAME приложению не нужны.
 | Проект | Что остаётся/переходит | Причина |
 |---|---|---|
 | 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. |
+| MAME | Прежний `../MAME` 0.287 и локальные ROM/DSS/CHD, пока новая среда не подготовлена | История проверенной сборки и ресурсы остаются доступными для сравнения и совместимости. |
+| MAME.HT | Новый `../MAME.HT` Holub/Tolik: драйвер, OSD, backend `sdbg`, raw `mamebridge`/`mame_mcp.py`, рецепты stock/sdbg с выходом `sprinter` | Это активный исходный fork; его нельзя подменять исходниками MAME 0.287, а патчи и бинарники проверяются на его собственной базе. |
 | Examples | Выделенный `../Examples`: `balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`, `space` и относящиеся к ним ресурсы/документы | Это демонстрации SDK с общей версией. Один репозиторий избегает множества мелких релизов. |
 | SprPoP | Всё из прежнего `applications/SprPoP/`: исходники, конверторы, тесты, собственные ресурсы и планы | Уже почти автономное приложение; оригинальные ресурсы и дальше остаются внешними. |
 | Volkov | Всё из прежнего `applications/Volkov/`: исходники, сценарии MAME, собственные тестовые носители и документы | Продукт и его проверки должны развиваться без дерева тулкита. |
@@ -88,13 +91,15 @@ MAME, а не к его исходникам. Стандартные пути в
 контракт установленной среды и допускают переопределение из окружения, аргументов `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_HOME             ?=
+MAME_BIN              ?=
+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
 ```

@@ -107,8 +112,13 @@ MAME_BIOS             ?= v3.06
 DAP-launch должны брать один источник настройки, даже если конкретный профиль
 не монтирует DSS-дискету.

-`MAME_HOME/mame.arm` — стандартный установленный бинарник, а stock/sdbg
-сборки находятся отдельно и выбираются явным `MAME_BIN`. Сборка одного
+В новом `MAME.HT` команда
+`make SUBTARGET=sprinter SOURCES=src/mame/sinclair/sprinter.cpp` создаёт
+`sprinter`, не `mame.arm`. SDK при наличии `MAME_HOME/sprinter` выбирает его;
+для прежних установок сохраняется `MAME_HOME/mame.arm`. Явный `MAME_BIN`
+имеет приоритет и позволяет запускать `MAME.HT/sprinter` со старым каталогом
+ROM/DSS без копирования образов. Stock/sdbg сборки находятся отдельно и
+выбираются явным `MAME_BIN`. Сборка одного
 варианта не перезаписывает другой и не меняет молча активный бинарник.
 Для запуска с нетипичной установкой можно переопределить каждый путь, не
 копируя ROM/CHD в каталог приложения. Все цели запуска валидируют свои
@@ -8,6 +8,8 @@
 но не открывает штатное debugger-окно. Подключённый
 [MCP-адаптер C-уровня](sdbg-mcp.md) читает те же записи `output` через
 `recent_events(after=...)`; он не ставит второй набор макросных точек.
+Маршрут DAP проверен и с новым `MAME.HT/sprinter` 0.289 в режимах `sdbg`
+и `osx`; выбор бинарника описан в [руководстве VS Code](vscode-sprinter-debug.md).

 ## Быстрый пример

@@ -59,6 +59,8 @@ code --extensionDevelopmentPath="/путь/к/VSCode-Sprinter" "$PWD"
 второй — на среду `MAME/runtime` с бинарником, ROM и DSS/CHD. Для выбора
 stock/sdbg или нестандартной установки используются поля `mameBin`,
 `mameRompath`, `mameDssImage`, `mameSystemHddImage`, `mameBios` профиля launch.
+Для нового fork можно оставить `mameHome` на подготовленной прежней среде и
+задать `"mameBin": "/путь/к/MAME.HT/sprinter"` в launch-конфигурации.

 Расширение в режиме `auto` использует `~/.pyenv/shims/python` при наличии
 local `.python-version`; для внешнего workspace ищет установленный
@@ -255,19 +257,25 @@ reset в native console обходят модель состояния VS Code;
 локального RPC и launcher; выбор `windows` решает только сторону MAME и не
 обеспечивает работу VS Code-интеграции.

-Backend `sdbg` входит как воспроизводимый patch к MAME 0.287. Исходники и
-рецепты теперь принадлежат самостоятельному проекту MAME:
+Backend `sdbg` уже входит в новый fork `MAME.HT` на базе MAME 0.289
+(Holub/Tolik). Его штатная сборка и имя исполняемого файла:

 ```sh
-cd /путь/к/MAME
+cd /путь/к/MAME.HT
+make SUBTARGET=sprinter SOURCES=src/mame/sinclair/sprinter.cpp
+./sprinter -version
 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`.
+Результат `make` — `./sprinter`, при запуске система по-прежнему задаётся
+аргументом `sprinter`. Для проверки на имеющихся ROM/DSS можно оставить
+старый `MAME_HOME` и указать `MAME_BIN=/путь/к/MAME.HT/sprinter`.
+В новом fork patch уже зафиксирован в Git; для чистой базы сохранён
+`scripts/sprinter/apply-sdbg-patch.sh`. Варианты копируются в
+`MAME.HT/runtime/bin/stock/sprinter` и `.../sdbg/sprinter`, не подменяя
+активный `MAME_HOME/sprinter`. Старый MAME 0.287 с `mame.arm` также
+поддерживается через явный `MAME_BIN` или прежнюю среду запуска.

 ## Logpoints

@@ -26,5 +26,6 @@ include $(SPRINTER_ROOT)/app.mk

 `make floppy` creates an image under the application's `build/media/`.
 For an emulator launch, set `MAME_HOME` to a prepared MAME runtime with
-`mame.arm`, `roms/` and `IMG/`; `MAME_BIN`, `MAME_ROMPATH`, `MAME_DSS_IMAGE`,
-`MAME_SYSTEM_HDD_IMAGE` and `MAME_BIOS` can override each part.
+`sprinter` or `mame.arm`, `roms/` and `IMG/`; `MAME_BIN`, `MAME_ROMPATH`,
+`MAME_DSS_IMAGE`, `MAME_SYSTEM_HDD_IMAGE` and `MAME_BIOS` can override each
+part.
@@ -50,7 +50,8 @@ The release does **not** include the MAME emulator or the Sprinter ROM /
 DSS / HDD images — those are large and have their own licensing.  To test:

 * **MAME:** install a build with the Sprinter driver and prepare `MAME_HOME`
-  containing `mame.arm`, `roms/`, DSS floppy and system CHD. `make floppy`
+  containing `sprinter` (new MAME.HT) or `mame.arm` (legacy), `roms/`, DSS
+  floppy and system CHD. `make floppy`
  creates a local SDK test disk; `make run MAME_HOME=/path/to/runtime` mounts it.
 * **Real Sprinter:** copy `.exe` to a floppy or HDD partition that DSS can
  see, then `RUN HELLO` from the shell.
@@ -25,6 +25,7 @@ include $(SPRINTER_ROOT)/app.mk
 ```

 `make floppy` создаёт образ в локальном `build/media/` приложения. Для
-запуска в эмуляторе задайте `MAME_HOME` с `mame.arm`, `roms/` и `IMG/`;
+запуска в эмуляторе задайте `MAME_HOME` с `sprinter` или `mame.arm`,
+`roms/` и `IMG/`;
 `MAME_BIN`, `MAME_ROMPATH`, `MAME_DSS_IMAGE`, `MAME_SYSTEM_HDD_IMAGE` и
 `MAME_BIOS` позволяют переопределить отдельные пути.
@@ -50,7 +50,8 @@ Sprinter / MAME / в любом ESTEX DSS шелле.
 они большие и имеют свои лицензии.  Для тестирования:

 * **MAME:** установите сборку с драйвером Sprinter и подготовьте `MAME_HOME`
-  с `mame.arm`, `roms/`, дискетой DSS и системным CHD. `make floppy` создаёт
+  с `sprinter` (новый MAME.HT) или `mame.arm` (прежняя сборка), `roms/`,
+  дискетой DSS и системным CHD. `make floppy` создаёт
  локальный диск SDK-тестов; `make run MAME_HOME=/путь/к/runtime` монтирует его.
 * **Реальный Sprinter:** скопируйте `.exe` на флоп или раздел HDD, видимый
  для DSS, затем `RUN HELLO` в шелле.
@@ -8,9 +8,25 @@ import xml.etree.ElementTree as ET
 ROOT = Path(__file__).resolve().parents[2]
 sys.path.insert(0, str(ROOT / 'toolchain'))
 from sdbg_launcher import disk_entries, lua_script, write_keyboard_config
+from mame_profile import MameProfile


 class LauncherTests(unittest.TestCase):
+    def test_mame_profile_prefers_sprinter_and_keeps_legacy_binary(self):
+        with tempfile.TemporaryDirectory() as directory:
+            home = Path(directory).resolve()
+            legacy = home / 'mame.arm'
+            legacy.touch()
+            self.assertEqual(MameProfile.resolve({'MAME_HOME': directory,
+                                                  'MAME_BIN': ''}).binary, legacy)
+            modern = home / 'sprinter'
+            modern.touch()
+            self.assertEqual(MameProfile.resolve({'MAME_HOME': directory,
+                                                  'MAME_BIN': ''}).binary, modern)
+            self.assertEqual(MameProfile.resolve({'MAME_HOME': directory,
+                                                  'MAME_BIN': str(legacy)}).binary,
+                             legacy)
+
    def test_lua_tables_have_expected_shape(self):
        with tempfile.TemporaryDirectory() as directory:
            path = Path(directory) / 'launch.lua'
@@ -26,8 +26,15 @@ class MameProfile:
        def selected(key: str, suffix: str) -> Path | None:
            return _path(values.get(key)) or (home / suffix if home else None)

+        binary = _path(values.get("MAME_BIN"))
+        if binary is None and home:
+            # Новая Sprinter-сборка MAME.HT называется sprinter;
+            # старые установленные среды по-прежнему содержат mame.arm.
+            binary = next((home / name for name in ("sprinter", "mame.arm")
+                           if (home / name).is_file()), home / "sprinter")
+
        return cls(home=home,
-                   binary=selected("MAME_BIN", "mame.arm"),
+                   binary=binary,
                   rompath=selected("MAME_ROMPATH", "roms"),
                   dss_image=selected("MAME_DSS_IMAGE", "IMG/dss171u.img"),
                   system_hdd_image=selected("MAME_SYSTEM_HDD_IMAGE", "IMG/sp_hdd_sys.chd"),
@@ -6,7 +6,13 @@ if [ -f "$mame_root/.codex/mame.local.env" ]; then
    . "$mame_root/.codex/mame.local.env"
 fi
 : "${MAME_UV:=uv}"
-: "${MAME_MCP_SCRIPT:=../MAME/src/mame_mcp.py}"
+if [ -z "${MAME_MCP_SCRIPT:-}" ]; then
+    if [ -f "$mame_root/../MAME.HT/src/mame_mcp.py" ]; then
+        MAME_MCP_SCRIPT=../MAME.HT/src/mame_mcp.py
+    else
+        MAME_MCP_SCRIPT=../MAME/src/mame_mcp.py
+    fi
+fi
 cd "$mame_root"
 if ! command -v "$MAME_UV" >/dev/null 2>&1; then
    echo "mame-z80: uv не найден; добавьте его в PATH или задайте MAME_UV в .codex/mame.local.env" >&2