Tree-Barrier Vsync

二进制： extracted/libtpu-0.0.40-cp314-cp314-manylinux_2_31_x86_64/libtpu/libtpu.so（build-id 89edbbe81c5b328a958fe628a9f2207d，build libtpu_lts_20260413_b_RC00；.text VMA == 文件偏移 0xe63c000，.rodata VMA == 文件偏移）。 状态： 可重实现级 · 证据等级： 已确认（字节锚定）——两阶段 BarrierCoresTree 扫描、Vsync/VsyncAdd/VsyncAddRemote 的 builder→creator→MLIR-op 链，以及 InfoTable 的构建/读取算术均为字节精确（已与 demangled 符号签名交叉核对）；SMEM Replica/PartitionIdLocationWordOffset 字面值和 2D DeviceAssignment 展平顺序为 LOW（memfile / 部分解码，见 §6）· 第 XIII 部分 — On-Pod Collectives 与 Barriers / SFLAG 与 barriers · 返回索引

摘要

net_util tree-barrier 是 TensorCore 跨核心 rendezvous，它不通过单个由 coloring 分配的 per-key SFLAG 路由。它是 jellyfish lowering 发出的两种不同拓扑之下的执行层：

BarrierCoresTree @0x1c6a75c0 — 跨核心 tree barrier（all-cores / replicated / partitioned）。它以两个阶段遍历由 routing-table 索引的 peer 集合（up-sweep fan-in 与 down-sweep fan-out），用 VsyncAddRemote 向每个 peer 发信号，并在保留的 GLOBAL TC SFLAG（base+count+4，GetGlobalBarrierSyncFlagNumber）上 rendezvous。由 AllGather / RingSum / RotatedPincer fusions 以及 runtime all-cores barriers 使用。
within-replica-group star（BarrierWithinReplicaGroup*）— 一个覆盖一个 replica group 的扁平 fan-in-to-master-then-fan-out-from-master barrier，由 AllToAll emitter lower。它不是 binomial tree；它记录在 Replica（type-2）Barrier。本页只覆盖它的 Vsync 执行（同一组 VsyncAddRemote/VwaitGeSV/VsyncAdd primitives）以及提供 peer 集合的 InfoTable，因为 tree-barrier 与 star 共享同一个 primitive 层。

两种拓扑都由一个三指令 primitive 族构成——VsyncAddRemote（通过 ICI 向 peer 的 sflag 发信号）、VsyncAdd（加到本地 sflag，用于 reset）、VwaitGeSV（阻塞直到 sflag 达到阈值）——并且都通过 replica-group InfoTable 枚举其 peer cores：这是一个编译期 int32 数组，以展平的全局 device_id 为索引，存储每个 device 在其 replica group 内的 ordinal；emit-time 时经由当前 core 的 (replica_id, partition_id) 从 SMEM 读回。

本页负责三件事：(1) tree sweep（BarrierCoresTree 两阶段 up/down 遍历），(2) Vsync primitive 族（builder → LloInstruction creator → MLIR llo op），以及 (3) InfoTable 布局 + walk 消费的线格式索引。barrier kind selection（BarrierConfig GLOBAL/REPLICA/CUSTOM）在上游——见 Barriers 概览、推断 Barrier Config；global SFLAG slot 在 Global-Barrier SFLAG 窗口；SFLAG memref binding 在 Barrier-to-SFLAG 绑定。

对重实现而言，契约是：

两条执行路径，一个 primitive 族。 跨核心 BarrierCoresTree（routing-table tree，GLOBAL sflag）和 per-replica-group star（InfoTable peer set，per-key/REPLICA sflag）是独立 emitter，但发出相同的 VSyncAddRemoteOp / VSyncAddOp / VWaitGeOp ops。tree barrier 不是分层建立在 star 之上。
Vsync 线格式。 VsyncAddRemote(sflag, peer_CoreLocationBase, value, bool) 将 peer location 折叠进 ICI remote-sflag address（EncodeRemoteSyncFlagAddress，按 codename 区分），并发出 VSyncAddRemoteOp。VsyncAdd 对本地 sflag 发出 VSyncAddOp；VwaitGeSV 发出 VWaitGeOp。这些是 TensorCore sequencer Vsync ops，与 SparseCore sc_tpu.sync_add 族相互独立。
InfoTable 以 device_id 为索引，存储 within-group ordinal。 构建：CreateStaticReplicaInfoTable → R1 int32[replica_count × (use_partition ? partition_count : 1)]，table[device_id] = within_group_position。读取：GetReplicaGroupCoreInfo 从 SMEM 读取此 core 的 (replica_id, partition_id)，LoadInfoTable 将线性索引转换为 (word, lane) 并用 Sld 加载 entry；恢复出的 ordinals → peer CoreLocationBase 列表，其中元素 [0] 是 group master。
tree shape 是一种 loop-nesting 选择。 GetTreeBarrierInfoTable 通过交换 DeviceAssignment 的哪个维度作为外层（fixed-per-group）轴，选择 ALL_CORES / REPLICATED / PARTITIONED；三个 table 每个 program 只 lazy register 一次。


