xla_* 标志图谱

地址适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（构建 libtpu_lts_20260413_b_RC00，build-id md5 89edbbe81c5b328a958fe628a9f2207d，781,691,048 字节）。其他版本会不同。

摘要

libtpu 精确注册了 2048 个 absl::Flag<T> 全局变量（即 AbslFlagHelpGenFor<name> 符号数量）。它们全都可通过单一入口设置：由 absl::ParseCommandLine 解析的 LIBTPU_INIT_ARGS；因此这个标志表面实际上就是 libtpu 的完整命令行。本页是该表面的分组图谱：不是扁平的 2048 行转储（那正是本 wiki 要避免的反模式），而是按家族分类，并对约 100 个最高信号量旋钮按子系统深入说明；每项都标注推断类型、已知时其背后的 proto 字段，以及置信度标签。

参照框架是 XLA 自身的标志系统。非 TPU 的 xla_* 标志是 xla::DebugOptions 的字段，由 xla::MakeDebugOptionsFlags @ 0x1e66ce80 注册（已确认：它接受一个 vector<tsl::Flag>* 和一个 DebugOptions*，并把每个字段绑定到一个 --xla_foo 标志）。TPU 私有家族（xla_tpu_*、xla_jf_*、xla_sc_*、megascale_*、barna_core_*）是独立的 absl::Flag 全局变量，它们的值经由 OverrideTpuCompEnvByCmdLineFlags @ 0x1d73e640 进入 TpuCompilationEnvironment (TCE)，不进入 DebugOptions。某个名称落入哪个 proto，是重新实现者最关键的结构事实；这个分类由 flag-families.md 负责，proto 由 debugoptions-proto.md 和 tpu-compilation-environment.md 负责。本页负责目录：分组后的命名空间以及逐标志的类型/效果。

权威的名称枚举来自改编后的 helper 符号集合：每个 absl::Flag<T> FLAGS_<name> 都会发出一个 _ZN<len>AbslFlagHelpGenFor<name>8NonConstEv 符号，因此该符号集合就是已注册标志的 1:1 清点（解析长度前缀可以精确还原每个 <name>）；nm | rg -o 'AbslFlagHelpGenFor...8NonConstEv' | sort -u | wc -l 返回 2048。本页列出的每个名称都能解析到二进制中的一个 AbslFlagHelpGenFor<name> 符号。类型按约定推断覆盖约 99% 的标志（enable_/use_/allow_ => bool，_ms/_kib/_count => int，_ratio/_factor => float，_file/_path => string，_mode/_level => enum，这是 XLA 自身注册它们时使用的启发式）；只有少数默认值和类型有字节证据，主要来自错误字符串中的 =value 子句，另有 xla_tpu_embedding_table_oblongness_threshold 是从其 AbslFlagDefaultGenFor 初始化器恢复的。除非某行标为 CERTAIN（字节证据）或 LOW（后缀有歧义），否则下面所有类型和默认值都应视为 HIGH。

导航约定如下：

• 家族分类：前缀 → 所属 proto → 数量，让读者在追踪名称前知道其字段位于何处。
• 按子系统的高信号量目录：重新实现 TPU 流水线实际需要的约 100 个标志，按调度器 / 融合 / MSA / collectives / SparseCore / 布局 / 数值 / autotune / 调试 / 运行时分组。
• 确定性边界：哪些行经过字节确认，以及其余行中错误字符串的默认值方向陷阱。

名称清点	2048 个已注册 absl::Flag（AbslFlagHelpGenFor* 符号，sort -u）
枚举符号	_ZN<len>AbslFlagHelpGenFor<name>8NonConstEv（每个标志 1 个）
DebugOptions 注册器	xla::MakeDebugOptionsFlags @ 0x1e66ce80（绑定 xla_* 字段）
TCE 标志→字段桥接	OverrideTpuCompEnvByCmdLineFlags @ 0x1d73e640（TPU 家族）
入口	LIBTPU_INIT_ARGS（str @ file 0x918c880）→ absl::ParseCommandLine
类型拆分（推断，全部 2048 个）	约 bool 68% · int 21% · string · float · enum（后缀约定，非字节定型）
字节确认的类型/默认值	约 18 个（大多来自 =value 错误字符串；oblongness 来自 AbslFlagDefaultGenFor）
置信度	HIGH（按约定推断），除非某行标为 CERTAIN（字节证据）或 LOW

---

1. 家族分类，一览

前缀是路由键：它决定哪个 proto 消费该标志，以及哪个编译器/运行时子系统拥有其语义。下面的数量是每个前缀的 AbslFlagHelpGenFor* 符号数量，总和为 2048 个已注册标志。落入 列是核心区别：xla_tpu_* 不是 DebugOptions 字段，这是 overview.md §3 标出的 GOOD/BAD 分界陷阱。

