The Opcode Catalog Ledger (140 real opcodes)

This page is the index and completeness check for the entire GPSIMD kernels cluster. It answers one question definitively: of the GPSIMD NEURON_ISA_TPB opcode space, how many are real hardware kernels, what is each one called, and which generation ships it?

The headline, derived byte-exact below:

172 union enum values − 31 PSEUDO (NRT-translated) − 1 INVALID = 140 real HW opcodes, every one named from the shipped common.h enums and struct-decoded through the firmware. This count is the union across the four shipped-generation NEURON_ISA_TPB_OPCODE enums (SUNDA / CAYMAN / MARIANA / MAVERICK), not the per-image active subset.

The page crosses three independent dispatch sources to prove this is the right boundary:

1. the four shipped common.h NEURON_ISA_TPB_OPCODE enums — the authoritative roster (172 union values, the 140 after subtraction);
2. the per-image kernel_info_table — the 17-entry POOL compute back-end active in one shipped image (CAYMAN_Q7_POOL_PERF_EXTISA_0);
3. the SEQ ASCII dispatch hub — the 178-slot front-end fetch table (55 real handlers / 123 default fills).

These three counts (140, 17, 55) differ by construction; §3 explains exactly why and which opcodes appear in which source.

Confidence tags follow the Confidence & Walls Model: OBSERVED = a byte / string read from the shipped image this session; INFERRED = reasoned over OBSERVED facts; CARRIED = consolidated from a cited cross-page anchor at its original confidence. The recovered common.h enums, firmware log strings, and ELF section bytes are binary-derived facts and are cited as such throughout.

Generation byte-confidence: v2 (SUNDA) / v3 (CAYMAN) / v4 (MARIANA) / v4+ (MARIANA_PLUS) are byte-grounded [HIGH/OBSERVED]; v5 (MAVERICK) is header-OBSERVED only for several late ops (enum names read; device body FLIX-desynced) → those rows are [INFERRED]. The per-gen device-body depth tail is flagged MED honestly in §4 and §5.

1. The 172 − 31 − 1 = 140 derivation (grounded)

1.1 The roster — four enums, one union

Each shipped generation ships exactly one typedef enum NEURON_ISA_TPB_OPCODE { … } block in its aws_neuron_isa_tpb_common.h. Re-parsed this session from all four headers under

extracted/aws-neuronx-gpsimd-customop-lib_0.21.2.0_amd64/opt/aws/neuron/gpsimd/
  custom_op/c10/include/neuron_{sunda,cayman,mariana,maverick}_arch_isa/tpb/
  aws_neuron_isa_tpb_common.h

with the regex NEURON_ISA_TPB_OPCODE_(\w+)\s*=\s*(0x..) and the trailing // Y / // n flag capture:

The chain is a strict superset for the shared band (sunda ⊂ cayman ⊂ mariana ⊂ maverick), plus a small set of SUNDA-exclusive ops the later gens dropped (the BF16 cluster 0x8A–0x8F, the dual-ptr pair 0x87/0x88). Zero opcode value maps to two different names across gens — re-checked this session; the union is therefore unambiguous. [HIGH/OBSERVED]

NOTE — counts grounded. rg -c 'NEURON_ISA_TPB_OPCODE_\w+\s*=\s*0x' returns 145 / 150 / 159 / 165 per header (SUNDA/CAYMAN/MARIANA/MAVERICK); the Python union over the four parsed dicts yields 172 distinct values. M+ (MARIANA_PLUS) reuses the MARIANA enum (the kernel_info_table key set is byte-identical, sha 9f2ce049), so it is folded into the MARIANA roster.

1.2 The 31 PSEUDO opcodes subtracted (0xC1–0xDF)

The contiguous band 0xC1–0xDF (upper three bits 0b110) is 31 PSEUDO opcodes. The enum names them all NEURON_ISA_TPB_OPCODE_PSEUDO_*, and the maverick header carries the governing FIXME comment directly on the first pseudo entry:

