Master Opcode Reference

All symbols, ordinals, and addresses on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310 wheel). The L1 enum is defined in neuronxcc/starfish/lib/libBIR.so (md5 12bb979f7ca41248252abb0f16b2da98); the L2/L3 encoders and setupHeader are in neuronxcc/starfish/lib/libwalrus.so (.text/.rodata base 0x62d660 / 0x1c72000, VA == file offset). cp311/cp312 share the .text logic — the opcode integers and the L1/L2/L3 arithmetic are ABI-stable across cp3xx, only the VAs drift. Other wheels differ — treat every address as version-pinned. See Build & Version Provenance.

Abstract

This appendix is the single consolidated lookup table for the neuronx-cc backend opcode space: all 110 bir::InstructionType arms × the wire opcode word per generation {V2, V3, V4} × the owning engine × the access/bundle family. It unifies what the three normative pages established separately — the 110-opcode InstructionType enum and its sameInst masks, the setupHeader L3 wire-word path and per-op opcode master, and the per-engine encoding pages (PE matmul, Pool, Activation, DVE, DMA) — into one row-per-opcode grid a reimplementer can scan by either the IR ordinal or the wire byte.

The reimplementation model is the three-layer opcode contract (§0): a BIR op carries up to three distinct integer identities in three separate namespaces. L1 is the bir::InstructionType ordinal (0..109, the IR class id). L2 is the NEURON_ISA_TPB_OPCODE enum value the COLLECT_OPCODES arm records (the engine-relative silicon micro-op id). L3 is the 16-bit wire header word setupHeader stamps at bundle[0:2], equal to (0x10 << 8) | L2byte. The cardinal invariant is L1 ≠ L2 for every op — they are different enums, equal for no opcode — so an opcode↔IT mapping is never one-to-one, and the only cross-layer-stable key is the shared name (the BIR-JSON "type" string), not any integer.

This page is a reference catalog, not an algorithm walkthrough; its value is completeness and correctness. The table in §1 is re-derived directly from InstructionType2string (0x2d5bf0), the sameInst switch (0x2db7b0), the three setupHeader bodies, and the per-op visitInst* COLLECT/GENERATE immediates — not hand-copied from the consolidated pages, so it catches their slips. Every per-gen cell carries a confidence tag; the five highest-risk rows (the per-arch Activation divergence, the MX family, the collective/custom-op/DMA arms) were adversarially re-verified against the binary in §4. Where a re-derivation disagreed with an earlier page, it is flagged in place as a CORRECTION with byte evidence, never silently overwritten.

0. The three-layer opcode contract

A BIR op has up to three integer identities. Conflating them is the cross-layer error the normative opcode page (§0) was written to kill, and it recurs in any map that prints "opcode 4 = Activation" without saying which opcode.

L1  bir::InstructionType ordinal (0..109)
      = the C++ enum tag at bir::Instruction+0x58 (the 22nd dword)
      = the IR class id — what the node *is*
      defined in libBIR  (2string @0x2d5bf0, sameInst @0x2db7b0)        [CONFIRMED]

L2  NEURON_ISA_TPB_OPCODE value
      = the int the COLLECT_OPCODES arm inserts into std::set<u32>
      = the byte GENERATE writes to bundle[0]
      = the engine-bitmap bit position in the wire validator
      = the silicon micro-op id — engine-relative
      decoded by core_v4::enum_variant_string_opcode @0x143fd80         [CONFIRMED]

L3  the 16-bit wire HEADER WORD setupHeader stamps at bundle[0:2]
      bundle[0]   = opcode byte           (= L2 low byte)
      bundle[1]   = 0x10 = inst_word_len  (16 dwords = 64-byte bundle, HARDCODED)
      bundle[2:4] = 0x0000
      ⇒ L3word = (0x10 << 8) | L2byte                                    [CONFIRMED]

The three invariants a reimplementation must honor:

• INV-1 — L3word = (0x10 << 8) | L2byte. The high byte 0x10 is the fixed length nibble (16 dwords); the low byte is the L2 opcode. QuantizeMx is the only op that perturbs the high byte: it OR-s bit 0 (0x10 → 0x11) when the SATURATE flag is set.
• INV-2 — L2 is one value, consistent across its uses: COLLECT-set int == GENERATE bundle[0] byte == opcode-count-map key == engine-bitmap bit.
• INV-3 — L1 ≠ L2 numerically for every op. The encoder is the non-injective projection L1 → {L2}. The only cross-layer-stable key is the L2/L1 name (BIR-JSON "type"), never any integer.

setupHeader itself is the same six instructions in all three generations (0f b6 02 c6 46 01 10 88 06 31 c0 66 89 46 02 c3): load the opcode byte, store 0x10 at bundle[1], store the opcode at bundle[0], zero bundle[2:4], return. It is reached as a virtual through the Generator vtable slot +0x48 (slot 9). All per-arch and per-op variation lives in the opcode byte fed to it, never in the header layout — which is exactly why this table can be one grid: only one column-family (the L3 byte) ever moves.

NOTE — the engine column is metadata, not a wire field. The physical engine rides the BIR Instruction at +0x90 (EngineType); the encoder only reads it as a census-map key. {PE=0, ACT=1, POOL=2, DVE=3, SP=4} on the wire. It is listed below because a reimplementer must route the op to the right engine, but it is never encoded in the 64-byte bundle.

1. Master 110-row opcode table

One row per bir::InstructionType ordinal. Words are shown as 0x10NN (NN = the L2 low byte). = in a per-gen column means inherits the prior generation's word verbatim (no override). — means not encoded on that generation (gen-gated). (lowered) / (no enc) / (base) mean the IT reaches no setupHeader at all (see the Kind column).

Columns: IT = L1 ordinal · Name = InstructionType2string name (= the cross-layer key) · L2 = NEURON_ISA_TPB_OPCODE low byte (hex) · V2/V3/V4 = the L3 16-bit word per generation · #B = 64-byte bundles this one op emits · Eng = physical engine (+0x90 metadata) · Kind/flags = reconciliation tags (legend below the table) · Conf = confidence of the opcode value.

Legend for Kind/flags: [base] abstract base IT (leaves carry the opcode) · [low] lowered-away / no encoder · [split] one IT forks into several L2 opcodes by a runtime field · [mb:n] multi-bundle (emits n wire words) · [col] L2 collision (this opcode is shared by another IT) · [ΔV4]/[ΔV3] genuine per-gen opcode-byte renumber · [newV3]/[newV4] gen-introduced (no earlier encoder) · [+1=cast] opcode low bit = dtype-cast flag.

GOTCHA — never assume opcode ↔ IT is one-to-one. The grid is non-injective in both directions: one IT can emit several L2 opcodes ([split]/[mb]), and one L2 opcode is shared by several ITs ([col]). A reimplementation that keys a decode table on the bare opcode byte will alias Rng with Memset, Send with Recv, the two branches, and the three DMA-direct ops. The disambiguator is always an in-bundle field, the direction bool, or the engine — see §2 and §3.

2. L2 opcode collisions

Eight wire opcodes are emitted by more than one InstructionType. The silicon does not distinguish the colliding ITs by opcode; an in-bundle field, the direction bit, or the engine does. This is the [col] flag, gathered. (IndirectLoad/IndirectSave are not a collision — they carry two distinct opcodes selected by a direction bool; see CORRECTION OPC-1.)

QUIRK — Rng(100) and Memset(Random)(10) collapse to the same 0x4D DVE-RNG slot — two distinct IR ops compiling to one micro-op, separated only by whether the fill immediate is forced to zero. A decoder cannot recover which IR op produced a 0x104D bundle from the opcode alone; that information is gone by L3.

3. Multi-bundle and [split] ops

Multi-bundle ops ([mb:n] — one IR op → n wire bundles)