家族	数量	主导类型	落入	子系统所有者
xla_tpu_*	909	bool / int / float	TCE（独立）	TPU 编译器 + 运行时
(other + xla_vf_/xla_pf_)	429	混合	n/a（vendored libs）	absl / grpc / protobuf / OR-tools
megascale_*	150	bool 73 / int 47 / str 14	独立 absl::Flag	DCN collective 运行时
xla_jf_*	148	bool 109 / int 23	TCE	Jellyfish XLA 后端
xla_*（普通）	121	bool / int / enum	xla::DebugOptions	通用 XLA
xla_sc_*	92	bool 73 / int 13	TCE	SparseCore LLVM 后端
tpu_*	69	bool / int / str	runtime/cache/driver	TPU 运行时
barna_core_*	61	float / int / duration	独立 absl::Flag	BarnaCore 嵌入硬件
xla_msa_*	22	bool / int / float	TCE + DebugOptions 混合	Memory-Space Assignment
tf_*	20	bool	runtime	TF-TPU 桥接
xla_gf_*	14	bool / int / enum	TCE	6acc60406/v7x VMEM/MSA
xla_mosaic_*	8	bool / enum	TCE	Mosaic MLIR 方言
xla_ior_*	4	bool / enum	TCE	"IOR" fast-mem MSA 变体
xla_llo_*	1	enum	TCE	LLO 注解生命周期

陷阱 — 429 个 (other) 已注册标志几乎都不是 TPU 标志：其中 412 个是静态链接进 745 MB 二进制的 absl、gRPC、protobuf、OR-tools 和 cp_model 库标志；剩余 17 个是很小的生成代号镜像（xla_vf_* 16 个、xla_pf_* 1 个），这里合并进来而不单独列行。flag-catalog-full.md 上的所有者划分会单独拆出 xla_vf_，并把纯 vendored-lib 桶报告为 412。枚举 AbslFlagHelpGenFor* 符号的重新实现者必须过滤到 xla* / tpu* / megascale* / barna_core* 前缀，否则会把 OR-tools 的完整标志表面（absl_flags_*、cp_model_*）也拉进来。它们仍可通过 LIBTPU_INIT_ARGS 设置，但配置的是 vendored solver，而不是 TPU 编译器。

说明 — 注册的 xla_gpu_* 标志为零（不存在 AbslFlagHelpGenForxla_gpu_* 符号），但 17 个 GPU/CPU 字段作为仅 proto 字段保留在共享 DebugOptions 描述符中。TPU 构建剥离了 GPU 标志连线，但在 proto 中保留了 GPU 字段。仅 proto 集合列在 debugoptions-proto.md。

xla_tpu_* 家族是该表面的主体，它自身按本页后续深入说明的子系统拆分：

xla_tpu_* 子系统	数量	深入说明
杂项 / 未分类	229	（长尾；不逐项编目）
ICI / collectives	174	§5
融合	101	§3
debug / dump / log	77	§9
MSA / memory-space	55	§4
SparseCore	50	§6
调度器	47	§2
auto-sharding / SPMD	40	§7
布局	29	§7
内存 / 分配	27	§8
dot / conv	24	（§3 中有代表性行）
autotune / AutoFDO	24	§10
数值 / 精度	21	§3
cost-model	8	§2
runtime	3	§8

---

2. 调度器（47 个 xla_tpu_）

目的

libtpu 在不同 gate 后面公开了五个不同的延迟隐藏调度器引擎，如果重新实现者假设只有一个调度器，就会错误建模流水线。主 gate 是 xla_tpu_enable_latency_hiding_scheduler；四个替代项（ilp、brkga、dozer、lem）是彼此独立的变体。BRKGA 引擎（Biased Random-Key Genetic Algorithm）带有自己的种群调优子家族。通用 xla_* 和 xla_jf_* 兄弟标志（完整调度器组中 76 个）承载 LHS 资源模型和 BRKGA fallback 旋钮。

目录 — TPU 调度器 gate

标志	类型	默认值	效果
xla_tpu_enable_latency_hiding_scheduler	bool	(unrec)	LHS 主 gate
xla_tpu_enable_ilp_latency_hiding_scheduler	bool	(unrec)	ILP 形式的 LHS
xla_tpu_enable_brkga_latency_hiding_scheduler	bool	(unrec)	遗传（BRKGA）调度器
xla_tpu_enable_dozer_latency_hiding_scheduler	bool	(unrec)	"Dozer" 变体
xla_tpu_enable_lem_scheduler	bool	(unrec)	LEM 变体
xla_tpu_consider_lp_llo_scheduler	bool	(unrec)	基于 LP 的 LLO 调度器
xla_tpu_enable_latency_hiding_layer_scheduler	bool	(unrec)	逐层 LHS
xla_tpu_enable_multi_compute_overlap_in_layer_scheduler	bool	(unrec)	多 compute 重叠
xla_tpu_aggressive_flexible_annotation_scheduling	bool	(unrec)	注解激进程度
xla_tpu_scheduling_annotation_deannotate_unsupported_groups	AutoOr<bool>	false (AUTO→off)	对注解缺口去注解
xla_tpu_enable_all_experimental_scheduler_features	bool	(unrec)	开启所有实验性调度特性