跨核心 tree	`net_util::BarrierCoresTree` @`0x1c6a75c0`（两阶段、GLOBAL sflag、routing-table peer set）
Replica-group star	`BarrierWithinReplicaGroupStartImpl` @`0x1c698080` / `…Done` @`0x1c6984e0` / Join @`0x1c6ad400`（见 Replica Barrier）
Signal primitive	`LloRegionBuilder::VsyncAddRemote(LloValue, CoreLocationBase const&, LloValue, bool)` @`0x1d522f40` → `VSyncAddRemoteOp`
Local-add primitive	`LloRegionBuilder::VsyncAdd` @`0x1d523200` → `VSyncAddOp`（`CreateVectorSyncFlagAdd` @`0x1d4dc1c0`）
Wait primitive	`LloRegionBuilder::VwaitGeSV` @`0x1d522f80`（int form @`0x1d54c4a0`）→ `VWaitGeOp`
Remote-addr fold	`EncodeRemoteSyncFlagAddress` @`0x1d54da40`（按 codename 分为 JfDf/Viperfish/Pufferfish/Ghostlite）
InfoTable 构建	`CreateStaticReplicaInfoTable` @`0x1c69b780` → `InfoTable{tag=1, ptr, byte_len, byte_size}`
InfoTable 读取	`GetReplicaGroupCoreInfo` @`0x1c698740` → `LoadInfoTable` @`0x1c69ff20` → peer `CoreLocationBase` list
Tree-shape 选择	`GetTreeBarrierInfoTable` @`0x1c6a8780`（ALL_CORES / REPLICATED / PARTITIONED）
Global sflag 来源	`Target::GetGlobalBarrierSyncFlagNumber` @`0x1d60f420`（`base+count+4`，Global-Barrier 窗口）

1. Vsync primitive 族

TensorCore tree/star barriers 发出的每个跨核心 SFLAG write 都经过三个 LloRegionBuilder 方法之一。每个方法都是一个很薄的 builder，通过 Create… factory 分配 LloInstruction，并将其追加到当前 LloRegion。这些 factory 以 MLIR llo dialect op 作为类型；op 名称已在 Dialect::addOperations 注册列表中确认（VSyncAddRemoteOp、VSyncAddOp、VSyncReadOp、VWaitGeOp、VWaitEqOp）。

Builder 方法（VMA）	`LloInstruction` creator（VMA）	MLIR `llo` op	作用
`VsyncAddRemote(sf, loc, v, b)` @`0x1d522f40`	`CreateVectorSyncFlagAddRemote(LloValue, LloValue, LloRegion*)` @`0x1d4dc340`	`VSyncAddRemoteOp`	将 `v` 加到 peer 的 sflag（fan-in / fan-out signal）
`VsyncAdd(sf, v)` @`0x1d523200`	`CreateVectorSyncFlagAdd(LloValue, LloValue, optional<bool>, LloRegion*)` @`0x1d4dc1c0`	`VSyncAddOp`	将 `v` 加到本地 sflag（用作 post-wait reset）
`VwaitGeSV(sf, thr, b)` @`0x1d522f80`（int form @`0x1d54c4a0`）	—（`VWaitGe` lowering）	`VWaitGeOp`	阻塞直到本地 sflag `>= thr`

signal builder 的主体正是三调用链（已在 0x1d522f40 的 decompile 中确认）：

