子核心分类（GFC/GLC/JXC/PXC/VFC/VLC）

地址适用于 libtpu-0.0.40-cp314 wheel（build-id 89edbbe81c5b328a958fe628a9f2207d）中的 libtpu.so。其他版本会有所不同。

摘要

libtpu 的驱动层组织在一个总命名空间 asic_sw::driver::deepsea:: 之下，每个 HAL 家族各有一个子命名空间：jxc、pxc、vxc、gxc。在每个家族内部，代码被划分为子核心，也就是片上编译器所面向的、按引擎划分的指令流处理器。这个分类中最重要的轴线是 fetch/load-core 拆分：某个家族是通过一条融合的数据流路由一个核心的指令流，还是通过两个协作核心（读取/发射的 fetch-core，以及暂存数据的 load-core）来路由。

这个拆分有明确的时间起点。JXC（Jellyfish、Dragonfish）没有拆分，其数据流是融合的，子命名空间按引擎块组织（dfc、jfc、registers、snap、trace-entry 类型）。从 PXC（Pufferfish）开始，每个家族都采用 fetch+load 拆分：PXC 有 pfc+plc，VXC 有 vfc+vlc，GXC 有 gfc+glc。本页标题中的六个 token 就是这些子核心。它们不是任意标签：它们作为真实的 C++ 命名空间出现在符号表中，并且（对于拆分家族）各自携带自己的 isa 和 profiler 子命名空间。

本页统一四个家族页面分别记录的内容。它确立了（1）拆分演进时间线，（2）从符号表验证出的逐家族子命名空间名册，以及（3）子核心与促成这种分组的 profiler TraceEntry 类之间的关系。它是“哪些子核心存在以及它们含义是什么”的规范参考；逐家族页面则承载 factory 和构造细节。

对于重新实现，契约是：

拆分时间线：JXC 融合 → PXC 引入 fetch+load → VXC 继承它 → GXC 将 ISA 完全下推到子核心中。重新实现必须为 JXC 建模每核心一条 pipeline，并为之后每个家族建模两个协作核心。
已验证的命名空间名册：哪些 asic_sw::driver::deepsea::<family>::<sub> 命名空间实际存在（而不是类型名内部那些看起来像命名空间的前缀）。
codename ↔ sub-core 映射，包括容易反转的 GXC 配对（Ghostlite=glc，6acc60406=gfc）。
profiler TraceEntry 集合（五个类，不是六个）以及它如何偏离六个子核心。


总命名空间	`asic_sw::driver::deepsea::`
家族	`jxc`（融合）、`pxc`、`vxc`、`gxc`（后三者均拆分）
Fetch/load 拆分起点	PXC（Pufferfish，v2）— JXC 是唯一的融合家族
子核心（拆分家族）	`pfc`/`plc`、`vfc`/`vlc`、`gfc`/`glc`
`TraceEntry` 类	5 — `pxc`（家族级）、`vxc::vfc`、`vxc::vlc`、`gxc::gfc`、`gxc::glc`
证据	`_functions.json` 符号名册；mangled `asic_sw::driver::deepsea::` 命名空间

Fetch/Load 拆分演进

融合时代（JXC）

JXC 携带一条融合的数据流。它的命名空间树中没有 fetch-core / load-core 区分：asic_sw::driver::deepsea::jxc:: 的直接子节点是引擎块（dfc — dataflow controller，jfc — Jellyfish core，registers，snap）、特定世代的性能计数器（jellyfish_performance_counters、dragonfish_performance_counters），以及一组 *_trace_entry 事件类型。JXC 的重新实现应建模为每核心一条指令 pipeline；没有需要协调的第二个暂存核心。

拆分时代（PXC → VXC → GXC）

从 Pufferfish 开始，每个核心的工作被划分到 fetch-core（指令读取和发射）与 load-core（数据暂存）之间。这种拆分表现为每个家族下两个同级子命名空间：

text

