Flag Catalog (Full)

All counts, symbols, and offsets on this page 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, ELF x86-64 DYN, not stripped). Other versions differ.

Abstract

This appendix is the exhaustive prefix index of libtpu's flag surface: every XLA_FLAGS / LIBTPU_INIT_ARGS / xla.DebugOptions name string the binary registers, grouped by prefix, with per-group counts, a representative enumerated subset, the inferred type, and the byte-evidenced default where one survives. It is the machine-style companion to the grouped narrative in xla-flag-atlas.md: the atlas explains what the high-signal knobs do; this page is the complete reference table a reader greps. Where the two disagree on a count, this page wins — its numbers come directly from the binary.

The authoritative name census is the mangled helper-symbol set. Every absl::Flag<T> FLAGS_<name> global emits an _ZN<len>AbslFlagHelpGenFor<name>8NonConstEv helper symbol, so that symbol set is a 1:1 enumeration of registered flags; length-prefix parsing recovers each <name> exactly. The binary carries 2048 such distinct symbols — the registered-flag count. A further set of names appears only in .rodata (deprecated aliases, error-message-only references) that are not backed by a live AbslFlagHelpGenFor symbol; folding those in yields 2107 distinct flag names. The two numbers answer two different questions: 2048 is "how many flags can you set," 2107 is "how many flag names exist as strings in the binary." Both are used below, labelled explicitly per row.

Every flag is settable through one funnel: LIBTPU_INIT_ARGS (env string @ file 0x918c880) is read by GetLibTpuInitArguments @ 0x20ccca20, split argv-style, and handed to absl::ParseCommandLine inside RealInitGoogle @ 0x210ae860. Because the parse is generic, the entire 2048-flag set is reachable through that one variable — there is no init-args-private subset. The xla_* (non-TPU) flags also bind to xla::DebugOptions fields via MakeDebugOptionsFlags @ 0x1e66ce80; the TPU-private families (xla_tpu_*, xla_jf_*, codenames, megascale_*, barna_core_*) are standalone globals that land in the TpuCompilationEnvironment via OverrideTpuCompEnvByCmdLineFlags @ 0x1d73e640, not in DebugOptions. Which proto a name lands in is owned by flag-families.md; this page owns the grouped name index.

This appendix is a pure-reference catalog: it carries no reimplementation contract of its own (the registration mechanism is reimplemented from xla-flag-atlas.md and registry-mediated-flags.md). It provides:

• A per-prefix count table — registered count and rodata-name count for each of the ~14 prefix namespaces, with scope and confidence.
• Per-prefix sections — for each prefix, the subsystem split (where applicable) and a substantial enumerated subset of names with inferred type, the highest-value TPU-specific flags spelled out in full.
• The certainty boundary — the 13 flags whose error-string =value remedy clauses survive (these spell the non-default direction, not the default), and the convention-inference caveat on the type column for the rest.

NOTE — two different xla_tpu_* counts measure two different things. The binary's AbslFlagHelpGenFor symbol set holds 909 registered xla_tpu_* flags — the settable surface. There are 968 distinct xla_tpu_* name strings in .rodata (909 registered + 59 rodata-only references), which is not the count of settable flags. This page splits the two columns per prefix so the distinction is explicit: use 909 for "how many --xla_tpu_*=... you can pass," 968 for "how many xla_tpu_* strings exist."

Per-Prefix Index (at a glance)

Every prefix namespace in the catalog, with the registered-flag count (binary AbslFlagHelpGenFor census) and the rodata-name count (registered + rodata-only). The "rodata names" column matches the prior 2107-union tally; the "registered" column is what is actually settable. Confidence is CERTAIN for counts derived directly from the symbol census, HIGH where the rodata-name delta carries concatenation noise.

NOTE — "registered total 2048" and "rodata names 2107" are both byte-derived: the registered total is the count of distinct AbslFlagHelpGenFor<name>8NonConstEv symbols (2048, confirmed by rg over the names sidecar); the 2107 is that set unioned with the rodata-only references (deprecated aliases, error-string mentions). The "other / no XLA prefix" registered count is the residual (2048 − the 1636 XLA/TPU-prefixed registered flags = 412); those are statically-linked library flags (alsologtostderr, alarm_on_failure, OR-tools cp_model_*, grpc internals) of no compiler interest.

xla_tpu_ — TPU Compiler + Runtime Knobs (909 registered / 968 names)

The dominant family — the TPU-private compiler and runtime knob surface, registered as standalone absl::Flag globals that land in TpuCompilationEnvironment, not in DebugOptions. (The sole two exceptions wired to DebugOptions are xla_tpu_detect_nan and xla_tpu_detect_inf — see the xla_ section.) Subsystem split, by keyword classification over all 968 xla_tpu_* name strings (sums to 968, not the 909 registered subset):

Scheduler — five engine gates

The scheduler family advertises five distinct engines, each behind its own gate. Defaults are unrecoverable from strings unless evidenced.

QUIRK — the name xla_tpu_brgka_latency_hiding_scheduler_no_progress_limit carries a transposed-letter typo (brgka vs the brkga used by its three siblings). It is a distinct registered flag string, not an alias — a reimplementer must register the misspelt name verbatim or this knob is unreachable.

