Descriptor + Ring Field-Table Reference

This is the per-field lookup appendix for laying out a GPSIMD DMA descriptor or al_udma ring register byte-by-byte. Every field is one row: (offset, width, name, semantics, valid values). The narrative — descriptor taxonomy, address-generation math, the DGE builder pipeline, the CCE op model, QoS, cross-die RDMA, completion — lives in the Consolidated Data-Movement + Collectives Reference; the DGE pseudo→real lowering and $S[] micro-op stream live in the DGE Micro-Op Encoding. This page is field rows only.

The al_udma per-engine CSR semantics (engine-global banks, arbiters, rate limiters) are catalogued in the CSR pages control/csr/udma-m2s.md and control/csr/udma-s2m.md (stubs at time of writing); the per-queue ring bank they reference is reproduced in full in section 6 below.

Provenance and confidence

Every row is grounded in a shipped, redistributable artifact read with stock tools, or carried byte-exact from a cited sibling page. Tags per row/table:

• HIGH/OBSERVED — byte/field-exact in a shipped artifact read this pass (a compile-verified ISA header, the al_udma v4 RTL register-definition JSON, the instruction_mapping.json struct→opcode table, or a recovered firmware string).
• HIGH/CARRIED — byte-exact in a cited sibling page; the source artifact (host kbin_dma_desc, the firmware RDMA disasm, the 16-B SDMA BD DWARF) is not in this extraction, so it is reproduced, not re-derived, here.
• MED — strong inference across a cross-gen or cross-layer reconciliation.

Primary artifacts (all under extracted/.../custom_op/c10/include/, absolute paths in the verification log):

Carried byte-exact (DWARF / native-disasm in a cited sibling — not in this extraction): the 16-B SDMA_CME_BD_DESC (C1, §1); the RDMA op8/op9 inst_specific operand layout (C2, §2.4/2.5); the CCE 16-B compute descriptor (C3, §7) including the host kbin_dma_desc_cce_info_t (140 B) and sdma_data_type_size[] table.

Conventions (apply to every table): off = byte offset from the struct/bank start (decimal for structs, hex for register banks). w = width in bytes, or bN for an N-bit packed bitfield, or [hi:lo] for an RTL bit range. Multi-byte scalars are little-endian. Packed C bitfields list LSB-first within the byte. All 64-B words: byte0 = opcode, byte1 = inst_word_len = 0x10 (16 dwords = 64 B). The struct layout is the mariana (NC-v4) reference; ISA_STATIC_ASSERT==64 is identical cayman..maverick for the shared forms (gen map: SUNDA = NC-v2, CAYMAN = NC-v3, MARIANA = NC-v4, MAVERICK = NC-v5).

CORRECTION (catalog size). This catalog covers SIX 64-B descriptor words, not five. DMA_DIRECT2D_XPOSE (opcode 0xbd, tile-geometry-driven) and DMA_GATHER_XPOSE (opcode 0xf1, index-array-driven) are distinct structs with distinct field layouts — confirmed by struct2opcode (H3) mapping ..._DIRECT2D_XPOSE_STRUCT → DMA_TRANSPOSE and ..._GATHER_XPOSE_STRUCT → DMA_GATHER_TRANSPOSE separately, and by two separate shipped headers. They are §2.3 and §2.4 below.

1. The 16-B hardware BD — SDMA_CME_BD_DESC (HIGH/CARRIED — C1)

The atomic ring entry every al_udma SDMA descriptor engine reads. byte_size 0x10 (DWARF dma.hpp:79). The DWARF lives in data_transfer.o, which is not in this extraction → this whole section is CARRIED.

Table 1.0 — SDMA_CME_BD_DESC (16 B)

Table 1.1 — SDMA_DESC_WORD0 (4 B) — DWARF bit layout, bit0 = LSB of the dword

QUIRK (firmware gen-tag repurpose). The firmware dma_data_transfer path packs the length in [15:0] and a 2-bit GENERATION/RING tag in [25:24] = byte3 [1:0] (the DWARF dmb+concatenate positions, not the DWARF ringid at byte3 [7:6]). Build mask &0xFCFF0000. The completion busy-poll matches the same two bits: (comp_BD.byte3 & 0x3). (MED/CARRIED.)

