xla.DebugOptions Proto

本页所有符号、地址和字段编号均适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（构建 libtpu_lts_20260413_b_RC00，build-id md5 89edbbe81c5b328a958fe628a9f2207d，781,691,048 字节，ELF x86-64 DYN，未 stripped）。字段名和枚举类型名逐字取自嵌入 .rodata 的 descriptor pool。其他版本会不同。

摘要

xla::DebugOptions 是共享的 XLA 编译器/运行时配置消息，也就是 XLA 在 CPU、GPU 和 TPU 后端之间整体携带的那个 proto。它会随 HLO 模块跨越 JAX/PJRT 前端 → 后端边界：它是 HloModuleConfigProto 的字段 14，也是 ExecutionOptions 的字段 4。在 JAX-on-GPU 构建中，它是公共 --xla_* flag 表面（--xla_dump_to、--xla_step_marker_location，……）背后的 proto。在这个 libtpu 构建中，它基本是惰性的：TPU 编译器真正的旋钮位于含 1121 个字段的 TpuCompilationEnvironment 中，且只有两个 DebugOptions 字段连接到了已注册的 absl::Flag。

本页负责逐字段 schema：字段编号 → 名称 → wire type → C++/proto 类型，按区域分组并按字段编号排序。这是本 wiki 其余页面引用的权威 DebugOptions 字段字典。descriptor pool 携带 290 个存活字段（最大字段编号 501，211 个编号空洞）、17 个嵌套枚举、2 个嵌套 map-entry 消息，以及零个真正的（用户声明的）oneof。每个标量都是包在合成单成员 oneof 中的 proto3 optional，提供显式 has-bit presence，也就是说 wire 上的 DebugOptions 会精确记录前端触碰了哪些旋钮。

重实现者的参照框架是 OpenXLA 自己的 xla.proto。两个 TPU 特有事实会改变它：第一，TPU 构建不会从 proto 中裁剪 GPU/CPU 字段，183 个 xla_gpu_* + 31 个 xla_cpu_* + 5 个 xla_llvm_* 字段仍保留在 descriptor 中，以便 GPU 构建的 XLA 可以往返传递它们，但没有 TPU 代码读取它们，也没有 flag 设置它们。第二，字段编号稀疏，且是通过删除形成墓碑，而不是通过声明 reserved 范围：descriptor 不携带 reserved_range / reserved_name，所以 211 个空洞只是已删除 flag 的孔位，仅靠评审纪律守护。

注意 — DebugOptions 携带 290 个存活字段，已从 pool index 403 的 descriptor 完整解码（290 个字段名与二进制交叉匹配）。这是字段清单的权威 schema 计数；其他位置的 111 项 tag 抽样会低估它。

对重实现而言，契约是：

字段 schema — 290 个字段编号、名称和 proto 类型，按字段编号排序，使重实现者可以重建 descriptor 并往返处理 wire format。
presence 模型 — 每个标量都是 proto3-optional（合成 oneof，has-bit presence）；12 个字段是 repeated/map。这使得“用户设置了这个旋钮”可以和“保留默认值”区分开来。
TPU 惰性拆分 — 哪些字段连接到 flag（2 个），哪些仅能通过 PJRT debug_options 设置（generic/dump/hlo/llvm），以及哪些是 GPU/CPU 仅 proto 携带项（214 个），没有 TPU 代码读取。


消息	`xla.DebugOptions`（package `xla`，proto3）
Descriptor	FileDescriptorProto index 403 = `…/compiler/xla/xla.proto`（VA `0xc021470`）
存活字段	290（最大 field# 501，211 个空洞）
全默认基线	`xla::DefaultDebugOptionsIgnoringFlags()` @ `0x1e66a860`（mangled `_ZN3xla32DefaultDebugOptionsIgnoringFlagsEv`）
默认值差异 helper	`GetNonDefaultDebugOptions` @ `0x1c920540` · `DumpNonDefaultDebugOptions` @ `0x1c920d80`
嵌套枚举	17（+ 1 个字段引用外部 `xla.autotuner.Backend`）
嵌套消息	2 个 map-entry 类型（由 `map<K,V>` 自动生成）
真正 oneof	0（278 个合成 proto3-optional 标记）
连接到 flag 的字段	2 — `xla_tpu_detect_nan` (135), `xla_tpu_detect_inf` (136)
置信度	CONFIRMED（字段名 + 枚举名 + 基线符号字节锚定），除非行内另有说明

