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>
This commit is contained in:
2026-07-07 09:15:04 +03:00
parent 5184415fc4
commit 8a952b99eb
13 changed files with 418 additions and 124 deletions
+38 -14
View File
@@ -4,15 +4,21 @@
* Механика (docs/im2_isr_design.md):
* - таблица векторов: 257 байт с выравниванием 256 внутри статического
* буфера 513 байт (_irq_state.c), заполняется байтом H = старший
* байт её же адреса; CPU по вектору V читает адрес (H<<8|H) —
* трёхбайтовый `jp _irq_tramp` лежит ВНУТРИ таблицы по смещению H
* (безопасно: внешний вектор — 0xFF, а H < 0xC0; заливка H
* перехватывает и вектора SIO/CTC, если их кто-то включит);
* - трамплин (_irq_tramp.c): AF-пробник порта 0x19 (SIO-A RR0);
* кадровое прерывание → полный save → user handler → restore;
* затем ВСЕГДА jp на обработчик DSS 0x0038 (DSS работает в IM 1;
* SMC-операнд патчится при install) — EI/RETI делает DSS;
* - install: I := H, IM 2; remove: I := старое, IM 1 (штатный режим DSS).
* байт её же адреса; 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
@@ -24,14 +30,32 @@
#define _IRQ_VEC_BUF_SIZE (256 + 257)
extern uint8_t _irq_vec_buf[_IRQ_VEC_BUF_SIZE];
extern isr_t _irq_user; /* NULL = не установлен */
extern uint8_t _irq_old_i; /* I до install */
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; /* счётчик пользователей таблицы */
/* Вход трамплина (asm, _irq_tramp.c). */
/* Порты встроенной периферии 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_install (16-битный адрес). */
/* SMC-операнд `jp` на обработчик DSS (метка в _irq_tramp.c). */
extern uint16_t _irq_dss_target;
#endif
+55
View File
@@ -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;
}
+5 -2
View File
@@ -1,10 +1,13 @@
/*
* _irq_state — данные IM2-модуля: буфер вектор-таблицы, указатель на
* user-handler, сохранённый регистр I. Только данные.
* _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;
+115
View File
@@ -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();
}
+60
View File
@@ -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;
}
+34
View File
@@ -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();
}
+4 -83
View File
@@ -1,96 +1,17 @@
/*
* irq_install — установить user-handler кадрового прерывания (IM 2).
*
* Строит 257-байтную вектор-таблицу (выравнивание 256 в рантайме,
* заполнение байтом H = старший байт адреса таблицы; `jp _irq_tramp`
* лежит внутри таблицы по смещению H — читаются лишь байты
* [0xFF]/[0x100] для внешнего вектора 0xFF; вектора встроенной
* периферии Z84C015 (SIO 0x10..0x1E, CTC 0x06) штатно выключены, но
* заливка H перехватывает и их — чейн на 0x0038 валиден для всех).
*
* ВАЖНО (проверено по docs/samples/sprinterIntLib.asm и
* SIO_CTC_KEY.asm): DSS работает в IM 1 — его обработчик живёт на
* 0x0038, а I=0x3F — наследие Spectrum ROM, НЕ признак IM 2-таблицы.
* Поэтому чейн из трамплина ВСЕГДА идёт на 0x0038 (jp 0x0038 с
* interrupted-PC на стеке в точности имитирует вход IM 1 / RST 38),
* а старое I сохраняется только чтобы вернуть регистр при remove.
*
* irq_remove вешается на atexit — выход без снятия оставил бы I/IM2
* на памяти умершего процесса.
* irq_install — установить user-handler кадрового прерывания.
* Захватывает общую IM2-таблицу (_irq_table_ref) и включает кадровый
* путь трамплина. Детали и результаты отладки: docs/im2_isr_design.md.
*/
#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;
}
int irq_install(isr_t handler)
{
if (!handler) { errno = EINVAL; return -1; }
if (_irq_user) { errno = EBUSY; return -1; }
/* Трамплин и таблица обязаны жить в 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 = (uint8_t *)(((uint16_t)(buf + 255u)) & 0xFF00u);
uint8_t h = (uint8_t)((uint16_t)table >> 8);
IRQ_DISABLE();
/* Старое I — только для восстановления регистра в irq_remove. */
_irq_old_i = irq_get_i();
/* DSS работает в IM 1 — чейн всегда на его обработчик 0x0038.
* НЕ читать «таблицу по I»: I=0x3F — мусорное наследие Spectrum
* ROM, чтение [0x3FFF]/[0x4000] даёт случайный адрес (0x00BF) и
* зависание на первом же прерывании. */
_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);
if (_irq_table_ref() != 0) return -1;
_irq_user = handler;
irq_set_i_im2(h);
IRQ_ENABLE();
/* Выход без снятия = крах шелла (I указывает в память процесса). */
static uint8_t atexit_armed;
if (!atexit_armed) {
atexit_armed = 1;
atexit(irq_remove);
}
return 0;
}
+4 -18
View File
@@ -1,30 +1,16 @@
/*
* irq_remove — снять user-handler и вернуть систему в штатный режим
* DSS: I := сохранённое значение (наследие Spectrum ROM, обычно 0x3F)
* и ВСЕГДА IM 1 — DSS работает в IM 1, его обработчик на 0x0038
* (так же делают сэмплы сообщества: sprinterIntLib.asm
* intRestoreDefaultInterrupt, SIO_CTC_KEY.asm). Идемпотентно;
* вызывается и из atexit.
* irq_remove — снять кадровый user-handler и отпустить IM2-таблицу
* (последний пользователь возвращает I/IM 1 — штатный режим DSS).
* Идемпотентно; вызывается и из atexit-уборки.
*/
#include "_irq.h"
static void irq_restore(uint8_t i_val) __naked
{
(void)i_val;
__asm
;; A = старое I (только регистр; режим DSS всегда IM 1).
ld i, a
im 1
ret
__endasm;
}
void irq_remove(void)
{
if (!_irq_user) return;
IRQ_DISABLE();
_irq_user = 0;
irq_restore(_irq_old_i);
IRQ_ENABLE();
_irq_table_unref();
}