Skip to content

LinxISA v0.4 Rendering Command Contract

This document defines the live public command-submission contract for the canonical v0.4 rendering and compute stack.

It freezes the early bring-up policy that Vulkan command buffers are lowered by software into Linx block streams before kernel submission. The contract applies to user-mode driver code, kernel submission plumbing, emulator behavior, and bring-up evidence.

Scope

  • API level: Vulkan-first graphics and compute submissions.
  • Submission unit: validated Linx block streams plus referenced descriptor/state records.
  • Execution substrate: Linx block/BID ordering, MPAR shader kernels, and engine-dispatch blocks.

This page is normative for command lowering and submission ownership. It does not replace the ISA manual for instruction semantics.

Canonical Submission Model

Canonical v0.4 systems use a BCC-led command model:

  • User-mode driver code, or a BCC-adjacent runtime acting on its behalf, MUST lower Vulkan command buffers into a submission-ready Linx block stream before that work enters the kernel queue interface.
  • The kernel driver MUST treat the submitted block stream as the semantic unit of execution. It MAY validate, patch, schedule, and account for that stream, but it MUST NOT perform a second high-level Vulkan command interpretation pass.
  • The on-device command processor MUST consume validated block streams and engine-dispatch packets, not raw Vulkan command buffers and not a separate opaque GPU packet language.

Rationale:

  • keeps command-processor behavior small and auditable during bring-up,
  • lets the software stack reuse existing Linx block/BID ordering rules,
  • makes emulator, RTL, and AVS evidence comparable at the same semantic layer.

Required Block-Stream Contents

The lowered stream MUST make all execution-relevant work explicit. The stream MUST encode, directly or by stable referenced records:

  • pipeline and shader state selection,
  • descriptor/resource bindings,
  • MPAR or other architecturally legal kernel launches,
  • synchronization and barrier points,
  • DMA, clear, copy, and other fixed-function engine invocations,
  • completion points needed for queue fences, timeline semaphores, and runtime observability.

Hidden command-processor side tables that materially change execution semantics are not part of the canonical v0.4 model.

Ownership Split

User-Mode Driver Responsibilities

The user-mode driver or its lowering runtime MUST:

  • compile or select shader/kernel code,
  • flatten API command recording into an executable block stream,
  • choose state-bundle records and resource descriptors referenced by that stream,
  • emit explicit synchronization blocks and waits required by API ordering,
  • preserve the architectural legality constraints of the underlying block and kernel model.

Kernel Driver Responsibilities

The kernel driver MUST own:

  • memory allocation and mapping,
  • queue submission and scheduling,
  • relocation/patch application for referenced records,
  • validation of user-provided block streams and descriptor references,
  • fence and timeline object bookkeeping,
  • performance/debug accounting.

The kernel driver MUST NOT be the first component that expands Vulkan command buffers into Linx architectural work items.

State Bundle Contract

Pipeline and render-state bundles are canonicalized as referenced records, not as opaque command-processor private state.

  • Small or rarely changing values SHOULD be emitted directly through descriptor operands such as B.ARG and B.IOR.
  • Larger or hot state MAY be materialized into referenced records or StateTiles and then named explicitly from the lowered block stream.
  • Pipeline-state objects, descriptor tables, and similar reused state MUST be immutable for the lifetime of a submitted stream view. Rebinding is expressed by switching handles or descriptors, not by mutating hidden in-flight state.

This rule keeps replay, validation, and emulator observability aligned with the architectural stream seen by AVS.

Rendering Pipeline Strategy Boundary

Canonical v0.4 does not define one mandatory rendering pipeline shape.

Both of these strategies are allowed under the same public contract:

  • immediate-style rendering, where primitives are processed largely in submission order or reordered batches,
  • tile-based rendering, where work is staged through screen-space or intermediate tile groupings before final writeback.

What is fixed is the submission and ownership boundary, not the pipeline style:

  • BCC-led software lowering still produces the executable block stream,
  • the lowered stream still names explicit shader, data-movement, and engine-dispatch work,
  • tiles remain the general inter-engine handoff medium even when the workload is not using a full tile-based rendering strategy,
  • the kernel and command processor still consume explicit Linx work items rather than reinterpreting a higher-level pipeline graph.

This means immediate-style and tile-based bring-up paths may coexist without forking the architectural contract.

First-Acceleration Boundary

