xla_* Flag Atlas

Addresses apply to libtpu.so from the libtpu-0.0.40-cp314 wheel (build libtpu_lts_20260413_b_RC00, build-id md5 89edbbe81c5b328a958fe628a9f2207d, 781,691,048 bytes). Other versions differ.

Abstract

libtpu registers exactly 2048 absl::Flag<T> globals (the AbslFlagHelpGenFor<name> symbol count). Every one of them is settable through a single funnel — LIBTPU_INIT_ARGS parsed by absl::ParseCommandLine — so the flag surface is, in effect, libtpu's entire command line. This page is the grouped atlas of that surface: not a flat 2048-row dump (that would be the anti-pattern this wiki exists to avoid) but a per-family taxonomy with per-subsystem deep-dives into the ~100 highest-signal knobs, each tagged with its inferred type, the proto field it backs where known, and a confidence label.

The reference frame is XLA's own flag system. The non-TPU xla_* flags are fields of xla::DebugOptions, registered by xla::MakeDebugOptionsFlags @ 0x1e66ce80 (confirmed: it takes a vector<tsl::Flag>* and a DebugOptions* and binds each field to a --xla_foo flag). The TPU-private families (xla_tpu_*, xla_jf_*, xla_sc_*, megascale_*, barna_core_*) are standalone absl::Flag globals whose values land in TpuCompilationEnvironment (TCE) via OverrideTpuCompEnvByCmdLineFlags @ 0x1d73e640, not in DebugOptions. Which proto a name lands in is the single most consequential structural fact for a reimplementer; that taxonomy is owned by flag-families.md and the protos by debugoptions-proto.md and tpu-compilation-environment.md. This page owns the catalog: the grouped name space and per-flag type/effect.

The authoritative name enumeration is the mangled helper-symbol set: every absl::Flag<T> FLAGS_<name> emits an _ZN<len>AbslFlagHelpGenFor<name>8NonConstEv symbol, so that symbol set is a 1:1 census of registered flags (length-prefix parsing recovers each <name> exactly); nm | rg -o 'AbslFlagHelpGenFor...8NonConstEv' | sort -u | wc -l returns 2048. Every catalogued name on this page resolves to an AbslFlagHelpGenFor<name> symbol in the binary. Types are convention-inferred for ~99% of flags (the enable_/use_/allow_ ⇒ bool, _ms/_kib/_count ⇒ int, _ratio/_factor ⇒ float, _file/_path ⇒ string, _mode/_level ⇒ enum heuristic XLA itself uses to register them); only a handful of defaults and types are byte-evidenced — most from =value clauses in error strings, plus xla_tpu_embedding_table_oblongness_threshold recovered from its AbslFlagDefaultGenFor initializer. Treat every type and default below as HIGH unless a row says CERTAIN (byte-evidenced) or LOW (ambiguous suffix).

For navigation, the contract is:

• The family taxonomy — prefix → owning proto → count, so a reader knows where a name's field lives before chasing it.
• The per-subsystem high-signal catalog — the ~100 flags a reimplementer of the TPU pipeline actually needs, grouped by scheduler / fusion / MSA / collectives / SparseCore / layout / numerics / autotune / debug / runtime.
• The certainty boundary — which rows are byte-confirmed, and the err-string direction-of-default trap on the rest.

1. Family Taxonomy — At a Glance

The prefix is the routing key: it decides which proto consumes the flag and which compiler/runtime subsystem owns its semantics. The counts below are per-prefix AbslFlagHelpGenFor* symbol counts and sum to the 2048 registered total. The Lands in column is the central distinction — xla_tpu_* are not DebugOptions fields, a trap overview.md §3 flags as the GOOD/BAD divide.