1. 类型和前缀统计

类型分布

290 个字段按 proto 类型分解如下（可从 descriptor 的逐字段 type card 重新推导）：

Proto 类型	数量	C++ accessor 类型
bool	185	`bool`
int32	30	`int32_t`
string	26	`std::string`
enum	23	nested-enum / external enum
int64	21	`int64_t`
message	3	1 个子消息 + 2 个 map-entry
float	2	`float`

怪癖 — DebugOptions 有零个 double 和零个 unsigned 字段，不同于 TCE（携带 14 个 double 和 15 个 unsigned）。DebugOptions 是一个扁平配置 proto，几乎完全由 bool 开关构成（185/290，64%）。重实现者可以假设除 2 个 float 字段外，所有标量都是 signed 或 bool。

前缀分布和 TPU 构建状态

最重要的结构事实：字段的前缀族决定它在这个 TPU 构建中是否有任何作用。

前缀	数量	TPU 构建状态
`xla_gpu_*`	183	仅 proto — 无 flag，无 TPU consumer（GPU 携带项）
generic `xla_*`	39	仅 proto — 只能通过 PJRT `debug_options` 设置
`xla_cpu_*`	31	仅 proto — 无 flag，无 TPU consumer（CPU 携带项）
`xla_dump_*`	24	仅 proto — 只能通过 PJRT `debug_options` 设置
`xla_hlo_*`	6	仅 proto — 只能通过 PJRT `debug_options` 设置
`xla_llvm_*`	5	仅 proto — 只能通过 PJRT `debug_options` 设置
`xla_tpu_*`	2	连接到 FLAG（135 `detect_nan`，136 `detect_inf`）

坑点 — 枚举 DebugOptions 字段的重实现者会看到 183 个 xla_gpu_* 字段（例如 xla_gpu_enable_triton_gemm、xla_gpu_autotune_level），它们看起来像活旋钮。它们不是：这个二进制中任何地方都没有注册 xla_gpu_* flag（零个 AbslFlagHelpGenForxla_gpu_* 符号，已确认）。GPU/CPU 字段存在于共享 descriptor 中，纯粹是为了让 GPU 构建的 XLA 可以序列化/反序列化同一个消息；在 TPU 上它们是无效负载。不要把它们连接到任何东西。（CONFIRMED — 符号扫描返回 0。）

2. Presence 模型

Proto3-optional，而不是真正 oneof

descriptor 声明了 278 个 “oneof”，但每一个都是合成的单成员 proto3-optional 标记（_<fieldname>），每个标量字段一个。真正的多成员用户声明 oneof 为零。因此每个标量都携带显式 has-bit：前端可以区分“设置为 false”和“保留默认 false”。

text

field 113  xla_dump_hlo_as_proto : bool
  └─ synthetic oneof _xla_dump_hlo_as_proto  (1 member, proto3-optional)
       → has_xla_dump_hlo_as_proto()  reads the has-bit
       → xla_dump_hlo_as_proto()      reads the value (zero if unset)
