Internal Wiki

主题

libtpu 内部机制 — 逆向工程参考 ​

状态：18 个部分共 424 页 · 完整内容索引 · 主二进制：libtpu-0.0.40-cp314-cp314-manylinux_2_31_x86_64/libtpu/libtpu.so — 781,691,048 B，x86-64 ELF64 DYN，未剥离符号，build-id 89edbbe81c5b328a958fe628a9f2207d · 辅助文件：sdk.so（94,732 个函数）

本参考是什么 ​

这是一份达到可重新实现级别的 Google libtpu.so 逆向工程参考 — 该 PJRT 插件将 Cloud TPU 硬件暴露给 JAX、PyTorch/XLA 和 TensorFlow。它在功能上等价于 NVIDIA 的 libcuda.so + libnvrtc.so + nvcc/ptxas 中面向具体设备的那一半，并被压缩进一个 745 MB 的单体共享对象：其中静态链接了整个 XLA 编译器、所有 TPU MLIR 方言、各代 LLVM 后端、oneDNN、tcmalloc、Abseil、gRPC、protobuf、Eigen、TPU 运行时、设备驱动 shim，以及 ICI/DCN fabric 栈。

这里的一切都纯粹由二进制静态分析重建而来 — objdump、nm、readelf -rW、原始字节读取，以及对切出的描述符执行 protoc --decode_raw。该二进制发布时未剥离符号 — 反汇编器恢复了 884,832 个函数，其中 881,784 个（99.66 %）带有真实符号名 — 因此在大部分接口面上，重建达到了字节精确 / 可重新实现级别。

为什么它很难 ​

  • 分析数据库中有 884,832 个函数（按函数生成的制品目录略高，为 884,843 个文件，包含 thunk/alias/data-stub 条目；函数计数引用 884,832，见二进制取证概览）；1,249,324 个字符串；约 52 GB 提取出的 IDA sidecar。
  • 40,313 张分发表（约为 ptxas 的 409 张的 100 倍），分类为 19 个分类学类别。
  • 160,351 条 RTTI 记录（_ZTI 60,457 · _ZTV 39,244 · _ZTS 60,650 · 2），60,457 个 typeinfo 中以 mlir::（13,091）、asic_sw::（11,379）、tensorflow::（3,108）、xla::（3,036）、llvm::（2,940）为首，后面还有 dnnl:: / std:: / grpc_core:: 以及很长的 vendored 尾部。
  • .init_array 中有 约 2,900 个静态构造器；1,069,659 条重定位（其中 1,069,006 条是 R_X86_64_RELATIVE）。
  • 节头表恰好在 EOF 结束 — 其后没有尾随载荷。出现在 .text 内的一个 zstd magic 立即数是内联常量，不是存储的压缩帧；见尾随 zstd Blob。
  • 自定义 ELF 节（google_malloc、malloc_hook、protodesc_cold、filewrapper_toc、__rseq_cs、__lcxx_override）。
  • 六代 TPU 硅片使用 Google 内部代号阶梯：jellyfish → dragonfish → pufferfish → viperfish → ghostlite → 6acc60406，每一代都有自己的 ISA 编码、成本模型和 HAL 家族。

双层 C ABI ​

text
                JAX / PyTorch-XLA / TensorFlow
                          │
                          ▼  PJRT C-API (v0.103)
              ┌──────────────────────────────┐
              │   PJRT layer (outer C-API)   │   ← 外层 ABI  (Part II)
              │   GetPjrtApi @ 0xe6a83a0     │
              │   140-slot PJRT_Api struct   │
              │   17 extensions chained      │
              └──────────────┬───────────────┘
                             │  Tpu* C shim (~200 symbols)
              ┌──────────────────────────────┐
              │   libtpu runtime + compiler  │   ← 内层 ABI  (Part III)
              │   xla::jellyfish::*          │
              │   asic_sw::deepsea::*        │
              │   platforms_deepsea::*       │
              └──────────────────────────────┘

本参考如何组织 ​

18 个部分遵循数据自身的依赖链，而不是按字母顺序或重要性排序。阅读每一部分时，只需假设已读过它之前的部分：