// LloRegionBuilder::VsyncAddRemote(LloValue* sflag, CoreLocationBase const& peer_loc,
//                                  LloValue* value, bool is_remote)        @0x1d522f40
LloValue *enc = LloRegionBuilder::EncodeRemoteSyncFlagAddress(this, sflag, peer_loc, is_remote);  // 0x1d54da40
LloInstruction *op = LloInstruction::CreateVectorSyncFlagAddRemote(enc, value, *this, region);    // 0x1d4dc340
return LloRegion::AppendInstruction(region, op, 0, region_ctx);                                    // 0x1d50f9a0
```text

`EncodeRemoteSyncFlagAddress` @`0x1d54da40` 将 peer `CoreLocationBase` 和本地 sflag number 折叠成 ICI 可路由的 remote-sflag address。它按 chip codename 分派——`EncodeRemoteSyncFlagAddressJfDf`、`…Viperfish`、`…Pufferfish`、`…Ghostlite` 都存在于 `functions.json`——因此*精确的* address bit-layout 是代际相关的。高层契约（“`VsyncAddRemote` 以一个 `CoreLocationBase` 选择的 peer 为目标，作用于本地 sflag number”）与代际无关且已字节确认；per-codename encoding 单独记录在 [Remote SFLAG Encoders](remote-sflag-encoders.md)。

> **注意 —** 这些是 **TensorCore-sequencer** Vsync ops。SparseCore embedding barriers 使用相互独立的 primitive 族（`sc_tpu.sync_add` / `sync_wait`），目标是相互独立的保留 SFLAG sub-block（`SparseCoreTarget+0x1d0`）。两者从不共享 primitive 或 sflag；见 [Barriers 概览 §1](overview.md) 和 [SFLAG Sync-Flag 层级](../memory/sflag-protocol.md)。

---

## 2. `BarrierCoresTree` — 跨核心两阶段 tree sweep

`net_util::BarrierCoresTree` @`0x1c6a75c0` 是 all-cores / replicated / partitioned **tree** barrier。它的签名（从 `functions.json` demangle）为：

```text
net_util::BarrierCoresTree(
    LloRegionBuilder,
    std::function<absl::StatusOr<LloValue*>(LloRegionBuilder, TreeBarrierType)>,  // per-type InfoTable producer
    TreeBarrierType,
    ProgramSharedRegistry const*,
    LloValue* /*barrier_sflag, may be null*/,
    bool)

2.1 sflag：GLOBAL slot，而不是 per-key id

当调用方传入 null barrier_sflag 时，BarrierCoresTree 自行 materialise 保留的 GLOBAL TC barrier slot（已在 decompile 中确认）：

int global = Target::GetGlobalBarrierSyncFlagNumber(target);          // 0x1d60f420 → base+count+4
LloValue *sf = LloRegionBuilder::SflagImmPtr(b, global, "global barrier sync flag", 24);
```text

这是保留的 top-5 slot `base+count+4`（GLOBAL `BarrierConfig` lower 到的同一 slot——见 [Global-Barrier SFLAG 窗口](global-barrier-window.md)）。因此 tree barrier 在*单个、program-wide* sflag 上 rendezvous，而不是在由 coloring 分配的 per-key id 上。一个 `TreeBarrierType::kAll` 合法性 CHECK（`.rodata` 字符串 `"barrier_type == TreeBarrierType::kAll"`）守卫 all-cores 路径。

### 2.2 两阶段 sweep（up-sweep fan-in，down-sweep fan-out）

tree walk 以**两个阶段**发出，每个阶段都在 `.rodata` 字符串 `"tree-barrier-phase-1"` 和 `"tree-barrier-phase-2"` 中标注。每个阶段计算一个 per-core routing-table index，并在一个步长为 `0x10` byte 的 `SimpleLoop` 中向其 tree 选择的 peers 发信号（routing entry 中 `CoreLocationBase` 大小的元素）：

```c
// PHASE 1 (up-sweep)：朝 tree root 向 children/parent 发信号
GetLimitedIciRoutingTableIndex(idx, …, "tree-barrier-phase-1", 20, …);   // 0x1c6a5e80
region1 = LloRegionBuilder::SimpleLoop(b, n1, /*start*/1, /*stride*/16, /*step*/1);   // 0x1d57d4a0
  VsyncAddRemote(b, value, peer, sflag, 0, …);                            // 0x1d522f40 → VSyncAddRemoteOp

// PHASE 2 (down-sweep)：沿 tree 向下释放
GetLimitedIciRoutingTableIndex(idx, …, "tree-barrier-phase-2", 20, …);   // 0x1c6a5e80
region2 = LloRegionBuilder::SimpleLoop(b, n2, 1, 16, 1);                  // 0x1d57d4a0
  VsyncAddRemote(b, value, peer, sflag, 0, …);                            // VSyncAddRemoteOp

global rendezvous 自身在同一主体中使用 wait + reset primitives：VwaitGeSV(sflag, thr)（VWaitGeOp）阻塞直到 up-sweep arrivals 已累积，然后 VsyncAdd(sflag, …)（VSyncAddOp）在 down-sweep release 前 reset 本地 sflag。这是 canonical up-sweep/down-sweep barrier：arrivals 沿 routing tree fan in 到 rendezvous 点，core 对 GLOBAL sflag wait-ge，然后沿同一棵 tree fan out 释放。