asic_sw::driver::deepsea::
  ├─ jxc/                      (融合 — 无拆分)
  │    dfc, jfc, registers, snap, *_performance_counters, *_trace_entry
  ├─ pxc/                      (引入拆分)
  │    ├─ pfc/                 ── Pufferfish fetch-core   (isa, profiler, b0)
  │    ├─ plc/                 ── Pufferfish load-core    (profiler)
  │    ├─ isa/                 ── 家族级 ISA
  │    └─ profiler/            ── 家族级 profiler（持有 TraceEntry）
  ├─ vxc/                      (继承拆分)
  │    ├─ vfc/                 ── vector fetch-core        (isa, profiler/TraceEntry)
  │    ├─ vlc/                 ── vector load-core         (profiler/TraceEntry)
  │    └─ isa/                 ── 家族级 ISA
  └─ gxc/                      (拆分；ISA 只在子核心下)
       ├─ gfc/                 ── general fetch-core (6acc60406/v5)  (isa, profiler/TraceEntry)
       └─ glc/                 ── general load-core  (Ghostlite/v4)  (isa, profiler/TraceEntry)
```text

> **注意 —** 拆分逐步移动到*更深层*。PXC 和 VXC 保留家族级 `isa` 命名空间，同时也有 fetch/load 子核心。GXC **没有**家族级 `isa`（符号搜索 `deepsea3gxc3isa` 返回零）；它的整个 ISA 都位于 `gxc::gfc::isa` 和 `gxc::glc::isa` 下。因此架构趋势是融合（JXC）→ 使用共享家族 ISA 的拆分（PXC、VXC）→ 使用逐子核心 ISA 的拆分（GXC）。

### 拆分存在的原因

fetch/load 拆分将指令发射与数据移动解耦，使 load-core 可以在 fetch-core 继续发射的同时预取并暂存操作数，这是把 issue pipe 与 load/store pipe 分离的标准理由。它与另外两个 PXC 时代的变化一起到来，而这些变化也指向同一方向：DMA 从独立 issuer 对象（JXC 的 `JfDmaIssuer`）移入驱动本身，DMA 描述符也从 V1 的 32-byte 单级形式推进到 V2 的 ≥96-byte 4-level-strided 形式。这个拆分是更丰富的数据移动模型在指令侧的对应物。

---

## 逐家族子命名空间名册（已验证）

这个名册直接取自 `*_functions.json` 符号表，这是关于实际存在内容的最强可用证据。计数是 mangled 命名空间 token 的出现次数；“—”表示该命名空间不存在。

| 子命名空间 | JXC | PXC | VXC | GXC |
|---|---|---|---|---|
| fetch-core | —（融合） | `pfc` | `vfc` | `gfc` |
| load-core | —（融合） | `plc` | `vlc` | `glc` |
| 家族级 `isa` | — | `pxc::isa` (137K) | `vxc::isa` (170K) | —（不存在） |
| 家族级 `profiler` | — | `pxc::profiler` (8K) | — | — |
| 子核心 `isa` | — | `pfc::isa` (46K) | `vfc::isa` (69K) | `gfc::isa` (270K), `glc::isa` (294K) |
| 子核心 `profiler` | — | `pfc`, `plc` | `vfc`, `vlc` | `gfc`, `glc` |
| 引擎块 | `dfc`, `jfc`, `registers`, `snap` | `internal`, `pfc::b0` | — | — |

> **注意 —** `bcs`/`brn`/`hbm`/`hib`/`ici` token *不是* JXC 子命名空间，它们是 `*_trace_entry` 类型名内部的前缀（例如 `bcs_internal_trace_entry`、`ici_packet_trace_entry`）。JXC 根本**没有 `jxc::isa`**：Jellyfish/Dragonfish 编译器侧 ISA 位于 `platforms_deepsea::jellyfish::isa`（共享 compiler-base 命名空间，例如 `platforms_deepsea::jellyfish::isa::BundleSlot`、`MiscOpcode`；demangled-symbol 搜索 `xla::jellyfish::isa` 返回零，`platforms_deepsea::jellyfish::isa` 返回 3122）。`jellyfish`/`dragonfish` 只作为 `jellyfish_performance_counters` / `dragonfish_performance_counters` 出现，从不作为裸命名空间出现。
>
> **注意 —** GXC 的 ISA 和 profiler 位于*子核心*层级：`gxc::gfc::isa`、`gxc::glc::isa`、`gxc::gfc::profiler` 和 `gxc::glc::profiler` 都存在且规模很大。GXC 缺少的是*家族级* `gxc::isa`/`gxc::profiler`（PXC 和 VXC 有这些；GXC 将 ISA 下推到子核心）。GXC 只在 HAL 对象层级位于 VXC 家族内部（共享 factory 和 impl — 参见 [GXC 家族](gxc-family.md)）；它的驱动 ISA 完全属于自己。

---

## 六个子核心与 Codename 映射

六个子核心到 silicon codename 的映射如下。JXC 作为融合前身也列入以求完整；它没有 fetch/load 子核心，因此该行命名的是家族而非子核心。

| 子核心 | 家族 | 角色 | Codename | TpuVersion |
|---|---|---|---|---|
|（融合）| JXC | 单条融合数据流 | Jellyfish, Dragonfish | 0, 1 |
| `pfc` | PXC | Pufferfish fetch-core | Pufferfish | 2 |
| `plc` | PXC | Pufferfish load-core | Pufferfish | 2 |
| `vfc` | VXC | vector fetch-core | Viperfish | 3 |
| `vlc` | VXC | vector load-core | Viperfish (Viperlite) | 3 |
| `glc` | GXC | general load-core | **Ghostlite** | **4** |
| `gfc` | GXC | general fetch-core | **6acc60406** | **5** |

> **易错点 —** GXC codename 配对是本页最容易弄错的内容。**Ghostlite (v4) = `glc`**（load-core）；**6acc60406 (v5) = `gfc`**（fetch-core）。codec 路径在符号层面固定了这一点：`TpuCodecGhostlite` 只分派到 `gxc::glc::isa` + `ghostlite::isa::EncoderGl*`；匿名 v5 codec 只分派到 `gxc::gfc::isa`。二进制的外部名称字符串让两者相差一个世代：Ghostlite 解析为 `TPU v6 lite`（`TPU v6e`/`TPU v6 lite` 频段），6acc60406 解析为 `TPU7x`，因此把 `gfc` 与某个 “v6” 名称配对会出现一代的 off-by-one。规范的 version↔external-name 对照见 [Codename 矩阵](tpu-version-codename-matrix.md)。

---

## Profiler Trace-Entry 类

这些子核心最初被归组，是因为 profiler 会发出逐子核心的 `profiler::TraceEntry` 事件类。符号表显示这个类存在于**五个**命名空间中，而不是六个，并且也不是显而易见的一子核心一类模式：

| 持有 `profiler::TraceEntry` 的命名空间 | Token 计数 | 粒度 |
|---|---|---|
| `pxc::profiler::TraceEntry` | 3087 | **家族级**（未拆分为 pfc/plc） |
| `vxc::vfc::profiler::TraceEntry` | 4338 | 子核心（fetch） |
| `vxc::vlc::profiler::TraceEntry` | 3326 | 子核心（load） |
| `gxc::gfc::profiler::TraceEntry` | 4781 | 子核心（fetch） |
| `gxc::glc::profiler::TraceEntry` | 4590 | 子核心（load） |

`TraceEntry` 类消费 `TpuXPlaneBuilder` 并生成 `tsl::profiler::XEventBuilder` 事件（`ProcessTraceEntry`、`UpdateContext` 方法），送入 XLA profiler 的 XPlane。每个实例由 `ChipCoreId` 标识，并串接 `JfTrace_RunDebugInfo` vector 与 offload-context 查找 map。

> **易错点 —** 统一的 `profiler::TraceEntry` 类并不是一子核心一个。**JXC 没有 `profiler::TraceEntry` 类**；它的 profiler 支持是通过逐引擎 `*_trace_entry` *类型*（例如 `ici_packet_trace_entry`）实现的，而不是统一的 `TraceEntry`。并且 **PXC 的 `TraceEntry` 位于家族层级**（`pxc::profiler::TraceEntry`），没有拆分到 `pfc`/`plc`；`pfc`/`plc` profiler 反而持有控制接口和 limits-factory 类（`TracemarkLimitsFactory`、`EveryoneTraceControlFactory`）。因此统一 `TraceEntry` 类恰好存在于五处：PXC（家族）、VFC、VLC、GFC、GLC。六个*子核心*（fetch/load 命名空间）和五个 *trace-entry 类*是不同集合，只有 VXC 和 GXC 上整齐重合。

---

## Deepsea 总命名空间与 Compiler-Base 命名空间

“deepsea” 是总项目；每个 silicon 驱动家族（`jxc`/`pxc`/`vxc`/`gxc`）都是 `asic_sw::driver::deepsea::` 的子节点。但 “deepsea” 和 “jellyfish” 还有第二种并行用法，重新实现者不能把它与驱动树混淆：**compiler base**。它横跨两个顶层命名空间：`platforms_deepsea::jellyfish::isa` 持有共享 ISA primitives，`xla::jellyfish::` 持有 codec、逐 codename 编译器 target 和 cost model。不存在 `xla::jellyfish::isa`（`isa` 子命名空间只位于 `platforms_deepsea::` 下）。

```text
deepsea（总项目）
  ├─ COMPILER-BASE（generation-agnostic ISA + codec）
  │    ├─ platforms_deepsea::jellyfish::isa   ── 共享 ISA primitives（BundleSlot, MiscOpcode, …）
  │    ├─ ghostlite::isa                      ── 命名的 v4 worker encoders/decoders（EncoderGl*, DecoderGl*）
  │    ├─ viperfish::isa                      ── 命名的 v3 worker encoders/decoders（EncoderVf*, DecoderVf*）
  │    └─ xla::jellyfish::                     ── codec + targets + cost models
  │         ├─ CompactProgram<...>            ── 以 gxc::{gfc,glc}::isa bundle 类型为模板参数
  │         ├─ JellyfishTarget / DragonfishTarget   ── 逐 codename compiler targets
  │         └─ JfCycleTable / GfcCycleTable / GlcCycleTable   ── 逐世代 cost models
  └─ asic_sw::driver::deepsea::                ── DRIVER tree（本页主题）
       jxc, pxc, vxc, gxc + their sub-cores