目录 — BRKGA 调优 + 通用 LHS

标志	类型	效果
xla_tpu_brkga_latency_hiding_scheduler_generation_limit	int	BRKGA 代数
xla_tpu_brkga_latency_hiding_scheduler_num_chromosomes	int	BRKGA 种群
xla_tpu_brkga_latency_hiding_scheduler_num_top_heap_computations	int	BRKGA 精英集合
xla_tpu_brgka_latency_hiding_scheduler_no_progress_limit	int	BRKGA 停滞截止（注意 brgka 拼写错误）
xla_hlo_scheduling_brkga_generation_limit	int	通用 BRKGA 代数
xla_hlo_scheduling_brkga_enable_as_fallback	bool	仅将 BRKGA 用作 fallback
xla_latency_hiding_scheduler_rerun	bool	重新运行 LHS pass
xla_latency_hiding_scheduler_resource_serializing	bool	序列化资源使用
xla_latency_hiding_scheduler_enable_selective_resources	bool	选择性资源跟踪
xla_lhs_prioritize_async_depth_over_stall	bool	async-depth 优先级
xla_lhs_make_all_gather_selective	bool	选择性 AG 重叠
xla_lhs_threshold_for_applying_output_fusion_latency_multiplier	float	output-fusion 延迟乘数阈值
xla_jf_vliw_scheduler	bool	Jellyfish VLIW 后调度器
xla_jf_critical_path_scheduler	bool	关键路径调度器
xla_hlo_parse_memory_schedule_from_file	string	回放固定调度

8 个 cost-model 标志会供给调度器的延迟估计：xla_tpu_emitter_learned_cost_model_options（string/proto，一个 learned-cost proto，但没有随附 ML client）、xla_tpu_enable_instruction_cycle_checking（bool）、xla_tpu_hbm_initial_cycle_penalty（int）、xla_tpu_break_of_accum_cost_heuristic（bool），以及通用的 xla_jf_random_latency 和 xla_jf_use_cost_based_memory_coloring。

怪癖 — xla_tpu_brgka_latency_hiding_scheduler_no_progress_limit 中的 brgka 拼写是标志名本身的拼写错误，与拼写正确的 brkga 旋钮不同。按模式复制 BRKGA 家族的重新实现者，如果不同时匹配两种拼写，会静默遗漏这个旋钮。这个拼写错误存在于已注册的 AbslFlagHelpGenFor 符号中；它是真实标志名，不是提取产物。

---

3. 融合（101 个 xla_tpu_）

目的

融合是第二大的 xla_tpu_ 子系统，并承载整个表面上唯一一组有字节证据的默认值；五个 =value 错误字符串中有四个位于这里。这些 gate 控制 read-write-buffer (RWB) 融合、dot→dot 链接、嵌套 dot（PartialReduce）融合、MRB 累加，以及深度融合的数值容差。通用的 xla_jf_* conv/多输出融合旋钮和 SparseCore 融合 gate 补足了这个组。

目录 — 融合 gate（字节证据簇）

标志	类型	默认值	效果
xla_tpu_rwb_fusion	bool	true	read-write-buffer 融合
xla_tpu_dot_dot_fusion	bool	true	dot→dot 融合
xla_tpu_nested_dot_fusion	bool	true	嵌套 dot（PartialReduce）融合
xla_tpu_accumulate_into_mrb	bool	true	MRB 累加融合
xla_tpu_allow_deeply_nested_fusion_numerical_diff	bool	true	容忍深度融合数值差异
xla_tpu_fusion_debugger_instrument_inputs	AutoOr<bool>	false（Gen movw $0→AUTO；consumer AUTO→off 时关闭）	fusion-debugger 输入插桩
xla_tpu_allow_input_fusion_in_certain_reduce_ops	bool	(unrec)	reduce-op 输入融合
xla_tpu_allow_conv_input_fusion_with_downcast_convert	bool	(unrec)	带 downcast 的 conv 输入融合
xla_tpu_wrap_fusion_lowerable_hlos_in_loop_fusion	bool	(unrec)	包装可 lower 的 HLO
xla_tpu_enable_experimental_fusion_cost_model	bool	(unrec)	实验性融合 cost model

目录 — 通用融合 + dot/conv + 数值