```text

12 个非 `optional` 字段是 10 个 repeated-scalar/enum（4 个 `repeated string`，6 个 `repeated enum`）和 2 个 map 字段（§4）— 没有独立的（非 map）repeated message 字段。Repeated/map 字段具有列表/map presence（size），而不是 has-bit。

> **注意 —** 这个 presence 模型正是 `GetNonDefaultDebugOptions` @ `0x1c920540` 和 `DumpNonDefaultDebugOptions` @ `0x1c920d80` 存在的原因：它们使用 has-bit 将已填充的 DebugOptions 与全默认基线（`DefaultDebugOptionsIgnoringFlags` @ `0x1e66a860`）做差异比较，只发出用户实际改动的字段。丢弃 proto3-optional presence 的重实现会丢失这些函数依赖的“用户触碰了什么”信号。

### 默认值在 `.text` 中，而不在 descriptor 中

proto3 不携带 descriptor 级字段默认值，每个标量的 *wire* 默认值都是零值（`false`/`0`/`""`/enum-0）。*有效*运行时默认值是前端覆盖之前 `DefaultDebugOptionsIgnoringFlags` @ `0x1e66a860` 写入的内容。该函数是 `.text` 中一个大型构造器；恢复出的逐字段默认值归 [`default-debugoptions.md`](default-debugoptions.md) 所有。本页负责 schema；该页负责值。

> **注意 —** 只有 **两个** DebugOptions 字段连接到 flag：将全部 290 个字段名与二进制已注册的 `AbslFlagHelpGenForxla_*` 符号交叉匹配，只找到两个交集，`xla_tpu_detect_nan` (135) 和 `xla_tpu_detect_inf` (136)（两个 `detect` flag-gen 符号均存在）。经典 dump/HLO 旋钮（`xla_dump_to`、`xla_hlo_profile`，……）在这个构建中**不是**独立 absl flag，它们只通过 PJRT `CompileOptions.debug_options` proto 路径到达 DebugOptions。其他 1328 个已注册 `xla_*` flag 落在 TCE 中，而不是这里。

---

## 3. 按区域划分的字段 Schema

完整的 290 字段 schema 如下，按功能区域分组，并在每组内按字段编号排序。列说明：**#** = 字段编号；**type** 携带 proto label（`repeated`）和 enum/message 类型名；**conf** = 名称/类型字节精确的置信度（`C` = 已与 descriptor 字符串确认，`H` = 高）。右列在相关处给出 flag 连接 / dump 触发说明。这里不显示默认值 — 见 [`default-debugoptions.md`](default-debugoptions.md)。

### 3.1 HLO 调试 / profile（`xla_hlo_*`）— 6 个字段

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 2 | `xla_hlo_graph_addresses` | bool | C | 消息从字段 2 开始（字段 1 已删除） |
| 9 | `xla_hlo_profile` | bool | C | |
| 92 | `xla_hlo_graph_sharding_color` | bool | C | |
| 370 | `xla_hlo_pass_fix_detect_cycles` | bool | C | |
| 447 | `xla_hlo_print_inline_stack_frames` | bool | C | |
| 106 | `xla_hlo_evaluator_use_fast_path` | bool | C | |

### 3.2 HLO pass 控制（generic `xla_*`）— 节选

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 30 | `xla_disable_hlo_passes` | repeated string | C | 逐 pass 禁用列表 |
| 104 | `xla_disable_all_hlo_passes` | bool | C | |
| 124 | `xla_enable_hlo_passes_only` | repeated string | C | allow-list |
| 31 | `xla_backend_optimization_level` | int32 | C | -O level |
| 33 | `xla_embed_ir_in_executable` | bool | C | |
| 35 | `xla_eliminate_hlo_implicit_broadcast` | bool | C | |
| 107 | `xla_allow_scalar_index_dynamic_ops` | bool | C | |
| 122 | `xla_allow_excess_precision` | bool | C | |
| 142 | `xla_multiheap_size_constraint_per_heap` | int32 | C | |
| 251 | `xla_debug_buffer_assignment_show_max` | int64 | C | |
| 293 | `xla_reduce_window_rewrite_base_length` | int64 | C | |
| 315 | `xla_syntax_sugar_async_ops` | bool | C | |
| 335 | `xla_enable_fast_math` | bool | C | |
| 363 | `xla_unsupported_crash_on_hlo_pass_fix_max_iterations` | bool | C | |
| 379 | `xla_unsupported_crash_on_hlo_pass_noop_change` | bool | C | |
| 380 | `xla_unsupported_crash_on_hlo_pass_silent_hlo_change` | bool | C | |
| 419 | `xla_keep_shardings_after_spmd` | bool | C | |
| 452 | `xla_enable_hlo_sharding_v3` | bool | C | |
| 463 | `xla_recognize_reduction_optimization_level` | int32 | C | |
| 187 | `xla_partitioning_algorithm` | enum `PartitioningAlgorithm` | C | SPMD partitioner 选择 |
| 344 | `xla_pjrt_allow_auto_layout_in_hlo` | bool | C | |
| 397 | `xla_early_exit_with_layouts` | bool | C | |

### 3.3 Layout / 测试 layout（generic `xla_*`）

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 90 | `xla_test_all_output_layouts` | bool | C | |
| 91 | `xla_test_all_input_layouts` | bool | C | |
| 373 | `xla_test_add_command_buffer_mode` | bool | C | |

### 3.4 数值 / NaN-Inf 检测 — TPU 有意义的核心

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 135 | `xla_tpu_detect_nan` | bool | C | **连接到 FLAG**（存在 `AbslFlagHelpGenForxla_tpu_detect_nan`） |
| 136 | `xla_tpu_detect_inf` | bool | C | **连接到 FLAG**（存在 `AbslFlagHelpGenForxla_tpu_detect_inf`） |
| 403 | `xla_detect_unstable_reductions` | enum `DetectionMode` | C | |
| 432 | `xla_detect_unstable_reductions_post_optimizations` | enum `DetectionMode` | C | |
| 426 | `xla_gpu_detect_nan` | enum `DetectionMode` | C | GPU 携带项（注意：enum，不是 bool） |
| 428 | `xla_gpu_detect_inf` | enum `DetectionMode` | C | GPU 携带项（注意：enum，不是 bool） |

> **怪癖 —** `xla_tpu_detect_nan` (135) 和 `xla_tpu_detect_inf` (136) 是 `bool`，但*较晚加入的* `xla_gpu_detect_nan` (426) / `xla_gpu_detect_inf` (428) 是三态 `DetectionMode` 枚举（`NONE`/`WARNING`/`FAIL`）。两个 TPU bool 字段是 libtpu 中唯一具有已注册 `absl::Flag` 的 DebugOptions 字段，它们是 JAX-on-TPU 用户实际能通过 flag 表面翻转的活数值旋钮。重实现者不能假设 `_detect_nan` 家族在各后端之间类型统一。

### 3.5 TPU step marker — 唯一有 TPU 意义的枚举字段

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 108 | `xla_step_marker_location` | enum `StepMarkerLocation` | C | 控制 TPU step-marker 放置 |

`StepMarkerLocation` 在 §5 中枚举。这是唯一会实质影响 TPU codegen 的 DebugOptions 枚举字段（profiler step marker 相对于 `while` 循环的插入位置）。

### 3.6 Dump / 调试输出（`xla_dump_*`）— 24 个字段

dump 家族仅 proto 可用（PJRT `debug_options` 路径）。其中六个是 **dump 触发器**：其 set 状态会门控特定 HLO-family proto 的序列化的 `bool`（交叉引用到各自发出的 proto）。

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 109 | `xla_dump_to` | string | C | 输出目录 |
| 110 | `xla_dump_hlo_module_re` | string | C | 模块名 regex |
| 111 | `xla_dump_hlo_pass_re` | string | C | pass 名 regex |
| 154 | `xla_dump_hlo_pipeline_re` | string | C | pipeline 名 regex |
| 433 | `xla_dump_emitter_re` | string | C | emitter regex |
| 112 | `xla_dump_hlo_as_text` | bool | C | |
| 113 | `xla_dump_hlo_as_proto` | bool | C | **→ `HloProto`** |
| 114 | `xla_dump_hlo_as_dot` | bool | C | |
| 115 | `xla_dump_hlo_as_url` | bool | C | |
| 116 | `xla_dump_hlo_as_html` | bool | C | |
| 164 | `xla_dump_hlo_as_long_text` | bool | C | |
| 118 | `xla_dump_hlo_snapshots` | bool | C | **→ `HloSnapshot`** |
| 144 | `xla_dump_module_metadata` | bool | C | **→ `HloModuleMetadataProto`** |
| 182 | `xla_dump_latency_hiding_schedule` | bool | C | **→ `ScheduleProto`** |
| 381 | `xla_dump_full_hlo_config` | bool | C | **→ `HloModuleConfigProto`** |
| 405 | `xla_dump_hlo_unoptimized_snapshots` | bool | C | **→ `HloUnoptimizedSnapshot`** |
| 131 | `xla_dump_include_timestamp` | bool | C | |
| 132 | `xla_dump_max_hlo_modules` | int32 | C | |
| 149 | `xla_dump_fusion_visualization` | bool | C | |
| 151 | `xla_dump_compress_protos` | bool | C | |
| 153 | `xla_dump_disable_metadata` | bool | C | |
| 185 | `xla_dump_enable_mlir_pretty_form` | bool | C | |
| 290 | `xla_dump_large_constants` | bool | C | |
| 466 | `xla_dump_buffer_assignment_analysis` | bool | C | |

相邻的 dump 相关 generic 字段：252 `xla_detailed_logging`（bool）、253 `xla_enable_dumping`（bool）、436 `xla_enable_scoped_logging_timers`（bool）。

### 3.7 Command buffer / runtime（generic `xla_*`）

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 311 | `xla_cmd_buffer_trace_cache_size` | int64 | C | |
| 317 | `xla_enable_command_buffers_during_profiling` | bool | C | |
| 364 | `xla_flags_reset` | bool | C | |
| 408 | `xla_disable_automatic_host_compute_offload` | bool | C | |
| 429 | `xla_enable_enzyme_comms_opt` | bool | C | |
| 439 | `xla_allow_h2h_copy_when_automatic_host_compute_offload_disabled` | bool | C | |
| 102 | `xla_force_host_platform_device_count` | int32 | C | |

### 3.8 GPU 继承但惰性（`xla_gpu_*`）— 183 个字段，仅 proto

完整的 183 个字段存在于 descriptor 中，但没有 TPU 代码读取。最好按其*轴向*描述，而不是逐行倾倒；下面的代表性锚点确认该家族完整存在，并覆盖其功能簇。每行都是 `gpu*` 仅 proto。

| cluster | representative fields (#) | types |
|---|---|---|
| autotuning | `xla_gpu_autotune_level`(123), `xla_gpu_autotune_max_solutions`(288), `xla_gpu_experimental_autotune_cache_mode`(324, enum `AutotuneCacheMode`), `xla_gpu_experimental_autotune_backends`(442, repeated external enum `xla.autotuner.Backend`), `xla_gpu_autotune_gemm_rtol`(316, float) | int32/int64/enum/float |
| Triton GEMM | `xla_gpu_enable_triton_gemm`(188), `xla_gpu_triton_gemm_any`(190), `xla_gpu_unsupported_enable_triton_gemm`(322), `xla_gpu_experimental_enable_triton_heroless_priority_fusion`(340) | bool |
| collectives / NCCL | `xla_gpu_all_reduce_combine_threshold_bytes`(157, int64), `xla_gpu_nccl_termination_timeout_seconds`(163, int64), `xla_gpu_enable_pipelined_all_reduce`(217), `xla_gpu_disable_async_collectives`(289, repeated enum `CollectiveOpType`) | int64/bool/enum |
| command buffer | `xla_gpu_enable_command_buffer`(258, repeated enum `CommandBufferCmdType`), `xla_gpu_command_buffer_scheduling_mode`(404, enum `CommandBufferSchedulingMode`), `xla_gpu_command_buffer_update_mode`(469, enum `CommandBufferUpdateMode`), `xla_gpu_command_buffer_unroll_loops`(411) | enum/bool |
| latency / scheduling | `xla_gpu_enable_latency_hiding_scheduler`(186), `xla_gpu_enable_analytical_latency_estimator`(255), `xla_gpu_enable_analytical_sol_latency_estimator`(356), `xla_gpu_analytical_latency_estimator_options`(357, map) | bool/map |
| codegen / cuDNN / cuBLAS | `xla_gpu_enable_cublaslt`(166), `xla_gpu_cudnn_gemm_fusion_level`(285, int32), `xla_gpu_enable_cudnn_layer_norm`(262), `xla_gpu_libnvjitlink_mode`(343, enum `LibNvJitLinkMode`) | bool/int32/enum |
| while-loop | `xla_gpu_enable_while_loop_unrolling`(294, enum `WhileLoopUnrolling`), `xla_gpu_enable_while_loop_double_buffering`(248) | enum/bool |
| diagnostics | `xla_gpu_shape_checks`(170, enum `ShapeChecks`), `xla_gpu_pgle_accuracy_checker`(341, enum `PGLEStrictnessLevel`), `xla_gpu_detect_nan`(426)/`detect_inf`(428, enum `DetectionMode`) | enum |
| paths / files | `xla_gpu_cuda_data_dir`(61), `xla_gpu_dump_autotune_results_to`(222), `xla_gpu_kernel_cache_file`(306), `xla_gpu_collectives_implementation`(468) | string |

> **注意 —** 183 个 `xla_gpu_*` 字段没有在这里逐一记录，因为它们在 TPU 上全部惰性；记录每个“含义”只会在没有重实现价值的情况下复述字段名（§1 坑点）。簇表证明该家族在 descriptor 中存在且完整（因此 wire format 可往返），这就是 TPU 重实现者所需的全部。字段 451 `xla_gpu_execution_terminate_timeout` 是 `string`，不是 int，这是重新生成 proto 时值得注意的一个有意 descriptor 怪癖。

### 3.9 CPU 继承但惰性（`xla_cpu_*`）— 31 个字段，仅 proto

同样仅 proto。确认该家族的代表性锚点：

| # | name | type |
|---:|---|---|
| 60 | `xla_cpu_multi_thread_eigen` | bool |
| 97 | `xla_cpu_use_onednn` | bool |
| 99 | `xla_cpu_enable_fast_math` | bool |
| 120 | `xla_cpu_fast_math_honor_nans` | bool |
| 308 | `xla_cpu_prefer_vector_width` | int32 |
| 333 | `xla_cpu_max_isa` | string |
| 365 | `xla_cpu_experimental_xnn_graph_fusion_mode` | enum `XnnGraphFusionMode` |
| 399 | `xla_cpu_experimental_onednn_fusion_type` | repeated enum `LibraryFusionType` |
| 448 | `xla_cpu_scheduler_type` | enum `CpuSchedulerType` |
| 467 | `xla_cpu_opt_preset` | enum `CpuOptPreset` |

### 3.10 LLVM IR metadata（`xla_llvm_*`）— 5 个字段，仅 proto

| # | name | type |
|---:|---|---|
| 70 | `xla_llvm_enable_alias_scope_metadata` | bool |
| 71 | `xla_llvm_enable_noalias_metadata` | bool |
| 72 | `xla_llvm_enable_invariant_load_metadata` | bool |
| 73 | `xla_llvm_disable_expensive_passes` | bool |
| 300 | `xla_llvm_force_inline_before_split` | bool |

### 3.11 逃生口 — `map<string,string>`

| # | name | type | conf | note |
|---:|---|---|:--:|---|
| 500 | `xla_backend_extra_options` | `map<string,string>` | C | 规范的 typed-flag 逃生口 |
| 357 | `xla_gpu_analytical_latency_estimator_options` | `map<string,string>` | C | GPU 携带项 |

`xla_backend_extra_options` (500) 是唯一能承受未知 key 添加的字段：后端无需 typed 字段即可读取的任意 string→string 选项。它被有意放在字段 500，以便为顺序增长留下 471–499（§6）。

---

## 4. 嵌套消息和 Map

descriptor 正好携带 2 个嵌套消息，二者都是自动生成的 map-entry 类型，另有一个由字段 424 引用的*外部*子消息。

```text
DebugOptions.XlaBackendExtraOptionsEntry { string key = 1; string value = 2; }
  └─ field 500 xla_backend_extra_options : map<string,string>

