TCE Field Dictionary (A)

All field numbers, names, types, offsets, and addresses on this page apply to libtpu.so from the libtpu-0.0.40-cp314 wheel (build-id 89edbbe81c5b328a958fe628a9f2207d, libtpu_lts_20260413_b_RC00). Other versions renumber and re-offset fields.

Abstract

TpuCompilationEnvironment (TCE) is the TPU-private master compile-config protobuf: a single editions-proto message carrying 1121 live fields, every one of which is also a registered absl::Flag (a perfect 1:1 mapping, the structural inverse of the GPU/CPU-shared xla.DebugOptions). This page is the field-number → name → proto type dictionary for the lower half of that proto: field numbers 1 through 560. The matching upper half — field 561 through 1218 (max field number 1218, with 97 deletion gaps) — lives on TCE Field Dictionary (B). The split point is exact and stated below.

The dictionary is reconstructed from the TpuCompilationEnvironment FileDescriptorProto carved out of the binary at protodesc_cold VA 0xbfa6060 (size 137,692 B) and cross-checked against the generated fast-parse table TpuCompilationEnvironment::_table_ @ 0x21cfa9e0, whose 1121-entry FieldEntry array is sorted by ascending field number. Each line of this page gives the field number, the verbatim field name (every name on this page was confirmed byte-present in the binary's .rodata string pool), the proto base type, and — for the 423 wrapped fields — the wrapper message/enum type. The C++ struct offset and the per-field literal default value are deliberately not repeated here; they are the subject of TCE Field-Offsets & Flag Defaults, and the structural overview (parse-table header, type histogram, HOT-tag taxonomy, AutoProto switch) is on TpuCompilationEnvironment.

For a reimplementer, the contract this page satisfies is narrow and precise:

• Field number → name. The canonical numbering a serialized TCE proto uses on the wire and that GetTpuCompEnvWithDefaultValues walks when it resolves each field to its absl::Flag.
• Name → proto base type. bool / int32 / int64 / uint32 / uint64 / float / double / string / enum / message — the wire type that decides how the value is parsed and stored.
• Wrapper type, where present. Which enum (TristateProto.Value, MemorySchedulerProto.Value, …) or which message (AutoProto, RangeSpecProto, the typed helpers) a non-scalar field carries.

How to Read These Tables

Each row is one live field, in ascending field-number order. Columns are uniform across every group:

• # — the proto field number (the wire tag). Numbers are not contiguous: TCE has 97 deletion gaps in 1..1218 (no reserved_range; deleted fields simply vanish from the descriptor). Gaps inside this page's range are listed in §Field-Number Gaps.
• Field name — the verbatim proto field name, identical to the registered absl::Flag name. Most carry the xla_tpu_ / xla_jf_ / xla_ prefixes; a handful are bare (config_criterion, loop_invert, rematerialization_algorithm).
• Type — the proto base type. For enum and message, the Wrapper / message type column names the concrete type.

NOTE — the 423 non-scalar fields split into 74 enum-typed (67 of them TristateProto.Value = AUTO/DISABLED/ENABLED, plus 7 direct helper enums) and 349 message-typed (330 are the 30-arm AutoProto switch wrapper; the remaining 19 are typed helper messages such as RangeSpecProto, RepeatedStrings, and the msa.* option messages). The wrapper enum value-by-value tables and the AutoProto arm list live on TpuCompilationEnvironment; this page only names the wrapper per field.

GOTCHA — a field's position on this page is its field number, not its struct offset. The two are unrelated: the parse table sorts FieldEntry by field number, but the C++ _impl_ layout interleaves them by type/alignment (field #2 sits at struct offset +0xBC, field #1 at +0xB8, field #3 at +0xA8). Do not infer offset from field number; use TCE Field-Offsets & Flag Defaults.

#1 – #30 — Collectives, Cross-Program Prefetch, CMEM, Embedding

The lowest field numbers are the oldest jellyfish-era knobs: all-gather emitters, the net-router ring limits, the (now mostly deprecated) cross-program-prefetch / scoped-CMEM cluster, and the first embedding tunable. Field #21 is a gap.

NOTE — field #30 is one of only four fields in the whole proto with is_used_at_runtime=true; the others (#354, #432, and xla_tpu_num_embedding_devices) live further on. The bit lives in the TpuCompEnvFieldOptions extension (#535801365), not in the parse table. Fields #4, #14, #15, #16, #17, #18, #19, #20, #22, #23 are among the 101 deprecated=true fields, superseded by the per-family xla_{jf,vf,gf,cmem}_vmem_* knobs.

#31 – #95 — Scheduler, Tracing, BRKGA, LLO/LSRA, SDC Checker

This block opens with the memory-scheduler selector (#31), then a run of trace/profile toggles, the BRKGA HLO-scheduling parameters, the early LLO/LSRA register-allocation knobs, the combiner thresholds, and the first big SDC-checker cluster. Field #21, #44, #45, #54, #59, #70 are gaps in this range.

#96 – #159 — VLIW Scheduling, Convolution Precision, Bounds-Check, IOR/LLVM Backend

A scheduling-and-codegen block: the VLIW scheduler and its fuel, conv-precision numerics, the bounds-check RangeSpec family, the LLVM-backend toggles, and the first loop_invert pair. Gaps: #121, #124–#127, #156.

QUIRK — field #132 xla_tpu_verify_or_assign_tiling_before_lowering is a VerifyOrAssignTilingFlagsProto.Value enum (NONE=0 / VERIFY=1 / ASSIGN=2), not a bool. A reimplementer who treats every xla_tpu_*verify* knob as a boolean toggle will mis-parse this one — it gates the tile-mode selector consumed at struct offset +0xDFC.

#160 – #219 — Loop-Invert, ISA Emitter, IOR/MSA, LLVM, Instrumentation

The loop_invert / ISA-emitter RangeSpec cluster, the IOR fast-mem and stored-solution MSA knobs, the LLVM-backend group, the HLO-dedup pair, and the bf16-coalescing / rematerialization-algorithm knobs. The two bare-named strings config_criterion (#209) and rematerialization_algorithm (#212) appear here. Gaps: #214, #218.

#220 – #294 — AutoFDO Start, Conv Fusion, Pipelining, Overlay Compression, JF VMEM Family

The first AutoFDO toggle, the conv-fusion / conv-precision numerics block, the JF pipelining knobs, the overlay-compression and single-phase-ring transfer parameters, and the start of the per-family JF VMEM MSA cluster (#275–#286). Gaps: #244–#247, #250–#254, #268, #292, #294.

NOTE — the xla_jf_vmem_* block (#275–#286) is the jellyfish arm of the per-family MSA overlap-ratio family. It is mirrored field-for-field by the xla_vf_vmem_* (#436–#447), xla_tpu_cmem_* (#309–#315), and xla_gf_vmem_* (#533–#547) arms later on this page. The three float ratios in each arm (max / min / preferred overlap-to-async-copy) are the MSA cost-model tuning surface; the per-version overlay picks one arm.

#295 – #354 — SparseCore Tracing, All-Reduce VMEM, CMEM MSA Family, Detect-NaN, Megacore Fusion

The first AutoProto-typed field (#295), the all-reduce VMEM contingency knobs, the xla_tpu_cmem_* MSA arm, the copy-fusion cluster, the NaN/Inf/special-FP detection toggles, and the megacore-fusion enable Tristate (#344). Gaps: #303, #335.

GOTCHA — xla_tpu_detect_inf (#327) and xla_tpu_detect_nan (#329) are TCE proto fields distinct from the same-named xla.DebugOptions fields (#136/#135). The TCE fields are flag-wired and materialized from the absl default; the DebugOptions ones are born proto3-zero (FALSE) unless the flag override layer sets them. Do not conflate the two protos when reimplementing the detect-NaN path.

#355 – #432 — Untiled Layout, Experimental Padding, Megacore-Fusion Tuning, Poison-Padding, SPMD Windowed Einsum

The untiled-VMEM-DMA toggle, the experimental quantization/padding knobs, the megacore-fusion margin/scaling floats, the MSA while-execution count, the nested-dot-fusion cluster, the poison-padding pair, the RWB-fusion bool, and the SPMD windowed-einsum decomposition block. Gaps: #356–#359, #362, #379, #401, #419, #422.

NOTE — xla_tpu_rwb_fusion (#413) is one of two fields (with xla_tpu_accumulate_into_mrb, #597 on page B) whose absl default is TRUE despite an earlier help-string reading of false. The registered flag default is byte-authoritative; the help text describes behavior, not the default. See TCE Field-Offsets & Flag Defaults.

#433 – #497 — Aggressive Scheduling, VF VMEM Family, Async Collective Fusion, AutoFDO/Autotune

The aggressive-scheduling Tristate, the full xla_vf_vmem_* MSA arm (#436–#447), the send/recv aggregation cluster, the async-collective-fusion block (the first SparseDenseMatmulFdoConfig message at #462), the AutoFDO module flags, and the autotune-by-pass toggles. Gaps: #434, #448, #468, #470, #481, #484, #491.

#498 – #560 — Prefetch FIFO, ICI-SDC Test, Data-Parallel DCN, GF VMEM Family, AG Pipelining

The closing block of this page: prefetch-interval-picker overrides, the numerics accurate_log2, the ICI-SDC self-test cluster (#516–#521, #560), the data-parallel DCN pipelining knobs, the full xla_gf_vmem_* MSA arm (#533–#547), the overlay-profiler toggles, and the AG-backward-pipelining group. Gaps: #506, #509, #511, #515, #527, #530, #531, #546.

NOTE — field #560 xla_tpu_ici_sdc_test_run_on_program_start is the last field on this page. The next field, #561 xla_tpu_debug_sflag_wait_timeout_ms (uint32), opens TCE Field Dictionary (B). The boundary is exact: this page owns 1 ≤ field# ≤ 560, page B owns 561 ≤ field# ≤ 1218.

Field-Number Gaps in #1–#560

The numbering is not contiguous: TCE carries no reserved_range or reserved_name, so a deleted field simply leaves a hole. The gaps inside this page's range — every field number in 1..560 that is not a live field above — are:

21, 44, 45, 54, 59, 70, 121, 124, 125, 126, 127, 156, 214, 218,
244, 245, 246, 247, 250, 251, 252, 253, 254, 268, 292, 294, 303,
335, 356, 357, 358, 359, 362, 379, 401, 419, 422, 434, 448, 468,
470, 481, 484, 491, 506, 509, 511, 515, 527, 530, 531, 546

GOTCHA — these holes are deletions, not declared-reserved ranges. A reimplementer carving the descriptor must not assume the field set is 1..N contiguous; iterate the actual FieldEntry array (sorted ascending) and skip the missing numbers. The full 97-gap list across 1..1218 lives on TpuCompilationEnvironment; the slice above is the portion below #561.

Type Distribution Within #1–#560

For orientation, the proto base-type mix of the 508 live fields on this page (the lower half is bool-heavy, consistent with the early jellyfish toggle era):

The whole-proto histogram (418 bool / 148 int64 / 349 message / 74 enum / 37 string / 34 float / 32 int32 / 14 double / 11 uint32 / 4 uint64) and the parse-table-derived type_card proof are on TpuCompilationEnvironment.

Confidence

Every field number, name, and type on this page is CERTAIN: the names derive from the TpuCompilationEnvironment FileDescriptorProto carved from the binary and were cross-checked against the 1121-entry FieldEntry array of TpuCompilationEnvironment::_table_ @ 0x21cfa9e0, whose entry order is field-number-sorted. Twenty-two of the names spanning the full #1–#560 range were additionally confirmed byte-present, verbatim, in the binary's .rodata string pool (0 misses), including the wrapper type strings TristateProto, VerifyOrAssignTilingFlags, AutoProto, and RangeSpecProto. The HOT-subsystem tags shown in italics for a few fields (NUMERICS, PIPELINER, SPARSE_CORE) and the four is_used_at_runtime markers come from the TpuCompEnvFieldOptions field-option extension (#535801365) and are HIGH confidence — recovered from the descriptor, not the parse table; not every tagged field is annotated here (the complete HOT breakdown is on TpuCompilationEnvironment). No field on this page is LOW confidence.

Cross-References

• TCE Field Dictionary (B) — the upper half: field #561 – #1218, same field#→name→type grammar
• TpuCompilationEnvironment — the structural overview: parse-table header, type histogram, HOT-tag taxonomy, wrapper-enum value tables, the 30-arm AutoProto switch
• TCE Field-Offsets & Flag Defaults — the C++ struct offset and literal default value of each field; the kGenFunc-vs-inline FlagImpl mechanism
• Configuration & Compile Knobs — overview — how the TCE proto sits in the PJRT compile path alongside DebugOptions and the flag registry
• Part XVI — Configuration & Compile Knobs — index entry