Sprinter-SDCC/RELEASE_NOTES.md

# Sprinter C Compiler — Release Notes

## v1.0  (2026-06-01)

First public release.  Production-ready toolchain for writing C programs that
target Sprinter / ESTEX DSS.  Built on top of vendored SDCC 4.5; this repository
adds everything Sprinter-specific.

### Highlights

* **One-line builds:** `sprinter-cc -o foo.exe foo.c` — pulls in crt0, libsprinter,
  packs the resulting .ihx into a SprintEXE.
* **27 working examples** covering every API surface — used as regression tests
  while the toolchain was developed.
* **Five memory modes** (`tiny / small / big / huge / manual`) handle programs
  from a few KB up to 32 KB of code + arbitrarily many 16 KB banks.
* **Full Sprinter API coverage**: console, files & directories, environment,
  date/time, mouse, graphics (both 320×256×256 and 640×256×16 modes including
  the hardware accelerator), bitmap-font text, banking, paging.

### Component versions

* SDCC: 4.5.0 (vendored binary)
* SprintEXE format: as documented in `docs/converted/ProgrammerManual.txt`
* MAME: 0.283 with `sprinter` driver (vendored at `mame/v306/mame.arm`)
* DSS / ESTEX: 1.71.57 (matches `mame/v306/IMG/dss171u.img`)

### What's included

Toolchain:
* `bin/sprinter-cc` — Bash driver
* `toolchain/mkexe/mkexe` — host C utility, packs `.ihx` → `.exe`
* `toolchain/check_banks.py` — post-link bank size enforcement

Runtime (`runtime/`):
* `crt0.s` — default startup for tiny / big modes, parses argv
* `crt0_minimal.s` — opt-out for very small programs (no argv)
* `crt0_small.s` — for small / huge modes, allocates W2 via ESTEX `$3A`
* `crt0_banked.s` — parameterised: handles W3 banks (huge) or W1 banks (big)
  via assemble-time `BANK_W1` flag
* `bank.s` — `___sdcc_bcall_ehl` trampoline (banking-aware,
  preserves uint8_t return value in A)
* `heap.s` + `heap_top.s` — 32 KB W2-resident heap, configurable upper bound
  via `sprinter-cc --stack-size`

Libraries (`libc/`):
* `libsprinter.lib` archives: io (open/read/lseek/close/unlink/stat/atexit/setjmp/
  errno/sleep/time/env/conio/fsdir/dir/mouse), stdio (putchar/puts/getchar/print_hex/
  file/cprintf/solid_helpers), mem (mem_alloc/bank_io), gfx (gfx_core/gfx_lines/
  gfx_16/gfx_text)

Headers (`libc/include/`):
* Standard: `stdio.h`, `unistd.h`, `fcntl.h`, `errno.h`, `time.h`, `sys/stat.h`
* Sprinter-specific: `conio.h`, `gfx.h`, `mouse.h`, `dir.h`, `sprinter.h`,
  `sprinter_exit.h`, `sprinter_mem.h`
* Compatibility: `sprinter_compat.h` — Solid-C aliases and types

Examples (27 in `examples/`):
* I/O: hello, argv, cat, seek, ls, filetest, stattest, errno
* Memory & banking: mem_test, malloc, banked, bankedbg, banklocl
* Mouse: mouse, gfx_mous
* Graphics: gfx_demo, gfx_d16, gfx_text
* Misc: timedir, ptime, openenv, conio, attrprob, strtest, stdlib, assrtest, rt_test

Documentation (`docs/`):
* `TODO.md` — roadmap, v2 plans
* `solid_c_compatibility.md` — Solid-C compatibility gap analysis
* `im2_isr_design.md` — interrupt design (v2)
* `converted/` — searchable plain-text copies of original Russian documentation

### Notable design decisions

* **DSS allocates pages by program size** — `< 16 KB` programs get only one
  16 KB page.  Memory modes encode the four possible layouts.
* **One libsprinter.lib for all modes** — SDCC's linker drops unused .rel members,
  so a `tiny` hello program only pulls in what it needs (~700 bytes overhead).
* **Banking trampoline ABI**: 1-byte saved page + 2-byte bjump return between
  the bcall ret and the callee's stack arguments.  `pop bc; out (c), b` on the
  way back preserves A (a previous version clobbered A and silently lost
  uint8_t return values).
