6.1KB

Brut Annotations Historique

story: E04-S05 owner: e04_runtime status: done started: 2026-11-09 depends-on: [E04-S03, E01-S04]

E04-S05 Claim

Intended change

Deliver the runtime half of print and runtime faults: PETSCII text and scalar output, stable R-codes, and a mailbox/screen fault report, with an x128 fixture that checks the rendered screen and the mailbox. The increment also proves one source-to-code path: hello.n8 compiles to a PRG through a pass-2 string capture and a fixture-only emitter, then runs in x128. General parser-to-codegen integration, sizing.s, and compiler pass 3 remain separate backend work.

File area

src/runtime/print.s, src/common/print.inc (new)
src/runtime/faults.s, src/common/faults.inc (new)
src/compiler/parser.s (pass-2 print capture)
tests/runtime/print-test.s (new)
tests/compiler/hello.n8, tests/compiler/hello-test.s (new)
scripts/build-print-test.ps1, scripts/verify-print-test.ps1 (new)
scripts/build-hello-test.ps1, scripts/verify-hello-test.ps1 (new)
docs/decisions.md, docs/architecture.md
planning/claims/E04-S05.md
generated files under build/print-test/ and build/hello-test/

Acceptance evidence

Prints literals and every supported scalar on tested displays: the fixture renders TEXT OK (string literal), BYTE 0 7 255, WORD 0 12345 65535, INT -1 -32768 32767, BOOL FALSE TRUE, and CHAR A in x128's VIC-II display; the host compares all twelve screen rows.
Null, bounds, divide, stack, and heap faults have stable codes: R001, R002, R003, R004, and R005 are printed as RUNTIME FAULT R00n, and the mailbox ends with code 5 and address $1234.
Runtime messages do not corrupt the program's memory mapping: the fixture compares CR to $0E and RCR to its saved value after all print and fault calls, and records 1 in MB_DATA only when both match.
hello.n8 compiles and runs end to end in x128: the compile fixture loads HELLO.N8 from a D81, parses it, captures the single string literal, and emits a 118-byte HELLO.PRG ($1C01 load, $1C0D entry). A second x128 session autostarts the extracted PRG and displays HELLO FROM NOVA128 on row 13. The emitter is fixture-only: it handles one print of one string literal and does not call out_startup or the general code generator.

Coordination notes

D132 records the output formats, the R-code namespace, and the direct CHROUT contract. It builds on D129 (generated code runs at CR $0E) and changes no memory map.
The runtime must not be called from a compiler state with relocated zero page: print.s calls the KERNAL without a wrapper and uses (pr_ptr),y.
Fault reporting returns to its caller. Unwinding a fault through frames is deferred to the frame/exception work.
E04-S03's AR_FAULT_DIV0 now has a stable external code (FLT_DIV0 = R003); arithmetic itself is unchanged.
The hello path uses the D128 container (stub at $1C01, body at $1C0D) but bypasses startup.s; it is a bounded proof, not the general emitter. The fixture must set out_load and out_entry before out_begin, because output.s does not initialize them.
HELLO.N8 is stored with unshifted PETSCII name bytes ($48...), so the build script writes the host file with a lowercase name; c1541 maps it to those bytes. The true-drive D81 must be allowed to settle before exit or the PRG's data sectors are not flushed to the image.

Work log

Added print.s: pr_char (preserves X/Y), pr_cr, pr_text, minimal-decimal pr_byte/pr_word/pr_int, and pr_bool.
Moved pr_ptr to the zero-page segment: indirect indexed addressing needs a zero-page operand, which ca65 rejected from BSS.
Added faults.s: mailbox code/address then MB_ST_FAIL, a fixed RUNTIME FAULT R prefix, three-digit code, and CR.
Added the fixture with a screen clear, all scalar formats, all five faults, and a CR/RCR preservation check.
Fixed the fixture's mapping constant to CR_RAM0_KERNAL (the c128.inc spelling) and checked that the linked image ends below $4000 in the build script.
Added D132 and architecture section 7.8.
Added pass-2 print capture to parser.s: gen_text/gen_text_len, gen_print_count, and gen_bad; a print accepts one string-literal item and marks unsupported shapes. Parser code growth required near-branch trampolines around the literal path for ca65's +/-128 range.
Added hello-test.s and its build/verify scripts. The compile fixture sets out_load/out_entry, emits the D128 stub and a body that saves CR, selects $0E, calls CHROUT per captured byte, restores CR, and returns to BASIC.
Added architecture section 7.9 and updated D132.

Completion

Tests run:
- scripts/verify-print-test.ps1 (build plus x128 run)
- scripts/verify-hello-test.ps1 (compile session, D81 extraction, x128 run)
- scripts/verify-parser-test.ps1 -Port 6551 (41 fixtures)
- git diff --check
Results: all twelve print/fault screen rows match; the print mailbox has producer 3, status FA, code 5, address $1234, and mapping preserved. The hello mailbox has stage 2, status A5, one 18-byte print, and no output error; HELLO.PRG is 118 bytes and displays on row 13. All 41 parser fixtures pass (lowest expression stack pointer $A7).
Files changed: src/runtime/print.s, src/common/print.inc, src/runtime/faults.s, src/common/faults.inc, src/compiler/parser.s, tests/runtime/print-test.s, tests/compiler/hello.n8, tests/compiler/hello-test.s, the four build/verify scripts, docs/decisions.md, docs/architecture.md, this claim.
Remaining risks: the hello emitter handles only one literal string print, with no expressions, calls, or startup section; general parser-to-codegen integration and compiler pass 3 remain open. Only the 40-column VIC-II display is tested. The capture buffer is bounded; longer or unsupported print shapes stop at the unsupported stage rather than truncating silently. Print/fault routines are not reentrant and assume the system zero page; fault unwinding and best-address selection are not implemented; generated code and BSS must stay below $4000 under CR $0E.

6.1KB Brut Annotations Historique