Table 1.2 — SDMA_CME_DESC_WORD1 (4 B) — CME command / CRC controls

Table 1.3a — SDMA_CMETYPE (optype, WORD1[11:9]) · Table 1.3b — SDMAOP (op, WORD1[8:6])

2. The six 64-B TPB DMA instruction words (HIGH/OBSERVED H1 — D4/D5 CARRIED C2)

All ISA_STATIC_ASSERT==64. byte0 = opcode, byte1 = inst_word_len = 0x10. Src/dst start addresses are ADDR8 (8 B, §5.7). The opcode set (Table 4.0): DMAMEMCPY=0xb8, DMA_INDIRECT=0xbb, DMA_TRANSPOSE=0xbd, SB2SB_COLLECTIVE=0xbf, EXTENDED_INST=0xf0, DMA_GATHER_TRANSPOSE=0xf1 — all byte-exact in ..._common.h.

2.1 DIRECT2D / DMAMEMCPY — opcode 0xb8 (HIGH/OBSERVED H1)

aws_neuron_isa_tpb_dma_direct2d.h:24-43, NEURON_ISA_TPB_DMA_DIRECT2D_STRUCT.

Validity (is_valid_dma_memcpy_direct, verbatim from the header comment): valid header + events; valid addr8 src/dst; is_valid_dge_shape_reg on each; shape-reg mode ⇒ num_elem == 0 && step_elem[1] == 0; valid memcpy dtypes; bound-check regs valid vs the addr marker; valid compute_op. Plain-memcpy (no-CCE) enforces byte equality Σ src_num·src_elem == Σ dst_num·dst_elem; the CCE branch (is_valid_dma_cce) instead enforces aligned start addrs/steps for compute_op != NONE.

2.2 INDIRECT1D / DMA_INDIRECT — opcode 0xbb (HIGH/OBSERVED H1)

aws_neuron_isa_tpb_dma_indirect1d.h:23-47, NEURON_ISA_TPB_DMA_INDIRECT1D_STRUCT. 1-D src/dst (single step/num), with two index-vector addresses.

Key vs DIRECT2D: the bound regs at +58/+59 gate the index arrays (addressing is index-driven); the two index addrs (+48 src / +52 dst) let one instruction gather and scatter. Index addrs must lie in SBUF partition 0 (has_dma_indirect_idx_addr_in_sbuf_partition0).

NOTE (index count ≤ 4096). The header's has_dma_indirect_valid_index_count caps each indirect leg at num_elem <= 4096 (waived in shape-from-register mode), not the "128 lanes" of an earlier draft. idx_num_active_channels (the active index channels) is the separate per-lane control checked by check_dma_indirect_indices.

2.3 DIRECT2D_XPOSE / DMA_TRANSPOSE — opcode 0xbd, NC-v3+ (HIGH/OBSERVED H1)

aws_neuron_isa_tpb_dma_direct2d_xpose.h:24-42, NEURON_ISA_TPB_DMA_DIRECT2D_XPOSE_STRUCT. Tile-geometry-driven xbar transpose: no index array; the transpose is described by a static tile (tile_src_rows × tile_src_cols) plus a tile_src_row_step. Identical struct body across cayman/mariana/maverick.

Validity (is_valid_dma_transpose): NC ≥ V3; tile_src_rows == 16; tile-cols/dtype size co-constraint above; in_dtype == out_dtype and 2-B for the transpose proper; dst_start_addr % 32 == 0; dst_step_elem[i] % 32 == 0 || dst_num_elem[i] == 1.

QUIRK (header comment typo). The header annotates out_dtype as // 5 (15). The 5 is a stray width column; out_dtype is a 1-byte DTYPE at offset 15 (src_start_addr immediately follows at 16, and ISA_STATIC_ASSERT==64 holds). Lay it as 1 byte.