"currently NRT relies on the fact that all pseudo instructions have upper three bits of the opcode equal to 0b110. Pseudo instructions are generated by compiler and translated into non-pseudo HW instructions by NRT."

These are compiler-emitted scheduling/marshalling tokens that NRT lowers into the real HW ops before the stream reaches the device. The GPSIMD device firmware never decodes them; they have no dispatch surface (no SEQ slot, no kernel_info_table row). All 31 (verified this session: every 0xC1–0xDF entry is named PSEUDO_*, none escapes the band):

[HIGH/OBSERVED — band re-parsed; FIXME comment read from maverick header.]

GOTCHA — pseudo vs. real namesakes. Several pseudo names collide with real-op names (0xCA PSEUDO_EMBEDDING_UPDATE vs. real 0x79 EMBEDDING_UPDATE; 0xCD/0xCE PSEUDO_TENSOR_STORE/LOAD vs. real 0xAB/0xAA; 0xDD PSEUDO_BRANCH_PREFETCH_HINT vs. real 0xB5). The pseudo is the compiler-side token; the real op is the device-decoded instruction. They are distinct opcode bytes and distinct enum entries. Do not conflate them.

1.3 The 1 INVALID subtracted (0xFF)

NEURON_ISA_TPB_OPCODE_INVALID = 0xFF is a sentinel, not an instruction (it is the "no opcode" / error marker). There is no 0x00 opcode in any enum (the band starts at 0x01 LDWEIGHTS). One value subtracted. [HIGH/OBSERVED]

1.4 The metric

   172   union distinct opcode VALUES across the 4 shipped common.h enums
 −  31   PSEUDO 0xC1–0xDF (compiler-generated, NRT-lowered, not device-decoded)
 −   1   INVALID 0xFF sentinel (not an instruction)
 ───────
   140   REAL HW opcodes — the GPSIMD kernel-lane decode space

The metric is: distinct opcode VALUES in the union of the four shipped-generation NEURON_ISA_TPB_OPCODE enums, minus the NRT-pseudo band, minus the INVALID sentinel. This is the denominator every per-kernel page in this cluster is measured against. [HIGH/OBSERVED — re-derived byte-exact this session.]

2. The master opcode → kernel table (140 real opcodes)

One row per real HW opcode. Columns:

• Op — the opcode byte (hex).
• Kernel name — from the enum identifier, cross-checked against the kernel_info_table resolved name and the SEQ 'S:' / POOL 'P%i:' log string.
• Eng — executing engine: POOL (Q7 compute core) · NX (SEQ control core) · PE (systolic array) · ACT (activation) · DVE (vector engine) · NX/DMA (descriptor-backed).
• Struct — the operand struct family (from the per-kernel FW decode; — where the body is not separately decoded).
• Dtype — supported dtype set / route.
• Presence — per-gen [SUNDA·CAYMAN·MARIANA·M+·MAVERICK]: Y=maintained (// Y), n=dormant (// n), .=present-unflagged, -=absent. M+ mirrors MARIANA's enum (byte-identical KIT).
• Decode — the cluster page (or status) that decodes this opcode's body.

Rows marked †MED have the body in the per-gen device-depth tail (FLIX-desync interior, out-of-corpus container, or header-OBSERVED-only on MAVERICK). They are named + dispatch-placed with HIGH confidence; only the operand-layout body is MED.

2.1 PE — systolic array (0x01–0x0A)

CORRECTION — 0x05 is WEIGHT_SHIFT, not "Matmul". The kernel_info_table cross-gen matrix source notes once labelled 0x05 as "Matmul"; the shipped header is authoritative: 0x02 = MATMUL, 0x05 = WEIGHT_SHIFT (dormant nnnnn). Recorded here as WEIGHT_SHIFT. [HIGH/OBSERVED]

2.2 ACT — activation (0x21–0x26)

2.3 DVE — vector engine (Exponential, RNG, sparsity, MX)

NOTE — 0x30 EXPONENTIAL presence. The header carries it present-but-unflagged (.) in all four generations ([HIGH/OBSERVED]). Its DVE compute body is a MARIANA realization (per the cross-gen matrix); the ..... reflects the header roster, the DVE engine attribution reflects the runtime.

2.4 POOL — Q7 compute core (the bulk of the kernel lane)

2.5 DVE — batchnorm family (0x60–0x66)

(The transpose/2 batchnorm variants 0x82, 0x8E, 0x94 are listed in their numeric positions in §2.4.)

2.6 NX — SEQ control core + DMA (0x9F–0xBF)

NOTE — 0x81 JPEG_DECODE is real-but-dormant (presence -nnnn — absent on SUNDA, dormant on CAYMAN+), listed in its numeric position in §2.4. The pseudo 0xD7 PSEUDO_JPEG_DECODE is a different opcode (§1.2). [HIGH/OBSERVED]

Row count: 140 — PE 10 · ACT 6 · DVE-vector 8 · POOL band 56 · batchnorm 10 (0x60–0x66 + 0x82/0x8E/0x94) · NX 49 · 0x81. Every real HW opcode appears exactly once, verified against the §1.4 derivation.

3. The three-source crossing (why 140 ≠ 17 ≠ 55)

The three dispatch sources are structurally distinct and were never meant to have equal cardinality. The ledger's job is to show the inclusion relations precisely.

The counts differ for three reasons:

1. The 140 is the cross-gen union; the 17 is one image. The kernel_info_table holds only the POOL compute back-end for a single shipped image. Its 17 keys are {0,0,spec,opcode} 8-byte records read LE as (opcode<<24)|(spec<<16); five of them are the same opcode 0xF0 with different spec bytes (the extended-instruction bridge), so the 17 rows cover only ~13 distinct opcodes. Every other real opcode reaches its kernel by a non-kernel_info_table path (direct SEQ handler, DGE, ACT/PE/DVE engine dispatch). The kernel_info_table key set is byte-identical CAYMAN→MAVERICK (sha 910d41c3 == 9f2ce049 == a92c8ba0) — POOL's compute table does not grow across generations; the opcode-space growth lands on PE/DVE/ACT instead.

2. The 55 SEQ handlers are the fetch surface, not the compute surface. The 178-slot table is what the NX core fetches and routes; 55 slots resolve to real handlers (the SEQ control spine + the POOL/ACT/PE/DVE entry trampolines), the other 123 are 0x3198 default fills. The POOL compute opcodes appear here as their SEQ entry 'S:' handler (Tensor-Tensor, Pool, Copy, …); their bodies then run on the Q7 core, reached either directly or via the 0xF0 bridge (the single opcode that forwards (0xF0, spec) from SEQ surface A to kernel_info_table surface B).

3. The 140 includes engines and gens the other two sources don't. The roster spans PE (0x01–0x0A), ACT (0x21–0x26), DVE (RNG/sparsity/MX), and the MAVERICK-only and SUNDA-only ops — none of which are POOL kernel_info_table rows, and several of which (the MAVERICK INT_WIDE 0xF3/0xF4, the SUNDA BF16 0x8A–0x8F) are not in any clean carve slot at all.

The reconciliation, stated as inclusions: the 17 kernel_info_table opcodes ⊂ the POOL subset of the 55 SEQ-real opcodes ⊂ the 140 roster. Going the other way, the 140 roster − (SEQ-named + kernel_info_table-covered + FW-decoded) = the remaining kernel-lane gap (the NONE rows above). See pool-dispatch for the SEQ↔Q7 hand-off and kernel-info-table for the 17-entry byte dump.

4. Per-generation presence

The presence column reads [SUNDA·CAYMAN·MARIANA·M+·MAVERICK]. The byte-grounded story:

• SUNDA (v2) is the floor. 145 enum entries. It is the only key-set outlier: it has the BF16 cluster 0x8A–0x8F (Y----) and the dual-ptr pair 0x87/0x88 (n----) that no later gen ships, and it lacks the entire extended layer (no 0xF0 bridge, no 0x7B dequant, no 0xE4 cptc, no 0xBE/0xF2). SUNDA's POOL kernels live in an out-of-corpus EXTISA container (neuronx-runtime package), so its 18-entry flat table is [HIGH/CARRIED], not re-verified here. MED tail flag: the SUNDA BF16 operand layouts are out-of-corpus.

• CAYMAN (v3) establishes the extended layer. 150 entries: +0x06/0x07 (LdTags, MatmulSparse), +0xBC–0xBF/0xE4/0xE9/0xF1/0xF2 (the -Y… rows), and the 0xF0 bridge. Fully byte-grounded [HIGH/OBSERVED].

• MARIANA (v4) adds DVE + PE. 159 entries: +0x08/0x09/0x0A (PE seed/MX), +0x25 (Activate2), +0xE0–0xE3 (sparsity/Rand2/QuantizeMx), +0xB4 (TestEventSem). The --YYY rows. [HIGH/OBSERVED]

• MARIANA_PLUS (v4+) reuses the MARIANA enum. No opcode-space delta; the M+ column mirrors MARIANA. The v4+ change is the DGE fast-path, not the opcode roster (KIT sha 9f2ce049, byte-identical to MARIANA). [HIGH/OBSERVED]

• MAVERICK (v5) +6, mostly header-OBSERVED. 165 entries. Three byte-pinned [HIGH/OBSERVED]: 0xB6 COMPACT_CONTROL_INST, 0xB9 DMA_MEMCPY2, 0xBA DMA_IMMEDIATE. Three name-pinned, byte-MED [INFERRED]: 0x26 ACTIVATE_MULTIPASS, 0xF3 TENSOR_TENSOR_INT_WIDE, 0xF4 TENSOR_SCALAR_INT_WIDE — the enum names are read directly, but the byte value and dispatch trampoline are FLIX-desynced / not in a clean carve. These six are the ----Y rows.

GOTCHA — search-cluster ops are MARIANA, not MAVERICK additions. The ops 0x6C/0x6D/0x6E/0x6F (YYYYY) are pre-existing MARIANA DVE opcodes, not v5 additions; at MAVERICK they are merely PROF-armed onto the DVE engine (a profile-table change, not opcode growth). Do not double-count them as MAVERICK-new. [HIGH/OBSERVED]

The MED per-gen device-body tail carried explicitly (these rows are dispatch-placed

• named HIGH, body MED): SUNDA RELEASE/zero-log + out-of-corpus EXTISA container (the BF16 cluster 0x8A–0x8F, dual-ptr 0x87/0x88); MAVERICK 0xF3/0xF4 and 0x26 ACTIVATE_MULTIPASS (header-OBSERVED only → INFERRED, no POOL DEBUG image); the FLIX-desync device interiors of the 0xBD/0xF1 SEQ FLIX-inline DMA-transpose handlers.

5. Phantom and wall callouts

CORRECTION — SortMerge is a PHANTOM. Do not document it as a live opcode. A task plan once named "SortMerge" as a hardware opcode to decode. There is no SortMerge HW opcode in any shipped enum. It survives only as a comment on the 0x98 line of the maverick header: NEURON_ISA_TPB_OPCODE_TENSOR_SCALAR_SELECT = 0x98, // SortMerge wip 0x97 // Y. The byte 0x97 is never assigned to an opcode in any gen (it appears elsewhere only as the unrelated UPDATE_MODE_SEM_SUB_REG_COMPLETE = 0x97 in a different enum), and 0x98 is the real TENSOR_SCALAR_SELECT (ts-select). SortMerge is named-but-never-shipped. See confidence-model §4.5. [HIGH/OBSERVED — maverick header line read this session.]

QUIRK — MAVERICK 0xF3/0xF4 are header-OBSERVED only (INFERRED placement). The INT_WIDE pair is named in the maverick enum but has no POOL DEBUG image carrying a clean device body — the dispatch trampoline is FLIX-desynced. The names are HIGH; the byte value, engine split (DVE vs POOL), and operand struct are MED/INFERRED. Marked †MED in the table. [INFERRED]

WALL — FLIX-desync device interiors. Several POOL/DMA bodies (0x45 Pool inner reduce, 0xBD/0xF1 DMA-transpose, the MAVERICK late ops) sit inside FLIX/VLIW bundles that the linear ncore2gp disassembler resyncs imperfectly. Their opcode, dispatch slot, and funcVA are byte-exact; only the instruction interior is MED. This is the corpus-wide MED ceiling (confidence-model §4.4), not a per-kernel defect.

6. Coverage tally (over the 140 real HW opcodes)

The 51 NONE, split by maintenance flag (latest-present-gen char): 43 maintained (// Y) + 8 dormant (// n). The 43 maintained-NONE further split into 14 SEQ control-spine (named in the dispatch hub, no dedicated body — ENGINE_NOP, HALT, DRAIN, NOP, NOTIFY, the semaphore/poll ops, …) and 29 genuine compute/DMA/ACT gap (the true remaining kernel-lane decode debt — the maintained gap rows above).

NOTE — dormant reconciliation. There are 20 dormant (// n) opcodes total; 8 are NONE (0x04, 0x05, 0x4A, 0x4B, 0x4C, 0x73, 0x81, 0x9C) and 12 are dormant; covered (0x44, 0x4F, 0x54, 0x5F, 0x60, 0x63, 0x64, 0x70, 0x71, 0x76, 0x87, 0x88). Re-verified this session: 8 + 12 = 20, exactly the dormant set. [HIGH/OBSERVED]

7. The index — per-kernel pages this ledger catalogs

This page is the anchor for the kernels cluster. Each real opcode's body is documented on a dedicated page (authored separately). The major ones, by family:

• Tensor-Tensor / Tensor-Scalar / Reduce: tensor-tensor · tensor-scalar · tensor-reduce · scalar-tensor-tensor · tensorcumulative · tensor-tensor-scan
• Copy / Cast / Pool / Iota: cast-copy · avg-max-pool · iota · cross-lane-reduce · stream-transpose
• PE / ACT: pe-matmul · activate-pwl
• Quantize / codec: tensor-dequantize · mx-dequant · convlutload · cptc-codec
• Indirection / DMA: indirection-gather · rangeselect · sb2sb-remote-copy
• Search / select / predicated: search-cluster · sort · ts-select · castpredicated · copypredicatedreduce
• RNG / dropout / batchnorm: rng-lfsr-dispatch · rand2 · dropout · batchnorm-forward · batchnorm-backprop
• Sparsity / sequence / nonzero: sparsity-compress-tag · get-sequence-bounds · nonzero-with-count
• NX control: move-dtype · alu-op-matrix · tensorload · tensorstore

NOTE — forward-links. The per-kernel pages above are authored separately in this cluster; some rows in §2 tagged (planned) point at pages that document a search/select/predicated/DVE sibling not yet body-decoded — those are forward-links to in-cluster stubs. The table's opcode → name → presence facts here are byte-grounded regardless of per-page authoring state.

Dispatch-mechanism cross-links (committed siblings): the POOL main dispatch loop (SEQ↔Q7 hand-off) · the kernel_info_table byte layout (the 17-entry table) · the 0xF0 extended sub-dispatch (the 5-spec bridge) · the SEQ ASCII dispatch hub (the 178-slot fetch table) · the Confidence & Walls model.