Environment Variable Catalog (NEURON_RT_*)

All addresses, offsets, defaults, and env-var spellings on this page apply to libnrt.so from aws-neuronx-runtime-lib 2.31.24.0-0b044f4ce (real file libnrt.so.2.31.24.0, SONAME libnrt.so.1, build-id 8bb57aba0fb2e0035f1d88e9fc4fb3e7387c102e, git 0b044f4ce). The ELF is not stripped and carries full DWARF v4 + a 24,864-entry .symtab; every variable name is read verbatim from NUL-terminated .rodata tokens and every destination field is the DWARF struct member the parse callsite stores into. All PT_LOAD segments are identity-mapped (.text/.rodata/.bss VMA == file offset). All addresses are analysis VMAs. Other versions will differ.

Part IV — Userspace Runtime Core / REFERENCE catalogue · Evidence grade: Confirmed (getenv→field map) — names are verbatim .rodata; destination fields are the lea OFF(%base),%rdx argument joined to the DWARF layout of the two config structs; defaults are the inline 2nd-argument immediate of the typed nrt_config_parse helper where recovered. Rows whose setter is outside nrt_config_parse_init_config are confidence-tagged. · back to index

Abstract

This page is the exhaustive control surface of the Neuron Runtime: every NEURON_RT_* and genuine NEURON_* environment variable the runtime recognizes, anchored to the getenv callsite that reads it and the config-struct field it writes. The runtime ingests its entire environment once, at nrt_init time, inside one master parser — nrt_config_parse_init_config @0x8a1d0 — and freezes the result for process lifetime. The familiar reference frame is a classic parse-once config block (the shape of an OpenMP OMP_* scan or a CUDA CUDA_* ingest), with one structural wrinkle a reimplementer must reproduce: the destination is two distinct structs, and only the base register of the destination lea distinguishes them. The config-structs page owns the field-by-field layout of both aggregates; this page owns the name → callsite → field direction of the same mapping.

The whole 123 MB object imports exactly three libc env primitives: getenv@GLIBC_2.2.5 (PLT 0x3cfd0, 43 call sites), secure_getenv@GLIBC_2.17 (PLT 0x3d9d0, 4 sites — all in vendored std::filesystem::temp_directory_path, not Neuron), and a Rust std::sys::env::unix::getenv closure (1 site, in the neuron_rustime bridge). Almost no NEURON_RT_* var is read at a bare getenv site; instead the master parser builds the variable name as a std::string from a .rodata literal, supplies the default as the helper's 2nd argument, and passes &dest (the 3rd argument, %rdx) pointing into one of the two structs — a typed nrt_config_parse(name, default, &dest) helper then does getenv(name), falls back to the default on miss, and parses into *dest. The destination is either the 656 B static singleton nrt_config (nrt_config_t @.bss 0xc5c480, written nrt_config_0.<field>) or the 296 B heap nrt_global_config (nrt_global_config_t, *ngc @.bss 0xc5c460, read everywhere through nrt_gconf() @0x82670).

A NUL-split .rodata token sweep, cross-checked against the standalone string table, enumerates 138 distinct NEURON_RT_* tokens (134 unique vars + the 4 LOG_LEVEL/LOG_LEVEL_/LOG_LOCATION/LOG_LOCATION_ plain/per-component forms) and 9 genuine non-RT NEURON_* vars. The remaining ~1,540 NEURON_* tokens are enum-value constants (NEURON_ISA_*, NEURON_MEMALLOC_*, NEURON_DM_*, NEURON_DRIVER_FEATURE_*, NEURON_POD_*), not env vars, and are excluded. This is a reference catalogue, so it takes the deliberate style-guide exception to the 40-row table rule: the catalogue table below is the body of the page, every row carrying name, type, default, destination field (struct + DWARF offset), effect, and a confidence tag.

Reimplementation Contract

