libc: IM2 user-ISR, Phase 1 — libc/irq (irq_install/irq_remove) + irqtest

Проще исходного плана (docs/im2_isr_design.md обновлён): отдельный
--memory im2 не понадобился.

- <irq.h>: irq_install(handler) — вызов ~50 Гц только на КАДРОВЫХ
  прерываниях (клавиатура bit0:0x19 и CBL bit7:0xFE отфильтровываются);
  штатный обработчик DSS чейнится ВСЕГДА (SMC-jp, адрес из старой
  IM2-таблицы по регистру I) — клавиатура/SYSTIME/мышь живут
- вектор-таблица: 513 Б BSS + runtime-выравнивание; Sprinter шлёт
  только вектор 0xFF, поэтому jp-заглушка лежит внутри самой таблицы
  по смещению H — без linker-областей и правок crt0
- трамплин: полный сейв обоих наборов+IX/IY вокруг user-handler'а
  (ex af,af' как .db 0x08 — апостроф ломает препроцессор SDCC)
- tiny/big: работает (код в W2); small/huge: EINVAL по проверке
  адресов; irq_remove идемпотентен и висит на atexit (выход без
  снятия = I в памяти умершего процесса = крах шелла); old_I==0 → IM1
- tests/irqtest: тики за 3 с против time() (~50 Гц), живая клавиатура
  под handler'ом, остановка после remove, чистый выход
- docs: im2_isr_design (статус+дельты), libc-reference (<irq.h>), TODO

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/TODO.md

@@ -35,13 +35,14 @@ imagesize/getimage/putimage (COPY/XOR/AND/OR/NOT_PUT), setviewport/
 Acceptance: типичная BGI-программа переносится без существенных
 правок.  Референс: Turbo C 2.x BGIDEMO.
 
-### IM2 Interrupt Handlers
+### IM2 Interrupt Handlers — Phase 1 ГОТОВ (2026-07-06, libc/irq, tests/irqtest; Phase 2: CBL/ISA/цепочки)
 
 User-ISR через IM 2 — timer ticks, музыка (AY/COVOX), real-time
-игры, async input.  Решение: отдельный memory mode `--memory im2`.
-Полный research/design: docs/im2_isr_design.md (vector 0xFF общий,
-disambiguation по портам 0x19/0xFE; таблица/ISR/стек в W2; chain к
-DSS-хендлеру обязателен).
+игры, async input.  Phase 1 реализован БЕЗ отдельного memory mode:
+libc/irq (<irq.h>: irq_install/irq_remove), таблица в BSS с runtime-
+выравниванием, jp-заглушка внутри таблицы, чейн к DSS всегда;
+работает в tiny/big, в small/huge — EINVAL.  Детали и отличия от
+исходного плана: docs/im2_isr_design.md.
 
 ### Прочее v2
 

docs/im2_isr_design.md

@@ -1,6 +1,30 @@
 # IM2 Interrupt Handlers — Design Document
 
-**Status:** РЕАЛИЗАЦИЯ ОТЛОЖЕНА (до пост-релизной версии). Обязательная фича для v2.
+**Status: Phase 1 РЕАЛИЗОВАН 2026-07-06** (libc/irq: irq_install/
+irq_remove + трамплин; тест tests/irqtest).  Отличия реализации от
+плана ниже:
+
+- **отдельный `--memory im2` НЕ понадобился**: таблица — статический
+  буфер 513 Б в BSS с выравниванием в рантайме; т.к. Sprinter шлёт
+  только вектор 0xFF, значимы лишь байты [0xFF]/[0x100], и 3-байтовый
+  `jp _irq_tramp` лежит ВНУТРИ таблицы по смещению H (H = старший
+  байт её адреса, < 0xC0 — не пересекается).  Никаких linker-областей
+  и правок crt0;
+- работает в tiny/big (код и данные в W2); в small/huge irq_install
+  возвращает EINVAL (проверка адресов трамплина/буфера);
+- **чейн к DSS — ВСЕГДА** (и клавиатура, и кадр, и CBL): не нужно
+  знать, что DSS делает в своём ISR — SYSTIME/клавиатура/мышь живут.
+  User-handler зовётся только на кадровых (фильтр: бит 0 порта 0x19,
+  бит 7 порта 0xFE → мимо); финальный jp — SMC-операнд;
+- W3-порт в трамплине НЕ сохраняется: gfx держит DI на время свопов,
+  а user-handler'у banking запрещён; DSS свои окна сохраняет сам;
+- irq_remove вешается на atexit (выход без снятия = I указывает в
+  память умершего процесса = крах шелла); old_I==0 → восстановление IM 1;
+- открытые вопросы 1 (что делает DSS ISR) и 2 (ld a,i) сняты
+  дизайном «всегда чейн» и безусловным EI.
+
+Phase 2 (CBL/COVOX handler, ISA, цепочка нескольких хендлеров) — ниже
+по плану, не реализовано.
 
 Этот документ собирает всё, что мы знаем о прерываниях Sprinter и план реализации user-задаваемых ISR через Z80 IM 2 mode. Когда возьмёмся за реализацию — читать этот файл, чтобы не повторять research.
 

docs/libc-reference.md

@@ -155,6 +155,17 @@ rect fill_rect` — через акселератор (hline/vline burst до 25
 font[row*256+char]).
 Палитра: `gfx_pal_load/set/get/get_color/reset` (страницы 0..3).
 
+## <irq.h> — user-ISR кадрового прерывания (IM 2)
+
+| Сигнатура | Описание |
+|---|---|
+| `int irq_install(isr_t h)` | h зовётся ~50 Гц на кадровых прерываниях; DSS-обработчик чейнится всегда (клавиатура/SYSTIME/мышь живы). 0 / -1+errno (EBUSY повтор, EINVAL — код не в W2: только tiny/big) |
+| `void irq_remove(void)` | вернуть таблицу DSS; идемпотентно; висит на atexit |
+| `IRQ_DISABLE()/IRQ_ENABLE()` | di/ei — скобки для чтения shared-переменных из main |
+
+Handler'у нельзя: ESTEX/BIOS-вызовы, gfx_*/своп окон, акселератор,
+banked-функции; только volatile-глобалы и быстрая работа (<1 мс).
+
 ## <palette.h> — низкий уровень (BIOS $A4/$A6)
 
 `pal_load pal_get pal_set_color pal_get_color` (страница 0..7,

docs/size_baseline.tsv

@@ -23,6 +23,7 @@ gfx_mous	5542
 gfx_text	2560
 hello	4176
 hello2	4251
+irqtest	4818
 ls	4919
 malloc	4462
 mdview	19122