Files
Quadrapassel/docs/MEMORY_LAYOUT.md
T

74 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CoCo 3 memory contract
Current candidate uses stock Disk BASIC and `PCLEAR1`, then
`LOADM"QUAD.BIN":EXEC`. `PCLEAR0` was tested in an isolated official build-48
MC6809/512 KB machine and returned `?FC ERROR`; it is not used.
The standard CMOC linker places code/constant data at $1400 and writable static
data at $0E00. The one reserved legacy PMODE page ($0E00–$13FF) is deliberately
used for the game's static variables. This is a CoCo 3-only program: it never
calls PMODE or PCLS. HSCREEN 2 uses its separate physical graphics banks $30–$33.
Graphics is initialized once before preferences are created. Scene changes clear
only the framebuffer through the approved renderer, keeping ROM initialization
outside live game state. No BASIC user program or prior
low-resolution picture is preserved by launching
this game. BASIC system RAM, text RAM and disk buffers below $0E00 remain intact.
The November 11 joystick update ends code/constants at $7AF6 and static data at
$13F6 (1,526 bytes including initialized variables). The limits remain unchanged.
The font uses 336 row bytes plus 12 punctuation codes; 198 bytes of font/packing
data are stored in the low data region and only read by the renderer. $7B00–$7FFF is kept free for
the foreground/ROM stack, with CMOC configured for 1,024 bytes. The split layout has passed settings and earned-score save/reload checks on
MC6809/512 KB in the official app. Full stack qualification and actual 128 KB
testing remain pending. This is a checked
address budget, not a claim that 128 KB has passed.
`tools/check_memory.pl` verifies every nonempty link-map section independently.
This is necessary because CMOC's `--limit` checks `program_end`, which is the low
static-data end when `--data` is used. The build fails if code/constants extend
past $7B00 or static data extends past $1400. No data or stack may occupy the
renderer’s temporary $8000–$9FFF MMU window.
The approved C renderer temporarily maps task-0 slot 4 to graphics banks $30–$33,
copies bounded chunks and restores the prior mapping before standard APIs run.
CMOC does not implement volatile: a separate read function is used and emitted
reads/stores must be audited in each delivered candidate. No authored assembly,
custom interrupt handler or custom sound driver is used.
Menu text is loaded through standard decbfile APIs from twelve independently
checksummed 512-byte pages in QPTEXT.DAT. The menu buffer shares storage with the
288-byte tile cache and 200-byte board cache; gameplay rebuilds those caches on
resume. Original title lettering uses 84 bytes of shape data and a scanline
scratch buffer, rather than a full-screen bitmap.
The score store keeps one 256-byte page and one 80-byte top-ten table in RAM.
QPSAVE0.DAT/QPSAVE1.DAT each hold 35 sectors, with the commit header written last.
Files longer than the schema allows are rejected and reported; the program does
not truncate an unexpectedly oversized file. Missing/short inactive files can be
created/extended using the documented file API. Only the two named save files
are written. QPTEXT.DAT is read-only game data.
Build 02 packs each caption's scene and column into one byte, preserving all
positions. The palette (11 bytes) and preference-validation table (15 bytes)
use low static data; they are only read. Optional video timing instrumentation
is enabled only by QUAD_PROFILE and is unavailable in Release. Every profile
build still needs the unchanged link guard; profile configurations are unqualified.
Build 03 additionally moves the seven effect-duration bytes into low static
storage (read only in use), iterates packed captions with a byte pointer, and
compacts equivalent input handling/status text. Code/const end $7ACD; static
end $13FD; reserved stack remains 1024 bytes. Full bcontrol position sampling
was tried but exceeded the guard; the delivered path retains standard coco.h
position reading with public interrupt protection.
Final build04's independent calibration/position pointers avoid the target
compiler indexing defect. Code/const end $7AD4 (44 bytes free), static end
$13FD (3 bytes free). The original MMU window, section limits and 1024-byte
stack reserve are unchanged. Memory qualification remains actual-128-KB pending.
Build05 maps Fire 2 into the existing hard-drop edge path: code/const end $7AFE
(2 bytes free), static end $13FD (3 bytes free), unchanged 1024-byte stack reserve.
Official build54 reproduces these exact bounds and passes MC6809/512 KB standard
right-port tests. Further code/data growth requires compaction first; 128 KB and
full stack qualification remain pending.