GetLimitedIciRoutingTableIndex @0x1c6a5e80 读取 per-core Replica/PartitionIdLocationWordOffset SMEM words，并将它们 bit-pack（SandU32/SshrlU32/Por 链）成 routing-table index，用于选择该阶段的 peer slice——也就是说，walk 遵循的 tree shape 由 routing table 数据驱动，而不是静态的 binomial fan-out degree。

2.3 Custom variant

BarrierCoresTreeCustom closure（.rodata "custom-tree-barrier"）是第二个入口，它直接从 module config 获取 TreeBarrierType，而不是从 arg 获取；它受 program 的 megachip/megacore module flags 守卫。它发出相同的两阶段 VsyncAddRemote walk；只有 TreeBarrierType 的来源不同。

易错点 — BarrierCoresTree 不是 within-replica-group barrier。AllToAll within-group barrier 是一个 flat star（一个 master，peer[0]），位于 BarrierWithinReplicaGroup*（Replica Barrier）。BarrierCoresTree 是 AllGather / RingSum / RotatedPincer 和 runtime all-cores barriers 使用的跨核心 tree。两者最终都到达同一个 VSyncAddRemoteOp——但 peer set、sflag 与拓扑不同。

3. Vsync star（within-replica-group）— primitive-level 视角

replica-group barrier（Replica Barrier）在这里仅以 primitive 层级纳入，因为它是 Vsync 族最简单的 exhibit，也因为它消费同一个 InfoTable（§4）。它是一个覆盖一个 barrier sflag N = group size 的两半 flat star：

text

NON-MASTER half  (BarrierWithinReplicaGroupStartImpl @0x1c698080):
  if N <= 1: install no-op Join, return        // singleton group ⇒ 无 barrier
  peers = GetReplicaGroupCoreInfo(InfoTables…)  // peers[0] = group MASTER
  Predicated(Pneg(participation_pred))          // 只有 non-masters 运行 signal
  (verify) ScheckGe(0)/ScheckLt(chip_count)/ScheckNe(self) on master chip id
  VsyncAddRemote(barrier_sflag, MASTER=peers[0], +1, false)     // +1 → master's sflag

MASTER half  (BarrierWithinReplicaGroupDone @0x1c6984e0 / Join @0x1c6ad400):
  Predicated(participation_pred)                // 只有 master 运行 wait+release
  VwaitGeSV(barrier_sflag, N-1)  [annotation "replica-group-barrier-wait"]   // 所有 non-masters 已到达
  VsyncAdd(barrier_sflag, 1-N)                  // 将 sflag reset 回 0
  for peer in peers[1..]: (ScheckGe/Lt/Ne guards)
      VsyncAddRemote(peer.barrier_sflag, +1, false)            // 释放每个正在等待的 non-master
