RXAS Human Instruction Reference

This folder is the human-focused RXAS reference. It is intentionally separate from docs/ai-context implementation notes and from the historical generated VM-spec instruction chapter.

The reference covers every mnemonic accepted in RXAS source and gives each mnemonic an independently validated example. It can later feed the generated documentation pipeline.

Suggested Documentation Model

• Keep this folder as the human-authored source for RXAS semantics.
• Keep docs/ai-context/RXAS_ASSEMBLER.md focused on implementation architecture for agents and maintainers.
• Keep docs/instructions/ as machine/generated instruction metadata.
• Later, teach the VM-spec generator to consume these files or a structured derivative of them, rather than hand-maintaining separate prose in multiple places.

Current Inventory

• Source-accepted unique mnemonics: 379
• Source-accepted opcode/form rows: 585
• Authoritative database: binutils/include/rxops.h, filtered by rxop_is_source_mnemonic() in binutils/include/rxdefs.h
• Human-readable inventory source: rxas -i, which applies the same filter

Excluded Opcode Rows

The reference documents only mnemonics accepted in RXAS source. It deliberately excludes every database row whose opcode name starts with RESERVED_, together with the internal/runtime-only INULL, INTERRUPT, and IUNKNOWN opcodes. This is the exact rule implemented by rxop_is_source_mnemonic() and used by both the assembler lookup and rxas -i; excluded rows are not omitted merely because they lack prose or examples.

Skeleton Comparison

The authoritative filtered database currently has 379 unique mnemonics and 585 form rows. The section files contain 379 exact single-mnemonic headings, with no missing, unknown, or duplicate mnemonic headings.

Source Syntax

• RXAS Program Syntax: source layout, comments, header directives, procedures, labels, operands, literals, constants, and metadata.

Instruction Sections

• Program Control And Calls: 30 mnemonics
• Data Movement And Conversion: 7 mnemonics
• Integer, Logical, And Boolean: 44 mnemonics
• Floating Point: 24 mnemonics
• Decimal And Numeric Settings: 46 mnemonics
• Strings And Characters: 31 mnemonics
• Binary Memory: 41 mnemonics
• Arrays, Attributes, References, And Objects: 36 mnemonics
• I/O, Sockets, Processes, And Time: 48 mnemonics
• Signals, Breakpoints, And Runtime: 19 mnemonics
• Metadata And Introspection: 23 mnemonics
• Large And Fused Instructions: 29 mnemonics
• Uncategorized Review: 0 mnemonics

Review Notes

• The section grouping is editorial and can evolve as the human reference settles.
• Each mnemonic should appear exactly once across the section files; use Instruction Inventory to validate coverage.
• Binary-memory forms require particular care because constant/register forms, explicit byte ranges, bounds, and endian behavior differ by instruction.