System descriptor field guide

A system descriptor records CPU targets, chip resources, and chip connectivity. The compiler represents it as #ttcore.system_desc; a standalone .ttsys file stores a SystemDescRoot FlatBuffer containing a SystemDesc. For obtaining or inspecting a descriptor, see TTRT query and TTRT read. The device attribute describes a compiler view over this system, including a mesh shape and selected chips.

The tables below use the FlatBuffer field names. In textual MLIR, grid_size is named grid and dram_grid_size is named dram_grid. Two-dimensional sizes and coordinates are ordered y, x (rows, columns for sizes). Memory sizes, addresses, and alignment values are in bytes, unless stated otherwise.

SystemDesc

Field	Meaning
cpu_descs	CPU target descriptions. Each entry contains role (Host or Device) and an LLVM target_triple string. The runtime producer currently emits one Host entry using its build’s TARGET_TRIPLE.
chip_descs	Chip resource descriptions; see ChipDesc. This array is addressed through chip_desc_indices.
chip_desc_indices	Maps a chip’s position in the system descriptor to an index in chip_descs. These values are descriptor indices, not TT-Metal device IDs.
chip_capabilities	Per-chip capability bit masks. HostMMIO indicates host MMIO capability; the runtime sets it from is_mmio_capable(), otherwise it emits no capability bits.
chip_coords	Chip placement records with fields rack, shelf, y, and x. The current runtime emits only one placeholder (0, 0, 0, 0), even for multiple chips. Do not interpret that output as a measured topology or assume one coordinate record per chip.
chip_channels	Ethernet connections, each described by two device IDs and their Ethernet core coordinates; see ChipChannel. This list is optional in the MLIR assembly format.

In textual MLIR, the lists in #ttcore.system_desc are positional, in the order shown above; the final channel list may be omitted.

Chip indices versus device IDs

For a chip position i, SystemDescAttr::getChipDesc(i) performs:

chip_descs[chip_desc_indices[i]]

Both array accesses must be in range. The indirection permits chips to share a descriptor; it does not require producers to deduplicate descriptors. The current runtime sorts the queried devices by TT-Metal device ID, appends one ChipDesc per device, and writes chip_desc_indices = [0, 1, ...].

For example, if the queried devices have IDs 4 and 7, their chip positions are 0 and 1, and the runtime emits descriptor indices [0, 1], not [4, 7]. Looking up the second chip uses getChipDesc(1). Ethernet channel endpoints still use device IDs 4 and 7. A hypothetical deduplicating producer could instead store one shared descriptor with indices [0, 0]; this illustrates the mapping, not the current runtime output.

The chipIds in the compiler’s device attribute refer to chip indices in the system descriptor. Do not substitute channel endpoint IDs for these indices. The distinction motivated the correction discussed in PR #3758.

ChipDesc