text
  硅片模型 ─► 编译器 pass ─► ISA 编码 ─► 成本模型 ─► 调度
       (IV)             (V)              (VI)            (VII)         (VIII)
                                                                         │
   专用引擎 (SparseCore, IX) ◄───────────────────────────────┘
       │
   片上内存与 DMA (X) ─► 运行时 (XI) ─► 分布式 fabric (XII–XIV)
                                                  │
                              可观测性 (XV) ─┴─► 配置 (XVI)

编译器后端被有意按规范的三类关注点拆分 — 有哪些指令（VI）、它们的成本是多少（VII）、如何排序和打包它们（VIII） — 因为在这个二进制中，成本模型数据的体量约为调度算法的 3 倍，把它们混在一起会产生一个 50 页的巨物。SparseCore（IX）保持完整，而不是沿这条边界切开：它是一个自包含引擎，读者会希望在一个地方读完。

状态与证据等级 ​

下面每个页面都带有一个等级，反映其论断直接锚定到二进制的程度：

  • C — 已确认 / 可重新实现级：以 objdump/nm/readelf 或对切出描述符执行 protoc --decode_raw 的结果为字节锚点。字节级深挖页面默认使用此等级。
  • I — 推断 / 综合：基础性、取证调查、逐代参数化或连接性的概览页面。
  • O — 开放：尚未恢复；在开放前沿登记表中跟踪。

上面的证据等级（C/I/O）是重要的逐页标签。O（开放）页面标记一个具体的尚未恢复细节，并在开放前沿登记表中跟踪。

各部分速览 ​

开放列统计仍带有 O（尚未恢复细节）等级的页面。

部分标题页数开放依赖来源领域
0参考装置90——
I二进制剖析1200forensics / dispatch / RTTI
II插件生命周期与 PJRT API230Iruntime / PJRT
IIITpu C-Shim 层100IIshim
IV硅片与硬件代号模型240—silicon
V编译器 — 降低与优化 Pass360IVcompiler
VITensorCore ISA 与 LLO 编码422IV, VISA
VII成本与延迟模型410IV, VIcost
VIII指令调度与 Bundle 打包140VI, VIIcost / scheduling
IXSparseCore 与 BarnaCore450IV, VI, VIIsparsecore
X片上内存与 DMA200IVmemory / DMA
XI运行时与执行110II, VI, Xruntime
XII互连与路由300IVcollectives / routing
XIIIPod 内集合通信与屏障300IX, XIIcollectives
XIVMegascale（多主机 / DCN）210XII, XIIIcollectives / DCN
XV性能分析与遥测220XI, XIIprofiler
XVI配置与编译旋钮161V, VIIconfig
XVII附录180allcross-cutting
总计4243

逐代导航交叉索引 ​

本书大量按代组织。要端到端追踪某一代硅片，请沿其所在行阅读：

TpuVersion代号Cloud / 市场名家族页ISA bundleMXU 延迟性能网格
0JellyfishTPU v2targets/jxc-family.mdisa/bundle-jf-41b.mdcost/mxu-latency-jf-df.mdcost/performance-jf-df.md
1DragonfishTPU v3targets/jxc-family.mdisa/bundle-df.mdcost/mxu-latency-jf-df.mdcost/performance-jf-df.md
2PufferfishTPU v4targets/pxc-family.mdisa/bundle-pf-51b.mdcost/mxu-latency-pf.mdcost/performance-pf.md
3ViperfishTPU v5 / v5etargets/vxc-family.mdisa/bundle-vf-64b.mdcost/mxu-latency-vf.mdcost/performance-vf.md
4GhostliteTPU v6e (Trillium)targets/gxc-family.mdisa/bundle-gl.mdcost/mxu-latency-gl.mdcost/performance-gl-ghperf.md
56acc60406TPU7xtargets/gxc-family.mdisa/bundle-gf.mdcost/mxu-latency-gf.mdcost/performance-gf-ghperf.md

单页合并常量表是逐代主比较矩阵。

阅读路径 ​

  • 重新实现成本模型 / 调度器 — IV（硅片常量）→ VI（ISA）→ VII（成本数据）→ VIII（调度）。
  • 理解 TPU 到 TPU 的集合通信 — IV → XII（fabric + 路由）→ XIII（集合算法）→ XIV（多主机）。
  • 解析已编译程序 / bundle 字节 — VI（ISA 编码）→ X（内存与 DMA）→ XI（运行时加载/执行）。
  • 编写或调试 PJRT 使用方 — II（PJRT API）→ III（Tpu C-shim）→ XI（执行）→ XV（性能分析）。
  • 端到端追踪一代 TPU — 使用上面的逐代交叉索引：家族（IV）→ bundle（VI）→ MXU 延迟 + 性能网格（VII）。
  • 调试挂起 / 死锁 — XIII（屏障 + SFLAG）→ X（continuation-queue）→ XII（VC-balance + 路由）。
  • 只是建立方向感 — 0（参考装置，尤其是 Compile-Flow Walkthrough）→ I（二进制剖析）→ IV（代号模型）。