DebugOptions.XlaGpuAnalyticalLatencyEstimatorOptionsEntry { string key = 1; string value = 2; }
  └─ field 357 xla_gpu_analytical_latency_estimator_options : map<string,string>  (gpu carryover)

External (defined elsewhere in xla.proto, NOT nested in DebugOptions):
  field 424 xla_gpu_experimental_thunk_buffer_debug_filter : message xla.ThunkBufferDebugFilter
    xla.ThunkBufferDebugFilter {
      repeated xla.IntRangeInclusive thunk_id_ranges            = 1;
      repeated string                profile_annotation_regexes = 2;
    }
    xla.IntRangeInclusive { int64 first = 1; int64 last = 2; }

怪癖 — 字段 424 是 DebugOptions 中唯一真正的子消息字段；类型统计（§1）中的另外两个 “messages” 是自动生成的 map-entry 类型。数到 “3 个 message 字段” 的重实现者不应期待 3 个手写子消息，而是一个（ThunkBufferDebugFilter，GPU 携带项）加两个 map entry。（CONFIRMED — ThunkBufferDebugFilter 和 XlaBackendExtraOptionsEntry 名称在 descriptor 中有字节锚点。）

5. 嵌套枚举

全部 17 个嵌套枚举，逐值来自 descriptor。23 个 enum 类型字段除字段 442 外都使用其中之一；字段 442 引用外部 xla.autotuner.Backend（定义在单独的 descriptor-pool 文件中，值集未在此恢复）。