两棵树在 codec 层相遇：一个 TpuCodec* 对象（编译器侧，位于 xla::jellyfish::CompactProgram 下）发出 bundle，而这些 bundle 的类型位于驱动树的子核心 ISA 下，例如 xla::jellyfish::CompactProgram<asic_sw::deepsea::gxc::glc::isa::TensorCoreBundleCompact>。因此 compiler base 是 generation-agnostic 的，而逐世代特化则是插入其中的子核心 ISA bundle 类型。

易错点 — 因为 compiler base 命名为 jellyfish，搜索 “jellyfish ISA” 会落到 platforms_deepsea::jellyfish::isa，而不是任何 jxc::isa（也不是 xla::jellyfish::isa，后者有零个符号；xla::jellyfish:: 持有 codec、targets 和 cost models，但 ISA primitives 位于 platforms_deepsea:: 下）。JXC 的驱动命名空间根本没有 isa。重新实现者在接线 JXC 时必须在 compiler-base 命名空间中寻找 ISA，而不是在 JXC 驱动家族下寻找。这也是 jxc::jellyfish 和 jxc::dragonfish 不作为命名空间存在的原因：codename-specific 的驱动状态位于 *_performance_counters 和 *_trace_entry，而 codename-specific 的编译器状态是 xla::jellyfish::JellyfishTarget / DragonfishTarget。