GOTCHA (vs GATHER_XPOSE). DIRECT2D_XPOSE has no index field and no idx_num_active_channels; the transpose source is a contiguous 2-D tile. GATHER_XPOSE (§2.4) is the index-array variant. They share an opcode prefix family but not a layout — do not alias them.

2.4 GATHER_XPOSE / DMA_GATHER_TRANSPOSE — opcode 0xf1, NC-v3+ (HIGH/OBSERVED H1)

aws_neuron_isa_tpb_dma_gather_xpose.h:40-59, NEURON_ISA_TPB_DMA_GATHER_XPOSE_STRUCT. Index-array-driven gather-then-xbar-transpose (SW-DGE on the Q7). Note dtype is a DTYPE_PAIR (Table 4.4a) and dst_step_elem_0 is implicit (== sizeof(dtype_hi)).

Constraints (header): 2-B dtype only (dtype_lo == dtype_hi, BF16/FP16); index UINT32 in multiples of 16; gather_dim must be Y (slow axis) initially; dst 32-B aligned (xbar); 16×128 xbar transpose tiles for 2-B dtypes. Use cases: MoE MLP, chunked-prefill attention.

2.5 RDMA_DESC_GEN / EXTENDED op8 — cross-die SBUF→SBUF P2P (HIGH/CARRIED C2; envelope re-verified H1)

The 64-B word is a NEURON_ISA_TPB_EXTENDED_STRUCT (aws_neuron_isa_tpb_extended.h:41-48): header@0, events@4, extended_opcode@12, completion_info@13 (Table 4.7), inst_specific0[18]@14..31, inst_specific1[32]@32..63. op8 (firmware @IRAM 0x161f4) populates the inst_specific region:

Effect: builds, per masked engine, a CME-COPY BD ring copying [src, src+free_dim_bytes] across all 128 SBUF partitions, plus a local sema BD (EVT_SEM.inc(local_sem)) and a remote sema BD (EVT_SEM.inc(remote_sem) routed to the peer). The routing-id fold and the two-semaphore protocol are in the data-movement reference.

2.6 RDMA_DESC_START / EXTENDED op9 (HIGH/CARRIED C2)

Firmware @IRAM 0x1723c. Same EXTENDED_STRUCT envelope; carries no operands.

Effect: consumes/drains the ring op8 built; role-splits TX (M2S TDRTP_inc) vs RX (S2M RDRTP_inc) by PRID parity and doorbells. GEN can be issued early/free; the wait sits on START.

3. The v5 (Maverick / NC-v5) inline forms (HIGH/OBSERVED H1; runtime behavior INFERRED)

v5 supersedes the GENERATE/DIMPUSH/REGWRITE emit by folding the 16-B BD inline. Both structs are shipped in the neuron_maverick_arch_isa headers (copyright comment "NC-v5"), ISA_STATIC_ASSERT==64, and struct2opcode (H3) maps them to DMA_IMMEDIATE / DMA_MEMCPY2.

NOTE. Field layout is HIGH/OBSERVED (shipped header + struct2opcode). The firmware-side runtime semantics of these v5 forms are not exercised in this extraction's firmware image → treat the behavior (not the layout) as INFERRED.

3.1 DMA_IMMEDIATE — opcode 0xba · aws_neuron_isa_tpb_dma_immediate.h:36-46

Each DESCRIPTOR_RAW[16] is laid out as the §1 SDMA_CME_BD_DESC. num_descriptors must be 1/2/3; per-descriptor descN_src chooses immediate (the inline [16]) vs the 4×u32 register set named by descriptor_reg[N] (DMA_DESC_MODE IMMEDIATE=0 / REGISTER=1).

3.2 DMA_MEMCPY2 / DMA_COPY2D — opcode 0xb9 · aws_neuron_isa_tpb_dma_copy2d.h:22-43

GOTCHA (rd_done/wr_done index split). The read-done index sits at +14 (in the header half) and the write-done index at +38 (in the middle, between the src and dst address blocks) — they are not contiguous.