text

StepMarkerLocation (field 108 — the one TPU-meaningful enum):
  STEP_MARK_AT_ENTRY=0, STEP_MARK_AT_TOP_LEVEL_WHILE_LOOP=1,
  STEP_MARK_NONE=2, STEP_MARK_AT_SECOND_LEVEL_WHILE_LOOP=3
  -- non-sequential: NONE=2 sits BETWEEN the two while-loop values

ShapeChecks (170):            IGNORE=0, RUNTIME=1, COMPILE_TIME=2
PartitioningAlgorithm (187):  NOOP=0, _EXP0=1, _EXP1=2, _EXP2=3
CommandBufferCmdType (258, repeated):
  INVALID=0, FUSION=1, CUBLAS=2, CUDNN=3, COLLECTIVES=4, CONDITIONAL=5,
  WHILE=6, CUSTOM_CALL=7, CUBLASLT=8, DYNAMIC_SLICE_FUSION=9,
  DYNAMIC_SLICE_COPY_FUSION=10
CollectiveOpType (289, repeated):
  NOOP=0, ALLREDUCE=1, ALLGATHER=2, REDUCESCATTER=3, COLLECTIVEBROADCAST=4,
  ALLTOALL=5, COLLECTIVEPERMUTE=6, RAGGEDALLTOALL=7, ALLCOLLECTIVES=8
