/*
 * irq.h — пользовательские обработчики кадрового прерывания (IM 2).
 *
 * Sprinter шлёт вектор 0xFF от трёх источников: кадр (50 Гц),
 * клавиатура (бит 0 порта 0x19), CBL/COVOX.  Штатно DSS работает в
 * IM 1 (обработчик 0x0038).  Установка обработчика переключает CPU в
 * IM 2 со своей таблицей и зовёт handler'ы ТОЛЬКО на кадровых
 * прерываниях; после них (и на всех прочих источниках) управление
 * всегда передаётся штатному обработчику DSS на 0x0038 — клавиатура,
 * SYSTIME и курсор мыши продолжают работать.  irq_remove() возвращает
 * IM 1/I как было (и вызывается автоматически из exit).
 *
 * ЦЕПОЧКА: можно поставить до IRQ_CHAIN_MAX независимых обработчиков
 * (напр. свой тик + FPS-делитель gfx_set_fps_div).  Порядок вызова =
 * порядок слотов; после remove/add взаимный порядок НЕ гарантируется
 * (переиспользуется первая дыра) — обработчики обязаны быть независимы.
 *
 * ПАМЯТЬ: работает во ВСЕХ режимах (tiny/small/big/huge) — трамплин
 * при коде в W1 копируется в W2 и восстанавливает базовую W1-страницу
 * вокруг вызова (docs/im2_isr_design.md).  Единственное исключение:
 * в small для очень мелких программ данные могут ещё лежать в W1 —
 * тогда установка вернёт -1/EINVAL (перейти на huge или увеличить
 * размер).  Обработчик может быть обычной C-функцией где угодно.
 *
 * Правила для 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);

/* Максимум одновременных кадровых обработчиков в цепочке. */
#define IRQ_CHAIN_MAX 4

/* Добавить обработчик кадрового прерывания в цепочку.
 * 0 — OK; -1 + errno: EINVAL (handler==NULL или данные не в W2),
 * ENOMEM (все IRQ_CHAIN_MAX слотов заняты). */
int  irq_chain_add(isr_t handler);

/* Снять ОДИН обработчик из цепочки (по указателю).  Идемпотентно;
 * освобождение последнего слота возвращает IM 1/I штатному DSS. */
void irq_chain_remove(isr_t handler);

/* Совместимость: irq_install == irq_chain_add (EBUSY больше не бывает —
 * несколько обработчиков легальны; при заполнении слотов — ENOMEM). */
int  irq_install(isr_t handler);

/* Снять ВСЮ цепочку и вернуть IM2-таблицу DSS.  Безопасно звать
 * повторно; вызывается автоматически при exit().  Для точечного
 * снятия — irq_chain_remove. */
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