A reimplementation must iterate the op's COLLECT set (it is a std::set<u32>, legally holding more than one opcode), not assume one opcode per instruction.

[split] ops (one IT → multiple L2 opcodes selected by a runtime field)

The opcode is chosen at encode time by a sub-type discriminator, not fixed per IT:

• TensorReduce(27): TR 0x7C/0x7D + CR 0x42/0x52/0x83/0x84 — selected by (apply_transpose, isBitVec) (6 opcodes total).
• TensorScalar(28)/TensorScalarPtr(29): 0x43/0x93/0x53/0x9A/0x9C/0x9E/0xE5/0x74 — one dispatcher (generateTensorScalarOrPtr); IT28 has no own encoder. V3/V4 widen the field bands, not the opcode.
• TensorScalarCache(30): 0x9A (Reduce) / 0xE6 (Cumulative+Scan) by TSCMode.
• TensorTensor(31): 0x41/0x51 by isBitVecInstruction (+ GPSIMD int32 re-stamp 0x8A).
• BNStats(34): 0x61/0x82 by apply_transpose. BNGradients(36): 0x63/0x94 by coeff source.
• Memset(10): 0x49 (Const) / 0x4D (Random). CollectiveCompute(48): 0xD9/0xDA (fine/coarse).
• TensorLoad(75): 0xCE/0xAA (imm/reg). TensorSave(76): 0xAB/0xCD (imm/reg).
• SetRandState(59): 0x78 (Pool) / 0xD0 (DVE) by EngineType.
• TensorCopy(23): 0x46 (no cast) → 0x47 (cast). The [+1=cast] low bit is decided on the raw src/dst dtype, not the reinterpreted one.

4. Adversarial verification — five highest-risk rows

These five rows are the ones most likely to be wrong in a transcription (per-gen divergence, gen-gated families, the collisions). Each was re-derived from the encoder body's COLLECT dword-store / GENERATE byte-store immediates and the 0x10<<8|byte word-store, read from the libwalrus disasm sidecars (cp310, VA == file offset).

A further pair of DVE-engine [newV3] pins (RangeSelect and NonzeroWithCount) was spot-checked the same way: RangeSelect CoreV3 @ 0x135f8c0 stamps 0xBC (0x10BC) @0x135f95f; NonzeroWithCount CoreV3 @ 0x1355a30 stamps 0xF2 (0x10F2) @0x1355b18. Both CONFIRMED, both gen3-introduced (no CoreV2 sibling).

5. Corrections

Where the re-derivation disagreed with an earlier page or table, the binary witness is recorded here in place rather than silently merged. (These are the prior opcode-map slips this appendix exists to catch.)

CORRECTION (OPC-1) — IndirectLoad(43) / IndirectSave(45) L2 byte. Two earlier reports disagreed — one named 0xC4, the other the COLLECT-witness 0xD6 (214) — and a prior synthesis treated this as a single shared opcode, flagging it a collision. The binary settles it: generateIndirectLoadSave @ 0x1268c00 emits both opcodes on two mutually-exclusive branches gated by its bool a3 (isLoad) argument. The 0xC4 (196) path stores its COLLECT dword @ 0x1268f89 and GENERATE bytes @ 0x12690cd/0x12694b8; the 0xD6 (214, PseudoRangeCheck) path stores its dword @ 0x1269576 and bytes @ 0x1269a6c/0x1269bd3. So IndirectLoad and IndirectSave carry distinct wire opcodes (one 0xC4, one 0xD6) selected by the direction bool — not a shared 0xD6 collision. Both reports were right for their respective sub-instruction; the "disagreement" was an artifact of reading one merged encoder as one opcode. CONFIRMED (both immediates byte-present in the disasm). The decompile does not label which bool value maps to Load vs Save by name, so the per-direction assignment of 0xC4/0xD6 is left open.

