TCE 字段字典 (B)
本页上的所有字段编号、结构体偏移、类型卡和默认值均适用于来自
libtpu-0.0.40-cp314的libtpu.so（build-id89edbbe81c5b328a958fe628a9f2207d，libtpu_lts_20260413_b_RC00，781,691,048 B，未 stripped）。其他 wheel 版本会重新编号并重排字段；不要跨 build 移植这些编号。
摘要
TpuCompilationEnvironment (TCE) 是 TPU PJRT 插件的主配置 proto：一条消息，其中每个字段也都是一个已注册的 absl::Flag， 因此每个 xla_* / megascale_* 开关既是序列化的 proto 字段，也是 命令行/环境 flag。该消息携带1121 个存活字段，编号最高到 #1218（空洞是已废弃/移除的编号）。字段编号 → 名称 → 类型映射是线上的契约：它决定序列化后的 env 如何反序列化、 某个 tag 会选择 TpuCompilationEnvironment::_table_ (@0x21cfa9e0) 中的哪个 FieldEntry，以及值最终落到结构体的哪个字节上。
本页是该字典的上半部分。它覆盖字段编号 #561 到 #1218（消息中的最高编号；两半在 #561 边界处分割， 较低的 560 个字段编号在字典 A 中，其余 561 个存活条目，即稠密 FieldEntry 数组的条目 561–1121，在本页），按字段编号排序，并在该范围内 按功能区域分组。对每个字段，它给出逐字的 flag/proto 名称、proto 类型 （以及当基础类型为 enum 或 message 时的包装 enum 或消息类型）， 以及置信度标签。下半部分，即字段 #1 到 #560，位于 tce-field-dictionary-a.md；两页在 #561 边界拼合。本页不会重复列出结构体偏移或字面默认值， 除非某个默认值是该字段唯一可区分的属性；这些列是 tce-field-offsets-defaults.md 的主题， 而消息级结构（解析表、has-bits、AutoProto oneof）在 tpu-compilation-environment.md 中说明。
该字典是一个参考目录，不是算法，因此它本身不携带重新实现契约。 重新实现者必须复现的是字段空间的形状，下面先用维度表捕获， 随后用按区域划分的名称列表捕获：
- field# → name → proto-type 映射，范围为 #561–#1218，这是上半 FieldEntry 行所编码的线上契约部分。
- 此范围内四个 enum 类型字段和 message 类型字段的包装解析 （AutoProto / typed-message）——仅有基础 proto 类型并不能告诉读者如何解码值； 包装 enum 或 AutoProto 分支类型才能做到。
- 该范围的类型直方图，使重新实现者知道要写入每个上半 FieldEntry 的 每种类型对应的
type_card（type_card是 proto 类型的 1:1 代理， 与下半部分共享）。
| 本页拥有的范围 | 字段 #561 – #1218（561 个存活条目；#1–#560 在字典 A 中） |
| 存活字段总数（消息） | 1121（最大字段编号 1218 / 0x4c2） |
| 解析表 | TpuCompilationEnvironment::_table_ @0x21cfa9e0 (.data.rel.ro) |
| FieldEntry 数组 | table+0x370，1121 × 12 B，按 field# 升序排序 |
| FieldEntry 布局 | {uint32 offset; uint32 has_idx; uint16 aux_idx; uint16 type_card} |
| 结构体大小 | sizeof(TpuCompilationEnvironment) = 0x15e8 (5608 B) |
| 默认实例 | TpuCompilationEnvironment_globals_ @0x227b87e0 |
注意 — 字段编号不是数组索引。FieldEntry 数组是稠密的 （1121 个条目），但字段编号是稀疏的（最大 1218）。对于字段编号
N，index_of(N) = (N-1) − (count of gap field-numbers below N)。两个字典页都按字段编号列出， 而不是按数组索引列出，所以读者无需计算空洞数量——但遍历_table_的 重新实现者必须计算。
范围形状 — #561–#1218 的类型直方图
整条消息的类型直方图（全部 1121 个字段）是固定的，并且每个 proto 基础 类型都精确映射到一个 16 位 type_card。上半部分继承相同的 type_card 常量；只有两半之间的计数不同。重新实现者要逐字写入 每个匹配类型 FieldEntry 的消息范围常量如下：
| Proto 类型 | type_card | 消息范围计数 | 包装 / 备注 |
|---|---|---|---|
bool | 0x0011 | 418 | 普通 bool |
int64 | 0x10d1 | 148 | 普通 int64 |
message | 0x0416 | 349 | AutoProto oneof 或 typed sub-message；aux_idx 解析类型 |
enum | 0x1891 | 74 | 8 个不同包装 enum 之一；67 个是 TristateProto.Value，另外 7 个是专用包装 |
string | 0x0c15 | 37 | SSO；消息范围内 7 个非空默认值 |
float | 0x1893 | 34 | f32 |
int32 | 0x1091 | 32 | 普通 int32 |
double | 0x18d3 | 14 | f64 |
uint32 | 0x0891 | 11 | 普通 uint32 |
uint64 | 0x08d1 | 4 | 普通 uint64 |
易错点 —
type_card是表内唯一的 proto 类型信号； 字段名称不存储在_table_中（名称位于 FileDescriptorProto 字符串流@0xbfa6060）。如果重新实现者按字段名称驱动解码， 就无法从解析表读取到任何东西——应按type_card驱动，并且对message/enum通过aux_idx进入 aux 数组（table+0x3800， 349 个条目）查找具体消息_table_或包装。
下面的按区域计数是上半部分的份额。它们按名称区域推导， 不是按 type_card 重新计数；应将按区域总数视为指示性信息 （HIGH），而上面的消息范围 type_card 常量是精确的（CERTAIN）。
如何阅读字典行
每行是 field# | name | type[/wrapper] | confidence。name 列是逐字的 absl::Flag 符号（FLAGS_<name> 全局）和 proto 字段名—— 二者完全相同；解析表恰有 1121 个 FieldEntry 行，且恰有 1121 个匹配的 FLAGS_* 对象，确认了这种 1:1 映射。type 列是来自 type_card 的 proto 基础类型；对 enum，它追加包装 enum；对 message，它追加 AutoProto 或 typed sub-message。置信度：
- CERTAIN — 本轮从二进制字符串流逐字读取名称，类型来自
type_card。 - HIGH — 名称和类型来自逐字节精确的解析表扫描；本轮未逐个重新 grep， 但与已确认集合一致。
- LOW — 本轮未将字段编号独立重新钉牢到名称（解析表顺序钉牢了它， 但具体名称归属是推断的）；行内标记。
注意 — 对于本轮未现场确认的名称，其字段编号 → 名称归属依赖解析表 FieldEntry 顺序（按 field# 升序）与 FileDescriptorProto 名称流的交叉校验。 当本页列出一个已命名、已锚定字段（包装 enum、字符串默认值、MSA 比率） 时，该名称已从
.rodata逐字 grep，置信度为 CERTAIN。若它按计数列出一个区域 而不命名每个成员，则该区域内逐字段名称为 HIGH，区域边界是已锚定的断言。
#561–#599 — SDC 检查器、大缓冲区缩放、标量
该段刚好位于字典 A 边界之上，主要由 SDC （silent-data-corruption）检查器系列和 memory-space-assignment (MSA) 大缓冲区缩放控制组成。两个已锚定字段钉住该段。
| Field# | Name | Type / wrapper |
|---|---|---|
| #578 | xla_tpu_alternate_memory_benefit_scaling_factor_for_large_buffers | string（默认 "SQRT"） |
| #583 | xla_tpu_sdc_checker_checksum_algo | enum / ChecksumAlgoProto.Value |
| #592 | xla_tpu_msa_inefficient_use_to_copy_ratio | float（默认 0.5） |
特例 — #578 是一个 string flag，其值是离散的类 enum token （
"SQRT"，代码路径中还有"LINEAR"/"NONE"），不是数字。 该字符串会在下游解析为缩放模式。重新实现者必须把它存储为std::stringSSO 字段（type_card 0x0c15），而不是 enum——线上类型 真的是 string。默认"SQRT"已从.rodata逐字 grep。
ChecksumAlgoProto.Value（#583 的包装）是 7 个专用 （非 Tristate）TCE 包装 enum 之一：DEFAULT=0、XOR=1、SIP_HASH_1_3=2 （值名 SIP_HASH_1_3 已逐字确认）。#583 默认为 0 (DEFAULT)。该段中的其余字段是 bool 和 int64 SDC-checker 开关（例如 xla_tpu_sdc_checker_*， 逐个名称为 HIGH 置信度；段边界是已锚定的断言）。
#600–#649 — 寄存器选择、MXU SDC 注入
该段承载寄存器分配器选择策略和 MXU SDC-injection 开销。寄存器选择策略是 上半部分中影响最大的 enum。
| Field# | Name | Type / wrapper |
|---|---|---|
| #611 | xla_tpu_sdc_inject_mxu_sequences_overhead | float（默认 1.2） |
| #631 | xla_tpu_register_selection_policy | enum / RegSelectPolicyProto.Value |
RegSelectPolicyProto.Value 有七个值：NONE=0、LEGACY=1、 BALANCE_PREV_NEXT_USES_IGNORE_FREE=2、BALANCE_PREV_NEXT_FREE_SPILL=3、 DOUBLE=4、WORST=5、DISREGARD_RECENTLY_USED=6。
特例 — #631 默认为
6(DISREGARD_RECENTLY_USED)，不是0。 该默认值由kGenFunc物化（@0x1d723540处的AbslFlagDefaultGenFor函数体，movb $0x6,(%rdi); ret），因此如果重新实现者把寄存器策略 初始化为零值（NONE），就会从第一次编译开始偏离发布版 TPU 寄存器分配器。 值名DISREGARD_RECENTLY_USED已逐字 grep，且在.rodata中唯一。
该段其余字段是 bool/int 寄存器分配器和 SDC-injection 开关， 逐个名称为 HIGH。
#650–#699 — sflag-Wait 统计、调度器开关
一段调度器和 sflag-wait instrumentation。一个已锚定字符串默认值。
| Field# | Name | Type / wrapper |
|---|---|---|
| #656 | xla_tpu_collect_sflag_wait_stats_filter | string（默认 "all"） |
注意 — #656 及其兄弟 #739（如下）都默认到字符串
"all"， 并作为 instrumentation 过滤器——即 sflag-wait 站点的逗号列表， 其中"all"表示“instrument every site”。存储为 string；空字符串是一个 不同的值（instrument none），因此不要把""和"all"折叠在一起。
该段其余字段是 bool/int64 调度器调优项（HIGH）。
#700–#749 — 精度跟踪器、合成计算
该段引入精度跟踪器模式 enum 和第二个 sflag-wait 字符串过滤器。
| Field# | Name | Type / wrapper |
|---|---|---|
| #723 | xla_tpu_precision_tracer_mode | enum / PrecisionTracerModeProto.Value |
| #739 | xla_tpu_synthetic_compute_in_sflag_wait_filter | string（默认 "all"） |
PrecisionTracerModeProto.Value 有六个值：NONE=0、 LOG_ORIGINAL_AND_SHADOW=1、LOG_ABS_DIFF=2、LOG_ABS_DIFF_SUMMARY=3、 CHECK_ABS_DIFF=4、CHECK_ABS_DIFF_NONFATAL=5。#723 默认为 0 (NONE)。 同一个 PrecisionTracerModeProto.Value enum 也是 AutoProto 分支 #12 （见 tpu-compilation-environment.md）， 因此相同包装既在这里作为直接 enum 字段出现，也在 AutoProto oneof 内出现—— 重新实现者必须注册一次该包装，并从两个位置引用它。
#750–#799 — MSA 系列、Dot-RHS、卸载（Tristate 密集）
这是上半部分中 Tristate 最密集的段：memory-space-assignment (msa) 启用/选项集群、dot 参数放置、scatter offloading，以及 bundle-aware cost model。Tristate 字段都携带 TristateProto.Value（AUTO=0、DISABLED=1、ENABLED=2），并且许多默认 为 ENABLED。
| Field# | Name | Type / wrapper |
|---|---|---|
| #758 | xla_tpu_move_dot_parameters_to_rhs | enum / TristateProto.Value（默认 ENABLED） |
| #766 | xla_tpu_enable_large_2nd_minor_layout_for_x8 | enum / TristateProto.Value（默认 ENABLED） |
| #777 | xla_tpu_override_scavenge_vmem_for_fusions | enum / TristateProto.Value（默认 ENABLED） |
| #787 | xla_msa_enable | enum / TristateProto.Value（默认 ENABLED） |
| #788 | xla_msa_min_overlap_to_async_copy_ratio | float（默认 1.0） |
| #789 | xla_msa_preferred_overlap_to_async_copy_ratio | float（默认 2.0） |
| #790 | xla_msa_max_overlap_to_mem_size_async_copy_ratio | float（默认 8.0） |
特例 — #788/#789/#790 的 MSA overlap-ratio 三元组命名并不 完全一致。min/preferred 使用
..._overlap_to_async_copy_ratio， 但 max 字段是xla_msa_max_overlap_to_mem_size_async_copy_ratio——多了一个to_mem_size中缀。三个名称均已逐字 grep。该三元组映射了字典 A 中的jf/vf/gf/cmemoverlap 三元组（#280/284/285、 #442/446/447、#540/544/545、#309/313/314）；msa系列是同一个五路 MSA 调优模式的上半成员。这里的比率值是发布默认值（1.0 / 2.0 / 8.0）， 也就是该系列 overlay 按 TPU 代际应用的同一组三元组；见tce-field-offsets-defaults.md。
xla_msa_enable (#787) 是主 MSA enable，默认 ENABLED(2)，通过 movb 2 gen (@0x1d705500) 实现。该段中未锚定的 Tristate 成员 （#766、#777 和若干 bool 兄弟）名称为 HIGH，TristateProto.Value 包装为 CERTAIN。
#800–#849 — SparseCore 卸载、Bundle-Aware Cost Model、Collective Optimize
SparseCore collective-offload 和 bundle-aware cost-model Tristate 集群， 以及 async-wrapper fusion-type enum。该段大量字段默认 ENABLED。
| Field# | Name | Type / wrapper |
|---|---|---|
| #802 | xla_tpu_enable_offloading_scatter_to_sparsecore | enum / TristateProto.Value（默认 ENABLED） |
| #804 | xla_tpu_use_bundle_aware_cost_model_for_fusions | enum / TristateProto.Value（默认 ENABLED） |
| #807 | xla_tpu_experimental_do_not_use_fusion_estimate_cost_changes | enum / TristateProto.Value（默认 ENABLED） |
| #816 | xla_msa_use_bundle_aware_cost_model | enum / TristateProto.Value（默认 ENABLED） |
| #822 | xla_tpu_enable_sparse_core_collective_offload_all_gather | enum / TristateProto.Value（默认 ENABLED） |
| #827 | xla_sc_async_wrapper_fusion_type | enum / ScAsyncWrapperFusionTypeProto.Value |
| #839 | xla_tpu_enable_sparse_core_collective_offload_all_reduce | enum / TristateProto.Value（默认 ENABLED） |
ScAsyncWrapperFusionTypeProto.Value（#827 的包装）有四个值： DEFAULT=0、SINGLE_SPARSE_DENSE_CALL=1、SINGLE_MINIBATCHING_STEP=2、 SINGLE_TPU_CUSTOM_CALL=3。
特例 — #827 默认为
3(SINGLE_TPU_CUSTOM_CALL)，即最后一个 枚举项，而不是0 (DEFAULT)。值名SINGLE_TPU_CUSTOM_CALL已逐字确认 且唯一。重新实现者必须将 async-wrapper fusion type 物化为 3， 否则 SparseCore async wrapper 会以错误策略融合。这与 #631 是同一种模式—— 上半部分有两个 enum 的发布默认值是非零、非首个枚举项。
_all_gather (#822) 和 _all_reduce (#839) SparseCore-offload Tristate 是同一系列的一部分，该系列还包括 #860（如下）的 _reduce_scatter 成员—— 它们是一组按 collective 逐项设置的 offload toggle。
#850–#899 — Collective Optimize、Advanced MOF、Quantized All-Reduce
SparseCore-offload Tristate 集合的尾部、constant-table collective optimization、advanced multi-output fusion，以及一个 quantized-collective 阈值。
| Field# | Name | Type / wrapper |
|---|---|---|
| #852 | xla_collective_optimize_constant_table | enum / TristateProto.Value（默认 ENABLED） |
| #860 | xla_tpu_enable_sparse_core_collective_offload_reduce_scatter | enum / TristateProto.Value（默认 ENABLED） |
| #866 | xla_jf_enable_advanced_multi_output_fusion | enum / TristateProto.Value（默认 ENABLED） |
| #890 | xla_tpu_quantized_all_reduce_size_threshold_mib | float（默认 3.0） |
注意 — #852 的 flag 名称省略了大多数邻居使用的
_tpu中缀——它是xla_collective_optimize_constant_table，已逐字确认，而不是xla_tpu_collective_optimize_constant_table。TCE flag 命名空间混合了xla_*、xla_tpu_*、xla_jf_*、xla_sc_*、xla_msa_*和megascale_*前缀，没有强制规则；重新实现者必须从 descriptor 中逐字获取 每个名称，不要规范化前缀。
这四个是 #900 以下最后一批直接锚定字段。#866 是 JellyFish (jf) advanced-multi-output-fusion toggle 的上半成员，默认 ENABLED(2)。
#900–#1218 — 尾部：混合标量、Tristates、AutoProto 消息
最上方约 220 个字段编号没有单一主导区域；它们混合了 bool/int 标量开关、 额外的 TristateProto.Value toggle，以及在后续 proto 修订中新增的 message 类型 AutoProto / typed-message 字段。本轮没有逐个 name-grep 该尾部中的字段，因此该段的逐字段名称归属为 LOW——解析表顺序将每个 字段编号钉到一个 FieldEntry，type_card 将每个字段钉到一个 proto 类型， 但具体名称在这里没有独立重新确认。该尾部的结构已锚定且为 HIGH：
| Axis | Values | Source |
|---|---|---|
| 存活条目计数 | 1121 个 FieldEntry 行（第 1121 个是最后一个存活字段） | num_field_entries=1121，升序 |
| 最高存活字段编号 | #1218 (0x4c2) | 解析表头 max_field_number |
| 尾部中的空洞字段编号 | 1218 − 1121 = 97 个 dead 编号，分布在整个范围中 | 表头算术 |
| 存在的 Proto 类型 | bool、int64、int32、float、double、string、enum、message | 消息范围直方图 |
message 字段 | 通过 aux_idx → aux 数组（table+0x3800）解析；AutoProto = empty/AUTO 默认 | aux 条目（消息范围内 349 个 message 字段） |
易错点 — 第 1121 个 FieldEntry 是最后一个存活字段，但它的字段 编号是 #1218，不是 1121。因为 #1218 以下有 97 个字段编号已死， 存活条目计数（1121）和最高字段编号（#1218）正好相差这 97 个空洞。 字典 A 拥有前 560 个字段编号（#1–#560）；本页拥有其余部分（#561–#1218）。 重新实现者读取解析表时只会看到 1121 个存活条目及其实际（稀疏）编号； dead 编号只是不存在。
注意 — 该尾部（以及整个 TCE）中的 message 类型字段绝大多数是
xla.jellyfish.AutoProtooneof 字段。AutoProto 是一个 30 分支 oneof， 其默认值为空消息（oneof-case 0 = AUTO）；分支消息类型 （例如ShardyOptions、IlpLatencyHidingSchedulerOptions、EmitterLearnedCostModelOptions、BundleInstrumentationOptions、TpuCustomCallMemorySpaceSpec——本轮已确认均出现在.rodata中） 记录在tpu-compilation-environment.md。 对字典而言，尾部message字段的行是field# | name | message/AutoProto | LOW；oneof 的解码不是逐字段的。注意 — TCE 字段编号是稀疏的，不是稠密的。解析表头 （
max_field_number=1218，num_field_entries=1121）包含 97 个 dead 编号，因此存活条目计数（1121）不是字段编号。两个字典页按字段编号 拼合（A：#1–#560；B：#561–#1218），任何映射序列化 tag 的读者都必须使用 存活 FieldEntry，绝不能假设 tag == index。
此范围引用的包装 Enum
7 个专用（非 Tristate）TCE 包装 enum 中有四个是 #561–#1218 中某个直接 enum 字段的类型 （而不是只出现在 AutoProto oneof 内）。它们的值表逐字读取自 FileDescriptorProto value-name 流（@0xbfa6060+）：
| Field# | Wrapper enum | Values | Default |
|---|---|---|---|
| #583 | ChecksumAlgoProto.Value | DEFAULT=0, XOR=1, SIP_HASH_1_3=2 | 0 DEFAULT |
| #631 | RegSelectPolicyProto.Value | NONE=0, LEGACY=1, BALANCE_PREV_NEXT_USES_IGNORE_FREE=2, BALANCE_PREV_NEXT_FREE_SPILL=3, DOUBLE=4, WORST=5, DISREGARD_RECENTLY_USED=6 | 6 |
| #723 | PrecisionTracerModeProto.Value | NONE=0, LOG_ORIGINAL_AND_SHADOW=1, LOG_ABS_DIFF=2, LOG_ABS_DIFF_SUMMARY=3, CHECK_ABS_DIFF=4, CHECK_ABS_DIFF_NONFATAL=5 | 0 NONE |
| #827 | ScAsyncWrapperFusionTypeProto.Value | DEFAULT=0, SINGLE_SPARSE_DENSE_CALL=1, SINGLE_MINIBATCHING_STEP=2, SINGLE_TPU_CUSTOM_CALL=3 | 3 |
该范围内的所有其他 enum 字段都携带 TristateProto.Value （AUTO=0、DISABLED=1、ENABLED=2）。包装到 flag 的桥接是 TpuCompEnvReflection::NormalizeFieldType<T> 模板族（每种包装类型一个实例）， 它把 flag 的 typed value 复制到 proto 字段中；完整包装列表和桥接在 tpu-compilation-environment.md 中。
交叉引用
- TCE 字段字典 (A) — 字段 #1–#560，同一 field#→name→type 目录的下半部分；两页在 #561 边界拼合
- TpuCompilationEnvironment — 消息结构：解析表、FieldEntry/aux 布局、has-bits、包装 enum（67 个
TristateProto.Value字段加 7 个专用包装），以及 30 分支 AutoProto oneof，其分支是本字典中的message类型字段 - TCE Field-Offsets & Flag Defaults — 每个字段的结构体偏移列和逐字节精确的字面默认值，包括本页只点名引用的按区域默认值
- Flag Families —
xla_*/xla_tpu_*/xla_jf_*/xla_sc_*/xla_msa_*/megascale_*前缀系列，以及 flag 名称如何映射到其注册的absl::Flag - XLA Flag Atlas — 通过 TPU PJRT 插件暴露的更广泛 XLA debug/compile flags 目录
- Config Overview — 配置子系统入口（Part XVI）