* **Text I/O is Turbo-C-style split**: `puts/printf/putchar` (fast, via PCHARS)
  ignore text attribute; `cputs/cprintf/putch` apply `g_text_attr`.  Same
  convention as Borland C 2.x — programs port over with minimal changes.
* **Graphics accelerator**: the `LD D,D / LD C,C / LD E,E / LD B,B` instruction
  trick is wrapped in self-modifying-code primitives in `gfx_lines.c` (the block
  length byte must literally follow `LD A,#imm`; we patch it at runtime).
* **Mouse cursor format** (verified empirically): 1 byte per pixel, `0xFF =
  transparent`; the driver stores the bitmap in a dedicated video bank.
* **Video mode bitmaps**: BIOS font is **interleaved** — `byte[r*256 + c]`,
  not `byte[c*8 + r]` as the obvious reading suggests.

### Limitations / known issues

* **No interrupt handlers in v1** — scheduled for v2.  `examples/rt_test` uses
  busy-wait sleep via ESTEX `$30` instead.
* **MAME's mouse driver stubs `$0E GET_SENSITIVE`** — returns 0 instead of the
  current value.  Workaround: always call `mouse_set_sensitivity(h, v)` with
  known values at startup; don't trust `mouse_get_sensitivity_*()` reads.
* **MAME's mouse driver `$0B RETURN_CURSOR`** — writes the bitmap to the IX
  buffer but does not update the H/L/D/E result registers, so
  `mouse_get_cursor()` returns width/height/hot_x/hot_y as 0.
* **Several Solid-C functions not yet ported** — see
  `docs/solid_c_compatibility.md` for the categorised list.
* **No fprintf / scanf family** — workaround: `sprintf(buf, ...) + fputs(buf, fp)`.
* **No double-buffering wrapper** — Sprinter hardware supports it (port `0xC9`),
  the user-facing wrapper is part of the v2 BGI-style API.

### Migration notes from pre-1.0 trees

If you were tracking the project during development:
* All example directories were renamed to satisfy 8.3 filenames on the floppy:
  `banked_big → bankedbg`, `seek_demo → seek`, `malloc_test → malloc`,
  `time_dir_test → timedir`, `bank_local_data → banklocl`,
  `gfx_demo16 → gfx_d16`, `gfx_text_demo → gfx_text`,
  `gfx_mouse_test → gfx_mous`, etc.
* `puts` / `putchar` no longer apply `g_text_attr` (switched to fast PCHARS).
  Programs that depended on coloured stdio must use `cputs` / `cprintf` /
  `putch` instead, or call `textattr(...)` followed by clrscr.
* `runtime/bank.s` is no longer bundled in `sprinter.lib` — it's assembled
  per-build by `sprinter-cc` with the right `BANK_W1` flag for the chosen
  memory mode.

### Acknowledgements

* **Peters Plus** team (Иван Мак, Дмитрий Паринов) for designing Sprinter and
  publishing the architecture / BIOS / DSS documentation that made this
  toolchain possible.
* **Dmitry M.** for the z88dk `+pps` Sprinter target — first proof-of-concept
  for cross-compiling C to SprintEXE; several conventions were borrowed.
* **The SDCC team** for the Z80 backend that does the heavy lifting.
* **The MAME team** for emulating the Sprinter Sp2000 well enough for
  full toolchain regression testing without hardware.

---

## v2.0 (planned)

Scope:
1. IM2 interrupt handlers (`irq_install` / `irq_remove`) — design in
   `docs/im2_isr_design.md`
2. Turbo-C-style BGI graphics API (`initgraph` / `setcolor` / `circle` /
   `getimage` / `putimage` / `setviewport` / `setlinestyle` / ...)
3. Audio API (AY-3-8910 + COVOX, requires IM2)
4. ISA-8 slot drivers (sound, network — requires IM2)
5. Remaining Solid-C compatibility (Phase 2/3 in `docs/solid_c_compatibility.md`):
   `ungetc`, `getdate/gettime/setdate/settime`, `absread/abswrite`,
   `scanf` family, `fdopen` / `freopen` / `fclosall`