| 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
cd docs/architecture/isa-manual && make gen pdf
cd docs/architecture/isa-manual && make gen html
python3 tools/isa/gen_registers_reg5.py --out-dir docs/architecture/isa-manual/src/generated
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
python3 tools/isa/gen_ssr_adoc.py \
--spec isa/v0.57/linxisa-v0.57.json \
--out-dir docs/architecture/isa-manual/src/generated
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
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
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
cd /Users/zhoubot/linx-isa && mkdocs build
Check for broken cross-references or missing content
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
- Never edit generated files by hand. All
generated/ files are overwritten by their respective generators.
- 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.
- 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.
- To fix the encoding diagram: Update
tools/isa/gen_encoding_svg.py and re-run.
- Register tables must stay consistent with checked-in golden JSON. The generator is hermetic and must reject any external or home-directory source dependency.
- 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 |
|---|
<<preamble>> | 00_preamble.adoc |
<<progmodel>> | 03_programming_model.adoc |
<<progmodel-gpr>> | GPR section |
<<progmodel-clockhands>> | ClockHands section |
<<progmodel-tile>> | Tile registers section |
<<progmodel-barg>> | BARG section |
<<encoding>> | 03_encoding_and_formats.adoc |
<<blockisa>> | 04_block_isa.adoc |
<<system>> | 10_system_and_privilege.adoc |
<<ssr-table>> | SSR table (generated) |
<<ssr-acr-scoped>> | ACR-scoped SSRs |
<<chapter_vec>> | 20_vec.adoc |
<<insnref>> | 90_instruction_reference.adoc |
<<insnref-groups>> | Instruction groups summary (generated) |
<<reg5-general-purpose-registers-gpr>> | GPR table section |
<<reg5-t-result-queue>> | T result queue section |
<<reg5-u-result-queue>> | U result queue section |
<<trapno-encoding>> | 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.
