Files
VCCPlusOSS/docs/development/CMOC_INDEXED_ARGUMENT_LOAD.md

4.9 KiB

CMOC indexed argument-load qualification

Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.

Failure and general correction

A joystick-driven program passed adjacent axis and calibration bytes to one function. After loading centers[index + 1], CMOC's removeUselessLdaOrLdb peephole rule deleted the reload of index before centers[index]:

LDB index
LDX #centers
LDB D,X

The last instruction overwrites B only after computing its effective address. B is the low byte of D, so the first load is required. Without it, the previous argument's value becomes the subscript. Correct emulator joystick values can therefore reach incorrect compiled game logic.

The rule also checked the instruction mnemonic instead of its operand for predecrement/postincrement effects, and recognized only an explicit B, prefix on the intervening X load. The new cmoc-indexed-argument-load.patch uses the compiler's existing InsEffects.read analysis on both following instructions. It preserves B dependencies, including D-indexed and indirect operands, and uses the existing side-effect predicate on the removed load. Independent overwritten loads can still be optimized. This is a compiler rule correction; it does not recognize a game, input API, variable name or source pattern.

build.py applies the patch only to its ignored source copy after the existing compiler patches. build-runtime.py records vccIndexedArgumentLoadFix: 1. The pinned CMOC source and third-party manifests remain unchanged.

Target-executed regression

The authored fixture passes four actual bytes to a capture function from two arrays, at runtime indices 0 and 2. It covers byte indices, word indices and pointer bases. Distinct surrounding sentinels distinguish the stale-index error from legitimate values. The guest prints raw result bytes; expected values and comparison belong to the host runner, rather than the optimizer under test.

For each pair of indices, the expected bytes are:

04 0C 08 10 14 1C 18 20

The baseline staged compiler passed -O0 on MC6809 and HD6309 but failed -O2 on both. Its byte-index case printed 04 0C 3A 10 14 1C 3A 20: the sentinel 3A replaced the third argument. Retained generated assembly confirmed the removed reload immediately before LDB D,X.

The fixed universal staged compiler passed -O0 and -O2 on both emulated processors through both its arm64 and x86_64 compiler slices: eight executions, each checking all six calls. All use --coco --no-relocate --switch=jump. The CoCo 3 ROM is an explicitly supplied local input. The x86_64 host compiler ran under Rosetta on Apple Silicon; no physical Intel or physical CoCo result is claimed.

Reproduce with a staged runtime and a separately built shared-core library:

python3 tests/toolchain/indexed-arguments/check.py \
  platforms/macos/LocalResources/ToolchainBundle \
  /path/to/libVCCCore.a platforms/macos/LocalResources/ROMs/coco3.rom \
  --host-arch arm64
python3 tests/toolchain/indexed-arguments/check.py \
  platforms/macos/LocalResources/ToolchainBundle \
  /path/to/libVCCCore.a platforms/macos/LocalResources/ROMs/coco3.rom \
  --host-arch x86_64

The regression also runs within tools/toolchain/check.py --rom. Its runner uses temporary output and leaves the app, guest sessions and disk images alone.

Additional checks and runtime staging

  • The focused native rule check links the actual compiler build objects and checks 13 dependency/side-effect guards and two safe removals. It covers direct/indirect B and D indexing, intervening LDX/LEAX dependencies, and direct/indirect index/stack updates.

  • Existing indexed-subtraction and logical-negation target regressions pass at -O0 and -O2 on both guest processors with the new compiler.

  • The public source-only toolchain build passes; all nine library archive targets, greeting compile/link, DECB format and known assembler bytes pass.

  • Both compiler slices were rebuilt through tools/toolchain/build.py with explicit --host-arch arm64 and --host-arch x86_64 and minimum macOS 14.

  • tools/toolchain/verify-runtime.py passes for that bundle: both complete architecture build chains, system-only dynamic dependencies, relocated bundle paths, preprocessor errors, dependency regeneration with spaces/quotes/#/$, bundled Perl modules, disk allocation and ROM-backed/standalone disk linking, with developer tools deliberately unavailable to the bundled workflow.

To run the native rule check after a native build.py source build:

python3 tests/toolchain/indexed-arguments/check-rule.py \
  .build/cmoc-indexed-arguments/fixed/work/cmoc