约定 ​

  • 函数地址是虚拟地址（@0x…）；对于 .text/.rodata/.lrodata，VA == file offset。
  • 每页都带有一个 References 块：列出其引用的源二进制和函数/符号虚拟地址。

NOTE — VA == file-offset 规则只适用于 .text/.rodata/.lrodata。对于 .data，文件偏移是 VA − 0x400000；对于 .data.rel.ro，文件偏移是 VA − 0x200000；如果对位于这些节中的结构体按原始 VA 用 xxd/objdump seek，会读到错误字节。完整节映射见 ELF 剖析。

源语料 ​

本书每一页都来自对 libtpu.so 的静态分析 — 它的符号表、反汇编和反编译。分析所针对的完整输入集，精确到字节，收录在源码语料映射中；生成和使用这些输入的方法描述在方法论中。

完整内容索引 ​

以下目录来自 SUMMARY.md，覆盖当前 docs/projects/libtpu 下的 424 个页面（含本页；不含 SUMMARY.md 本身）。

libtpu 内部机制

第 0 部分 — 参考设备 ​

第一部分 — 二进制解剖 ​

第二部分 — 插件生命周期和 PJRT API ​

第三部分 — Tpu C-Shim 层 ​

第四部分 — 芯片和硬件代号模型 ​

第五部分 - 编译器：降低和优化遍数 ​

第六部分 — TensorCore ISA 和 LLO 编码 ​

第七部分 — 成本和延迟模型 ​

第八部分 — 指令调度和捆绑打包 ​

第九部分 — SparseCore 和 BarnaCore ​

第 X 部分 — 片上存储器和 DMA ​

第 XI 部分 — 运行时和执行 ​

第 XII 部分 — 互连和路由 ​

第 XIII 部分 — Pod 集体和障碍 ​

第 XIV 部分 — 超大规模(多主机/DCN) ​

第 XV 部分 — 分析和遥测 ​

第 XVI 部分 — 配置和编译旋钮 ​

第十七部分 — 附录 ​

详细内容索引 ​

Part 0 — 参考装置 (9) ​

导向与连接材料。先读 Compile-Flow Walkthrough — 它追踪一个 matmul 穿过每个部分，是进入整本书的入口。

  • 落地页 / 本参考 · index.md · I libtpu 是什么、二进制来源、组织方式、逐代交叉索引、阅读路径。
  • 如何阅读本书 · front/how-to-read.md · I 证据等级、依赖流的理由、阅读路径画像。
  • 编译流程走查 · front/compile-flow-walkthrough.md · I 追踪一个 dot op：HLO → MHLO → tpu → LLO → bundle 字节 → 执行，并交叉引用每个部分。 src: P-2-03, P-2-01
  • 方法论 · methodology.md · I 提取流水线、IDA sidecar、FLIRT、protoc --decode_raw、命名约定。 src: W001
  • 子系统地图 · subsystem-map.md · I 13 个领域的依赖网络，以及 18 个部分如何覆盖它。 src: W001, G001–G003
  • 代号速查表 · front/codename-cheatsheet.md · C 一张卡片上的 TpuVersion 0–5 ↔ 代号 ↔ chip-DID ↔ Cloud 名称。
  • 术语表 · glossary.md · I LLO、MXU、XLU、EUP、SCS/TAC/TEC、MRB、SFLAG、ICI/DCN 等。
  • 证据与置信度约定 · front/evidence-conventions.md · I C/I/O 等级，以及全书使用的锚点格式。 src: W001
  • 参考文献 · bibliography.md · I 外部参考；明确说明二进制中不包含的内容（Trillium/Ironwood 只是外部名称）。

Part I — 二进制剖析 (12) ​

