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>
This commit is contained in:
@@ -0,0 +1,68 @@
|
|||||||
|
# Sprinter C-Compiler — правила проекта
|
||||||
|
|
||||||
|
Target-слой SDCC 4.5 (z80) для компьютера Sprinter Sp2000: crt0,
|
||||||
|
линковка, libc, mkexe. Общение и комментарии — на русском.
|
||||||
|
|
||||||
|
## Сборка и проверка
|
||||||
|
|
||||||
|
```
|
||||||
|
make # tools + lib + все тесты (43) + examples
|
||||||
|
make -C lib # только libc → lib/sprinter.lib
|
||||||
|
make floppy # упаковать все .exe в mame/v306/IMG/mc.img
|
||||||
|
make size-check # размерный регресс: _CODE vs docs/size_baseline.tsv
|
||||||
|
make size-baseline # принять текущие размеры эталоном
|
||||||
|
```
|
||||||
|
|
||||||
|
Одиночный тест: `cd tests/<имя> && make run` (пакует ТОЛЬКО этот exe
|
||||||
|
+ EXTRA_DATA на дискету и запускает MAME). Тесты в MAME гоняет
|
||||||
|
пользователь — готовь дискету и проси прогнать.
|
||||||
|
|
||||||
|
После правок libc: пересборка от чистого листа (`make -C lib clean`)
|
||||||
|
не обязательна — stale .rel чистятся автоматически; `make size-check`
|
||||||
|
обязателен (рост _CODE без причины — регрессия).
|
||||||
|
|
||||||
|
## Правила libc
|
||||||
|
|
||||||
|
- **1 публичная функция = 1 .c-модуль** (линкер тянет .rel целиком —
|
||||||
|
гранулярность файлов = гранулярность DCE). Никакой группировки
|
||||||
|
«используются вместе». Internal-хелперы — тоже по одному на модуль
|
||||||
|
(`_`-префикс); общие статики — в отдельные data-модули
|
||||||
|
(`_xxx_state.c`); internal-заголовки (`_file.h`, `_gfx.h`, …) —
|
||||||
|
рядом с исходниками, НЕ в libc/include.
|
||||||
|
- Имя файла = имя функции. lib/Makefile собирает wildcard'ом —
|
||||||
|
ничего регистрировать не надо.
|
||||||
|
- Комментарии — на русском; шапка модуля объясняет что/зачем + ABI.
|
||||||
|
- File-scope переменные НЕ инициализировать `= 0` (crt0 зануляет
|
||||||
|
_DATA; см. memory/sdcc_static_storage_gotcha).
|
||||||
|
- asm-связки между модулями: `call/jp _global` — ок; `jr/djnz` через
|
||||||
|
границу и fall-through — НЕЛЬЗЯ (docs/libc-split-asm-cases.md).
|
||||||
|
- Заголовки: сначала пробовать include_next-паттерн; полная замена
|
||||||
|
SDCC-заголовка обязана дублировать его контракт
|
||||||
|
(docs/libc-headers.md).
|
||||||
|
- Справочник API — docs/libc-reference.md (обновлять при добавлении
|
||||||
|
функций).
|
||||||
|
|
||||||
|
## ABI и платформа (кратко; детали в memory/)
|
||||||
|
|
||||||
|
- SDCC `__sdcccall(1)`: arg1 → HL (8-бит → A), arg2 → DE, остальные
|
||||||
|
на стеке (callee-pops в __naked); **возврат int/ptr в DE**, uint8 в A.
|
||||||
|
IX callee-saved (в __naked с IX — push/pop обязательны).
|
||||||
|
- ESTEX (rst #0x10): CF=1 — ошибка, код в A → `call __errno_set`;
|
||||||
|
все регистры клобберятся (IX сохранять); стек обязан быть в W2.
|
||||||
|
- BIOS (rst #0x08): строки/буферы в #4000-#BFFF.
|
||||||
|
- Квирки: ESTEX WRITE возвращает DE=0 на успехе (судить по CF/A);
|
||||||
|
лимит 8 файловых манипуляторов, 9-й OPEN ВЕШАЕТ DSS (_fd_guard);
|
||||||
|
ENV $46: A=0 = NOT FOUND.
|
||||||
|
- Перед обвинением компилятора/железа — подтвердить артефактом
|
||||||
|
(сгенерированный .asm в lib/build/, дамп, репро) — см.
|
||||||
|
memory/defer_unexplained_quirks.
|
||||||
|
|
||||||
|
## Структура
|
||||||
|
|
||||||
|
- `libc/<area>/*.c` — модули libc; `libc/include/` — публичные заголовки
|
||||||
|
- `runtime/` — crt0-семейство, heap, bank (bank.s собирается per-build)
|
||||||
|
- `bin/sprinter-cc` — обёртка компилятора; `toolchain/mkexe` — упаковщик
|
||||||
|
- `tests/` — по одному API/фиче; `examples/` — реальные приложения
|
||||||
|
- `docs/` — дизайн-доки; `docs/TODO.md` — roadmap
|
||||||
|
- `third_party/solid-c/` — нативный Sprinter C (референс, CP866;
|
||||||
|
их ABI несовместим — только как образец)
|
||||||
+150
-433
@@ -1,436 +1,153 @@
|
|||||||
# TODO / Roadmap
|
# 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)
|
- [ ] **П6/железо**: MAME-смоук всех тестов после libc-сплита (conio,
|
||||||
- [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`
|
ptime, stattest, mouse, gfx_demo/gfx_d16/gfx_text/gfx_mous —
|
||||||
- [x] `libc/mem/bank_io.c` — HOME-резидентные `bank_read`/`bank_write`/`bank_load_byte`/`bank_store_byte` со свопом W3 внутри
|
трогался asm акселератора); затем прогон на реальном Sprinter
|
||||||
- [x] `examples/malloc_test/` — проверка SDCC's malloc (~210 64-байтных allocations через всю heap)
|
(mdview2 + FILE* v2 + fdmax — подтвердить лимит 8 манипуляторов
|
||||||
- [x] `examples/mem_test/` — проверка page allocator: 3 страницы, разные паттерны через bank_write, верификация через bank_read
|
и зависание DSS на 9-м OPEN)
|
||||||
|
- [ ] Мигрировать оставшиеся examples на sprinter-cc вместо ручных
|
||||||
## Этап 6 — argv parsing + sprinter-cc wrapper ✅ ГОТОВО
|
Makefile (косметика)
|
||||||
|
- [ ] check_banks.py: разбивка size = code + const + bss per bank
|
||||||
- [x] crt0 парсит ESTEX command-line из IX-prefix (inline asm в `runtime/crt0.s`)
|
|
||||||
- [x] Strip leading CP/M-style space (DSS quirk)
|
## Auto-banking (memory/banking_roadmap.md)
|
||||||
- [x] Передача `argc`/`argv` в main() через HL/DE (SDCC __sdcccall(1) ABI)
|
|
||||||
- [x] argv[0] = basename .EXE через ESTEX APPINFO ($47 subfn 2)
|
Phase 1 — file-level bin-packing (`toolchain/auto_bank.py`) — когда
|
||||||
- [x] `runtime/crt0_minimal.s` — opt-out для очень маленьких программ
|
проект перерастёт ~30 KB кода: парсинг размеров из .rel/.map,
|
||||||
- [x] `runtime/crt0_banked.s` — теперь тоже парсит argv (parse_argv + get_progname скопированы из crt0.s; будет factored в argv.s когда возьмёмся за libsprinter.lib)
|
first-fit-decreasing, уважение `#pragma codeseg BANKn`, перелинковка,
|
||||||
- [x] Bash-обёртка `bin/sprinter-cc`: `sprinter-cc -o foo.exe foo.c` одной строкой
|
печать плана. Phase 2-5 (rebalance, banks.toml, function-level) —
|
||||||
- [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) ✅ ГОТОВО
|
## ОБЯЗАТЕЛЬНОЕ ДЛЯ V2
|
||||||
|
|
||||||
- [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.
|
### Turbo-C-style graphics API (BGI-like)
|
||||||
- [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 горизонтальных пикселя).
|
Расширить `gfx_*` до уровня Turbo-C `<graphics.h>`: initgraph/
|
||||||
- [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.
|
closegraph/cleardevice-алиасы, current point (moveto/lineto/linerel),
|
||||||
|
setcolor/setbkcolor, getpixel, circle/arc/ellipse/pieslice, drawpoly/
|
||||||
См. memory/sprinter_graphics.md, sprinter_accelerator.md, sprinter_graphics_16.md, sprinter_font_format.md.
|
fillpoly, floodfill, bar/bar3d, outtext[xy]/settextstyle/textwidth,
|
||||||
|
imagesize/getimage/putimage (COPY/XOR/AND/OR/NOT_PUT), setviewport/
|
||||||
Открытые мелочи (не блокируют):
|
клиппинг, setactivepage/setvisualpage (2 страницы есть), setlinestyle.
|
||||||
- [ ] Шрифт-quad для 640: per-cell палитра (mode 0x82 разрешает 1 из 4 палитр per 16×8 cell) — через прямой доступ к area-описания экрана 0x0300..0x039F
|
Acceptance: типичная BGI-программа переносится без существенных
|
||||||
|
правок. Референс: Turbo C 2.x BGIDEMO.
|
||||||
## Auto-banking (см. `memory/banking_roadmap.md` для деталей)
|
|
||||||
|
### IM2 Interrupt Handlers
|
||||||
Phase 1 — file-level bin-packing — реализовывать когда проект перерастёт ~30 KB кода.
|
|
||||||
|
User-ISR через IM 2 — timer ticks, музыка (AY/COVOX), real-time
|
||||||
- [ ] `toolchain/auto_bank.py`:
|
игры, async input. Решение: отдельный memory mode `--memory im2`.
|
||||||
- Парсит размеры из `.rel`-файлов (или из .map после dry-run link'а)
|
Полный research/design: docs/im2_isr_design.md (vector 0xFF общий,
|
||||||
- First-fit-decreasing bin-packing
|
disambiguation по портам 0x19/0xFE; таблица/ISR/стек в W2; chain к
|
||||||
- Уважает `#pragma codeseg BANKn` как manual override
|
DSS-хендлеру обязателен).
|
||||||
- Перелинковывает с новыми `-Wl-b_BANKn=...` параметрами
|
|
||||||
- Печатает план распределения
|
### Прочее v2
|
||||||
|
|
||||||
Phase 2-5: incremental rebalance, declarative `banks.toml`, function-level, call-graph-aware. Только если/когда понадобится.
|
- [ ] **Audio API** — AY-3-8910 + COVOX (требует IM2)
|
||||||
|
- [ ] **ISA-8 slot support** — ZX-Bus карты (требует IM2)
|
||||||
## Bank-local static data (mutable data в том же банке что и код) — ✅ ГОТОВО
|
|
||||||
|
## GFX: расширения по accelerator_doc.txt
|
||||||
- [x] Пример `examples/bank_local_data/` — функция в BANK1 со своим writable BSS array + const table + malloc-тест
|
|
||||||
- [x] `mkexe -p 0` для нулевого padding банков (BSS-storage обнуляется при загрузке)
|
Quick wins:
|
||||||
- [x] Канонический рецепт: `--codeseg BANK1 --constseg BANK1 --dataseg BANK1` для bank1.c + `-Wl-b_BANK1=0x1C000` для линковки. **`--dataseg BANK1` РАБОТАЕТ** — раньше казалось обратное из-за trampoline bug который маскировал результат.
|
- [ ] block-size через `LD A,(nn)` вместо SMC (док разрешает LD A,(HL/BC/DE))
|
||||||
- [x] **Критичный фикс trampoline'a в runtime/bank.s** — старый `pop af; out (n), a` клобберил A → все banked-функции возвращающие uint8_t тихо возвращали мусор. Новый `pop bc; out (c), b` сохраняет A.
|
- [ ] кэширование block-size между burst'ами (accel помнит размер)
|
||||||
- [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)
|
- [ ] `gfx_blit` / `gfx_blit_transparent` — block copy (LD L,L / LD A,A),
|
||||||
|
прозрачность через bank 0x58 («FF is transparent»)
|
||||||
Зачем: для модулей с большим private state (level loader, audio engine, scene data). Экономит W2 heap для динамики, а статика остаётся в бэке.
|
- [ ] `gfx_xor_rect` / `gfx_or_rect` / `gfx_and_rect` / `gfx_invert_rect`
|
||||||
|
- [ ] шрифты ≠ 8×8: gfx_set_font_data(ptr,w,h,advance), proportional,
|
||||||
## Подсказки из solid-c (нативный Sprinter C — `third_party/solid-c/`)
|
8×16/16×16, отдельный font_id API; font-quad для 640×256
|
||||||
|
(per-cell палитра через дескрипторы 0x0300..0x039F)
|
||||||
После анализа solid-c'овской libc (см. `memory/solid_c_findings.md`) выявлены готовые паттерны для следующих недостающих функций. Приоритет от **высокого** к низкому:
|
|
||||||
|
Оптимизации (не сейчас):
|
||||||
### High-priority gaps (легко портировать, большая польза)
|
- [ ] gfx_line через accel для пологих диагоналей (runs ≥ 4-5 px)
|
||||||
- [x] **`errno` + `strerror`/`perror`** — табличка 32 ошибок (libc/io/errno.c)
|
- [ ] композитные примитивы с одним W3-swap на операцию
|
||||||
- [x] **Расширенный `open()`** для O_CREAT/O_TRUNC/O_APPEND/O_EXCL state machine
|
|
||||||
- [x] **`atexit`** — 8-callback LIFO + `exit()` + `_exit()` (libc/io/atexit.c)
|
## Прочий backlog
|
||||||
- [x] **`setjmp`/`longjmp`** — 6-байт jmp_buf={sp,ix,pc} (libc/io/setjmp.c)
|
|
||||||
- [x] **`sleep(seconds)`** — 50Hz halt-loop (libc/io/sleep.c)
|
- [ ] factoring parse_argv из crt0/crt0_banked в общий argv.s
|
||||||
- [x] **ESTEX ENV API** ($46, getenv/putenv) — libc/io/env.c. Учли doc-bug: реально A=0 это NOT FOUND
|
- [ ] `restore SP on EXIT` (паттерн z88dk +pps) — проверить нужность
|
||||||
|
- [ ] CI: MAME с -aviwrite для screenshot-сравнения без человека
|
||||||
### Medium-priority (нужно для shell-like утилит)
|
- [ ] linker duplicate-symbol warnings: сейчас фильтруются в
|
||||||
- [ ] **Mouse driver** — `rst $30h`, 17 функций. **Сначала тест что работает в MAME**.
|
sprinter-cc (наши overrides _puts/___sdcc_heap/_asctime/…);
|
||||||
- [x] **`ffirst`/`fnext` + ffblk_t struct** для directory listing — реализовано, demo: ls.exe
|
радикально — --nostdlib с ручным списком модулей z80.lib
|
||||||
- [x] **`getdatetime`/`setdatetime`** через ESTEX $21/$22 — libc/io/time.c, demo: time_dir_test
|
- [ ] ZX Spectrum-совместимый target; ZX-Bus драйверы; PGO-tools
|
||||||
- [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
|
|
||||||
|
- [ ] **Port_Y banking trick** (адреса 0xC000+0x400*N → строки
|
||||||
### Low-priority — ✅ FILE* stack ГОТОВО
|
Y..Y+15): в MAME 0.283 НЕ работает (2026-06-01). На железе:
|
||||||
|
dual-write тест → если работает, кэшировать Port_Y в putpixel
|
||||||
- [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`.
|
(~8× меньше OUT для Брезенхэма); если нет — вычистить из доков.
|
||||||
- [ ] fprintf / fscanf — нужна printf-через-callback machinery. Пока пользователь может `sprintf(buf, ...) + fputs(buf, fp)`.
|
- [ ] fdmax: лимит манипуляторов и зависание 9-го OPEN — MAME vs железо.
|
||||||
- [ ] Опциональный buffered mode (setvbuf, line/block buffering) — если когда-то понадобится.
|
|
||||||
|
## Known quirks (зафиксированы, обходы в libc)
|
||||||
### POSIX time API — ✅ ГОТОВО
|
|
||||||
- [x] `libc/io/posix_time.c` — time/localtime/gmtime/mktime/asctime/ctime поверх getdatetime. SDCC's time.rel избегаем (нельзя override _RtcRead). См. `examples/ptime`.
|
- ESTEX $46 ENV: A=0 это NOT FOUND (док врёт) — memory/sprinter_platform
|
||||||
|
- ESTEX WRITE $14: на успехе DE=0, не счётчик; успех = CF=0 & A=0 —
|
||||||
### sys/stat — ✅ ГОТОВО
|
memory/estex_write_de_quirk
|
||||||
- [x] `libc/io/stat.c` — POSIX stat/fstat. Гибрид open+fstat для файлов, ffirst+iter для папок (включая "."/".."). См. `examples/stattest` и `memory/estex_ffirst_dotdot.md`.
|
- DSS: 8 манипуляторов, 9-й OPEN вешает систему; _fd_guard в libc —
|
||||||
|
memory/dss_fd_limit
|
||||||
### assert — ✅ ГОТОВО (используем SDCC's __assert через fallback include path)
|
- SDCC z80 `if(n!=g)g=n;` пишет (n-g) — memory/sdcc_z80_cmp_store_a_bug
|
||||||
|
|
||||||
## 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.)
|
## Этап 10 — libc: сплит + FILE v2 + Solid-C (2026-07-05/06) ✅
|
||||||
- `<ctype.h>` (toupper/tolower)
|
|
||||||
- `<math.h>` (sinf/cosf/sqrtf/etc.)
|
Полный план/итоги: docs/libc-roadmap.md. Кратко:
|
||||||
|
- вся libc разложена «1 функция = 1 модуль» (~250 модулей, wildcard-
|
||||||
Линкер автоматически тянет из z80.lib когда нужно. **НЕ переписывать**.
|
сборка, DCE на уровне файлов): gfx_text −4.4 КБ, timedir/ls/stattest
|
||||||
|
−3 КБ и т.д.; правила asm-связок: docs/libc-split-asm-cases.md
|
||||||
Наши Sprinter-specific обязательные модули остаются: atexit, env, errno, setjmp, putchar/puts/getchar, conio, fsdir, time, mouse, open/read/lseek/close.
|
- **FILE* v2 (B+)**: ленивый буфер 512 на чтение/запись с
|
||||||
|
автопереключением, таблица OPEN_MAX=8, flush-on-exit, ungetc,
|
||||||
## Build-system: libsprinter.lib + sprinter-cc — ✅ ГОТОВО
|
fprintf/vfprintf, fdopen/freopen/fclosall/fgetpos/fsetpos; горячие
|
||||||
|
пути fgetc/fputc/fgets на asm (fgets 100 КБ: 144с unbuffered-оценка
|
||||||
- [x] `lib/Makefile` — собирает каждый libc/*.c в `.rel`, архивирует через sdar в `lib/sprinter.lib`
|
→ ~1 с). Дизайн: docs/file-buffering-design.md
|
||||||
- [x] Включает runtime/bank.s и runtime/heap.s (auto-pulled при __banked/malloc)
|
- **scanf/fscanf/sscanf** — своё C-ядро (в SDCC z80 нет)
|
||||||
- [x] `bin/sprinter-cc` — bash-wrapper: `sprinter-cc -o foo.exe foo.c` одной строкой
|
- **Solid-C совместимость закрыта**: <dos.h> (даты/диски/absread),
|
||||||
- [x] Поддержка опций `--crt0=default|minimal|banked`, `--bank N=FILE.c`, `-I`, `-L`/`-E`/`-S`, `-Wl`, `--mkexe`
|
errno-алиасы, <sprinter_solid.h> — docs/solid_c_compatibility.md
|
||||||
- [x] `examples/hello_sccc/` — демо: `hello.c` собирается за один shell-вызов, размер совпадает с ручным Makefile (925 байт)
|
- гигиена: stale .rel чистка, все 43 теста в make all, размерный
|
||||||
- [x] Split `putchar.c` → `putchar.c` + `puts.c` для per-function granularity (puts override SDCC's z80.lib version)
|
регресс (make size-check), контракт заголовков docs/libc-headers.md
|
||||||
- [x] Включён в `make all` (зависимость `lib` перед `examples`)
|
- справочник API: docs/libc-reference.md
|
||||||
|
|
||||||
Возможные улучшения (опционально):
|
## Этап 9 — memory modes (tiny/small/big/huge/manual) ✅ 2026-05-30
|
||||||
- [ ] Мигрировать остальные examples на sprinter-cc вместо ручных Makefile (косметика)
|
|
||||||
- [ ] Дальнейшая декомпозиция libc/*.c per-function (но текущая granularity уже даёт нужный размер — линкер пакетует .rel целиком, и для большинства файлов это одна функция)
|
`--memory MODE` в sprinter-cc; crt0-семейство (crt0/minimal/small/
|
||||||
|
banked); small: ESTEX GETMEM+SETWIN2 до gsinit, auto-detect W2 по
|
||||||
## Этап 9 — memory modes для sprinter-cc
|
порту 0xC2; big/huge: параметризация crt0_banked/bank.s через
|
||||||
|
BANK_W1; --debug, --stack-size. Детали: memory/memory_modes_
|
||||||
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).
|
implemented, memory/sprinter_memory_modes.
|
||||||
|
|
||||||
- [x] **`tiny`**: всё (CODE+DATA+стек) в W2. Default. Verified hello/argv/conio/malloc/file/etc.
|
Дизайн-решения: одна sprinter.lib на все режимы (DCE per-member);
|
||||||
- [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.
|
gfx.lib отдельно не нужен; libc_banked + sprinter_home.lib — идея
|
||||||
- [x] **`--memory-manual SPEC`**: парсит `CODE=W1|W2,DATA=W1|W2|SAME,BANKED=W1|W3`. Реализовано 2026-05-30.
|
на потом (триггер: HOME забит user-кодом).
|
||||||
- [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.
|
## Этап 8 — графика ✅
|
||||||
- [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.
|
320×256×256 + 640×256×16, акселератор (Fill h/v, SMC block-size),
|
||||||
- [x] **`--debug` флаг**: prepend `DEBUG_RT = 1` в crt0 + `-DDEBUG_RT` в sdcc. Открывает symbol `_w2_self_allocated` (uint8_t) — runtime diagnostic кто аллоцировал W2. Реализовано 2026-05-30.
|
Брезенхэм, bitmap font (WIN_GET_ZG, interleaved), gfx_text.
|
||||||
|
memory/sprinter_graphics*, sprinter_accelerator, sprinter_font_format.
|
||||||
### Дизайн-решения по libc и crt0
|
|
||||||
|
## Bank-local data ✅
|
||||||
**Одна `sprinter.lib`** работает для всех memory mode — `.rel`-члены relocatable, SDLD делает dead-code elimination per-member (без графики не подтягивает `gfx_core.rel` и т.д.). Verified hello vs malloc_test через map-файлы.
|
|
||||||
|
--codeseg/--constseg/--dataseg BANKn + mkexe -p 0; фикс трамплина
|
||||||
**`gfx.lib` отдельно — НЕ нужен**: dead-code elimination уже работает.
|
(pop bc/out (c),b — сохраняет A); malloc из банка прозрачен (heap в
|
||||||
|
W2). memory/bank_local_data_pattern.
|
||||||
**`libc_banked` (libc в bank вместо HOME)** — идея на потом, когда HOME (16 KB) забит user-кодом + libc в `huge` mode. Реализуется через `--codeseg BANK0` при компиляции libc; trade-off: trampoline ~30 циклов на каждый libc-вызов. Триггер: реальная программа упрётся в HOME budget.
|
|
||||||
|
## Этапы 5-7 и ранняя libc ✅
|
||||||
**HW-зависимые модули — `sprinter_home.lib` отдельно.** Часть libc физически не может быть забанкована в W3, потому что она РАБОТАЕТ с W3:
|
|
||||||
- `gfx_*` — пишет в видеопамять `0xC000+` после swap W3 на video page
|
- malloc/free (SDCC + runtime/heap.s в W2), page allocator
|
||||||
- `bank_io` (mem_alloc_pages/bank_read/bank_write) — swap'ит W3 через `OUT (0xE2)`
|
(mem_alloc_pages, ESTEX $3C-$3E + BIOS $C4), bank_read/bank_write
|
||||||
- Будущие ISR — прерывание может прийти когда W3 на чём угодно
|
- crt0 argv-парсинг (IX-prefix, CP/M-space quirk, APPINFO basename),
|
||||||
|
sprinter-cc wrapper со всеми опциями
|
||||||
В huge mode эти модули ДОЛЖНЫ остаться в HOME (W1). Когда будем делать `libc_banked`, **одновременно** выделяем `sprinter_home.lib` (HOME-only) из `sprinter.lib` (bankable). Финальная схема:
|
- errno+strerror/perror, open state-machine, atexit, setjmp/longjmp,
|
||||||
```
|
sleep, ENV API ($46), ffirst/fnext, getdatetime/setdatetime,
|
||||||
sprinter_home.lib HOME-only: gfx, bank_io, ISR shims
|
chdir/getcwd/mkdir/rmdir, conio (полный), mouse (RST 30h, 14 ф-й),
|
||||||
sprinter.lib bankable: printf, malloc, string, conio, stdio, env, ...
|
POSIX time API, sys/stat, assert
|
||||||
sprinter_banked.lib тот же sprinter.lib но --codeseg BANK0 (для huge)
|
- text I/O split (stdio fast / conio attr) — memory/text_output_api_split
|
||||||
```
|
- SDCC stdlib НЕ переписываем — memory/sdcc_stdlib_works
|
||||||
Триггер: реализация `--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 × количество строк/столбцов экономии. Применимо ко всем композитным примитивам.
|
|
||||||
|
|||||||
@@ -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 программ.
|
||||||
@@ -91,16 +91,14 @@ fgetpos/fsetpos (хвост П2). bdos/brk/ioctl — отказ решение
|
|||||||
подтвердить на эмуляторе
|
подтвердить на эмуляторе
|
||||||
- [ ] Потом на железе (mdview2 и так ждёт проверки на железе — совместить)
|
- [ ] Потом на железе (mdview2 и так ждёт проверки на железе — совместить)
|
||||||
|
|
||||||
## П7. Документация
|
## П7. Документация — ЗАКРЫТ 2026-07-06
|
||||||
|
|
||||||
- [ ] docs/libc-reference.md — сводный справочник API (по заголовкам:
|
- [x] **docs/libc-reference.md** — справочник API по всем заголовкам
|
||||||
сигнатура + 1 строка описания + особенности ABI); сейчас знание
|
- [x] docs/TODO.md переписан: открытое наверху, закрытые этапы (5-10)
|
||||||
размазано по memory/ и комментариям
|
в «Истории»; протухшие пункты (FILE rewrite «для v2») сняты
|
||||||
- [ ] TODO.md: этапы 5/6/8 закрыты — перенести в history, добавить «этап 9 —
|
- [x] **CLAUDE.md** создан: сборка/проверка, правила libc (1 ф-я =
|
||||||
libc-оптимизация» (этот план)
|
1 модуль, `_`-модули, русские комментарии, без `= 0`,
|
||||||
- [ ] В CLAUDE.md/README зафиксировать правила libc: 1 ф-я = 1 модуль,
|
asm-правила), ABI-шпаргалка, квирки, структура
|
||||||
internal `_`-модули, русские комментарии, без `= 0`, asm-правила
|
|
||||||
(docs/libc-split-asm-cases.md)
|
|
||||||
|
|
||||||
## П8. Смежное (не libc, из TODO.md — чтобы не потерялось)
|
## П8. Смежное (не libc, из TODO.md — чтобы не потерялось)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user