Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Extraction Status

Binaries pinned on this pagelibnrt.solibnrt.so.2.31.24.0 (aws-neuronx-runtime-lib 2.31.24.0-0b044f4ce, BuildID 8bb57aba0fb2e0035f1d88e9fc4fb3e7387c102e, ELF64 DYN x86-64, not stripped, full DWARF v4); libnccom.so.2.31.24 (aws-neuronx-collectives 2.31.24.0-1a31ba186, BuildID 9c00176c081788c9435d27d11bb40e92495463f0, not stripped, .debug_info); neuron.ko (aws-neuronx-dkms 2.27.4.0, GPL-2.0 C source authoritative, binary stripped); libncfw.so (SONAME libncfw.so.2.31.1.0.cf13a49f, BuildID a98f8e1ca2294582835310c3a1092e0a5e500db5, no DWARF); libnrtucode_extisa.so (BuildID 7bb03bc42ce1530924a1797ec9d5e518a7ae5e44, stripped, no DWARF); plus the static archive libnds.a (6 TUs, 810,674 B, the same code linked into libnrt.so).

Part 0 — Reference Apparatus / REFERENCE · Evidence grade: this page grades other pages; its own claims are the per-page status tags carried in each cited page's own header blockquote, plus the DWARF coverage facts from the source-map and heavy-frame census re-run against these binaries · back to index

Abstract

This is the book's honest self-assessment. Every other page asserts a confidence in its own header — "Reimplementation-grade", "byte-anchored", "boundary edge" — but a reader landing on one page cannot see how the whole stack lines up: which subsystems are decoded to the byte and which are an opaque blob with a name stuck on it. This page is that ledger. It assigns one of three evidence grades to every shipped page and to every subsystem cluster, names the principal gap that keeps each cell below the top grade, and routes the genuinely-opaque items to the Phase-3 Deep-Dive Backlog. It is a catalogue: its quality is the completeness and the honesty of the map, not new derivation.

The three grades are deliberately coarse. Byte-level decoded (reimplementation-grade) means a competent engineer could rebuild the artifact — wire format, ISA encoding, struct layout, algorithm — from the page alone, because the bytes were read and the decision logic recovered. Surface-mapped means the role, call surface, and inputs/outputs are pinned but at least one interior is not decoded to the byte: a config TU with no recovered static caller, a serializer with no DWARF, an upload path summarized rather than re-derived. Not-traced means the page is honest about an opaque region — a sequencer-internal microcode op, a per-arch leaf body left at a name, an interior math kernel that was sized but not walked. The grade is the floor of the page: a page that is byte-level on its main artifact but leaves one helper opaque is graded by what a reimplementer still cannot rebuild. Two of the five binaries — libncfw.so and libnrtucode_extisa.so — carry no DWARF and (for extisa) no symbols at all, which sets a hard ceiling on every page that depends on them; that ceiling is named explicitly in §5.

NOTE — "surface-mapped" is not a failure grade. For vendored OSS (protobuf, Abseil, simdjson, libarchive, zlib, the Rust crates) surface-mapping is the correct terminal state — a reimplementer links the pinned version rather than reversing the arena allocator. Those rows are graded by whether the boundary (which symbols, which version, what they back) is decoded, not the library interior. The version pins live in the vendored SBOM; this page does not re-grade them.

Grade legend

GradeMeaningWhat it implies for a reimplementer
byte-levelWire format / ISA / struct / algorithm decoded to the byte; decision logic recoveredRebuild from the page alone; cross-check against the cited address/offset
surface-mappedRole, call surface, inputs/outputs pinned; ≥1 interior not byte-decodedReproduce the boundary; the interior needs the binary (or, for OSS, link upstream)
not-tracedAn opaque region named honestly — sized but not walked, or no DWARF/symbolsTreat as a black box at the named boundary; routed to the deep-dive backlog

1. Per-Part coverage table

