Source-Tree Reconstruction (KaenaRuntime)

Binary (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.

Part 0 — Reference Apparatus / REFERENCE · Evidence grade: every directory and every translation-unit path below is a verbatim DW_AT_name string read from libnrt.so's own .debug_info (331 DW_TAG_compile_unit records; DW_AT_comp_dir = /opt/workspace/KaenaRuntime/build/private/develop/almalinux/RelWithDebInfo; DW_AT_producer = GNU C++17 14.2.1 20250110 -O2 -fPIC -ggdb3). The tree is reconstructed from the shipped binary, not transcribed from any source distribution.

Abstract

libnrt.so ships with full DWARF, and every object it was built from leaves one DW_TAG_compile_unit record carrying its source path in DW_AT_name and a common build root in DW_AT_comp_dir. Reading that compile-unit table back yields the first-party source tree without ever seeing the source: 203 KaenaRuntime translation units (.c / .cc / .cpp), grouped under thirteen subsystem directories rooted at /opt/workspace/KaenaRuntime/, defining 4,407 functions with their own DW_TAG_subprogram body (a DW_AT_low_pc inside the CU, deduped by low_pc). The remaining 128 of the 331 CUs (incl. the 6 zlib-builtin) are vendored object code statically linked in — Abseil, the Rust std/core/alloc runtime, KaenaProfilerFormat protobuf, libarchive, simdjson, zlib, KaenaDriverLib — versioned on the Vendored-Library SBOM and excluded from this page's first-party tree.

This page is the spine for locating which page owns which .c/.cc. It is the directory-tree view of the same translation units the Subsystem Matrix indexes by subsystem Part: where the matrix answers "I need subsystem X, which TU and which page?", this page answers the inverse — "I am holding tdrv/dma_ring.c, where in the book does it live?". The owning-page column below is the exact SUMMARY.md path, kept consistent with that matrix; the subsystem→page logic is not re-derived here, only the directory tree and the per-TU function counts that the matrix draws from. Per-function semantics belong to the deep pages; this is the map, not the territory.

CORRECTION — the CU partition now closes cleanly at 331 = 203 first-party + 128 vendored, where the 128 vendored already includes the 6 zlib-builtin CUs (previously narrated as a separate "+6" addend, which read as 203 + 122 + 6 and obscured the closure). | Largest TU (C) | tdrv/instruction_block_mariana.c — 297 fns | | Largest TU (C++) | enc/enc.cc — 352 fns | | Excluded | 128 vendored CUs, incl. 6 zlib-builtin (→ SBOM); the no-DWARF siblings libncfw.so, libnrtucode_extisa.so |

1. The subsystem directory tree

A compact hierarchical view of the thirteen first-party directories, fn-weighted. Each line is CUs / fns; the full per-TU breakdown is in §2. The per-arch triplication (cayman / mariana / sunda) is real in the DWARF — each silicon gets its own tdrv_arch_*.c, instruction_block_*.c, encd/archs/*.c, and dve_config_*.c.

/opt/workspace/KaenaRuntime/
├─ tdrv/         84 CU / 2413 fn   device driver, DMA, instruction-block builders, per-arch
│   ├─ cayman/    4 CU             arch fan-out: dma_desc_util, isa, tdrv_arch, dve_config
│   ├─ mariana/   2 CU             arch fan-out: tdrv_arch, dve_config
│   ├─ sunda/     4 CU             arch fan-out: isa, tdrv_arch, tsync, dve_config
│   └─ encd/      6 CU             execution-engine descriptor compiler
│       └─ archs/ 3 CU             per-arch encd: arch / cayman / mariana / sunda
├─ enc/          52 CU / 1062 fn   on-device collectives compute engine
│   ├─ async_sr/  7 CU             async point-to-point sendrecv (OFI / rendezvous / kv_store)
│   └─ switch_platform/ 33 CU      switch-fabric collective composer
│       ├─ events/{broadcast,reduce,handshake,sync,function}/   per-event algorithm TUs
│       └─ ops/{all_gather,all_reduce,all_to_all,reduce_scatter}/ op selectors (1–3 fn each)
├─ nrt/          27 CU /  377 fn   public C API + config/profile/sys_trace
├─ kelf/          5 CU /  318 fn   KELF/KBIN/NEFF container parse + numpy/HLO stats
├─ kmgr/         10 CU /  117 fn   model/kernel manager (dlr loader, xu/ worker queue)
│   └─ xu/        4 CU             execution-unit work-queue + worker threads
├─ nds/           6 CU /   36 fn   Neuron DataStore (== libnds.a, folded into libnrt)
├─ ucode/         1 CU /   26 fn   microcode loader glue
├─ utils/         5 CU /   23 fn   md5 / sha256 / instance / time helpers
├─ nlog/          3 CU /   15 fn   logging + backtrace + symbol resolution
├─ ndebug/        1 CU /   10 fn   ndebug_stream
├─ dve_config/    4 CU /    7 fn   DVE (dynamic-vector-engine) config + per-arch
├─ dx/            1 CU /    2 fn   dx/ring.c (notification ring)
├─ hw_decode/     1 CU /    1 fn   hw_decode table glue
└─ build/.../     3 CU /    0 fn   GENERATED blob stubs (*_bins.c: dve / hw_decode / ucode)

NOTE — the directory names are not a convention imposed by this analysis; they are the leading path components of the DW_AT_name strings in .debug_info (e.g. the CU named tdrv/encd/archs/cayman.c). The comp_dir root is constant across all 203 first-party CUs, so a relative path under it is unambiguous.

QUIRK — nds/ (6 CUs) is the static archive libnds.a compiled once and linked in; its six neuron_ds*.c.o members appear in libnrt.so's DWARF as first-party nds/ CUs even though the library is also catalogued as a separate artifact. The counter plane it implements is shared with the kernel .ko — see datastore/userspace-libnds.md.

2. Per-TU inventory

Every first-party translation unit, grouped by directory. fns = DW_TAG_subprogram records with a DW_AT_low_pc inside the CU, deduped by low_pc (defined bodies only; declarations and inlined-away statics do not count). Owning page is the exact SUMMARY.md path consistent with the Subsystem Matrix; a TU whose surface the book splits across pages is listed at its primary owner. Confidence grades the fn-count + owning-page assignment: HIGH when the matrix cites the TU path verbatim; MEDIUM when the page assignment is the best directory/basename fit but the TU is folded into a neighbour CU by -O2, or the count rolls inlined bodies upward.

NOTE — the fn-counts are an -O2 per-CU-of-definition fact: a body inlined into another CU is counted in the CU that owns the out-of-line copy, so a thin public-wrapper TU can show fewer fns than its API surface, and a per-arch builder can absorb its callees' bodies. This is a property of the build, not a miscount.

tdrv/ — 84 CU / 2413 fn

enc/ — 52 CU / 1062 fn

GOTCHA — the 31 enc/switch_platform/events/* and ops/* TUs are template-instantiated and -O2-inlined; addr2line on their low_pcs resolves to STL header frames, so the address-band coverage cells folded them into enc.cc / enc_primitive.cc by address without naming the event TU. Their owning-page cells above (switch-broadcast-barrier.md for broadcast/barrier/handshake/sync, algorithm-taxonomy.md for reduce/op-selectors) are asserted by directory membership, not by an address-grounded source-filename cite — the lowest-confidence first-party rows on this page. This is the same gap recorded in the matrix CORRECTION (F-SRCMAP §4b).

nrt/ — 27 CU / 377 fn

kelf/ — 5 CU / 318 fn

kmgr/ — 10 CU / 117 fn

nds/ — 6 CU / 36 fn

ucode/ — 1 CU / 26 fn

utils/ — 5 CU / 23 fn

nlog/ — 3 CU / 15 fn

ndebug/ — 1 CU / 10 fn

dve_config/ — 4 CU / 7 fn

dx/, hw_decode/, build/ — 5 CU / 3 fn

3. The total and what is excluded

The thirteen subsystem directories plus the build/ blob stubs sum to the 203 first-party CUs / 4,407 defined functions reported in the at-a-glance table. The per-subsystem rollup:

What this tree deliberately excludes:

• The 128 vendored CUs (incl. 6 zlib-builtin) — the other half of the 331-CU table. Their object code is statically linked into libnrt.so's .text (Abseil, Rust std/core/alloc + crates, KaenaProfilerFormat's ntff.pb.cc / neuron_trace.pb.cc, libarchive, simdjson, zlib, KaenaDriverLib's ndl.c), but they are not KaenaRuntime source and are versioned on the Vendored-Library SBOM, not here. The KaenaProfilerFormat protobuf is generated from an AWS-authored .proto, so it lands in the vendored half by origin, not by being third-party OSS.
• The no-DWARF sibling binaries — libncfw.so (collectives firmware carrier) and libnrtucode_extisa.so (GPSIMD/Q7 ext-ISA provider) carry no compile units, so no source tree is recoverable from them; their structure is documented in Parts X–XI from binary layout, not DWARF.
• The kernel .ko (aws-neuronx-dkms) — a separate GPL binary with its own source tree; its TU filenames are reconstructed from the GPL DKMS tree in Part III, not from libnrt.so's DWARF.

NOTE — the DWARF compile-unit count (203 first-party) is the authoritative TU count and supersedes the earlier __FILE__-string-derived figure (221), which counted headers (.h / .hpp) that have no compile unit of their own. The DWARF count is translation units only: a header included by many TUs leaves no CU, so it never appears in this tree.

Cross-References

• Subsystem ↔ Binary ↔ Source-TU Matrix — the same 203 TUs indexed by subsystem Part; the source of every owning-page cell above and the dual-organization straddles
• Vendored-Library SBOM — version pins for the 128 vendored CUs this tree excludes (Abseil, protobuf, Rust, libarchive, zlib, simdjson, KaenaDriverLib)
• Binary Layout — the ELF section/segment census these compile units compile into
• Symbol-Version Manifest — the NRT_2.0.0 / NRT_3.0.0 .gnu.version_d nodes that export the public surface of the nrt/ TUs