libc: IM2 Phase 2b — звук CBL/COVOX через callback fill(), без кольца libc

CBL уже имеет аппаратный буфер 256 Б (2×128, двойная буферизация на
стороне железа) — держать поверх него ещё одно кольцо в libc было бы
лишней копией. cbl_open(freq, fmt, pump_mode, underrun_mode, fill)
регистрирует callback, вызываемый из ISR за очередным блоком; он сам
пропихивает данные приложения (откуда угодно) через cbl_push_otir()/
cbl_push_accel() — без промежуточного буфера.

- два насоса: OTIR (порт 0x4F) и ACCEL (акселератор, спец-страница
  EMM 0xFD@0xC000); OTIR+16-бит запрещён (EINVAL) — по исходнику MAME
  порт данных физически не может собрать 16-бит сэмпл из пары байт;
- форматы CBL_FMT_MONO8/16/STEREO8/16, частоты 7.8..109к;
- CBL_UNDERRUN_APP (по умолчанию, недолив не наша забота) /
  CBL_UNDERRUN_SILENCE (буфер тишины malloc'ится только в этом режиме);
- tests/cbltest: матрица 64 комбинации (2 насоса × 8 форматов × 4
  частоты); tests/cblwav: banked-стрим речи с дискеты (физстраницы
  кэшированы заранее — mem_get_page нельзя звать из fill()/ISR);
  tests/cblstream: единственный случай с собственным кольцом уровня
  приложения (диск нельзя читать из fill()).

Verified в MAME 2026-07-07 — все три теста работают.

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

docs/im2_isr_design.md

@@ -1,7 +1,13 @@
 # IM2 Interrupt Handlers — Design Document
 
-**Status: Phase 1 РЕАЛИЗОВАН 2026-07-06, ИСПРАВЛЕН после отладки**
-(libc/irq: irq_install/irq_remove + трамплин; тест tests/irqtest).
+**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)
 
@@ -77,9 +83,151 @@ SIO_CTC_KEY.asm):
   I/IM 1; atexit-уборка глушит CTC ОБЯЗАТЕЛЬНО (иначе после выхода
   прерывания кГц-частоты душат шелл).
 
-Phase 2b (CBL/COVOX handler — вернуть фильтр 0xFE.7 при активном CBL,
-sample-буфер; фундамент Audio API), ISA-вектора, цепочки нескольких
-хендлеров — не реализовано.
+## 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.
 
@@ -247,7 +395,7 @@ User's ISR НЕ должен:
 
 ## Phase 2 (когда понадобится)
 
-- CBL/COVOX prerequisite handler (для audio playback)
+- ~~CBL/COVOX prerequisite handler~~ — реализован, см. «Phase 2b» выше
 - ISA interrupt handler (для ZX-Bus карт)
 - Multiple user handler chain (e.g. tick + sound)