The Corpus, Tiers & Binary Inventory

This page is the SHA-pinned, role-annotated catalogue of every artifact this reference is built on. Its job is narrow and absolute: a reader who meets any claim anywhere in the guide should be able to come here, find the exact file that backs it, and re-hash that file on their own disk to confirm they are looking at the same bytes. Nothing here is interpretation — it is the index of witnesses. The interpretation lives in the subsystem pages; this page only says what exists, where, how big, and what each thing is ground-truth for.

Everything was recovered by static analysis of shipped, redistributable binaries, headers, config files, and TIE artifacts — no runtime trace, no debugger session, no design document. Two Debian packages and their nested toolchain tarball are the entire primary corpus. Two sibling reverse-engineering corpora are used only for cross-checks. A wave of 677 internal analysis reports is derived output, not a primary artifact, and is catalogued as such at the end.

Every count and size on this page was re-derived directly from the files on disk this pass (sha256sum, stat -c%s, file, nm, readelf), not copied from a report. Where a count matters, it is tagged [CONF/PROV] per the Confidence & Walls Model, and counts taken from a symbol table say so explicitly — symbol-table counts via nm, never a grep over decompiled text, because decompile-grep inflates opcode/leaf tallies two-to-twelve-fold.

1. The tier model

Artifacts are graded by how directly they ground a claim — the shorter the chain from a statement back to a byte, the higher the tier. A reimplementer encoding a hard requirement wants a T0 witness; a T3 report is a pointer to one, never a substitute.

The decisive property of the gpsimd corpus is that several T0 artifacts are executable oracles, not just readable data. libfiss-base.so answers "what value does this opcode produce?" by running, and libcas-core.so answers "how many cycles?" by running (behind a license gate). That is why this reference reaches OBSERVED-by-execution — the strongest tier of fact short of silicon — and it is why the oracle DLLs sit at the top of the T0 list below.

2. The primary corpus at a glance — two packages, one tarball

Everything T0 arrives in two Debian packages plus the toolchain tarball nested inside the second. [HIGH/OBSERVED]

The package versions are themselves OBSERVED facts (they are the directory names of the extracted trees). The customop package is 0.21.2.0; the tools package is 0.21.0.0-bc9b5fad5. Treat the build suffix bc9b5fad5 as the tools-package build id.

Path convention for this page. All T0/T1 paths are written relative to the corpus root neuronx-gpsimd/. The two extracted package roots are abbreviated:

• CUSTOMOP/ = extracted/aws-neuronx-gpsimd-customop-lib_0.21.2.0_amd64/opt/aws/neuron/gpsimd/custom_op/
• TOOLS/ = extracted/nested/gpsimd_tools_tgz/tools/

extracted/ is git-ignored; locate files there with fd --no-ignore or an absolute path.

3. T0 — Device firmware (the Vision-Q7 images)

These are the artifacts that carry the actual GPSIMD device code. The firmware that runs on the Q7 DSP is not a standalone file — it is a set of ELF32-Xtensa images embedded as .rodata data inside two host-side x86-64 wrapper libraries, exposed through …_SO_get / …_JSON_get accessor symbols. That is the single most important structural fact a reimplementer must internalise here, and the inventory makes it explicit.

SHA-256 of the two firmware .so wrappers (re-hashed this pass):

• libnrtucode_internal.so = b7c67e898a116454a8e0ce257b1d6523a23ffa237a6ec21021ecb70632fc329b
• libnrtucode.so = 06d3f0b1630e38828ace79d3c9f3123ac14b3ea4c5cde4aa906a31b3e82ccce5
• libnrtucode.a = 158dadc5c76dc0491b9243091458b43c2d59091ba3ba5a727206915bd7bd6130

Counts re-derived this pass (all [HIGH/OBSERVED]):

• libnrtucode_internal.so has 946 total .symtab symbols (nm | wc -l) and 66 …_EXTISA_*_(SO|JSON)_get accessor symbols. Per-codename …_SO_get image getters: 1 SUNDA, 4 CAYMAN, 4 MARIANA, 4 MARIANA_PLUS, 4 MAVERICK = 17 (the JSON-twins double this to 34 getter symbols).
• Embedded ELF32-Xtensa device images, counted by scanning \x7fELF magic and reading e_machine: 16 in libnrtucode_internal.so, 12 in libnrtucode.so — a corpus device-image total of ≈28–29. The combined figure of 29 embedded ELF32-Xtensa device blobs is the cross-page anchor used in How to Read This Guide. [HIGH/OBSERVED] for the per-library 16/12; [HIGH/CARRIED] for the aggregate 29 (spans both libs).
• The device firmware is compiled -fno-rtti: _ZTI/_ZTV/_ZTS symbol count = 0 in the wrapper, confirming no C++ class hierarchy is recoverable from the device side. [HIGH/OBSERVED]

