tpunetd 关系
tpunetd 是每台主机上的 TPU 控制守护进程。它的职责只是在名称上与 Megascale 有重叠：tpunetd 处理切片内芯片和 fabric 设置，而 Megascale 的 MegaScaleTransport 处理跨切片地址表交换。 两者按顺序运行，并使用不同的 transport。
本页描述两者之间的数据流；关于 tpunetd 自身的内部机制，请参见 tpunetd 协议。
分层
text
+----------------------------------------------------------------+
| XLA Megascale Runtime |
| (xla::megascale::runtime::CommunicationBackend) |
| |
| DiscoverTopologyAndAddressBindings(slice_id, args, |
| host_id, num_slices) |
| │ |
| ▼ |
| GetMultiSliceTopology gRPC over MEGASCALE_PORT |
| Coordinator（每个作业一个进程） |
+──────────────────────────────────────────────────────────────────+
▲ 读取 tpu_topology_args (TpuTopologyArgsProto) 和
│ address_mapping (NetworkAddressMapping)，二者派生自
│ tpunetd 先前发布的芯片坐标
│
+──────────────────────────────────────────────────────────────────+
| tpunetd_client (superpod::tpunetd_client::TpunetdClient) |
| |
| TpunetdClient::Init |
| ConnectToTpunetd → Unix socket /var/google/services/... |
| SessionMaster::Create → 生成每 peer 的 SessionWorker |
| stub，通过此切片内的 TCP 通信 |
| |
| 发出的 RPC（libtpu 使用的子集）： |
| StartSession / StopSession / StatSession |
| CheckSessionHealth / GetChipCoordinates |
| GrantSessionPermission / GetCoreDump |
+──────────────────────────────────────────────────────────────────+
▼ gRPC over Unix socket
+──────────────────────────────────────────────────────────────────+
| tpunetd daemon（进程外，拥有芯片） |
| |
| ICI fabric 设置：CreateNetwork, UpdateTopology, |
| ConfigureIci, EnableIciDataLink, WaitForDataLinkUp |
| 路由表安装：SetRoutingTable |
| 全局时间计数器：SetGtcConfiguration, WaitForGtcReset |
| 芯片坐标分配：SetChipCoordinates, |
| SetGlobalChipId |
+──────────────────────────────────────────────────────────────────+
```text
## 序列：完整 Megascale 作业启动
依赖关系严格按 tpunetd → MegaScaleTransport 运行。runtime 通过在插件的
`do_init` 内对调用排序来强制这一顺序：
1. **tpunetd_client 连接。**
`TpunetdClient::Create(topology, TpuType, Options)` 后接
`TpunetdClient::Init(opts, retry_count)`，打开通向本地 tpunetd
守护进程的 Unix socket。
2. **Session 启动。** `SessionControl/StartSession`
（当 `--bypass_vbar_control_service=true` 时）或
`VBARControl/StartSession`（默认）注册此主机的芯片。
守护进程分配芯片坐标、编程 ICI 路由表、配置全局时间计数器、
拉起 ICI 数据链路，并在 session 就绪时回传信号。
3. **切片内 rendezvous（`tpunetd_client::BroadcastBarrier`）。**
`tpunetd_client::BroadcastBarrier` 类
（`BroadcastNotification` / `BroadcastWaitForReady`，由
`SyncWithTimeout` 门控）驱动
`superpod.tpunetd_client.proto.TpuNetworkSessionBarrier/Notify`
和 `.../WaitForReady` RPC，覆盖该切片中的每台主机。
这是一个点对点 barrier；tpunetd 本身不参与。
4. **TpuTopologyArgsProto 提取。** 切片内 rendezvous 完成后，
runtime 查询 `SessionControl/GetChipCoordinates` 以取得已分配坐标，
构造每切片的 `tpu::TpuTopologyArgsProto`（芯片维度、主机边界、
每进程边界、twist factors），并将其暂存。
5. **MegaScaleTransport 启动。** `CommunicationBackend::Create`
构造 backend；`transport_factory()` 生成 `GrpcTransport`；
`GrpcTransport::Init` 绑定 `MEGASCALE_PORT` 服务器。
协调器进程还会额外实例化 `TopologyCoordinator`。
6. **跨切片 rendezvous。**
`DiscoverTopologyAndAddressBindings(local_slice_id,
args /* from step 4 */, local_host_id, num_slices)` 运行。
这是本节其他页面记录的入口点。
7. **稳定状态。** Megascale 的 rendezvous 完成后，
`StartHeartBeat()` 在 `MegaScaleTransport` 上运行。runtime
随即准备好处理 PJRT 可执行文件启动；tpunetd 的
`SessionMaster::CheckSessionHeartbeat` 在 tpunetd transport
上并行运行。
不存在 Megascale 先于 tpunetd 启动的路径。
`enable_megascale_topology=false` 标志会完全绕过第 5/6 步
（单切片模式）；tpunetd 仍会运行。反向情况，即没有 tpunetd 的
Megascale，在该二进制中不会发生。
## 穿过边界的数据流
Megascale 请求（`GetMultiSliceTopologyRequest`，其 proto descriptor
位于文件偏移 `0xbf81634`）携带以下状态，其中两项派生自 tpunetd：
| `GetMultiSliceTopologyRequest` 的字段 | 派生自 tpunetd RPC |
|---|---|
| `tpu_topology_args`（字段 2，`tpu.TpuTopologyArgsProto`） | `SessionControl/GetChipCoordinates`，加上 runtime 中的本地 `TpuTopologyArgs` 构造（使用由 `SetChipCoordinates` 填充的芯片布局字段）。 |
| `address_mapping`（字段 1，`xla.megascale.runtime.NetworkAddressMapping`）：携带 `slice_id`、`host_id` 和 repeated `HostNetworkAddress` 条目（每个条目包含一个 `address` 字符串，以及 `interface_name`、`numa_node`、`host_name_for_debugging`）。 | 不直接来自 tpunetd：`address` 值来自受 `megascale_port` / `megascale_port_name` 标志控制的本地解析，但该绑定依赖 tpunetd 已分配 `slice_id` / `host_id` 芯片坐标，这些坐标决定主机使用哪个网络。 |
| `incarnation_id`（字段 3，int） | 进程本地；独立于 tpunetd。 |
协调器会对每个入站请求运行 `proto2::util::MessageDifferencer::Compare`
来验证 `tpu_topology_args` 字段（参见
[拓扑交换](topology-exchange.md)）。这意味着：如果同一切片中的两台主机
在完成 tpunetd 启动后拥有不同芯片坐标，就会在这个边界被检测出来，
即使 tpunetd 自身的 `StartSession` 本来是一致的。rodata `0x9b27486`
处的漂移警告就是为暴露这种失败模式之一而设计的。
## tpunetd 不做什么
- **不做跨切片地址交换。** tpunetd 是按主机运行的；它的 peer fanout
（`SessionMaster::ExecuteOnAllWorkers`）被限制在同一切片内的 peer。
多切片地址表属于 Megascale 的领域。
- **不做跨切片 barrier。** `BroadcastBarrier` 是每切片的；
多切片同步使用 `MegaScaleTransport.Barrier`。
- **不做 PJRT 集成。** tpunetd 对 JAX/TF 客户端不可见；
PJRT 与 libtpu 通信，libtpu 与 tpunetd 通信。客户端永远不会看到
`tpunetd.*` proto。
- **不支持非 Borg / 非 Cloud 路径。** `kTpunetdSupportedTpuVersions`
白名单将 tpunetd 限制在特定 TPU 世代；较旧的单主机设置会回退到
进程内 `SliceBuilder` 家族，后者有自己的每主机 rendezvous
（不同于 tpunetd 和 Megascale）。
## 运维影响
- **多切片 TPU pod 上操作员可见的启动日志：**
1. tpunetd_client 侧：`"Running in Cloud, using TpunetdClient"`
或 `"Creating tpunetdclient for worker ..."`。
2. tpunetd_client SessionMaster：peer 连接日志。
3. 每切片 barrier 完成（没有特定日志；`SessionMaster` 静默继续）。
4. CommunicationBackend ctor 侧：每进程 FLAGS 日志行。
5. 仅在协调器上：
`"Megascale Topology Coordinator started for <N>"`.
6. 每进程：周期性
`"MegaScale Topology Discovery in progress. Missing hosts..."`
直到完成。
7. 完成后：`"MegaScale Topology Discovery completed."`
- **卡住切片上操作员可见的失败：** 每切片的 tpunetd
`SessionMaster::CheckSessionHeartbeat` 最先注意到停滞主机；它会发出
`"Session is failing due to the following chips having zero as
chip id"`。如果该切片始终没有完成 tpunetd 启动，Megascale 的每主机请求
永远不会到达，协调器会在其周期性状态日志中报告缺失的切片。
因此，这两个系统提供互补诊断：tpunetd 看到每芯片失败；Megascale 看到每切片 /
每主机缺失。
## 交叉引用
- [tpunetd 协议](../tpunetd-protocol.md)：本页与 Megascale 关联起来的守护进程 wire surface
- [Bootstrap › 概览](overview.md)：tpunetd 依赖在生命周期中的位置
- [ICI 移交](ici-handoff.md)：两个系统之间的 ICI-up → DCN-rendezvous 边界
- [Fleet Metadata › 切片形状](../fleet-metadata/slice-shape.md)：tpunetd 的 `GetChipCoordinates` 所馈入的切片几何