The live v0.4 contract intentionally does not freeze the first accelerated rendering stage boundary beyond the existing submission and fallback rules.

Allowed staged bring-up progression includes:

  • BCC-led software scaffolding for setup, assembly, raster, binning, or writeback during early bring-up,
  • VEC kernels for programmable shading and other parallel-loop stages,
  • later migration of justified hot spots into tile-oriented hardened execution that remains compatible with the existing TAU and block/BID contracts.

What is required today:

  • programmable shading and general parallel-loop rendering work must remain valid on VEC,
  • any hardened path must preserve an explicit fallback,
  • stage movement from BCC scaffolding into VEC or TAU-backed execution must remain visible in the block stream and validation evidence.

Tile-Based Strategy Rules

When a rendering stack chooses a tile-based strategy under canonical v0.4, the following rules apply:

  • architectural tiles remain general-purpose intermediate-state storage first, not an ISA-level promise of one fixed screen-space tiling scheme,
  • screen-space tiling is a higher-level rendering strategy built on top of the existing tile register, StateTile, and TMA model,
  • tile-based execution must still be represented as explicit lowered block work, not as a hidden pipeline mode inside the kernel or command processor.

Early Bring-up Shape

The canonical early tile-based bring-up shape is:

  1. BCC-led software logic builds tile lists or equivalent binning structures.
  2. VEC kernels execute programmable tile-local shading or related parallel-loop work.
  3. explicit TMA or .brg visible writeback resolves tile results to global memory.

This staged shape is a bring-up baseline, not a final performance commitment. Later migration of hot paths into VEC kernels or hardened tiler, raster, or ROP-like engines is allowed only if the same explicit block-stream visibility is preserved.

What Is Fixed

For tile-based rendering under v0.4, these points are now frozen:

  • tiles are the canonical inter-engine handoff and working-set carrier,
  • early binning ownership may remain in BCC software scaffolding,
  • programmable tile-local rendering work remains valid on VEC,
  • final memory visibility still occurs only through architecturally visible movement and writeback operations.

What Remains Deferred

Canonical v0.4 still does not freeze:

  • exact screen-space tile dimensions,
  • the final long-term ownership of binning,
  • exact render-pass or subpass flush policy for every workload,
  • MSAA, compression, or advanced depth-format staging beyond the current explicit rendering profile.

Secondary Command Buffers

Canonical v0.4 bring-up does not define a separate on-device interpreter for secondary command buffers.

  • Secondary command buffers MUST be flattened, inlined, or otherwise resolved by software before final queue submission.
  • The submitted block stream MAY retain references to reusable immutable state bundles, but it MUST NOT depend on the kernel or command processor to execute a nested Vulkan command-buffer graph.
  • Multi-threaded recording is a user-mode construction problem. The submitted queue payload remains one explicit executable stream per submission.

Synchronization Contract

Queue synchronization is expressed at block-stream granularity and inherits the existing Linx block/BID completion model.

  • Within one queue submission, architectural ordering points MUST be represented by explicit block or engine synchronization in the lowered stream.
  • A submission-level fence or timeline-semaphore signal MUST become visible only after the terminal required block set for that submission has reached completion under the normal scalar_done && engine_done rule.
  • A timeline-semaphore or queue wait MUST prevent dependent blocks from becoming eligible until the waited value is satisfied.
  • The lowered stream MUST make barrier scopes explicit enough that emulator and kernel validation can determine whether memory-domain and execution-domain ordering requirements were preserved.

This contract intentionally maps API synchronization onto existing Linx block completion semantics rather than inventing a second independent retirement model.

What Is Deferred

The following topics are intentionally outside the frozen v0.4 command contract and may evolve later without changing the rules above:

  • exact Mesa directory layout for the eventual Linx Vulkan driver,
  • presentation-path details for X11, Wayland, or DRM scanout,
  • compressed command encodings behind software lowering, so long as the kernel submission boundary still exposes explicit executable block streams,
  • future hardware packet formats that remain a lossless transport for the same canonical block-stream semantics.

Bring-up Implications

Bring-up and AVS evidence for rendering-adjacent work SHOULD be captured at the lowered-stream boundary:

  • emulator traces should show the executed block stream or its direct decoded form,
  • kernel submission debugging should report block-stream and fence/timeline transitions,
  • driver/runtime conformance checks should validate that no legacy opaque command language has been reintroduced at the public submission boundary.