CORRECTION (OPC-2) — RangeSelect(63) emission width. The op's opcode is 0x10BC (188, byte-verified), but the CoreV3 encoder may append a 0x9B (DveReadAccumulator) drain word, making the practical emission two wire words. The table row carries 0xBC as the op opcode and notes the 0x9B append rather than listing two opcodes — they are one logical op with an accumulator-drain tail, not a [split]. STRONG.

CORRECTION (OPC-3) — NonzeroWithCount IT. An earlier annotation read "bir 231" for this op; the L1 ordinal is 104 (CONFIRMED from both InstructionType2string and the sameInst arm). 231 (0xE7) is IndirectCopy's L2 opcode, not this op's IT — a cross-layer conflation. There is no 231-vs-242 IT split; the only relation is the normal L1(104) ≠ L2(242=0xF2) that every op has. Resolved: IT = 104, L2/L3 = 0xF2/0x10F2. CONFIRMED.

CORRECTION (OPC-4) — MatmultSparse(9) opcode. An earlier table listed 0x50; the binary read of generateMatMulSparse @ 0x135d150 stamps 0x07 (and generateLoadTagsSparse @ 0x135e960 stamps 0x06). The wire bytes are 0x06+0x07; 0x50 ('P') was an ASCII-band mislabel of an adjacent/unused slot. CONFIRMED via binary.

6. Reading the table — reimplementer notes

• Vestigial / not-emitted arms. Of the 110 ITs, ~25 reach no setupHeader: the abstract bases (MatmultBase(7), DMA(18), Collective(47), Terminator(77), DMADescriptor(68)); the lowered-away ops (Generic(0), GenericRelu(2), AbstractCopy(3), GenericCopy(1), TensorCopyDynamicSrc/Dst(24/25), GenericIndirectLoad/Save(42/44), Select(51), Loop(105), DynamicForLoop(106), DoWhile(108), DMABlock(107), TongaReduceMacroSymbolic(109)); the kernel/debug carriers (BIRKernel(54), NKIKernel(55), NKIKLIRKernel(56), DevicePrint(57), Break(83)); and Rand(60) (shipped as Rand2/IT97). InlineASMBytes(93) has no fixed opcode — the user's first hex byte is the opcode.
• No-sameInst arms. NKIKernel(55), NKIKLIRKernel(56), and Call(84) __assert_fail "Not Implemented" if sameInst is called — CSE/dedup over those ops is unsupported by design. The five structured-control opcodes (105–109) also have no meaningful structural-eq (they are region/loop carriers). See §sameInst.
• Per-gen reading. Read across the V2/V3/V4 columns left to right; = carries the prior word forward. A — then a word (e.g. RangeSelect: — / 0x10BC / =) marks the generation the op was introduced. The only genuine byte renumber of an existing op across generations is Activation (0x21 → 0x25 at V4); every other V3/V4 override either keeps the opcode and only widens field bands, or is a gen-new op.
• Confidence. CONFIRMED rows have a binary-pinned encoder (the ~85 concrete ITs). STRONG rows are transcribed from the COLLECT site without a per-byte re-read this pass (e.g. ReadVarAddr, the indirect-load/save pair pending a 3rd witness). INFERRED/HIGH rows are the lowered/abstract ITs with no encoder body — classified by the absence of a visitInst* body and a sameInst arm, consistent across both libraries.

Related Components

Cross-References

• InstructionType — the 110-opcode L1 enum, the opcode field at +0x58, and the sameInst structural-equality masks (the source of the IT/Name columns and the [base]/family flags)
• The Opcode Master — setupHeader, the L3 wire word, and the per-op L1↔L2↔L3 reconciliation (the source of the V2/V3/V4 word columns and the INV-1..3 contract)
• Instruction Bundle — the 64-byte bundle the header word leads; inst_word_len = 0x10 = 16 dwords
• DVE Opcode Table — the on-device 256-slot opcode→microcode-row map the DVE sequencer indexes with the L2 opcode byte
• Build & Version Provenance — the cp310/311/312 wheel pins and the VA-drift note for cross-version address translation