命名陷阱与权威标签

地址适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（build-id 89edbbe81c5b328a958fe628a9f2207d，781,691,048 B）。其他版本会不同。

摘要

TPU 代号模型里有几个很容易混淆的标签，还有少量看似合理但被二进制否定的错误名称。本页是常设陷阱清单：列出每个诱人但错误的标签，引用推翻它的字节证据，并给出权威值。如果下游页面说 "Ghostlite = v5p"、"Trillium = 6acc60406"、"2 HAL families"，或者把 "Ghostfish" 当作已确认的代号，那么按这里的证据就是错的。

这些陷阱分为三类：计数陷阱（TpuVersion 和 HAL-family 的计数很容易少算）、差一代命名陷阱（Cloud 名称整体上滑一代，把 Ghostlite 误标为 v5p，把 6acc60406 误标为 v6e/Trillium），以及编造代号（"Ghostfish" 这个释名在二进制中出现次数为零）。下面每个权威值都有字节锚点。

对重新实现的收益很直接：采用这里任何一个错误标签的克隆实现，都会把硅片路由到错误的工厂、codec 或外部名称。相信 "Ghostlite = v5p" 会把 Ghostlite 的 TpuVersion 4 交给属于 Viperfish（TpuVersion 3）的显示字符串和 Cloud 类型；相信 "2 HAL families" 会提前一代分叉 VXC 类；相信 "Ghostfish" 或 "TpuCodec6acc60406" 会发明一个二进制从未声明过的符号。下表逐项列出二进制事实，说明是什么让整数分发、工厂键和生成名称在各代之间保持一致。

权威 TpuVersion 计数	6（枚举 0..5），由 TpuVersionToString @ 0x20b3a480 限定（a1 >= 6 → fatal）
权威 HAL family 计数	3 — JXC、PXC、VXC 工厂类
代号事实来源	TpuVersionToString rel.ro 表 @ 0x22011bf0（6 个重定位）
二进制中的营销名称	无（Trillium/Ironwood/Ghostfish = 0 次出现）

---

计数事实

陷阱 — "5 TpuVersions" 少算了；实际有 6 个。 二进制定义了六代。TpuVersionToString（0x20b3a480）在索引一个六项指针表前检查 a1 >= 6，而位于 0x22011bf0 的 .data.rel.ro 表正好有六个 R_X86_64_RELATIVE 重定位，分别命名 jellyfish（0x863f064）、dragonfish（0x863f392）、pufferfish（0x863f1c4）、viperfish（0x863f172）、ghostlite（0x86864e0）、6acc60406（0x863f0cf）。最常被漏掉的值是 viperfish（v3）：它很容易被并入相邻代。TpuVersionFromProto（0x20b3a8c0）同样有 1..6 的 case，映射到内部 0..5。

陷阱 — "2 HAL families" 少算了；实际有 3 个。 有三个不同的工厂类，由三条独立的 typeinfo 记录确认：tpu::(anon)::TpuHalJxcHardwareFactory、tpu::(anon)::TpuHalPxcHardwareFactory 和 tpu::TpuHalVxcHardwareFactory。六代按 JXC（Jellyfish、Dragonfish）、PXC（Pufferfish）和 VXC（Viperfish、Ghostlite、6acc60406）路由。最新两代共享 VXC 工厂：glc 初始化模块位于 0x94a4a6f 的 CHECK 字符串为 make_unique<TpuHalVxcHardwareFactory>(kGhostlite)，gfc 初始化模块位于 0x94a3ef5 的字符串为 make_unique<TpuHalVxcHardwareFactory>(k6acc60406)。因此 glc/gfc 是 VXC-family 子核心，不是第四个工厂。参见 HAL Families。

---

命名事实

glc 和 gfc 编码器的地址与命名空间没有歧义；陷阱在于把 Cloud/营销名称上滑一代套到它们身上。

陷阱 — "Ghostlite = v5p" 高了一代；Ghostlite = v6e / "TPU v6 lite"。 位于 0x1f250160 的 glc 编码器是 gxc::glc::isa::TensorCoreVectorAlu0Encoder::Encode。命名空间 Ghostlite/glc 是正确的；v5p 不是 — v5p 是 Viperfish (v3) 的 Cloud 标准名称，其字符串 "TPU v5p" 位于 0x85c9e34，低一代。正确绑定是 glc = TpuVersion 4 = ghostlite = "TPU v6 lite"（TpuVersionToExternalName @ 0x20b3a500 的 case 4）= Cloud v6e = Trillium（外部）。参见 Marketing / Cloud Naming。

陷阱 — "6acc60406 = Trillium / v6e" 低了一代；6acc60406 = TPU7x。 位于 0x1f8b53c0 的 gfc 编码器带有命名空间 gfc 和标签 6acc60406 — 两者都正确 — 但 Trillium/v6e 属于低一代的 Ghostlite。正确绑定是 gfc = TpuVersion 5 = 6acc60406 = "TPU7x"（TpuVersionToExternalName 的 case 5）= Cloud tpu7x。这两个编码器的位级 VALU 编码不受影响；移动的只是版本/营销标签。

陷阱 — "Ghostfish" 不是二进制代号。 释名 "Ghostfish" 很容易被类比为 ghostlite→glc，但对完整镜像做不区分大小写扫描，对 ghostfish/Ghostfish 返回零个匹配，并且不存在 TpuCodec6acc60406 C++ 类符号（只有源路径字符串 tpu_codec_6acc60406.cc；由 sub_1E838380 构建的 v5 codec 是匿名的）。这一代唯一规范的内部名称是混淆标签 6acc60406。

---

Codec / 类拓扑事实

