XEvent 元数据 ID

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

摘要

设备或主机时间线上的一个 XEvent 本身不携带名称——它携带的是一个 int64 metadata_id，该值作为键进入其 XPlane 的 event_metadata 映射（map<int64, XEventMetadata>）。本页是该映射解析出的名称目录：也就是 libtpu 为它能够发出的每个 trace point 和每个主机作用域注册的、已驻留的 XEventMetadata.name 字符串。这是参考目录，不是算法页面——分配 id 的 builder 以及四层对象模型归 XPlane / XStat / TraceMe Emission 所有，设备 trace-point → event-name 的翻译归 TraceEntry → XEvent/XStat 所有。配套的 stat 字典（XStatMetadata，即每个事件的注解）位于 XStat Metadata IDs。本页只负责事件名称字典。

支配整个目录的唯一事实是：XEvent 元数据 id 不是全局类型编号——它是每个 plane 内部的驻留键。 /device:TPU:0 上的整数 7 和 /host:0 上的整数 7 表示不同事件，因为每个 XPlane 都会在采集时构建自己的 event_metadata 映射。消费者必须读取该 plane 的字典来解析任何 id；不存在跨 plane 的 id 命名空间。因此，本目录分为两个半区，它们采用两种不同的 id 分配机制。设备 plane 事件由一个静态、线缆稳定的硬件枚举播种：每个芯片家族的 TraceEntries.TracePointId 值（按 0–255 分带，中间有空洞）被写入硬件环形缓冲区的 TraceHeader.trace_point_id，其枚举值的字符串成为 XEventMetadata.name。主机 plane 事件则是动态按名称驻留的：tsl::profiler::TraceMe 标签流经 XPlaneBuilder::GetOrCreateEventMetadata(string_view)，它对标签求哈希，并在首次出现时分配下一个空闲的 plane-local id。

因此，设备半区可以按其来源枚举建立目录。共有五个按芯片划分的 TraceEntries.TracePointId 枚举（每个硅片家族一个），分别包含 99/122/78/135/144 个值；它们在各代之间重新分带，而不是严格追加。主机半区只能按名称建立目录——整数是 tsl 构建细节（HostEventType），不是线缆契约——因此本页按已确认的 ASCII 标签列出主机事件。下面两个半区都按 profile 消费者在时间线上看到的横切类别分组：TensorCore sequencer / compute、DMA & memory transfer、sync & fence、control & instrumentation、collective substrate、throttle & power、SparseCore，以及 host-scope band。

本页重建的目录覆盖：

两种 id 机制——静态的 TracePointId 枚举播种设备名称，与动态按名称驻留的主机名称，以及为什么 id 只有相对于其 plane 才有意义。
设备事件名称字典——每个 TraceEntries.TracePointId band、它贡献的枚举值字符串，以及逐家族差异（UHI→HDE、BarnaCore→SparseCore、不断增长的 throttle band）。
主机事件名称字典——按名称驻留的已确认 TraceMe 标签（TpuExecuteOp、InfeedEnqueueTuple、MegaScale:…、TpuCompile，……）。
类别分类法——每个 band 如何映射到 compute / memory / sync / control / collective / throttle / SparseCore，以及每类的代表性事件名称。


事件名称来源字段	`XEventMetadata.name`（xplane.proto 字段 2），由 `XEvent.metadata_id` 作为键
设备 id 机制	静态——`TraceEntries.TracePointId` 枚举值字符串
主机 id 机制	动态——`GetOrCreateEventMetadata(string_view)` 名称驻留
设备芯片家族	5——pxc, vfc, vlc, glc, gfc
设备事件数量	99 / 122 / 78 / 135 / 144（pxc/vfc/vlc/glc/gfc）
TracePointId 值范围	按 0–255 分带并带有保留空洞；哨兵 `255`（仅 pxc）
设备 builder	`xprof::TpuXPlaneBuilder` / `TpuXLineBuilder::AddEvent`
主机 builder	`tsl::profiler::XPlaneBuilder::GetOrCreateEventMetadata`

**注意——**本页设备表中的 id 是 TraceEntries.TracePointId 枚举值（由硬件写入、线缆稳定的整数），不是序列化 XSpace 实际携带的 plane-local XEvent.metadata_id。profiler 在采集时会把枚举值映射到一个新驻留的 plane-local id；枚举值才是稳定契约，元数据 id 则按 plane 派生。当某行写着“id 81”时，指的是该家族上 TCS_INTERNAL_SET_SYNC_FLAG 的枚举值，也就是硅片写入的东西——参见 XPlane / XStat / TraceMe Emission §How a Device Trace-Entry Becomes an XEvent。

