[API contract] Constrain reinterpret_tile to zero-instruction raw-carrier views

[zhoubot]

Summary

Audit and tighten the existing reinterpret_tile<NewDType>(src) API so it is a
zero-instruction, compiler-only Tile view rather than an implicit architectural
Tile-descriptor mutation.

The API already exists on linx, together with
docs/tileop-usage/reinterpret-tile.md. The current implementation changes the
view's public DType, and downstream Tile operations obtain the PTO datatype
encoding from that new type. This is broader than the currently accepted PTO
architecture contract and is the concrete mismatch reported in
PTO-ISA/pto-spec#162.

This issue requests an API-contract correction and implementation. It does not
authorize weakening the PTO ASL exact-dtype checks to a byte-width comparison.

Why this is needed

The failing pattern is:

// Runtime Tile descriptor after TCVT: BF16.
auto bits = reinterpret_tile<std::uint16_t>(bf16_tile); // emits no instruction

// The current API can make the consumer encode UINT16 even though the
// architectural Tile descriptor is still BF16.
TANDS(..., bits, ...);

// A later numeric consumer expects the original BF16 descriptor.
TMULS(..., bf16_tile, ...);

A zero-instruction C++ expression is not observable by hardware, gfrun, QEMU,
or the PTO ASL model. It therefore cannot silently relabel the architectural
Tile descriptor. Treating every same-width dtype as interchangeable would also
leave numeric interpretation, packed formats, scale-bearing formats, aliases,
definedness, and destination descriptor propagation unspecified.

Proposed API contract

1. reinterpret_tile is a non-owning compiler view

Keep the public spelling:

template <typename ViewDType, TileLike SourceTile>
[[nodiscard]] constexpr auto reinterpret_tile(SourceTile& source);

The returned view MUST:

• emit no PTO instruction, copy, conversion, memory access, or state update;
• reference the same underlying Tile storage and register identity;
• preserve location/role, shape, valid shape, layout, packing, padding,
  compactness, TileSizeCode, and definedness;
• preserve the architectural/runtime backing descriptor dtype;
• reject rvalues so the non-owning view cannot outlive its source;
• remain Local-only until Shared handle and B.IOS binding semantics are
  separately designed.

The view type SHOULD expose both identities explicitly:

using ViewDType = NewDType;                 // compile-time API view
using BackingDType = typename Source::DType; // architectural descriptor

Do not represent these two meanings with one unqualified DType that every
consumer interprets as the architectural dtype. Add traits such as
is_reinterpreted_tile_view_v<T>, view_dtype_t<T>, backing_dtype_t<T>, and
an unwrap/accessor for the exact backing Tile as needed by consumers.

2. Compile-time legality

The first supported form MUST require:

• a named Local Tile lvalue;
• registered PTO source and view dtypes;
• equal element bit width;
• identical storage geometry and layout interpretation;
• no change to element count, TileSizeCode, shape, or physical bytes.

Equal bit width alone is not sufficient for all formats. Packed, scale-bearing,
or descriptor-sidecar formats MUST be rejected unless an accepted PTO contract
explicitly places the pair in a storage-compatible raw-carrier class.

Diagnostics MUST distinguish at least:

• unsupported target dtype;
• different element width;
• incompatible storage/layout class;
• Shared Tile not supported;
• consumer does not accept a reinterpret view;
• dangling/rvalue source.

3. Consumers opt in; generic Tile APIs do not

reinterpret_tile MUST NOT automatically make the view legal for every API
that accepts a Tile-shaped type.

Default numeric consumers—including arithmetic, matrix multiply, conversion,
comparison, reduction, and format/scale-sensitive operations—MUST use the
backing architectural dtype and MUST reject a cross-dtype reinterpret view
unless their accepted PTO contract explicitly says otherwise.

Raw-carrier consumers may opt in through a dedicated concept/trait. The initial
candidate family is the raw bitwise logical surface (TAND, TOR, TXOR and
their scalar forms), but the exact whitelist and legal dtype pairs MUST follow
the accepted resolution of PTO-SPEC #162. Do not infer eligibility from equal
width alone.

For an opted-in raw operation:

• ViewDType controls only the API-level raw element grouping that the PTO
  contract explicitly permits;
• BackingDType remains the architectural descriptor identity;
• source shape/layout/definedness come from the backing Tile;
• writing through a view to the same backing Tile preserves its descriptor;
• a separately owned Tile<NewDType> destination is an ordinary NewDType Tile,
  not an implicit descriptor mutation of the source.

If PTO needs an operation that actually changes a live Tile descriptor without
numeric conversion, that must be a separate explicit architectural relabel or
bitcast operation. It is not part of this zero-instruction API.

