Subsystem ↔ Binary ↔ Source-TU Matrix

Binaries (version pin): libnrt.so → libnrt.so.1 → libnrt.so.2.31.24.0 · 2.31.24.0-0b044f4ce · BuildID[sha1] 8bb57aba0fb2e0035f1d88e9fc4fb3e7387c102e · ELF64 DYN x86-64, NOT stripped, full DWARF v4 · aws-neuronx-dkms 2.27.4.0 (GPL-2.0 .ko, kernel module) · libncfw.so · BuildID a98f8e1c… · firmware carrier, NO DWARF · libnrtucode_extisa.so · BuildID 7bb03bc4… · GPSIMD ext-ISA provider, NO DWARF · libnccom.so · BuildID 9c00176c… + libnccom-net.so · BuildID 3415f096… · NCCL-fork collectives (dlopen'd, NOT DT_NEEDED) · libnds.a · datastore static lib (6 neuron_ds*.c.o members, compiled once and linked into libnrt.so).

Part XVI — Appendices / REFERENCE · Evidence grade: every source-TU cell is a verbatim DWARF DW_AT_name path from libnrt.so's .debug_info (331 compile units, comp_dir = /opt/workspace/KaenaRuntime/build/private/develop/almalinux/RelWithDebInfo); every binary boundary is from readelf -d/-V and the dlopen string table.

Abstract

This page is the master jump table of the book. Every other page documents one subsystem in depth; this matrix answers the orthogonal question — "I need subsystem X: which binary is it in, which translation unit implements it, and which page covers it?" — in a single lookup. The columns are deliberately the four coordinates a reimplementer needs before opening any deep page: the Part (where the book files it), the subsystem, the binary it lives in, the source TU(s) recovered from DWARF, and the exact wiki page path. Each row carries a Confidence tag because the binary→TU→page mapping is itself reverse-engineered: a row is HIGH when a DWARF compile-unit path is cited verbatim by a coverage cell, MEDIUM when the TU is name-matched only by basename or folded into a neighbour CU by -O2 inlining, and LOW when the binary is present but carries no DWARF (libncfw.so, libnrtucode_extisa.so) so the TU column is structural, not address-grounded.

The wiki is dual-organized, and this matrix is the index across both organizations. One axis is the subsystem Part (Parts I–XV group code by what it does — silicon model, model loading, collectives, profiling), and the row order below follows it. The other axis is the binary lane (Part II is the libnrt.so forensics lane; Part III is the kernel-driver .ko lane; Part X/XI/XII are the firmware/microcode/NCCL-fork binary lanes). A subsystem can appear on both axes — the datastore is a one-page map in the Part III kernel lane (kernel/datastore.md) and a four-page deep treatment in its own Part XIV (datastore/*), because the counter plane straddles the .ko and libnds.a. The ## Dual-Organization note at the foot of the page enumerates those straddles so a reader who lands on one face can find the other.

Binary legend

NOTE — the on-device collectives algorithm engine (enc_*/alg_ring/kangaring/mesh/rdh) is statically embedded inside libnrt.so (the enc/ and tdrv/encd/ CUs), NOT in libncfw.so or libnccom.so. Only the multi-node transport crosses the dlopen boundary into libnccom.so. Do not assume "collectives" == "the dlopen'd lib"; most of the collective compute is in libnrt.so itself — see Part IX vs Part XII below.

How to read a row

binary is where the code executes. source TU(s) is the DWARF DW_AT_name path under /opt/workspace/KaenaRuntime/ (first-party) or the vendored/.ko/firmware origin. wiki page is the exact SUMMARY.md path — every cell below is a real, shipped page. A + between TUs lists co-implementers of one subsystem; a TU listed under two Parts means the book splits one TU's surface across two pages (e.g. nrt_profile.cpp → inspect-profile API in Part XIII).

Part 0 — Reference Apparatus

Part I — Silicon & Architecture Model

NOTE — the silicon model is recovered from libnrt.so's per-arch fan-out (cayman/mariana/sunda), not from the .ko. The three *ArchHeaders Brazil packages (CaymanArchHeaders-1.0.826.0, MarianaArchHeaders-1.0.1133.0, SundaArchHeaders-1.0.1851.0) version-stamp the register layouts these TUs compile against but carry no functions.

Part II — Binary Anatomy & Forensics (libnrt.so)

Part III — Kernel Driver (DKMS, GPL Source)

Every row in this Part lives in aws-neuronx-dkms 2.27.4.0 (neuron.ko); the source TUs are kernel .c files from the GPL DKMS tree, not the libnrt.so DWARF set. Listed by page; TUs given where the GPL filename is known.

NOTE — the kernel TU filenames are reconstructed from the GPL DKMS source tree, not from libnrt.so DWARF (the .ko is a separate binary). The KaenaHal-2.31.0.0 al_hal_*/aws_hal_* DHAL has NO compile-unit in libnrt.so — it is kernel/driver-side; its strings reach libnrt.so only through inlined assert headers. That negative DWARF evidence is what assigns DHAL to the Part III .ko lane, not the Part IV userspace lane.

Part IV — Userspace Runtime Core (libnrt.so)

QUIRK — runtime/ndl.md documents code that is in libnrt.so but is not first-party: ndl.c (123 fns) is the vendored KaenaDriverLib-2.27.4.0 userspace driver shim, statically linked in. The same package's kernel-side counterpart is the .ko IOCTL plane (Part III). The nec_* reverse-callbacks from libnccom.so tail-call into this NDL layer (e.g. nec_get_device_count → jmp ndl_available_devices).

Part V — Model Format & Loading (NEFF / KBIN)

Part VI — TPB Instruction Set: Encoding & Validation

Part VII — Execution Engine

Part VIII — DMA & Descriptor Engine

Part IX — On-Device Collectives (enc / encd / cc_op)

The collective compute engine is statically embedded in libnrt.so (enc/ = 52 CUs / 1,062 fns; tdrv/encd/ builders). The multi-node transport (libnccom.so) is Part XII.

GOTCHA — the per-event switch-platform collective TUs (enc/switch_platform/events/* and ops/*, 31 small .cc files: 20 events + 11 ops) are template-instantiated and -O2-inlined: addr2line on their low_pcs resolves to STL header frames, so the ENC-ALG coverage cells folded them into enc.cc/enc_primitive.cc by address without naming the event TU. collectives/switch-broadcast-barrier.md and collectives/algorithm-taxonomy.md are the owning pages, but the per-event source filenames (e.g. intra_chip_broadcast_event.cc, proxy_buff_supported_local_reduce_event.cc) are a known source-map gap — see the CORRECTION below.

Part X — Collectives Firmware (libncfw)

libncfw.so has NO DWARF; TU column is structural (embedded-blob layout, recovered by binary analysis), hence LOW/MEDIUM confidence.

Part XI — GPSIMD / Q7 Microcode & ISA

libnrtucode_extisa.so has NO DWARF; the libnrt.so-side facade (ucode.c) does.

Part XII — Multi-Node Collectives: libnccom (NCCL Fork)

The transport lib + its libnrt.so-side bridge. libnccom.so is dlopen'd; the bridge trampolines (ncclX → neuronX dlsym pointers) live in libnrt.so.

NOTE — every libnccom.so/libnccom-net.so TU cell is (separate pkg): those binaries ship in aws-neuronx-collectives, absent from the runtime-lib extract, so their internal TUs are unverified (Confidence ≤ MEDIUM). The one HIGH row is nccom/abi.md — the boundary is fully observable from libnrt.so's import/dlsym table and the 16 exported nec_* reverse-callback thunks.

Part XIII — Profiling, Trace & Telemetry

NOTE — the trace producers split across origins inside one binary: the C API + protobuf serializer is first-party C++/KaenaProfilerFormat (nrt/nrt_*, ntff.pb.cc), while the capture/serialize engine is the first-party AWS neuron_rustime Rust crate (NOT vendored — it has no index.crates.io path). The Rust rows are MEDIUM because the cgu-merged Rust CUs do not expose per-function source TUs the way the C++ CUs do.

Part XIV — The Neuron DataStore (NDS)

The datastore straddles two binaries: per-process slabs in the .ko, the userspace accessor lib libnds.a (== the nds/ first-party CUs, statically linked into libnrt.so).

QUIRK — libnds.a is the only one of the six listed binaries that is not an independent runtime artifact: its 6 neuron_ds*.c.o members are compiled once and folded into libnrt.so, so its functions appear in libnrt.so's DWARF under nds/. It is catalogued separately because the same source is what the build links, and because the counter plane it implements is shared with the .ko's per-process slabs.

Part XV — Security & Attack Surface (White-Hat)

These pages are cross-cutting analyses, not new code; the binary/TU columns point at the subsystems they audit.

Part XVI — Appendices

Dual-Organization — subsystem Part vs binary lane

The book files the same physical code under two complementary schemes; a subsystem reached via one will often have a deeper or shallower face under the other. The straddles a reader should know:

CORRECTION (F-SRCMAP §4b) — the per-event switch-platform collective TUs (enc/switch_platform/events/*.cc, e.g. intra_chip_broadcast_event.cc, proxy_buff_supported_local_reduce_event.cc, intra_rank_dimr1w_event.cc, and ~13 peers) are a genuine source-map gap: they have real DWARF compile units but, being template-instantiated and -O2-inlined, no coverage cell names them — they are folded by address into enc.cc/enc_primitive.cc. Their owning pages are collectives/switch-broadcast-barrier.md and collectives/algorithm-taxonomy.md, but the source filename → page link for these specific TUs is asserted by directory membership, not by an address-grounded cite. Treat those event-TU rows (covered collectively under the Part IX switch-platform entries) as the lowest-confidence first-party mappings in this matrix.

Cross-References

• Symbol-Version Manifest — the NRT_2.0.0 / NRT_3.0.0 .gnu.version_d nodes and the dlopen'd libnccom boundary that the collectives rows reference
• Source-Tree Reconstruction (KaenaRuntime) — the full first-party TU inventory (203 CUs / 4,407 fns) that the source-TU column draws from
• ELF Anatomy — the DT_NEEDED list, DWARF presence, and section table that ground the binary legend
• Vendored-Library SBOM — the version pins for the 122 vendored CUs (Abseil, protobuf, Rust, libarchive, zlib, simdjson) that appear as (+ vendored …) in the source-TU cells