类别	pxc	vfc	vlc	glc	gfc	id 来源
Compute / TensorCore-seq（TCS, BarnaCore, SC tasks）	11+29	11	11	12	12	TracePointId
Memory / DMA（UHI/HDE, OCI, CMQ/VDQ, CMN/CMNUR, O2CUR）	48	76	54	70	73	TracePointId
Sync / fence（TCS sync flags, SC barriers）	8	8	8	14	14	TracePointId
Control / instrumentation（tracemark, interrupt, fence）	~9	~6	~3	~9	~9	TracePointId
Collective substrate（ICI packet, ICR DMA）	9	9	9	9	9	TracePointId
Throttle / power（+ FLL, SPI sampler）	1	7	7	9	25	TracePointId
SparseCore band（SC instruction/task/stream/message）	—	18	—	18	18	TracePointId
Perf-counter sampling（STATS_COUNTER）	—	—	—	—	6	TracePointId
Host scope band（TraceMe labels）	dynamic, name-interned（在 host planes 间共享）					name intern

事件名称如何解析

目的

在目录之前，先说明解析规则，因为正是它让本目录可用。每个想为 XEvent 取得人类可读名称的消费者都会执行同样的两步查找；重新实现者如果跳过它，就会给每个事件贴错标签。

查找过程

text

XEvent.metadata_id  ──(key)──▶  XPlane.event_metadata[ id ]  ──▶  XEventMetadata.name
                                 (map<int64, XEventMetadata>          (the human string;
                                  on THIS plane only)                  for device events, the
                                                                       TracePointId enum string)