745 MB ELF 如何布局与导航。这里只做分析与导向；大型枚举目录放在 Part XVII。

  • 概览 · forensics/overview.md · I 两个二进制、节模型、为什么它这么大。 src: W023, W027
  • ELF 剖析 · forensics/elf-anatomy.md · C 52 个节、段、VA==offset 规则、.lrodata/.rodata/.text 范围。 src: W023, W030
  • libtpu.so + sdk.so · forensics/two-binary-split.md · C 884,832 函数的主对象和 94,732 函数的 sdk；符号群体形态。 src: W001, W026
  • 自定义节 · forensics/custom-sections.md · C google_malloc、protodesc_cold、filewrapper_toc、__rseq_cs、__lcxx_override。 src: P-2-07, W030
  • 嵌入库图谱 · forensics/embedded-library-atlas.md · C Vendored Abseil/protobuf/Eigen/oneDNN/tcmalloc/LLVM 的字节核算（FLIRT）。
  • LLVM/MLIR 版本清单 · forensics/llvm-mlir-manifest.md · C 嵌入式工具链版本 + 组件列表。
  • 静态初始化流水线 · forensics/static-init.md · I 约 2,900 个 ctor、初始化顺序、插件发现钩子。
  • 尾随 zstd Blob · forensics/trailing-zstd-blob.md · C 为什么不存在尾随载荷：“4.1 MB dictionary blob” 误报修正（ZSTD-01）。 src: P-2-30
  • 分发表分类学 · forensics/dispatch-table-taxonomy.md · C 40,313 张表 → 19 类（MLIR Op-Model、UFB pools、libpfm4、dnnl/Xbyak…）。 src: P-2-06
  • RTTI ↔ Vtable 交叉验证 · forensics/rtti-vtable-census.md · C 每个 typeinfo 映射到其 vtable；命名空间统计。
  • 逐代函数分发器 · forensics/per-gen-function-dispatcher.md · Cutil_registration::FunctionRegistry 分发引擎。
  • 多态分发入口点 · forensics/polymorphic-entry-points.md · C 间接调用点 + thunk 表和顶层 vtable 类。

Part II — 插件生命周期与 PJRT API (23) ​

外层 ABI：插件如何加载，以及 JAX/PyTorch 使用的 140 槽 PJRT_Api 结构体。

生命周期 ​

PJRT_Api 接口面 ​

Part III — Tpu C-Shim 层 (10) ​

PJRT 与运行时/编译器之间的内层 C ABI：封装 C++ 内部机制的 Tpu* C 函数。

Part IV — 硅片与硬件代号模型 (24) ​

整个编译器被其参数化的硬件。请在 V–VIII 之前阅读：成本模型、ISA 和 MSA 默认值都以这里定义的逐代号常量为键。规范来源：逐代硬件常量（由 VI、VII、IX 引用）。

代号身份 ​

  • 概览 · targets/overview.md · I 六代、三个 HAL 家族、双 enum 陷阱。 src: P-2-08
  • 6 代号权威校准 · targets/tpu-version-codename-matrix.md · C 6 轴（enum / CHECK / chip_parts / PCI / namespace / marketing）交叉检查；确定 glc=v4、gfc=v5。
  • 双 Enum（Proto vs Internal） · targets/dual-enum-proto-vs-internal.md · CTpuVersionProto = internal + 1；“chip_parts v6” 的解析。 src: P-2-08
  • PCI Device IDs · targets/pci-device-ids.md · C Chip DIDs 0x00d1/0x00f2、header DIDs、rev-masks、IsGlc/IsGfc → device-type。
  • 市场 / Cloud 命名 · targets/marketing-cloud-naming.md · C v2…v6e/tpu7x；Trillium=v6e；Trillium/Ironwood 不在二进制中。
  • 已淘汰标签修正列表 · targets/codename-superseded-labels.md · C “v5p”/“Trillium” 误标，以及 Ghostfish gloss。

HAL 家族 ​

逐代号硬件常量 ​

内存模型入门（详细 allocator 在 Part X） ​

  • 内存层级 · targets/memory-hierarchy.md · I HBM/VMEM/SMEM/CMEM/SFLAG 层级模型 + 17 个 MemorySpace 值。 src: P-2-01
  • Address-Space ID 表（AS0–AS9） · targets/address-space-ids.md · C 包含 SparseCore fat-pointer AS7/8/9。

Part V — 编译器：降低与优化 Pass (36) ​