```text

两半的 decompile 逐字节匹配：`StartImpl` @`0x1c698080` 运行 `GetReplicaGroupCoreInfo` → `Pneg`/`Predicated` → `ScheckGe`/`ScheckLt` → `ToGlobalCoreId`/`GlobalCoreId`/`ScheckNe("Non-master core has same location as master core!")` → `VsyncAddRemote`；Join @`0x1c6ad400` 运行 `Predicated` → `VwaitGeSV`（标注 `"replica-group-barrier-wait"`）→ `VsyncAdd`（reset）→ 每 peer 一个 `ScheckGe`/`ScheckLt`/`ScheckNe("Barriering with self!")` + `VsyncAddRemote` loop。

> **注意 —** `StartImpl` closure 中的 `count >> 1` capture 是 peer span 的 `SmallVector` inline-capacity split，**不是** tree fan-out degree。within-group barrier 没有 tree halving——它是 `N-1` 次 remote-add in，一次 wait-ge，`N-1` 次 remote-add out。binomial table（`CreateStaticBinomialReplicaInfoTable` @`0x1375efa0`）是一个*不同的*结构，供 AllReduce/AllGather ring/pincer fusions 使用（[Binomial Recursive Doubling](../collectives/binomial-recursive-doubling.md)），不是这个 barrier。

---

## 4. replica-group `InfoTable` — 布局 + 索引

star（§3）和 tree（§2）都通过 `InfoTable` 枚举其 peer cores——这些是编译期 `int32` 数组，在 emit-time 从 SMEM 读取。构建侧和读取侧是对称的。

### 4.1 构建 — `CreateStaticReplicaInfoTable` @`0x1c69b780`

```c
InfoTable CreateStaticReplicaInfoTable(
    Span<ReplicaGroup> groups, long replica_count, long partition_count,
    bool b4, bool use_partition, DeviceAssignment*):

  table_len = replica_count * (use_partition ? partition_count : 1)   // entries，每个为 int32
  int32 *table = operator new(16 * table_len); memset(table, 0, 16 * table_len)
  //（过量分配 16 B/entry——SmallVector-backed alloc path；只使用 int32 lanes）
  for each ReplicaGroup g (stride 0x30):
      n   = g.replica_ids_size [g+0x1c]
      ids = g.replica_ids (inline [g+0x18] or heap [g+0x20])
      for k in [0, n):
          device_id = ids[k]                    // CHECK 0 <= device_id < table_len
          table[device_id] = k                  // 1D：存储 within-group ORDINAL
          // 2D / use_partition：也按 partition_count 对 device_id 做 div/mod，并
          //   通过 DeviceAssignment dims 展平（imul/add chain @0x1c69bb70），
          //   通过 proto2::internal::LogIndexOutOfBoundsAndAbort @0x21063300 做 bounds-check
  return InfoTable{ tag=1 [+0], data_ptr [+8], byte_len=table_len*4 [+0x10], byte_size=table_len*4 [+0x18] }
  // 注意：在 decompile 中 [+0x10] 存为 (16*table_len)>>2 == table_len*4——BYTE length，
  //       等于 [+0x18]，不是 int32 element count（table_len）。

decompile 确认了签名、memset、per-ReplicaGroup walk、LogIndexOutOfBoundsAndAbort bounds checks，以及 InfoTable{tag,ptr,count,bytes} 结果形状。table 以展平的全局 device_id 为索引，并存储该 device 在其 replica group 内的 ordinal（1D 形式）。每个 (replica_count × partition_count) topology 有一个这样的 table，直接从 HLO collective 的 replica_groups attribute（以及 2D 形式所用的 DeviceAssignment）派生。CreateReplicaInfoTable @0x1c69b660 是薄 wrapper。

4.2 读取 — `GetReplicaGroupCoreInfo` @`0x1c698740` + `LoadInfoTable` @`0x1c69ff20`

在 emit time，per core，GetReplicaGroupCoreInfo（缓存在 replica_group_core_info_cache_mutex @0x22579828 下，key 为 hlo/module/the InfoTables/longs/bool）恢复当前 core 的 group peers：

// 1. 从 SMEM 读取此 core 的 identity
replica_id   = Sld(SmemWordImmPtr(Target::ReplicaIdLocationWordOffset(),   "replica id location"));    // 0x1d617c80
partition_id = Sld(SmemWordImmPtr(Target::PartitionIdLocationWordOffset(), "partition id location"));  // 0x1d617ca0

// 2. LoadInfoTable：linear element index -> (word, lane)，然后 Sld 该 int32 entry
//    element width = (InfoTable[+0xb] >> 2) & 0x1F   (= s32)
//    stride        = SmemWordSizeBytes / WordSizeBytes(MemorySpace)
//    (word, lane)  = SdivmodU32(SmulU32(index, stride))
entry = LoadInfoTable(b, index, dtype, InfoTable);            // 0x1c69ff20

