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 package

atoms

Defines atoms: wrappers for single hardware intrinsics as typed operations on TileTensor operands.

An atom issues one instruction and describes its operands so that code above it can check and arrange them. Each operand has an engine, the kind of storage it lives in, and an OperandMap: the part of the instruction's index map that the hardware fixes, from index bits to address bits in the operand's AddressEncoding. The index bits encode one element of one issue as the threads that issue it see it: bits from INDEX_VALUE pick the element within one thread's part, bits from INDEX_LANE the thread within its warp, and bits from INDEX_WARP the warp.

An operand map says nothing about the tensor in that storage. A tensor's layout places logical coordinates at addresses; combining that placement with an atom's maps gives the fragment each thread holds, and is the work of the libraries built on top. Index bits a map leaves out are free: the caller's addresses decide where they go, as long as they keep clear of the map's avoid bits.

Orchestration is not an atom's job: tiling operands into issues, choosing which threads issue, partitioning tiles among them, and waiting on asynchronous instructions belong to the libraries built on top. An atom only advertises how its results complete, through its Completion type, which wraps the wait instructions of the atom's instruction family and is one of:

  • Synchronous: the results are ready when the call returns.
  • A BarrierCompletion: the atom is built with a caller's barrier, such as an mbarrier for a TMA load, and the instruction signals it; anyone can wait on the barrier.
  • A HandleCompletion: the instruction produces a handle, such as a DMA id, which the call returns as its Result; the target's wait instruction takes it.
  • A CounterCompletion: the family's wait instruction is tied to the instruction type rather than to one call, such as tcgen05.wait::ld or cp.async.wait_group, and waits for all of this thread's outstanding issues or all but a given number.
  • A BatchCompletion: issues join a batch the caller opens, without naming it; the caller commits the batch and waits on it, as with cp.async.bulk.commit_group and cp.async.bulk.wait_group.

An instruction family shares one completion type, so code that waits can tell which issues one wait covers.

Operand dtypes and engines are checked rather than pinned in signatures. A view's engine is its parent's OffsetResultType, and an atom's associated dtype reached through a generic parameter does not fold to the struct parameter that set it, so pinning either would reject valid operands in generic code.

Each instruction family is a submodule: layout.atoms.pointer for plain pointer loads and stores, layout.atoms.cp_async for cp.async, layout.atoms.b200.cp_async for the B200 bulk copy cp.async.bulk, and layout.atoms.tmem for Blackwell Tensor Memory.

You can import these APIs from the layout.atoms package:

from layout.atoms import CastAtom, LoadAtom, MmaAtom, StoreAtom, TransferAtom
from layout.atoms import OperandMap, Synchronous, same_engine
from layout.atoms import AddressEncoding, registers_map, vector_map

comptime values​

INDEX_LANE​

comptime INDEX_LANE = 32

The lowest index bit that picks the thread within its warp.

INDEX_VALUE​

comptime INDEX_VALUE = 0

The lowest index bit that picks an element within one thread's part.

INDEX_WARP​

comptime INDEX_WARP = 38

The lowest index bit that picks the warp, leaving room for 64-lane AMD wavefronts.

TMEM_COLUMN​

comptime TMEM_COLUMN = 0

The lowest TMEM address bit that picks a column.

TMEM_LANE​

comptime TMEM_LANE = 16

The lowest TMEM address bit that picks a lane.

Packages​

  • ​b200: Defines atoms for instructions specific to NVIDIA B200 GPUs.

Modules​

  • ​cp_async: Defines the transfer atom for NVIDIA's cp.async global-to-shared copy.
  • ​pointer: Defines atoms for plain pointer loads and stores.
  • ​tmem: Defines layout atoms for Blackwell Tensor Memory (TMEM).

Structs​

  • ​AddressEncoding: How an operand's address bits encode a location in its storage.
  • ​OperandMap: The part of an instruction's index map the hardware fixes for one operand.
  • ​Synchronous: The results are ready when the call returns.

Traits​

  • ​Atom: Wraps one hardware intrinsic issued on TileTensor operands.
  • ​AtomCompletion: Advertises how an instruction family's results complete.
  • ​BarrierCompletion: The atom is built with a caller's barrier, and the instruction signals it when its results are ready; anyone can wait on the barrier.
  • ​BatchCompletion: Issues join the batch the caller opened, without naming it; the caller commits the batch and waits on it.
  • ​CastAtom: Describes an instruction that converts elements from a source element type to a destination element type.
  • ​CounterCompletion: The family's wait instruction is tied to the instruction type, not to a call: it waits until at most a given number of this thread's issues of the family are outstanding.
  • ​HandleCompletion: The instruction produces a handle, which the call returns as its Result; the target's wait instruction takes it.
  • ​LoadAtom: Describes an instruction that loads elements from memory into registers.
  • ​MmaAtom: Describes a matrix multiply-accumulate instruction, C += A @ B.
  • ​StoreAtom: Describes an instruction that stores elements from registers into memory.
  • ​TransferAtom: Describes an instruction that moves elements from memory to memory, such as a DMA submit or cp.async.bulk, without passing through the issuer's registers.

Functions​

  • ​registers_map: Returns a register operand: value v of lane l is register v of thread l.
  • ​same_engine: Returns whether two engines are one engine family.
  • ​vector_map: Returns a memory operand of a per-lane vector access: value v is v * element_bytes bytes past the address the lane supplies.

Was this page helpful?