IR 下降和优化 pass。按硅片参数化（使用 IV），但 ISA-light：它按名称降低到 LLO op，而不是 bits。输出为 LLO IR；编码在 VI，成本/调度在 VII/VIII。

前端与流水线 ​

  • 概览 · compiler/overview.md · IDeepseaCompilerBase::RunHloPasses、编译阶段 0–3。 src: P-2-03
  • HLO 摄取 · compiler/hlo-ingestion.md · C StableHLO → HLO、入口 module。 src: P-002
  • 编译阶段 0–3 · compiler/compile-phases.md · C Phase0Stablehlo … Phase3Linking。 src: P-2-03
  • 编译缓存 · compiler/compilation-cache.md · C key、fingerprint、命中路径。 src: P-022
  • HLO Pass 注册表 · compiler/hlo-pass-registry.md · C 三个流水线容器 + xla_* flag-atlas 绑定。
  • HLO 前置 Pass · compiler/hlo-pre-passes.md · C TPU lowering 之前运行的 pass。
  • Sharding 传播 · compiler/sharding-propagation.md · C GSPMD sharding 推断。
  • Auto-Sharding / SPMD · compiler/auto-sharding-spmd.md · C 分区 pass。
  • 代数简化器 · compiler/algebraic-simplifier.md · I TPU 专用代数重写。
  • 动态形状支持 · compiler/dynamic-shape-support.md · C bounded-dynamic 模型、dimension-size op。
  • 优化屏障 · compiler/optimization-barrier.md · C 插入、遵守、擦除。
  • Custom-Call Lowering 与注册表 · compiler/custom-call-lowering.md · C target 目录 + 注册侧。

MLIR lowering 链 ​

内存与布局优化 ​

  • MSA 概览 · compiler/msa-overview.md · C memory-space-assignment ILP pass。
  • MSA AllocateSegment · compiler/msa-allocate-segment.md · C 分配主体 + config proto。
  • MSA 逐版本默认值 · compiler/msa-per-version-defaults.md · C 每代 overlap ratio / outstanding-copy cap。
  • MSA Reservation 与 HBM Policy · compiler/msa-reservation-hbm-policy.md · C MsaReservationPolicy / HbmPolicy 字段字典。
  • Layout Assignment · compiler/layout-assignment.md · C FindMemoryMinimizingLayout 权重 + AddBackendConstraints。

Fusion、dot/conv、tiling ​

Part VI — TensorCore ISA 与 LLO 编码 (42) ​

目标表示：LLO IR 和逐代 VLIW bundle 位布局。自包含 — 可独立于成本模型阅读。Bundle packing（LLO→bytes）在 VIII。

基础 ​

  • 概览 · isa/overview.md · I LLO IR：462 个 opcode、17 个 memory space、proto-descriptor 来源。 src: P-2-01, P-2-25
  • LloOpcode Enum（462） · isa/llo-opcode-enum.md · C 类别：scalar / vector / EUP / reduction / MXU / transpose / DMA / sync / BarnaCore。 src: P-2-25
  • MemorySpace Enum（17） · isa/memory-space-enum.md · C HBM/VMEM/SMEM/SFLAG/IMEM/CMEM/SC/HOST/PINNED。 src: P-2-01
  • Bundle 模型 · isa/bundle-model-overview.md · I 逐代大小（41/51/64 B）、slot 数、bundles-per-DMA-chunk。 src: P-2-04, P-2-34
  • InstBits 主 DB · isa/instbits-master-db.md · C LLVM-MC 逐 opcode base bits；default-all-zero / no-RELA 发现。
  • TPUInstrNameData / Descs / RegEncoding · isa/instr-name-data.md · C opcode→mnemonic、MCInstrDesc、reg-encoding 表。
  • LloOpcode ↔ Proto · isa/llo-opcode-to-proto.md · C 462 条目映射 + 反向 ProtoToLloOpcode。
  • MC-Emitter（getBinaryCodeForInstr） · isa/mc-emitter.md · C insertBits operand 路径 + HwMode 选择。
  • 239-Bit Record 格式 · isa/record-format.md · C APInt record + 逐 operand insertBits(value, pos, width)。

逐代 VLIW bundle ​

逐 slot 编码 ​

编码 / 解码支持 ​

Part VII — 成本与延迟模型 (41) ​

每条指令的成本。二进制中最大的数据接口面（51 个源文件）。由 VIII 中的调度器使用；依赖 ISA（VI）和硅片常量（IV）。