子核心与 Codec / Bundle ISA 层

对于 compiler-backend 重新实现，最重要的子核心是拥有片上 bundle ISA 的那个。对于拆分家族，这是逐子核心的 isa 命名空间，其核心类型是 TensorCoreBundleCompact（codec 编码和解码的打包指令 bundle）：

子核心 ISA	存在的 bundle-compact 类型	Token 计数
`pxc::pfc::isa`	`BarnaCoreChannelBundle`, `VectorBase`	46K
`vxc::vfc::isa`	SparseCore Scs/Tac bundle types	69K
`gxc::glc::isa`	`TensorCoreBundleCompact` (Ghostlite/v4)	294K
`gxc::gfc::isa`	`TensorCoreBundleCompact` (6acc60406/v5)	270K

每个版本的 codec 都排他地绑定到一个子核心 ISA。TpuCodecGhostlite codec 只分派到 gxc::glc::isa（加上命名的 ghostlite::isa::EncoderGl* worker）；匿名 v5 codec 只分派到 gxc::gfc::isa；TpuCodecViperfish codec 绑定到 vxc::vfc/vlc 和 viperfish::isa。这种排他绑定是 codename ↔ sub-core 映射最可靠的符号级证据，因为 codec 方法是已解码的函数体，而不是启发式推断。

