linx-isa-manual

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

# 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

# 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

# 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
<<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.