docs/RTL_CONTRACT.md

# RTL Integration Contract

Spec §36-38 ask for an architectural boundary that a future RTL
(SystemVerilog/Verilog/VHDL) implementation can be built against without
either side needing to change the other's architectural semantics. This
document is that boundary, plus how the golden test vectors in
`tests/golden_vectors.rs` become hardware test vectors. (As in
`ISA_SPEC.md`, every bare file path here is relative to `crates/jxcl/`.)

**This repository does not contain RTL.** It contains the reference
software model and the contract a future RTL implementation must honor.
Claiming otherwise — presenting the Rust emulator as if it were, or
implied fabricated hardware — is exactly what spec §35 forbids ("Do not
pretend that a software emulator itself constitutes fabricated
hardware").

## Conceptual pipeline mapping

| JXCL concept | Hardware unit | Reference implementation |
|---|---|---|
| Fetch (opcode + operand bytes at `PC`) | Instruction Fetch unit | `memory::Memory::fetch`, `execution::step`'s fetch stage |
| Decode | Decode / instruction-format ROM | `encoding::decoder::decode_one`, keyed by `isa::opcodes` |
| Register read/write | Register File | `isa::registers::RegisterFile` |
| ADD/SUB/ADC/SBC/MUL/MULH/DIV/REM/NEG/INC/DEC | Integer ALU / multiplier / divider | `alu.rs` |
| AND/OR/XOR/NOT/NAND/NOR/XOR3 | Logic gates | `alu.rs` |
| SHL/SHR/SAR/ROL/ROR | Barrel shifter | `alu.rs` |
| CMP/TEST | ALU + flag generation, result discarded | `alu::cmp`/`alu::test` |
| LOAD/STORE/LEA/PUSH/POP | Address generation + memory interface | `execution.rs`, `memory.rs` |
| JMP/CALL/RET/Jcc | Control-flow unit (+ stack for CALL/RET) | `control.rs`, `execution.rs` |
| CAS/XCHG/FENCE | Atomic unit / memory ordering | `execution.rs` (single-threaded reference semantics, spec §25) |
| Writeback | Register file write port | End of `execution::step`'s match arm |

## What the RTL contract freezes

An RTL implementation of TLM JXCL must reproduce, cycle-independent of
its own microarchitecture:

1. **Every opcode's binary encoding** — `isa::opcodes::all_defs()` (opcode
   byte, `Format`, byte layout per `docs/ISA_SPEC.md` §2-3). This is
   frozen; adding an opcode is fine, changing an existing one's encoding
   is an incompatible architecture revision (bump `ARCHITECTURE_ID` in
   `isa/constants.rs`).
2. **Every instruction's formal semantics** — the match arm in
   `execution.rs` for that mnemonic, including exactly which flags it
   touches (`isa::opcodes::InstructionDef::flags`) and the precise
   carry/overflow/shift/comparison rules in `alu.rs`'s doc comments.
3. **The fault catalog** — `errors::ExecutionFault` / `MemoryFault` and
   exactly which condition raises which fault (`docs/ISA_SPEC.md` §5).
4. **PC/branch semantics** — `control::branch_target`'s formula.
5. **The stack/calling convention** — downward-growing, `SP` semantics
   in `docs/ISA_SPEC.md` §6.

What it does **not** freeze: cycle count, pipeline depth, branch
prediction, cache behavior, or any other microarchitectural detail not
observable in the architectural state (`MachineState`). Spec §34 is
explicit that the reference implementation prioritizes correctness and
clarity over performance, and that applies equally to a hardware
implementation's *internal* timing — only the architecturally visible
end state after each instruction is part of this contract.

## Golden vectors as hardware test vectors

`tests/golden_vectors.rs` defines `Golden { name, source, expect_halted,
expect_fault, expect_registers, expect_flags }` entries. Each one is,
by construction, exactly the shape spec §38 asks for:

- **initial registers / initial memory**: implicit — every vector starts
  from `MachineState::new` (all registers zero, `SP = memory.len()`,
  flags clear) plus whatever the program's own prologue sets up.
- **program bytes**: the assembled `source`.
- **expected final registers / flags / halt-or-fault**: the `expect_*`
  fields.

To turn one into an RTL test bench vector: assemble `source` with
`jxcl asm`, load the resulting `.jxc`'s code section into the RTL
model's instruction memory at address `0`, run the RTL model to
completion (or the same fault), and diff its final register
file/flags/halt-or-fault-code against the `expect_*` fields — byte for
byte, bit for bit. A mismatch means either the RTL or this reference
model has an architectural bug; per spec §36, the ISA specification
(this document plus `ISA_SPEC.md`) — not either implementation — is the
tiebreaker for which one is wrong.