Skip to content

LinxISA v0.4 Architecture Contract

This document is the live public architecture contract for LinxISA v0.4. It replaces v0.3 as the active repository baseline and defines the canonical shader-kernel and rendering profile that downstream compiler, emulator, RTL, and runtime work must preserve.

Scope

  • ISA profile: v0.4 only
  • Canonical catalog: isa/v0.4/linxisa-v0.4.json
  • Canonical golden sources: isa/v0.4/
  • Canonical kernel execution state: isa/v0.4/state/kernel_execution.json
  • Canonical rendering profile: isa/v0.4/state/rendering_profile.json

Workload Targets

LinxISA v0.4 is not a rendering-only profile. The architecture is intended to cover multiple workload classes under one block-structured ISA:

  • general-purpose computing across the broader scalar, vector, and tile-capable machine,
  • AI-oriented workloads primarily composed from CUBE + VEC + TMA,
  • rendering-oriented workloads primarily composed from VEC + TMA + TAU.

These workload profiles share the same architectural contract and must not be described as separate incompatible machines.

Programmable parallel-loop execution across workload classes is provided by VEC: AI kernels such as softmax, rendering shaders, and other data-parallel loop work all run through the canonical SIMT vector model unless a more specialized engine is explicitly selected.

The architectural composition remains LinxCore-native:

  • BCC and the block fabric orchestrate heterogeneous block execution,
  • VEC, TMA, CUBE, and TAU are selected through the same architectural block model rather than through a separate GPU packet machine,
  • engine overlap and acceleration remain subordinate to the existing block/BID ordering, completion, flush, and recovery rules.

Architectural Guarantees

  1. Block-structured execution remains mandatory.
  2. Architectural control-flow targets MUST resolve to legal block boundaries.
  3. MPAR and MSEQ are the canonical shader-kernel block types in v0.4.
  4. Shader kernels are structured body streams selected by B.TEXT and bounded by the first terminator marker encountered in the body stream.
  5. p is the architectural 64-bit EXEC mask for shader-kernel execution.
  6. V.CMP.* ->p is the normative lane-mask generation rule.
  7. Kernel l.* versus v.* execution domain is derived by operand class inside one unified lx64 kernel space.
  8. Kernel global memory access uses bridged forms only: l.*.brg and v.*.brg.
  9. Tiles remain general-purpose intermediate-state storage; the first rendering profile uses 4KB 1024x1 row-major SoA fragment/state carriers.
  10. TAU execution is tile-to-tile only; small state uses descriptors and hot/large state uses StateTiles.
  11. Contradictory legacy raw fragments are archived history only and are reserved or illegal in canonical v0.4.
  12. Privileged state, trap envelopes, template replay flags, and body-fetch rules follow the v0.4 manual and state catalog.

v0.4 Delta Summary

This section is the canonical summary of architecture-level changes from the older v0.3 baseline into live v0.4.

Shader-Kernel Bodies

Canonical v0.4 promotes SIMT shader kernels from the older linear-snippet model into structured kernel bodies:

  • MPAR and MSEQ are the canonical shader-kernel block types,
  • kernel bodies may contain structured in-body control flow,
  • containment, entry, exit, and termination rules are normative in isa/v0.4/state/kernel_execution.json and the ISA manual programming-model chapters.

Unified Kernel Execution Domain

Canonical v0.4 uses one unified lx64 kernel-body execution space:

  • l.* versus v.* execution is derived by operand class,
  • p is the architectural 64-bit EXEC mask,
  • V.CMP.* ->p is the normative lane-mask generation rule,
  • scalar/group-domain source operands broadcast when consumed by v.*,
  • direct v.* writes into scalar/group-domain destinations are illegal except through explicit reduction or mask-producing instructions.

Shader Memory Path

Canonical v0.4 makes the shader memory path explicit:

  • shader-kernel global memory uses bridged forms only: l.*.brg and v.*.brg,
  • l.*.brg and v.*.brg share the same explicit-only address-formation rule,
  • shader-kernel memory issue participates in the architectural bridged or MTC ordering domain,
  • BCC scalar memory issue is architecturally closed while a canonical shader kernel is active.

Rendering And Workload Implications

Canonical v0.4 also freezes the high-level workload and rendering impact of these kernel changes:

  • the ISA is one multi-workload machine covering general-purpose, AI, and rendering workloads,
  • VEC is the general programmable SIMT engine for parallel-loop work,
  • rendering uses the BCC-led block-stream submission model and may use either immediate-style or tile-based pipeline strategies,
  • exact long-term rendering stage partitioning, binning ownership, and other performance-shaping pipeline choices remain intentionally deferred unless a later canonical page freezes them.

Canonical Pages

  • docs/architecture/isa-manual/src/linxisa-isa-manual.adoc
  • docs/architecture/v0.4-hardening-policy.md
  • docs/architecture/v0.4-workload-engine-model.md
  • docs/architecture/v0.4-rendering-kernel-authoring.md
  • docs/architecture/v0.4-rendering-pto-contract.md
  • docs/architecture/v0.4-rendering-command-contract.md
  • docs/architecture/linxcore/overview.md
  • docs/architecture/linxcore/microarchitecture.md
  • docs/architecture/linxcore/interfaces.md
  • docs/architecture/linxcore/verification-matrix.md

Conformance Gates

python3 tools/isa/build_golden.py --profile v0.4 --check
python3 tools/isa/validate_spec.py --profile v0.4
python3 tools/bringup/check_avs_contract.py --matrix avs/linx_avs_v1_test_matrix.yaml
python3 tools/bringup/check_avs_profile_closure.py --matrix avs/linx_avs_v1_test_matrix.yaml --status avs/linx_avs_v1_test_matrix_status.json --tier pr
python3 tools/bringup/check_sail_model.py
python3 tools/isa/check_canonical_v04.py --root .
python3 tools/bringup/check_linxcore_arch_contract.py --root . --strict --require-mkdocs

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