核心模型 ​

MXU 延迟（逐代 reservation 矩阵） ​

性能网格（逐代 Instruction × Resource） ​

CycleTable ​

  • CycleTable 家族 · cost/cycletable-family.md · C LatencyTable::Create(TpuVersion) factory 分发。
  • JfCycleTable · cost/jf-cycletable.md · C offsetLUT 转录 + 7 列 Resource 命名。
  • VfCycleTable · cost/vf-cycletable.md · C 32 条目 CT→(instr, res) dump + throughput 桥接。

EUP / 超越函数延迟 ​

XLU 成本 ​

Conv / window 成本 ​

其他成本 ​

  • Learned Cost-Model Client · cost/learned-cost-model-client.md · C EmitterLearnedCostModelOptions + 接线状态。
  • Cost-Model Logging · cost/cost-model-logging.md · C impure AutoOr 使用方 + float grammar。
  • 合并逐代计数 · cost/iars-per-tensorcore.md · C IarsPerTensorCore / mxu / xlu 计数集中一表。

Part VIII — 指令调度与 Bundle 打包 (14) ​

使用成本模型（VII）并发出有序、已打包 bundle（VI）的算法。按设计小于 VII — 在此语料中，调度算法只是成本数据的一小部分。

Part IX — SparseCore 与 BarnaCore (45) ​

embedding/sparse 引擎（SparseCore，v5+）及其退役前身（BarnaCore，v2–v4）。保持完整，而不是沿 ISA/成本/调度轴切开。collective-offload 故事在 Part XIII。

SparseCore 引擎 ​

  • 概览 · sparsecore/overview.md · I SCS/TAC/TEC、2-sequencer（SCS+TEC）模型。 src: P-2-02
  • 架构 · sparsecore/architecture.md · C 引擎角色 + embedding 数据路径。
  • SCS（Scalar）引擎 · sparsecore/scs-engine.md · C scalar sequencer 引擎。
  • TAC 引擎 · sparsecore/tac-engine.md · C 仅 codec 的角色。
  • TEC（Vector）引擎 · sparsecore/tec-engine.md · C vector 执行引擎。
  • 逐引擎 Bundle Slot-Base 映射 · sparsecore/bundle-slot-base-map.md · C SCS/TAC/TEC 字节偏移。
  • Region → Sequencer Outliner · sparsecore/region-to-sequencer-outliner.md · C 将 SC computation 分区为逐引擎 bundle。
  • getSequencerType · sparsecore/getsequencertype.md · C 引擎选择（SCS/TAC/TEC）。

SparseCore ISA ​

SparseCore 数据路径（embeddings） ​

  • Scan Datapath · sparsecore/scan-datapath.md · C mask 消耗 + ScanOp lowering。
  • Segmented Scan · sparsecore/segmented-scan.md · C SegmentedScanOpLowering reduction_op switch。
  • Segmented-Add-Scan · sparsecore/segmented-add-scan.md · C newer-gen segment-reduce 家族。
  • Embedding Minibatching 分解 · sparsecore/embedding-minibatching.md · C scan lowering 之上的 HLO 层。
  • SampleCombiner Emitter · sparsecore/sample-combiner-emitter.md · C inner-loop combiner emit。
  • EmitValencyLoop · sparsecore/emit-valency-loop.md · C 逐 sample valency loop。
  • RankAndPermute / RadixSort · sparsecore/rank-and-permute-radixsort.md · C sort/permute compute 函数。
  • Dedup Multiplicity · sparsecore/dedup-multiplicity.md · C DuplicateCount→multiplicity + Uniquify inverse-permutation。

SparseCore 指针与 DMA ​

SparseCore 后端 ​

SparseCore 横切内容 ​

BarnaCore（legacy v2–v4） ​

Part X — 片上内存与 DMA (20) ​

内存层级的 allocator 和 DMA wire format。层级模型在 IV 中预备；这里给出 allocator 算法和 descriptor 字节布局。

内存层级 ​

DMA ​

Part XI — 运行时与执行 (11) ​

已编译程序如何在 stream 上运行。使用 ISA（VI）和内存（X）。

Part XII — 互连与路由 (30) ​

物理 fabric 以及 packet 如何在其上路由。Pod 内集合通信（XIII）构建于其上的几何基底（twisted torus）。

ICI fabric ​

