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 grounded directly in InstructionType2string (0x2d5bf0), the sameInst switch (0x2db7b0), the three setupHeader bodies, and the per-op visitInst* COLLECT/GENERATE immediates. Every per-gen cell carries a confidence tag, and the five rows most prone to transcription error (the per-arch Activation divergence, the MX family, the collective/custom-op/DMA arms) carry their explicit byte witnesses in §4.

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)

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

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

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.

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.

RangeSelect(63) sits just outside this family. Its opcode is the single 0x10BC, but the CoreV3 encoder may append a 0x9B (DveReadAccumulator) drain word, so the practical emission is two wire words. It is one logical op with an accumulator-drain tail — not a [split], and not a two-opcode instruction — which is why the table row carries 0xBC alone and notes the append.

Anchors: generateMatMulSparse @ 0x135d150 (stamps 0x07), generateLoadTagsSparse @ 0x135e960 (stamps 0x06) — the MatmultSparse pair.

[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.
• IndirectLoad(43)/IndirectSave(45): 0xC4 / 0xD6 (PseudoRangeCheck), selected by the isLoad direction bool.

The indirect load/save pair

IndirectLoad(43) and IndirectSave(45) share one encoder — generateIndirectLoadSave @ 0x1268c00 — but not one opcode. The function's bool direction argument gates two mutually-exclusive branches, each with its own COLLECT dword and GENERATE byte stores: the 0xC4 (196) path and the 0xD6 (214, PseudoRangeCheck) path. So the pair is a [split], not a [col] collision: one IT-pair, two distinct wire opcodes chosen at encode time.

The decompile does not name which bool value maps to Load versus Save, so the per-direction assignment of 0xC4 and 0xD6 remains open; both immediates are byte-present, only their pairing with a direction is unpinned.

Anchors: 0xC4 path — COLLECT dword @ 0x1268f89, GENERATE bytes @ 0x12690cd / 0x12694b8; 0xD6 path — dword @ 0x1269576, bytes @ 0x1269a6c / 0x1269bd3.

4. Byte witnesses — 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 is pinned by 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).

The two DVE-engine [newV3] pins carry the same class of witness: RangeSelect CoreV3 @ 0x135f8c0 stamps 0xBC (0x10BC) @0x135f95f; NonzeroWithCount CoreV3 @ 0x1355a30 stamps 0xF2 (0x10F2) @0x1355b18. Both are gen3-introduced — neither has a CoreV2 sibling.

GOTCHA — NonzeroWithCount's L1 ordinal is 104, not 231. 231 (0xE7) is IndirectCopy's L2 opcode, and reading it as an IT is the classic cross-layer conflation INV-3 exists to prevent. This op's own numbers are the ordinary L1(104) ≠ L2(242 = 0xF2).

5. 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. CERTAIN rows have a binary-pinned encoder (the ~85 concrete ITs). HIGH rows are transcribed from the COLLECT site without a per-byte witness (e.g. ReadVarAddr). MEDIUM 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