NOT-PRESENT in this checkout — named but absent

The following are referenced in the broader Neuron literature but do not exist as files in this corpus; any page that needs them must say so and treat the claim as CARRIED or walled. Marking them prevents fabrication.

4. T0 — The ncore2gp oracle DLLs (decode, value, timing)

These nine host x86-64 DLLs under TOOLS/ncore2gp/config/ are the most valuable artifacts in the corpus, because they are not merely readable — they are the Vision-Q7 model, callable in-process. They are all not stripped (they retain a full .symtab; none carries DWARF .debug_* sections — "not stripped" here means named symbols, not source-line debug info). [HIGH/OBSERVED]

Alongside the DLLs, the config directory ships the plain-text core description that the DLLs are built from — these are themselves T0:

The complete TIE description in human-readable form is not in the config dir but under TOOLS/ncore2gp/control/TIE/: Xtensa.xml (45 533 206 B — the TIE-XML) and Xtensa.tl (112 537 066 B — the TIE source). These are the fourth independent ISA witness (alongside libisa-core, the arch-ISA headers, and the embedded images). [HIGH/OBSERVED]

Re-derivation note on opcode/leaf counts. A naïve rg -c 'OPCODEDEF' or rg -c 'Opcode' over a symbol dump returns ~15 700 — that is inflated noise: there is no literal OPCODEDEF symbol or string in libisa-core.so at all. The honest, useful figures are the 864 module__xdref_ value leaves in libfiss-base.so and libisa-core.so's decode-table export namespaces, both nm-grounded. Do not cite the grep number. [HIGH/OBSERVED]

5. T0 — Arch-ISA headers, instruction maps, and register/address artifacts

The cleartext per-generation specification. Five generations are represented, in two distinct naming families — a fact a reimplementer must not flatten:

• The four unified generations ship as CUSTOMOP/c10/include/neuron_<gen>_arch_isa/ (aws_neuron_isa_* headers), for <gen> ∈ {sunda, cayman, mariana, maverick}.
• Tonga (v1) is the pre-unified outlier: it ships separately as CUSTOMOP/c10/include/arch-headers/tonga/ (215 files) and the older arch-isa/ tree (63 files, aws_tonga_isa_* headers). It is not one of the four neuron_<gen>_arch_isa/ sets. [HIGH/OBSERVED]

Each instruction_mapping.json has top-level keys {struct2opcode, struct2pseudo_opcode} (struct2pseudo_opcode = 2 in every gen). The monotone climb 89→99→108→114 is the OBSERVED per-generation opcode growth. The cayman map hashes to 4e9c1f6abe0d015d… (re-verified this pass). [HIGH/OBSERVED]

The core-kind enum that ties these names to firmware is read directly from libnrtucode_internal.so strings: NRTUCODE_CORE_{SUNDA,CAYMAN,MARIANA,MARIANA_PLUS,MAVERICK}_NX_POOL — 5 NX-POOL core kinds. (The plain libnrtucode.so assert lists only the first four; the _internal variant lists all five.) [HIGH/OBSERVED]

Register / CSR / address-map artifacts

[HIGH/OBSERVED] on every size/path above (re-stat-ed this pass). Note: the al_address_map_db.pkl lives in the maverick customop arch-headers, not in the cayman-arch-regs tarball — both are catalogued above so the distinction is explicit.

6. T0/T1 — The native Xtensa toolchain (the device disassembler)

The corpus ships a complete, runnable Xtensa toolchain under TOOLS/XtensaTools/ (55 tools in bin/). The single most useful tool for this reference is the device disassembler:

The toolchain also carries the LLVM-10 Xtensa backend (libLLVMXtensaCodeGen.so.10, libXtensaCodeGen.so, xt-clang/xt-clang++) and ~10 ISS variants of libsimxtcore.so (per-GCC/clang build). The firmware itself records two build identities: XtensaTools-14.09 / clang-10 (older generations) and XtensaTools-15.05 / clang-15 (Maverick). [HIGH/OBSERVED]