// 3a. 1D path（optional 3rd table absent）：一次 LoadInfoTable；通过 FromGlobalCoreId
//     构建 peer CoreLocationBase list（0x18-byte stride）。            // 0x1d51b340
// 3b. 2D path（3rd InfoTable present / partition flag）：LoadInfoTable 两次
//     (replica table + partition table) -> ReplicaAndPartitionId pairs ->
//     GetCoreLocations @0x1c69a580 -> peer CoreLocationBase list。
// peers[0] = group MASTER。
```text

`LoadInfoTable` 的 decompile 确认了 element-width 表达式 `(*(byte*)(infotable+11) >> 2) & 0x1F`、`WordSizeBytes` / `SmemWordSizeBytes` stride，以及 `SmulU32`/`SdivmodU32` index→`(word, lane)` 转换。`GetReplicaGroupCoreInfo` 的 decompile 确认了通过 `SmemWordImmPtr` + `Sld` 读取 `ReplicaIdLocationWordOffset` / `PartitionIdLocationWordOffset` SMEM、1D single / 2D double `LoadInfoTable` 调用，以及 `FromGlobalCoreId`。

> ⇒ 一个 `(replica_id, partition_id)` pair 索引 SMEM-resident `InfoTable`，以恢复当前 core 的 within-group ordinal；该 ordinal 枚举 group 的 peer `CoreLocation`。`peers[0]` 是 star（§3）发信号/等待的 master。

### 4.3 两张 table + 可选第三张

`GetReplicaGroupCoreInfo` 和 barrier emitters 接受 `(InfoTable& A, InfoTable& B, optional<InfoTable> C)`：

| Arg | Table | 来源 |
|---|---|---|
| `A` | replica-axis table | `CreateStaticReplicaInfoTable`（replica fill） |
| `B` | partition-axis table | `CreateStaticReplicaInfoTable`（partition variant） |
| `C`（optional） | 3D / limited-ICI-routing table | `CreateStaticReplicaInfoTableForLimitedIciRouting` @`0x1c69c120` |

cache hash 组合 `(InfoTable, InfoTable, long, long, bool, long)` @`0x1c6acb20`（两张 table + `replica_count` + `partition_count` + 一个 flag + 一个 long）。tables 自身作为 HLO constants 携带（`GetConstantTables` 返回 AllToAll emitter 消费的 `StatusOr<tuple<InfoTable, InfoTable, optional<InfoTable>>>`——见 [All-to-All Tables](../collectives/alltoall-tables.md)）。

---

## 5. Tree-table shape — `GetTreeBarrierInfoTable` @`0x1c6a8780`

跨核心 tree barrier 的 *grouping*（哪些 cores 一起 rendezvous）是单个 `DeviceAssignment` loop-nesting 选择。`GetTreeBarrierInfoTable(TpuTopology, DeviceAssignment, TreeBarrierType, …)` 读取 assignment dims `DA[+0]=replica_count`、`DA[+8]=partition_count`，计算 `total = replica_count × partition_count`，并嵌套两层 loop，其顺序由 `TreeBarrierType` 设置：

| `TreeBarrierType` | r8d | registry key（`.rodata`） | 外层 loop（每个 group 固定） | 内层 loop | 每个 group = 满足以下条件的 cores |
|---|---|---|---|---|---|
| `ALL_CORES` (0) | 0 | `<all-cores-tree-barrier-info-table>` @`0xb433290` | （覆盖所有 device ids 的单个 flat group） | — | program 中的每个 core |
| `REPLICATED` (1) | 1 | `<replicated-cores-tree-barrier-info-table>` @`0xb4332c0` | `partition_count` | `replica_count` | 共享一个 partition，replica 不同（同步一个 partition 的各 replicas） |
| `PARTITIONED` (2) | 2 | `<partitioned-cores-tree-barrier-info-table>` @`0xb4332f0` | `replica_count` | `partition_count` | 共享一个 replica，partition 不同（同步一个 replica 的 model-parallel shards） |

`REPLICATED` 与 `PARTITIONED` 之间**唯一**的差异，是 `DeviceAssignment` 的哪个维度作为外层（fixed-per-group）轴：`REPLICATED` 固定 partition 并跨 replicas 分组；`PARTITIONED` 固定 replica 并跨 partitions 分组。两者都生成一个 `(replica, partition)` pairs 的 `Span<pair<long,long>>`，输入给 `$_2` pair→core-id closure @`0x1c6a94c0` → `GetCoreLocations` @`0x1c69a580`。decompile 确认了三个 `$_2`/`$_3`/`$_4` closures，以及按 `TreeBarrierType` 分派的 `LogMessage`。

三张 table 以 key 标识，并且每个 program 只注册一次：

- `GetOrCreateTreeBarrierInfoTable` @`0x1c6b60e0` 将 type → registry string key：`r8d==2` → tag `0x2b` `<partitioned-…>`；`==1` → tag `0x2a` `<replicated-…>`；否则 tag `0x23` `<all-cores-…>`（tags 是 key-string lengths）。
- `RegisterTreeBarrierInfoTables` @`0x1c6a8620` 通过 `AddValue` @`0x1c8dad80` 将全部三个 lazy-InfoTable closures（`0x1c6b60a0` / `0x1c6b66c0` / `0x1c6b6700`）lazy register 到 `ProgramSharedRegistry`。

> **易错点 —** `DeviceAssignment` dim convention `[+0]=replica_count, [+8]=partition_count` 具有**字节确认的 offsets**（`movslq DA[+0]` / `DA[+8]`），但维度*名称*来自 `REPLICATED`/`PARTITIONED` loop-nesting semantics 以及标准 XLA `DeviceAssignment [replica, computation]` shape，而不是来自 struct field descriptor。*行为*（每种 type 的外层轴）是确定的。

---

## 6. 端到端执行 datapath

| 阶段 | Function（VMA） | 输出 |
|---|---|---|
| BarrierConfig → sflag | `net_util::GetBarrierSyncFlag` @`0x1c69ad00` | TC barrier sflag = `*(Target+0x8c0)+id`（[Barrier-to-SFLAG 绑定](barrier-to-sflag-binding.md)） |
| membership table（构建） | `CreateStaticReplicaInfoTable` @`0x1c69b780` | R1 `int32[replica×partition]`，`table[dev]=pos` |
| membership read（per core） | `GetReplicaGroupCoreInfo` @`0x1c698740` | peer `CoreLocationBase` list（`peer[0]`=master） |
| ↳ scalar table load | `LoadInfoTable` @`0x1c69ff20` | SMEM `int32` entry 的 `Sld` |
| START（non-master signal） | `BarrierWithinReplicaGroupStartImpl` @`0x1c698080` | `VSyncAddRemoteOp(+1)` → master |
| DONE（master wait+release） | `…Done` @`0x1c6984e0` / Join @`0x1c6ad400` | `VWaitGeOp(N-1)` + `VSyncAddOp(1-N reset)` + `N-1× VSyncAddRemoteOp(+1)` → peers |
| cross-core tree（两阶段） | `BarrierCoresTree` @`0x1c6a75c0` | 基于 `GetLimitedIciRoutingTableIndex` 的 up-sweep + down-sweep，GLOBAL sflag，`VSyncAddRemoteOp` |
| tree-table shape select | `GetTreeBarrierInfoTable` @`0x1c6a8780` | `ALL_CORES` / `REPLICATED` / `PARTITIONED` groups |
| global sflag slot | `GetGlobalBarrierSyncFlagNumber` @`0x1d60f420` | `base+count+4`（[Global-Barrier 窗口](global-barrier-window.md)） |

---

## 7. 验证说明

> 在 `libtpu.so` v0.0.40 中字节精确（已与 demangled symbol table 交叉核对）：
>
> - `VsyncAddRemote` @`0x1d522f40`：主体正是 `EncodeRemoteSyncFlagAddress` @`0x1d54da40` → `CreateVectorSyncFlagAddRemote` @`0x1d4dc340` → `LloRegion::AppendInstruction` @`0x1d50f9a0`——精确。
> - Vsync creators：`CreateVectorSyncFlagAddRemote(LloValue*, LloValue*, LloRegion*)` 和 `CreateVectorSyncFlagAdd(LloValue*, LloValue*, optional<bool>, LloRegion*)` 存在于 `functions.json`；MLIR ops `VSyncAddRemoteOp` / `VSyncAddOp` / `VWaitGeOp` / `VWaitEqOp` / `VSyncReadOp` 已在 `addOperations` 注册列表中确认。
> - `BarrierCoresTree` @`0x1c6a75c0`：GLOBAL-sflag materialisation（`GetGlobalBarrierSyncFlagNumber` @`0x1d60f420` + `SflagImmPtr "global barrier sync flag"`）；**两阶段** sweep（`.rodata` `"tree-barrier-phase-1"` / `"tree-barrier-phase-2"`，每个都有 `GetLimitedIciRoutingTableIndex` @`0x1c6a5e80` + `SimpleLoop` @`0x1d57d4a0` stride `0x10` + `VsyncAddRemote`）；`VwaitGeSV` + `VsyncAdd` rendezvous；`BarrierCoresTreeCustom` `"custom-tree-barrier"` variant——已确认。
> - star（`StartImpl` @`0x1c698080` / Join @`0x1c6ad400`）：`Pneg`/`Predicated` gate、`ScheckGe`/`ScheckLt`/`ScheckNe` guards（`"Non-master core has same location as master core!"`、`"Barriering with self!"`）、标注 `"replica-group-barrier-wait"` 的 `VwaitGeSV`、`VsyncAdd` reset、per-peer `VsyncAddRemote` loop——逐字节确认。
> - `CreateStaticReplicaInfoTable` @`0x1c69b780`：`Span<ReplicaGroup>, long, long, bool, bool, DeviceAssignment*` 签名、`memset`、per-group fill、`LogIndexOutOfBoundsAndAbort` @`0x21063300` bounds checks、`InfoTable{tag=1, ptr, byte_len=4·table_len, byte_size=4·table_len}` 结果（`[+0x10]` 字段是 byte length `(16·table_len)>>2`，**不是** element count）——已确认。
> - `LoadInfoTable` @`0x1c69ff20`：element width `(*(byte*)(table+0xb) >> 2) & 0x1F`、`WordSizeBytes` / `SmemWordSizeBytes`、`SmulU32` + `SdivmodU32` index→`(word,lane)`——精确。
> - `GetReplicaGroupCoreInfo` @`0x1c698740`：通过 `SmemWordImmPtr` + `Sld` 使用 `Replica/PartitionIdLocationWordOffset`、1D-single / 2D-double `LoadInfoTable`、`FromGlobalCoreId`——已确认。
> - `GetTreeBarrierInfoTable` @`0x1c6a8780`：`TpuTopology, DeviceAssignment, TreeBarrierType` 签名和三个 pair-mapping closures——已确认；`GetOrCreateTreeBarrierInfoTable` @`0x1c6b60e0` 中的 registry keys / tags——已确认。
>
> **[LOW / 部分解码]**
>
> - `Target::ReplicaIdLocationWordOffset()` @`0x1d617c80` / `PartitionIdLocationWordOffset()` @`0x1d617ca0` 字面*值*——即每个 core 在 runtime 读取以获知自身 `(replica_id, partition_id)` 的 SMEM word offsets——由 chip-config / boot path 填充（embedded-memfile dependency）；只确认了它们的*使用*，没有确认 accessor bodies。
> - `CreateStaticReplicaInfoTable` 中感知 2D `DeviceAssignment` 的 fill（`imul`/`add` multi-dim flatten @`0x1c69bb70`）：1D path（`table[dev]=pos`）是字节精确的；2D flatten 的精确 dim ordering 已按结构跟踪，但未完全钉住。
> - `GetTreeBarrierInfoTable` `$_2` pair→global-core-id closure @`0x1c6a94c0` 到达 `GetCoreLocations` @`0x1c69a580`，但精确的 `(replica, partition)` → core-id flattening（相对于 replica-group tables）只是采样过，未完全解码。
> - `Target+0x3b8`→`[+0x70]`（`StartImpl` 使用的 master-chip-id `ScheckLt` upper bound）：offsets 已确认；“chip count” 角色来自 `"Master core chip id underflow/overflow"` assert strings，而没有独立的具名 accessor。

---

## 交叉引用

### Barrier 算法（本节）

- [Barriers 概览](overview.md) — `BarrierType` model 以及选择本层执行哪个 barrier 的 producer→normaliser→lowering flow
- [Replica（type-2）Barrier](replica-barrier.md) — within-replica-group flat-star barrier，其 `Vsync` 执行 + `InfoTable` peer set 在此处描述
- [Global-Barrier SFLAG 窗口](global-barrier-window.md) — `BarrierCoresTree` rendezvous 所在的 `base+count+4` GLOBAL slot
- [Barrier-to-SFLAG 绑定](barrier-to-sflag-binding.md) — `GetBarrierSyncFlag` / `BarrierConfig` → chip SFLAG memref
- [推断 Barrier Config](infer-barrier-config.md) — 决定 sflag kind 的 `CUSTOM → GLOBAL/REPLICA` normaliser
- [TensorCore Barrier](tensorcore-barrier.md) — TC-substrate signal/wait barrier 与由 coloring 选择的 `CUSTOM` ids
- [Remote SFLAG Encoders](remote-sflag-encoders.md) — per-codename `EncodeRemoteSyncFlagAddress` ICI address fold

### 同级子系统

- [SFLAG Sync-Flag 层级](../memory/sflag-protocol.md) — 每个 Vsync op 写入的 SFLAG atomic-counter substrate
- [All-to-All Tables](../collectives/alltoall-tables.md) — 提供 barrier 的 `GetConstantTables` `InfoTable`s 的 AllToAll emitter
- [Binomial Recursive Doubling](../collectives/binomial-recursive-doubling.md) — 供 reduce/gather fusions 使用的*独立* binomial table（`CreateStaticBinomialReplicaInfoTable`），不是此 barrier
- [Collectives](../collectives/overview.md) — 消费这些 barriers 的 collective ops
- [返回索引](../index.md)

Tree-Barrier Vsync ​

摘要 ​

1. Vsync primitive 族 ​

2.1 sflag：GLOBAL slot，而不是 per-key id ​

2.3 Custom variant ​

3. Vsync star（within-replica-group）— primitive-level 视角 ​

4.2 读取 — GetReplicaGroupCoreInfo @0x1c698740 + LoadInfoTable @0x1c69ff20 ​