Compiler Cross-Reference to the neuronx-cc Wiki

This is the bridge page: it draws the line between this GPSIMD device guide and the sibling neuronx-cc compiler wiki — a separate mdBook documenting the full host compiler. This Part touches that compiler only at the GPSIMD seam (the emit_*→BIR→SundaISel→opcode bridge and the MX device bodies); everything else — the hlo-opt/hlo2penguin frontend, the Penguin middle-end, the libwalrus descriptor backend in its entirety, the scheduler/memory planner — is owned there, and this page points at it rather than re-deriving it.

It also adds one new datum to the ISA model: the neuronx-cc isa_tpb/sunda tables are a 5th independent ISA source for the TPB opcode roster, sitting alongside the four the TIE-database page already enumerates. That section is the substantive content here; the rest is boundary-drawing.

Audience & scope. A senior C++/LLVM engineer rebuilding a Vision-Q7-compatible GPSIMD engine, who needs to know which facts live in this book vs the compiler book, and why the compiler's ISA table is a legitimate fifth witness to the device opcode ledger. This page points, it does not duplicate — the owned emit_*/BIR/ISel/MX material is cross-linked, not restated.

Provenance. Every fact derives from static analysis of the shipped, redistributable neuronx-cc 2.24.5133.0+58f8de22 wheel artifacts (the Cython .so, the native libwalrus.so, the plain-.py/.pyi stubs) and the in-book device ledgers cited inline. Recovered symbols, strings, and shipped tables are binary-derived and citeable. No external vendor source tree is referenced. Confidence is tagged per claim HIGH/MED/LOW × OBSERVED (read this pass) / INFERRED (reasoned over OBSERVED) / CARRIED (read in a cited in-book page, reused).

CC = neuronx-cc/extracted/neuronx_cc-2.24.5133.0+58f8de22-cp311-cp311-linux_x86_64/neuronxcc/

cp310/cp311/cp312 wheels are byte-identical in the Cython layer; the cp311 copy is cited throughout.

GUARD — the sunda/tonga/cayman/mariana/maverick axis is the codegen-TARGET / arch-ISA axis, not silicon. sunda=CoreV2 (Trn1/Inf2 floor), tonga=Inf1 legacy, cayman=CoreV3/Trn2, mariana=CoreV4/Trn3, maverick=CoreV5/NCFW. The shipped isa_tpb table mined here is the sunda floor. No silicon-generation fact is inferred from any compiler descriptor. [HIGH/OBSERVED — the tokens appear only as directory names under CC/isa_tpb/ and CC/starfish/penguin/targets/.]

1. The 5th independent ISA source — isa_tpb/sunda

