Skip to content

LinxISA v0.57 Architecture Contract

This document is the live public architecture contract for LinxISA v0.57. It is the sole maintained ISA profile and incorporates the complete established scalar, vector, tile, system, kernel-execution, and rendering contract together with the v0.57 encoding additions.

Scope

  • Active ISA profile: v0.57
  • Canonical catalog: isa/v0.57/linxisa-v0.57.json
  • Canonical golden sources: isa/v0.57/
  • Kernel execution state: isa/v0.57/state/kernel_execution.json
  • Rendering profile: isa/v0.57/state/rendering_profile.json
  • PTO selector map: isa/v0.57/state/pto_encoding_map.json

The v0.57 contract is legacy-free. Removed compatibility spellings, archived raw fragments, generic mixed textual forms, and migration shims are illegal in active sources unless a v0.57 manifest assigns them explicitly as canonical forms.

Workload and Execution Model

LinxISA v0.57 is one block-structured architecture serving general-purpose, AI, and rendering workloads:

  • BCC and the block fabric orchestrate heterogeneous block execution.
  • VEC provides the canonical programmable SIMT engine for shaders, softmax, and other data-parallel loops.
  • AI workloads are primarily composed from CUBE + VEC + TMA.
  • Rendering workloads are primarily composed from VEC + TMA + TAU.
  • Engine overlap remains subordinate to architectural block/BID ordering, completion, flush, and recovery rules.

Architectural guarantees

  1. Block-structured execution is mandatory and control-flow targets resolve to legal block boundaries.
  2. MPAR and MSEQ are the canonical shader-kernel block types.
  3. B.TEXT selects structured out-of-line kernel bodies with dynamic termination at a legal body terminator.
  4. p is the architectural 64-bit EXEC mask; V.CMP.* ->p is the normative lane-mask generation rule.
  5. Shader kernels use one group PC, explicit EXEC mask state, and structured group-internal control flow bounded by the current B.TEXT region.
  6. l.* and v.* execution domains are derived by operand class inside one unified lx64 kernel space.
  7. Kernel global memory accesses use the bridged l.*.brg and v.*.brg forms and participate in the architectural bridged/MTC ordering domain.
  8. Tiles remain general-purpose intermediate-state storage; the rendering profile uses 4KB 1024x1 row-major SoA fragment/state carriers.
  9. TAU execution is tile-to-tile; descriptors carry small state and StateTiles carry hot or large state.
  10. The 32-bit and 48-bit fused BSTART.CALL forms retain two independently relocatable halfword-scaled PC-relative operands and atomically perform the call transfer and ra write.

The machine-readable catalog and state documents are normative. Downstream compiler, emulator, Linux, RTL, model, and workload implementations may not infer additional semantics from spreadsheets, archived notes, or legacy examples.

The published LinxCore implementation contract begins at docs/architecture/linxcore/overview.md; its canonical authoring source is rtl/LinxCore/docs/architecture/overview.md.

TMA Function Assignments

The TMA function field remains the 5-bit Function field in the existing typed tile-memory header:

31..27=DataType, 26..25=00, 24..20=Function, 19..15=00010, 14..0 fixed block-split tail.

The tile-memory aliases occupy adjacent function slots:

Function Canonical alias v0.57 status
0 BSTART.TLOAD load
1 BSTART.TSTORE store
2 BSTART.TMOV tile move
3 BSTART.TPREFETCH load without destination effects
4 BSTART.MGATHER masked-index gather family
5 BSTART.MSCATTER masked-index scatter family
6 BSTART.MGATHER.MASK predicate-masked gather
7 BSTART.MSCATTER.MASK predicate-masked scatter
8 BSTART.MGATHER.CAS per-element atomic gather/CAS
9..31 reserved illegal unless a later v0.57 manifest assigns them

Generic or mixed textual spellings such as BSTART.TMA <op>, <DataType> remain illegal in canonical v0.57 sources. The legal public spelling is the canonical alias for the assigned function.

BSTART.TPREFETCH

BSTART.TPREFETCH is assigned to TMA Function=3, directly adjacent to TLOAD, TSTORE, and TMOV.

TPREFETCH has the same address-generation, descriptor-validation, translation, permission, memory-fault, ordering, and restartability contract as TLOAD, with all destination effects removed:

  • no B.IOT destination binding,
  • no tile allocation,
  • no tile queue push,
  • no tile metadata or tile data writeback,
  • no architectural destination dependency.

TPREFETCH is not an optional hint. An implementation may choose any microarchitectural cache action, but it must perform the same architectural address checks and fault behavior as TLOAD over the same footprint. A faulting TPREFETCH is precise and restartable under the same rules as a faulting TLOAD. A non-faulting TPREFETCH completes without producing a visible register or tile result.

PTO Tile Operation Boundary

The checked-in PTO manifests classify all 111 workbook rows exactly once: 97 use TEPL selectors, 6 use TMA functions, and 8 use CUBE functions. isa/v0.57/state/pto_ops.json preserves the workbook operands, dtypes, descriptions, target support, and evidence; pto_encoding_map.json is the normative Linx encoding disposition.

  • MGATHER, MSCATTER, MGATHER.MASK, and MSCATTER.MASK use the existing gather/scatter descriptions in the active tile-block documentation.
  • MGATHER.CAS is the v0.57 per-element atomic gather selector from PR #133. Every active lane returns the pre-CAS memory value; failed comparisons are architecturally visible through that value and software may retry.
  • Established PTO spellings retain their selectors. TTRANS maps to canonical TTRANSPOSE; review-only names and typos are not architectural.
  • New selectors occupy only the allocated ranges 0x02B..0x048, 0x080..0x08B, 0x0C0..0x0C8, and 0x0E0..0x0E3.

Scalar CAS and DMA Boundary

v0.57 adds the 32-bit CASB, CASH, CASW, and CASD encodings from LinxISA/linx-isa#139. They atomically read [SrcL], compare the old value with SrcR, conditionally store SrcD, and return the old value in RegDst. They support aq and rl ordering and do not support the far flag. The existing 48-bit HL.CAS* forms remain unchanged.

v0.57 also assigns the 32-bit DMA encoding from that PR. SrcL holds the source address, SrcR holds the destination address, exactly 64 bytes are copied, and the operation completes before its command is submitted. The phrase “control parameters” in the PR's provisional prose does not define a new control-word ABI and must not be used to reinterpret SrcR.

Release Conformance

The v0.57 release is conformant only when all of the following remain true:

  • isa/v0.57/state/engine_ops.json identifies profile v0.57 and lists the legal TMA aliases above.
  • isa/v0.57/state/pto_encoding_map.json freezes the exact PTO selector map.
  • Generated v0.57 JSON, opcode, manual, Sail, compiler, emulator, Linux, RTL, and model projections agree on the same mask/match and legality rules.
  • Negative tests reject unassigned TMA functions, retired compatibility spellings, and generic mixed textual forms.
  • Downstream tests prove that TPREFETCH faults and orders like TLOAD while producing no destination effects.

The canonical conformance commands are:

python3 tools/isa/build_golden.py --profile v0.57 --check
python3 tools/isa/validate_spec.py --profile v0.57
python3 tools/isa/check_canonical_v057.py --root .
python3 tools/isa/test_v057_profile.py
python3 tools/isa/check_pto_v057_manifest.py --root .
python3 tools/bringup/check_avs_contract.py \
  --matrix avs/linx_avs_v1_test_matrix.yaml
python3 tools/bringup/check_linxcore_arch_contract.py \
  --root . --strict --require-mkdocs

All public compiler, emulator, RTL, Linux, model, and runtime updates must preserve this contract.