注意： v5 codec 是匿名的，不是名为 tpu::TpuCodec6acc60406 的类。TpuCodec::Create（0x1e835fa0）case 5 调用 sub_1E838380，后者构造的对象其 vtable 没有反修饰符号 — 类是匿名的。相比之下，case 4 调用有名的 tpu::CreateTpuCodecGhostlite，而 TpuCodecGhostlite 是一个真实类，带有 DecodeBundle/EncodeBundle 方法。v5 codec 可用，但没有具名实体；不存在 TpuCodec6acc60406 类。

codec 分发如下，逐字来自反编译：

TpuCodec* TpuCodec::Create(TpuVersion v):     // 0x1e835fa0
    case 0: return CreateTpuCodecJellyfish()
    case 1: return CreateTpuCodecDragonfish()
    case 2: return CreateTpuCodecPufferfish()
    case 3: return CreateTpuCodecViperfish()
    case 4: return CreateTpuCodecGhostlite()    // NAMED class
    case 5: return sub_1E838380()               // anonymous v5 codec
```text

> **注意：** `xla::jellyfish::GhostliteBundleRestrictions` 是一个具名类（存在 typeinfo + vtable + `AddMxuRequirements`/`AddXluRequirements` 方法），而 v5 代只通过字符串注册 `6acc60406BundleRestrictions`，没有规范 C++ 类。最新两代之间的命名不对称 — Ghostlite 具名、6acc60406 混淆 — 是一种刻意模式。

---

## Device-Type 和 v5 Chip-DID 事实

> **注意：** Ghostlite→device-type `13`（`0xd`）和 6acc60406→device-type `12`（`0xc`）的绑定是直接存储，不是推断。`DeviceTypeFromDeviceIdentifiers`（`0xf6993a0`）直接写入常量：在 `IsGlc` 分支写 `*(_DWORD*)(result+8) = 13`，在 `IsGfc` 分支写 `= 12`。完整 device-type 映射（Jellyfish 3、Dragonfish 5、Pufferfish 7、Puffylite 8、Viperfish 10、Viperlite 11、6acc60406 12、Ghostlite 13）是单个函数事实。参见 [PCI Device IDs](pci-device-ids.md)。
>
> **注意：** 6acc60406 PCI device ID 是真实的 `.rodata` 记录，只是匿名记录。它位于 `.rodata` `0xbdf3cc4`–`0xbdf3ce8`，由三条**匿名** 12 字节记录组成（PF hdr `0x0075`、VF hdr `0x0076`、Mgt PF hdr `0x0077`；全部 chip DID `0x00f2`、rev-mask `0xff`），并由 `s_44716` 标签终止。chip DID `0x00f2` 还由 `IsGfc` 立即数（`0xF21AE000751AE0`、`0xF21AE000761AE0`）独立确认。

---

## 双枚举 chip_parts 陷阱

> **注意：** 嵌入的 `6acc60406_chip_parts.binarypb` blob（`0xbdf29a0`、`0xbdf2ba0`）以 `08 06 12 97 01` 开头 — protobuf 字段 1（varint）= **6**。这个 `6` 是 **TpuVersionProto** 值（`TPU_VERSION_6acc60406`），是 1-based 枚举，不是内部 `TpuVersion`。`TpuVersionFromProto`（`0x20b3a8c0`）按 `internal = proto − 1` 映射，所以 proto `6` → 内部 `TpuVersion 5`。"chip_parts version 6" 和 "internal TpuVersion 5" 在两套平行枚举上命名的是**同一块** 6acc60406 / TPU7x 硅片；不存在冲突。codec platform-tag 守卫也独立确认了这一点（v4/Ghostlite codec 检查 proto 标签 5，v5 codec 检查 proto 标签 6）。参见 [Dual Enum](dual-enum-proto-vs-internal.md)。

---

## 命名陷阱速查表

| 诱人但错误的标签 | 诱因 | 权威值 | 证据 |
|---|---|---|---|
| "5 TpuVersions" | viperfish 被并入相邻代 | 6（`0..5`） | `TpuVersionToString` 边界 `>= 6`；6 个重定位 @ `0x22011bf0` |
| "2 HAL families" | VXC 吸收三个代号 | 3（JXC / PXC / VXC） | 三个工厂 typeinfo |
| "Ghostlite = v5p" | 差一代 Cloud 名称 | `v6e` / "TPU v6 lite" | `TpuVersionToExternalName` case 4 |
| "6acc60406 = Trillium / v6e" | 差一代营销名称 | "TPU7x" / `tpu7x` | `TpuVersionToExternalName` case 5 |
| "v5 codec = TpuCodec6acc60406" | 类比具名 codec | 匿名 codec（`sub_1E838380`） | 无类符号；只有 `tpu_codec_6acc60406.cc` 路径 |
| "Ghostfish"（gfc 代号） | 类比 `ghostlite`→`glc` | `6acc60406`（混淆标签） | `ghostfish` = 0 次出现 |
| "chip_parts internal version 6" | 混淆 proto/internal | proto 6 = internal 5 | `08 06` blob 字节；`TpuVersionFromProto` `−1` |
| "v5 PCI DID has no record" | 匿名（无符号） | chip DID `0x00f2`（匿名记录） | 字节 `0xbdf3cc4`+；`IsGfc` 立即数 |

---

## 交叉引用

- [代号矩阵](tpu-version-codename-matrix.md) — 这些修正所维护的权威 `TpuVersion` ↔ 代号表
- [营销 / Cloud 命名](marketing-cloud-naming.md) — `v5p`-vs-`v6e` 对照和仅外部使用的营销名称
- [PCI Device IDs](pci-device-ids.md) — 字节锚定的 device-type 与 v5 chip-DID 事实（PIN-01 / PIN-02）
- [HAL Families](hal-families.md) — 三工厂路由（CNT-02）