```text

该映射是 per-plane 的。同一个逻辑事件在 `/device:TPU:0` 和 `/device:TPU:1` 上驻留时，会在各自 plane 的映射中得到独立分配的 id，因此离开拥有它的 plane，id 没有意义。这就是为什么下面的设备表以*硬件* `TracePointId` 枚举值（稳定）为键，而不是以元数据 id（不稳定）为键。

### 两种机制并排对照

| | 设备 plane | 主机 plane |
|---|---|---|
| Plane 名称 | `/device:TPU:<n>` | `/host:<n>`, `XLA Modules`, `XLA Ops`, `Steps` |
| 名称来源 | `TraceEntries.TracePointId` 枚举值字符串 | `tsl::profiler::TraceMe` 标签 |
| Id 分配 | 静态枚举 → 名称 → per-plane 驻留 id | 动态：哈希标签，下一个空闲 plane-local id |
| Builder | `xprof::TpuXPlaneBuilder` / `TpuXLineBuilder::AddEvent` | `tsl::profiler::XPlaneBuilder::GetOrCreateEventMetadata` |
| 载荷（`XEventMetadata.metadata`） | 序列化的 `TraceEntry` variant blob | 通常为空 |
| 置信度 | CERTAIN（枚举字符串已在 `.rodata` 中按字节确认） | CERTAIN（标签已按字节确认） |

> **怪癖——**设备 `TraceEntry` oneof 的*字段编号*（2..N，密集且连续）与 `TracePointId` 的*枚举值*（按 0–255 分带）属于不同 id 空间。二者都存在于 `trace_entries.proto` 中，并且共享声明顺序，但只有枚举值会被硬件写入 `TraceHeader.trace_point_id`，也因此会成为事件名称。若重新实现按 protobuf 字段 tag 给事件建键，会给每个设备事件命错名。下面目录表携带的是枚举值；字段 tag 是 [TraceEntriesCoder](trace-entries-coder.md) 中记录的线缆编码实现细节。

---

## TensorCore Sequencer 与 Compute 事件

### 目的

硬件不会把 matmul 或 convolution 命名为 trace point——这些是 HLO op，会通过动态名称驻留出现在 *XLA Ops* plane 上，而不是通过 `TracePointId` 出现。设备上的 compute *进展* 是通过 TensorCore Sequencer（TCS）指令流 band、BarnaCore FSM band（仅 pufferfish）以及 SparseCore task/stream band（viperfish 起）间接观察到的。本节列出与 compute 相邻的 TCS 和 BarnaCore 名称；SparseCore band 在下方有单独章节。

### TensorCore Sequencer（TCS）band——ids 80–100

TCS band 存在于每个家族中，并且是目录中最稳定的部分。Ids 在各代之间几乎恒定；一个名称发生变化（从 viperfish 起 `HOST_INTERRUPT` → `CORE_INTERRUPT`），glc/gfc 在 97–100 追加 OCI-completion 和 PPM ids。

| TracePointId 值 | 名称 | 类别 | 家族 |
|---|---|---|---|
| 80 | `TCS_EXTERNAL_SYNC_FLAG_UPDATE_DMA_DONE` | sync | all |
| 81 | `TCS_INTERNAL_SET_SYNC_FLAG` | sync | all |
| 82 | `TCS_INTERNAL_ADD_SYNC_FLAG` | sync | all |
| 83 | `TCS_INTERNAL_HOST_INTERRUPT` (pxc) / `TCS_INTERNAL_CORE_INTERRUPT` (vfc+) | control | all |
| 84 | `TCS_INTERNAL_SET_TRACEMARK` | control | all |
| 85 | `TCS_INTERNAL_TRACE_INSTRUCTION` | control | all |
| 86 | `TCS_INTERNAL_UNSUCCESSFUL_SYNC_ATTEMPT` | sync | all |
| 87 | `TCS_INTERNAL_SUCCESSFUL_SYNC_ATTEMPT` | sync | all |
| 88 | `TCS_INTERNAL_READ_SYNC_FLAG` | sync | all |
| 89 | `TCS_INTERNAL_SCALAR_FENCE_START` | sync | all |
| 90 | `TCS_INTERNAL_SCALAR_FENCE_END` | sync | all |
| 91–96 | `OCI_DESCRIPTOR_*_ISSUED_FROM_TCS` / `OCI_MESSAGE_ISSUED_FROM_TCS` / `OCI_COMMON_*_COMPLETED_IN_TCS` | memory | all |
| 99 | `TCS_PPM_ENTRY_PPM_UPDATE_EVENT` | throttle | glc/gfc |
| 100 | `STATS_COUNTER_SAMPLE_ISSUED_FROM_TCS` | perf-sample | gfc |

> **注意——**`TCS_INTERNAL_TRACE_INSTRUCTION` (85) 和 `TCS_INTERNAL_SET_TRACEMARK` (84) 是设备目录中最接近“compute step”标记的项：它们包围已插桩的指令跨度，消费者会将其与 HLO ops 对齐。实际的 matmul/conv 身份稍后由 HLO 符号化器（`TpuXPlaneSymbolizer::SetEventMetadataFromSymbol`）提供，它会填充 `display_name` 和 HLO source stats——参见 [TraceEntry → XEvent/XStat](trace-entry-to-xevent.md)。

### BarnaCore FSM + sequencer band——ids 100–134（仅 pufferfish）

Pufferfish 携带一个 29 事件的 BarnaCore band，后续家族都没有；从 viperfish 起它被 SparseCore band 取代。FSM channel-controller ids（100–115）是一组 16 深的编号家族；具名 compute 和 sequencer-control 事件是更值得关注的行。

| TracePointId 值 | 名称 | 类别 |
|---|---|---|
| 100–115 | `BC_FSM_CHANNEL_CONTROLLER0` … `CONTROLLER15` | compute FSM |
| 116 | `BC_FSM_PROCESS_HOSTID` | compute |
| 117 | `BC_FSM_SPARSE_REDUCE` | compute |
| 118 | `BC_FSM_PROCESS_BCID` | compute |
| 119 | `BC_FSM_CONCAT` | compute |
| 120 | `BCS_TRACE_INSTRUCTION` | control |
| 121 | `BCS_SET_TRACEMARK` | control |
| 122 | `BCS_SYNC_START_STOP_TRACE` | sync |
| 123 | `BCS_HOST_INTERRUPT` | control |
| 124 | `BCS_FENCE` | sync |
| 125–134 | `BC_OCI_{READ,WRITE}_{REQUEST,RESPONSE}` / `OCI_DESCRIPTOR_*_ISSUED_BY_BC` / `OCI_MESSAGE_{RECEIVED,SENT}_BY_BC` | memory |

---

## DMA 与内存传输事件

### 目的

按事件数量计算，这是最大的类别。每个 host↔chip 传输、on-chip-interconnect 描述符生命周期、VPU↔scratchpad DMA、以及 HBM-controller 请求，都是这里的 trace point。该 band 也是各代之间架构调整最多的部分：host-DMA 前端从 UHI（pufferfish）迁移到 HDE（viperfish 起），VPU-DMA 引擎从 CMQ（pufferfish）变为 VDQ（viperfish-lite）再到无，memory-network controller 层级（CMN/CMNUR/CMNDE）和地址翻译 DMA（O2CUR）只出现在较新的芯片上。

### Host-DMA 前端

| 家族 | Band ids | 名称（代表性） |
|---|---|---|
| pxc (UHI) | 0–10 | `UHI_HOST_DMA_TRANSACTION_STARTED_ADDRESS_TRANSLATION`, `UHI_HOST_PHYSICAL_{REQUEST,RESPONSE}_{READ,WRITE}`, `UHI_OCI_REQUEST_{READ,WRITE}`, `OCI_*_BY_UHI_*` |
| vfc/vlc/glc/gfc (HDE) | 8–14 (glc) / 1–14 (gfc) | `HDE_HOST_REQUEST_WRITE`, `HDE_HOST_RESPONSE_WRITE`, `HDE_HOST_REQUEST_READ`, `HDE_HOST_RESPONSE_READ`, `OCI_COMMON_HDE_{READ,WRITE}_REQUEST`, `OCI_MESSAGE_SENT_BY_HDE` |

### OCI 引擎描述符 / 消息生命周期——主导 band

on-chip-interconnect（OCI）描述符和消息生命周期是 memory 类别中最大的单一贡献者——pxc 上 32 个事件，glc 上最多 54 个。名称遵循 `OCI_<phase>_<verb>_<location>` 语法（`OCI_DESCRIPTOR_DESC_AT_QNM`, `OCI_COMMON_READ_CMD_ISSUED_FROM_ENGINE`, `OCI_MESSAGE_MSG_ISSUED_FROM_QNM`）。由于该 band 是从描述符/消息 FSM 机械生成的，而不是手工命名的，因此用其语法描述比逐行倾倒更合适。

| 轴 | 值 | 来源 |
|---|---|---|
| phase prefix | `OCI_DESCRIPTOR`, `OCI_GENERIC`, `OCI_COMMON`, `OCI_MESSAGE`, `OCI_WRITE_REQ` | enum string prefix |
| verb | `ISSUED_FROM`, `ENQUEUED_AT`, `RECEIVED_BY`, `SENT_BY`, `ACCEPTED_AT`, `COMPLETED_IN`, `GENERATED_IN`, `DESC_AT` | enum string body |
| engine/location | `ENGINE`, `QNM`, `MN`, `TCS`, `BC`, `SC`, `MGR`, `CMNDE`, `ICR_{EGRESS,INGRESS}_DMA`, `UHI/HDE_BRIDGE` | enum string suffix |
| 代表 ids (pxc) | 20–27 (engine), 49–55 (ICR/command), 91–96 (TCS-issued), 129–134 (BC-issued) | TracePointId |
| 代表 ids (glc) | 20–27 (engine), 91–96 (TCS), 124–130 (SC), 161–167 (MGR) | TracePointId |

重新实现者可从 `trace_entries.proto` 的嵌套枚举重建完整的逐家族列表；携带明确语义（真正的命令发出、完成、跨引擎交接）的行就是上面这些。已逐字确认的具名锚点：`OCI_COMMON_OCI_READ_COMMAND`（pxc 55）、`OCI_MESSAGE_PACKET_SENT_TO_OCI`（pxc 52）、`OCI_DESCRIPTOR_DESC_AT_QNM`（pxc 20）。

### VPU / scratchpad DMA——CMQ（pxc）和 VDQ（vlc）

| 家族 | Band ids | 名称家族 |
|---|---|---|
| pxc (CMQ) | 140–149 | `CMQ_VPU_DMA_DESC`, `OCI_MESSAGE_CMQ_VPU_DMA_MSG`, `CMQ_VPU_DMA_REQ_{VMEM0,VMEM1,CMEM}_TO_{CMEM,VMEM0,VMEM1}_{READ,WRITE}`（8 个方向） |
| vlc (VDQ) | 142–149 | `VDQ_TRANSACTION_{READ,WRITE}_{REQ,RESP}_CHAN0/1`（8 个事件） |

> **怪癖——**CMQ band 的枚举字符串会*同时命名两个端点和方向*（`VMEM0_TO_CMEM_READ` vs `CMEM_TO_VMEM1_WRITE`），因此 142–149 这八个 ids 完整枚举了 {VMEM0,VMEM1}×{read,write}×{to-CMEM,from-CMEM} 的笛卡尔积。若重新实现把它们折叠为单个“VPU DMA”事件，就会丢失时间线渲染所需的源/目标 scratchpad 身份。

### Memory-network controller & HBM（glc/gfc）以及地址翻译（gfc）

| 家族 | Band ids | 名称家族 | 类别 |
|---|---|---|---|
| vfc/glc/gfc | 70–79 | `OCI_DESCRIPTOR_COMMON_RECEIVED_BY_CMNDE`, `OCI_MESSAGE_SENT_BY_CMNDE`, `CMN_DMA_REQUEST_{EAST,WEST}_SIDE_LANE0..3` | memory |
| glc/gfc | 170–173 | `CMNUR_HBMC_{RD_REQ,RD_RSP,WR_REQ,WR_RSP}`（HBM controller） | memory |
| glc/gfc | 174–185 | `CMNDE_CMNUR_{SRC,DST}_{REQ,RSP}`, `OCI_CMNUR_{RD,WR}_{REQ,RSP}`, `CMNUR_CMNUCB_CONTROL_*` | memory |
| gfc | 183–188 | `O2CUR_L2P_{WR_REQ_FIRST,WR_RSP_LAST,RD_REQ,RD_RSP}`, `CMNDE_UR_L2P_DMA_{REQ,RSP}`（logical→physical addr translation） | memory |

---

## Sync 与 Fence 事件

### 目的

Semaphore、barrier 和 fence 操作。在所有家族中，这是 TCS sync-flag 子 band（已在上面的 TensorCore Sequencer 中列出，ids 80–90）；从 viperfish 起，SparseCore instruction band 额外加入了一组明确且更丰富的 barrier/sync/sfence start-stop 对，旧硅片没有暴露这些事件。

### Sync 词汇表

| 层 | 名称 | Ids | 家族 |
|---|---|---|---|
| TCS sync flags | `TCS_EXTERNAL_SYNC_FLAG_UPDATE_DMA_DONE`, `TCS_INTERNAL_{SET,ADD,READ}_SYNC_FLAG`, `TCS_INTERNAL_{SUCCESSFUL,UNSUCCESSFUL}_SYNC_ATTEMPT`, `TCS_INTERNAL_SCALAR_FENCE_{START,END}` | 80–90 | all |
| SparseCore fences/barriers | `SC_INSTRUCTION_SFENCE_{START,STOP}` (111/112), `SC_INSTRUCTION_SYNC_{START,STOP}` (113/114), `SC_INSTRUCTION_BARRIER_{START,STOP}` (115/116), `SC_INSTRUCTION_SYNC_WATCH_{START,STOP}` (117/118) | 111–118 | vfc/glc/gfc |
| BarnaCore (pxc) | `BCS_SYNC_START_STOP_TRACE` (122), `BCS_FENCE` (124) | 122/124 | pxc |

> **注意——**sync 事件以 `_START`/`_STOP`（或 `_SUCCESSFUL`/`_UNSUCCESSFUL`）成对出现，因为时间线会把一次 sync attempt 渲染为持续时间跨度，而不是一个点。消费者会在同一 line 上用下一个匹配的 stop id 与 start id 配对，并使用 `sync_flag_id`/`sync_flag_number` stat（[XStat Metadata IDs](xstat-metadata-ids.md)）来消除并发 flag 的歧义。unsuccessful/successful 的拆分让 UI 能以不同颜色显示一个停滞的 sync 和一个立即完成的 sync。

---

## Control 与 Instrumentation 事件

### 目的

这些事件标记 instrumentation stream 本身——插入 tracemark、trace-instruction span，以及 host/core interrupt。它们不是 workload 事件；它们是 profiler 用来将硬件时间与软件意图对齐的脚手架。

| 名称 | Id (pxc) | Id (glc/gfc) | 子系统 |
|---|---|---|---|
| `TCS_INTERNAL_SET_TRACEMARK` | 84 | 84 | TCS |
| `TCS_INTERNAL_TRACE_INSTRUCTION` | 85 | 85 | TCS |
| `TCS_INTERNAL_HOST_INTERRUPT` / `..._CORE_INTERRUPT` | 83 | 83 | TCS |
| `SC_INSTRUCTION_CORE_INTERRUPT` | — | 108 | SparseCore |
| `SC_INSTRUCTION_SET_TRACEMARK` | — | 109 | SparseCore |
| `SC_INSTRUCTION_TRACE_INSTRUCTION` | — | 110 | SparseCore |
| `BCS_TRACE_INSTRUCTION` / `BCS_SET_TRACEMARK` / `BCS_HOST_INTERRUPT` | 120/121/123 | — | BarnaCore |

> **怪癖——**interrupt 事件跨代改名（pufferfish 上是 `HOST_INTERRUPT`，从 viperfish 起是 `CORE_INTERRUPT`），但保持*同一个枚举值*（83）。id 是稳定契约；字符串不是。按枚举值切换的消费者看到的是一个事件；按名称字符串切换的消费者必须处理两种拼写。这是设备目录的一般规则——ids 线缆稳定，名称可能重新拼写。

---

## Collective Substrate 事件（ICI）

### 目的

Collective 有两个视图。*语义*视图（`AllReduce`, `AllGather`, `ReduceScatter`, …）是一个主机 `TraceMe` 标签，列在下面的主机章节中。*物理*视图是 inter-chip-interconnect（ICI）packet band——也就是硅片写入的实际链路级 packet rx/tx/queue/inject 事件。ICI band 在所有五个家族中的形状相同（9 个事件，ids 40–48，再加上 ICR-DMA bridge 事件 43–53），因为链路层没有变化。

| TracePointId 值 | 名称 |
|---|---|
| 40 | `ICI_PACKET_PACKET_RECEIVED_ON_LINK_INPUT` |
| 41 | `ICI_PACKET_PACKET_TRANSMITTED_ON_LINK_OUTPUT` |
| 42 | `ICI_PACKET_PACKET_QUEUED_FOR_LINK_TRANSMISSION` |
| 43–46 | `ICI_PACKET_{CONTROL,DATA}_PACKET_{INJECTED,RECEIVED}_BY_ICR_DMA_BRIDGE` |
| 47–48 | `ICI_PACKET_{CONTROL,DATA}_PACKET_QUEUED_FOR_LOCAL_INGRESS` |
| 49–53 | `OCI_DESCRIPTOR_ENQUEUED_IN_ICR_EGRESS_DMA`, `OCI_MESSAGE_GENERATED_IN_ICR_{EGRESS,INGRESS}_DMA`, `OCI_MESSAGE_PACKET_{SENT_TO_OCI,RECEIVED_IN_ICR}` |

> **注意——**link layer 事件携带 `router_link_port_id ∈ {LINK0..LINK5}` 和 `virtual_channel` stats，因此即使 band 本身没有命名任何 collective，消费者也能从该 band 重建 per-link、per-VC 带宽。这些物理 packet 到语义 `AllReduce` span 的映射，是在主机侧通过将 `MegaScale:` TraceMe scope 的时间窗口与其中的 ICI traffic 相关联完成的——两个视图通过时间连接，而不是通过共享 id 连接。

---

## SparseCore 事件

### 目的

从 viperfish 起，sparse/embedding compute 从 pufferfish 的 BarnaCore FSM 迁移到专用 SparseCore（SC），它带有自己的 sequencer（SCS）、tile（SCT）和 crossbar（XBAR）。SC instruction/task/stream/message band（18 个事件，ids 108–135）就是它的 trace surface。control 和 sync 子 band 已经在上面列出；本节列出表示 SparseCore *进展*的 task/stream/message 名称。

| TracePointId 值 | 名称 | 类别 |
|---|---|---|
| 119 | `SC_TASK_ISSUE_FROM_SCS` | compute |
| 120 | `SC_TASK_COMMIT_ON_SCT` | compute |
| 121 | `SC_STREAM_ISSUE_FROM_CORE` | compute |
| 122 | `SC_STREAM_PROGRESS_XBAR` | compute |
| 123 | `SC_STREAM_PROGRESS_CMN` | compute |
| 131 | `SC_MESSAGE_OUTBOUND_INTERNAL_MESSAGE` | memory/msg |
| 132 | `SC_MESSAGE_INBOUND_INTERNAL_MESSAGE` | memory/msg |
| 124–130 | `OCI_DESCRIPTOR_*_ISSUED_BY_SC`, `OCI_MESSAGE_{RECEIVED,SENT}_BY_SC` | memory |
| 129/134/135 | `STATS_COUNTER_SAMPLE_ISSUED_FROM_{SCS,SCTD,SCTC}` | perf-sample |

> **注意——**`SC_TASK_ISSUE_FROM_SCS` → `SC_TASK_COMMIT_ON_SCT` 包围一个 SparseCore task 从 issue 到 commit 边界的生命周期，三个 `SC_STREAM_PROGRESS_*` ids 标记它穿过 crossbar（XBAR）和 memory network（CMN）的移动。这些事件展示 profile 中 SparseCore op 的流水线占用；它们是 TCS instruction-stream 事件在 SparseCore 上的对应物。

---

## Throttle 与 Power-Management 事件

### 目的

这是目录中增长最快的 band，也是一级 trace 类别。Pufferfish 只有一个 throttle 事件；gfc 有二十五个（20 throttle + 2 SPI samplers + 3 FLL）。这种增长反映了新版硅片的供电复杂度——cycle-skip 仲裁、PPM（peak-power-management）brake 边沿、LDIDT 电压跟踪，以及 frequency-locked-loop lock/select 都变得可观测。

| 家族 | 数量 | Band ids | 名称家族 |
|---|---:|---|---|
| pxc | 1 | 97 | `THROTTLE_STATE_THERMAL_AND_ELECTRICAL_THROTTLE_STATE` |
| vfc/vlc | 7 | 98–104 | `THROTTLE_CYCLE_SKIP_*`（7 事件家族，band 低于 glc） |
| glc | 7+2 | 200–206, 168–169 | `THROTTLE_CYCLE_SKIP_{THERMAL,EXT_BRAKE,EXT_THROTTLE,LDIDT_BRAKE,LDIDT_DROOP,ARBITRATION}`（200–205）, `THROTTLE_CYCLE_SKIP_PPM_SUSTAINED_AGGRESSIVE_BRAKE_RISING_EDGE`（206）, `SPI_SAMPLER_{VDD_CORE,HBM}_FRAME_EXEC`（168/169） |
| gfc | 20+3+2 | 200–222, 168–169 | glc set 重构 + PPM brake 笛卡尔积 `THROTTLE_CYCLE_SKIP_PPM_BRAKE_EVENT_{SUSTAINED,DIDT,OVERSHOOT}_{AGGRESSIVE,NOMINAL}`（206–211）, `THROTTLE_LDIDT_VOLTAGE_*`, `THROTTLE_MAX_VALUE_THROTTLE_MAX_{FAST,SLOW}`, `THROTTLE_MAXIMUM_TEMPERATURE_*`, `FLL_LOCK_FLL_{0,1}_LOCK`（220/221）, `FLL_SELECT_FLL_SELECT`（222） |

> **怪癖——**throttle band 在 glc/gfc 上位于*高* id 范围（glc 为 200–206，gfc 为 200–222），但在更早家族上位于*低*范围（97–104）——该 band 是被迁移了，而不是原地扩展。若重新实现假定所有芯片上的 throttle 事件都靠近 id 97，就会把每个 glc/gfc throttle 事件误分类为 memory 或 SparseCore。应按名称前缀（`THROTTLE_`, `FLL_`, `SPI_SAMPLER_`）建键，而不是按数字 band。

### Perf-counter sampling——STATS_COUNTER（仅 gfc）

最新家族新增了其他地方都没有的带内硬件 perf-counter sampling band：六个 `STATS_COUNTER_SAMPLE_ISSUED_FROM_{TCS,SCS,SCTD,SCTC,ICR_DATA,CMNUR}` 事件（ids 56, 100, 129, 134, 135, 182）。每个事件携带 `num_counters`、`payload_low/high`（uint64）和一个 `sample_id`——片上计数器会被采样并作为 trace 事件发出，而不是单独读出。

---

## 主机作用域事件（TraceMe Labels）

### 目的

`/host:<n>`、`XLA Modules`、`XLA Ops` 或 `Steps` plane 上的每个事件，都来自运行时线程上的一个 `tsl::profiler::TraceMe` RAII 作用域，而不是来自硬件。其名称是 TraceMe 标签字符串，由 `XPlaneBuilder::GetOrCreateEventMetadata(string_view)` 动态驻留。这些事件没有固定整数——提供 by-id 快路径的 `tsl` `HostEventType` 枚举是构建细节，尚未恢复。因此，目录按*名称*组织。下面所有名称都已在 `libtpu.so` 中逐字确认为 ASCII。

### Runtime execution & transfer

| 标签 | 作用 |
|---|---|
| `TpuExecuteOp` | 顶层设备执行作用域 |
| `DoEnqueueProgram` / `DoEnqueueContinuationProgram` | 将程序入队到设备队列 |
| `EnqueueRequestLocked` / `EnqueueProgram` / `ExecuteProgram` / `LoadProgram` / `RunHlo` | 队列提交与执行阶段 |
| `InfeedEnqueueTuple` / `InfeedEnqueue` / `WaitForInfeed` | infeed 路径 |
| `OutfeedDequeueTuple` / `OutfeedDequeue` / `WaitForOutfeed` | outfeed 路径 |
| `TransferBufferToDevice` / `TransferBufferFromDevice` / `TransferToDevice` / `TransferFromDevice` / `HostToDevice` / `DeviceToHost` / `Memcpy` | host↔device buffer 传输 |
| `InitializeTpu` / `StepInfo` / `SessionRun` / `ExecutorState::Process` | session/step 框定 |

### Compiler

| 标签 | 作用 |
|---|---|
| `TpuCompile` | TPU backend compile 作用域 |
| `XlaCompile` | XLA compile 作用域 |
| `CompileOp` / `JitCompile` | op/JIT compile 作用域 |

### Collective（语义视图）

| 标签 | 作用 |
|---|---|
| `MegaScale:` (prefix) | megascale transport scope prefix |
| `AllReduce` / `AllGather` / `ReduceScatter` / `SendRecv` / `collective-permute` | 语义 collective op 名称 |
| `MegaScaleAction` / `MegaScaleActionGraph` | megascale action-trace 作用域 |

> **陷阱——**这些标签是*按名称*驻留的，因此同一 plane 上两个带有相同标签的 TraceMe 作用域会共享一个 `XEventMetadata`（以及一个 id），而不同 plane 上的相同标签会得到新的 id。重新实现绝不能假定 `AllReduce` 有固定 id——它的 id 就是该 plane 上第一个 `AllReduce` 作用域被分配到的 plane-local id。名称是稳定的；id 明确不是。这与设备规则成对偶（设备 ids 稳定，名称可能重新拼写）。
>
> **注意——**TraceMe 标签可以在名称字符串中携带按 `name#k1=v1,k2=v2#` 编码的 key/value 元数据（`TraceMeEncode` 线缆格式，[XPlane / XStat / TraceMe Emission §Encode](xplane-xstat-traceme.md)）。第一个 `#` 之前的裸 `name` 会成为 `XEventMetadata.name`；`k=v` 对会成为事件上的 `XStat`，而不是事件名称的一部分。因此，`TpuExecuteOp#program_id=42#` 会把事件驻留为 `TpuExecuteOp`，并添加一个 `program_id` stat——目录名称始终是不带后缀的 base。

