Files
VCCPlusOSS/tools/toolchain/patches/README.md
T

105 lines
7.9 KiB
Markdown

# Local CMOC compiler patches
`cmoc-debug-metadata.patch` is an original VCC Plus extension to CMOC 0.1.100,
modified November 3, 2026 and licensed GPL-3.0-or-later. It is applied to the ignored build copy by
`tools/toolchain/build.py`; the pinned upstream snapshot and its checksums stay
unchanged.
With `-fno-omit-frame-pointer`, the compiler writes `* VCCDBG1 {…}` JSON comments
into retained assembly/listings. Metadata comes from resolved compiler types and
declarations, not a C-source text parser. It contains:
- function entry, frame-ready body and epilogue boundaries;
- lexical block ranges, including `for`-statement scopes;
- signedness, storage size, array dimensions, member offsets and pointer types;
- explicit `floatingFormat` tags: `coco-basic-40` for Color BASIC/native 5-byte floats and `ieee754-binary32-be` for MC6839 single precision;
- linker symbols for globals/static locals and U-relative offsets for parameters
and ordinary locals.
The boundaries are zero-byte assembler labels. They can inhibit some assembly
optimizations in debug builds; default/release compiler invocations emit neither
the comments nor these labels. No instructions or data bytes are introduced by
the metadata. The compiler runtime manifest records `vccDebugMetadata: 1`.
The app accepts metadata only from objects/listings/linker maps verified against
the same frozen sources and final executable. Inspection additionally checks
live mapped code and uses the debugger's atomic, non-I/O memory snapshot. Frame
locals require `-O0` as well as the preserved frame pointer and are unavailable in assembly-only functions, alternative calling
conventions, prologues/epilogues, or builds without a preserved U frame. Unsupported
floating-point formats and recursively truncated types remain explicitly
unavailable. Legacy metadata without `floatingFormat` is accepted but not decoded by guessing from storage size. Known format tags must agree with storage size; a genuine double-precision type is not tagged as supported. CMOC 0.1.100 currently lowers source-level `double` to `float`, so that alias carries the selected single-precision format. Expressions do not execute guest code or modify memory.
To regenerate the patch, edit a separate copy of the upstream source and produce
a unified diff with `a/src/…` and `b/src/…` paths. Verify that applying it to a fresh
copy succeeds and that ordinary optimized builds retain their original bytes.
## Indexed byte arithmetic and comparisons
`cmoc-indexed-byte-subtraction.patch` corrects three peephole rules in the build copy of CMOC 0.1.100 (modified November 7, 2026, GPL-3.0-or-later). On the 6809, B is the low byte of D. A byte load or negation can change the effective address of a later B- or D-indexed operand, including an indirect one. The subtraction and comparison rules now keep the original instruction order in those cases. The rules that remove a stack push also guard operands whose address would change with the stack pointer or an index side effect. Ordinary immediate substitutions remain available.
The [guest regression](../../../tests/toolchain/indexed-subtraction/qualification.c) exercises `184 - heights[i]` with runtime indices, variable bases, byte wraparound, both operand orders and equality/inequality against an array element. The [runner](../../../tests/toolchain/indexed-subtraction/check.py) checks the output against host-calculated expectations on MC6809 and HD6309 at `-O0` and `-O2`. It also runs as part of `tools/toolchain/check.py --rom`. Packaged runtimes identify the change with `vccIndexedByteSubtractionFix: 1` in their manifest.
## Indexed byte loads in function arguments
`cmoc-indexed-argument-load.patch` (November 11, 2026, GPL-3.0-or-later)
corrects `removeUselessLdaOrLdb` in the CMOC 0.1.100 build copy. The rule used
to remove an index reload from `LDB index; LDX #array; LDB D,X`, although B is
the low byte of D and is needed to select the loaded byte. Consecutive indexed
function arguments could therefore use the preceding argument's value as an
array subscript. The rule now uses the existing instruction-effects analysis
to preserve B dependencies in both intervening and final loads, including
indirect B/D-indexed operands. It also checks the actual operand for
predecrement/postincrement side effects. Independent overwritten loads remain
eligible for removal.
The [target regression](../../../tests/toolchain/indexed-arguments/qualification.c)
passes adjacent elements from two arrays at runtime indices 0 and 2, using
byte indices, word indices and pointer bases, with distinct surrounding
sentinels. Its [runner](../../../tests/toolchain/indexed-arguments/check.py)
executes `--coco --no-relocate --switch=jump` binaries at `-O0` and `-O2` on
MC6809 and HD6309; it is included in `tools/toolchain/check.py --rom`.
The [rule check](../../../tests/toolchain/indexed-arguments/check-rule.py)
links the actual built compiler objects and checks dependency/side-effect guards
as well as safe removals. See the [qualification record](../../../docs/development/CMOC_INDEXED_ARGUMENT_LOAD.md).
Packaged runtimes identify the change with `vccIndexedArgumentLoadFix: 1`.
## Logical negation of integer results
`cmoc-add-zero-flags.patch` (November 7, 2026, GPL-3.0-or-later) corrects CMOC 0.1.100's general peephole optimizer. CMOC emits `ADDD #0` to set the flags for a word-sized comparison with zero. A function can return 1 in D with Z still set from clearing A. Removing the add before the `tfrZtoB` helper made `!getReady()` return 1 in that case. The patch removes the general rule's unproven add-zero deletions and byte-test substitutions. The separate optimizations for recognized load/compare/branch sequences still run.
The [guest regression](../../../tests/toolchain/logical-negation.c) prints actual results for zero, widened unsigned bytes and 16-bit values. Run `tools/toolchain/check.py --rom` with a local CoCo 3 ROM to check those results at `-O0` and `-O2` on MC6809 and HD6309. Rebuilt app toolchains record `vccAddZeroFlagsFix: 1` in the manifest.
## Explicit before-directory disk allocation
`writecocofile-before-dir.patch` (November 4, 2026, GPL-3.0-or-later) adds
`--allocate-before-dir` as an explicit choice of the existing forward allocator.
It starts at granule zero, skips occupied granules, and continues above the
directory track if necessary. It does not imply a strict below-directory limit.
The last allocation option wins, as with the existing choices.
`build.py` applies it only to the build copy. `build-runtime.py` records
`vccWriteCoCoFileBeforeDir: 1`. The original CoCo Letters Makefile uses this option;
its former recipe-removal patch is retired and the vendored game matches upstream.
Runtime verification checks allocation order, byte-identical default behavior,
file readback, and spillover beyond the lower half of the disk.
## LWASM project input boundary
The native Assembly workspace passes `--project-inputs` when invoking LWASM.
`lwtools-project-inputs.patch` (November 5, 2026, GPL-3.0-or-later) constrains
source and binary input reads to regular files inside the physical working
directory. It checks each open, including binary data reopened during emission.
The companion `--project-map=FILE` records physical source paths, physical
one-based lines, sections, offsets and original instruction bytes. Macro
expansions, data directives, synthesized 6800/convenience operations and
OS-9 calls cannot become source breakpoints. The Swift client verifies final
DECB bytes after relocation. A project map requested with `--6809` also
rejects source pragmas that change that target.
The app supplies an isolated, symlink-free copy of the source snapshot. Other
invocations retain ordinary LWASM path behavior. Custom Make recipes execute
as user-supplied build commands and have a separate trust boundary.
Rebuild and stage the native runtime with `build-runtime.py` before packaging
the workspace. The runtime manifest records `vccLWASMProjectInputs: 1`;
older assemblers reject the required option.