GOTCHA — the 429 (other) registered flags are almost all not TPU flags — 412 are absl, gRPC, protobuf, OR-tools, and cp_model library flags statically linked into the 745 MB binary; the remaining 17 are the tiny gen-codename mirrors (xla_vf_* 16, xla_pf_* 1) folded in here rather than given their own rows. (The owner partition on flag-catalog-full.md breaks xla_vf_ out separately and reports the pure vendored-lib bucket as 412.) A reimplementer enumerating AbslFlagHelpGenFor* symbols must filter to the xla* / tpu* / megascale* / barna_core* prefixes or pull in OR-tools' entire flag surface (absl_flags_*, cp_model_*). They are still settable through LIBTPU_INIT_ARGS, but they configure the vendored solvers, not the TPU compiler.

NOTE — there are zero xla_gpu_* flags registered (no AbslFlagHelpGenForxla_gpu_* symbol exists), yet 17 GPU/CPU fields survive in the shared DebugOptions descriptor as proto-only, flag-less fields. The TPU build strips the GPU flag wiring but keeps the GPU fields in the proto. The proto-only set is enumerated on debugoptions-proto.md.

The xla_tpu_* family — the bulk of the surface — itself splits across the subsystems the rest of this page deep-dives:

2. Scheduler (47 xla_tpu_)

Purpose

libtpu advertises five distinct latency-hiding scheduler engines behind separate gates — a reimplementer who assumes a single scheduler will mis-model the pipeline. The master gate is xla_tpu_enable_latency_hiding_scheduler; the four alternatives (ilp, brkga, dozer, lem) are independent variants. The BRKGA engine (Biased Random-Key Genetic Algorithm) carries its own population-tuning sub-family. The generic xla_* and xla_jf_* siblings (76 in the full scheduler group) carry the LHS resource model and the BRKGA fallback knobs.

Catalog — TPU scheduler gates

Catalog — BRKGA tuning + generic LHS

The 8 cost-model flags feed the scheduler's latency estimates: xla_tpu_emitter_learned_cost_model_options (string/proto — a learned-cost proto with no shipped ML client), xla_tpu_enable_instruction_cycle_checking (bool), xla_tpu_hbm_initial_cycle_penalty (int), xla_tpu_break_of_accum_cost_heuristic (bool), plus the generic xla_jf_random_latency and xla_jf_use_cost_based_memory_coloring.

QUIRK — the brgka spelling in xla_tpu_brgka_latency_hiding_scheduler_no_progress_limit is a typo in the flag name itself, distinct from the correctly-spelled brkga knobs. A reimplementer copying the BRKGA family by pattern will silently drop this knob unless they match both spellings. The typo is in the registered AbslFlagHelpGenFor symbol — it is the real flag name, not an extraction artifact.

3. Fusion (101 xla_tpu_)

Purpose

Fusion is the second-largest xla_tpu_ subsystem and carries the only cluster of byte-evidenced defaults on the whole surface — four of the five =value error strings live here. The gates control read-write-buffer (RWB) fusion, dot→dot chaining, nested-dot (PartialReduce) fusion, MRB accumulation, and the numerical tolerances for deep fusion. The generic xla_jf_* conv/multi-output fusion knobs and the SparseCore fusion gate round out the group.

Catalog — fusion gates (byte-evidenced cluster)

Catalog — generic fusion + dot/conv + numerics

GOTCHA — the help/error-string =value clause is the value the message tells you to set — not the registered default. The byte-authoritative default is the FLAGS_<name> inline literal at FlagImpl+0x48, and for this cluster it is 01 00 00 00 = true in every case: rwb_fusion, dot_dot_fusion, accumulate_into_mrb, nested_dot_fusion, and allow_deeply_nested_fusion_numerical_diff are all true by default. The error strings (e.g. in PartialReduceEmitter::ValidateShapes @ 0x10eaa120, AssignMrbEntriesToChains @ 0x10f4ac60) offer =false/=true as a workaround to flip an on-by-default knob, so reading the suggested value as the default inverts it. Trust the +0x48 union, never the prose; see tce-field-offsets-defaults.md.

4. Memory-Space Assignment (MSA)