WhileLoopUnrolling (294):
  NO_UNROLL=0, DOUBLE_BUFFER=1, FULL_UNROLL=2, AUTO_UNROLL=3
AutotuneCacheMode (324):      UNSPECIFIED=0, UPDATE=1, READ=2
PGLEStrictnessLevel (341):    OFF=0, WARN=1, ERROR=2
LibNvJitLinkMode (343):       AUTO=0, DISABLED=1, ENABLED=2
PipelineParallelismOptLevel (351): DISABLE=0, ENABLE=1
XnnGraphFusionMode (365):     DISABLED=0, GREEDY=1, GREEDY_SLINKY=2, BYPASS_COST_MODEL=3
LibraryFusionType (399,400,422, all repeated):
  INVALID=0, DOT=1, ELTWISE=2, REDUCE=3, INDIVIDUAL_DOT=4, INDIVIDUAL_CONVOLUTION=5
DetectionMode (403,426,428,432): NONE=0, WARNING=1, FAIL=2
CommandBufferSchedulingMode (404): SERIALIZE=0, CONCURRENT=1, LHS=2, CONCURRENT_REGIONS=3
CpuSchedulerType (448):       DEFAULT=0, MEMORY_OPTIMIZED=1, CONCURRENCY_OPTIMIZED=2
CpuOptPreset (467):           DEFAULT=0, FAST_RUNTIME=1, FAST_COMPILE=2
CommandBufferUpdateMode (469): ALWAYS_UPDATE=0, NEVER_UPDATE=1, CAPTURE_CMD_NEVER_UPDATE=2
```text

> **坑点 —** `StepMarkerLocation` (108) 是 TPU 重实现者必须正确处理的枚举，其编号是个陷阱：`STEP_MARK_NONE=2` 位于两个 while-loop 放置值之间（`AT_TOP_LEVEL_WHILE_LOOP=1`、`AT_SECOND_LEVEL_WHILE_LOOP=3`）。按 ordinal 顺序驱动 step-marker 逻辑（“越高 = 越深”）是错误的，`NONE` 不是“最深”。按名称读取枚举值。该字段的有效 TPU 默认值（常被覆盖到偏离 `AT_ENTRY=0`）归 [`default-debugoptions.md`](default-debugoptions.md) 所有。

---

## 6. 字段编号空洞 — 删除项，而不是 Reserved 范围

该消息很稀疏：1–501 之间使用了 290 个编号，有 211 个空洞。descriptor 携带**没有** `reserved_range`，也**没有** `reserved_name`，这是每个空洞都是*已删除*字段（其行从 `xla.proto` 中移除）而非声明的 `reserved` 范围的正向证据。Upstream XLA 通过删除字段声明移除 flag；编号绝不会复用（protobuf 卫生），但守护它的只是评审纪律，而不是 `reserved` 关键字。

```text
Gaps (field numbers absent, 1..501):
  1, 3-8, 10-29, 32, 34, 36-59, 63-69, 74-89, 93-96, 98, 117, 119, 130,
  133-134, 139, 141, 143, 145, 152, 156, 158, 160-162, 167-169, 171-173,
  176-180, 183-184, 191-202, 204, 206-207, 211, 214, 218, 220-221, 226,
  229-230, 233-234, 238, 242-243, 249, 263-264, 266, 270-271, 275-276,
  278-279, 281-282, 286, 298-299, 302-303, 309, 313-314, 319-320,
  325-326, 330, 332, 346, 352, 354-355, 358, 361, 367, 369, 371, 385,
  394, 396, 398, 402, 423, 430, 443, 446, 464, 471-499

