Sprinter-SDCC/docs/mame-source-debug.md

# Отладка 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-интеграция.