# TLM JXCL — Instruction Set Architecture Specification

This is the authoritative architectural specification for **TLM JXCL**
("Pure Raw Dense ISA Forge"): a deterministic, byte-addressable, 64-bit
instruction set, and the reference implementation of it in the `jxcl`
crate. Every bare file path in this document (`src/...`, `alu.rs`,
`execution.rs`, etc.) is relative to `crates/jxcl/`.

The implementation (`isa::opcodes::ALL`/`all_defs()`) is the single
source of truth for opcode numbers, formats and flag effects; this
document is a human-readable rendering of that same table plus the
architectural decisions the code makes (this file and `isa/opcodes.rs`
must never disagree — if they do, the registry is correct and this file
has a bug).

## 1. Machine model

| Component | Width | Notes |
|---|---|---|
| General-purpose registers `R0`-`R31` | 64-bit | `R0` is hardwired to zero: reads yield `0`, writes are discarded. |
| `PC` (program counter) | 64-bit | Holds the address of the instruction currently being fetched. |
| `SP` (stack pointer) | 64-bit | Grows downward; initialized to `memory.len()`. |
| `FP` (frame pointer) | 64-bit | Architectural register; the base ISA never writes it itself (available for calling-convention use by software). |
| `FLAGS` | 4 used bits | `Z` (bit 0), `N` (bit 1), `C` (bit 2), `V` (bit 3). |
| Address space | 64-bit | Backed by a bounded flat buffer in the reference machine. |
| Endianness | Little-endian | All multi-byte memory and immediate fields. |

## 2. Encoding

Every register operand occupies **one whole byte** (values `0..32` are
legal; anything else is `INVALID_REGISTER`). This is a deliberate
trade-off: JXCL is dense relative to fixed-width RISC encodings (the
shortest instructions are 1-2 bytes; nothing is padded to a uniform
word), but every field boundary is byte-aligned, so decoding is never
ambiguous — no bit-packing puzzle, no variable-length integer scheme.
Immediates and displacements are fixed-width per opcode (never chosen by
a runtime flag) and little-endian.

| Format | Layout | Length |
|---|---|---|
| `None` | `opcode` | 1 |
| `R` | `opcode, rd` | 2 |
| `RR` | `opcode, rd, rs` | 3 |
| `RRR` | `opcode, rd, rs1, rs2` | 4 |
| `RImm64` | `opcode, rd, imm64` | 10 |
| `RMem` | `opcode, rd, base, disp32` | 7 |
| `MemR` | `opcode, base, disp32, rs` | 7 |
| `Cas` | `opcode, rd, base, rs_new, disp32` | 8 |
| `BranchImm32` | `opcode, disp32` | 5 |
| `Imm16` | `opcode, imm16` | 3 |

Minimum instruction length: 1 byte. Maximum: 10 bytes. Opcode space: one
byte (256 possible opcodes; 50 are assigned).

Effective address for every memory operand (`RMem`/`MemR`/`Cas`) is
`R[base] + sign_extend(disp32)` — there is no scaled-index
(`base + index*scale + disp`) addressing mode in this version; that is a
deliberate scope decision (see spec discussion §8), not an oversight.

## 3. Opcode map