ICI / Collectives — largest subsystem (174)

The ICI-SDC test harness contributes a 10-flag sub-family: xla_tpu_ici_sdc_test_{iterations, packet_size_chunks, buffer_size_chunks, delay_mask, pipeline_depth, max_distance} (all int), xla_tpu_ici_sdc_test_{emit_compact_code, run_on_program_start, inject_mismatch_for_testing_only} (bool), xla_tpu_ici_sdc_test_sflag_wait_timeout_ms (int).

Fusion (101)

MSA / scoped memory (55)

SparseCore TC-side (50)

Other high-signal xla_tpu_ knobs

• Numerics: xla_tpu_accurate_{exp, exp2, expm1, log1p, log2, logistic, sigshift} (bool), xla_tpu_bf16_emission_mode (enum), xla_tpu_auto_reduce_precision (bool), xla_tpu_experimental_enable_dynamic_int8_quantization (bool).
• Dot/conv: xla_tpu_enable_dot_strength_reduction, xla_tpu_enable_ragged_dot_kernel, xla_tpu_choose_faster_windowed_einsum_over_mem (all bool), xla_tpu_impure_contract_ragged_conv_with (string).
• Layout: xla_tpu_allow_layout_negotiation (bool), xla_tpu_enable_large_2nd_minor_layout, xla_tpu_allow_large_2nd_minor_layout_for_{x16, x8, x4} (int).
• Auto-sharding: xla_tpu_auto_spmd_partitioning_memory_budget_gb (int), xla_tpu_auto_spmd_partitioning_memory_budget_ratio (float), xla_tpu_auto_spmd_partitioning_solver_timeout_seconds (int), xla_tpu_auto_spmd_keep_all_user_shardings (bool).
• Cost-model: xla_tpu_emitter_learned_cost_model_options (string/proto), xla_tpu_enable_instruction_cycle_checking (bool), xla_tpu_hbm_initial_cycle_penalty (int), xla_tpu_impure_cost_model_logging_options (string).
• Debug/memory: xla_tpu_enable_tile_log_recorder (bool; errstr remedy =true, so default false), xla_tpu_impure_oom_fast_exit_threshold (int; errstr remedy =-1 for verbose logging), xla_tpu_always_spill_to_default_memory (bool).

xla_jf_ — Jellyfish XLA Backend (148)

The jf codename is the TPU XLA backend namespace (shared across generations). Lands in TCE. Subsystem split: misc 63, debug/dump 24, memory/alloc 15, fusion 10, MSA 9, ICI 8, dot/conv 7, sharding 4, scheduler 3, SparseCore 2, cost-model 2, numerics 1.

xla_ (plain) — Generic XLA / DebugOptions-Backed (121 registered / 138 names)

The non-codename xla_* flags. Unlike the TPU families, these bind to xla::DebugOptions fields via MakeDebugOptionsFlags @ 0x1e66ce80. Subsystem split over all 138 xla_* (plain) name strings (sums to 138, not the 121 registered subset): misc 32, ICI 23, scheduler 21, SparseCore 17, memory 15, MSA 14, debug 10, others 6.

GOTCHA — the classic XLA dump/HLO knobs (xla_dump_to, xla_hlo_profile, xla_dump_hlo_as_proto, xla_step_marker_location, xla_disable_hlo_passes) appear as xla.DebugOptions fields and as .rodata strings, but they are not registered absl::Flag globals in this build. A direct cross-match of all 290 DebugOptions field names against the registered-flag set finds exactly two overlaps: xla_tpu_detect_nan (DebugOptions field 135) and xla_tpu_detect_inf (field 136). Every other dump/HLO knob is settable only through the PJRT CompileOptions.debug_options proto path, never through LIBTPU_INIT_ARGS. A reimplementer who exposes --xla_dump_to= as a libtpu command-line flag is wrong about this build.

SparseCore & Embedding — xla_sc_ (92), barna_core_ (61)

xla_sc_* are the SparseCore-compiler LLVM-backend knobs (lands in TCE); barna_core_* are the BarnaCore embedding-engine runtime knobs (standalone).

xla_sc_ representative subset

barna_core_ representative subset

MSA Namespaces — xla_msa_ (22), xla_vf_ (16), xla_gf_ (14), xla_ior_ (4), xla_pf_ (1), xla_llo_ (1)

The dedicated memory-space-assignment namespaces. xla_msa_* is the generic MSA option set; xla_vf_* and xla_gf_* are gen-specific VMEM/MSA override sets (the vf / gf codename prefixes) carrying the same knob names scoped to that generation; xla_ior_* is the IOR fast-mem round-trip variant; xla_pf_* is a single ND-allreduce override; xla_llo_* is a single LLO-lifecycle flag.

xla_msa_ — full enumeration (22)

xla_vf_ (16), xla_gf_ (14), xla_ior_ (4), xla_pf_ (1)