标志	类型	效果
xla_jf_enable_multi_output_fusion	bool	多输出融合
xla_jf_enable_producer_consumer_multi_output_fusion	bool	producer/consumer MOF
xla_jf_fusion_max_vmem_mib	int	每个融合的 VMEM 上限（MiB）
xla_sc_enable_instruction_fusion	bool	SparseCore 指令融合
xla_tpu_enable_dot_strength_reduction	bool	dot → 更便宜的操作
xla_tpu_enable_ragged_dot_kernel	bool	ragged-dot kernel
xla_tpu_choose_faster_windowed_einsum_over_mem	bool	windowed-einsum 速度/内存权衡
xla_jf_conv_full_precision	bool	全精度 conv
xla_jf_auto_assign_mxu	bool	自动 MXU 分配
xla_tpu_accurate_exp / _log1p / _logistic	bool	精确超越函数家族
xla_tpu_bf16_emission_mode	enum	bf16 发射策略
xla_tpu_experimental_enable_dynamic_int8_quantization	bool	动态 int8 量化（实验性）

陷阱 — help/错误字符串的 =value 子句是消息告诉你去设置的值，不是已注册默认值。字节权威默认值是 FlagImpl+0x48 处的 FLAGS_<name> 内联字面量；对这个簇而言，每个都是 01 00 00 00 = true：rwb_fusion、dot_dot_fusion、accumulate_into_mrb、nested_dot_fusion 和 allow_deeply_nested_fusion_numerical_diff 默认全为 true。错误字符串（例如 PartialReduceEmitter::ValidateShapes @ 0x10eaa120、AssignMrbEntriesToChains @ 0x10f4ac60 中）提供 =false/=true，是作为翻转默认开启旋钮的 workaround；因此把建议值读成默认值会完全反向。信任 +0x48 union，而不是 prose；见 tce-field-offsets-defaults.md。

---

4. Memory-Space Assignment (MSA)

目的

MSA 控制缓冲区驻留位置（VMEM / CMEM / HBM）、async copy 如何跨内存层级预取，以及 scoped-memory 分配器（telamalloc）如何打包缓冲区。这些旋钮分三类：xla_tpu_* MSA 家族（55 个）、专用 xla_msa_* 命名空间（22 个），以及按代际区分的 xla_gf_vmem_*（6acc60406）/ xla_ior_fast_mem_* overlay。许多 MSA 字段通过 AUTO 三态解析，而不是携带扁平默认值；见 autoproto-autoor-resolution.md。

目录 — xla_tpu_* MSA

标志	类型	效果
xla_tpu_alternate_memory_benefit_scaling_factor_for_large_buffers	float	MSA 收益缩放
xla_tpu_async_copy_bandwidth_scaling_factor	float	async-copy 带宽模型
xla_tpu_allocate_scoped_vmem_at_same_offset	bool	scoped VMEM 偏移复用
xla_tpu_allocate_scoped_cmem_at_same_offset	bool	scoped CMEM 偏移复用
xla_tpu_allow_in_cmem_copy	bool	允许复制进 CMEM
xla_tpu_scoped_cmem_for_all_reduce	bool	all-reduce 使用 scoped CMEM
xla_tpu_vmem_scavenging_mode	enum	VMEM scavenger 策略
xla_tpu_vmem_use_telamalloc	bool	telamalloc VMEM 分配器
xla_tpu_scoped_vmem_limit_kib	int	scoped-VMEM 字节预算（KiB）

目录 — xla_msa_* 命名空间（22 个）

标志	类型	效果
xla_msa_enable	bool	MSA 主 gate
xla_msa_max_outstanding_prefetches	int	预取并发上限
xla_msa_max_outstanding_evictions	int	eviction 并发上限
xla_msa_max_cross_program_prefetches	int	XPP 数量上限
xla_msa_max_repacks / _max_retries	int	repack / retry 预算
xla_msa_min_overlap_to_async_copy_ratio	float	最小重叠比例
xla_msa_preferred_overlap_to_async_copy_ratio	float	首选重叠比例
xla_msa_max_overlap_to_mem_size_async_copy_ratio	float	重叠与内存大小比例
xla_msa_enable_window_prefetch	bool	window prefetch
xla_msa_enable_sync_copy_replacement	bool	sync→async copy 替换
xla_msa_expanded_scoped_alternate_memory_mode	enum	scoped-alt-mem 模式
xla_msa_experimental_ior_algorithm	enum	"IOR" eviction 算法（实验性）
xla_msa_use_bundle_aware_cost_model	bool	bundle-aware cost model
xla_msa_cost_model_options	string	cost-model 配置字符串

按代际的 overlay：xla_gf_vmem_max_outstanding_evictions / _max_repacks / _max_retries（int，6acc60406）、xla_gf_vmem_use_ior_algorithm（enum）、xla_ior_fast_mem_*（4 个标志，fast-mem 往返 MSA 变体）。通用的 xla_enable_cross_program_prefetch 和 xla_default_cross_program_prefetch_heuristic 在 DebugOptions 层级控制 XPP。

---

5. Collectives / ICI（174 个 xla_tpu_）

目的

