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/TODO.md

@@ -84,6 +84,22 @@ Quick wins:
       dual-write тест → если работает, кэшировать Port_Y в putpixel
       (~8× меньше OUT для Брезенхэма); если нет — вычистить из доков.
 - [ ] fdmax: лимит манипуляторов и зависание 9-го OPEN — MAME vs железо.
+- [ ] CBL: щелчок перед первым проигрыванием звука за сессию (tests/
+      cbltest, tests/cblwav) — воспроизводится ТОЛЬКО на первом запуске
+      программы за сессию MAME, не зависит от содержимого потока
+      (тон/тишина/речь одинаково).  Похоже на разовый прогрев звуковой
+      подсистемы MAME при первой активации канала — на реальном железе
+      скорее всего отсутствует.  Проверить и закрыть либо описать как
+      реальный аппаратный эффект.
+- [ ] **CBL: помехи в звуке при движении мыши** (tests/cblstream,
+      2026-07-07) — при потоковом воспроизведении движение мыши даёт
+      слышимые артефакты.  Гипотеза (НЕ подтверждена): мышь может
+      делить SIO-канал/детект-бит с клавиатурой (порт 0x19 бит 0,
+      см. _irq_tramp.c), и трамплин классифицирует байты мыши как
+      «клавиатура» → сразу chain на DSS (0x0038), пропуская проверку
+      CBL-хука для ЭТОГО прерывания — при движении мыши часть тиков,
+      которые должны были обслужить CBL-насос, уходят мимо, кольцо
+      недоливается.  Нужно исследование (MAME-дамп/лог трамплина).
 
 ## Known quirks (зафиксированы, обходы в libc)
 

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)
 

docs/libc-reference.md

@@ -168,6 +168,62 @@ font[row*256+char]).
 Handler'у нельзя: ESTEX/BIOS-вызовы, gfx_*/своп окон, акселератор,
 banked-функции; только volatile-глобалы и быстрая работа (<1 мс).
 
+## <cbl.h> — потоковый звук CBL/COVOX (вектор 0xFF, свой ISR)
+
+Без собственного кольца (2026-07-07): у CBL уже есть аппаратный буфер
+256 Б (2×128, двойная буферизация на стороне железа — см. официальную
+доку "5.3 COVOX-Blaster"); библиотека просто зовёт `fill()` приложения
+ИЗ ISR, а оно само пропихивает данные (откуда угодно) через
+`cbl_push_otir/accel` — без промежуточной копии.
+
+| Сигнатура | Описание |
+|---|---|
+| `int cbl_open(freq_code, fmt, pump_mode, underrun_mode, fill)` | включить CBL (`0x90\|fmt\|freq`), зарегистрировать callback; 0 / -1+errno (EBUSY повтор, EINVAL — freq/fmt/pump_mode/underrun_mode плохие или OTIR+16-бит, ENOMEM — буфер тишины) |
+| `void cbl_close(void)` | выключить CBL, снять хук, освободить буфер тишины (если был); висит на atexit |
+| `void cbl_push_otir(const void *src, uint16_t n)` | пропихнуть n байт через `otir` в порт 0x4F; звать ИЗ fill() |
+| `void cbl_push_accel(const void *src, uint16_t n)` | то же акселератором (страница EMM 0xFD@0xC000); единственный путь для 16-бит |
+| `uint16_t cbl_requests(void)` | счётчик запросов блока ISR (~fs/(сэмплов в блоке) в секунду) |
+| `uint16_t cbl_underruns(void)` | счётчик недоливов (`fill` вернул 0 или не задан) |
+| `CBL_FREQ_7K8 .. CBL_FREQ_109K` | коды частоты (биты 3..0 control-порта) |
+| `CBL_FMT_MONO8/MONO16/STEREO8/STEREO16` | формат (биты 5/6 control-порта); блок 128 Б (8-бит) или 256 Б (16-бит), не зависит от моно/стерео; тишина 0x80 (8-бит) / 0x0000 (16-бит, знаковый) |
+| `CBL_PUMP_OTIR / CBL_PUMP_ACCEL` | способ выдачи — см. ниже |
+| `CBL_UNDERRUN_APP / CBL_UNDERRUN_SILENCE` | поведение при недоливе — см. ниже |
+
+`typedef int (*cbl_fill_fn)(uint16_t n);` — callback, зовётся ИЗ ISR за
+очередным блоком (n = `_cbl_block`, 128/256).  **Обязан быть быстрым**
+— никаких ESTEX/BIOS/gfx-вызовов (тот же констрейнт, что у
+`irq_install()`-хендлера); вернуть ненулевое, если реально пропихнул n
+байт.  Диск (read()) читать из fill() НЕЛЬЗЯ — см. tests/cblstream,
+где под это заведено кольцо уровня приложения.
+
+Два насоса (3-й параметр `cbl_open`):
+- **OTIR** (`_cbl_pump_otir`) — `cbl_push_otir()` в порт 0x4F; базовый.
+  **НЕ умеет 16-бит** — `cbl_open(..., MONO16/STEREO16, CBL_PUMP_OTIR,
+  ...)` вернёт EINVAL: по исходнику MAME (sprinter.cpp) порт данных
+  ВСЕГДА кладёт байт как есть в один слот, не собирая пару байт в
+  16-бит значение и не сверяясь с 16-бит флагом вообще.
+- **ACCEL** (`_cbl_pump_accel`) — `cbl_push_accel()` через акселератор
+  в спец-страницу EMM 0xFD, замапленную в окно W3 на 0xC000 (см.
+  docs/converted/accel_r.txt, Forum.txt); размер блока патчится SMC
+  (`LD D,D` + immediate `LD A,n` + `LD L,L` — тот же паттерн, что и в
+  libc/gfx/_gfx_hfill256.c); единственный путь для 16-бит.
+  **Verified в MAME 2026-07-07** (tests/cbltest, вся accel-половина
+  матрицы прошла без ошибок/underrun).
+
+Поведение при недоливе (4-й параметр `cbl_open`):
+- **CBL_UNDERRUN_APP** (по умолчанию, 0) — не забота библиотеки, буфер
+  тишины НЕ аллоцируется, в CBL доигрывает то, что уже лежало в его
+  аппаратном буфере.
+- **CBL_UNDERRUN_SILENCE** (1) — насос сам пропихивает тишину; буфер
+  (128/256 Б по формату) аллоцируется malloc'ом ВНУТРИ `cbl_open()`
+  только в этом режиме.
+`cbl_underruns()` считает недоливы в обоих режимах — диагностика,
+поведение не меняет.
+
+Приватное прерывание, к DSS не чейнится; бит 7 порта 0xFE (запрос
+блока) читается только пока `cbl_open` не закрыт (при выключенном CBL
+бит всегда 1 — MAME-квирк).
+
 ## <palette.h> — низкий уровень (BIOS $A4/$A6)
 
 `pal_load pal_get pal_set_color pal_get_color` (страница 0..7,

docs/size_baseline.tsv

@@ -8,6 +8,9 @@ banklocl	4832
 banktest	3767
 bios_text	4470
 cat	915
+cblstream	6234
+cbltest	6374
+cblwav	6443
 conio	4634
 conio2	3946
 dec_test	860
@@ -23,7 +26,7 @@ gfx_mous	5542
 gfx_text	2560
 hello	4176
 hello2	4251
-irqtest	5834
+irqtest	5881
 ls	4919
 malloc	4462
 mdview	19122