• One parser, one pass, two structs. All init-time ingestion is nrt_config_parse_init_config @0x8a1d0. It calloc(0x128, 1)s the gconf, fills both structs field-by-field from the environment, then publishes the gconf via ngc = <ptr>. Reproduce the base-register discriminator: a lea OFF(%rax),%rdx where %rax = nrt_config @0xc5c480 writes the 656 B static struct (notated cfg.X below); a lea OFF(%rcx|%r14),%rdx where the base is the calloc'd gconf writes the 296 B heap struct (notated gcfg.X). Same offset, different struct — do not merge them.
• The default is the helper's 2nd argument. For every typed parse, the parse-time default is the literal immediate in %esi/%rsi at the call. Where that column reads —, the default is sourced from a struct constant, a prior value, or an arch-dependent branch (called out per-row), not an inline immediate.
• A handful of vars bypass the typed family. LOG_LEVEL/LOG_LOCATION (and their _-suffix per-component forms), FAKE_INSTANCE_TYPE, VIRTUAL_CORE_SIZE, the two [NEW] vars, and the six FP8_* vars at load time use direct getenv in their own functions; these rows name that function instead of an init line.
• Some recognized vars are not parsed in init_config. The [MED]-tagged rows (NINFER, EXEC_TIMEOUT, the *_BOUND_CHECK pair, INST_VALIDITY_CHECK, ONE_TMPBUF_ENABLE, IO_RING_CACHE_SIZE, …) are recognized names whose getenv lives in the execute/translate/load path (other cells' scope); their subsystem is known but the exact callsite/default is not owned here. A reimplementer must wire them, but their precise predicates belong to the load/exec pages.

CORRECTION (NX-023 — single-struct model) — an earlier scan recorded a single config object and placed the FP8 fields "in the config struct" at +252..+260. In truth those FP8 fields live in nrt_global_config (gcfg), and nrt_config_t+252 is fail_on_nan — the two structs were conflated. nrt_gconf() @0x82670 returns the 296 B ngc, not the 656 B static singleton; 117 consumer sites read nrt_gconf()->field. Confirmed by the DGE consumer translate_one_pseudo_dge_instr_v2 @0x322c40 (call nrt_gconf; and 0x1c(%rax) = gcfg.dbg_disable_dge+28; cmpb $0,0x24(%rax) = gcfg.dbg_vector_dge_skip_notif+36). See config-structs for the full two-struct reconciliation.

At a Glance — the Ingestion Shape

Before the catalogue, the three ingestion mechanisms a reimplementer must reproduce. Every catalogue row uses one of these.

The typed family (all take a std::string name, getenv inside):

The Catalogue

Reference-catalogue table (style-guide exception to the 40-row limit). Notation: cfg.X = nrt_config_t field at nrt_config @0xc5c480 (656 B static); gcfg.X = nrt_global_config_t field at *ngc (296 B heap, via nrt_gconf()). The Config Field column gives the field name and its DWARF offset, consistent with config-structs. Default is the inline 2nd-argument immediate where recovered; — ⇒ sourced from a struct constant / prior value / arch branch. Effect notes the consumer behavior; the parse callsite address is the getenv-bearing helper invocation. Rows are grouped by subsystem.

A — Core Visibility / Topology / Instance

B — DGE / Instruction-Validity / Bounds (Security-Relevant)

C — DMA / Descriptor / Prefetch

D — Collectives (CC / RDH / Mesh / Proxy)

E — Async Send/Recv & XU Compute (Experimental)

F — FP8 Numerics / Stochastic Rounding

NOTE — the six NEURON_RT_DBG_FP8_* vars are parsed once in init_config (defaults above) and re-read by direct getenv inside kelf_load_from_neff @0x4c0870 (sites 0x4c33e5..0x4c347c), where they override the FP8 config baked into the NEFF's def.json at load time. A reimplementer must honor both reads: the env value wins over the model file.

G — Ucode / NEFF Loading / Arch Select

H — Scratchpad / Tmpbuf / HBM / Memory

I — Execution Barriers / Ordering / Sync

J — P2P / Misc HW / Threading

K — Logging / Tracing / Metrics

L — Inspect / Profiling

Parsed by nrt_config_parse_inspect_config @0x86760 (the NEURON_RT_INSPECT_* family) and the profiling orchestrators; destinations are the inspect-config aggregate, not cfg/gcfg.

M — Core Dumps / OOM / Failure Capture

N — Genuine non-RT NEURON_*

NOTE — experimental flags. Four knobs are explicitly experimental and a reimplementer should treat their semantics as unstable across runtime minor versions. NEURON_RT_ASYNC_SENDRECV_BOOTSTRAP_PORT (gcfg+104) and NEURON_RT_ASYNC_SENDRECV_EXPERIMENTAL_ENABLED (gcfg+108) gate the experimental point-to-point async send/recv transport — the EXPERIMENTAL_ENABLED flag is the master gate, and the bootstrap port is meaningless unless it is set. NEURON_RT_RANKS_PER_NETWORK_PROXY (cfg+152, default 1) carries an ordering precondition: a value >1 requires the HW execution barrier (enable_hw_execution_barrier, cfg+206) — init_config aborts the combination of ranks_per_network_proxy>1 with the HW barrier disabled. NEURON_EXPERIMENTAL_COMPRESS_RG [NEW] is read by direct getenv in enc_parse_replica_groups @0x11ea54, outside the master parser, and toggles replica-group compression in the collectives path.

GOTCHA — secure_getenv is a vendor red herring. Four secure_getenv call sites exist, all inside vendored std::filesystem::temp_directory_path; none is a Neuron knob. A reimplementer scanning for the env surface by grepping *getenv PLT references must filter these out — and likewise exclude the ~1,540 NEURON_* enum-value constants (NEURON_ISA_*, NEURON_MEMALLOC_*, NEURON_DM_*, NEURON_DRIVER_FEATURE_*, NEURON_POD_*), which look like env vars by spelling but are never passed to getenv.

Boundary Edges

A handful of recognized vars are owned by other subsystems; this page records the env→field write only, and the consumer semantics live elsewhere.

Cross-References

• Configuration: nrt_config and nrt_global_config — the destination-field side of this mapping: the full field-by-field layout of both cfg (656 B) and gcfg (296 B), with offsets this page's Config Field column is consistent with
• Public C API: Device, Config and Env Parsing — the parse mechanism (the typed nrt_config_parse helper family, the getenv→&dest lea pattern) that turns a name into a field write
• Public C API: Lifecycle and Init/Teardown — nrt_init's single call into nrt_config_parse_init_config, where the whole environment is ingested once and frozen