Purpose

MSA controls where buffers live (VMEM / CMEM / HBM), how async copies prefetch across the memory hierarchy, and how the scoped-memory allocator (telamalloc) packs them. The knobs split three ways: the xla_tpu_* MSA family (55), the dedicated xla_msa_* namespace (22), and the per-generation xla_gf_vmem_* (6acc60406) / xla_ior_fast_mem_* overlays. Many MSA fields resolve through the AUTO tri-state rather than carrying a flat default — see autoproto-autoor-resolution.md.

Catalog — xla_tpu_* MSA

Catalog — xla_msa_* namespace (22)

Per-generation overlays: xla_gf_vmem_max_outstanding_evictions / _max_repacks / _max_retries (int, 6acc60406), xla_gf_vmem_use_ior_algorithm (enum), xla_ior_fast_mem_* (4 flags, the fast-mem round-trip MSA variant). The generic xla_enable_cross_program_prefetch and xla_default_cross_program_prefetch_heuristic gate XPP at the DebugOptions level.

5. Collectives / ICI (174 xla_tpu_)

Purpose

The largest xla_tpu_ subsystem. It covers the inter-chip-interconnect (ICI) collective emitters (all-reduce, all-gather, reduce-scatter, all-to-all), the resilient/fault-aware route selection, the sflag (sync-flag) wait watchdogs and hang-attribution telemetry, and the ICI-SDC (silent-data-corruption) test harness. The megascale_* family (§ separate) is the DCN runtime layer above these.

Catalog — collective emitters + sflag watchdogs

Catalog — generic collectives + ICI-SDC harness

The ICI-SDC test sub-family has 10 members (_iterations, _packet_size_chunks, _buffer_size_chunks, _delay_mask, _pipeline_depth, _max_distance, _emit_compact_code, _run_on_program_start, _inject_mismatch_for_testing_only, _sflag_wait_timeout_ms) — a self-test harness, not production tuning.

6. SparseCore + BarnaCore Embedding

Purpose

Two families serve the SparseCore (SC) embedding path: xla_sc_* (92) are the SparseCore LLVM-backend compiler/codegen knobs, and barna_core_* (61) are the BarnaCore HW embedding-accelerator runtime tunables. The xla_tpu_* side (50) carries the SC offload gates and the SC SDC checker. SC compiler flags land in TCE; BarnaCore flags are standalone runtime absl::Flag globals.

Catalog — xla_tpu_* SC offload + xla_sc_* compiler

Catalog — barna_core_* embedding runtime (61)

7. Layout + Auto-Sharding

Purpose

Layout knobs (29 xla_tpu_) control tiling, the "large 2nd-minor" layout per element width (x16/x8/x4), relayout, and layout negotiation. Auto-sharding / SPMD (40 xla_tpu_ + 8 generic) controls the auto-SPMD partitioner's memory budget and solver, plus user-sharding preservation.

Catalog — layout + sharding

GOTCHA — xla_tpu_allow_large_2nd_minor_layout_for_x16 and its _x8 / _x4 siblings are typed int, not bool, despite the allow_ prefix that elsewhere signals a boolean. The _for_x16 suffix implies a tri-state-or-count integer, not an on/off gate (LOW confidence — the type was inferred from suffix, not byte-confirmed). A reimplementer must not assume every allow_* flag is boolean.

8. Memory / Allocation + Runtime

Purpose

Allocation knobs (27 xla_tpu_ + generic) control OOM handling, HBM/VMEM/SMEM spilling, defragmentation, and allocation backtraces. The runtime/cache/driver family (tpu_*, 69) controls the compilation cache, driver watchdogs, and core-dump behavior — these are runtime, not compile-time, knobs.

Catalog — allocation + runtime/cache

