For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).
Mojo struct
TDMDescriptor
struct TDMDescriptor
A gfx1250 TDM descriptor: groups 0 and 1 of the 20-dword structure.
Groups 2 and 3 describe dimensions 2-4 with their strides and tile extents, none of which a 2D dense transfer uses; the instruction wrappers issue them as zeros and no storage is kept for them. Keep the descriptor in uniform (SGPR) registers: the TDM instructions require a wave-uniform descriptor and the hardware does not broadcast a divergent one.
Fields
- d0 (
SIMD[.int32, 4]): Group 0: the count field, the LDS byte address, the global address, and the descriptor type. - d1 (
SIMD[.int32, 8]): Group 1: the workgroup multicast mask, element size, padding fields, tensor extents, tile box extents, and the dim-1 row stride.
Implemented traits
AnyType,
Copyable,
Deinitable,
ImplicitlyCopyable,
Movable,
RegisterPassable,
TrivialRegisterPassable
Methods
make_2d
static def make_2d[dtype: DType, tile_dim0: Int, tile_dim1: Int, *, pad_interval_bytes: Int = Int(0), pad_amount_bytes: Int = Int(0), multicast_mask: Int = Int(0)](global_addr: Int64, lds_addr: Int32, tensor_dim0: Int32, tensor_dim1: Int32, dim1_stride: Int64) -> Self
Builds a 2D load or store descriptor for a box of tile_dim0 by tile_dim1 elements.
Dim 0 is the fastest-varying dimension with an implicit stride of one
element; dim1_stride is the pitch of dim 1 in elements. The extents
are what remains of the global tensor from the box origin, so the
hardware clamps each dimension against them and zero-fills the
out-of-bounds tail, which is how a TDM tile load handles ragged M/N/K. A
zero extent masks the whole dimension.
Both extents must be non-negative. They are packed as 16-bit halves of a
two's-complement value, so a negative remaining extent reads back as an
extent near 2^32, which the hardware clamps nothing against and the
transfer then runs past the end of the tensor. Where an extent is
computed as a difference, the caller clamps it to zero before the call;
with_extents deliberately does not, because it runs once per TDM
issue and its instruction count is budgeted.
Padding makes the LDS write pattern physical offset
dense + (dense / pad_interval_bytes) * pad_amount_bytes, applied to
the dense byte stream starting at lds_addr. Valid intervals are powers
of two in 8..1024 that are multiples of 4; valid amounts are in 4..512
and a multiple of 4. TDM has no XOR swizzle, so padding is the only way
to avoid LDS bank conflicts on the read side.
Constraints:
tile_dim0 and tile_dim1 must be in 1..65535, the padding values
must be in the ranges above, pad_amount_bytes requires a nonzero
pad_interval_bytes, both extents must be non-negative,
dim1_stride must fit in 48 bits, and multicast_mask must fit in
16 bits with at most five of them set.
Parameters:
- dtype (
DType): The element type of the transfer. - tile_dim0 (
Int): Extent of the box along dim 0, in elements. - tile_dim1 (
Int): Extent of the box along dim 1, in elements. - pad_interval_bytes (
Int): LDS padding interval in bytes (defaults to 0, which disables padding). - pad_amount_bytes (
Int): LDS padding amount in bytes (defaults to 0, which disables padding). - multicast_mask (
Int): 16-bit multicast mask, one bit per cluster rank of the workgroups that receive this transfer (defaults to 0, which means no multicast). AMD's published guidance on the instruction says the mask must include the requesting workgroup and may name at most five destinations; neither rule is in an ISA description, so only the 16-bit width and the five-destination bound are asserted here.
Args:
- global_addr (
Int64): Byte address of the box origin in global memory. - lds_addr (
Int32): LDS byte offset of the transfer's LDS end. Only its low 32 bits reach the descriptor, and a negative offset is not rejected. - tensor_dim0 (
Int32): Remaining extent of dim 0, in elements. Must be non-negative. - tensor_dim1 (
Int32): Remaining extent of dim 1, in elements. Must be non-negative. - dim1_stride (
Int64): Pitch of dim 1, in elements, in [0, 2^48). It is packed into 48 bits and is not checked here, because any runtime check would sit in every kernel that builds a descriptor; the bits above 48 are dropped.
Returns:
Self: The packed descriptor.
with_addr
def with_addr(self, global_addr: Int64, lds_addr: Int32) -> Self
Returns a copy of this descriptor aimed at a new global and LDS address.
Everything else, including a cleared count field, is carried over.
Args:
- global_addr (
Int64): Byte address of the box origin in global memory. - lds_addr (
Int32): LDS byte offset of the transfer's LDS end. Only its low 32 bits reach the descriptor, and a negative offset is not rejected.
Returns:
Self: The re-addressed descriptor.
with_extents
def with_extents(self, tensor_dim0: Int32, tensor_dim1: Int32) -> Self
Returns a copy of this descriptor with new remaining extents.
Everything else, including the tile box, the padding fields and the count field, is carried over.
Args:
- tensor_dim0 (
Int32): Remaining extent of dim 0, in elements. Must be non-negative. - tensor_dim1 (
Int32): Remaining extent of dim 1, in elements. Must be non-negative.
Returns:
Self: The re-extended descriptor.
disabled
def disabled(self) -> Self
Returns a copy of this descriptor with a cleared count field.
A count-0 descriptor transfers nothing, which is how a pipeline turns the last prefetch of a loop into a no-op without branching. Whether the hardware counts such a copy against TENSORcnt, and how long it takes to release it, is unverified, so a pipeline that issues one should wait for the counter to reach zero rather than for a specific count.
Returns:
Self: The disabled descriptor.