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 itsResult; 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 astcgen05.wait::ldorcp.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 withcp.async.bulk.commit_groupandcp.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_mapcomptime 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'scp.asyncglobal-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 onTileTensoroperands. -
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 itsResult; 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 orcp.async.bulk, without passing through the issuer's registers.
Functions
-
registers_map: Returns a register operand: valuevof lanelis registervof threadl. -
same_engine: Returns whether two engines are one engine family. -
vector_map: Returns a memory operand of a per-lane vector access: valuevisv * element_bytesbytes past the address the lane supplies.