docs: справочник libc API, правила проекта в CLAUDE.md, актуализация TODO (П7)

- docs/libc-reference.md — сводный справочник по всем заголовкам:
  сигнатуры + описание + особенности ABI и квирки
- CLAUDE.md — сборка/проверка (make, size-check, MAME-workflow),
  правила libc (1 функция = 1 модуль, internal _-модули, русские
  комментарии, без = 0, asm-связки), ABI-шпаргалка, структура репо
- docs/TODO.md переписан: открытые задачи наверху (MAME/железо,
  auto-banking, v2: BGI/IM2/audio, gfx-расширения, Port_Y),
  закрытые этапы 5-10 сжаты в «Историю»; снят протухший пункт
  «FILE API rewrite для v2» (сделан в v1), fprintf/fscanf и др.

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

docs/TODO.md

@@ -1,436 +1,153 @@
 # TODO / Roadmap
 
-Открытые задачи в порядке убывания приоритета. По мере появления реальных программ — приоритеты будут смещаться.
+Открытые задачи в порядке убывания приоритета; закрытые этапы — в
+«Истории» внизу.  Текущий срез libc-работ: docs/libc-roadmap.md.
 
-## Этап 5 — malloc / free + banking-aware page allocator ✅ ГОТОВО
-
-- [x] SDCC's `malloc`/`free` + наш `runtime/heap.s` (полностью заменяет library heap.rel, 14000-байтный heap в окне 2)
-- [x] `libc/mem/mem_alloc.c` — page allocator: `mem_alloc_pages`/`mem_free_block`/`mem_get_page`/`mem_info` через ESTEX `$3C/$3D/$3E` + BIOS `$C4`
-- [x] `libc/mem/bank_io.c` — HOME-резидентные `bank_read`/`bank_write`/`bank_load_byte`/`bank_store_byte` со свопом W3 внутри
-- [x] `examples/malloc_test/` — проверка SDCC's malloc (~210 64-байтных allocations через всю heap)
-- [x] `examples/mem_test/` — проверка page allocator: 3 страницы, разные паттерны через bank_write, верификация через bank_read
-
-## Этап 6 — argv parsing + sprinter-cc wrapper ✅ ГОТОВО
-
-- [x] crt0 парсит ESTEX command-line из IX-prefix (inline asm в `runtime/crt0.s`)
-- [x] Strip leading CP/M-style space (DSS quirk)
-- [x] Передача `argc`/`argv` в main() через HL/DE (SDCC __sdcccall(1) ABI)
-- [x] argv[0] = basename .EXE через ESTEX APPINFO ($47 subfn 2)
-- [x] `runtime/crt0_minimal.s` — opt-out для очень маленьких программ
-- [x] `runtime/crt0_banked.s` — теперь тоже парсит argv (parse_argv + get_progname скопированы из crt0.s; будет factored в argv.s когда возьмёмся за libsprinter.lib)
-- [x] Bash-обёртка `bin/sprinter-cc`: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций: `--memory`, `--memory-manual`, `--stack-size`, `--crt0=`, `--bank N=FILE.c`, `--debug`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-
-## Этап 8 — графика (320×256×256 + 640×256×16 + accel + bitmap font) ✅ ГОТОВО
-
-- [x] **8a** Graphics core: `gfx_init`/`gfx_done`/`gfx_clear`/`gfx_putpixel`/`gfx_pal_load`/`gfx_pal_set` (libc/gfx/gfx_core.c). Палитра через BIOS PIC_SET_PAL ($A4). Verified 320×256×256.
-- [x] **8b** Линии/прямоугольники/fill через accelerator (libc/gfx/gfx_lines.c): `gfx_hline`/`gfx_vline` через accel Fill (LD C,C / LD E,E + SMC block-size), `gfx_rect`/`gfx_fill_rect` с heuristic выбором ориентации (h/v bursts count), `gfx_line` с Bresenham для диагоналей. `gfx_clear` тоже переписан на column-major accel (~4× быстрее).
-- [x] **8c** 640×256×16 mode (libc/gfx/gfx_16.c): `gfx_*16` API, HIGH nibble = LEFT pixel (документация misleading), per-row RMW для vline (один байт = 2 горизонтальных пикселя).
-- [x] **8d** Bitmap font + gfx_text (libc/gfx/gfx_text.c): шрифт через BIOS WIN_GET_ZG ($B8), interleaved layout `font[row*256+char]`, `gfx_text`/`gfx_putchar` для 320 mode, `gfx_text16`/`gfx_putchar16` для 640 mode с pair-table lookup.
-
-См. memory/sprinter_graphics.md, sprinter_accelerator.md, sprinter_graphics_16.md, sprinter_font_format.md.
-
-Открытые мелочи (не блокируют):
-- [ ] Шрифт-quad для 640: per-cell палитра (mode 0x82 разрешает 1 из 4 палитр per 16×8 cell) — через прямой доступ к area-описания экрана 0x0300..0x039F
-
-## Auto-banking (см. `memory/banking_roadmap.md` для деталей)
-
-Phase 1 — file-level bin-packing — реализовывать когда проект перерастёт ~30 KB кода.
-
-- [ ] `toolchain/auto_bank.py`:
-    - Парсит размеры из `.rel`-файлов (или из .map после dry-run link'а)
-    - First-fit-decreasing bin-packing
-    - Уважает `#pragma codeseg BANKn` как manual override
-    - Перелинковывает с новыми `-Wl-b_BANKn=...` параметрами
-    - Печатает план распределения
-
-Phase 2-5: incremental rebalance, declarative `banks.toml`, function-level, call-graph-aware. Только если/когда понадобится.
-
-## Bank-local static data (mutable data в том же банке что и код) — ✅ ГОТОВО
-
-- [x] Пример `examples/bank_local_data/` — функция в BANK1 со своим writable BSS array + const table + malloc-тест
-- [x] `mkexe -p 0` для нулевого padding банков (BSS-storage обнуляется при загрузке)
-- [x] Канонический рецепт: `--codeseg BANK1 --constseg BANK1 --dataseg BANK1` для bank1.c + `-Wl-b_BANK1=0x1C000` для линковки. **`--dataseg BANK1` РАБОТАЕТ** — раньше казалось обратное из-за trampoline bug который маскировал результат.
-- [x] **Критичный фикс trampoline'a в runtime/bank.s** — старый `pop af; out (n), a` клобберил A → все banked-функции возвращающие uint8_t тихо возвращали мусор. Новый `pop bc; out (c), b` сохраняет A.
-- [x] **malloc из banked-функции работает прозрачно** — heap живёт в W2 (HOME), W2 никогда не свапается trampoline'ом, pointer валиден из любого контекста. См. memory/bank_local_data_pattern.md.
-- [x] Документация в memory: `memory/bank_local_data_pattern.md` (полный рецепт + malloc + nuances), `memory/sdcc_banking.md` (trampoline fix)
-- [ ] Опционально — расширить `check_banks.py` чтобы показывать разбивку size = code + const + bss per bank (cosmetic)
-
-Зачем: для модулей с большим private state (level loader, audio engine, scene data). Экономит W2 heap для динамики, а статика остаётся в бэке.
-
-## Подсказки из solid-c (нативный Sprinter C — `third_party/solid-c/`)
-
-После анализа solid-c'овской libc (см. `memory/solid_c_findings.md`) выявлены готовые паттерны для следующих недостающих функций. Приоритет от **высокого** к низкому:
-
-### High-priority gaps (легко портировать, большая польза)
-- [x] **`errno` + `strerror`/`perror`** — табличка 32 ошибок (libc/io/errno.c)
-- [x] **Расширенный `open()`** для O_CREAT/O_TRUNC/O_APPEND/O_EXCL state machine
-- [x] **`atexit`** — 8-callback LIFO + `exit()` + `_exit()` (libc/io/atexit.c)
-- [x] **`setjmp`/`longjmp`** — 6-байт jmp_buf={sp,ix,pc} (libc/io/setjmp.c)
-- [x] **`sleep(seconds)`** — 50Hz halt-loop (libc/io/sleep.c)
-- [x] **ESTEX ENV API** ($46, getenv/putenv) — libc/io/env.c. Учли doc-bug: реально A=0 это NOT FOUND
-
-### Medium-priority (нужно для shell-like утилит)
-- [ ] **Mouse driver** — `rst $30h`, 17 функций. **Сначала тест что работает в MAME**.
-- [x] **`ffirst`/`fnext` + ffblk_t struct** для directory listing — реализовано, demo: ls.exe
-- [x] **`getdatetime`/`setdatetime`** через ESTEX $21/$22 — libc/io/time.c, demo: time_dir_test
-- [x] **`chdir`/`getcwd`/`mkdir`/`rmdir`** — wrappers для ESTEX $1B-$1E — libc/io/fsdir.c
-- [x] **conio: `kbhit`/`getch`/`getche`/`cputs`/`clrscr`/`gotoxy`** — реализовано
-- [x] **conio extras**: `wherex`/`wherey` ($53), `wrchar`/`rdchar` ($58/$57), `textmode_get/set` ($50/$51), `clrscr_attr` ($56) + COLOR macros
-
-### Low-priority — ✅ FILE* stack ГОТОВО
-
-- [x] **Минимальный unbuffered FILE\*** — `libc/stdio/file.c` + `libc/include/stdio.h`. fopen/fclose/fputs/fgets/fread/fwrite/fseek/ftell/rewind/feof/ferror/clearerr/fflush + stdin/stdout/stderr как pseudo-streams. См. `memory/file_star_design.md` и `examples/filetest`.
-- [ ] fprintf / fscanf — нужна printf-через-callback machinery. Пока пользователь может `sprintf(buf, ...) + fputs(buf, fp)`.
-- [ ] Опциональный buffered mode (setvbuf, line/block buffering) — если когда-то понадобится.
-
-### POSIX time API — ✅ ГОТОВО
-- [x] `libc/io/posix_time.c` — time/localtime/gmtime/mktime/asctime/ctime поверх getdatetime. SDCC's time.rel избегаем (нельзя override _RtcRead). См. `examples/ptime`.
-
-### sys/stat — ✅ ГОТОВО
-- [x] `libc/io/stat.c` — POSIX stat/fstat. Гибрид open+fstat для файлов, ffirst+iter для папок (включая "."/".."). См. `examples/stattest` и `memory/estex_ffirst_dotdot.md`.
-
-### assert — ✅ ГОТОВО (используем SDCC's __assert через fallback include path)
-
-## libc/stdlib — ✅ не нужно делать (см. memory/sdcc_stdlib_works.md)
-
-Проверено через `examples/stdlib_test/`: SDCC z80.lib содержит работающие реализации:
-- `atoi/atol/atof, strtol/strtoul, rand/srand, qsort/bsearch, abs/labs, div/ldiv`
-- Полный `<string.h>` (memchr/cmp/set/cpy, strcat/cmp/cpy/len/chr/spn/etc.)
-- `<ctype.h>` (toupper/tolower)
-- `<math.h>` (sinf/cosf/sqrtf/etc.)
-
-Линкер автоматически тянет из z80.lib когда нужно. **НЕ переписывать**.
-
-Наши Sprinter-specific обязательные модули остаются: atexit, env, errno, setjmp, putchar/puts/getchar, conio, fsdir, time, mouse, open/read/lseek/close.
-
-## Build-system: libsprinter.lib + sprinter-cc — ✅ ГОТОВО
-
-- [x] `lib/Makefile` — собирает каждый libc/*.c в `.rel`, архивирует через sdar в `lib/sprinter.lib`
-- [x] Включает runtime/bank.s и runtime/heap.s (auto-pulled при __banked/malloc)
-- [x] `bin/sprinter-cc` — bash-wrapper: `sprinter-cc -o foo.exe foo.c` одной строкой
-- [x] Поддержка опций `--crt0=default|minimal|banked`, `--bank N=FILE.c`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
-- [x] `examples/hello_sccc/` — демо: `hello.c` собирается за один shell-вызов, размер совпадает с ручным Makefile (925 байт)
-- [x] Split `putchar.c` → `putchar.c` + `puts.c` для per-function granularity (puts override SDCC's z80.lib version)
-- [x] Включён в `make all` (зависимость `lib` перед `examples`)
-
-Возможные улучшения (опционально):
-- [ ] Мигрировать остальные examples на sprinter-cc вместо ручных Makefile (косметика)
-- [ ] Дальнейшая декомпозиция libc/*.c per-function (но текущая granularity уже даёт нужный размер — линкер пакетует .rel целиком, и для большинства файлов это одна функция)
-
-## Этап 9 — memory modes для sprinter-cc
-
-DSS выделяет страницы памяти по размеру приложения: < 16 KB → одна страница, в остальные окна подключается «страница #FF» (read=0xFF, write игнорится). Из-за этого CODE-в-W1 + DATA-в-W2 для маленькой программы молча ломается. См. [memory/sprinter_memory_modes.md](../../.claude/projects/-Volumes-SAM8-Projects-DIY-Z80-Sprinter-C-Compiler/memory/sprinter_memory_modes.md).
-
-- [x] **`tiny`**: всё (CODE+DATA+стек) в W2. Default. Verified hello/argv/conio/malloc/file/etc.
-- [x] **`--memory MODE` флаг в sprinter-cc**: parser + per-mode дефолты CODE_LOC/DATA_LOC, override через явные `--code-loc`/`--data-loc`. tiny работает; small/big/huge компилируются с warning'ом (runtime не готов). Реализовано 2026-05-30.
-- [x] **`--memory-manual SPEC`**: парсит `CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3`. Реализовано 2026-05-30.
-- [x] **`small` runtime**: `runtime/crt0_small.s` использует ESTEX `$3D GETMEM` + `$3A SETWIN2` чтобы выделить и замапить W2-страницу ДО gsinit. **НЕ** BIOS `$C4` — стек на этом этапе в W1 (boot_stack в HOME), а BIOS требует стек в W2. После маппинга SP переключается на 0xBFFE, дальше стандартный flow. Реализовано 2026-05-30, verified hello.exe.
-- [x] **`small` auto-detect для >16 KB программ**: `crt0_small.s` читает порт `0xC2` (текущая страница в W2 — не `0xA2`! это W1). Если 0xFF — выделяет page; иначе DSS уже сделала это (программа сама вылезла в W2). Один crt0 покрывает 0..30 KB. mkexe также разрешает HOME span W1+W2 (0x4000..0xBFFF). Verified hello: small (5 KB файл, SETWIN2 path) + 32 KB файл (auto-skip). Реализовано 2026-05-30.
-- [x] **`big` runtime** (tiny + banked code в W1): параметризовали `crt0_banked.s` + `bank.s` через `.ifdef BANK_W1` — другой banking port (0xA2 vs 0xE2), другой load-addr (0x4000 vs 0xC000). sprinter-cc prepend'ит `BANK_W1 = 1` при `--memory big`, передаёт `mkexe -B 0x4000`. Пример `examples/banked_big/`. Реализовано 2026-05-30.
-- [x] **`huge` runtime** (small + banked code в W3): merge W2-detect логики из `crt0_small.s` в `crt0_banked.s`. Существующий пример `examples/banked/` теперь использует MEMORY=huge. Реализовано 2026-05-30.
-- [x] **`--debug` флаг**: prepend `DEBUG_RT = 1` в crt0 + `-DDEBUG_RT` в sdcc. Открывает symbol `_w2_self_allocated` (uint8_t) — runtime diagnostic кто аллоцировал W2. Реализовано 2026-05-30.
-
-### Дизайн-решения по libc и crt0
-
-**Одна `sprinter.lib`** работает для всех memory mode — `.rel`-члены relocatable, SDLD делает dead-code elimination per-member (без графики не подтягивает `gfx_core.rel` и т.д.). Verified hello vs malloc_test через map-файлы.
-
-**`gfx.lib` отдельно — НЕ нужен**: dead-code elimination уже работает.
-
-**`libc_banked` (libc в bank вместо HOME)** — идея на потом, когда HOME (16 KB) забит user-кодом + libc в `huge` mode. Реализуется через `--codeseg BANK0` при компиляции libc; trade-off: trampoline ~30 циклов на каждый libc-вызов. Триггер: реальная программа упрётся в HOME budget.
-
-**HW-зависимые модули — `sprinter_home.lib` отдельно.** Часть libc физически не может быть забанкована в W3, потому что она РАБОТАЕТ с W3:
-- `gfx_*` — пишет в видеопамять `0xC000+` после swap W3 на video page
-- `bank_io` (mem_alloc_pages/bank_read/bank_write) — swap'ит W3 через `OUT (0xE2)`
-- Будущие ISR — прерывание может прийти когда W3 на чём угодно
-
-В huge mode эти модули ДОЛЖНЫ остаться в HOME (W1). Когда будем делать `libc_banked`, **одновременно** выделяем `sprinter_home.lib` (HOME-only) из `sprinter.lib` (bankable). Финальная схема:
-```
-sprinter_home.lib    HOME-only:   gfx, bank_io, ISR shims
-sprinter.lib         bankable:    printf, malloc, string, conio, stdio, env, ...
-sprinter_banked.lib  тот же sprinter.lib но --codeseg BANK0 (для huge)
-```
-Триггер: реализация `--memory huge` runtime.
-
-**crt0 — по одному на mode:**
-- `crt0.s` — текущий, для **tiny/big**: SP=0xBFFE, парсит argv (W2-ресурс уже выделен DSS).
-- `crt0_minimal.s` — текущий, для tiny без argv.
-- `crt0_small.s` — **новый, step 3**: для **small/huge**, аллоцирует W2 через `mem_alloc_pages` ДО gsinit, маппит в порт `0xA2`, потом стандартный flow.
-- `crt0_banked.s` — текущий, для **big**: trampoline-таблица для W3 банков, CODE в W2.
-- `crt0_banked_small.s` — **новый**: huge = small (W2-alloc) + banked (W3 trampolines).
-
-sprinter-cc подбирает crt0 по `--memory` mode (сейчас `--crt0=` это override).
-- [x] **Настраиваемый размер стека**: флаг `sprinter-cc --stack-size BYTES`. Wrapper генерирует `heap_top.s` с `___sdcc_heap_end = stack_top + 1 - stack_size`, отдельный .rel линкуется per-program. Default ≈1278 байт (heap_top=0xBB00) из `runtime/heap_top.s`. Реализовано 2026-05-30.
-
-Интерфейс: `sprinter-cc --memory [tiny|small|big|huge|manual] [--memory-manual SPEC] [--stack-size N] foo.c`. `--memory-manual` имеет смысл только с `--memory manual`.
-
-## Known issues / quirks
-
-- **ESTEX $46 ENV API**: ✅ работает. Док-ция в `DiskSyscalls.txt v1.6` ошибочно описывает return-status — A=0 это NOT FOUND, не FOUND. Зафиксировано в `memory/sprinter_platform.md`.
-
-## ОБЯЗАТЕЛЬНЫЕ ЗАДАЧИ ДЛЯ V2 (после релиза v1)
-
-### Turbo-C-style graphics API (BGI-like) — **MUST для v2**
-
-Расширить наш `gfx_*` API до уровня **Turbo-C `<graphics.h>`** (BGI) для MS-DOS.
-Программисты привыкшие к Turbo-C должны переносить графический код 1-в-1.
-
-**Что должно быть** (на основе Borland BGI):
-
-Setup/teardown:
-- `initgraph()` / `closegraph()` — у нас сейчас `gfx_init`/`gfx_done`, добавить alias
-- `getmaxx()` / `getmaxy()` — макрос на GFX_WIDTH-1 / GFX_HEIGHT-1
-- `cleardevice()` — alias to gfx_clear
-- `getgraphmode()` / `setgraphmode()` — у нас get_videomode/set_videomode
-
-Color/palette:
-- `setcolor(c)`, `getcolor()` — current draw color
-- `setbkcolor(c)`, `getbkcolor()` — background color
-- `setpalette(idx, c)` — палитра entry
-- `getpalette(&info)` — read all palette
-
-Primitives (мы уже имеем эквиваленты — добавить BGI-имена как aliases):
-- `putpixel(x, y, c)` — есть как gfx_putpixel
-- `getpixel(x, y)` — нужно реализовать (RMW обратное — IN)
-- `moveto(x, y)`, `lineto(x, y)`, `linerel(dx, dy)` — current point + line drawing
-- `line(x1, y1, x2, y2)` — есть как gfx_line
-- `rectangle(x1, y1, x2, y2)` — есть как gfx_rect (но другой API: x1,y1,x2,y2 vs x,y,w,h!)
-- `bar(x1, y1, x2, y2)` — есть как gfx_fill_rect
-- `bar3d(x1, y1, x2, y2, depth, topflag)` — новое: rect + 3d edges
-- `circle(x, y, r)`, `arc(...)`, `ellipse(...)`, `pieslice(...)` — новые primitives
-- `fillpoly()`, `drawpoly()` — полигоны
-- `floodfill(x, y, border_color)` — заливка
-
-Text on graphics screen:
-- `outtext(s)` / `outtextxy(x, y, s)` — есть как gfx_text (alias)
-- `settextstyle(font, dir, size)` — multiple bitmap fonts
-- `gettextsettings(&info)`
-- `textwidth(s)` / `textheight(s)` — measure
-
-Image manipulation:
-- `imagesize(x1, y1, x2, y2)` — bytes needed for getimage
-- `getimage(x1, y1, x2, y2, buf)` — save rect to buffer
-- `putimage(x, y, buf, op)` — paste back with COPY_PUT/XOR_PUT/AND_PUT/OR_PUT/NOT_PUT
-
-Clipping/viewport:
-- `setviewport(x1, y1, x2, y2, clip)` — drawing clip rect
-- `getviewsettings(&info)`
-- `clearviewport()`
-- `setactivepage(p)` / `setvisualpage(p)` — двойная буферизация (Sprinter имеет 2 screen)
-
-Line style:
-- `setlinestyle(style, pattern, thickness)` — SOLID_LINE / DOTTED_LINE / etc.
-- `getlinesettings(&info)`
-
-**Acceptance:** перенос типичной Turbo-C BGI программы (рисующей с использованием
-moveto/lineto/circle/bar/setcolor) должен работать без существенных правок.
-
-**Notes:**
-- BGI fonts (TRIPLEX/SANS_SERIF/GOTHIC) — у нас один BIOS font, остальные нужно
-  добавить (как bitmap data в lib)
-- imagesize/getimage/putimage — самые востребованные для game/animation
-- Active/visual page (двойная буферизация) — Sprinter поддерживает 2 graphics pages,
-  нужен API switching
-
-См. также `examples/` Turbo C 2.x BGIDEMO как reference что нужно.
-
-### IM2 Interrupt Handlers — **MUST для v2**
-
-User-задаваемые ISR через Z80 IM 2 mode.  Нужны для:
-- Timer ticks (50 Hz frame counter, плавная анимация)
-- Music playback (AY, COVOX)
-- Real-time games (input + game logic + render в interrupt-driven)
-- Async keyboard / mouse handling
-
-**Status:** ОТЛОЖЕНО до v2.  Полный research + design в `docs/im2_isr_design.md`.
-
-**Решение по архитектуре:** реализовать как отдельный memory mode `--memory im2`
-(вместо того чтобы лезть во все существующие crt0).  Detail'и в design-doc.
-
-**Резюме research'а** (полный текст в `docs/im2_isr_design.md`):
-- Vector 0xFF — frame + keyboard + CBL.  Disambiguation по портам 0x19 / 0xFE
-- Mouse hardware-IRQ не приходит (на текущей плате)
-- Vector table / ISR / stack ОБЯЗАНЫ быть в W2 (0x8000..0xBFFF)
-- DSS имеет свой IM 2 handler — нужно chain'иться (иначе клавиатура / SYSTIME ломаются)
-
-### Прочие крупные пункты для v2
-
-- [ ] **FILE API rewrite — buffered streams** — текущая реализация в
-  `libc/stdio/file.c` это provisional unbuffered shim (каждый fputc/fgetc
-  = один read/write syscall).  Нужна полноценная buffered семантика
-  как в Solid-C:
-
-  ```c
-  typedef struct {
-      uint   flags;     // +0..1   file status flags
-      int    level;     // +2..3   empty/fill level of buffer
-      char  *curp;      // +4..5   current active pointer
-      int    fd;        // +6..7   underlying low-level fd
-      char  *buffer;    // +8..9   data transfer buffer
-      char   hold;      // +10     ungetc byte if no buffer
-      short  token;     // +11..12 reserved
-      char   dummy;     // +13     reserved
-  } FILE;
-  ```
-
-  stdin/stdout/stderr — fd-маркеры `0 / -1 / -2`.  Отрицательные для
-  stdout/stderr выбраны намеренно: ESTEX OPEN может вернуть positive
-  small fd (1, 2, …) для обычного файла → если бы stdout=1, реальный
-  fd=1 сталкивался бы с идентификатором.  fd=0 для stdin безопасно
-  (ESTEX 0 не возвращает).  Сами fd не передаются в syscall'ы —
-  диспетчеризация по флагам `_F_CONIN/_F_CONOUT`.
-
-  Принтер-потоки (stdaux/stdprn) НЕ реализуем — Sprinter принтерной
-  API не имеет.
-
-  Альтернатива — взять реализацию из third_party/solid-c (sources в
-  `SRC/CLIB/`); там есть готовый buffered FILE + fopen/fread/fwrite/
-  fseek/setvbuf и т.д.  Адаптировать к нашим open/read/write/lseek.
-
-  При rewrite заодно решить deferred issues stdio-review:
-  - `fwrite` short-write должен ставить `_F_ERROR`
-  - `fgets(buf, 1, fp)` — стандарт говорит "empty string", мы вернули NULL
-  - `mode_to_flags` — break-out на '+' (cosmetic)
-
-- [ ] **Audio API** — AY-3-8910 + COVOX через прерывания (требует IM2)
-- [ ] **ISA-8 slot support** — ZX-Bus карты (sound, network, etc.) — требует IM2 + чтения portов
-
-## Прочие задачи (v1 backlog, не блокирующие)
-
-- [x] **#9: text I/O split (Turbo-C style)** — stdio (puts/printf/putchar) теперь fast no-attr через PCHARS/PUTCHAR. conio (cputs/cprintf/putch) применяет attr через textcolor/textbackground/textattr. KEEP_EXIST_ATTR → conio fallback на fast path. Verified в hello.exe. См. `memory/text_output_api_split.md`. Реализовано 2026-05-31.
-- [x] **Mouse API полный** (резидентный driver, RST 30h) — все 14 функций обёрнуты (init/show/hide/refresh/read/goto/bounds/text_cursor/load_cursor/get_cursor/get/set_sensitivity/video_mode_changed). См. `memory/mouse_api.md`. Verified в MAME 2026-05-31. Sensitivity = divider (меньше = быстрее).
-- [ ] Interrupt handlers — IM 2 vector table в HOME для user ISR'ов
-- [ ] Поддержка `restore SP on EXIT` (паттерн из z88dk +pps) — проверить нужно ли
-- [ ] CI: автоматически запускать MAME с `-aviwrite` для screenshot-сравнения, чтобы тесты примеров проходили без человека
-
-## Идеи на потом
-
-- Поддержка `<setjmp.h>` (есть в SDCC stdlib — нужно протестировать что наш crt0 совместим)
-- `<time.h>` через ESTEX SYSTIME (`$21`) и CMOS BIOS-функции
-- ZX Spectrum-совместимый режим как отдельный target (для портирования спектрумовских программ)
-- Поддержка ZX-Bus карт (sound, network, etc.) — нужны драйверы
-- Profile-guided optimization tools (hot/cold detection) для крупных программ
-
-## Linker duplicate-symbol warnings (благоприятные, отфильтрованы)
-
-Когда мы сознательно overrides'им SDCC z80.lib функции собственной версией в `sprinter.lib`, `sdldz80` пишет `?ASlink-Warning-Definition of public symbol '...' found more than once`. Линкер берёт первое найденное определение (наше), поэтому поведение корректное — warning только noise.
-
-Текущие overrides:
-- `_puts` — наша версия через PCHARS+\r\n vs SDCC posix puts
-- `___sdcc_heap` — наш heap в W2 vs SDCC's стандартный
-- `_asctime`, `_localtime` (и возможно другие из time) — наш `posix_time.c` через ESTEX SYSTIME vs SDCC's `time.rel` который зависит от `_RtcRead`
-
-**Текущее решение:** `bin/sprinter-cc` отфильтровывает warning-блок (warning + 2 follow-up `Library:` строки) из вывода `sdc
-
-c`. Через `-v` (verbose) всё показывается. Реализовано через awk-pipe.
-
-**Возможные улучшения:**
-- Перейти на explicit `--nostdlib` + ручной список нужных модулей из z80.lib (string, math, stdlib без override'нутых) — убрать ИСТОЧНИК warning'ов, не маскировать
-- Или: переименовать наши `_puts` → `_puts_sprinter` + alias через linker flag (не уверен что SDCC поддерживает)
-- Или: оставить как сейчас (рабочее и benign) — приоритет низкий
-
-## TODO: проверить на реальном железе
-
-- [ ] **Port_Y banking trick** (`docs/part2/SprinterGraphics programming.txt`):
-      доку утверждает что после `OUT (0x89), Y` адреса 0xC000+0x400*N в окне W3
-      маппятся на строки Y..Y+15 (одно программирование → 16 строк).
-      Empirical 2026-06-01 в MAME 0.283 этот trick **не работает** — пиксели
-      по адресам выше 0xC000+row_width уходят в невидимую область.  Канонический
-      `docs/samples/plasma2.asm` тоже не использует banking, переустанавливает
-      Port_Y per row.
-      План:
-      1. Получить доступ к реальному Sprinter
-      2. Запустить тест dual-write (`_gfx_putpixel_raw` + второй write в `0xD000+x`)
-      3. Если на железе видны двойные линии → бага MAME, открыть issue с
-         минимальным репро
-      4. Если на железе тоже одна линия → документ неверный, удалить упоминание
-         из доки и просто оставить текущую реализацию (Port_Y per pixel)
-      5. Если banking работает на железе → внедрить кэширование Port_Y в
-         `_gfx_putpixel_raw` (sentinel out-of-range, см. memory/gfx_port_y_banking.md)
-
-      Связанный выигрыш для Bresenham (60-pixel диагональ) — около 8× меньше
-      OUT (0x89) операций, для `gfx_fill_rect 320x256` — 16× меньше.  Не блокирует
-      release v1.
-
-## GFX: расширения по `docs/part2/accelerator_doc.txt`
-
-После прочтения детального accelerator doc выявлены незакрытые направления.
-Сейчас в коде используется только горизонтальный/вертикальный Fill mode.
-
-### Quick wins для текущих primitives
-
-- [ ] **Заменить SMC на `LD A, (var)` для block-size**.  Документ явно
-      разрешает `LD A, (HL)`, `LD A, (BC)`, `LD A, (DE)` (но не `LD A, r`).
-      Это уберёт SMC complexity в `gfx_lines.c:hfill_chunk/vfill_chunk` и
-      `gfx_16.c:g16_hfill_chunk`.  Запрещено только register-to-register.
-- [ ] **Кэширование block-size**.  Документ показывает что accel запоминает
-      block size между bursts (см. `Horizontal_Line_Fill`: устанавливают
-      size + `LD B,B` отключение, потом включают Fill mode и используют
-      сохранённый size).  Для `gfx_fill_rect` с 100 одинаковыми
-      строками — установить size 1 раз, а не 100.
-
-### Bank-prefix modes (port 0xE2 bits)
-
-Документ показывает три варианта банка видеостраницы помимо стандартного 0x50:
-
-| Bank byte | Effect |
-|---|---|
-| 0x50 | Normal write — пишется в shadow + видимый |
-| 0x54 | "no copy in main shadow RAM" |
-| 0x58 | **"FF is transparent"** — байт 0xFF при write оставляет background |
-| 0x5C | both |
-
-Bank 0x58 объясняет почему mouse cursor рисуется с 0xFF-прозрачностью.
-Это путь к **sprite-blending через accel block copy**:
-
-- [ ] **`gfx_set_bank_transparent(on)`** или флаг в `gfx_set_bank` для
-      выбора 0x50/0x58 при отрисовке sprite'ов
-- [ ] Использовать в новом `gfx_blit()` чтобы по факту получать
-      transparent sprites через accel-копию
-
-### Block copy mode (sprite blit'ы)
-
-`LD L,L` (horizontal) и `LD A,A` (vertical) — режим копирования блока через
-256-байтную accel memory.  Это базис для blit'ов.
-
-- [ ] **`gfx_blit(src_data, x, y, w, h)`** — копирование sprite'а
-      (произвольный размер, через accel)
-- [ ] **`gfx_blit_transparent(src, x, y, w, h)`** — с использованием bank 0x58
-
-См. `Draw_Restangle_Data` в accelerator_doc.txt как референс.
-
-### AND / OR / XOR operations через accel
-
-Документ показывает что accel поддерживает логические операции с блоками
-данных.  Применения:
-- XOR — инверсия области (выделение selection в UI)
-- OR / AND — masking, alpha-style blending
-- См. пример в accelerator_doc.txt: "256 bytes block coding via XOR"
-
-- [ ] **`gfx_xor_rect`** / **`gfx_or_rect`** / **`gfx_and_rect`** —
-      примитивы логических операций над прямоугольником
-- [ ] **`gfx_invert_rect(x, y, w, h)`** — alias на xor с 0xFF
-
-### Bitmap fonts разных размеров
-
-Сейчас `gfx_text` / `gfx_putchar` хардкоженно работают с 8×8 шрифтом
-(BIOS WIN_GET_ZG возвращает 256×8 байт).  Для будущих UI / титульников
-нужны:
-- [ ] **`gfx_set_font_size(w, h)`** — переключить ширину/высоту glyph'а
-- [ ] **`gfx_set_font_data(ptr, w, h, advance)`** — заменить указатель
-      на пользовательский шрифт + размеры
-- [ ] Поддержка **proportional** (advance != w) шрифтов — добавить
-      array advance[256] на ширину каждого glyph'а
-- [ ] **Big-font режимы**: 8×16, 16×16, 16×8 (для титульников)
-- [ ] Возможно отдельный API `gfx_text_ex(x, y, str, font_id)` где
-      font_id выбирает один из загруженных шрифтов
-- [ ] **Anti-alias 2-bit шрифты** (бит фон / бит граница / 2-бит alpha?)
-      — far future, для smooth UI
-
-## Финальный этап оптимизаций (не сейчас)
-
-- **`gfx_line` через accel для пологих диагоналей** — Bresenham для линии с |dy| << |dx| (или наоборот) выдаёт длинные runs одинакового Y (или X): пиксель, пиксель, пиксель, шаг Y, пиксель, пиксель... Каждый такой run — это готовый аргумент для `gfx_hline` (или `vline`).  
-  План исследования: посчитать длину runs как функцию от наклона; решить минимальный run length, при котором выгоднее accel hline чем N×putpixel (overhead accel ~20µs, putpixel ~5µs — accel выгоднее при run ≥ 4-5 px); для крутых диагоналей (dx ≈ dy) оставить Bresenham, для пологих — run-length-based fill.
-  Сейчас `gfx_line` orthogonal cases уже через accel — оптимизировать только косые.
-
-- **`gfx_fill_rect` с одним W3-swap на всю операцию** — сейчас каждый внутренний `gfx_hline`/`gfx_vline` делает свой DI/save-W3/restore-W3/EI. Можно сделать internal `_fill_rect_inner` который держит W3 замапленным и DI весь цикл; ~20µs × количество строк/столбцов экономии. Применимо ко всем композитным примитивам.
+## Ближайшее
+
+- [ ] **П6/железо**: MAME-смоук всех тестов после libc-сплита (conio,
+      ptime, stattest, mouse, gfx_demo/gfx_d16/gfx_text/gfx_mous —
+      трогался asm акселератора); затем прогон на реальном Sprinter
+      (mdview2 + FILE* v2 + fdmax — подтвердить лимит 8 манипуляторов
+      и зависание DSS на 9-м OPEN)
+- [ ] Мигрировать оставшиеся examples на sprinter-cc вместо ручных
+      Makefile (косметика)
+- [ ] check_banks.py: разбивка size = code + const + bss per bank
+
+## Auto-banking (memory/banking_roadmap.md)
+
+Phase 1 — file-level bin-packing (`toolchain/auto_bank.py`) — когда
+проект перерастёт ~30 KB кода: парсинг размеров из .rel/.map,
+first-fit-decreasing, уважение `#pragma codeseg BANKn`, перелинковка,
+печать плана.  Phase 2-5 (rebalance, banks.toml, function-level) —
+по потребности.
+
+## ОБЯЗАТЕЛЬНОЕ ДЛЯ V2
+
+### Turbo-C-style graphics API (BGI-like)
+
+Расширить `gfx_*` до уровня Turbo-C `<graphics.h>`: initgraph/
+closegraph/cleardevice-алиасы, current point (moveto/lineto/linerel),
+setcolor/setbkcolor, getpixel, circle/arc/ellipse/pieslice, drawpoly/
+fillpoly, floodfill, bar/bar3d, outtext[xy]/settextstyle/textwidth,
+imagesize/getimage/putimage (COPY/XOR/AND/OR/NOT_PUT), setviewport/
+клиппинг, setactivepage/setvisualpage (2 страницы есть), setlinestyle.
+Acceptance: типичная BGI-программа переносится без существенных
+правок.  Референс: Turbo C 2.x BGIDEMO.
+
+### IM2 Interrupt Handlers
+
+User-ISR через IM 2 — timer ticks, музыка (AY/COVOX), real-time
+игры, async input.  Решение: отдельный memory mode `--memory im2`.
+Полный research/design: docs/im2_isr_design.md (vector 0xFF общий,
+disambiguation по портам 0x19/0xFE; таблица/ISR/стек в W2; chain к
+DSS-хендлеру обязателен).
+
+### Прочее v2
+
+- [ ] **Audio API** — AY-3-8910 + COVOX (требует IM2)
+- [ ] **ISA-8 slot support** — ZX-Bus карты (требует IM2)
+
+## GFX: расширения по accelerator_doc.txt
+
+Quick wins:
+- [ ] block-size через `LD A,(nn)` вместо SMC (док разрешает LD A,(HL/BC/DE))
+- [ ] кэширование block-size между burst'ами (accel помнит размер)
+
+Новые возможности:
+- [ ] `gfx_blit` / `gfx_blit_transparent` — block copy (LD L,L / LD A,A),
+      прозрачность через bank 0x58 («FF is transparent»)
+- [ ] `gfx_xor_rect` / `gfx_or_rect` / `gfx_and_rect` / `gfx_invert_rect`
+- [ ] шрифты ≠ 8×8: gfx_set_font_data(ptr,w,h,advance), proportional,
+      8×16/16×16, отдельный font_id API; font-quad для 640×256
+      (per-cell палитра через дескрипторы 0x0300..0x039F)
+
+Оптимизации (не сейчас):
+- [ ] gfx_line через accel для пологих диагоналей (runs ≥ 4-5 px)
+- [ ] композитные примитивы с одним W3-swap на операцию
+
+## Прочий backlog
+
+- [ ] factoring parse_argv из crt0/crt0_banked в общий argv.s
+- [ ] `restore SP on EXIT` (паттерн z88dk +pps) — проверить нужность
+- [ ] CI: MAME с -aviwrite для screenshot-сравнения без человека
+- [ ] linker duplicate-symbol warnings: сейчас фильтруются в
+      sprinter-cc (наши overrides _puts/___sdcc_heap/_asctime/…);
+      радикально — --nostdlib с ручным списком модулей z80.lib
+- [ ] ZX Spectrum-совместимый target; ZX-Bus драйверы; PGO-tools
+
+## Проверить на реальном железе
+
+- [ ] **Port_Y banking trick** (адреса 0xC000+0x400*N → строки
+      Y..Y+15): в MAME 0.283 НЕ работает (2026-06-01).  На железе:
+      dual-write тест → если работает, кэшировать Port_Y в putpixel
+      (~8× меньше OUT для Брезенхэма); если нет — вычистить из доков.
+- [ ] fdmax: лимит манипуляторов и зависание 9-го OPEN — MAME vs железо.
+
+## Known quirks (зафиксированы, обходы в libc)
+
+- ESTEX $46 ENV: A=0 это NOT FOUND (док врёт) — memory/sprinter_platform
+- ESTEX WRITE $14: на успехе DE=0, не счётчик; успех = CF=0 & A=0 —
+  memory/estex_write_de_quirk
+- DSS: 8 манипуляторов, 9-й OPEN вешает систему; _fd_guard в libc —
+  memory/dss_fd_limit
+- SDCC z80 `if(n!=g)g=n;` пишет (n-g) — memory/sdcc_z80_cmp_store_a_bug
+
+---
+
+# История — закрытые этапы
+
+## Этап 10 — libc: сплит + FILE v2 + Solid-C (2026-07-05/06) ✅
+
+Полный план/итоги: docs/libc-roadmap.md.  Кратко:
+- вся libc разложена «1 функция = 1 модуль» (~250 модулей, wildcard-
+  сборка, DCE на уровне файлов): gfx_text −4.4 КБ, timedir/ls/stattest
+  −3 КБ и т.д.; правила asm-связок: docs/libc-split-asm-cases.md
+- **FILE* v2 (B+)**: ленивый буфер 512 на чтение/запись с
+  автопереключением, таблица OPEN_MAX=8, flush-on-exit, ungetc,
+  fprintf/vfprintf, fdopen/freopen/fclosall/fgetpos/fsetpos; горячие
+  пути fgetc/fputc/fgets на asm (fgets 100 КБ: 144с unbuffered-оценка
+  → ~1 с).  Дизайн: docs/file-buffering-design.md
+- **scanf/fscanf/sscanf** — своё C-ядро (в SDCC z80 нет)
+- **Solid-C совместимость закрыта**: <dos.h> (даты/диски/absread),
+  errno-алиасы, <sprinter_solid.h> — docs/solid_c_compatibility.md
+- гигиена: stale .rel чистка, все 43 теста в make all, размерный
+  регресс (make size-check), контракт заголовков docs/libc-headers.md
+- справочник API: docs/libc-reference.md
+
+## Этап 9 — memory modes (tiny/small/big/huge/manual) ✅ 2026-05-30
+
+`--memory MODE` в sprinter-cc; crt0-семейство (crt0/minimal/small/
+banked); small: ESTEX GETMEM+SETWIN2 до gsinit, auto-detect W2 по
+порту 0xC2; big/huge: параметризация crt0_banked/bank.s через
+BANK_W1; --debug, --stack-size.  Детали: memory/memory_modes_
+implemented, memory/sprinter_memory_modes.
+
+Дизайн-решения: одна sprinter.lib на все режимы (DCE per-member);
+gfx.lib отдельно не нужен; libc_banked + sprinter_home.lib — идея
+на потом (триггер: HOME забит user-кодом).
+
+## Этап 8 — графика ✅
+
+320×256×256 + 640×256×16, акселератор (Fill h/v, SMC block-size),
+Брезенхэм, bitmap font (WIN_GET_ZG, interleaved), gfx_text.
+memory/sprinter_graphics*, sprinter_accelerator, sprinter_font_format.
+
+## Bank-local data ✅
+
+--codeseg/--constseg/--dataseg BANKn + mkexe -p 0; фикс трамплина
+(pop bc/out (c),b — сохраняет A); malloc из банка прозрачен (heap в
+W2).  memory/bank_local_data_pattern.
+
+## Этапы 5-7 и ранняя libc ✅
+
+- malloc/free (SDCC + runtime/heap.s в W2), page allocator
+  (mem_alloc_pages, ESTEX $3C-$3E + BIOS $C4), bank_read/bank_write
+- crt0 argv-парсинг (IX-prefix, CP/M-space quirk, APPINFO basename),
+  sprinter-cc wrapper со всеми опциями
+- errno+strerror/perror, open state-machine, atexit, setjmp/longjmp,
+  sleep, ENV API ($46), ffirst/fnext, getdatetime/setdatetime,
+  chdir/getcwd/mkdir/rmdir, conio (полный), mouse (RST 30h, 14 ф-й),
+  POSIX time API, sys/stat, assert
+- text I/O split (stdio fast / conio attr) — memory/text_output_api_split
+- SDCC stdlib НЕ переписываем — memory/sdcc_stdlib_works

docs/libc-reference.md

@@ -0,0 +1,194 @@
+# libc — справочник API (2026-07-06)
+
+Сводка по заголовкам: сигнатура + одна строка + особенности ABI.
+Детали дизайна: docs/libc-headers.md (контракт затенения SDCC),
+docs/file-buffering-design.md (FILE*), docs/solid_c_compatibility.md.
+
+Общие соглашения:
+- ошибки: возврат -1/NULL/EOF + `errno` (код DSS as-is, см. errno.h);
+- SDCC `__sdcccall(1)`: 1-й аргумент HL (8-битный — A), 2-й — DE,
+  остальные на стеке; **int/указатель возвращается в DE**;
+- строки для BIOS-вызовов (rst 8) должны лежать в #4000–#BFFF;
+- стек при любых ESTEX/BIOS-вызовах — в W2 (обеспечено crt0).
+
+## <stdio.h> — полная замена SDCC (контракт: printf-семейство из z80.lib)
+
+Из SDCC z80.lib: `printf sprintf vprintf vsprintf`.
+
+Консоль (ESTEX, без атрибутов — быстрый путь; цветной вывод — conio):
+| Сигнатура | Описание |
+|---|---|
+| `int putchar(int c)` | символ через PUTCHAR $5B; '\n'→CR LF |
+| `int getchar(void)` | блокирующий WAITKEY $30, ASCII |
+| `char puts(const char *s)` | строка + '\n' (посимвольно через putchar) |
+| `char *gets(char *buf)` | строка с консоли, без контроля длины |
+| `void dec8/dec16/dec32(v)` | десятичная печать без ведущих нулей |
+| `void hex8/hex16/hex32(v)` | hex-печать фиксированной ширины |
+
+FILE* (буферизованный, вариант B+ — единый ленивый буфер BUFSIZ=512
+на чтение/запись с автопереключением; таблица `OPEN_MAX=8` слотов;
+exit() сбрасывает всё через atexit; **ошибки записи отложенные —
+проверять fclose**):
+| Сигнатура | Описание |
+|---|---|
+| `FILE *fopen(path, mode)` | "r/w/a" + '+', 'b/t' игнорируются |
+| `FILE *fdopen(fd, mode)` | завернуть готовый fd (закрывать fclose!) |
+| `FILE *freopen(path, mode, fp)` | переоткрыть тот же FILE* |
+| `int fclose(FILE*)` / `void fclosall(void)` | сброс+закрытие / все потоки |
+| `int fflush(FILE*)` | сброс записи / откат readahead; NULL = все |
+| `int fgetc/fputc(...)` | горячий путь на asm; getc/putc — макро-алиасы |
+| `char *fgets(buf, n, fp)` | до '\n' (сохраняется); блочный LDI-сканер |
+| `int fputs(s, fp)` | без '\n'; через fwrite |
+| `size_t fread/fwrite(p, sz, n, fp)` | блоки ≥ 512 идут мимо буфера |
+| `int ungetc(c, fp)` | 1 байт putback (и на stdin) |
+| `int fseek(fp, off, whence)` / `long ftell(fp)` | ftell без побочных эффектов |
+| `void rewind(fp)` | fseek(0) + сброс EOF/ERROR |
+| `int fgetpos/fsetpos(fp, &pos)` | fpos_t = long |
+| `int feof/ferror(fp)`, `void clearerr(fp)` | флаги потока |
+| `int fprintf/vfprintf(fp, fmt, ...)` | vsprintf в статический буфер 256 |
+| `int scanf/fscanf/sscanf(...)` | %d %u %x %o %c %s, `l`, ширина, %*, %% |
+| `int rename(old, new)` | ESTEX RENAME $10 |
+
+`stdin/stdout/stderr` — консольные псевдопотоки (fd 0/-1/-2), не
+буферизуются; freopen на них меняет только FILE*-операции (printf
+идёт в ESTEX напрямую).
+
+## <stdlib.h> — include_next + добавки
+
+Из SDCC: malloc/free/calloc/realloc (heap в W2), atoi/atol/strtol/
+strtoul, rand/srand, qsort/bsearch, abs/labs, div/ldiv, exit-типы.
+Наше: `int16_t min(a,b)`, `int16_t max(a,b)` (функции, как в Solid-C).
+
+## <string.h> — include_next + добавки
+
+Из SDCC: mem*/str* полностью. Наше: `char *strlwr/strupr(char *s)` —
+in-place регистр, латиница + кириллица CP866.
+
+## <time.h> — полная замена (struct tm в SDCC-ABI, __TIME_UNSIGNED=1)
+
+| Сигнатура | Описание |
+|---|---|
+| `void getdatetime(datetime_t*)` | RTC как есть (ESTEX SYSTIME $21) |
+| `int setdatetime(const datetime_t*)` | установка RTC ($22) |
+| `time_t time(time_t*)` | Unix-эпоха из RTC |
+| `mktime/gmtime/localtime/asctime/ctime` | POSIX поверх RTC (без TZ) |
+
+`datetime_t`: day/month/year(полный)/hour/minute/second/dow (1=Вс).
+
+## <unistd.h>, <fcntl.h> — fd-уровень (манипуляторы DSS)
+
+| Сигнатура | Описание |
+|---|---|
+| `int open(path, flags)` | O_RDONLY/WRONLY/RDWR + O_CREAT/TRUNC/EXCL/APPEND (ESTEX $11/$0A/$0B) |
+| `int creat(path, mode)` | open(W|CREAT|TRUNC); mode игнорируется |
+| `int read/write(fd, buf, n)` | ESTEX $13/$14. **Квирк WRITE: DE-возврат ненадёжен, успех = CF=0&A=0** (см. memory/estex_write_de_quirk) |
+| `int close(fd)` | ESTEX $12 |
+| `long lseek(fd, off, whence)` | 32-битная позиция (MOVE_FP $15) |
+| `int unlink(path)` | удалить (DELETE $0E) |
+| `int isatty(fd)` | fd <= 0 (файловые манипуляторы DSS с 1) |
+| `int mkdir/rmdir/chdir(path)` | ESTEX $1B/$1C/$1D |
+| `char *getcwd(buf, size)` | буфер 256 байт, size игнорируется |
+| `void sleep(seconds)` | 50 halt/с по кадровому IRQ |
+
+**Лимит: 8 одновременных манипуляторов**; 9-й OPEN вешает DSS —
+libc отказывает сама (EMFILE, предохранитель _fd_guard).
+
+## <errno.h>
+
+`errno` (int), коды = коды DSS (EOK..EUNKERR) + POSIX-имена
+(ENOENT/EBADF/EMFILE/…) + алиасы Solid-C (EZERO/EINVFNC/ENOFILE/…).
+`const char *strerror(int)`, `void perror(const char*)`.
+
+## <dos.h> — DOS-слой Solid-C
+
+| Сигнатура | Описание |
+|---|---|
+| `void getdate/gettime(&d)` | struct date/time (Turbo-C; ti_hund=0) |
+| `int setdate/settime(&d)` | RMW полного datetime |
+| `uint8_t getdisk(void)` | текущий диск, 0=A (ESTEX $02) |
+| `int setdisk(uint8_t)` | смена диска; возврат = число дисков ($01) |
+| `int absread/abswrite(disk, sect, cnt, buf)` | секторы ЛОГИЧЕСКОГО диска (BIOS $55/$56); буфер в #4000–#BFFF; abswrite минует ФС! |
+
+## <dir.h>
+
+`int ffirst(pattern, ffblk_t*, attrib)` / `int fnext(ffblk_t*)` —
+поиск по шаблону (ESTEX $19/$1A). Квирк: "."/".." находятся только
+итерацией "*.*" (memory/estex_ffirst_dotdot). FA_*-атрибуты.
+
+## <sys/stat.h>
+
+`int stat(path, struct stat*)` / `int fstat(fd, ...)` — st_mode
+(S_ISREG/S_ISDIR), st_size, st_mtime (Unix-эпоха).
+
+## <conio.h> — текстовый экран с атрибутами (Turbo-C стиль)
+
+Клавиатура: `kbhit getch getche getkey` (+KEY_* коды позиций),
+`char *cgets(buf)`.
+Вывод с атрибутом: `putch cputs cprintf` (~10× медленнее stdio-пути;
+'\n' НЕ транслируется — писать "\r\n").
+Атрибуты: `textcolor textbackground textattr`, `set/get_text_attr`,
+COLOR_*-enum, `COLOR(fg,bg)`, COLOR_BLINK; `set/get_putch_raw_mode`.
+Экран: `clrscr clrscr_attr gotoxy home() wherex wherey wherexy scroll
+wrchar rdchar`; режимы `gettextmode/settextmode` (0x02=40×32,
+0x03=80×32).
+Порты/IRQ: `inp outp enable() disable()`.
+Текстовая палитра: `text_pal_load/set_color/get/get_color/reset`
+(план 0..3 → страница BIOS 4..7).
+
+## <bios/text.h> — быстрый BIOS-вывод (rst 8, place-based)
+
+`bios_set_place/get_place`, `bios_write[attr][_until|_stop]`,
+`bios_fillchar/fillattr/fillcharattr`, `bios_clearwin[_ch]`,
+`bios_scrollwin`. Строка s — в #4000–#BFFF; place продвигается.
+
+## <gfx.h> — графика (0x81: 320×256×256; 0x82: 640×256×16)
+
+Setup: `gfx_init(mode,page)→prev`, `gfx_done(prev)`.
+Страницы/банк: `gfx_set/get_visible_page`, `gfx_set/get_draw_page`
+(double buffering), `gfx_set/get_bank` (0x50..0x5F, 0x58 = FF-
+прозрачность), `gfx_wait_vsync()`.
+Примитивы (суффикс _256 / _16): `clear putpixel hline vline line
+rect fill_rect` — через акселератор (hline/vline burst до 256 байт;
+в 0x82 vline через RMW). Координаты int, клиппинг по краям.
+Текст: `gfx_putchar256/16, gfx_text256/16` (8×8, fg/bg; в 0x82 x —
+чётный), `gfx_load_default_font`, `gfx_set_font(ptr)` (interleaved
+font[row*256+char]).
+Палитра: `gfx_pal_load/set/get/get_color/reset` (страницы 0..3).
+
+## <palette.h> — низкий уровень (BIOS $A4/$A6)
+
+`pal_load pal_get pal_set_color pal_get_color` (страница 0..7,
+записи B,G,R,0), `pal_reset(type)` / `pal_reset_at(type,page,graph)`;
+PAL_GRAPH/PAL_SINCLAIR/PAL_CGA.
+
+## <mouse.h> — драйвер RST 30h
+
+`mouse_init show hide refresh read(mouse_state_t*) goto bounds_x/y
+text_cursor load_cursor/get_cursor(mouse_cursor_t*) set_sensitivity
+get_sensitivity_x/y video_mode_changed`. Sensitivity = делитель
+(меньше = быстрее). Solid-C алиасы ms_* включены.
+
+## <sprinter.h> — платформа
+
+Константы портов (PORT_PAGE_W0..W3, PORT_RGADR, PORT_RGMOD), номера
+всех ESTEX-функций (ESTEX_*), BIOS EMM ($C0..$C7); `__sfr`-доступ и
+inline `sprinter_page_w0..w3(page)`; ENV: `getenv putenv sysenv`.
+
+## <sprinter_mem.h> — EMM-страницы и банковый I/O
+
+`mem_alloc_pages(n)→blk_id, mem_free_block, mem_get_page(blk,idx),
+mem_info(&total,&free)` (реализации _bios/_estex; макро-выбор
+MEM_MANAGE_MODE_*). HOME-резидентный доступ к чужим страницам:
+`bank_load_byte/store_byte/read/write` (своп W3 внутри; *_w1 —
+вариант через окно W1).
+
+## <sprinter_exit.h>
+
+`atexit` (LIFO, 8 слотов), `exit` (хендлеры+сброс FILE), `_exit`.
+
+## <sprinter_compat.h> / <sprinter_solid.h>
+
+Типы (BYTE/BOOL/WORD/uint/FD/f_point), TRUE/FALSE/OK/ERROR,
+`setmem movmem` (порядок аргументов!), `strerr seek tell ltell
+remove _ffirst _setargv abort()`, isascii. `<sprinter_solid.h>` —
+зонтичный: один include для портирования Solid-C программ.

docs/libc-roadmap.md

@@ -91,16 +91,14 @@ fgetpos/fsetpos (хвост П2).  bdos/brk/ioctl — отказ решение
       подтвердить на эмуляторе
 - [ ] Потом на железе (mdview2 и так ждёт проверки на железе — совместить)
 
-## П7. Документация
+## П7. Документация — ЗАКРЫТ 2026-07-06
 
-- [ ] docs/libc-reference.md — сводный справочник API (по заголовкам:
-      сигнатура + 1 строка описания + особенности ABI); сейчас знание
-      размазано по memory/ и комментариям
-- [ ] TODO.md: этапы 5/6/8 закрыты — перенести в history, добавить «этап 9 —
-      libc-оптимизация» (этот план)
-- [ ] В CLAUDE.md/README зафиксировать правила libc: 1 ф-я = 1 модуль,
-      internal `_`-модули, русские комментарии, без `= 0`, asm-правила
-      (docs/libc-split-asm-cases.md)
+- [x] **docs/libc-reference.md** — справочник API по всем заголовкам
+- [x] docs/TODO.md переписан: открытое наверху, закрытые этапы (5-10)
+      в «Истории»; протухшие пункты (FILE rewrite «для v2») сняты
+- [x] **CLAUDE.md** создан: сборка/проверка, правила libc (1 ф-я =
+      1 модуль, `_`-модули, русские комментарии, без `= 0`,
+      asm-правила), ABI-шпаргалка, квирки, структура
 
 ## П8. Смежное (не libc, из TODO.md — чтобы не потерялось)