Host analysis tooling (used on the x86-64 side)

Plain GNU objdump / nm / readelf / sha256sum are used directly on the host-side ELFs. All symbol counts on this page are nm on the binary, never a grep over decompiled C. The Toolchain Inventory & Versions page details exact versions; the Methodology page details how the oracles are driven in-process.

7. T1 — The IDA sidecar JSON set

For each analysed T0 ELF, an IDA pass produces a directory of sidecar artifacts under ida/<mangled-target>/. 12 binaries in this corpus carry a full IDA database (.i64); the domain-relevant ones are libnrtucode_internal.so and libnrtucode.so (the remaining ten are the bundled third-party libcrypto/libssl/libsqlite3/libbz2/liblzma/libz/libffi and the OpenSSL engines-1.1/*.so providers — not GPSIMD device code, listed only to account for the 12). [HIGH/OBSERVED]

Per target, the sidecar set provides (25 JSON kinds + binary/text dumps):

When a sidecar and the T0 binary disagree, the binary wins — the sidecar is a lens, not a source. [HIGH/INFERRED]

8. T2 — Sibling cross-check corpora

Three independently-shipped Neuron corpora live in the same repo tree and are used only to corroborate a gpsimd-internal fact from a separate build — never as the sole source of one. [HIGH/OBSERVED] (presence re-checked this pass.)

9. T3 — The 677-report raw/ wave (derived analysis, not a primary artifact)

The raw/ directory holds 680 entries — 677 .txt analysis reports + 3 data files (E007_native_link_graph_edges.tsv, W028_package_payload_tree_atlas.tsv, W031_ida_sidecar_manifest_catalog.jsonl). This wave is derived output of T0/T1 analysis — it is documentation, not a witness. A CARRIED claim cites a report here; to become OBSERVED it must trace through to the T0/T1 file the report was built from. [HIGH/OBSERVED] (census re-counted this pass.)

Breakdown by report family:

Reconciliation against the binaries (why the FILE wins). Several T3 reports state large counts that are broader censuses than this page's headline figures, and that is fine as long as the granularity is named. The clearest example: the ELF-fingerprint report (W030) counts libfiss-base.so as having 40 758 exports (of which slotfill:25138); this page cites 864 value leaves. Both are true — 864 is the nm-counted module__xdref_* per-element value-function count (the reimplementer's "how many opcode value semantics" number), while 40 758 is the whole export table including slotfill/regload/writeback rows. When a report's number and a re-nm'd number disagree on the same quantity, this page uses the binary's number. [HIGH/OBSERVED]

10. Lawful-interop posture

Every result in this reference is the product of static analysis only — reading, hashing, disassembling, and (for the freely-callable value/decode oracles) executing in-process — of already-shipped, redistributable AWS Neuron packages. No vendor source tree was used; no design document was consulted; no proprietary firmware was decrypted or circumvented. The wiki is authored under the interoperability research exemption of 17 U.S.C. § 1201(f) (and the analogous EU software-directive provisions): the sole purpose is to document the interfaces and behaviour necessary to build an independently interoperable Vision-Q7-compatible GPSIMD engine, toolchain, runtime, or simulator. The cycle/timing oracle (libcas-core.so) is described only at the level its retirement path is gated by a FlexNet license check (AUTH::check_iss_licenses) — no license circumvention is performed or documented; the license wall is reported as a wall (see the Confidence & Walls Model), not crossed. The freely-callable value lane (libfiss-base.so) requires no license and is the only oracle this reference executes.

Cross-references

• How to Read This Guide — the 13-host-library / 29-device-blob framing and the page-anatomy conventions this inventory feeds.
• The Confidence & Walls Model — the [CONF/PROV] tag system every count here uses, and the file-absent walls (libnrt.so, v5 Q7_CC_TOP) this page records.
• Methodology — How This Was Reverse-Engineered — how the T0 oracle DLLs are driven in-process to turn OBSERVED into OBSERVED-by-execution.
• Toolchain Inventory & Versions — exact versions of the native Xtensa toolchain and host analysis tools named in §6.
• Codename ↔ Generation Cross-Walk — the five-codename axis the §5 header sets and §3 core-kind enum are keyed on.
• The planned Bibliography of Source Binaries appendix is the formal, fully-hashed citation list this page's working inventory feeds into.