注意 — 字段 1 已删除（存活消息从字段 2 xla_hlo_graph_addresses 开始）。低位密集空洞（3–29、36–59、74–89）是早期 XLA 变动。471–499 块（29 个编号）是开放分配窗口：字段连续运行到 470，然后跳到带外的 500/501 对。为比 libtpu_lts_20260413_b_RC00 更新的 XLA 重新生成此 proto 的重实现者应预期 471–499 会开始填充。（CONFIRMED — descriptor 有零个 reserved entry；471–499 是有意增长窗口这一点为 HIGH。）

7. 重实现说明

往返处理整个 proto，即使是惰性字段。 为了反序列化经 PJRT CompileOptions.debug_options 传入的 DebugOptions，TPU 重实现必须接受全部 290 个字段（包括 214 个 GPU/CPU 携带项），否则会拒绝 GPU 构建前端序列化的消息。只读取约 70 个 generic/dump/hlo/tpu 字段；但要接受全部 290 个。
只连接 2 个 flag。 只有 xla_tpu_detect_nan (135) 和 xla_tpu_detect_inf (136) 需要 absl::Flag 绑定。其他一切都经由 proto 到达，绝不经由 flag 表面；flag 名称清单见 xla-flag-atlas.md。
保留 proto3-optional presence。 has-bit 是 GetNonDefaultDebugOptions / DumpNonDefaultDebugOptions 与基线做差异比较的依据；丢弃 presence 会破坏“用户触碰了什么”的日志。
默认值是单独关注点。 本页只负责 field# → name → type。每个字段的有效默认值（来自 DefaultDebugOptionsIgnoringFlags @ 0x1e66a860）归 default-debugoptions.md 所有。为 TPU 编译路径包装 DebugOptions 的 TCE 归 tpu-compilation-environment.md 所有。

