Skip to main content

ADR-0034: CUBE raw-carrier totality and composite preflight

Inventory counts in this record are acceptance-time historical context; the current inventory is owned by the ASL tree and its generated projections.

  • Date: 2026-07-30
  • Requirements: PTO-REQ-CUBE-001, PTO-REQ-TILE-LEGALITY-001, PTO-REQ-PROFILE-001

Context​

PTO accepts 13 direct CUBE functions covering matrix multiply, bias, accumulation, MX row/column scaling, accumulator conversion, and the analogous matrix-vector forms. The model had executable helpers, but Stage 4 lacked a complete type/layout rule, decoded effect evidence for every selector, and a single preflight boundary for composite operations.

The numeric hooks intentionally receive source and destination type metadata. Their hardware-accurate floating, saturation, rounding, accumulation-width, and exceptional-value behavior is a conformance obligation, not something the portable reference can infer from raw 64-bit payload carriers.

Decision​

PTO-v0 type and placement rule​

PTO-v0 accepts all 25 architectural TileDataType values for every CUBE operand and permits mixed source, scale, bias, accumulator, and destination types. The reference profile passes raw XLEN carriers and all operand types to the named matrix profile hooks. This defines deterministic reference behavior without claiming target numeric equivalence; target-specific numeric results remain open under S5-T2.

Row-major and column-major descriptors may be mixed because CUBE indexes logical rows and columns through each operand's descriptor. Vector, Matrix, Memory, and Any locations do not change PTO-v0 semantics. As for every generic tile operation, an implementation-defined layout rejects before effects.

Shape and definedness​

Matrix multiply requires left columns to equal right rows and requires the destination valid shape to be exactly left rows by right columns. GEMV adds a single-column vector requirement. Bias accepts scalar, row, column, or full destination broadcast shape. MX row scale is destination-rows by one and column scale is one by destination-columns.

Every source, bias, and scale valid region must be defined before execution. Accumulating forms additionally require a defined destination. ACCCVT requires a defined source and matching configured and valid row/column extents. ACCCVT uses logical coordinates and therefore does not require source and destination layouts or element types to match.

Composite preflight and aliases​

Decoded legality validates every descriptor, source-definedness rule, shape, layout, and accumulate precondition before the first destination write. A failure reports TILE_LEGALITY and preserves the complete destination.

Source payloads are snapshotted before destination writes. Bias and scale descriptors and payloads are also snapshotted before the matrix phase. PTO-v0 therefore permits destination/source, destination/bias, destination/scale, and extra-operand aliases. If scale and bias operands alias one another, each role observes the common pre-instruction value. Multi-stage operations never read a value they wrote earlier through an aliased operand.

Evidence contract​

The canonical tile catalog and CUBE ASL units own the accepted function inventory and raw-carrier/profile boundary. TestCubeDecodedSelectorMatrix executes every accepted selector through decoded dispatch and checks its result. Additional matrices cover all 25 type identities, mixed type/layout/location execution, implementation-defined layout rejection, all 19 reserved function codes, ten representative alias classes, and nine preflight failure roles with complete destination preservation. The alias matrix covers destination-left, destination-right, source-source, bias, both scale roles, extra-source, accumulate, ACCCVT, and GEMV aliases. The preflight matrix covers destination, left, right, bias, both scale roles, accumulator definedness, layout, and shape.

The repository checker derives function/name identity from the canonical tile catalog and release-traceability-readiness.json, and fails closed if the ASL, test entrypoints, or instruction-contract ownership drifts.

Consequences​

  • CUBE reference semantics are total without presenting raw-carrier arithmetic as hardware numeric conformance.
  • Composite helpers cannot partially update a destination before discovering an invalid later bias or scale operand.
  • Alias behavior is snapshot-based and independent of helper call order.
  • Adding a new type, selector, layout class, or numeric profile requires an explicit evidence update.
Last updated on by Kevin Zhou