最大的 xla_tpu_ 子系统。它覆盖 inter-chip-interconnect (ICI) collective 发射器（all-reduce、all-gather、reduce-scatter、all-to-all）、弹性/故障感知路由选择、sflag（sync-flag）等待 watchdog 和 hang 归因遥测，以及 ICI-SDC（silent-data-corruption）测试 harness。megascale_* 家族（单独章节）是这些之上的 DCN 运行时层。

目录 — collective 发射器 + sflag watchdog

标志	类型	默认值	效果
xla_tpu_enable_sparse_core_reduce_scatter_v2	AutoOr<bool>	true（AUTO→on，但 EnableSparseCoreReduceScatterV2 @ 0x1d6b8660 处有 TpuVersion+第二字段组合）	SC ND reduce-scatter v2
xla_tpu_all_gather_collective_matmul_mode	enum	(unrec)	collective-matmul AG 模式
xla_tpu_all_gather_step_count	int	(unrec)	AG ring 步数
xla_tpu_all_reduce_vmem_contingency_kib	int	(unrec)	AR VMEM 预留（KiB）
xla_tpu_all_to_all_max_rdma_size_kib	int	(unrec)	A2A RDMA 分块上限（KiB）
xla_tpu_1d_uni_direction_ring_min_input_size_chunks	int	(unrec)	1-D ring 阈值
xla_tpu_use_resilient_collective_emitter	bool	(unrec)	故障感知路由表
xla_tpu_add_barriers_around_aggregated_collectives	bool	(unrec)	barrier 包裹
xla_tpu_force_startup_barrier_in_binomial_all_reduce	bool	(unrec)	startup barrier
xla_tpu_combine_quantized_all_reduce_operands	bool	(unrec)	quantized-AR 操作数组合
xla_tpu_checksum_all_reduce_transfers	bool	(unrec)	AR 传输校验和
xla_tpu_debug_sflag_wait_timeout_ms	int	(unrec)	TC sflag-wait watchdog
xla_tpu_debug_sc_sflag_wait_timeout_ms	int	(unrec)	SC sflag-wait watchdog
xla_tpu_collect_sflag_wait_stats	bool	(unrec)	sflag-wait 统计主开关
xla_tpu_collect_sflag_wait_hang_core	bool	(unrec)	hang 归因：core
xla_tpu_collect_sflag_wait_hang_rate	float	(unrec)	hang-rate 统计

目录 — 通用 collectives + ICI-SDC harness

标志	类型	效果
xla_enable_async_all_gather	bool	async AG（DebugOptions）
xla_enable_async_all_reduce	bool	async AR（DebugOptions）
xla_enable_async_reduce_scatter_fusion	bool	async RS 融合
xla_all_gather_combiner_threshold_count	float	AG combiner 阈值
xla_all_reduce_latency_bound_threshold_in_bytes	float	AR latency-bound 阈值
xla_enable_all_gather_2d_emitter / _3d_emitter	bool	2D/3D AG 发射器
xla_tpu_ici_sdc_test_iterations	int	ICI-SDC 测试迭代次数
xla_tpu_ici_sdc_test_packet_size_chunks	int	ICI-SDC 包大小
xla_tpu_ici_sdc_test_inject_mismatch_for_testing_only	bool	注入 ICI mismatch（仅测试）
xla_tpu_ici_sdc_test_run_on_program_start	bool	程序启动时运行 harness

ICI-SDC 测试子家族有 10 个成员（_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）：它是自测 harness，不是生产调优。

---