QUIRK (queue_id width). The header comment says "4b queue ID", but the actual C bitfield DMA_FLAGS.queue_id is 3 bits (queue_id:3, common.h). Trust the struct, not the comment — queue id is 0..7.

4. Shared sub-structs (referenced by every word above) (HIGH/OBSERVED H1)

All from ..._common.h (mariana; maverick identical for the shared forms; v5 enums §4.8–4.13 from the maverick header). Packed structs list fields LSB-first within the byte.

Table 4.1 — NEURON_ISA_TPB_HEADER (4 B) · Table 4.2 — NEURON_ISA_TPB_EVENTS (8 B)

The events.semaphore/sem_increment completion fields inside each descriptor (e.g. DIRECT2D +13/+14) are distinct from the EVENTS wait/update pair above: EVENTS gates issue; the descriptor's own semaphore posts completion.

Table 4.0 — NEURON_ISA_TPB_OPCODE (DMA-relevant values) (HIGH/OBSERVED H1)

Table 4.3 — NEURON_ISA_TPB_BOUND_CHECK_REG (1 B, packed)

Validity (has_valid_bound_check_reg): inert iff (bc_enabled==0 && bc_reg==0 && bc_disable_oob_error_notif==0), or armed iff (bc_enabled==1 && is_valid_register_read_with_marker(bc_reg, marker)). A half-set register (enabled but bc_reg==0 with notif on) is invalid.

Table 4.4a — DTYPE_PAIR (1 B) · Table 4.4b — DTYPE enum values (selected)

The 4-bit DTYPE_BASIC used inside DTYPE_PAIR and the wider DTYPE enum share these low values; DTYPE additionally encodes FP4_EXP2=0x10 and the CPTC trellis dtypes 0x19..0x1F (5-bit), which do not fit a DTYPE_PAIR nibble.

Table 4.5 — DGE_COMPUTE_OP (1 B enum) · Table 4.6 — DMA_INDIRECT_FLAGS (1 B, packed)

INDIRECT_DIM: X=0, Y=1, Z=2, W=3 — minor2major (X fastest), the reverse of numpy major2minor. When no shape-reg is used, the indirect dim must be X (only dim).

Table 4.7 — EXT_COMPLETION_INFO (1 B, packed) — extended.h:22-28

Table 4.8 — DMA_ENGINE_CONFIG (1 B) (v5) · DMA_ENGINE_COUNT enum

Table 4.9 — DMA_ADDR_MODE (the 12 v5 addressing modes; addr_mode pair @+12) (HIGH/OBSERVED H1)

addr_mode byte = {src_addr_mode:4 low, dst_addr_mode:4 high} (DMA_ADDR_MODE_PAIR).

Table 4.10 — DMA_SEMA_UPDATE_MODE (per-leg sema/collsync update) (v5; HIGH/OBSERVED H1)

Bit decode: bit0 enabled, bit1 inc/counter, bit2 sem-vs-collsync, bit3 local-vs-remote. sema_update_mode byte @+13 = {rd_done:4 low, wr_done:4 high} (DMA_SEMA_UPDATES).

Table 4.11 — DGE_OPCODE (the @+15 KIND, compiler pseudo only)

QUIRK (offset +15 duality). In a compiler pseudo word (PSEUDO_DMA_DIRECT2D 0xd4) byte +15 is dge_op (DGE_OPCODE 0..3); in the resolved real word (DMAMEMCPY 0xb8) the same byte is compute_op (DGE_COMPUTE_OP 0..4). Two fields, one byte, keyed by byte0 (the opcode).

Table 4.12 — DMA_CONFIGS (1 B, packed) [DIRECT2D +12 / INDIRECT1D +61 / XPOSE +63]

NOTE (two QoS namespaces). This device priority_class is a 3-bit, 5-value field (P0..P4) — the firmware map nrtucode_core_dge_get_priority_class_map@0x9b10f0 bounds the index with if (a3 <= 4). The compiler-side DMAQoSClass is a separate 0..14 enum that the device path saturates down into priority_class (17→5→4 cap). Keep them distinct: a descriptor byte holds priority_class (0..4), never DMAQoSClass.