The TIE-database page §4 certifies the Cairo (ncore2gp) ISA from four independent shipped sources: (1) the libisa-core.so runtime decode tables, (2) the libtie-core.so / Xtensa.xml TIE database (the only one carrying bit-precise semantics), (3) the native xtensa-elf-objdump disassembler, and (4) the device-side custom_op/c10/include/* arch-isa headers + instruction_mapping.json.

Sources 1–3 witness the Vision-Q7 core ISA (the 1534-opcode Xtensa FLIX scalar/vector instruction set the GPSIMD POOL kernels are written in). Source 4 witnesses a different layer: the NEURON_ISA_TPB tensor-engine macro-op word — the 64-byte instruction (NEURON_ISA_TPB_INST_NBYTES = 64) the host compiler emits and the device firmware decodes. The neuronx-cc isa_tpb/sunda tables are a 5th source on that same Source-4 layer: a different serialization, produced by a different tool, shipped in a different artifact — the compiler wheel, not the device custom-op library.

NOTE — what makes this the 5th source, not a re-read of Source 4. Source 4 is the device-side TPB layer (neuronx-gpsimd/extracted/.../custom_op/c10/include/<gen>_arch_isa/tpb/, a hand-authored C++ header + a generated instruction_mapping.json whose struct2opcode has 89 entries on the sunda floor — byte-verified jq '.struct2opcode|length'). The 5th source is the compiler-side TPB layer (CC/isa_tpb/sunda/{neuron_isa,neuron_isa_tpb_pybind}.so — RTTI-registered C++ enums + a per-opcode pybind builder/validator module). An error in one — a stale header, a wrong pybind encode template — would not propagate to the other; their agreement is a genuine confidence signal, exactly the independence criterion tie-database §4 requires of a source. They share design provenance (one TPB ISA spec) but independent serialization + tool. [HIGH/OBSERVED]

This 5th source is orthogonal to Sources 1–3 (the Vision-Q7 FLIX core ISA): trying to find a "missing ISA-39 Xtensa opcode" in isa_tpb is a category error — the two rosters describe different machines at different abstraction levels. The device firmware decodes the TPB opcode and runs a Vision-Q7 FLIX kernel to implement it (the kernel_info_table binding documented in opcode-catalog-ledger).

1.1 What the two isa_tpb/sunda modules are

[HIGH/OBSERVED — both .sopresent and read this pass; theNEURON_ISA_TPB_OPCODE/_ALU_OP/_CCE_OP/_COLLECTIVE_TYPE/_DGE_COMPUTE_OPRTTI typeinfo strings are present inneuron_isa.so.]

1.2 The corroboration — what the 5th source confirms

The 5th source's value is agreement, op-by-op, with the device ledger (opcode-catalog-ledger, the device-side #688-class ledger this Part binds against) and with the four enumerated sources:

1. The full TPB opcode roster, byte-name-identical. Every opcode name in the device ledger is present in the pybind enum, including the 30 Pseudo* and the bf16 cluster — a 5-way roster agreement (the 4 device-side gen headers + this compiler enum). No new opcode appears in the compiler that the ledger lacks (it cannot: the ledger is the maverick superset; the sunda compiler is the v2 floor). The compiler adds no opcode; it confirms the roster and supplies the per-opcode descriptor struct + validators. [HIGH/OBSERVED]

2. The 20 operand/mode sibling enums match the device firmware enum reads field for field — e.g. COLLECTIVE_TYPE ∈ {ALL_REDUCE, ALL_GATHER, REDUCE_SCATTER, ALL_TO_ALL, ALL_TO_ALL_V, PERMUTE_REDUCE, PERMUTE_REDUCE_IMPLICIT} (strings verified), and DGE_COMPUTE_OP (RTTI _ZTI29NEURON_ISA_TPB_DGE_COMPUTE_OP) confirms the device dma_compute reduce-op set from a 5th source. [HIGH/OBSERVED]

3. The pseudo-count gen-floor refinement. The sunda compiler enum carries 30 Pseudo* names, the maverick device header 31 — the delta is exactly PseudoJpegDecode (a later-gen addition absent from the sunda floor), consistent with the ledger's per-gen matrix, not a conflict. [HIGH/OBSERVED — no-gen guard honored.]

QUIRK — the BIR spelling Matmult (two-t) vs the TPB spelling Matmul (one-t) marks the IR↔ISA boundary. The Penguin BIR node is InstMatmult (_ZN3bir11InstMatmult…); the TPB opcode it lowers to is Matmul 0x02. This is the cleanest single tell of which layer a name belongs to — the BIR roster owns the IR spellings, the device ledger owns the TPB spellings. [HIGH/OBSERVED]

1.3 The gap-opcode corroboration (the sharpest claim)

The device decode alone left a set of maintained gap opcodes with "name/semantics inferred" (the firmware decode is a NONE-tagged stub, or the descriptor literals were unrecoverable from the carved firmware .literal pool). For the sunda-present subset, the 5th source upgrades those to OBSERVED: it carries the opcode name, the builder class, the descriptor struct, and the field validators. Verified this pass:

GOTCHA — the confirmation runs both ways: presence AND absence. The maverick / CoreV5-only opcodes the ledger flags as absent from the sunda floor are confirmed-absent in the 5th source: TENSOR_TENSOR_INT_WIDE 0xF3 / TENSOR_SCALAR_INT_WIDE 0xF4 — the string int_wide (any case) has grep count 0 across neuron_isa.so, neuron_isa_tpb_pybind.so, and libwalrus.so (byte-verified this pass). Likewise ACTIVATE_MULTIPASS 0x26 and DMA_MEMCPY2 0xB9 are absent from the sunda table. So the 5th source corroborates the ledger's per-gen Y/n matrix in both directions — the sunda-floor gap ops are present-and-named; the maverick-only ones are verifiably-absent. The compiler does not reveal the maverick INT_WIDE byte encodings (out-of-table on the sunda floor). [HIGH/OBSERVED]

1.4 The descriptor emitter (the device-side gap, closed from the compiler side)

The device firmware's opcode→descriptor literals were unrecoverable from the carved .literal pool. The compiler is the producer of those descriptors, and resolves the gap directly: libwalrus.so names exactly 68 distinct NEURON_ISA_TPB_*_STRUCT descriptor types (byte-verified: strings libwalrus.so | rg -o 'NEURON_ISA_TPB_…_STRUCT' | sort -u | wc -l = 68) — the descriptor FORMAT taxonomy keyed by the S<n>S<n>D<m>_<op> tag (N source + M destination access-patterns) — plus the access-pattern types (TENSOR1D–4D, ADDR4) and the emitter API neuronxcc::backend::CoreV{2,3,4}GenImpl::assignAccess{1,2,3,4}D(…, const bir::AccessPattern&, …)

• assignAccessToType + assignStaticPattern + assignStartAddr + setupSyncUpdate (mangled symbols present in the backend:: namespace this pass).

This is a pointer, not a re-derivation: the full descriptor backend — the per-STRUCT field byte-offsets, the get_bytes 64-byte serializer body, the CoreVNGenImpl weak-inlined bodies — is owned by the neuronx-cc wiki (§3). This Part owns only where that emitter meets the GPSIMD seam: the compiler-map §1 descriptor-emit leg and the MX device bodies page, which byte-decodes the device consumer of two of those structs (S3DMX1_QUANT and MXMEM_PATTERN1D).

1.5 The cost model + version anchor

CC/hwm/ctm.…so carries the per-gen, per-engine Pool cost classes {InferentiaPool, SundaPool, CaymanPool, CoreV4Pool} (RTTI-verified: the mangled _ZN9SundaPoolC1Ev etc.

• getReorderWindowSize) — the GPSIMD/Q7 launch-cost model the scheduler queries. The architecturally meaningful datum (the ~150-cycle GPSIMD_START vs the 64-cycle Vector MIN_II, from the cc-stubs .pyi) is why the compiler keeps small tiles on Vector and routes to GPSIMD only what Vector cannot do; that tie is already stated and owned at compiler-map §1.1 and sundaisel §4. The full scheduler cost model is owned by the neuronx-cc wiki (§3).

Version. The isa_tpb/sunda tables ship under the neuronx-cc wheel __version__ = '2.24.5133.0+58f8de22', __buildtime__ = 'Apr 08 2026, 21:07:10 UTC' (byte-verified cat CC/version/__init__.py this pass). This is the toolchain version; it is distinct from the device-image ulib_to_ucode_version 1.21.1.0 / ulib_to_isa_version 1.0.2520.0 handshake (CARRIED; see the version table at compiler-map §7), which is the runtime/firmware axis. The cc table is the compile-time TPB ISA whose ucode target is 1.21.1.0.

NOTE — kernel_info_table is NOT compiler-emitted. No kernel_info_table / funcVA emission appears in any cc artifact (zero strings across isa_tpb, libwalrus, penguin). This confirms the device-side model: the (spec,opcode)→funcVA dispatch table is baked into the device firmware image, not produced by the host compiler. The division of labor is exact: neuronx-cc emits the TPB instruction (opcode byte + descriptor); the device firmware provides the kernel_info_table that routes that opcode to its Vision-Q7 FLIX kernel. The kernel_info_table is the runtime/firmware binding between the two ISAs; the compiler emits only the upstream (TPB) half. [HIGH/OBSERVED — absence in cc; the device-side placement is CARRIED from opcode-catalog-ledger.]

2. The ownership boundary — owned here vs cross-linked there

The line between this device guide and the sibling neuronx-cc compiler wiki, one row per subsystem. Owned here means a committed page in this Part decodes it to the GPSIMD seam; in the neuronx-cc wiki means the full internals live in the separate compiler book (§3) and this Part only points at the seam.

CORRECTION (vs GX-REF-02 §3.1, which CARRIED "73 InstXxx"). The backing report tabulated 73 Penguin BIR Inst* classes from an intermediate birpy read. The committed bir-inst-roster grounds the count on the full libBIR.so createFromJson/_ZTV symbol sets: 110 concrete classes (the "73" was the GPSIMD/compute-touching subset, before the 24-class control spine, 4 load/store, and 5 kernel containers). This page defers to the 110 figure — point, don't re-derive. [HIGH/OBSERVED — owned at bir-inst-roster §2, §8.]

CORRECTION (vs GX-REF-02 §0/§2.2, which framed isa_tpb as confirming "~172-opcode" roster). The committed compiler-map §7 and opcode-catalog-ledger reconcile the ledger as 172 union enum values − 31 PSEUDO − 1 INVALID = 140 real HW opcodes. The 5th source's "~172" is the union enum cardinality (every name incl. pseudos + invalid), not the real-HW-opcode count; both are correct at their level. This page cites the 140 real / 172 union split per the owned ledger. [HIGH/OBSERVED.]

3. Explicit pointers to the neuronx-cc wiki (the non-GPSIMD internals)

The following live in the separate neuronx-cc compiler mdBook — not a relative link from this book (it is a different book.toml). Cite them by path/name. A reimplementer of the device engine does not need these; a reimplementer of the compiler does.

• neuronx-cc/wiki/ — the hlo-opt / hlo2penguin HLO frontend. The XLA-HLO optimizer and the HLO→Penguin-BIR lowering. This Part records only that it converges on the same BIR (compiler-map §6).
• neuronx-cc/wiki/ — the Penguin middle-end. Every BIR transform/legalize pass, the tiling/layout pipeline, the list scheduler (build_ddg/enumerate_ready/pick_candidate), and the modulo-allocation / max-live-spiller memory planner.
• neuronx-cc/wiki/ — the libwalrus backend in full. The 65 MB descriptor-emission core: the per-NEURON_ISA_TPB_*_STRUCT field byte-offsets, the CoreV{2,3,4}GenImpl emitter bodies, the get_bytes 64-byte serializer, the ~688-entry is_valid_*/valid_* validator suite over NEURON_ISA_TPB_INST_UNION, and walrus_driver/hlo-neff-wrapper NEFF output.
• neuronx-cc/wiki/ — the scheduler cost model. The hwm/ctm.so per-gen×per-engine cost classes and the per-op cycle formulas, beyond the single GPSIMD launch-cost tie this Part needs.
• neuronx-cc/wiki/ — the isa_tpb builder/validator catalog. The full pybind get_bytes/set_bytes encode boundary and the per-opcode CamelCase builders, beyond the roster/gap corroboration §1 cites.