xla_gf_vmem_{max_outstanding_evictions, max_repacks, max_retries} (int), xla_gf_vmem_use_ior_algorithm (enum), xla_gf_vmem_enable_while_redundant_eviction_elimination (bool) — the gen-specific VMEM mirror of the xla_msa_* set; xla_vf_* carries the same vmem_* knob set (16 names, including xla_vf_allow_replicated_vmem_writes and xla_vf_allow_split_vmem). xla_ior_{fast_mem_round_trip_production_msa, fast_mem_run_production_msa, stored_solution_path, use_stored_solution} (4) carry the IOR fast-mem round-trip variant. xla_pf_enable_nd_allreduce (1, bool) is the lone xla_pf_* flag; xla_llo_annotation_lifecycle_strict_mode (1, enum) is the lone xla_llo_* flag.

Runtime / Driver — tpu_ (69), megascale_ (150), tf_ (20), xla_mosaic_ (8)

tpu_ — runtime / compilation-cache / driver (69)

Standalone runtime flags (not compiler knobs). Representative subset:

NOTE — the lowercase libtpu_* identifiers (libtpu_init_utils, libtpu_lockfile, libtpu_sdk_*, libtpu_telemetry_*, libtpu_version, the libtpu_lts_20260413_b_ build tag) are not flags — they are translation-unit / module name strings in .rodata. They are excluded from the 2107 catalog.

megascale_ (150) — DCN collective runtime

Top knobs: megascale_num_slices (int), megascale_slice_id (int), megascale_coordinator_address (string), megascale_transport_type (enum), megascale_enable_tpu_premapping (bool), megascale_enable_watchdog (bool), megascale_graph_hang_threshold (int), megascale_heartbeat_{interval,timeout}_ms (int), megascale_error_reporter_abort_on_{error,hang} (bool), megascale_use_heartbeat (bool), megascale_grpc_num_channels (int), megascale_use_mtls_for_grpc (bool), megascale_verify_checksums (bool), megascale_use_numa_aware_threadpool (bool; errstr remedy =false, so default true).

tf_ (20) and xla_mosaic_ (8)

tf_* are the TensorFlow-TPU bridge flags (tf_jf_* and similar). xla_mosaic_* are the Mosaic MLIR custom-kernel dialect flags, including the legacy xla_mosaic_deprecated_allow_implicit_single_buffering.

Defaults — the Certainty Boundary

proto3 carries no descriptor-level defaults, and the per-flag defaults live in xla::DefaultDebugOptions() and the FLAGS_<name> static initializers — both in .text, not recoverable from strings. What does survive is a set of help/error strings that spell a --flag=value clause. Critically, every such surviving clause is a remedy — the value the message tells the user to set when something goes wrong ("use --flag=false in the meantime", "set =true to enable") — so the spelled value is the non-default, and the implied actual default is its opposite. 13 flags carry such a =value remedy clause; the remaining flags' defaults leave no string at all.

GOTCHA — none of these are byte-confirmed defaults. Each =value is the value the message tells the user to set (the remedy), which is the non-default; the "Implied default" column is the inferred opposite for the booleans, and is genuinely unrecoverable for the int-valued knobs (where the remedy is a specific tuning value, not a sentinel-vs-default flip). Do not read the remedy value as the default — it is the opposite. The authoritative defaults for every flag require disassembling DefaultDebugOptions() and the FLAGS_* ctors in .text. Four further flags sometimes cited with byte-defaults (xla_tpu_allow_deeply_nested_fusion_numerical_diff, xla_tpu_enable_offloading_{gather,scatter}_to_sparsecore, xla_tpu_fusion_debugger_instrument_inputs) carry no =value string at all and have no string-derivable default.

For the type column: the 13 types above are byte-corroborated from =value evidence; the rest are convention-inferred from the flag-name suffix (enable_/use_/allow_ ⇒ bool; _ms/_kib/_count/_size/_n ⇒ int; _ratio/_factor/_fraction ⇒ float; _file/_path/_dir/_proto ⇒ string; _mode/_type/_level ⇒ enum). This is XLA's own registration convention, so it is reliable but not per-flag byte-confirmed. A _threshold suffix may be int or float; _mode/_level may be int-enum or string — those are HIGH, not CERTAIN.

Cross-References

• xla_* Flag Atlas — the curated sibling: grouped narrative + per-subsystem deep-dive into the ~100 highest-signal knobs (point here for what a flag does)
• Flag Families — prefix → owner routing: which proto (DebugOptions vs TCE vs standalone) each prefix lands in, live-vs-inert verdict per family
• DebugOptions Proto — the xla.DebugOptions message (290 fields, 17 nested enums), the 2-field flag-wiring overlap (xla_tpu_detect_nan/inf)
• Default DebugOptions — where the per-flag defaults live (DefaultDebugOptions() + FLAGS_* static initializers in .text)
• Registry-Mediated Flags — the AbslFlagHelpGenFor registration mechanism and the MakeDebugOptionsFlags / OverrideTpuCompEnvByCmdLineFlags bind sites
• Flag Prefix Dispatch — the TpuVersion-aware prefix-strip/select mechanism for the codename families
• Environment Variables — LIBTPU_INIT_ARGS, LIBTPU_ON_GCE, TPU_LOAD_LIBRARY, the parse funnel into absl::ParseCommandLine