Sprinter-SDCC/docs/im2_isr_design.md

# IM2 Interrupt Handlers — Design Document

**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.

## Зачем нужны прерывания

- **Timer ISR (50/60 Hz)** — счётчик кадров, плавная анимация без busy-loop, тайминги
- **Mouse / keyboard async-обработка** — без polling
- **Music playback** — AY-3-8910, COVOX через прерывания
- **Real-time games** — input + game logic + render в interrupt-driven архитектуре

## Hardware-факты (из docs/converted)

### Sources of vector 0xFF

| Источник | Detect bit | Частота |
|---|---|---|
| Frame (screen refresh) | (default if none of below) | 50/60 Hz |
| Keyboard | port `0x19` (COM_A) bit 0 | event-driven |
| CBL/COVOX (sound) | port `0xFE` bit 7 (sample request) | sample-rate-dependent |
| Mouse | — (hardware interrupt not wired) | — |
| ISA | другой vector (configurable) | depends |

Источники:
- `docs/converted/Forum.txt:956` — кадровые и клавиатурные прерывания приходят с vector 0xFF; различаются по bit 0 порта 0x19. От мыши прерываний нет
- `docs/converted/Forum.txt:758-764` — CBL также vector 0xFF, отличить по bit 7 порта 0xFE
- `docs/converted/IvanMak.txt:1086` — `READ_KBD`: IN(0x19), bit 0 = "байт принят"; затем IN(0x18) = data byte; нужно drain FIFO (до 3 байт)
- `docs/converted/IvanMak.txt:1471` — ВАЖНОЕ ОГРАНИЧЕНИЕ: vector table + ISR + stack ОБЯЗАНЫ быть в области `0x8000..0xBFFF` (window 2). Иначе BIOS будет отключать прерывания на каждой вызове функции

### Что DSS делает в своём ISR (предположения, требует verification)

DSS shell имеет свой IM 2 handler:
- Drain'ит keyboard FIFO в свой буфер (читается через ESTEX WAITKEY/SCANKEY)
- Возможно обновляет ESTEX SYSTIME ($21) tick counter
- Возможно poll'ит mouse (хотя hardware-IRQ от mouse нет — может быть software polling)
- Refresh курсора мыши (он же видимый и движется в shell)

Без chain'инга к DSS:
- Сломается клавиатура (ESTEX kbd functions не получат байты)
- Может сломаться SYSTIME counter
- Может перестать обновляться mouse cursor

### IM2-трюк

Стандартная схема для одиночного ISR address:
1. Аллоцировать **257-байтный** буфер заполненный одинаковым байтом `H`
2. Загрузить `I = H` (например `H=0xA3` → table at `0xA300`, обращения `0xA300..0xA400`)
3. При прерывании CPU читает байт по `(I<<8)|v` и следующий
4. Если оба байта = `H` → ISR address = `(H<<8)|H` = `HHHH`
5. По адресу `HHHH` положить `jp real_isr`

Поскольку для нас интересен только vector 0xFF: read bytes at `(0xA3FF)` and `(0xA400)`. Если table заполнена H=0xA3 — оба байта читаются как 0xA3. ISR_ADDR = `0xA3A3`. По адресу 0xA3A3 кладём 3-байтовый `jp _trampoline`.

## Предлагаемый дизайн

### Public API (libc/include/irq.h)

```c
typedef void (*isr_t)(void);

int  irq_install(isr_t handler);  /* 0 OK, -1 error (already installed) */
void irq_remove(void);

/* Convenience macros — wrap DI/EI when modifying volatile globals
 * shared between main and ISR. */
#define IRQ_DISABLE()  __asm di __endasm
#define IRQ_ENABLE()   __asm ei __endasm
```

Пример использования:
```c
volatile uint16_t ticks = 0;
void on_tick(void) { ticks++; }

int main(void) {
    irq_install(on_tick);
    uint16_t start = ticks;
    while (ticks - start < 50) { /* wait 1s */ }
    irq_remove();
}
```

### Внутренности

**Аллокация vector page:**
- Static buffer 513 байт в `_BSS` (sprinter.lib).
- Размер 513 = 256 (выравнивание) + 257 (сама table) — в худшем случае выравнивание тратит 256 байт.
- Внутри буфера ищем 256-byte aligned адрес. SDCC может не поддерживать `__attribute__((aligned(256)))` — придётся через ассемблер с `.area _BSS_ALIGNED` и линкер-флаг для выравнивания, или через runtime поиск aligned position.
- **Alternative:** заранее линкуем vector page по фиксированному адресу через linker flag `-Wl-b_VECTORS=0xA300` (как у банков). Стабильнее.

**Trampoline в W2:**
- Маленький asm-блок (~50 байт) который:
  1. `ex af,af'; exx; push ix; push iy` — сохранить ВСЕ регистры
  2. `in a, (0xE2); push af` — сохранить current W3 page byte
  3. `in a, (0x19); bit 0, a; jr z, _not_kbd` — keyboard?
     - keyboard path: chain to DSS old ISR (jp/call to saved address)
  4. `in a, (0xFE); bit 7, a; jr z, _not_cbl` — CBL? (Phase 2)
  5. Frame path: `ld hl, (user_handler); ld a, h; or l; jr z, _no_user; call hl_indirect`
  6. `pop af; out (0xE2), a` — restore W3
  7. `pop iy; pop ix; exx; ex af,af'; ei; reti`

