irq: Phase 2a — CTC-таймер на отдельном векторе 0x06 (Z84C015)

- irq_ctc_install(handler, div2, div3) / irq_ctc_remove: канал 2 CTC
  делит видеотакт 875 кГц (1 тик = 1 знакоместо), канал 3 считает от
  него и прерывает; f = 875000/(div2*div3), div 0 = 256. Пресет
  IRQ_CTC_VSYNC_DIV2/3 = 112*160 — точное начало кадра ~48.8 Гц БЕЗ
  примеси клавиатуры (вектор 0x06 отделён от общего 0xFF)
- CTC-трамплин: полный сейв -> handler -> EI/RETI; RETI обязателен
  (daisy chain Z84C015 снимает IUS только по опкоду RETI); к DSS не
  чейнится — личное прерывание
- общая IM2-таблица под счётчиком ссылок (_irq_table.c): кадровый и
  CTC-хендлеры независимы, последний unref возвращает I/IM 1;
  atexit-уборка глушит CTC обязательно (иначе кГц-прерывания душат
  шелл после выхода)
- порты/слова по docs/samples: CH0=0x10/CH2=0x12/CH3=0x13,
  0x57/0xD7/вектор в CH0, стоп 0x03
- irqtest: CTC-vsync параллельно с кадровым + произвольная частота;
  MAME: frame 48 Гц, ctc(vsync) 49 Гц (parallel frame жив),
  ctc(50x50) 350 Гц точно по формуле, remove/выход чистые

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

Makefile

@@ -16,7 +16,7 @@
 TESTS := hello hello2 simple banked bankedbg banktest strtest cat seek \
          malloc mem_test argv errno rt_test openenv ls conio conio2 \
          attrprob timedir mouse banklocl stdlib assrtest ptime stattest \
