第 IV 部分概览 — 硅片和硬件代号模型

地址适用于来自 libtpu-0.0.40-cp314 wheel 的 libtpu.so。其他版本会有所不同。

摘要

libtpu.so 是 XLA 加载以面向 Google TPU 硬件的 PJRT 插件，并且它必须用一个二进制文件服务六个不同的硅片世代。第 IV 部分记录该库如何表示这一事实：一个命名世代的 6 值枚举 (tpu::TpuVersion)、驱动它的三组 HAL 工厂族，以及挂在枚举整数下的逐世代 codec、bundle encoder 和芯片常量表。本页是该子系统的地图 — 六个世代是什么、它们如何分组，以及版本整数如何贯穿 HAL 路由、ISA 选择和硬件常量查找。

这个模型最容易通过类比一个 LLVM 后端用同一个 TargetMachine 服务多个 sub-target 来理解。TpuVersion 枚举扮演 Triple::ArchType 的角色 — 一个门控每个目标相关决策的单一整数 — 而 HAL 工厂族扮演 Subtarget 选择的角色。TPU 独有的麻烦在于双枚举陷阱：运行时分发所用的整数（TpuVersion，从 0 开始）与序列化 proto 中传递的整数（TpuVersionProto，从 1 开始）相差一。本部分中有一半页面都是为了把这两套编号理清。

本部分按三层组织。身份层（本概览、代号矩阵、双枚举页面）定义枚举及其到代号、wire 值和外部名称的交叉映射。路由层（HAL families、sub-core taxonomy、各 family 页面）定义一个版本如何选择工厂以及 fetch/load core 拆分。常量层（per-codename HW constants、PCI device IDs、chip parts）定义每个世代携带的硬件参数。

世代	6 — kJellyfish=0 … k6acc60406=5
身份枚举	tpu::TpuVersion（内部，从 0 开始）↔ TpuVersionProto（wire，从 1 开始）
规范映射	tpu::TpuVersionToString @ 0x20b3a480 → off_22011BF0 rel.ro 指针表
HAL 族	3 个工厂类 — JXC、PXC、VXC
Sub-core 模型	从 Pufferfish 起的 fetch/load core 拆分（pfc/plc、vfc/vlc）
ISA 子族	共享 VXC family 下的 gxc::gfc（v5，fetch）、gxc::glc（v4，load）

---

六个世代

六个 TpuVersion 值按枚举顺序列出，并附上 codename matrix 完整建立的一行身份说明。代号是 TpuVersionToString 的输出；外部名称是 TpuVersionToExternalName 的输出。

Int	代号	外部名称	HAL 族	定义性特征
0	jellyfish	TPU v2	JXC	第一代；BarnaCore embedding engine，无 SparseCore
1	dragonfish	TPU v3	JXC	Jellyfish 派生版 — 共享 encoder、flags、bundle 限制
2	pufferfish	TPU v4	PXC	引入 fetch/load core 拆分（pfc/plc）
3	viperfish	TPU v5	VXC	首个 SparseCore；BarnaCore 退役
4	ghostlite	TPU v6 lite	VXC	gxc::glc ISA 子族；具名 codec
5	6acc60406	TPU7x	VXC	混淆代号；匿名 codec；gxc::gfc ISA 子族

两个结构性事实塑造了下游的一切。第一，这些世代并非彼此独立 — Dragonfish 复用 Jellyfish 的 encoder（共享的 CreateEncoderJfDf 路径），而 6acc60406 复用 Ghostlite 的 encoder（CreateEncoderGlGf），因此六个世代归并为四个 encoder family。第二，最新世代（6acc60406）暴露得最少：只有它拥有混淆且非助记的代号、没有具名 TpuCodec C++ 类，并且 bundle-restrictions 注册只以字符串存在。这种不对称是该二进制文件自己标记哪一代硅片在此构建中最新的方式。

---

三个 HAL 族