One row per shipped page, grouped by Part; the SUMMARY path is exact. Grade is the page floor per the legend. Status is a one-phrase state; Principal gap names the single thing that keeps the cell below byte-level (— if none). Conf grades this assessment of the page, not the page's own internal claims.

Part 0 — Reference Apparatus

Page (src/…)GradeStatusPrincipal remaining gapConf
front/how-to-read.mdbyte-levelconventions fixedHIGH
front/five-binaries.mdsurface-mappedbinary identity mapper-binary depth lives downstreamHIGH
front/inference-walkthrough.mdbyte-levelworked exampleHIGH
methodology.mdbyte-levelmethod fixedHIGH
front/codename-cheatsheet.mdbyte-levelcodename↔arch pinnedHIGH
front/source-tree.mdbyte-level331 DWARF CU tree31 switch-platform events/+ops/ TUs, of which 13 are the per-event composer TUs (broadcast/reduce) name-gapped, the rest op-selectors (all fn-covered)HIGH
glossary.mdbyte-levelterms fixedHIGH
front/bibliography.mdsurface-mappedexternal refsHIGH
reference/binary-layout.mdbyte-levelsection/segment mapHIGH
reference/extraction-status.mdthis page

Part I — Silicon & Architecture Model

PageGradeStatusPrincipal remaining gapConf
arch/overview.mdsurface-mappedruntime-lens modelHIGH
arch/generations-enum.mdbyte-levelV2/V3/V4 enum decodedHIGH
arch/pci-device-ids.mdbyte-leveldevice-ID→arch tableHIGH
arch/hw-geometry.mdbyte-levelper-gen geometry constsHIGH
arch/coretype-numbering.mdbyte-levelthe +1 off-by-one resolvedHIGH
arch/memory-hierarchy.mdbyte-levelBAR/SBUF layoutHIGH

Part II — Binary Anatomy & Forensics

PageGradeStatusPrincipal remaining gapConf
forensics/overview.mdbyte-levelheavy-frame censusHIGH
forensics/elf-anatomy.mdbyte-levelELF tables readHIGH
forensics/vendored-sbom.mdbyte-levelversions pinned; library interiors intentionally not reversedOSS interiors out of scope by designHIGH
forensics/static-init.mdbyte-level77 ctors mappedHIGH
forensics/globals-atlas.mdbyte-levelsingleton atlasHIGH
forensics/dispatch-tables.mdbyte-leveldispatch taxonomyHIGH
forensics/rtti-class-hierarchy.mdbyte-levelRTTI graphHIGH
forensics/string-domain.mdbyte-levelstring surfaceHIGH
forensics/crt-plt.mdbyte-levelPLT/loader surfaceHIGH

Part III — Kernel Driver

Page clusterGradeStatusPrincipal remaining gapConf
kernel/overview.mdkernel/ioctl-pod.md (probe, cdev, IOCTL dispatch+catalog, mem/dma/nq/pod handlers)byte-levelGPL C source read directlyline-anchored, not REHIGH
kernel/mempool-handles.md, dma-op-layer.md, dma-rings.mdbyte-levelDMA/handle modelHIGH
kernel/udma-main.md, udma-m2m.md, udma-iofic.mdbyte-levelUDMA fork (GPL C)HIGH
kernel/dhal-core.md, dhal-v2.md, dhal-v3.md, dhal-v4.mdbyte-levelDHAL v2/v3/v4 bodies decodedHIGH
kernel/notification-queues.md, topsp.md, reset.md, crwl.md, pod-election.mdbyte-levelNQ/reset/lock/electionHIGH
kernel/fw-io.md, dmabuf-p2p.md, datastore.md, metrics.md, sysfs.md, power.md, misc.mdbyte-levelmailbox/p2p/telemetryHIGH

Part IV — Userspace Runtime Core