---

## 逐代目录差异

设备目录在数量上单调增长，但跨硅片代际会重新分带，而不是严格追加。下表总结每个家族新增或移除了什么；面向特定芯片的重新实现者可用它判断哪些 band 存在。

| 维度 | pufferfish (pxc) | viperfish (vfc) | viperfish-lite (vlc) | ghostlite (glc) | 6acc60406 (gfc) |
|---|---|---|---|---|---|
| total events | 99 | 122 | 78 | 135 | 144 |
| host-DMA band | UHI (7) | HDE (4) | HDE (4) | HDE (4) | HDE (4) |
| sparse compute | BarnaCore `BC/BCS/B7b2m` (29) | SparseCore `SC_*` (18) | none | `SC_*` (18) | `SC_*` (18) |
| VPU DMA | CMQ (9) | — | VDQ (8) | — | — |
| mem-net controller | — | CMN/CMNUR/CMNDE (20) | — | CMN/CMNUR/CMNDE (16) | + O2CUR (4) |
| throttle/power | 1 | 7 | 7 | 7 + SPI(2) | 20 + SPI(2) + FLL(3) |
| perf-counter sampling | — | — | — | — | `STATS_COUNTER` (6) |
| addr translation | — | — | — | — | `O2CUR_L2P` (4) |
| TCS interrupt name | `HOST_INTERRUPT` | `CORE_INTERRUPT` | `CORE_INTERRUPT` | `CORE_INTERRUPT` | `CORE_INTERRUPT` |
| dummy sentinel (id 255) | yes | no | no | no | no |