路由 ​

  • 概览 · routing/overview.md · I route-generation → route-cache → emission 流水线。
  • RandomizedToroidalWildFirstPaths · routing/randomized-toroidal-wildfirst.md · C path generator。
  • Route-Table Generation · routing/route-table-generation.md · C physmap + GetPhysicalToLogicalMapping3D。
  • GetStaticPath 与 Multipod · routing/get-static-path.md · C inter-pod route emission。
  • ToroidalRouteCache · routing/toroidal-route-cache.md · C 85-file binarypb decode + 逐代号拆分。
  • Route-Cache Decompress · routing/route-cache-decompress.md · C CompressedToroidalRouteCache proto→map。
  • Route-Cache Dedup · routing/route-cache-dedup.md · C RouteCacheDeduplicator key + type dispatch。
  • Route-Cache Codec · routing/route-cache-codec.md · C BitEncoder / DecodePathFromBits / TopologyRotationHelper。
  • CreateRoutingSchedule Solver · routing/create-routing-schedule.md · C priority-queue hop-assignment + PointerType enum。
  • net_router Pipeline · routing/net-router-pipeline.md · C software-pipeline callback + Transfer construction。
  • Unicast Route Emission · routing/unicast-route-emission.md · C DmaDestinationRoutingTableEntryMapper 之上的层。
  • GetDistances · routing/get-distances.md · C nK twisted-torus distance metric。

Twisted torus 几何 ​

ICR node-fabric ​

Part XIII — Pod 内集合通信与屏障 (30) ​

一个 collective 如何在 fabric（XII）上被分解、offload 和同步。SparseCore-offload 路径桥接到 IX。

集合算法 ​

  • 概览 · collectives/overview.md · I strategy picker 和算法家族。
  • SelectNDStrategy · collectives/strategy-nd-picker.md · C collective-algorithm picker + degraded-axis handling。
  • Binomial / Recursive-Doubling · collectives/binomial-recursive-doubling.md · C 逐 rank partner schedule。
  • AllReduce Hierarchical / Pincer · collectives/allreduce-hierarchical-pincer.md · C multi-phase 0x101 路径 + pincer fusion。
  • AllGather ND-Ring · collectives/allgather-nd-ring.md · C GetShardIndex/GetOffset + 2D/3D selector。
  • AllToAll Tables · collectives/alltoall-tables.md · C GenerateAllToAllTables → ConstantMapper。
  • ReduceScatter · collectives/reduce-scatter.md · C reduce-scatter 分解。
  • ConstantMapper · collectives/constant-mapper.md · C compile-time collective constant-pool tag + SMEM read。
  • Degraded-Axis Ingest · collectives/degraded-axis.md · C TpuDegradedAxesProto fault-tolerant 路径。

SparseCore-offload 集合通信 ​

  • SC-Offload Config Builder · collectives/sc-offload-config-builder.md · C ConstructConfigForCollectiveUniDirNDGroups。
  • HierarchicalKind · collectives/hierarchical-kind.md · C AllGather/AllReduce/ReduceScatter OffloadConfig 结构体。
  • Tensor-Split / ND-Plane · collectives/tensor-split-ndplane.md · C tensor_split_factor / NumScOffloadDevices + NDPlaneInfo。
  • Physical-Core Placement · collectives/physical-core-placement.md · C physical_core_indices 逐 color 映射。
  • SC Core-Selection（Offload） · collectives/sc-core-selection-offload.md · C assignment cost + resource model。
  • get_remote_memref · collectives/get-remote-memref.md · C 跨 chip 地址组合。
  • StartRemoteDma · collectives/start-remote-dma.md · C all-to-all producer + SubsliceToFullSliceGlobalCoreId。

SFLAG 与屏障 ​

更高层 ​

  • Megacore Fusion · collectives/megacore-fusion.md · I megacore collective fusion。
  • FP8 Quantized Collective · collectives/fp8-quantized-collective.md · C quantized-collective 分发路径。 src: #1339
  • SPMD Link-Count Cost · collectives/spmd-link-count-cost.md · C link-count divisor + 完整 collective cost-formula 集。

Part XIV — Megascale（多主机 / DCN）(21) ​

Pod 内 ICI 之上的数据中心网络层：跨主机 rendezvous、fleet metadata 和错误聚合。

Part XV — 性能分析与遥测 (22) ​