QUIRK — xla_tpu_impure_oom_fast_exit_threshold defaults to 10 (byte-evidenced: inline FlagImpl+0x48 = 0x0a, no Gen reloc) — a positive count, not a -1 "disabled" sentinel. The impure_ prefix is a libtpu naming convention marking ~30 non-deterministic / logging / side-effecting knobs (impure_cost_model_logging_options, impure_llo_lifecycle_log_mode, impure_probability_of_host_offloading). A reimplementer should treat impure_ flags as runtime-observable side channels, not pure compile decisions.

9. Debug / Dump / Log / Trace

Purpose

77 xla_tpu_ debug/dump knobs plus the generic xla_jf_dump_* and xla_enable_*_trace families (181 in the full group). These control HLO/LLO/MLIR dumps, tracing, NaN/SDC checking, and the log recorders. The xla_jf_dump_* family is the Jellyfish-backend dump surface; xla_sc_dump_* is the SparseCore equivalent.

Catalog — dump / trace / verify

Catalog — LLVM-emitter dumps (xla_llvm_*, 4)

10. Autotune / AutoFDO

Purpose

23 xla_tpu_autofdo_* flags drive profile-guided optimization: fingerprint-keyed loading of pre-tuned flags, layouts, schedules, and shardings, plus the FlagNet predictor. AutoFDO is a fingerprint→tuning cache: a module's fingerprint keys a stored set of decisions that bypass the live cost models.

Catalog — AutoFDO

11. The Certainty Boundary

The entire catalog above rests on two extraction methods with different trust levels, and a reimplementer must respect the seam.

Names — CERTAIN. The 2048 registered names come from the AbslFlagHelpGenFor<name> mangled-symbol set, which is a 1:1 enumeration of absl::Flag globals (sort -u | wc -l = 2048). Every name catalogued on this page resolves to such a symbol. Additional flag-like strings appear in .rodata (deprecated aliases / error-message references) but are not registered flags; they are not counted in the 2048 and are out of scope here.

Types — HIGH, mostly inferred. Only the suffix convention (XLA's own registration convention) types ~99% of flags. The ambiguous suffixes (_threshold int-or-float, _mode/_level int-enum-or-string) are marked LOW per row. Byte-confirming a type needs the absl::Flag<T> template argument from the FLAGS_<name> symbol's RTTI — not done here.

Defaults — only 18 are CERTAIN. Most come from =value clauses in help/error strings; xla_tpu_embedding_table_oblongness_threshold is recovered directly from its AbslFlagDefaultGenFor initializer (movl $0x42480000 = 50.0f @ 0x1d7068c0), which overrides the =1 workaround value its error string suggests. Everything else lives in .text initializers (xla::DefaultDebugOptions() and the per-flag FLAGS_* static ctors) not recoverable from strings. The full byte-evidenced set:

NOTE — for the ~330 TCE fields that are AutoProto oneofs, "default" is not even a flat value — it is an AUTO-resolution polarity baked into each consumer, optionally rewritten by a per-TpuVersion MSA overlay. The effective value is flag-default ⊕ AUTO-polarity ⊕ per-version-overlay. That resolution is owned by autoproto-autoor-resolution.md; this atlas catalogs the flag names and inferred types, not their resolved values.

Related Components

Cross-References

• overview.md — the four-stage flag→DebugOptions→TCE→effective-value pipeline this atlas sits inside
• flag-families.md — the prefix→owner taxonomy in full; which proto each family lands in
• env-vars.md — LIBTPU_INIT_ARGS and the env-var roster that feeds the parse
• debugoptions-proto.md — xla::DebugOptions: the 290-field schema the plain xla_* flags back (full descriptor decode; the earlier "111 wire-fields / 94 flag-wired" figure was a partial sample, superseded there)
• tpu-compilation-environment.md — the 1121-field TCE proto the xla_tpu_* / xla_jf_* / xla_sc_* flags land in
• autoproto-autoor-resolution.md — the AUTO tri-state that makes "default" a resolution rule for ~330 fields
• tce-field-offsets-defaults.md — the byte-exact field→offset→default reference where the non-evidenced defaults are recovered