趋势是：host interface 统一到 HDE；sparse compute 从 BarnaCore 迁移到 SparseCore，并具备显式 barrier/sync-watch 语义；memory hierarchy 获得显式 network controller（CMNUR），并且在 gfc 上加入地址翻译（O2CUR）和带内 perf-counter sampling；power management 成为增长主力（1 → 20+ throttle events）。五个枚举位于二进制文件捆绑的 descriptor pool 中，地址分别为 `0xbef0d50`（pxc）、`0xbf06830`（vfc）、`0xbf28fd0`（vlc）、`0xbf41210`（glc）、`0xbf64c80`（gfc），每个都是其 `trace_entries.proto` 的 `TraceEntries.TracePointId` 嵌套枚举。

> **注意——**每个事件的*载荷*字段（随 `XEventMetadata.metadata` 携带的 `TraceEntry` variant message）没有在这里编目——那是每个事件的字节布局，归载荷页面所有（[uhi/oci/ici DMA](payload-uhi-oci-ici-dma.md)、[SC band](payload-sc-band.md)、[vfc/vlc/gfc](payload-vfc-vlc-gfc.md)）。本页只是 name→category 字典。

---

## 此处无法恢复的内容

- **主机事件整数 id。** `tsl` `HostEventType`/`StatType` 静态枚举值（`GetOrCreateEventMetadata(int64)` by-id 快路径）是在 `tsl` 构建时分配的，无法从字符串恢复——它们是实现细节，不是线缆契约。主机事件只按名称记录。（任何具体主机整数的置信度都是 LOW。）
- **实时 `XEventMetadata.metadata` 嵌入。** 已证明该字段携带序列化的逐家族 `TraceEntry`，但它存储的是完整 `TraceEntry`、只有 `TraceHeader`，还是重新编码的子集，尚未通过捕获的 `XSpace` 确认。（MEDIUM。）
- **Plane-local metadata-id 分配顺序。** 由于 ids 会在采集时按首次出现顺序驻留，某个事件在给定 `XSpace` 中得到的具体整数无法通过静态分析预测——只有名称以及（对设备事件而言）来源 `TracePointId` 枚举值是稳定的。

---

## 交叉引用

- [XPlane / XStat / TraceMe Emission](xplane-xstat-traceme.md)——驻留这些名称的 builder API（`GetOrCreateEventMetadata`）、四层对象模型，以及主机 `TraceMe` 捕获路径
- [TraceEntry → XEvent/XStat](trace-entry-to-xevent.md)——设备侧翻译：将硬件 `TracePointId` 映射为本页编目的事件名称
- [XStat Metadata IDs](xstat-metadata-ids.md)——配套的 *stat*（注解）字典，用于为每个事件属性定型；事件在这里，stats 在那里
- [Tracepoints Master Registry](tracepoints-master-registry.md)——支撑这里所总结 band 的完整逐家族 `TraceEntries.TracePointId` 枚举
- [TraceEntriesCoder](trace-entries-coder.md)——设备 codec，以及不同于枚举值 id 空间的 oneof field-tag id 空间
- [Profiling and Telemetry Overview](overview.md)——五阶段捕获流水线，以及这些事件填充的双来源（`/host` + `/device`）`XSpace`

XEvent 元数据 ID ​

摘要 ​

事件名称如何解析 ​

目的 ​

查找过程 ​

XEvent 元数据 ID

摘要

事件名称如何解析

目的

查找过程