Table 4.13 — WAIT_MODE (selected) · Table 4.14 — UPDATE_MODE (selected) (HIGH/OBSERVED H1)

CORRECTION. An earlier draft wrote "wait_mode 0x04 = wait ≥ value" and "update_mode 0x13 = inc-on-complete". Per the enum (common.h): 0x04 is WAIT_FOR_SEM_GT_IMM (strictly greater; GE is 0x05), and 0x13 is SEM_INC_COMPLETE (correct). Use 0x05 for "wait ≥".

5. The ADDR8 / ADDR4 marker byte (high byte; mask 0xFC) (HIGH/OBSERVED H1)

ADDR8 is an 8-B union (common.h:603); its high byte is the marker selecting the addressing form. ADDR4 is the 4-B compute-word address (common.h:532).

Table 5a — ADDR8 marker constants (MASK 0xFC) · Table 5b — ADDR4 markers

Bit defs (ADDR8): OFFSET_WIDE = 1<<2, OFFSET_REG = 1<<3, ADDR_TBL = 1<<5, SHAPE_REG = 1<<6, ADDR_REG = 1<<7; MASK = 0xFC. A SHAPE_REG marker selects shape-from-register (runtime-sized) mode: num_elem must be 0 and the index cap is waived. The PSEUDO_ADDR8 union adds addr_var (NEFF variable id) + addr_unknown.

6. The al_udma v4 ring register bank (HIGH/OBSERVED H2)

UnitName UDMA_M2S (AddrWidth 18, SizeInBytes 0x40000) / UDMA_S2M (SizeInBytes 0x38000). Engine-global bundle bases (RegistersBundleArrays AddressOffset, re-verified H2):

Each per-queue bank is at 0x1000 + i*0x1000 (i = 0..15, stride 0x1000). Offsets below are relative to the bank base; an absolute address is 0x1000 + i*0x1000 + off.

The two doorbells. TDRTP_inc (TX/M2S) and RDRTP_inc (RX/S2M) are both at bank +0x38 → absolute 0x1038 for queue 0. Each has a single field val[23:0] (24-bit, VAL_MASK 0xffffff): writing N increments the tail by N descriptors = the launch.

6.1 M2S_Q[i] — 39 registers (al_udma_m2s_regs.json) (HIGH/OBSERVED H2, count = 39)

Table 6.1a — M2S cfg (+0x20) bitfields (HIGH/OBSERVED H2)

CORRECTION (vs earlier cfg notes). Per the RTL JSON: en_pref[16] + en_scheduling[17] are the enable bits; force_full_line is bit 18 (not 31); AXI_qos is [31:28] (4-bit, reset 0xe), not [30:28]. This wire QoS is the 4-bit AXI value; the descriptor's 0..4 priority_class (§4.12) feeds it via the QoS map.

6.2 S2M_Q[i] — 36 registers (al_udma_s2m_regs.json) (HIGH/OBSERVED H2, count = 36)

Byte-for-byte the M2S ring renamed TDR→RDR / TCR→RCR, with S2M-specific completion + packet-handler regs and no DWRR / no rate-limiter (RX is QoS-tagged, not bandwidth-shaped).

Table 6.2a — S2M cfg (+0x20) bitfields (HIGH/OBSERVED H2)

CORRECTION (S2M en_comp_ring_update reset — engine-asymmetric). The reset is not the same on both engines. The RTL JSON gives udma_s2m.json: comp_cfg@0x54.en_comp_ring_update ResetValue 0x1 (ON) and udma_m2s.json: comp_cfg@0xa0.en_comp_ring_update ResetValue 0x0 (OFF) — verified on both the Cayman (NC-v3) and Mariana (NC-v4) register JSON. So S2M defaults the completion-ring write-back ON, M2S OFF. (A prior reconciliation draft of this page mistakenly "corrected" the S2M reset to 0 for both engines — that claim was wrong and is retracted here.) The companion S2M-only defaults still hold: dis_comp_coal rst 1, first_pkt_promotion rst 1, buf2_len_location rst 1, desc_size rst 4 — none of which exist on M2S.

