--- name: linx-isa-manual description: LinxISA v0.57 manual navigation and authoring skill. Use when reading, updating, or cross-referencing the ISA manual at docs/architecture/isa-manual/. Contains the complete golden register contract, canonical instruction groups, and build/test workflow. --- # LinxISA v0.57 Manual Navigation Skill ## Overview This skill covers the ISA manual at `docs/architecture/isa-manual/` and its associated generators. The canonical source-of-truth for active instruction definitions is `isa/v0.57/linxisa-v0.57.json`. v0.57 is the sole active ISA release. Use the v0.57 release manifest as the conformance manifest; do not route active manual generation, encoding diagrams, or instruction fragments to any retired profile path. ## Golden Register Contract The ISA manual's register table (generated by `tools/isa/gen_registers_reg5.py`) must be derived only from the checked-in `isa/v0.57` register JSON. Register namespaces retain their own encoded class/index; do not invent one global register-number space or read external CSV files. ### General-Purpose Registers (R0–R23) | Code | Name | Asm | Description | |------|------|------|-------------| | 0 | R0 | zero | 常数0 | | 1 | R1 | sp | 栈指针寄存器 | | 2 | R2 | a0 | 函数参数0 | | 3 | R3 | a1 | 函数参数1 | | 4 | R4 | a2 | 函数参数2 | | 5 | R5 | a3 | 函数参数3 | | 6 | R6 | a4 | 函数参数4 | | 7 | R7 | a5 | 函数参数5 | | 8 | R8 | a6 | 函数参数6 | | 9 | R9 | a7 | 函数参数7 | | 10 | R10 | ra | 函数返回值 | | 11 | R11 | s0/fp | 栈帧寄存器/callee-save寄存器0 | | 12 | R12 | s1 | callee-save寄存器1 | | 13 | R13 | s2 | callee-save寄存器2 | | 14 | R14 | s3 | callee-save寄存器3 | | 15 | R15 | s4 | callee-save寄存器4 | | 16 | R16 | s5 | callee-save寄存器5 | | 17 | R17 | s6 | callee-save寄存器6 | | 18 | R18 | s7 | callee-save寄存器7 | | 19 | R19 | s8 | callee-save寄存器8 | | 20 | R20 | x0 | caller-save寄存器0 | | 21 | R21 | x1 | caller-save寄存器1 | | 22 | R22 | x2 | caller-save寄存器2 | | 23 | R23 | x3 | caller-save寄存器3 | ### Result Queue Registers | Code | Name | Description | |------|------|-------------| | 24–27 | T#1–T#4 | T result queue entries 1–4 | | 28–31 | U#1–U#4 | U result queue entries 1–4 (`u` aliases U#3, `t` aliases U#4) | **Total: 32 architectural reg5 encodings (codes 0–31).** Other register namespaces such as SSR, LSR, ACR, BID, and tile operands have independent encoding contracts and must not be appended to this table as global codes. ## Canonical Instruction Groups Instruction groups, form counts, and generated fragments must come from the active v0.57 golden catalog. Do not carry forward stale retired-profile denominator text; if the generated count changes, report the count emitted by `isa/v0.57/linxisa-v0.57.json`. | Chapter | Group | Forms | |---------|-------|-------| | 11_agu | Load UnScaled, Load Register Offset, Load Pair, Load Post-Index, Load Pre-Index, Load Long Offset, Load Symbol, Load PC-Relative | ~130 | | 12_alu | Arithmetic Operation 32/64bit, Compare Instruction, Shuffle, Move, Max-Min, Division, Format Convert, Three Source Integer | ~155 | | 13_fsu | Floating-point Arithmetic, Floating-point Compare, Two-Source Floating Point, Three-Source Floating Point, Format Convert (float) | ~45 | | 14_amo | Atomic Operation, Reduce Operation with Register | ~77 | | 15_bbd | Block Offset, Block Hint, Block Dimension, Block Split, Cache Maintain, Prefetch, RESERVE | ~81 | | 16_bru | Branch, PC-Relative, Load Immediate Offset | ~30 | | 17_cmd | SSR Access, Set Commit Argument | ~33 | | 18_rsv | General Manager, Immediate, Long Immediate | ~6 | | 19_sys | C.BSTART, C.TINST, C.UNARY | ~20 | | 20_vec | All V.* forms (load/store/arith/reduce/shuffle/etc.) | ~163 | ## SSR (System Status Registers) — 12 base registers | ID | Name | Access | Description | |----|------|--------|-------------| | 0x0000 | TP | RW | Thread pointer (TLS base) | | 0x0001 | GP | RW | Global pointer (global data base) | | 0x0010 | TIME | RO | Timer counter | | 0x0020 | CSTATE | RW | Common state (privilege + execution state) | | 0x0021 | LXLCID | RO | Linx logical core ID | | 0x0022 | VENDOR | RO | Vendor ID | | 0x0023 | VERSION | RO | Core version | | 0x0024 | LCFR | RO | Core feature description (includes LaneNum) | | 0x0025 | LCFR_EN | RW | Core feature enable | | 0x0050 | BLOCKNUM | RO | Block Number | | 0x0051 | BLOCKID | RO | Block ID | | 0x0C00 | CYCLE | RO | Cycle counter | ## Trap Classes (13) | TRAPNUM | Name | Description | |---------|------|-------------| | 0 | EXEC_STATE_CHECK | Target Exec State Check | | 4 | ILLEGAL_INST | Illegal instruction / SSR / encoding | | 5 | BLOCK_TRAP | Block-level trap (format/legality) | | 6 | SCALL | System call (ACRC) | | 32 | INST_PC_FAULT | Instruction PC fault | | 33 | INST_PAGE_FAULT | Instruction page fault | | 34 | DATA_ALIGN_FAULT | Data alignment fault | | 35 | DATA_PAGE_FAULT | Data page fault | | 44 | INTERRUPT | Interrupt (E=1, TRAPARG0=irq_id) | | 49 | HW_BREAKPOINT | Hardware breakpoint | | 50 | SW_BREAKPOINT | Software breakpoint (EBREAK) | | 51 | HW_WATCHPOINT | Hardware watchpoint | | 52 | ASSERT_FAIL | ASSERT failure trap | ## Manual Structure ``` docs/architecture/isa-manual/ src/ linxisa-isa-manual.adoc # Main entry point chapters/ 00_preamble.adoc # Version, changelog 01_introduction.adoc # Overview, profiles 02_isa_overview.adoc # ISA design principles 03_encoding_and_formats.adoc # Bit encoding, format table 03_programming_model.adoc # GPRs, ClockHands, Tile, BARG, SSR, FCSR 04_block_isa.adoc # Block structure, BSTART/BSTOP/EOB 05b_regid10_operand_encoding.adoc 05c_convert_type_encoding.adoc 06_assembly_conventions.adoc # Syntax, pseudo-ops 07_templates.adoc # Template blocks (FENTRY, FRET, etc.) 08_tile_blocks.adoc # Tile block types 09_memory_operations.adoc 09b_xb_system_call_block.adoc 10_system_and_privilege.adoc 11_agu.adoc 12_alu.adoc 13_fsu.adoc 14_amo.adoc 15_bbd.adoc 16_bru.adoc 17_cmd.adoc 18_rsv.adoc 19_sys.adoc 20_vec.adoc 90_instruction_reference.adoc 99_appendix_spec.adoc generated/ registers_reg5.adoc # AUTO-GENERATED from gen_registers_reg5.py system_registers_ssr.adoc # AUTO-GENERATED from gen_ssr_adoc.py trapno_encoding.adoc # AUTO-GENERATED from gen_ssr_adoc.py instruction_details.adoc # AUTO-GENERATED from gen_manual_adoc.py instruction_group_summary.adoc mnemonic_index.adoc instruction_reference.adoc encodings/ # AUTO-GENERATED SVG diagrams enc_*.svg # One per instruction form enc_*_parts.svg # Multi-part instructions encoding_legend.svg instructions/ # AUTO-GENERATED instruction fragments setc.adoc, add.adoc, ... ``` ## Build and Validate ### Generate all manual content ```bash # Full manual build (AsciiDoc to PDF) cd docs/architecture/isa-manual && make gen pdf # Or HTML cd docs/architecture/isa-manual && make gen html # Just regenerate registers table python3 tools/isa/gen_registers_reg5.py --out-dir docs/architecture/isa-manual/src/generated # Regenerate instruction fragments python3 tools/isa/gen_instruction_fragments.py \ --spec isa/v0.57/linxisa-v0.57.json \ --uop-root isa/v0.57/uop_classification_v0.57 \ --out-dir docs/architecture/isa-manual/src/generated/instructions \ --enc-rel-dir encodings # Regenerate SSR/trap encoding tables python3 tools/isa/gen_ssr_adoc.py \ --spec isa/v0.57/linxisa-v0.57.json \ --out-dir docs/architecture/isa-manual/src/generated # Generate SVG encoding diagrams python3 tools/isa/gen_encoding_svg.py \ --spec isa/v0.57/linxisa-v0.57.json \ --out-dir docs/architecture/isa-manual/src/generated/encodings ``` ### Validate manual quality ```bash # Fragment quality check python3 tools/isa/gen_instruction_fragments.py \ --spec isa/v0.57/linxisa-v0.57.json \ --uop-root isa/v0.57/uop_classification_v0.57 \ --out-dir docs/architecture/isa-manual/src/generated/instructions \ --enc-rel-dir encodings \ --check # Canonical v0.57 guard checks python3 tools/isa/check_canonical_v057.py --root /Users/zhoubot/linx-isa python3 tools/isa/check_canonical_v057.py --root /Users/zhoubot/linx-isa python3 tools/isa/check_pto_v057_manifest.py --root /Users/zhoubot/linx-isa # MkDocs build (GitHub Pages) cd /Users/zhoubot/linx-isa && mkdocs build ``` ### Check for broken cross-references or missing content ```bash # Verify all generated instruction files exist python3 -c " import os, glob inst_dir = 'docs/architecture/isa-manual/src/generated/instructions' missing = [] # Check all includes in the main manual reference for f in glob.glob(f'{inst_dir}/*.adoc'): name = os.path.basename(f)[:-5] # Expected: every instruction form has a fragment print(f'Total instruction fragments: {len(glob.glob(f\"{inst_dir}/*.adoc\"))}') # Check registers_reg5.adoc has all 32 reg5 encodings content = open('docs/architecture/isa-manual/src/generated/registers_reg5.adoc').read() import re codes = re.findall(r'^\|`(\d+)`', content, re.MULTILINE) print(f'Register codes in generated file: {len(codes)} (expected 32)') " ``` ## Key Editing Rules 1. **Never edit generated files by hand.** All `generated/` files are overwritten by their respective generators. 2. **To add a reg5 encoding:** Update `isa/v0.57/registers/gpr_reg5.json`, rebuild the golden catalog, and re-run `tools/isa/gen_registers_reg5.py`. 3. **To add an instruction:** The instruction must exist in `isa/v0.57/linxisa-v0.57.json`. Re-run `gen_instruction_fragments.py` to regenerate its fragment. 4. **To fix the encoding diagram:** Update `tools/isa/gen_encoding_svg.py` and re-run. 5. **Register tables must stay consistent with checked-in golden JSON.** The generator is hermetic and must reject any external or home-directory source dependency. 6. **Chapter narrative introductions** (the long paragraphs at the start of each instruction chapter) are in `chapters/*.adoc` — these are hand-written and should be maintained carefully. ## v0.57 Delta Coverage Requirements - Document `TPREFETCH` as destination-free `TLOAD`: same addressing and attribute model, adjacent encoding family to `TLOAD`/`TSTORE`, and no tile destination/result publication. - Document v0.57 TMA selectors as a dense PTO tile-memory family `0..8`; reject holes, aliases, and legacy selector names unless the v0.57 manifest reserves them. - Keep named `CUBE` block/template forms unique across the manual, golden catalog, generator output, and examples. A distinct CUBE form needs a distinct mnemonic/template identity. - Add scalar CAS and DMA forms as active v0.57 deltas, not legacy extensions. - Keep the v0.57 PTO operation map synchronized with the 111 PTO dialect operations; missing or extra generated PTO manual fragments are blockers. - Remove or mark old spellings as rejected legacy syntax. Do not document legacy aliases as active compatibility unless the v0.57 catalog and compiler/QEMU gates accept them. ## Common Cross-Reference Anchors | Anchor | Location | |--------|----------| | `<>` | 00_preamble.adoc | | `<>` | 03_programming_model.adoc | | `<>` | GPR section | | `<>` | ClockHands section | | `<>` | Tile registers section | | `<>` | BARG section | | `<>` | 03_encoding_and_formats.adoc | | `<>` | 04_block_isa.adoc | | `<>` | 10_system_and_privilege.adoc | | `<>` | SSR table (generated) | | `<>` | ACR-scoped SSRs | | `<>` | 20_vec.adoc | | `<>` | 90_instruction_reference.adoc | | `<>` | Instruction groups summary (generated) | | `<>` | GPR table section | | `<>` | T result queue section | | `<>` | U result queue section | | `<>` | Trap encoding (generated) | ## Skill Evolve Policy - Update this skill when the manual structure changes (new chapters, new sections, renamed anchors). - Update register contract rows when checked-in register JSON changes. - Do NOT update for routine editorial fixes within chapters. - After updating, validate with `mkdocs build` and `python3 tools/isa/gen_instruction_fragments.py --check`.