Page clusterGradeStatusPrincipal remaining gapConf
runtime/overview.md, api-lifecycle.md, api-device-config.md, api-tensors.md, api-async-collectives.mdbyte-levelpublic C API surfacethunks forward to impl TUsHIGH
runtime/config-structs.md, env-vars.mdbyte-levelnrt_config + NEURON_RT_* tableHIGH
runtime/error-codes.mdbyte-levelpriority classifier + error catalogueHIGH
runtime/interned-strings.mdbyte-levelstring DBHIGH
runtime/tdrv-lifecycle.md, tdrv-dmem.md, tdrv-dma-rings.md, tdrv-scratchpad.md, tdrv-tensor.md, tdrv-arch-ops.mdbyte-levelTDRV coreHIGH
runtime/arch-geometry.mdsurface-mappedper-arch geometrysbuf_base_for_core leaf bodies MEDHIGH
runtime/arch-csr-offsets.md, arch-notification.md, arch-sdma.md, arch-stpb.mdbyte-levelper-arch CSR/INTC/SDMA/STPBHIGH
runtime/hal-adapter.md, hal-tpb-shims.md, hal-registers.mdbyte-levelKaenaHal adapter/shimsHIGH
runtime/hal-udma-iofic.mdsurface-mappedHAL UDMA build + IOFIC17/24 al_hal_udma_config fns no static callerHIGH
runtime/logging.md, device-book.md, ndl.mdbyte-levelnlog / db / NDL shimHIGH

Part V — Model Format & Loading

Page clusterGradeStatusPrincipal remaining gapConf
neff/overview.md, container.md, metadata-schema.md, section-taxonomy.md, dtype-system.mdbyte-levelNEFF=gzip-tar + JSON schemaHIGH
neff/kelf2kbin.md, kbin-structs.md, memory-planning.md, compute-resource-build.md, load-pipeline.mdbyte-levelKBIN lowering + KBL buildhuge per-fn parse leaves (sized)HIGH

Part VI — TPB Instruction Set

PageGradeStatusPrincipal remaining gapConf
isa/overview.mdbyte-levelengine instruction modelHIGH
isa/pseudo-instruction-lowering.mdbyte-levelSP/TopSP buildersHIGH
isa/instruction-record.mdbyte-level64-byte record formatHIGH
isa/fp8-dtype-encoding.mdbyte-levelFP8/dtype encodingHIGH
isa/validator-architecture.mdbyte-levelvalidator entry treeHIGH
isa/validators-per-arch.mdbyte-levelper-arch validator deltassome encd interior math not walkedHIGH

Part VII — Execution Engine

PageGradeStatusPrincipal remaining gapConf
exec/overview.md, kmgr-facade.md, xu-workers.md, submit-path.md, completion-engine.md, xu-queue-abi.mdbyte-levelsubmit/harvest path + ABIHIGH

Part VIII — DMA & Descriptor Engine

PageGradeStatusPrincipal remaining gapConf
dma/overview.mdbyte-levelDMA engine mapHIGH
dma/descriptor-format.mdbyte-level16-byte descriptor decodedHIGH
dma/meta-ctrl-overlays.mdbyte-levelSDMA/CCE/TDG overlaysHIGH
dma/ring-cycle.md, virtual-rings.md, iofic.mdbyte-levelring/vring/IOFICHIGH

Part IX — On-Device Collectives

Page clusterGradeStatusPrincipal remaining gapConf
collectives/overview.md, engine-core.md, comm-context.md, nccl-boundary.mdbyte-levelenc context + libnccom boundaryHIGH
collectives/algorithm-taxonomy.md, mesh-composer.md, ring-scheduling.md, hierarchical-rdh.md, enc-primitives.mdbyte-levelmesh/ring/hier/RDH composerscomposer methods are line sinks (sized)HIGH
collectives/switch-broadcast-barrier.mdsurface-mappedswitch-platform events13 per-event composer TUs name-gapped (fn-covered)MEDIUM
collectives/topology-partition.mdbyte-levelunion-find partitionerHIGH
collectives/proxy-driver.md, send-recv.mdbyte-levelbananaphone IPC + async P2PHIGH
collectives/cc-op-isa.mdbyte-levelcc_op_entry on-device ISAHIGH
collectives/channel-descriptor.mdbyte-level148-byte channel descriptorHIGH
collectives/encd-overview.md, encd-dma-devmem.md, encd-sema-topsp.md, encd-arch-ops.mdbyte-levelencd emitter (per-arch)HIGH

