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.