六个代号由符号表确认的正好三个 HAL 工厂类服务：TpuHalJxcHardwareFactory、TpuHalPxcHardwareFactory 和 TpuHalVxcHardwareFactory。映射是多对一：

JXC  TpuHalJxcHardwareFactory   <- kJellyfish (0), kDragonfish (1)
PXC  TpuHalPxcHardwareFactory   <- kPufferfish (2)              (constructed with no version arg)
VXC  TpuHalVxcHardwareFactory   <- kViperfish (3), kGhostlite (4), k6acc60406 (5)
```text

JXC 承载两个最老的世代，因为 Dragonfish 是共享其 dataflow 的 Jellyfish 刷新版。PXC 专用于 Pufferfish，并且构造时不带版本参数，因为它只服务一个世代。VXC 是现代 family：它处理 Viperfish、Ghostlite 和 6acc60406，只由工厂构造时传入的 `TpuVersion` 整数区分 — 一个工厂类以三种方式参数化。init-module 到 factory 的接线（`google_init_module_tpu_hal_*` translation units，包括分别命名的 `glc` 和 `gfc` init modules，它们都注册 VXC factory）详见 [HAL Families](hal-families.md)。

> **注意：** `glc` 和 `gfc` init-module 名称并不意味着存在 `Glc`/`Gfc` 工厂类。第 4 和第 5 世代通过以其 ISA 子族命名的 init modules（`glc`、`gfc`）注册，但二者都构造共享的 `TpuHalVxcHardwareFactory`。不存在 `TpuHalGxcHardwareFactory`。`glc`/`gfc` token 命名的是 *ISA sub-core namespace*，而不是第四个 HAL family。

---

## Fetch/Load Sub-Core 拆分

从 Pufferfish 开始，逐世代 ISA namespace 拆成一个 **fetch core** 和一个 **load core** — 一种解耦访问/执行组织，其中一个 core 流式传输操作数，另一个 core 执行。这个拆分直接出现在 `asic_sw::driver::deepsea` namespace 群中：

```text
deepsea (driver umbrella)
  jxc   jellyfish/dragonfish   -- no fetch/load split (fused dataflow)
  pxc   pfc (fetch) / plc (load)      -- Pufferfish; split introduced here
  vxc   vfc (fetch) / vlc (load)      -- Viperfish family
  gxc   gfc (fetch) / glc (load)      -- gfc -> 6acc60406 (v5), glc -> Ghostlite (v4)

这个模式在 pxc 和 vxc 中很清楚：f/l 字母标记 fetch 与 load，且符号计数不对称（fetch core 大得多 — pfc 约 8.0K vs plc 约 0.9K，vfc 约 17.4K vs vlc 约 1.8K 个 mangled-token 出现），符合一个芯片内解耦 fetch/execute 对的特征。JXC 没有这种拆分：jxc::jellyfish 是一个很薄的 namespace，匹配第一代融合 dataflow 设计，没有单独的 fetch core。

注意：在 gxc 下，f/l 字母标记 fetch/load，且每个 sub-core 都是不同的世代。 gfc 是 general fetch-core，glc 是 general load-core — 与 pxc/vxc 相同的 f/l 约定。转折在于两个 gxc sub-core 并不拆分同一个芯片：glc 承载 Ghostlite（v4），gfc 承载 6acc60406（v5），各自都是完整且规模接近的 ISA namespace（gfc 约 63.8K、glc 约 62.9K token 出现 — 不是 pxc/vxc 那种一边倒的 fetch/load 比例）。codec walk 锁定了配对 — TpuCodecGhostlite 绑定 gxc::glc::isa，匿名 v5 codec 绑定 gxc::gfc::isa。把 gfc 解读为 "Ghostlite fetch-core" 会同时颠倒这两个事实；sub-core taxonomy 页面详细推导了这个配对。

---

TpuVersion 如何贯穿流水线

当程序从目标识别走向代码发射时，版本整数会按以下顺序在三个决策点被读取：