-         filetest fdmax fbench solidt dec_test gets stest2 winrest \
+         filetest fdmax fbench solidt irqtest dec_test gets stest2 winrest \
          bios_text text_palette \
          gfx_demo gfx_d16 gfx_text gfx_mous gfx_dbuf
 

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`.
+игры, async input.  Phase 1 реализован БЕЗ отдельного memory mode:
-Полный research/design: docs/im2_isr_design.md (vector 0xFF общий,
+libc/irq (<irq.h>: irq_install/irq_remove), таблица в BSS с runtime-
-disambiguation по портам 0x19/0xFE; таблица/ISR/стек в W2; chain к
+выравниванием, jp-заглушка внутри таблицы, чейн к DSS всегда;
-DSS-хендлеру обязателен).
+работает в tiny/big, в small/huge — EINVAL.  Детали и отличия от
+исходного плана: docs/im2_isr_design.md.
 
 ### Прочее v2
 

docs/im2_isr_design.md

@@ -1,6 +1,85 @@
 # IM2 Interrupt Handlers — Design Document
 
-**Status:** РЕАЛИЗАЦИЯ ОТЛОЖЕНА (до пост-релизной версии). Обязательная фича для v2.
+**Status: Phase 1 РЕАЛИЗОВАН 2026-07-06, ИСПРАВЛЕН после отладки**
+(libc/irq: irq_install/irq_remove + трамплин; тест tests/irqtest).
+
+## Результаты 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 handler — вернуть фильтр 0xFE.7 при активном CBL,
+sample-буфер; фундамент Audio API), ISA-вектора, цепочки нескольких
+хендлеров — не реализовано.
 
 Этот документ собирает всё, что мы знаем о прерываниях Sprinter и план реализации user-задаваемых ISR через Z80 IM 2 mode. Когда возьмёмся за реализацию — читать этот файл, чтобы не повторять research.
 

docs/libc-reference.md

@@ -155,6 +155,19 @@ 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 |
+| `int irq_ctc_install(h, div2, div3)` | периодический таймер CTC (вектор 0x06): f = 875000/(div2×div3), div 0=256; пресет кадра IRQ_CTC_VSYNC_DIV2/3 (112×160, ~48.8 Гц); независим от кадрового; трамплин завершает RETI |
+| `void irq_ctc_remove(void)` | глушит CTC (обязательно; atexit подстрахует) |
+| `IRQ_DISABLE()/IRQ_ENABLE()` | di/ei — скобки для чтения shared-переменных из main |
+
+Handler'у нельзя: ESTEX/BIOS-вызовы, gfx_*/своп окон, акселератор,
+banked-функции; только volatile-глобалы и быстрая работа (<1 мс).
+
 ## <palette.h> — низкий уровень (BIOS $A4/$A6)
 
 `pal_load pal_get pal_set_color pal_get_color` (страница 0..7,

docs/libc-roadmap.md

@@ -84,7 +84,7 @@ fgetpos/fsetpos (хвост П2).  bdos/brk/ioctl — отказ решение
 - [x] Размерный регресс: toolchain/size_check.py + docs/size_baseline.tsv;
       `make size-check` (выход 1 при росте) / `make size-baseline`
 
-## П6. Верификация после сплита
+## П6. Верификация после сплита — ЗАКРЫТ 2026-07-06 (MAME; железо — отдельно)
 
 - [ ] `make floppy` + прогон в MAME ключевых тестов (conio, filetest, ptime,
       stattest, mouse, gfx_demo) — линковка прошла, но поведение надо

docs/size_baseline.tsv

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

libc/include/irq.h

@@ -0,0 +1,63 @@
+/*
+ * irq.h — пользовательский обработчик кадрового прерывания (IM 2).
+ *
+ * Sprinter шлёт вектор 0xFF от трёх источников: кадр (50 Гц),
+ * клавиатура (бит 0 порта 0x19), CBL/COVOX.  Штатно DSS работает в
+ * IM 1 (обработчик 0x0038).  irq_install() переключает CPU в IM 2 со
+ * своей таблицей и зовёт handler ТОЛЬКО на кадровых прерываниях;
+ * после него (и на всех прочих источниках) управление всегда
+ * передаётся штатному обработчику DSS на 0x0038 — клавиатура,
+ * SYSTIME и курсор мыши продолжают работать.  irq_remove()
+ * возвращает IM 1/I как было (и вызывается автоматически из exit).
+ *
+ * ТРЕБОВАНИЕ ПАМЯТИ: код и данные программы должны быть в W2
+ * (0x8000-0xBFFF) — режимы tiny и big.  В small/huge (CODE в W1)
+ * irq_install вернёт -1/EINVAL: во время прерывания W1 может быть
+ * перемаплен.  Дизайн: docs/im2_isr_design.md.
+ *
+ * Правила для handler'а (вызывается ~50 раз/с, все регистры
+ * сохраняются снаружи):
+ *   МОЖНО:  volatile-глобалы, арифметика, короткая работа (<1 мс);
+ *   НЕЛЬЗЯ: ESTEX/BIOS-вызовы (printf/malloc/файлы), gfx_* и любой
+ *           своп W1/W3, акселератор, banked-функции, longjmp наружу.
+ */
+
+#ifndef IRQ_H
+#define IRQ_H
+
+#include <stdint.h>
+
+typedef void (*isr_t)(void);
+
+/* Установить обработчик кадрового прерывания.
+ * 0 — OK; -1 + errno: EBUSY (уже установлен), EINVAL (код/данные
+ * не в W2 — неподходящий memory mode). */
+int  irq_install(isr_t handler);
+
+/* Снять обработчик и вернуть IM2-таблицу DSS.  Безопасно звать
+ * повторно; вызывается автоматически при exit(). */
+void irq_remove(void);
+
+/* ---- CTC-таймер (Z84C015, вектор 0x06 — отдельный от кадрового) ---
+ *
+ * Канал 2 тактируется 875 кГц (1 тик = 1 знакоместо видеотракта) и
+ * делит; канал 3 считает от канала 2 и прерывает.  Частота handler'а:
+ *     f = 875000 / (div2 * div3),  div 0 = 256
+ * (диапазон ~13 Гц .. десятки кГц; на частотах выше пары кГц handler
+ * должен быть ОЧЕНЬ коротким).  Ставится независимо от irq_install —
+ * можно иметь оба.  Ограничения для handler'а те же, что выше.
+ * Обработчик завершается RETI (в трамплине) — daisy chain Z84C015. */
+
+int  irq_ctc_install(isr_t handler, uint8_t div2, uint8_t div3);
+void irq_ctc_remove(void);     /* глушит CTC; тоже вызывается из exit() */
+
+/* Пресет точного кадра: 112 тактов (2 пикс. линии) * 160 = 320 линий,
+ * ~48.8 Гц, начало кадра — «vsync без примеси клавиатуры». */
+#define IRQ_CTC_VSYNC_DIV2  112
+#define IRQ_CTC_VSYNC_DIV3  160
+
+/* Скобки для доступа main-кода к данным, разделяемым с ISR. */
+#define IRQ_DISABLE()  __asm__("di")
+#define IRQ_ENABLE()   __asm__("ei")
+
+#endif

libc/irq/_irq.h

@@ -0,0 +1,61 @@
+/*
+ * _irq.h — внутренности IM2-модуля (НЕ публичный заголовок).
+ *
+ * Механика (docs/im2_isr_design.md):
+ *  - таблица векторов: 257 байт с выравниванием 256 внутри статического
+ *    буфера 513 байт (_irq_state.c), заполняется байтом H = старший
+ *    байт её же адреса; CPU по внешнему вектору 0xFF читает адрес
+ *    (H<<8|H) — трёхбайтовый `jp _irq_tramp` лежит ВНУТРИ таблицы по
+ *    смещению H (H < 0xC0 — с [0xFF]/[0x100] не пересекается; заливка
+ *    H перехватывает и вектора SIO 0x10..0x1E, если их кто-то включит);
+ *  - таблица общая для кадрового и CTC-хендлеров — жизнью управляет
+ *    счётчик ссылок (_irq_table_ref/_irq_table_unref в _irq_table.c);
+ *    unref последнего возвращает I и IM 1 (штатный режим DSS);
+ *  - кадровый трамплин (_irq_tramp.c): AF-пробник порта 0x19 (SIO-A
+ *    RR0, бит 0 = клавиатурный байт); кадр → полный save → user
+ *    handler → restore; затем ВСЕГДА jp на обработчик DSS 0x0038
+ *    (DSS работает в IM 1) — EI/RETI делает DSS;
+ *  - CTC-трамплин (_irq_ctc_tramp.c): вектор 0x06 (Z84C015, каналы
+ *    2+3 в связке, база 875 кГц); полный save → handler → restore →
+ *    EI/RETI — RETI ОБЯЗАТЕЛЕН (daisy chain: без него CTC не пошлёт
+ *    следующее прерывание); к DSS НЕ чейнится (наше личное прерывание).
+ */
+#ifndef _IRQ_INTERNAL_H
+#define _IRQ_INTERNAL_H
+
+#include <stdint.h>
+#include <irq.h>
+
+/* Буфер под таблицу: 256 (выравнивание) + 257 (таблица). */
+#define _IRQ_VEC_BUF_SIZE (256 + 257)
+
+extern uint8_t _irq_vec_buf[_IRQ_VEC_BUF_SIZE];
+extern isr_t   _irq_user;        /* кадровый handler; NULL = нет */
+extern isr_t   _irq_ctc_user;    /* CTC-handler; NULL = нет */
+extern uint8_t _irq_old_i;       /* I до захвата таблицы */
+extern uint8_t _irq_refs;        /* счётчик пользователей таблицы */
+
+/* Порты встроенной периферии Z84C015 (docs/samples/SIO_CTC_KEY.asm). */
+#define _IRQ_CTC_CH0   0x10
+#define _IRQ_CTC_CH2   0x12
+#define _IRQ_CTC_CH3   0x13
+#define _IRQ_SIO_A     0x19      /* SIO-A RR0: бит 0 = Rx available */
+
+/* Захватить/отпустить IM2-таблицу (счётчик ссылок).  ref: при первом
+ * захвате строит таблицу, ставит I/IM2, взводит atexit-уборку;
+ * 0 или -1+errno (EINVAL — код/буфер не в W2).  unref: при последнем
+ * отпускании возвращает I и IM 1. */
+int  _irq_table_ref(void);
+void _irq_table_unref(void);
+
+/* Адрес выровненной таблицы (валиден при _irq_refs > 0). */
+uint8_t *_irq_table(void);
+
+/* Входы трамплинов (asm). */
+void _irq_tramp(void);
+void _irq_ctc_tramp(void);
+
+/* SMC-операнд `jp` на обработчик DSS (метка в _irq_tramp.c). */
+extern uint16_t _irq_dss_target;
+
+#endif

libc/irq/_irq_ctc_tramp.c

@@ -0,0 +1,55 @@
+/*
+ * _irq_ctc_tramp — вход прерывания CTC-канала 3 (вектор 0x06, IM 2).
+ *
+ * Полный сейв обоих наборов + IX/IY, вызов _irq_ctc_user, restore,
+ * EI/RETI.  RETI ОБЯЗАТЕЛЕН: периферия Z84C015 в daisy chain снимает
+ * своё «interrupt under service» только увидев опкод RETI на шине —
+ * с обычным RET следующее прерывание от CTC не придёт (см.
+ * docs/samples/sprinterIntLib.asm).  К DSS НЕ чейнимся — это наше
+ * личное прерывание, не системное.
+ */
+
+#include "_irq.h"
+
+void _irq_ctc_tramp(void) __naked
+{
+    __asm
+        push  af
+        push  bc
+        push  de
+        push  hl
+        .db   0x08                  ; ex af,af (теневой AF)
+        push  af
+        exx
+        push  bc
+        push  de
+        push  hl
+        push  ix
+        push  iy
+
+        ld    hl, (__irq_ctc_user)
+        ld    a, h
+        or    a, l
+        jr    Z, _ictc_skip
+        call  _ictc_call_hl
+    _ictc_skip:
+
+        pop   iy
+        pop   ix
+        pop   hl
+        pop   de
+        pop   bc
+        exx
+        pop   af
+        .db   0x08                  ; ex af,af (теневой AF)
+        pop   hl
+        pop   de
+        pop   bc
+        pop   af
+        ei
+        reti
+
+    _ictc_call_hl:
+        jp    (hl)
+    __endasm;
+}

libc/irq/_irq_state.c

@@ -0,0 +1,13 @@
+/*
+ * _irq_state — данные IM2-модуля: буфер вектор-таблицы, указатели на
+ * user-handler'ы (кадровый и CTC), сохранённый регистр I, счётчик
+ * ссылок таблицы.  Только данные.
+ */
+
+#include "_irq.h"
+
+uint8_t _irq_vec_buf[_IRQ_VEC_BUF_SIZE];
+isr_t   _irq_user;
+isr_t   _irq_ctc_user;
+uint8_t _irq_old_i;
+uint8_t _irq_refs;

libc/irq/_irq_table.c

@@ -0,0 +1,115 @@
+/*
+ * _irq_table — жизненный цикл общей IM2-таблицы (счётчик ссылок).
+ *
+ * Первый ref: проверка W2-адресов, построение таблицы (заливка H +
+ * jp _irq_tramp по смещению H), I := H, IM 2, atexit-уборка.
+ * Последний unref: I := старое, IM 1 (штатный режим DSS — его
+ * обработчик на 0x0038; см. docs/samples/sprinterIntLib.asm).
+ */
+
+#include <string.h>
+#include <errno.h>
+#include <sprinter_exit.h>
+#include "_irq.h"
+
+/* Прочитать регистр I. */
+static uint8_t irq_get_i(void) __naked
+{
+    __asm
+        ld    a, i
+        ret
+    __endasm;
+}
+
+/* I := A, режим IM 2. */
+static void irq_set_i_im2(uint8_t i_val) __naked
+{
+    (void)i_val;
+    __asm
+        ;; __sdcccall(1): uint8_t-аргумент уже в A.
+        ld    i, a
+        im    2
+        ret
+    __endasm;
+}
+
+/* I := A, штатный IM 1 (DSS). */
+static void irq_set_i_im1(uint8_t i_val) __naked
+{
+    (void)i_val;
+    __asm
+        ld    i, a
+        im    1
+        ret
+    __endasm;
+}
+
+/* Уборка на exit: снять оба хендлера (CTC глушится обязательно —
+ * иначе после выхода его прерывания задушат шелл). */
+static void irq_atexit(void)
+{
+    irq_ctc_remove();
+    irq_remove();
+}
+
+uint8_t *_irq_table(void)
+{
+    return (uint8_t *)(((uint16_t)((uint16_t)_irq_vec_buf + 255u))
+                       & 0xFF00u);
+}
+
+int _irq_table_ref(void)
+{
+    if (_irq_refs) {
+        _irq_refs++;
+        return 0;
+    }
+
+    /* Трамплины и таблица обязаны жить в W2 (0x8000-0xBFFF): во время
+     * прерывания W1/W3 могут быть перемаплены.  CODE вне W2 =
+     * неподходящий memory mode (small/huge). */
+    uint16_t tramp = (uint16_t)&_irq_tramp;
+    uint16_t buf   = (uint16_t)_irq_vec_buf;
+    if (tramp < 0x8000 || tramp >= 0xC000 ||
+        buf   < 0x8000 || buf + _IRQ_VEC_BUF_SIZE > 0xC000) {
+        errno = EINVAL;
+        return -1;
+    }
+
+    uint8_t *table = _irq_table();
+    uint8_t  h     = (uint8_t)((uint16_t)table >> 8);
+
+    IRQ_DISABLE();
+
+    /* Старое I — только чтобы вернуть регистр при unref: DSS работает
+     * в IM 1 (I=0x3F — наследие Spectrum ROM, НЕ таблица). */
+    _irq_old_i = irq_get_i();
+    _irq_dss_target = 0x0038;
+
+    memset(table, h, 257);
+    uint8_t *stub = table + h;         /* h < 0xC0 — с [0xFF] не пересекается */
+    stub[0] = 0xC3;                    /* jp _irq_tramp */
+    stub[1] = (uint8_t)(tramp & 0xFF);
+    stub[2] = (uint8_t)(tramp >> 8);
+
+    irq_set_i_im2(h);
+    IRQ_ENABLE();
+
+    _irq_refs = 1;
+
+    static uint8_t atexit_armed;
+    if (!atexit_armed) {
+        atexit_armed = 1;
+        atexit(irq_atexit);
+    }
+    return 0;
+}
+
+void _irq_table_unref(void)
+{
+    if (!_irq_refs) return;
+    if (--_irq_refs) return;
+    IRQ_DISABLE();
+    irq_set_i_im1(_irq_old_i);
+    IRQ_ENABLE();
+}

libc/irq/_irq_tramp.c

@@ -0,0 +1,75 @@
+/*
+ * _irq_tramp — вход IM2-прерывания (вектор 0xFF, все источники).
+ *
+ * До выяснения источника трогаем только AF: клавиатура (бит 0 порта
+ * 0x19 = SIO-A RR0 «Rx Character Available») уходит напрямую в DSS.
+ * Кадровое прерывание: полный сейв обоих наборов + IX/IY, вызов
+ * user-handler'а, симметричный restore.  В конце ВСЕГДА jp на
+ * обработчик DSS 0x0038 (DSS работает в IM 1; jp с interrupted-PC на
+ * стеке имитирует RST 38) — он делает свой save/restore и завершает
+ * EI/RETI: клавиатурный FIFO, SYSTIME и курсор мыши живут.
+ *
+ * CBL-фильтр по биту 7 порта 0xFE УБРАН: при выключенном CBL бит
+ * подтянут к 1 (MAME kbd_fe_r: data |= 0xE0), и каждое кадровое
+ * прерывание ложно уходило бы в чейн — user-handler не вызывался бы
+ * никогда.  Вернуть вместе с поддержкой CBL в Phase 2.
+ *
+ * Операнд финального jp (_irq_dss_target) — SMC, патчится из
+ * irq_install; модуль в _CODE (RAM на Sprinter, W2 в tiny/big).
+ */
+
+#include "_irq.h"
+
+void _irq_tramp(void) __naked
+{
+    __asm
+        push  af
+        in    a, (#0x19)
+        rrca                        ; бит 0 — клавиатурный байт принят?
+        jr    C, _irq_chain
+
+        ;; --- кадровое прерывание ---
+        push  bc
+        push  de
+        push  hl
+        ld    hl, (__irq_user)
+        ld    a, h
+        or    a, l
+        jr    Z, _irq_pop3          ; handler не установлен
+
+        ;; Сохранить теневой набор и индексные — user-код клобберит всё.
+        .db   0x08                  ; ex af,af (теневой AF)
+        push  af
+        exx
+        push  bc
+        push  de
+        push  hl
+        push  ix
+        push  iy
+
+        ld    hl, (__irq_user)
+        call  _irq_call_hl
+
+        pop   iy
+        pop   ix
+        pop   hl
+        pop   de
+        pop   bc
+        exx
+        pop   af
+        .db   0x08                  ; ex af,af (теневой AF)
+    _irq_pop3:
+        pop   hl
+        pop   de
+        pop   bc
+    _irq_chain:
+        pop   af
+        ;; Всегда к DSS (IM 1, обработчик 0x0038) — EI/RETI за ним.
+        .db   0xC3                  ; jp nn
+    __irq_dss_target::
+        .dw   0x0038                ; SMC: подтверждается в irq_install
+
+    _irq_call_hl:
+        jp    (hl)
+    __endasm;
+}

libc/irq/irq_ctc_install.c

@@ -0,0 +1,60 @@
+/*
+ * irq_ctc_install — периодический user-таймер на CTC Z84C015
+ * (каналы 2+3 в связке, вектор 0x06 — ОТДЕЛЬНЫЙ от кадрового 0xFF).
+ *
+ * Канал 2 тактируется видеотактом 875 кГц (1 тик = 1 знакоместо) и
+ * работает делителем; канал 3 считает от канала 2 и генерирует
+ * прерывание.  Частота = 875000 / (div2 * div3), div 0 = 256.
+ * Пресет кадра: 112 * 160 (2 пиксельные линии * 160 = 320 линий) —
+ * точное начало кадра ~48.8 Гц без примеси клавиатуры.
+ *
+ * Программирование (docs/samples/sprinterIntLib.asm, SIO_CTC_KEY.asm;
+ * значения control-слов «надо читать доку по z84c15»):
+ *   0x57 -> CH2, div2   — счётчик, без прерывания
+ *   0xD7 -> CH3, div3   — счётчик, прерывание разрешено
+ *   0x00 -> CH0         — базовый вектор блока CTC = 0 (ch3 -> 0x06)
+ */
+
+#include <errno.h>
+#include "_irq.h"
+
+static uint8_t ctc_div2;
+static uint8_t ctc_div3;
+
+static void ctc_program(void) __naked
+{
+    __asm
+        ld    a, #0x57              ; CH2: counter, int off, TC следом
+        out   (#_IRQ_CTC_CH2), a
+        ld    a, (_ctc_div2)
+        out   (#_IRQ_CTC_CH2), a
+        ld    a, #0xD7              ; CH3: counter, int on, TC следом
+        out   (#_IRQ_CTC_CH3), a
+        ld    a, (_ctc_div3)
+        out   (#_IRQ_CTC_CH3), a
+        xor   a, a                  ; базовый вектор CTC = 0
+        out   (#_IRQ_CTC_CH0), a
+        ret
+    __endasm;
+}
+
+int irq_ctc_install(isr_t handler, uint8_t div2, uint8_t div3)
+{
+    if (!handler) { errno = EINVAL; return -1; }
+    if (_irq_ctc_user) { errno = EBUSY; return -1; }
+    if (_irq_table_ref() != 0) return -1;
+
+    uint16_t tramp = (uint16_t)&_irq_ctc_tramp;
+    uint8_t *table = _irq_table();
+
+    IRQ_DISABLE();
+    _irq_ctc_user = handler;
+    /* Вектор 0x06 — обычная (не same-byte) запись в таблицу. */
+    table[0x06] = (uint8_t)(tramp & 0xFF);
+    table[0x07] = (uint8_t)(tramp >> 8);
+    ctc_div2 = div2;
+    ctc_div3 = div3;
+    ctc_program();
+    IRQ_ENABLE();
+    return 0;
+}

libc/irq/irq_ctc_remove.c

@@ -0,0 +1,34 @@
+/*
+ * irq_ctc_remove — остановить CTC-таймер (мягкий reset канала 3 —
+ * control-слово 0x03: reset без TC) и отпустить IM2-таблицу.
+ * Обязателен перед выходом (atexit-уборка зовёт сама): без остановки
+ * CTC продолжит дёргать INT после возврата в шелл.  Идемпотентно.
+ */
+
+#include "_irq.h"
+
+static void ctc_stop(void) __naked
+{
+    __asm
+        ld    a, #0x03              ; CH3: soft reset, прерывание выкл
+        out   (#_IRQ_CTC_CH3), a
+        ld    a, #0x03              ; CH2: остановить и делитель
+        out   (#_IRQ_CTC_CH2), a
+        ret
+    __endasm;
+}
+
+void irq_ctc_remove(void)
+{
+    if (!_irq_ctc_user) return;
+    IRQ_DISABLE();
+    ctc_stop();
+    _irq_ctc_user = 0;
+    /* Слоты вектора 0x06 — назад в заливку H (чейн на 0x0038). */
+    uint8_t *table = _irq_table();
+    uint8_t  h     = (uint8_t)((uint16_t)table >> 8);
+    table[0x06] = h;
+    table[0x07] = h;
+    IRQ_ENABLE();
+    _irq_table_unref();
+}

libc/irq/irq_install.c

@@ -0,0 +1,17 @@
+/*
+ * irq_install — установить user-handler кадрового прерывания.
+ * Захватывает общую IM2-таблицу (_irq_table_ref) и включает кадровый
+ * путь трамплина.  Детали и результаты отладки: docs/im2_isr_design.md.
+ */
+
+#include <errno.h>
+#include "_irq.h"
+
+int irq_install(isr_t handler)
+{
+    if (!handler) { errno = EINVAL; return -1; }
+    if (_irq_user) { errno = EBUSY; return -1; }
+    if (_irq_table_ref() != 0) return -1;
+    _irq_user = handler;
+    return 0;
+}

libc/irq/irq_remove.c

@@ -0,0 +1,16 @@
+/*
+ * irq_remove — снять кадровый user-handler и отпустить IM2-таблицу
+ * (последний пользователь возвращает I/IM 1 — штатный режим DSS).
+ * Идемпотентно; вызывается и из atexit-уборки.
+ */
+
+#include "_irq.h"
+
+void irq_remove(void)
+{
+    if (!_irq_user) return;
+    IRQ_DISABLE();
+    _irq_user = 0;
+    IRQ_ENABLE();
+    _irq_table_unref();
+}

tests/irqtest/Makefile

@@ -0,0 +1,5 @@
+# Build irqtest.exe — smoke IM2 user-ISR (tiny mode: код/данные в W2).
+
+PROJ_ROOT := $(abspath $(CURDIR)/../..)
+EXAMPLE   := irqtest
+include $(PROJ_ROOT)/app.mk

tests/irqtest/irqtest.c

@@ -0,0 +1,142 @@
+/*
+ * irqtest — smoke-тест IM2-модуля (Phase 1+2, docs/im2_isr_design.md).
+ *
+ * Проверяет:
+ *   1. кадровый handler тикает ~50 Гц (сверка с time() за 3 секунды);
+ *   2. клавиатура/SYSTIME живы при установленном handler'е (чейн к DSS);
+ *   3. CTC-таймер (вектор 0x06): пресет vsync ~49 Гц ОДНОВРЕМЕННО с
+ *      кадровым; затем быстрый режим 875 кГц/(50*50) = 350 Гц;
+ *   4. irq_remove/irq_ctc_remove останавливают тики;
+ *   5. чистый выход в шелл (I/IM восстановлены, CTC заглушен).
+ */
+
+#include <stdio.h>
+#include <time.h>
+#include <conio.h>
+#include <errno.h>
+#include <irq.h>
+
+static volatile uint16_t ticks;
+static volatile uint16_t ctc_ticks;
+
+static void on_tick(void)
+{
+    ticks++;
+}
+
+static void on_ctc(void)
+{
+    ctc_ticks++;
+}
+
+/* Диагностика: регистр I до установки (что за режим у DSS?). */
+static uint8_t get_i(void) __naked
+{
+    __asm
+        ld    a, i
+        ret
+    __endasm;
+}
+
+/* Busy-пауза без единого ESTEX-вызова (~симв. полсекунды). */
+static void busy_wait(void)
+{
+    for (volatile uint16_t i = 0; i < 30000u; i++) ;
+}
+
+/* Атомарное чтение 16-битного счётчика, разделяемого с ISR. */
+static uint16_t read_ticks(void)
+{
+    uint16_t v;
+    IRQ_DISABLE();
+    v = ticks;
+    IRQ_ENABLE();
+    return v;
+}
+
+int main(void)
+{
+    /* --- диагностика ДО установки --- */
+    uint8_t old_i = get_i();
+    const uint8_t *vec = (const uint8_t *)(((uint16_t)old_i << 8) + 0xFF);
+    printf("I=%02x, [I:FF]=%02x%02x (DSS isr cand: %04x)\n",
+           old_i, vec[1], vec[0],
+           (unsigned)(vec[0] | ((uint16_t)vec[1] << 8)));
+
+    if (irq_install(on_tick) != 0) {
+        printf("irq_install failed: errno=%d\n", errno);
+        return 1;
+    }
+    puts("irq installed");
+
+    /* Фаза 1: busy-пауза БЕЗ ESTEX — жив ли трамплин/чейн вообще. */
+    busy_wait();
+    printf("phase1: ticks=%u (expect >0)\n", read_ticks());
+
+    puts("phase2: measuring 3 s vs time()...");
+
+    /* Выровняться на границу секунды (time() зовёт ESTEX SYSTIME в
+     * цикле — заодно стресс чейна к DSS). */
+    time_t t0 = time(0);
+    while (time(0) == t0) ;
+    uint16_t start = read_ticks();
+    time_t t1 = time(0);
+    while (time(0) < t1 + 3) ;
+    uint16_t got = read_ticks() - start;
+
+    printf("ticks: %u in 3 s (~%u Hz, expect ~50)\n", got, got / 3);
+
+    /* --- Phase 2: CTC-таймер одновременно с кадровым --- */
+    if (irq_ctc_install(on_ctc, IRQ_CTC_VSYNC_DIV2, IRQ_CTC_VSYNC_DIV3)) {
+        printf("irq_ctc_install failed: errno=%d\n", errno);
+        return 1;
+    }
+    {
+        time_t t3 = time(0);
+        while (time(0) == t3) ;
+        IRQ_DISABLE();
+        uint16_t c0 = ctc_ticks, f0 = ticks;
+        IRQ_ENABLE();
+        time_t t4 = time(0);
+        while (time(0) < t4 + 2) ;
+        IRQ_DISABLE();
+        uint16_t dc = ctc_ticks - c0, df = ticks - f0;
+        IRQ_ENABLE();
+        printf("ctc(vsync): %u in 2 s (~%u Hz), frame in parallel: %u\n",
+               dc, dc / 2, df);
+    }
+    irq_ctc_remove();
+
+    /* CTC на произвольной частоте: 875000/(50*50) = 350 Гц. */
+    if (irq_ctc_install(on_ctc, 50, 50)) {
+        printf("ctc fast install failed: errno=%d\n", errno);
+        return 1;
+    }
+    {
+        time_t t5 = time(0);
+        while (time(0) == t5) ;
+        IRQ_DISABLE();
+        uint16_t c0 = ctc_ticks;
+        IRQ_ENABLE();
+        time_t t6 = time(0);
+        while (time(0) < t6 + 2) ;
+        IRQ_DISABLE();
+        uint16_t dc = ctc_ticks - c0;
+        IRQ_ENABLE();
+        printf("ctc(50x50): %u in 2 s (~%u Hz, expect ~350)\n", dc, dc / 2);
+    }
+    irq_ctc_remove();
+
+    puts("press any key (keyboard must work)...");
+    getch();
+
+    irq_remove();
+    uint16_t frozen = read_ticks();
+    time_t t2 = time(0);
+    while (time(0) < t2 + 1) ;
+    if (read_ticks() == frozen) puts("remove: ticks frozen, OK");
+    else                        puts("remove: FAIL, still ticking");
+
+    puts("irqtest done.");
+    return 0;
+}