**Где живёт trampoline:**
- Для `tiny` mode: `_CODE` = W2 → естественно
- Для `big` mode: `_CODE` = W2 → естественно
- Для `small`/`huge`: `_CODE` = W1, **но trampoline ДОЛЖЕН быть в W2** (W1 может swap'нуться)
- **Решение:** новая linker area `_TRAMP_W2` с absolute address в W2 (например 0xBE00). sprinter-cc размещает её через `-Wl-b_TRAMP_W2=0xBE00`. trampoline.s помечает себя `.area _TRAMP_W2`.

**Chain to DSS:**
- В `irq_install`:
  ```asm
  ld a, i              ; A = current vector page high byte
  ld (old_I), a
  ld h, a
  ld l, #0xFF
  ld a, (hl)           ; A = vector_high (= old_I по trick'у)
  ld d, a
  ld e, a              ; DE = address of DSS's IM2 jp
  ld hl, (de)          ; HL = DSS's old jp target
  ld (dss_old_isr), hl
  ```
- В trampoline keyboard-path:
  ```asm
  ld hl, (dss_old_isr)
  push hl
  ret                  ; jumps to DSS ISR which ends with EI; RETI
  ```
- **Опасность:** DSS's ISR может предполагать что регистры свежие (как только что от CPU) → возможно нужно НЕ saving некоторые регистры до chain'а

**`irq_remove`:**
- DI
- Restore I to old value
- Restore IM mode (обычно был IM 2 → IM 2; редко IM 1 if shell upgraded)
- Free vector page if dynamically allocated
- EI

## Ограничения user handler'а

User's ISR может:
- Читать/писать volatile globals
- Делать дешёвые арифметические операции
- Менять `g_text_attr` (но не вызывать putch/cputs)

User's ISR НЕ должен:
- Вызывать `printf` / `puts` / `malloc` / любые ESTEX/BIOS функции — они могут не быть re-entrant
- Использовать `gfx_*` — они swap'ят W3, наш trampoline уже сохраняет порт но если внутри ISR будет повторный swap то trampoline не сможет восстановить
- Запускать accelerator (LD D,D и т.д.) — accel меняет систему команд CPU
- Долго работать — ISR должен быть быстрым (< 1ms), иначе пропустим следующий

## Открытые вопросы

1. **Что именно DSS делает в своём ISR** — disassemble DSS или вызвать его с инструментировкой
2. **`ld a, i` semantics** на Sprinter — на Z80 P/V flag отражает IFF2; нужно для save/restore
3. **Alignment vector page** — найти SDCC-совместимый способ: либо linker absolute area, либо runtime align внутри 513-байтного буфера
4. **Re-entrancy ESTEX из main во время ISR**:
   - Если main вызывает ESTEX и в это время приходит interrupt → DSS chain'инг должен работать корректно (DSS уже спроектирован под IM 2)
   - Если main вызывает BIOS (RST 8) — это отключает прерывания на время вызова, OK
4. **Memory budget** — vector page 513 байт в BSS уменьшит heap. В tiny mode с heap ~10KB это ~5%. OK.

## Phase 1 acceptance

- `examples/irq_test/` — счётчик тиков растёт с 50 Hz
- Клавиатура продолжает работать через DSS chain (можно прервать тест клавишей)
- Корректный exit — DSS shell получает управление обратно без crash
- Работает во всех memory modes (tiny, small, big, huge)
- Memory note `memory/sprinter_im2_isr.md` с описанием ABI и ограничений

## Phase 2 (когда понадобится)

- ~~CBL/COVOX prerequisite handler~~ — реализован, см. «Phase 2b» выше
- ISA interrupt handler (для ZX-Bus карт)
- 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"

Идея: вместо того чтобы крутить trampoline location во всех существующих режимах, сделать **отдельный `--memory im2`** который:
- Forces CODE в W2 (как tiny)
- Reserves определённый адрес в W2 под vector page и trampoline (например 0xBE00..0xBFFF)
- crt0_im2.s ставит IM 2 в начале (заменяет DSS handler с chain)
- crt0_im2.s восстанавливает на exit

**Плюсы:**
- Меньше matrix-сложности (irq работает только в одном mode)
- Можно агрессивно reserved'ить W2-память
- Тестируется как единое целое

**Минусы:**
- Программам приходится явно выбирать `--memory im2` для использования прерываний
- Дублирование crt0 и runtime

Текущее предложение — пойти этим путём (отдельный mode) для v2, не лезть в существующие crt0.

## Внешние ссылки

- `docs/converted/IvanMak.txt:1040-1054` — секция 9.3 "Прерывания от ISA" + 9.4 "AT-Клавиатура"
- `docs/converted/IvanMak.txt:1469-1473` — IM 2 ограничения (table/stack/ISR в W2)
- `docs/converted/Forum.txt:758-764` — CBL interrupt discrimination
- `docs/converted/Forum.txt:956` + `:1049` — vector 0xFF disambiguation
- `docs/converted/Parinov.txt:601` — IM 1 alternative (handler по адресу 0x0038, не наш путь)

## История

- 2026-06-01 — research собран в этот документ, реализация отложена до v2