accelerator_type string ("v5p", "v6e", "tpu7x", ...)
        |  AcceleratorTypeToTpuVersionEnum (parser)         @ 0x204cf620
        v
   TpuVersion  (internal enum, 0..5)
        |
        +--> HAL routing:    TpuHalFactory::Register / Create  -> JXC | PXC | VXC factory
        |
        +--> chip constants: per-version constant tables, chip_parts.binarypb (proto version = internal+1)
        |
        +--> ISA selection:  TpuCodec::Create  @ 0x1e835fa0     -> per-codename codec
                             ProgramProtoUtil::BundleCount @ 0x1e830e80 -> encoder family (JfDf | Pf | Vf | GlGf)
```text

1. **识别。** 用户提供的 `accelerator_type` 字符串由 `AcceleratorTypeToTpuVersionEnum`（`0x204cf620`）解析为 `TpuVersion`。从此处开始，字符串消失，所有事情都变成整数分发。反方向 — 枚举回显示字符串 — 是 `TpuVersionToExternalName`（`0x20b3a500`）。

2. **HAL 路由。** 版本选择 HAL 工厂族。`TpuHalFactory::Register` 记录 `(PlatformType, TpuVersion) → factory`，运行时查找会构造由该版本参数化的 JXC、PXC 或 VXC factory。

3. **芯片常量。** 逐版本硬件参数（core 数量、MXU 形状、内存层级）从逐版本常量表和嵌入的 `chip_parts.binarypb` 资源中读取。这是双枚举陷阱咬人的一个阶段：chip-parts 的 `version` 字段是 *proto* 值，因此最新世代的 blob 对运行时分发为 `5` 的硅片读作 `6`。参见 [Dual Enum](dual-enum-proto-vs-internal.md)。

4. **ISA 选择。** 版本选择 codec（`TpuCodec::Create`，`0x1e835fa0` — 每个世代一个 `CreateTpuCodec<Codename>`，v5 codec 匿名）以及 bundle encoder family（`ProgramProtoUtil::BundleCount`，`0x1e830e80` — 它把六个世代归并为四个 encoder family：`JfDf`、`Pf`、`Vf`、`GlGf`）。

重新实现必须以相同顺序、在同一个整数上执行这些读取。最常见的失败模式是在阶段之间混用两套 enum 空间 — 把字符串解析为内部 enum，不加 `+1` 就序列化为 proto，然后不减 `−1` 就反序列化回来，最终偏离一个世代。

---

## 交叉引用

- [TPU 版本代号矩阵](tpu-version-codename-matrix.md) — 权威的 enum 到 codename 映射、五轴交叉映射和特性矩阵
- [双枚举（Proto vs Internal）](dual-enum-proto-vs-internal.md) — `internal = proto − 1` 的差一关系和完整 wire-value 表
- [HAL 族](hal-families.md) — JXC / PXC / VXC factory 路由和逐代号 init modules
- [Sub-Core 分类](sub-core-taxonomy.md) — fetch/load core 拆分和 `gxc::glc` / `gxc::gfc` ISA 子族
- [逐代号 HW 常量](per-codename-hw-constants.md) — 由 `TpuVersion` 门控的硬件参数
- [PCI 设备 ID](pci-device-ids.md) — 在发现阶段把硅片绑定到版本的 DeviceIdentifiers 记录
- [TpuChipConfig](tpu-chip-config.md) — 解码后的常量如何组装成运行时 `Target` config
- [内存层级](memory-hierarchy.md) — 常量填充的 HBM/VMEM/SMEM/SFLAG/CMEM 层级模型
- [Marketing / Cloud 命名](marketing-cloud-naming.md) — `accelerator_type` 词汇表和 codename↔Cloud 交叉映射
- [TpuHal 类层级](tpuhal-class-hierarchy.md) — 版本整数键入的四棵类树
- [ISA 概览](../isa/overview.md) — 版本选择的 codec 和 bundle-encoder families