Part X — Collectives Firmware (libncfw)

PageGradeStatusPrincipal remaining gapConf
firmware/overview.md, carrier-library.mdsurface-mappedcarrier mapno DWARF (see §5)HIGH
firmware/embedded-payloads.mdbyte-level8 Xtensa blobs carved + fingerprintedHIGH
firmware/serializer-families.mdsurface-mappedper-arch CC-context dumpersserializer interiors — no DWARFMEDIUM
firmware/ncfw-sequencer.mdsurface-mappedXtensa-LX disassemblysequencer-internal ops not fully tracedMEDIUM
firmware/upload-path.mdsurface-mappedDKMS→DRAM uploadDMA-descriptor algebra summarized, not re-derivedHIGH

Part XI — GPSIMD / Q7 Microcode & ISA

Page clusterGradeStatusPrincipal remaining gapConf
gpsimd/overview.md, xtensa-vision-q7.md, xtensa-toolchain.mdbyte-levelQ7 identification + TIE configHIGH
gpsimd/extisa-provider.md, dispatch-tables.md, ucode-facade.mdbyte-levelnrtucode_* API + dispatch + dlopen facadeextisa binary stripped (boundary only)HIGH
gpsimd/microcode-loader.mdbyte-levelRELA+FLIX UCPL loaderHIGH
gpsimd/q7-blobs.mdbyte-level13 Q7 blobs carvedsequencer-internal TIE ops in microcode not-tracedHIGH
gpsimd/ivp-isa-catalog.mdbyte-level1065 ivp + 469 scalar = 1534 mnemonics, 12569 placementsHIGH

Part XII — Multi-Node Collectives (libnccom)

Page clusterGradeStatusPrincipal remaining gapConf
nccom/overview.md, comm-init.md, topology.md, algorithm-ring.md, algorithm-tree.md, send-recv-prims.md, proxy-engine.md, tuning.md, transport-intra.md, transport-efa.md, net-plugin.md, abi.mdsurface-mappedNCCL-fork map (DWARF-bearing)inherited NCCL bodies mapped by delta, not byte-walkedHIGH

Part XIII — Profiling, Trace & Telemetry

Page clusterGradeStatusPrincipal remaining gapConf
trace/overview.md, inspect-profile-api.md, system-monitor.mdbyte-levelthree trace producersHIGH
trace/ntff-format.md, ntff-wire-tables.mdbyte-levelntff.proto wire tables decodedHIGH
trace/event-taxonomy.mdbyte-level46 SysTraceEventType variantsHIGH
trace/rust-capture.md, rust-serde.md, rust-ffi.mdbyte-levelneuron_rustime capture + serde + FFIRust generics mapped via cgu, not sourceHIGH
trace/telemetry-errors.mdbyte-levelmetrics + error reportingHIGH

Part XIV — Neuron DataStore

PageGradeStatusPrincipal remaining gapConf
datastore/overview.md, kernel-side.md, userspace-libnds.mdbyte-levelcounter plane + libnds.aHIGH
datastore/wire-format.mdbyte-levelNDS wire format decodedHIGH

Part XV — Security & Attack Surface

PageGradeStatusPrincipal remaining gapConf
security/overview.md, ioctl-attack-surface.md, fw-io-trust.md, hardening.mdbyte-levelprivilege-gate model + 14 findingsHIGH

Part XVI — Appendices

PageGradeStatusPrincipal remaining gapConf
appendix/subsystem-matrix.mdsurface-mappedsubsystem↔binary↔TU matrixHIGH
appendix/symbol-versions.mdbyte-levelsymbol-version manifestHIGH
appendix/globals-index.mdbyte-levelglobal address indexHIGH
appendix/known-bugs.mdsurface-mappedanomalies catalogHIGH
appendix/deep-dive-backlog.mdsurface-mappedbacklog (receives §4)HIGH