NOTE — the neuronx-cc wiki is a SEPARATE BOOK. It has its own SUMMARY.md and book.toml; a relative [link] from this book would dangle. These are deliberately inline path/name citations, not hyperlinks. Within this book, the GPSIMD seam is fully cross-linked (§4). [convention — keeps mdbook build link-clean.]

4. Cross-references (within this book)

• The GPSIMD-Relevant Compiler Map + emit_*→opcode — the 4-stage HLO→BIR→SundaISel→Generator→NEFF map and the 62-row emit_*→opcode table; the seam opener.
• The Penguin BIR Instruction Set + BIR→ISA Map — the 110-class BIR Inst* roster and the per-class device-opcode binding (the 73→110 correction above).
• SundaISel Deep-Dive — the engine-poly ISel, intrinsic fusion, the AssignHWDGEEngine libwalrus pass, the DGE selector.
• Byte-Decode of the MX Device Bodies — the device consumer of the S3DMX1_QUANT/MXMEM_PATTERN1D descriptors this 5th source names.
• Dtype/Engine/Gen Fan-In + CC-Lane Synthesis — the bf16/INT_WIDE dtype→opcode dispatch (the sibling capstone; the 0x8A–0x8F cluster §1.3 corroborates).
• The TIE Database & Four Independent ISA Sources — the four sources this page adds a 5th to (the 5th is parallel to Source 4, orthogonal to 1–3).
• Opcode Catalog Ledger — the device opcode roster the 5th source corroborates op-by-op.