| Opcode | Mnemonic | Format | Flags | Category |
|---|---|---|---|---|
| 0x00 | NOP | None | — | System |
| 0x01 | MOV | RR | — | Data |
| 0x02 | MOVI | RImm64 | — | Data |
| 0x03 | LOAD | RMem | — | Data |
| 0x04 | STORE | MemR | — | Data |
| 0x05 | PUSH | R | — | Data |
| 0x06 | POP | R | — | Data |
| 0x07 | LEA | RMem | — | Data |
| 0x10 | ADD | RR | Z,N,C,V | Arithmetic |
| 0x11 | SUB | RR | Z,N,C,V | Arithmetic |
| 0x12 | ADC | RR | Z,N,C,V | Arithmetic |
| 0x13 | SBC | RR | Z,N,C,V | Arithmetic |
| 0x14 | MUL | RR | Z,N,C,V | Arithmetic |
| 0x15 | MULH | RR | Z,N | Arithmetic |
| 0x16 | DIV | RR | Z,N | Arithmetic |
| 0x17 | REM | RR | Z,N | Arithmetic |
| 0x18 | NEG | R | Z,N,C,V | Arithmetic |
| 0x19 | INC | R | Z,N,V | Arithmetic |
| 0x1A | DEC | R | Z,N,V | Arithmetic |
| 0x20 | AND | RR | Z,N | Logical |
| 0x21 | OR | RR | Z,N | Logical |
| 0x22 | XOR | RR | Z,N | Logical |
| 0x23 | NOT | R | Z,N | Logical |
| 0x24 | NAND | RR | Z,N | Logical |
| 0x25 | NOR | RR | Z,N | Logical |
| 0x26 | XOR3 | RRR | Z,N | Logical |
| 0x30 | SHL | RR | Z,N,C | Shift |
| 0x31 | SHR | RR | Z,N,C | Shift |
| 0x32 | SAR | RR | Z,N,C | Shift |
| 0x33 | ROL | RR | Z,N,C | Shift |
| 0x34 | ROR | RR | Z,N,C | Shift |
| 0x40 | CMP | RR | Z,N,C,V | Comparison |
| 0x41 | TEST | RR | Z,N | Comparison |
| 0x50 | JMP | BranchImm32 | — | Control flow |
| 0x51 | CALL | BranchImm32 | — | Control flow |
| 0x52 | RET | None | — | Control flow |
| 0x53 | JZ | BranchImm32 | — | Control flow |
| 0x54 | JNZ | BranchImm32 | — | Control flow |
| 0x55 | JC | BranchImm32 | — | Control flow |
| 0x56 | JNC | BranchImm32 | — | Control flow |
| 0x57 | JL | BranchImm32 | — | Control flow |
| 0x58 | JLE | BranchImm32 | — | Control flow |
| 0x59 | JG | BranchImm32 | — | Control flow |
| 0x5A | JGE | BranchImm32 | — | Control flow |
| 0x60 | HALT | None | — | System |
| 0x61 | TRAP | Imm16 | — | System |
| 0x62 | SYS | Imm16 | — | System |
| 0x70 | CAS | Cas | Z,N (custom, see §7) | Atomic |
| 0x71 | XCHG | RMem | — | Atomic |
| 0x72 | FENCE | None | — | Atomic |

`isa::opcodes::all_defs()` is machine-readable proof this table is
exhaustive and collision-free (`no_duplicate_opcodes` /
`every_mnemonic_has_exactly_one_entry` tests enforce it on every build).

## 4. Flag semantics

- **Carry (`C`)** follows the x86 convention: for `ADD`/`ADC` it is the
  *unsigned carry-out* of bit 63; for `SUB`/`SBC`/`CMP`/`NEG` it is the
  unsigned *borrow* (`1` iff the true difference is negative).
- **Overflow (`V`)** is always the *signed* overflow of the operation.
- `INC`/`DEC` leave `C` unchanged (only `Z`, `N`, `V`) — a documented
  choice distinguishing them from full `ADD`/`SUB` of `1`.
- `MUL` sets `C` and `V` together when the discarded high 64 bits of the
  128-bit product are nonzero; it does not distinguish signed vs.
  unsigned overflow.
- Shift/rotate `C` is the last bit shifted out (or, for shift-by-zero,
  `false`). Shift/rotate counts are masked to the low 6 bits of the
  count operand (`0..64`), never faulting on a large count.
- `CMP`/`TEST` compute like `SUB`/`AND` respectively but discard the
  result, keeping only flags.

## 5. Memory model

The reference machine is a single flat, bounded address space split into
two regions:

- **Code region** `[0, code_size)`: readable + executable, **not**
  writable.
- **Everything else**: readable + writable, **not** executable.

An access that only *partially* overlaps the code region is denied in
full (not just the overlapping part) — matching how a real MMU denies an
access that touches any byte of a protected page.

16/32/64-bit accesses must be naturally aligned or raise
`AlignmentFault`; 8-bit accesses are always aligned. Faults:
`INVALID_ADDRESS`, `ALIGNMENT_FAULT`, `READ_VIOLATION`,
`WRITE_VIOLATION`, `EXECUTE_VIOLATION` (`memory.rs`), plus
`INVALID_OPCODE`, `INVALID_REGISTER`, `DIVIDE_BY_ZERO`, `STACK_FAULT`,
`ILLEGAL_OPERAND` at the execution layer (`execution.rs`).

`LOAD`/`STORE`/`XCHG`/`CAS` all operate on 64-bit words only in this
version (no byte/half-word/word memory ops) — the enumerated instruction
list never asked for width-suffixed memory ops, so this is a scope
decision, not an omission.

## 6. Control flow

`PC` holds the address of the instruction currently being fetched.
Every branch/`CALL` displacement is **relative to the address of the
next sequential instruction**:

```
pc_after_fetch = pc_of_instruction + instruction_length
target = pc_after_fetch + displacement
```

