IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /get-started.md). For the complete documentation index, see llms.txt.
Skip to main content
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.

Was this page helpful?