libtpu 如何发出 XPlane trace 和硬件遥测。逐代 trace payload 具有不同的 on-wire format。

Part XVI — 配置与编译旋钮 (16) ​

每个 flag、env var 和 compile knob，以及它们如何解析。TpuCompilationEnvironment 是 1,121 字段的主配置对象。

Part XVII — 附录 (18) ​

参考表、source-traceability 索引和开放前沿登记表。

  • LloOpcode 表（462） · appendix/llo-opcode-table.md · C 带类别的完整 enum。 src: P-2-25
  • LlvmTpu Intrinsic 表（1356） · appendix/llvmtpu-intrinsic-table.md · C 完整 tpu_* intrinsic 列表。
  • MemorySpace 表（17） · appendix/memory-space-table.md · C 完整枚举。 src: P-2-01
  • Dispatch-Table Taxonomy（full） · appendix/dispatch-table-taxonomy-full.md · C 全部 19 类 + 40,313-table TSV。 src: P-2-06
  • filewrapper_toc Catalog（61） · appendix/filewrapper-toc-catalog.md · C 每个嵌入式 runtime resource。 src: P-2-07
  • protodesc_cold Catalog（760） · appendix/protodesc-cold-catalog.md · C 每个嵌入式 FileDescriptorProto。 src: P-2-07
  • RTTI Namespace Census · appendix/rtti-namespace-census.md · C 完整 160,351 条目分解。
  • Reconstructed-Proto Index · appendix/reconstructed-proto-index.md · C 从 descriptor pool 恢复的每个 proto。
  • Error / Status Codes · appendix/error-status-codes.md · C status-code 目录。
  • Flag Catalog（full TSV） · appendix/flag-catalog-full.md · C machine-readable flag 列表。
  • Symbol Namespace Index · appendix/symbol-namespace-index.md · I namespace population map。 src: W014, W003
  • 逐代主比较矩阵 · appendix/per-gen-comparison-matrix.md · C bundle/lanes/MXU/XLU/IAR/SFLAG/EUP/DID，六代，一页。
  • 证据锚点索引 · appendix/evidence-anchor-index.md · I page → source-findings file → binary VA，完整 traceability map。 src: (this corpus)
  • 源码语料映射 · appendix/source-corpus-map.md · I P-2/P-3/W raw-findings file → part assignment。 src: W001, W034
  • 开放前沿登记表 · appendix/open-frontier-register.md · I 尚未恢复的内容（cmem-load/sparsity 边界；sparsity slot #1092；NOP canonical #1096；flag-prefix #1171）。
  • 交叉引用依赖图 · appendix/cross-reference-graph.md · I 页面间依赖网络。 src: G001–G003
  • 二进制布局参考 · appendix/binary-layout.md · C segment、anchor symbol、与 ptxas/nvlink/cicc 的规模对比。 src: W023, W027
  • 扩展术语表 · appendix/glossary-extended.md · I 每个 acronym + internal class name。 src: W014

附录亮点 ​

两个附录页面是连接材料，使本书可审计，并让逐代叙事保持连贯：

  • 证据锚点索引（appendix/evidence-anchor-index.md）— 完整的 page → source-findings file（P-2-*/P-3-*/W*）→ binary VA 映射。书中的每个论断都可经由该索引追溯到一个具体函数地址和一个具体 raw-findings file。这正是可重新实现参考与博客文章的区别。
  • 逐代主比较矩阵（appendix/per-gen-comparison-matrix.md）— 一页，六代（Jellyfish/Dragonfish/Pufferfish/Viperfish/Ghostlite/6acc60406）× 每个逐代常量：bundle 大小、lane/sublane 计数、MXU 维度、XLU/IAR 计数、逐层级内存（VMEM/SMEM/SFLAG/CMEM/HBM）、accelerator-core 类型，以及承载逐代 EUP push→pop 延迟的成本模型类三元组（LatencyTable/CycleTable/Performance）。把原本分布在 Part IV、VI 和 VII 的逐代材料串在一起。

开放前沿 ​

等级为 O 的页面尚未由完整 raw-findings file 支撑：sparsity slot 编码（task #1092）、逐代 NOP canonical 编码（#1096）、TpuVersion-aware flag-prefix dispatch（#1171），以及 cmem-load/sparsity 边界。开放前沿登记表跟踪这些内容。其他所有内容都由 C（已确认）或 I（推断）raw-findings file 支撑。