2. What is byte-level decoded

The artifacts a reimplementer can rebuild from the page alone, each with its owning page. These are the load-tested cores of the book — wire formats read field-by-field, ISA catalogues sized against their own operand tables, struct layouts confirmed against multiple sources.

3. What is surface-mapped (boundary pinned, interior not byte-decoded)

These pages pin the role and call surface but stop short of a byte-level interior — correctly, because the interior either lacks a recovered caller, lacks DWARF, or is upstream OSS a reimplementer should link rather than reverse.

  • Some HAL config TUs — 17 of 24 al_hal_udma_config functions have no recovered static caller in libnrt; their role is known, their invocation context is not → runtime/hal-udma-iofic.md.
  • The libncfw serializer interiors — per-arch CC-context dumpers with no DWARF → firmware/serializer-families.md.
  • Some firmware upload paths — the DMA-descriptor algebra of the DKMS→DRAM upload is summarized, not re-derived → firmware/upload-path.md.
  • The libnccom inherited NCCL bodies — mapped by delta from upstream NCCL 2.31.24+nrt2.0, not byte-walked → nccom/overview.md.

4. What remains opaque (not-traced)

The honest black boxes. Each is named at its boundary and routed to the Phase-3 Deep-Dive Backlog; none is claimed as covered.

Opaque regionWhere it surfacesWhy it is opaqueBacklog route
Sequencer-internal TIE ops in the Q7 microcodegpsimd/q7-blobs.mdcustom Tensilica TIE ops; no public iclass decodedeep-dive-backlog (Q7 microcode)
The NCFW Xtensa sequencer's internal handler opsfirmware/ncfw-sequencer.mdno DWARF; disassembly mapped, internals not fully walkeddeep-dive-backlog (NCFW sequencer)
Per-arch SBUF leaf bodies (sbuf_base_for_core MED)runtime/arch-geometry.mdwindow size byte-pinned; per-core base derivation MEDdeep-dive-backlog (arch leaves)
Some encd interior mathisa/validators-per-arch.md, collectives/encd-overview.mdhuge per-fn bodies sized but not line-walkeddeep-dive-backlog (encd math)
13 switch-platform per-event composer TUscollectives/switch-broadcast-barrier.mdtemplate/STL-inlined; folded into enc.cc by address, never name-citeddeep-dive-backlog (switch-platform events)

GOTCHA — "not-traced" never means "absent from the book." Each opaque region has a page that names its boundary, its inputs, and its callers; what is missing is the byte-level interior. A reimplementer treats the boundary as a contract and the interior as a build-against-the-binary task — not as a hole the book pretends is filled.

5. The no-DWARF ceiling

Two of the five binaries set a hard ceiling that no amount of analysis lifts to byte-level on internal names:

  • libncfw.so (BuildID a98f8e1ca…) carries no DWARF and self-versions in its SONAME (libncfw.so.2.31.1.0.cf13a49f) rather than in .git_hash/.nrt_brazil_version sections. Its public boundary (the libncfw_get_image_func get-image entry, the embedded blob set, the v2 reset prologue) is byte-anchored; its internal serializer and handler names are not recoverable, so those pages are graded surface-to-MED by construction.
  • libnrtucode_extisa.so (BuildID 7bb03bc4…) is stripped — no DWARF and no symbol table. It is reached only as a dlopen target whose 30-entry dlsym binding table names its API surface; everything below that surface is decoded by raw disassembly against the carved blobs, not by symbol.

NOTE — the byte-identity QUIRK that links these two carriers (the SUNDA v2 sequencer boot scaffold ships byte-identically in both, per firmware/upload-path.md) is itself a byte-level fact recovered despite the no-DWARF ceiling — proof that the ceiling caps internal naming, not byte-level structural claims. The grade floor of a no-DWARF page is therefore surface on names but can be byte-level on bytes; the table above grades the names a reimplementer would need, which is the binding constraint.

Cross-References