Field	Meaning and current runtime source
arch	Chip architecture: Wormhole_b0, Blackhole, or Quasar in the FlatBuffer schema, obtained from device->arch().
grid_size (grid in MLIR)	Compute-with-storage worker grid dimensions, from compute_with_storage_grid_size(). This is a worker grid, not the mesh shape of multiple chips or a list of every physical core on the chip.
coord_translation_offsets	Translated NoC0 coordinate of logical worker (0, 0): the producer calls worker_core_from_logical_core({0, 0}), then virtual_noc0_coordinate(0, workerNWCorner), and stores the result in y, x order. This pair is not a full per-core coordinate mapping.
l1_size	L1 capacity per core, from l1_size_per_core(). It includes the region below l1_unreserved_base.
num_dram_channels	Number of DRAM channels, from num_dram_channels().
dram_channel_size	DRAM capacity per channel, from dram_size_per_channel(), rather than total chip DRAM capacity.
noc_l1_address_align_bytes	NoC L1 address alignment, from HAL get_l1_alignment().
pcie_address_align_bytes	PCIe address alignment, from HAL get_pcie_alignment().
noc_dram_address_align_bytes	NoC DRAM address alignment, from HAL get_dram_alignment().
l1_unreserved_base	Start of the L1 region available to the allocator, from get_base_allocator_addr(HalMemType::L1). getUsableL1Size() subtracts this address from l1_size.
erisc_l1_unreserved_base	Unreserved Ethernet RISC L1 base, from HAL get_erisc_l1_unreserved_base(). This is separate from the worker L1 base.
dram_unreserved_base	Start of the allocator’s unreserved DRAM region, from get_base_allocator_addr(HalMemType::DRAM).
dram_unreserved_end	Exclusive upper bound of the compiler-usable DRAM region per channel. calculateDRAMUnreservedEnd() conservatively reserves space for kernel programs at the top of DRAM and rounds the remaining end address down to the allocator’s DRAM alignment. This is a calculated bound, not a free-memory measurement.
supported_data_types	Data types advertised by the descriptor. The runtime currently uses explicit lists, including a separate Quasar list, rather than querying support for each type. This is not a promise that every operation supports every listed type.
supported_tile_sizes	Advertised Tensix tile shapes in y, x order. The runtime currently uses the fixed list (4, 16), (16, 16), (32, 16), (4, 32), (16, 32), (32, 32).
dst_physical_size_tiles	Physical destination-register capacity expressed in tiles; currently set to 16 by the runtime producer. The compiler’s logical tile capacity can be smaller: getDstLogicalSizeTiles() halves it when full synchronization is disabled and halves it again for 32-bit data types.
num_cbs	Number of circular buffers, taken from TT-Metal’s NUM_CIRCULAR_BUFFERS constant.
num_compute_threads	Compute-thread count recorded for a worker. The runtime sets 1 for Wormhole/Blackhole and 4 for Quasar.
num_datamovement_threads	Programmable data-movement-thread count recorded for a worker. The runtime sets 2 for Wormhole/Blackhole and 6 for Quasar; its Quasar comment distinguishes 6 programmable from 8 physical DM cores.
dram_grid_size (dram_grid in MLIR)	DRAM grid dimensions from dram_grid_size(), in y, x order.
dram_bank_to_logical_worker_noc0	DRAM-bank-indexed logical worker coordinates returned by get_optimal_dram_bank_to_logical_worker_assignment(NOC_0). The runtime skips this query for Quasar and emits an empty list.
dram_bank_to_logical_worker_noc1	Corresponding bank-to-logical-worker assignment for NOC_1; also empty in the current Quasar runtime output.

The compiler computes usable DRAM bytes per channel as dram_unreserved_end - dram_unreserved_base. Neither this value nor l1_size - l1_unreserved_base reports how much memory is currently free after allocations.

ChipChannel

Field	Meaning
device_id0	TT-Metal device ID of the first endpoint.
ethernet_core_coord0	First endpoint’s Ethernet core coordinate, serialized in y, x order.
device_id1	TT-Metal device ID of the second endpoint.
ethernet_core_coord1	Second endpoint’s Ethernet core coordinate, serialized in y, x order.

The runtime’s getAllDeviceConnections() uses active Ethernet cores and get_connected_ethernet_core(). It orders endpoints by device ID and deduplicates the resulting connections. Connections whose lookup throws are skipped, so the list should not be treated as a complete inventory of all external connections. The coordinates come from those TT-Metal Ethernet APIs; they are not worker-grid indices or chip placement coordinates.

SystemDescRoot (.ttsys envelope)

Field	Meaning
version	TT-MLIR producer version, with major, minor, and patch components.
schema_hash	Generated system-descriptor FlatBuffer schema hash.
ttmlir_git_hash	Producer’s TT-MLIR Git revision string.
product_identifier	Product identifier string; the current runtime writes the placeholder "unknown".
system_desc	The SystemDesc payload described above.

The standalone format is a size-prefixed FlatBuffer with file identifier TTSY and extension .ttsys. The envelope metadata is separate from the fields of the compiler’s #ttcore.system_desc attribute.

Queried descriptors and compiler defaults

A runtime query obtains resource values from the opened mesh’s devices, HAL, and allocators, but it also includes the fixed values and placeholders noted above. In particular, chip_coords and product_identifier do not identify the actual physical installation.

SystemDescAttr::getDefault() instead constructs architecture-specific defaults in the compiler. These are not a hardware query. For multiple chips, the current default builders assume a ring topology with (0, 0) Ethernet core coordinates. Use the producer and provenance of a descriptor when interpreting its values; do not treat default or placeholder topology as discovered connectivity.

Source reference

The field definitions and the producer/consumer behavior described here are in:

• FlatBuffer resource types and standalone root.

• TTCore attribute definitions and assembly formats.

• Runtime descriptor producer, including getCurrentSystemDescImpl(), getCoordinateTranslationOffsets(), calculateDRAMUnreservedEnd(), and getAllDeviceConnections().

• Compiler defaults, FlatBuffer reader, and chip lookup.

• MLIR-to-FlatBuffer serialization.