注意 — TensorCoreBundleCompact 同时出现在 gxc::gfc::isa 和 gxc::glc::isa 下（且不在共享 gxc::isa 下），这正是将 GXC 的 ISA 固定到子核心层级的证据。两个 GXC codec 的 bundle 编码即便在 bit 层面也不同：Ghostlite 使用 7-bit opcode 和 4-bit per-slot predicate，6acc60406 将 opcode 扩到 8 bits 并把 per-slot predicate 缩为 2-bit dual form；因此单一共享 GXC ISA 会是错误的，这两个子核心 ISA 确实是不同的世代。bit-level delta 见 GXC 家族。

四个家族概览

下表把每个家族与其拆分状态、子核心、ISA 放置位置、DMA 模型和 HAL 产品关联起来。这是合并后的跨家族视图，四个单独页面也各自从自身角度呈现了这些内容。

轴线	JXC	PXC	VXC	GXC
Codenames	Jellyfish, Dragonfish	Pufferfish	Viperfish	Ghostlite, 6acc60406
TpuVersions	0, 1	2	3	4, 5
Fetch/load 拆分	none（融合）	`pfc`/`plc`	`vfc`/`vlc`	`gfc`/`glc`
Factory class	`TpuHalJxcHardwareFactory` (anon)	`TpuHalPxcHardwareFactory` (anon)	`TpuHalVxcHardwareFactory` (global)	none — 使用 VXC factory
Factory vtable	0x215fe530	0x216085c8	0x21cabf70	（VXC 的 0x21cabf70）
HAL impl size	208 B	208 B	216 B	216 B（VXC 的）
ISA 放置位置	`platforms_deepsea::jellyfish::isa`（compiler-base）	家族 + 子核心	家族 + 子核心	仅子核心
DMA 模型	独立 `JfDmaIssuer`	位于 `TpuPxcDriver` 中	位于 `TpuVxcDriver` 中	位于 `TpuVxcDriver` 中
DMA 描述符	V1 (32 B)	V2 (≥96 B)	V2	V2
TensorCore	yes	yes	yes	yes
BarnaCore	yes	yes（最后一代）	no	no
SparseCore	no	no	yes（第一代）	yes
`profiler::TraceEntry`	none	家族级	逐子核心	逐子核心

注意 — 这张表在每个轴线上都呈现出清晰的世代推进：fetch/load 拆分、V2 DMA 描述符、DMA-in-driver 都在 PXC 一起到来；SparseCore 到来与 BarnaCore 退场都发生在 VXC；ISA 放置位置则持续向内迁移（仅 compiler-base → 家族 + 子核心 → 仅子核心）。HAL-impl size 是唯一例外：三个家族为 208 B，只有 VXC/GXC 为 216 B，纯粹因为这两个需要单个 +0xD0 slice-builder flag。

家族名称的由来

四个家族标签（jxc、pxc、vxc、gxc）遵循 _xc 后缀约定，首字母关联到该家族的“主”codename 或核心类别：