6. SparseCore + BarnaCore 嵌入 {#6-sparsecore--barnacore-embedding}

目的

两个家族服务 SparseCore (SC) 嵌入路径：xla_sc_*（92 个）是 SparseCore LLVM 后端编译器/codegen 旋钮，barna_core_*（61 个）是 BarnaCore 硬件嵌入加速器运行时可调项。xla_tpu_* 一侧（50 个）承载 SC offload gate 和 SC SDC checker。SC 编译器标志落入 TCE；BarnaCore 标志是独立的运行时 absl::Flag 全局变量。

目录 — xla_tpu_* SC offload + xla_sc_* 编译器

标志	类型	默认值	效果
xla_tpu_enable_offloading_gather_to_sparsecore	bool	false	gather offload 到 SC
xla_tpu_enable_offloading_scatter_to_sparsecore	enum (Tristate)	ENABLED（Gen movb $2）	scatter offload 到 SC
xla_tpu_enable_sc_log_recorder	AutoOr<bool>	false（AUTO→off）	SC log recorder
xla_tpu_embedding_table_oblongness_threshold	float	50.0	embedding-table oblongness 截止
xla_tpu_enable_sc_sdc_checker	bool	(unrec)	SparseCore SDC checker
xla_tpu_aggregate_data_dependent_sc_ops	bool	(unrec)	数据依赖 SC 聚合
xla_sc_enable_instruction_fusion	bool	(unrec)	SC 指令融合
xla_sc_enable_latency_hiding_scheduler	bool	(unrec)	SC LHS
xla_sc_enable_tile_overlays / _scs_overlays	bool	(unrec)	tile / SCS overlay
xla_sc_enable_stack_eliding	bool	(unrec)	栈省略
xla_sc_enable_hbm_optimization_mode	enum	(unrec)	SC HBM 优化模式
xla_sc_detect_nan	bool	(unrec)	SC NaN 检测
xla_sc_assert_level	enum	(unrec)	SC 断言级别
xla_sc_dump_llvm_ir_to	string	(unrec)	转储 SC LLVM IR
xla_sc_use_legacy_embeddings_loop_configs	bool	(unrec)	legacy embeddings loop configs

目录 — barna_core_* 嵌入运行时（61 个）

标志	类型	效果
barna_core_max_hbm_fraction_for_embeddings	float	embeddings 的 HBM 比例上限
barna_core_override_tpu_table_limit_fraction	float	每表限制覆盖
barna_core_software_row_sharding_hbm_usage_fraction_limit	float	SW row-sharding HBM 上限
barna_core_master_partitioner_thread_count	int	partitioner 线程数
barna_core_hot_id_profiler_top_n_multiple	int	hot-ID profiler top-N
barna_core_file_operation_timeout	duration/int	file-op 超时
barna_core_embedding_common_config_proto_path	string	embedding config proto 路径
barna_core_partitioner_optimization_objective	enum	partitioner 目标

---

7. 布局 + Auto-Sharding {#7-layout--auto-sharding}

目的

布局旋钮（29 个 xla_tpu_）控制 tiling、按元素宽度划分的 "large 2nd-minor" 布局（x16/x8/x4）、relayout 和布局协商。Auto-sharding / SPMD（40 个 xla_tpu_ + 8 个通用标志）控制 auto-SPMD partitioner 的内存预算和 solver，以及用户 sharding 保留。

目录 — 布局 + sharding

标志	类型	效果
xla_tpu_allow_layout_negotiation	bool	布局协商 gate
xla_tpu_enable_large_2nd_minor_layout	int	large 2nd-minor 布局主开关
xla_tpu_allow_large_2nd_minor_layout_for_x16	int	每 x16 变体
xla_tpu_allow_large_2nd_minor_layout_for_x8	int	每 x8 变体
xla_tpu_allow_large_2nd_minor_layout_for_x4	int	每 x4 变体
xla_tpu_allow_sharding_on_minor_dim	int	minor-dim sharding
xla_tpu_auto_spmd_partitioning_memory_budget_gb	int	auto-SPMD 内存预算（GB）
xla_tpu_auto_spmd_partitioning_memory_budget_ratio	float	预算比例
xla_tpu_auto_spmd_partitioning_solver_timeout_seconds	int	solver wall-clock 上限
xla_tpu_auto_spmd_keep_all_user_shardings	bool	保留用户 shardings
xla_tpu_auto_spmd_remove_all_user_shardings	bool	移除用户 shardings
xla_tpu_autotune_shardings	bool	sharding autotune
xla_jf_spmd_threshold_for_windowed_einsum_mib	float	windowed-einsum SPMD 阈值（MiB）
xla_jf_bf16_propagation	bool	bf16 传播

陷阱 — xla_tpu_allow_large_2nd_minor_layout_for_x16 及其 _x8 / _x4 兄弟是 int 类型，不是 bool，尽管 allow_ 前缀在其他地方表示布尔值。_for_x16 后缀暗示一个三态或计数整数，而不是开/关 gate（LOW 置信度：类型由后缀推断，未由字节确认）。重新实现者不能假设每个 allow_* 标志都是布尔值。

---

8. 内存 / 分配 + 运行时 {#8-memory--allocation--runtime}

目的

分配旋钮（27 个 xla_tpu_ + 通用标志）控制 OOM 处理、HBM/VMEM/SMEM spilling、碎片整理和分配 backtrace。运行时/cache/driver 家族（tpu_*，69 个）控制编译缓存、driver watchdog 和 core-dump 行为；这些是运行时旋钮，不是编译期旋钮。

目录 — 分配 + runtime/cache

标志	类型	默认值	效果
xla_tpu_impure_oom_fast_exit_threshold	int	10（+0x48=0x0a）	OOM fast-exit 阈值
xla_enable_megacore_hbm_spill	bool	true	megacore HBM spill
xla_tpu_always_spill_to_default_memory	bool	(unrec)	始终 spill 到默认内存（proto 字段）
xla_jf_poison_vmem_allocations	bool	(unrec)	poison VMEM 分配（调试）
xla_jf_memory_allocator_include_backtrace	bool	(unrec)	分配 backtrace
xla_jf_lsra_v2_spill_reporter_threshold	int	(unrec)	LSRA spill-report 阈值
xla_hbm_logging_buffer_size_bytes	int	(unrec)	HBM 日志缓冲区大小
tpu_compilation_cache_persists_in_riegeli	bool	(unrec)	缓存持久化格式
tpu_persistent_compilation_cache_location	string	(unrec)	缓存位置路径
tpu_persistent_compilation_cache_ttl_secs	int	(unrec)	缓存 TTL
tpu_driver_callback_watchdog_timeout	int	(unrec)	driver watchdog 超时
tpu_core_dump_directory	string	(unrec)	core-dump 目录
tpu_log_allocations_on_oom	bool	(unrec)	OOM 时记录分配
DANGEROUS_tpu_runtime_abi_verification_disabled	bool	(unrec)	禁用 ABI 验证

怪癖 — xla_tpu_impure_oom_fast_exit_threshold 默认值为 10（字节证据：内联 FlagImpl+0x48 = 0x0a，无 Gen reloc），是正计数，不是 -1 "disabled" 哨兵。impure_ 前缀是 libtpu 命名约定，标记约 30 个非确定性 / 日志 / 有副作用的旋钮（impure_cost_model_logging_options、impure_llo_lifecycle_log_mode、impure_probability_of_host_offloading）。重新实现者应将 impure_ 标志视为运行时可观察的侧信道，而不是纯编译决策。

---

9. Debug / Dump / Log / Trace

目的

77 个 xla_tpu_ debug/dump 旋钮，加上通用 xla_jf_dump_* 和 xla_enable_*_trace 家族（完整组中 181 个）。这些控制 HLO/LLO/MLIR 转储、trace、NaN/SDC 检查和 log recorder。xla_jf_dump_* 家族是 Jellyfish 后端的转储表面；xla_sc_dump_* 是 SparseCore 对应项。

目录 — dump / trace / verify

标志	类型	默认值	效果
xla_tpu_enable_tile_log_recorder	bool	false	tile log recorder
xla_jf_debug_level	int	1	Jellyfish 调试详细程度
xla_jf_run_verifier	bool	false	运行 HLO verifier
xla_jf_dump_to	string	(unrec)	Jellyfish 转储目录
xla_jf_dump_hlo_text	bool	(unrec)	转储 HLO 文本
xla_jf_dump_llo_html	bool	(unrec)	转储 LLO HTML
xla_jf_dump_isa_program_proto	string	(unrec)	转储 ISA program proto
xla_jf_dump_extended_fingerprint	string	(unrec)	extended fingerprint 转储
xla_jf_collect_llo_stack_trace	bool	(unrec)	收集 LLO stack trace
xla_sc_dump_llvm_ir_to	string	(unrec)	转储 SC LLVM IR
xla_sc_dump_mlir_to	string	(unrec)	转储 SC MLIR
xla_enable_hlo_trace	bool	(unrec)	HLO trace
xla_enable_mxu_trace	bool	(unrec)	MXU trace
xla_enable_transpose_trace	bool	(unrec)	transpose trace
xla_dump_hlo_memory_schedule_info	bool	(unrec)	转储 memory schedule 信息

目录 — LLVM-emitter 转储（xla_llvm_*，4 个）

标志	类型	效果
xla_llvm_isa_emitter	bool	启用 LLVM→ISA emitter
xla_llvm_isa_emitter_bundles	bool	发射 instruction bundles
xla_llvm_isa_emitter_force	bool	强制使用 LLVM ISA emitter
xla_llvm_generate_xla_compatible_dwg	bool	XLA-compatible debug-with-graph

---

10. Autotune / AutoFDO

目的

23 个 xla_tpu_autofdo_* 标志驱动 profile-guided optimization：按 fingerprint 加载预调优的标志、布局、调度和 shardings，以及 FlagNet predictor。AutoFDO 是 fingerprint→tuning 缓存：模块的 fingerprint 索引一组已存储决策，从而绕过实时 cost model。

目录 — AutoFDO

标志	类型	效果
xla_tpu_autofdo	bool	AutoFDO 主 gate
xla_tpu_autofdo_profile_file	string	profile 文件路径
xla_tpu_autofdo_load_module_layout_fingerprint	string	每模块 layout fingerprint
xla_tpu_autofdo_load_module_flag_fingerprint	string	每模块 flag fingerprint
xla_tpu_autofdo_module_flags / _module_layouts	bool	应用 flag / layout 调优
xla_tpu_autofdo_flagnet	enum	FlagNet predictor 模式
xla_tpu_autofdo_flagnet_confidence_threshold	int	FlagNet 置信度截止
xla_tpu_autofdo_hlo_module_size_threshold	int	AutoFDO 的大小阈值
xla_tpu_autotune_layouts / _schedules / _shardings	bool	autotune layouts/schedules/shardings
xla_tpu_autofdo_proposed_layout_file	string	proposed-layout 文件

---

11. 确定性边界

上面的整个目录基于两种信任级别不同的提取方法，重新实现者必须尊重这条边界。

名称 — CERTAIN。 2048 个已注册名称来自 AbslFlagHelpGenFor<name> 改编符号集合，这是 absl::Flag 全局变量的 1:1 枚举（sort -u | wc -l = 2048）。本页列出的每个名称都能解析到这样的符号。.rodata 中还会出现额外的类标志字符串（已弃用别名 / 错误消息引用），但它们不是已注册标志；它们不计入 2048 个，也不在本页范围内。

类型 — HIGH，主要为推断。 只有后缀约定（XLA 自己的注册约定）为约 99% 的标志定型。有歧义的后缀（_threshold int-or-float、_mode/_level int-enum-or-string）会逐行标记为 LOW。字节确认一个类型需要从 FLAGS_<name> 符号的 RTTI 中取得 absl::Flag<T> 模板实参；这里未做。

默认值 — 只有 18 个是 CERTAIN。 大多来自 help/错误字符串中的 =value 子句；xla_tpu_embedding_table_oblongness_threshold 是直接从其 AbslFlagDefaultGenFor 初始化器恢复的（movl $0x42480000 = 50.0f @ 0x1d7068c0），该值覆盖其错误字符串建议的 =1 workaround 值。其他全部位于 .text 初始化器（xla::DefaultDebugOptions() 和逐标志 FLAGS_* 静态构造器）中，无法从字符串恢复。完整的字节证据集合：

标志	默认值
xla_tpu_accumulate_into_mrb	true（+0x48=01）
xla_tpu_rwb_fusion	true（+0x48=01）
xla_tpu_dot_dot_fusion	true（+0x48=01）
xla_tpu_nested_dot_fusion	true
xla_tpu_allow_deeply_nested_fusion_numerical_diff	true
xla_tpu_fusion_debugger_instrument_inputs	AUTO（Gen movw $0）→ off
xla_tpu_scheduling_annotation_deannotate_unsupported_groups	false（AutoOr，AUTO→off）
xla_tpu_enable_tile_log_recorder	false（+0x48=00）
xla_tpu_enable_sc_log_recorder	false（AutoOr，AUTO→off）
xla_tpu_enable_sparse_core_reduce_scatter_v2	true（AutoOr AUTO→on；version 组合）
xla_tpu_enable_offloading_gather_to_sparsecore	false
xla_tpu_enable_offloading_scatter_to_sparsecore	ENABLED（Gen movb $2）
xla_tpu_impure_oom_fast_exit_threshold	10（+0x48=0x0a）
xla_tpu_embedding_table_oblongness_threshold	50.0（float）
xla_enable_megacore_hbm_spill	true
xla_jf_debug_level	1
xla_jf_run_verifier	false
megascale_use_numa_aware_threadpool	true（+0x48=01）

说明 — 对于约 330 个属于 AutoProto oneof 的 TCE 字段，"default" 甚至不是扁平值，而是内置在各 consumer 中的 AUTO 解析极性，并可选择由每 TpuVersion 的 MSA overlay 重写。有效值是 flag-default ⊕ AUTO-polarity ⊕ per-version-overlay。该解析由 autoproto-autoor-resolution.md 负责；本图谱编目的是标志名称和推断类型，不是其解析后的值。

---

相关组件

组件	关系
AbslFlagHelpGenFor<name> @ symtab	每个标志的 1:1 名称枚举符号
xla::MakeDebugOptionsFlags @ 0x1e66ce80	注册 xla_* DebugOptions 标志
OverrideTpuCompEnvByCmdLineFlags @ 0x1d73e640	将 TPU 家族绑定进 TCE
GetLibTpuInitArguments @ 0x20ccca20	所有标志的 LIBTPU_INIT_ARGS 入口
PartialReduceEmitter::ValidateShapes @ 0x10eaa120	承载 nested_dot_fusion=true 证据字符串

交叉引用

• overview.md — 本图谱所在的四阶段 flag→DebugOptions→TCE→effective-value 流水线
• flag-families.md — 完整的前缀→所有者分类；每个家族落入哪个 proto
• env-vars.md — LIBTPU_INIT_ARGS 以及供给解析的 env-var 名册
• debugoptions-proto.md — xla::DebugOptions：普通 xla_* 标志背后的 290 字段 schema（完整 descriptor 解码；早先的 "111 wire-fields / 94 flag-wired" 数字是部分样本，已在该处 superseded）
• tpu-compilation-environment.md — xla_tpu_* / xla_jf_* / xla_sc_* 标志落入的 1121 字段 TCE proto
• autoproto-autoor-resolution.md — 让约 330 个字段的 "default" 成为解析规则的 AUTO 三态
• tce-field-offsets-defaults.md — 字节精确的 field→offset→default 参考，用于恢复没有字符串证据的默认值