Signed conditions after a `CMP`/`SUB` use the standard two's-complement
flag algebra: `JL` is `N != V`, `JGE` is `N == V`, `JG` is
`!Z && (N == V)`, `JLE` is `Z || (N != V)`.

`CALL` pushes `pc_after_fetch` (the return address) and jumps to the
target; `RET` pops that address back into `PC`. The stack grows
downward: `PUSH` decrements `SP` by 8 before writing; `POP` reads then
increments `SP` by 8. `SP` is initialized to `memory.len()`.

## 7. Atomics (single-threaded reference semantics)

`CAS rd, [base+disp], rs_new`: reads the memory word at the effective
address; if it equals `R[rd]` ("expected"), writes `R[rs_new]` there and
leaves `R[rd]` unchanged, setting `Z`. Otherwise `R[rd]` is overwritten
with the actual memory value and `Z` is cleared. `N` reflects the sign
bit of whatever ends up in `R[rd]`. This is a custom flag convention
(not the generic ALU `Z`/`N`), documented here as required by spec §25.

`XCHG rd, [base+disp]`: atomically swaps `R[rd]` with the memory word.

`FENCE`: a real, decodable no-op in this single-threaded reference
model — there is no second agent whose memory-visibility order a fence
could affect. It exists so instruction streams written for a concurrent
JXCL backend still assemble and execute here unchanged (spec §25
explicitly disclaims any hardware cache-coherency claim beyond what is
actually implemented).

## 8. Binary format

See `src/binary.rs` for the exact 56-byte header layout (`MAGIC`,
`VERSION`, `ARCHITECTURE`, `ENTRY_POINT`, `CODE_OFFSET`, `CODE_SIZE`,
`DATA_OFFSET`, `DATA_SIZE`, `FLAGS`, reserved). When loaded, code is
placed at virtual address `0` and data immediately follows at virtual
address `code_size` — a fixed, deterministic layout.

## 9. Assembly syntax

```
start:
    MOVI R1, 10
    MOVI R2, 20
loop:
    ADD  R1, R2
    DEC  R2
    CMP  R2, R0
    JG   loop
    HALT

.data
buffer:
    .qword 1234
    .byte 1, 2, 3
```

- Labels (`name:`), instructions, and directives are one per line;
  `;` starts a line comment.
- Registers: `R0`-`R31` (case-insensitive).
- Numeric literals: decimal, `0x` hex, `0b` binary; a leading `+`/`-` is
  accepted before a literal.
- Memory operands: `[Rbase]`, `[Rbase+disp]`, `[Rbase-disp]`.
- Directives: `.code`/`.text`, `.data` (switch section), `.const NAME
  value`, `.entry LABEL_OR_NUMBER`, `.byte`/`.word`/`.dword`/`.qword
  v, v, ...` (emit data).
- A label or `.const` reference is used wherever an immediate,
  displacement, or branch target is expected; label addresses are
  absolute virtual addresses (code labels equal their code offset; data
  labels equal `code_size + their data offset`).

The disassembler's canonical form never invents label names — it prints
every resolved address as a plain number, which the assembler accepts
anywhere it accepts a label. This is what makes
`assemble(disassemble(program)) == program` hold without needing a
symbolication pass in the disassembler (see `src/disassembler.rs`).

## 10. Execution engine

`execution::step` performs, in order: **fetch** (opcode byte, then the
rest of the instruction once its format-determined length is known) →
**decode** (`encoding::decoder::decode_one`, which also validates every
register field) → **execute** (the giant match in `execution.rs`,
dispatching to `alu.rs` for arithmetic/logical/shift operations) →
**update state** → **next PC**. Every architectural fault path sets
`state.fault` and `state.halted` and returns `StepResult::Faulted`
rather than panicking. The handful of `.unwrap()`/`.expect()` calls
outside test code (`execution.rs`'s register read/write, `main.rs`'s
post-validation binary re-parse, fixed-width slice-to-array conversions
in `binary.rs`/`encoding/decoder.rs` after a length check earlier in the
same function) are all on invariants the immediately preceding code in
that same function already established — none of them is reachable on
malformed input reaching that point, but they are not architectural
fault handling either. All *architectural* error/fault reporting — bad
opcodes, bad registers, memory violations, divide-by-zero, stack
under/overflow, malformed assembly/binaries — goes through the
structured error types in `errors.rs`, never a panic.

`SYS`/`TRAP` never touch the host filesystem/network/process/environment
themselves — they only set `state.pending_signal`, which the CLI or a
future host integration observes after `step()` returns.