JXC — Jellyfish；该家族以第一个 codename 命名，融合核心引擎是 jfc（Jellyfish core）。
PXC — Pufferfish；它服务的单个 codename；核心 pfc/plc 是 Pufferfish-fetch / Pufferfish-load。
VXC — Viperfish；主 codename；核心 vfc/vlc 是 vector-fetch / vector-load。
GXC — General；这是唯一一个标签不是 codename 的家族。其核心 gfc/glc 是 general-fetch / general-load，并且它承载两个 codename（Ghostlite、6acc60406），而不是以其中一个命名。这个抽象与 GXC 没有自己的 factory 一致：它是叠加在 VXC HAL 之上的 “general” 扩展家族。

怪癖 — GXC 中的 g 表示 “general”，不是 “Ghostlite”。如果重新实现者把 gfc 读成 “Ghostlite-fetch-core”，就会错误配对 codename：Ghostlite 是 load-core（glc），而 fetch-core（gfc）是 6acc60406。general-vs-codename 命名正是说明 GXC 是扩展家族而非独立家族的结构性线索。

证据方法

该分类从 IDA *_functions.json 导出中恢复出来，依据是符号名及其反编译函数体，而不是任何单个反编译函数。每个驱动命名空间都以 Itanium-mangled 形式出现为 asic_sw6driver7deepsea3<famlen><fam>3<sublen><sub>...（例如 deepsea3gxc3glc3isa 表示 asic_sw::driver::deepsea::gxc::glc::isa）。上表中的计数是整个导出中每个 length-prefixed token 的原始出现次数（因此它们随命名空间被引用的密集程度缩放，而不是随 distinct-symbol 数量缩放；二进制自身符号表更稀疏，例如 gxc::glc::isa 的 demangled-symbol 计数约为 68K，而 token 出现次数为 294K）。检查 token 后面紧跟的字符可以区分真实子命名空间和只是更长类型名前缀的 token。这就是证明 JXC bcs/brn/hbm/hib/ici “命名空间”其实是 *_trace_entry 类型名前缀的方法，也证明了家族级 gxc::isa 的缺失（deepsea3gxc3isa → 零匹配）。

重新实现备注

关注点	指引
建模 JXC	每核心一条融合 pipeline；无 load-core；DMA 通过独立 `JfDmaIssuer` 对象；ISA 位于 `platforms_deepsea::jellyfish::isa`
建模 PXC/VXC	每核心两个子核心（fetch + load）；家族级 `isa`；DMA 折入驱动；V2 描述符
建模 GXC	两个子核心，ISA 只位于子核心下；复用 VXC HAL 产品链；Ghostlite=glc，6acc60406=gfc
Profiler	预期 PXC（家族）、VFC、VLC、GFC、GLC 有统一 `TraceEntry` 类；JXC 使用逐引擎 `*_trace_entry` 类型
Codename ↔ sub-core	使用上方已验证表；不要从版本号推断 fetch 与 load

交叉引用

Part IV 概览 — Silicon & Codename hub；fetch/load 拆分在 TpuVersion 分派模型中的位置
JXC 家族 — 融合数据流家族；无拆分基线和 platforms_deepsea::jellyfish::isa
PXC 家族 — fetch/load 拆分的起点；pfc/plc；家族级 ISA 和 profiler
VXC 家族 — vfc/vlc；第一个 SparseCore 家族；逐 codename 的 InitializeDrivers switch
GXC 家族 — gfc/glc；逐子核心 ISA；Ghostlite/6acc60406 codename 配对
HAL 家族 — 四个家族共享的 TpuHalFactory base chain
Codename 矩阵 — 6-value TpuVersion enum 和 HAL routing

子核心分类（GFC/GLC/JXC/PXC/VFC/VLC） ​

摘要 ​

Fetch/Load 拆分演进 ​

融合时代（JXC） ​

拆分时代（PXC → VXC → GXC） ​

子核心与 Codec / Bundle ISA 层 ​

四个家族概览 ​

家族名称的由来 ​

证据方法 ​

重新实现备注 ​

交叉引用 ​