4. Required API documentation

Update the reinterpret documentation to explain:

• compiler view versus architectural descriptor;
• reinterpret versus TCVT numeric conversion;
• raw-carrier whitelist and rejected numeric consumers;
• lifetime and aliasing;
• supported dtype/layout classes;
• examples that produce no instruction;
• compile-time failure examples;
• the dependency on PTO-SPEC #162 for any expanded consumer surface.

Remove or replace examples that imply a reinterpreted view is automatically
valid for TMATMUL or other numeric operations.

Verification

Add tests that prove:

1. ViewDType changes while BackingDType, storage carrier, shape, layout,
   TileSizeCode, identity, and bytes remain unchanged.
2. Constructing the view emits no instruction in optimized target output.
3. The accepted raw-carrier example emits exactly the intended consumer bundle
   and no TCVT, copy, memory transfer, or hidden relabel operation.
4. Numeric consumers reject cross-dtype views at compile time with actionable
   diagnostics.
5. Different-width, unregistered, incompatible packed/scale-bearing, Shared,
   and rvalue sources fail at compile time.
6. Aliased source/view access preserves one backing descriptor and has a
   deterministic lifetime contract.
7. CPU-sim/host compilation and Linx target compilation agree on the type
   traits and negative gates.
8. After PTO-SPEC #162 is accepted, one cross-model test uses the same compiled
   consumer in gfrun and QEMU without weakening ASL dtype legality.

Acceptance criteria

• The API exposes compiler view dtype and architectural backing dtype as
  distinct concepts.
• A zero-instruction reinterpret cannot silently change runtime descriptor
  state.
• Generic numeric operations cannot consume a cross-dtype view accidentally.
• Raw-carrier consumers use an explicit, reviewable opt-in contract.
• Documentation and positive/negative compilation tests match the contract.
• Target disassembly proves zero additional instructions for view creation.
• The issue/implementation links PTO-SPEC #162 and does not claim broader ISA
  legality before that architecture decision is accepted.

Existing implementation context

• Current header implementation: include/common/pto_tile.hpp
• Current documentation: docs/tileop-usage/reinterpret-tile.md
• Related open implementation history: Feat/v058 reinterpret cmpmode backfill #15
• Architecture decision owner:
  PTO-ISA/pto-spec#162

[VV0003]

Thanks for opening this issue. We would like to clarify the original purpose of reinterpret_tile<NewDType>(src).

The intended semantics were:

• do not modify the Tile payload;
• do not perform a numeric conversion;
• do not copy or move the Tile;
• do not update the architectural/runtime Tile descriptor;
• keep the same underlying Tile storage and bit pattern;
• provide a compile-time view so that a specific TileOP which only accepts a particular dtype can consume the same bits.

For example, the intended use was conceptually:

auto raw_bits = reinterpret_tile<uint16_t>(bf16_tile);
// use raw_bits only with an explicitly supported raw/bitwise TileOP

The purpose was not to convert BF16 values to UINT16 values. It was only to allow a supported operation to process the same 16-bit bit pattern using an explicitly defined raw-carrier interpretation.

That said, we agree that the current implementation may expose this view too broadly. The current view changes its public DType to NewDType, while the underlying architectural Tile descriptor remains the source dtype. If generic consumers derive their instruction datatype from the view, the compiler may emit a consumer with UINT16 while the runtime descriptor is still BF16.

Therefore, the intended product-line scope should be aligned per operation family rather than based only on equal element width:

• raw bitwise operations may be candidates for an explicit opt-in;
• arithmetic, conversion, comparison, reduction, matrix, GEMV, and scale-sensitive operations should not implicitly accept cross-dtype reinterpret views;
• packed and scale-bearing formats should remain rejected unless explicitly covered by the PTO contract;
• Shared Tile reinterpretation should remain out of scope until its Shared/B.IOS binding semantics are defined.

The likely implementation direction is to keep reinterpret_tile as a non-owning, zero-instruction compiler view, but distinguish:

ViewDType      -- the compile-time raw view requested by the API
BackingDType   -- the architectural dtype of the underlying Tile descriptor

Generic numeric consumers should use the backing architectural dtype or reject cross-dtype views. Only explicitly approved raw-carrier consumers should be allowed to use ViewDType.

We also agree that the model's exact-dtype checks should not be weakened to byte-width checks as a workaround. The legal consumer set and legal dtype pairs should be aligned with the resolution of PTO-SPEC #162.

In short, the API's original purpose is to preserve the same data bits and make them available to a narrowly defined set of dtype-constrained TileOPs, not to generally relabel a Tile or make every same-width dtype interchangeable.