Component	Relationship
`xla::DefaultDebugOptionsIgnoringFlags()` @ `0x1e66a860`	全默认基线构造器；拥有有效默认值
`xla::GetNonDefaultDebugOptions` @ `0x1c920540`	通过 has-bit 将已填充消息与基线做差异比较
`xla::DumpNonDefaultDebugOptions` @ `0x1c920d80`	只发出用户改动字段的日志路径
`TpuCompilationEnvironment` (`_table_` @ `0x21cfa9e0`)	TPU 私有主配置；DebugOptions 是 GPU/CPU 共享的同级项
`HloModuleConfigProto`（字段 14）/ `ExecutionOptions`（字段 4）	跨 PJRT 边界携带 DebugOptions 的 proto

交叉引用

overview.md — 三层 flag→proto→effective-value 管线；DebugOptions 作为 Stage 2a 所处的位置
xla-flag-atlas.md — 约 2107 个名称的 flag 表面；哪些 flag（2 个）设置 DebugOptions 字段，哪些 1328 个落在 TCE 中
default-debugoptions.md — DefaultDebugOptionsIgnoringFlags @ 0x1e66a860 的有效默认值（本页负责 schema；该页负责默认值）
tpu-compilation-environment.md — 为 TPU 编译路径包装 DebugOptions 的 1121 字段 TCE
autoproto-autoor-resolution.md — TCE 使用的 AutoOr<T> 三态 resolver（DebugOptions 本身没有 AutoProto 字段 — 全部 278 个 singular 字段都是普通 proto3-optional）

xla.DebugOptions Proto ​

摘要 ​

1. 类型和前缀统计 ​

类型分布 ​

前缀分布和 TPU 构建状态 ​

2. Presence 模型 ​

Proto3-optional，而不是真正 oneof ​

5. 嵌套枚举 ​

7. 重实现说明 ​

相关组件 ​

交叉引用 ​