CORRECTION (S2M append-register names). The three append registers are append_orig_addr_low@0xe0, append_orig_addr_high@0xe4, append_orig_len@0xe8, append_status@0xec (RTL names), and the 36th register is force_target_q_mapping@0x124 — earlier drafts ended at gdma_pref@0x120 and mis-named the len/status pair append_orig_addr_len/append_orig_addr_status.

NOTE (cross-gen size). The register JSON is the maverick (NC-v5) udma_v4 IP: M2S SizeInBytes 0x40000, S2M 0x38000, AddrWidth 18. Cayman (NC-v3) shipped a smaller M2S window (0x20000); the per-queue offsets above are identical, only the unit envelope and the tail-set register family (cayman TDRDTP_inc@0xe0 vs maverick TDRTP_set@0xd4) differ. (MED, cross-gen.)

7. The CCE compute-descriptor extension (HIGH/CARRIED — C3)

A CCE transfer is the same 16-B SDMA_CME_BD_DESC ring entry with the meta-control word set (SDMAOP.op = CCE = 4). The CDMA channel reads N source streams off M2S, applies a per-element ALU op in flight, and writes the single reduced/scaled result down S2M. The byte layout of the M2S compute descriptor and the host-side kbin_dma_desc_cce_info_t are not in this extraction (no kbin_dma_desc symbol, no sdma_data_type_size table here) → this whole section is CARRIED from the host/firmware analysis.

Table 7.0 — CCE 16-B M2S compute descriptor (W0..W3, overlays SDMA_CME_BD_DESC)

Table 7.1 — the META-CTRL word (al_sdma_m2s_build_*_meta_ctrl)

Table 7.2 — SDMA_CCETYPE (the device CCE op enum) (HIGH/CARRIED — C3)

(kbin COPY=0/TRANSPOSE=5 are not CCE ops.)

Table 7.3 — CCE operand selectors (W2 nibbles) (HIGH/CARRIED — C3)

scale_dtype must be FP32; one FP32 W3 per per-source descriptor (per-rank, not per-element). Optional stochastic-rounding sub-descriptor 0x6000000 on down-convert.

Table 7.4 — host kbin_dma_desc_cce_info_t (140 B) (HIGH/CARRIED — C3)

GOTCHA (sdma_data_type_size[fp32r] == 0). The device size table reports 0 bytes for FP32R (0xB), not 4. A reimplementer computing reduce-packet size as dtype_size * N must special-case FP32R (it is a partial-fp32 accumulation format that the size table deliberately zeroes); otherwise the packet-size and stride math collapses.

CCE vs plain COPY — the minimal delta on the same 16-B BD / ring / doorbell:

CCE limits: max elements v2→1024, v3/v4→2048; reduce packet size = min(dtype_size·N, cc_cce_reduce_prio_pkt_size[priority_class]) & ~0x1F (32-B-granular priority cap).

Firmware grounding (H4)

The descriptor builder that emits these words is the SW-DGE in libnrtucode_internal.so. Its recovered emit strings (verbatim) confirm the field model end-to-end:

S: push GENERATE to DMA[%d]: %s : addr=0x%llx, elem_size=%d, sem_num=%i
S: push DIMPUSH to DMA[%d]: [%u,%u][%d,%d]
S: push REGWRITE to DMA[%d]
S: DGE $S[%i]+=%i@dmacomplete src=[0x%x]@0x%llx[0x%x,0x%x][%u,%u]
       dst=[0x%x]@0x%llx[0x%x,0x%x][%u,%u] cast:0x%x->0x%x
       bounds:(%1d 0x%llx<=0x%llx, %1d 0x%llx<=0x%llx) compute_op: 0x%x

The $S[] template maps one-to-one onto the §2.1 field layout: [%u,%u] = num_elem X/Y, [%d,%d]/[0x%x,0x%x] = step_elem X/Y, cast:0x%x->0x%x = in_dtype→out_dtype, bounds:(...) = the two BOUND_CHECK_REGs, compute_op: 0x%x = the DGE_COMPUTE_OP.