第 2 章：核心抽象模型：通信算子、拓扑、算法、协议与传输层

上一章我们让 NCCL 跑了起来，观察了 ncclCommInitRank、ncclAllReduce、ncclCommDestroy 三个 API 的外部行为。但外部行为只是冰山一角——当 ncclAllReduce 返回时，GPU 上到底发生了什么？数据走了哪条路？为什么同样的 AllReduce 在不同机器上性能差异巨大？要回答这些问题，必须先建立 NCCL 的公共词汇表。本章将逐一拆解五个核心抽象：通信域（ncclComm）、通道（channel）、算法（algorithm）、协议（protocol）、传输层（transport）。这五个概念贯穿全书，后续每一章的分析都会用到它们。理解它们之间的关系，就理解了 NCCL 的骨架。

2.1 通信域 ncclComm：一个进程的通信上下文

直觉模型

把 ncclComm 想象成一个「群聊」：每个进程加入群聊后拿到一个群 ID，之后所有消息都在这个群里发。群里有几个人（nRanks）、我是谁（rank）、走什么线路（channels）、用什么规则（config），全都记在这个群聊对象里。

如果没有 ncclComm，NCCL 就不知道「谁和谁通信」「数据发到哪里去」——每次调用 API 都得重新协商 rank 列表、重建连接，开销无法承受。

数据结构与内存布局

ncclComm 是整个 NCCL 最核心的结构体，定义在 src/include/comm.h 中。它极其庞大（近 300 行），我们按功能分组来看关键字段。

身份标识与生命周期哨兵

📎 src/include/comm.h:576-580 定义了 startMagic，📎 src/include/comm.h:879-881 定义了 endMagic。这两个字段不是安全密钥，而是内存越界检测哨兵。在 📎 src/include/comm.h:883-885 处有两个 static_assert：

static_assert(offsetof(struct ncclComm, startMagic) == 0, "startMagic must be the first field of ncclComm");
static_assert(offsetof(struct ncclComm, endMagic) == sizeof(struct ncclComm) - sizeof(uint64_t),
              "endMagic must be the last field of ncclComm");

Rank 与拓扑信息

📎 src/include/comm.h:628-629 定义了 rank 和 nRanks——我在通信域中的编号和总参与者数。📎 src/include/comm.h:644-652 定义了节点相关字段：node（我所在节点编号）、nNodes（总节点数）、localRank（节点内编号）、localRanks（节点内 GPU 数），以及三张映射表 rankToNode、rankToLocalRank、localRankToRank。

通道与缓冲区

📎 src/include/comm.h:593-593 定义了 channels[MAXCHANNELS]——这是通信域内所有通道的数组。📎 src/include/comm.h:674-676 定义了通道数量：nChannels（连接通道数）、collChannels（集合通信入队通道数）、nvlsChannels（NVLS 通道数）。

📎 src/include/comm.h:691-693 定义了缓冲区大小：buffSizes[NCCL_NUM_PROTOCOLS]（每种协议的缓冲区大小）、p2pChunkSize（P2P 块大小）、nvlsChunkSize（NVLS 块大小）。

工作队列与 FIFO

📎 src/include/comm.h:719-728 定义了工作 FIFO 相关字段：workFifoBytes（FIFO 大小，2 的幂）、workFifoBuf（主机侧 FIFO 缓冲区）、workFifoBufDev（设备侧 FIFO 缓冲区）、workFifoProduced（已生产字节数）、workFifoConsumed（已消费字节数）。

进程内同步屏障

📎 src/include/comm.h:731-731 定义了进程内多通信域同步机制：

struct ncclComm* intraComm0; // leader of intra-process comms (self possible)
struct ncclComm* intraNext; // next of intra-process comms, intraComm0 is head
int intraRank;
int intraRanks;
uint32_t intraBarrierPhase;
char intraPad1[64 - sizeof(uint64_t)];
uint64_t intraBarrierCounter; // only used if this is intraComm0
char intraPad2[64 - sizeof(uint64_t)];
uint64_t intraBarrierGate; // only used if this is intraComm0

注意 intraPad1 和 intraPad2 的大小是 64 - sizeof(uint64_t)，即 56 字节。加上前面的 uint64_t 字段，每个字段组恰好占 64 字节——这是一个缓存行（Cache Line）。

异步错误状态

📎 src/include/comm.h:705-705 定义了 asyncResult——这个字段记录通信域的异步操作状态。上一章我们提到 ncclCommFinalize 返回时通信域可能还处于 ncclInProgress 状态，就是通过这个字段追踪的。

场景驱动 Walkthrough：从 ncclCommInitRank 到结构体填充

当用户调用 ncclCommInitRank(&comm, nranks, commId, rank) 时，NCCL 内部会分配一个 ncclComm 结构体并逐字段填充。我们跟随这个流程看关键字段如何被设置：

第一步：分配与清零

NCCL 使用 ncclCalloc 分配 ncclComm，确保所有字段初始为 0。此时 startMagic 和 endMagic 被设置为 NCCL_MAGIC（📎 src/include/comm.h:563-569 定义为 0x0280028002800280，注释说 "Nickel atomic number is 28"）。

第二步：填充身份信息

rank、nRanks、cudaDev 从参数和 CUDA API 获取。commHash 由 ncclCommId 哈希得到，用于后续网络通信中的一致性校验。

第三步：构建拓扑图

NCCL 调用拓扑探测模块枚举所有 GPU、网卡、PCI 交换机，构建 topo 字段（📎 src/include/comm.h:595-595）。这个拓扑图决定了后续算法选择和路径规划。

第四步：初始化通道

channels[MAXCHANNELS] 数组被逐个初始化。每个通道的 id 被设置为数组索引，peers 和 devPeers 指针被分配。

第五步：建立传输连接

根据拓扑图，NCCL 为每对 rank 选择传输层（P2P/SHM/NET），调用对应的 setup 和 connect 回调。连接信息存储在 channels[i].peers[j] 中。

第六步：设置魔数

最后，endMagic 被设置为 NCCL_MAGIC，标记结构体初始化完成。

设计思考与生产踩坑

为什么 ncclComm 这么大？

踩坑场景一：多线程共享通信域

踩坑场景二：销毁后访问

ncclCommDestroy 释放结构体内存后，如果还有线程持有指针并访问，会读到已释放内存。startMagic 和 endMagic 可以帮助检测这种情况——如果魔数不匹配，说明指针已失效。

踩坑场景三：缓存行伪共享

在多进程场景下（每个进程一个 rank），intraBarrierCounter 和 intraBarrierGate 的填充尤为重要。如果省略填充，多个进程的屏障操作会互相干扰，导致同步延迟从纳秒级上升到微秒级。

2.2 通道 channel：把一次通信切成多条流水线

直觉模型

搬家时不止开一条传送带，而是同时开好几条，每条负责一部分箱子，整体搬得更快。channel 就是 NCCL 的「传送带」——把一次集合通信的数据切分成多份，每条通道独立搬运一份，并行推进以提高带宽利用率。

如果没有 channel，所有数据只能走一条路径，GPU 之间的多条物理链路（多张网卡、多组 NVLink）无法同时利用，带宽利用率会大幅下降。

数据结构与内存布局

ncclChannel 定义在 📎 src/include/comm.h:169-191：

struct ncclChannel {
  struct ncclChannelPeer** peers;
  struct ncclDevChannelPeer** devPeers;
  /* devPeer pointer array used for host side access */
  struct ncclDevChannelPeer** devPeersHostPtr;
  struct ncclRing ring;
  int* devRingUserRanks;
  struct ncclTree tree;

  struct ncclTree collnetChain;
  struct ncclDirect collnetDirect;

  struct ncclNvls nvls;

  int id; // index of this channel
  uint32_t workFifoProduced; // +1 successor of last used work fifo byte

  /* comm split sharable resources */
  struct ncclChannelPeer* collnetPeers;
  struct ncclDevChannelPeer* collnetDevPeers;
  struct ncclChannelPeer* nvlsPeers;
  struct ncclDevChannelPeer* nvlsDevPeers;
};

关键字段解析

• peers / devPeers：指向该通道内所有 rank 的连接信息。peers 是主机侧视图，devPeers 是设备侧视图（GPU kernel 直接访问）。
• ring：Ring 算法的拓扑描述——每个 rank 的前驱和后继。
• tree：Tree 算法的拓扑描述——父节点和子节点列表。
• collnetChain / collnetDirect：CollNet 算法的两种变体拓扑。
• nvls：NVLink SHARP 的拓扑描述。
• id：通道索引，从 0 到 nChannels-1。
• workFifoProduced：该通道的工作 FIFO 生产指针。

通道数量计算

通道数量在 ncclComm 中定义（📎 src/include/comm.h:674-676）：

int nChannels; // connection nChannels
int collChannels; // enqueue nChannels
int nvlsChannels; // enqueue nChannels

P2P 通道调度

📎 src/include/channel.h:21-33 定义了 ncclP2pChannelBaseForRound 函数，用于计算 P2P 通信中每个 round 使用的通道基址：

inline uint8_t ncclP2pChannelBaseForRound(struct ncclComm* comm, int p2pRound) {
  int base;
  if (comm->nNodes > 1) {
    int localSize = comm->p2pSchedGroupSize;
    int groupDelta = p2pRound / localSize;
    int localDelta = p2pRound % localSize;
    base = groupDelta * divUp(localSize, NCCL_MAX_DEV_WORK_P2P_PER_BATCH);
    base += localDelta / NCCL_MAX_DEV_WORK_P2P_PER_BATCH;
  } else {
    base = p2pRound;
  }
  return reverseBits(base, log2Up(comm->p2pnChannels));
}

场景驱动 Walkthrough：一次 AllReduce 如何分配通道

假设 8 个 rank、4 个通道，执行一次 AllReduce。数据被切成 4 份，每份由一个通道负责。

第一步：算法选择

NCCL 的 tuning 模块根据消息大小和拓扑选择算法（比如 Ring）和协议（比如 Simple）。

第二步：通道分配

ncclTaskColl 结构体（📎 src/include/comm.h:212-273）被创建，其中 nChannels 字段被设置为 4（📎 src/include/comm.h:254-254）。channelLo 和 channelHi 字段（📎 src/include/comm.h:256-257）标记该任务使用的通道范围。

第三步：数据切分

每个通道负责 count / nChannels 个元素。通道 0 处理第 0 到 count/4-1 个元素，通道 1 处理第 count/4 到 count/2-1 个元素，以此类推。

第四步：并行执行

4 个通道的 GPU kernel 同时启动，各自在自己的数据切片上执行 Ring AllReduce。由于通道之间没有数据依赖，可以完全并行。

第五步：结果合并

所有通道完成后，每个 rank 的 recv buffer 中就是完整的 AllReduce 结果。

并发控制与硬件交互

通道与 GPU 资源的映射

通道与网络设备的映射

在多网卡场景下，不同通道可以绑定到不同网卡。比如 4 个通道、2 张网卡，通道 0 和 1 走网卡 A，通道 2 和 3 走网卡 B。这样两张网卡的带宽都能被利用。

通道数量的选择

• 更多 kernel 启动开销
• 更多连接建立开销
• 更复杂的同步

NCCL 的 tuning 模块会根据消息大小自动选择最优通道数。小消息用少量通道（减少开销），大消息用多通道（提高带宽）。

生产避坑指南

踩坑场景一：通道数配置不当

踩坑场景二：通道与拓扑不匹配

踩坑场景三：P2P 通道冲突

ncclP2pChannelBaseForRound 的 reverseBits 操作如果实现有误，会导致多个 round 映射到同一通道，造成串行化。📎 src/include/channel.h:32-32 的 reverseBits(base, log2Up(comm->p2pnChannels)) 确保通道分配均匀。

2.3 算法 algorithm：Tree/Ring/CollNet/NVLS/PAT 的拓扑组织

直觉模型

从北京到上海可以坐高铁、飞机或自驾，每种方式适合不同的距离和人数。NCCL 的算法就是这些「出行方式」——Ring 适合大消息的稳定带宽，Tree 适合小消息的低延迟，CollNet 利用网卡卸载，NVLS 利用 NVLink SHARP 硬件加速，PAT 是 NVLS 的并行化变体。

如果没有算法选择，NCCL 只能用一种固定模式通信，无法适应不同消息大小和拓扑结构，性能会大打折扣。

数据结构与内存布局

Ring 算法

Ring 算法的核心是 ncclRing 结构体（在 src/include/comm.h 中通过 channels[i].ring 引用）。📎 src/include/collectives.h:81-116 定义了 RingAlgorithm 基类：

class RingAlgorithm {
protected:
  int refCount;
  int nRanks;
  int nStepsPerLoop;
  int chunkSteps;
  int sliceSteps;
  ssize_t sliceSize;
  ssize_t loopSize;
  ssize_t channelSize;
  uint8_t* sendbuff;
  uint8_t* recvbuff;
  void* sendMhandle;
  void* recvMhandle;
  void* srecvMhandle;

public:
  virtual void getNextSendAddr(int curStep, uint8_t** sendbuffOut, size_t* sizeOut, void** mhandleOut) = 0;
  virtual void getNextRecvAddr(int curStep, uint8_t** recvbuffOut, size_t* sizeOut, void** mhandleOut) = 0;
  int incRefCount() {
    return (int)COMPILER_ATOMIC_ADD_FETCH(&refCount, 1, std::memory_order_relaxed);
  }
  int decRefCount() {
    return (int)COMPILER_ATOMIC_SUB_FETCH(&refCount, 1, std::memory_order_release);
  }
  RingAlgorithm() {
    refCount = 0;
  }
  virtual ~RingAlgorithm() {};
};

关键字段解析

• refCount：引用计数，用于 proxy 线程和 GPU kernel 共享算法对象。
• nRanks：环上节点数。
• nStepsPerLoop：每轮循环的步数。AllReduce 是 2*(nRanks-1)*chunkSteps（📎 src/include/collectives.h:218-218）。
• chunkSteps / sliceSteps：块步数和切片步数，控制流水线粒度。
• sliceSize / loopSize / channelSize：切片大小、循环大小、通道大小。
• sendbuff / recvbuff：发送和接收缓冲区指针。
• sendMhandle / recvMhandle / srecvMhandle：内存句柄，用于网络注册。

引用计数的原子操作

📎 src/include/collectives.h:106-108 展示了 incRefCount 和 decRefCount：

int incRefCount() {
  return (int)COMPILER_ATOMIC_ADD_FETCH(&refCount, 1, std::memory_order_relaxed);
}
int decRefCount() {
  return (int)COMPILER_ATOMIC_SUB_FETCH(&refCount, 1, std::memory_order_release);
}

RingARAlgorithm：AllReduce 的 Ring 实现

📎 src/include/collectives.h:118-234 定义了 RingARAlgorithm，继承自 RingAlgorithm。核心方法是 getNextSendAddr 和 getNextRecvAddr。

📎 src/include/collectives.h:126-167 的 getNextSendAddr 逻辑：

void getNextSendAddr(int curStep, uint8_t** sendbuffOut, size_t* sizeOut, void** mhandleOut) {
  int curLoop = curStep / nStepsPerLoop;
  int curLoopStage = (curStep % nStepsPerLoop) / chunkSteps;
  int chunkStage = curLoopStage % nRanks;
  int sliceStage = (curStep % chunkSteps) / sliceSteps;
  ssize_t elemOffset = curLoop * loopSize;
  ssize_t remSize = channelSize - elemOffset;
  // ... 计算 chunkOffset, sliceOffset, curSliceSize ...
  if (remSize < loopSize) {
    curChunkSize = alignUp(divUp(remSize / elemSize, nRanks), 16 / elemSize) * elemSize;
  } else {
    curChunkSize = chunkSize;
  }
  chunkId = (ringIndex + nRanks - 1 - chunkStage) % nRanks;
  chunkOffset = chunkId * curChunkSize;
  nelem = std::min(remSize - chunkOffset, curChunkSize);
  curSliceSize = std::max(divUp(nelem / elemSize, 16 * slicePerChunk) * 16, sliceSize / elemSize / 32) * elemSize;
  sliceOffset = sliceStage * curSliceSize;
  // ... 设置 sendbuffOut, sizeOut, mhandleOut ...
}

PAT 算法

PAT（Parallel Aggregated Tree）是 NVLS 的并行化变体。📎 src/include/collectives.h:416-423 定义了 ncclPatStep：

struct ncclPatStep {
  int recvDim, sendDim, recvOffset, sendOffset, stepOffset, postRecv, postSend, nelem, last, flags;
  // PAT algo computation thread step number; -1 while the slot is free.
  int step;
  // This PAT group's offset within the shared NVLS slot.
  int nvlsOffset;
  size_t inpIx, outIx;
};

📎 src/include/collectives.h:425-435 定义了 ncclPatPeer：

struct ncclPatPeer {
  uint64_t step;
  struct ncclConnInfo* conn;
  struct ncclConnFifo* connFifo;
  void* buff;
  uint64_t* headPtr;
  uint64_t* tailPtr;
  uint64_t stepCache;
  long long int accSize;
  int connStepSize;
};

场景驱动 Walkthrough：Ring AllReduce 的步骤演化

假设 4 个 rank（0, 1, 2, 3），每个 rank 有 4 个元素，执行 Ring AllReduce。

Reduce-Scatter 阶段

• 步骤 0：rank 0 发送元素 0 给 rank 1，rank 1 发送元素 1 给 rank 2，rank 2 发送元素 2 给 rank 3，rank 3 发送元素 3 给 rank 0。
• 步骤 1：每个 rank 将收到的元素与本地对应元素相加，然后发送给下一个 rank。
• 步骤 2：继续累加和传递。
• 步骤 3：此时每个 rank 拥有一个完整的归约结果（rank 0 有元素 3 的结果，rank 1 有元素 0 的结果，等等）。

AllGather 阶段

• 步骤 4-6：每个 rank 将自己拥有的归约结果沿环传播，最终所有 rank 拥有完整结果。

📎 src/include/collectives.h:218-218 的 nStepsPerLoop = 2 * (nRanks - 1) * chunkSteps 正好对应这个流程：Reduce-Scatter 需要 (nRanks-1)*chunkSteps 步，AllGather 也需要 (nRanks-1)*chunkSteps 步，总共 2*(nRanks-1)*chunkSteps 步。

设计思考与生产踩坑

为什么 Ring 和 Tree 并存？

踩坑场景一：算法选择错误

踩坑场景二：NVLS 硬件不支持

NVLS 需要特定的硬件支持（NVLink SHARP）。如果硬件不支持但代码强制使用 NVLS，会回退到 Ring 或 Tree，但可能伴随性能抖动。📎 src/include/comm.h:755-755 的 nvlsSupport 字段标记硬件是否支持 NVLS。

踩坑场景三：PAT 算法的聚合因子配置

PAT 算法的 aggFactor 决定了聚合多少个步骤。📎 src/include/collectives.h:537-560 展示了 aggFactor 的计算逻辑：

aggFactor = 1;
size_t channelSize = end - offset;
while (stepSize / (channelSize * sizeof(T) * aggFactor) >= 2 && aggFactor < nranks / 2) {
  aggFactor *= 2;
  aggDelta /= 2;
}
postFreq = aggFactor;
if (postFreq < parallelFactor) parallelFactor = postFreq;
int d = stepDepth;
while (d > 1 && aggFactor < nranks / 2) {
  d /= 2;
  aggFactor *= 2;
  aggDelta /= 2;
}

2.4 协议 protocol：LL/LL128/Simple 三种数据搬运策略

直觉模型

寄快递可以选「同城闪送」「次日达」或「普通快递」，速度和成本不同。NCCL 的协议就是这些「寄法」——LL（Low Latency）适合小消息的低延迟传输，LL128 适合中等消息的 128 字节对齐传输，Simple 适合大消息的高带宽传输。

如果没有协议选择，NCCL 只能用一种固定策略搬运数据，无法在延迟和带宽之间取得平衡。

数据结构与内存布局

协议枚举

📎 src/include/comm.h:55-57 定义了协议相关的线程阈值：

#define NCCL_LL_THREAD_THRESHOLD 8
#define NCCL_LL128_THREAD_THRESHOLD 8
#define NCCL_SIMPLE_THREAD_THRESHOLD 64

协议缓冲区

📎 src/include/comm.h:691-691 定义了 buffSizes[NCCL_NUM_PROTOCOLS]——每种协议有独立的缓冲区大小。

协议相关的 FIFO 结构

📎 src/include/comm.h:59-83 定义了 ncclSendMem 和 ncclRecvMem：

struct ncclSendMem {
  union {
    struct {
      uint64_t head;
      char pad1[CACHE_LINE_SIZE - sizeof(uint64_t)];
      void* ptrExchange;
      uint64_t redOpArgExchange[2];
      char pad2[CACHE_LINE_SIZE - sizeof(void*) - 2 * sizeof(uint64_t)];
      int offsFifo[NCCL_STEPS];
    };
    char pad3[MEM_ALIGN];
  };
};

struct ncclRecvMem {
  union {
    struct {
      uint64_t tail;
      char pad1[CACHE_LINE_SIZE - sizeof(uint64_t)];
      struct ncclConnFifo connFifo[NCCL_STEPS];
      int flush; // For GDRCopy-based flush
    };
    char pad4[MEM_ALIGN];
  };
};

struct ncclConnFifo {
  int mode;
  ssize_t offset;
  ssize_t size;
  void* ptr;
};

协议选择逻辑

• 消息大小：小消息用 LL，中等用 LL128，大消息用 Simple。
• 拓扑结构：NVLink 连接适合 LL128，网络连接适合 Simple。
• 硬件能力：某些 GPU 架构对特定协议有优化。

场景驱动 Walkthrough：LL 协议的数据搬运

假设使用 LL 协议传输 1KB 数据。

第一步：数据写入发送缓冲区

主机侧将数据写入 sendbuff，然后更新 ncclSendMem.head 指针，通知 GPU kernel 有新数据。

第二步：GPU kernel 读取数据

GPU kernel 轮询 head 指针，发现新数据后，从 sendbuff 读取数据。

第三步：数据传输

GPU kernel 通过 NVLink 或网络将数据发送到目标 rank。

第四步：目标 rank 接收数据

目标 rank 的 GPU kernel 将数据写入 recvbuff，然后更新 ncclRecvMem.tail 指针。

第五步：主机侧读取数据

主机侧轮询 tail 指针，发现新数据后，从 recvbuff 读取数据。

并发控制与硬件交互

LL 协议的低延迟机制

LL128 协议的 128 字节对齐

• 减少部分缓存行写入（Partial Cache Line Write）
• 提高内存带宽利用率
• 简化硬件处理逻辑

Simple 协议的批量传输

生产避坑指南

踩坑场景一：协议与消息大小不匹配

踩坑场景二：LL128 对齐问题

踩坑场景三：协议切换开销

2.5 传输层 transport：P2P/SHM/NET/CollNet 底层搬运通道

直觉模型

从 A 点到 B 点可以走路、骑车、坐地铁或打车，NCCL 的传输层就是这些不同的「出行方式」。上层不关心具体怎么走，只关心能不能送到。P2P 是「走路」（同机 GPU 直连），SHM 是「骑车」（共享内存），NET 是「坐地铁」（网络），CollNet 是「打车」（网卡卸载）。

如果没有传输层抽象，上层算法需要针对每种物理链路写不同的代码，无法复用。

数据结构与内存布局

传输层枚举

📎 src/include/transport.h:18-23 定义了传输层类型：

#define NTRANSPORTS 4
#define TRANSPORT_UNDEFINED -1
#define TRANSPORT_P2P 0
#define TRANSPORT_SHM 1
#define TRANSPORT_NET 2
#define TRANSPORT_COLLNET 3

传输层接口

📎 src/include/transport.h:129-146 定义了 ncclTransportComm——传输层的通信接口：

struct ncclTransportComm {
  ncclResult_t (*setup)(struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo*, struct ncclPeerInfo*,
                        struct ncclConnect*, struct ncclConnector*, int channelId, int connIndex);
  ncclResult_t (*connect)(struct ncclComm* comm, struct ncclConnect*, int nranks, int rank, struct ncclConnector*);
  ncclResult_t (*free)(struct ncclComm* comm, struct ncclConnector*);
  ncclResult_t (*proxySharedInit)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState,
                                  int nChannels);
  ncclResult_t (*proxySetup)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState, void* reqBuff,
                             int reqSize, void* respBuff, int respSize, int* done);
  ncclResult_t (*proxyConnect)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState, void* reqBuff,
                               int reqSize, void* respBuff, int respSize, int* done);
  ncclResult_t (*proxyFree)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState);
  ncclResult_t (*proxyProgress)(struct ncclProxyState* proxyState, struct ncclProxyArgs*);
  ncclResult_t (*proxyRegister)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState,
                                void* reqBuff, int reqSize, void* respBuff, int respSize, int* done);
  ncclResult_t (*proxyDeregister)(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState,
                                  void* reqBuff, int reqSize, int* done);
};

关键回调解析

• setup：建立连接前的准备工作，交换连接参数。
• connect：实际建立连接。
• free：释放连接资源。
• proxySharedInit：初始化 proxy 线程共享资源。
• proxySetup / proxyConnect：proxy 线程侧的连接建立。
• proxyProgress：proxy 线程推进数据传输。
• proxyRegister / proxyDeregister：内存注册和注销。

传输层结构体

📎 src/include/transport.h:148-154 定义了 ncclTransport：

struct ncclTransport {
  const char name[8];
  ncclResult_t (*canConnect)(int*, struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo*,
                             struct ncclPeerInfo*);
  struct ncclTransportComm send;
  struct ncclTransportComm recv;
};

传输层实例

📎 src/include/transport.h:36-36 声明了四个传输层实例：

extern struct ncclTransport p2pTransport;
extern struct ncclTransport shmTransport;
extern struct ncclTransport netTransport;
extern struct ncclTransport collNetTransport;

📎 src/include/transport.h:36-36 定义了传输层数组：

extern struct ncclTransport* ncclTransports[];

对等节点信息

📎 src/include/transport.h:46-74 定义了 ncclPeerInfo——rank 之间交换的元数据：

struct ncclPeerInfo {
  int rank;
  int cudaDev;
  int nvmlDev;
  int gdrSupport;
  uint64_t hostHash;
  uint64_t pidHash;
  dev_t shmDev;
  int64_t busId;
  cudaUUID_t gpuUuid;
  struct ncclComm* comm;
  int cudaCompCap;
  int gpuCftSupport;
  size_t totalGlobalMem;
  // MNNVL support
  nvmlGpuFabricInfoV_t fabricInfo;
  int fabricHandleSupport;
  int cuMemSupport;
  int version;
  uint64_t supportedGinTypeBitMask;
  bool crossNicSupport;
  bool rmaPluginAvailable;
  bool cuMemGdrSupport;
  int mloPart; // MLOPart partition index, or -1 if not an MLOPart GPU
  int cudaDriverVersion;
  bool gpuCftMulticastSupport;
  bool gpuCftCountedSupport;
  uint32_t gitVersionHash;
};

• hostHash 相同 → 同一主机 → 可用 P2P 或 SHM
• hostHash 不同 → 不同主机 → 必须用 NET
• gdrSupport → 是否支持 GPUDirect RDMA
• cudaCompCap → GPU 计算能力，影响协议选择

场景驱动 Walkthrough：建立 P2P 连接

假设两个 rank 在同一主机内，NCCL 选择 P2P 传输层。

第一步：交换 PeerInfo

两个 rank 通过 bootstrap 通道交换 ncclPeerInfo，确认彼此在同一主机、GPU 支持 P2P。

第二步：调用 canConnect

📎 src/include/transport.h:148-154 的 canConnect 回调被调用，检查拓扑图确认两个 GPU 之间有 NVLink 或 PCIe 连接。

第三步：调用 setup

p2pTransport.send.setup 和 p2pTransport.recv.setup 被调用，准备连接参数（如 IPC 句柄）。

第四步：调用 connect

p2pTransport.send.connect 和 p2pTransport.recv.connect 被调用，实际建立连接。

第五步：注册内存

如果需要 RDMA，调用 proxyRegister 注册发送和接收缓冲区。

并发控制与硬件交互

P2P 传输层

• 两个 GPU 在同一 PCIe 域或 NVLink 域
• 操作系统支持 CUDA IPC
• 足够的权限

SHM 传输层

NET 传输层

• 网络设备支持 GPUDirect RDMA（可选，但推荐）
• 正确的网络配置（IP 地址、子网掩码等）
• 足够的网络带宽

CollNet 传输层

• 支持 SHARP 的网卡
• 正确的 SHARP 配置

生产避坑指南

踩坑场景一：P2P 不可用

踩坑场景二：网络配置错误

踩坑场景三：GPUDirect RDMA 未启用

2.6 五件套如何组合：一次通信的完整生命周期

组合关系图

flowchart TD
    api["ncclAllReduce(sendbuff, recvbuff, count, ...)"] --> comm_lookup["查找 ncclComm"]
    comm_lookup --> task_create["创建 ncclTaskColl"]
    task_create --> tuning{"tuning 模块选择算法和协议"}
    tuning -->|"小消息"| tree_ll["Tree + LL"]
    tuning -->|"中等消息"| ring_ll128["Ring + LL128"]
    tuning -->|"大消息"| ring_simple["Ring + Simple"]
    tuning -->|"NVLS 可用"| nvls["NVLS + Simple"]
    tree_ll --> channel_assign["分配通道"]
    ring_ll128 --> channel_assign
    ring_simple --> channel_assign
    nvls --> channel_assign
    channel_assign --> transport_select{"选择传输层"}
    transport_select -->|"同机 GPU 直连"| p2p["P2P"]
    transport_select -->|"同机无直连"| shm["SHM"]
    transport_select -->|"跨机"| net["NET"]
    transport_select -->|"CollNet 可用"| collnet["CollNet"]
    p2p --> kernel_launch["启动 GPU kernel"]
    shm --> kernel_launch
    net --> kernel_launch
    collnet --> kernel_launch
    kernel_launch --> execute["执行通信"]
    execute --> complete["完成，更新 asyncResult"]

完整生命周期

阶段一：API 调用

用户调用 ncclAllReduce，传入发送缓冲区、接收缓冲区、元素数、数据类型、归约操作、通信域、CUDA stream。

阶段二：任务创建

NCCL 创建 ncclTaskColl 结构体（📎 src/include/comm.h:212-273），填充 func（AllReduce）、sendbuff、recvbuff、count、datatype、opHost 等字段。

阶段三：算法和协议选择

Tuning 模块根据消息大小、拓扑结构、硬件能力选择算法（Ring/Tree/NVLS）和协议（LL/LL128/Simple）。选择结果写入 ncclTaskColl 的 algorithm 和 protocol 字段（📎 src/include/comm.h:227-227）。

阶段四：通道分配

根据算法和协议，确定使用的通道数和通道范围。nChannels、channelLo、channelHi 字段被设置（📎 src/include/comm.h:254-257）。

阶段五：传输层选择

根据拓扑图，为每对 rank 选择传输层（P2P/SHM/NET/CollNet）。连接信息存储在 channels[i].peers[j] 中。

阶段六：Kernel 启动

NCCL 构建 ncclKernelPlan（📎 src/include/comm.h:357-410），包含工作队列、清理队列、任务队列等。然后启动 GPU kernel。

阶段七：执行通信

GPU kernel 读取工作 FIFO，执行数据传输和归约操作。Proxy 线程异步推进网络 I/O。

阶段八：完成

所有通道完成后，asyncResult 被设置为 ncclSuccess。用户可以通过 ncclCommGetAsyncError 查询状态。

设计思考

为什么需要五件套？

• ncclComm：解决「谁和谁通信」的问题。
• channel：解决「如何并行」的问题。
• algorithm：解决「用什么拓扑」的问题。
• protocol：解决「用什么策略」的问题。
• transport：解决「走什么物理链路」的问题。

它们正交组合，让 NCCL 能够适应各种硬件配置和消息大小，而不需要为每种组合写专门的代码。

组合的灵活性

• 算法：5 种（Tree/Ring/CollNet/NVLS/PAT）
• 协议：3 种（LL/LL128/Simple）
• 传输层：4 种（P2P/SHM/NET/CollNet）

本章思考与自测

<details><summary>Q1: 如果将 📎 src/include/comm.h:731-731 中的 intraPad1[64 - sizeof(uint64_t)] 改为 intraPad1[0]（即去掉缓存行填充），在多进程场景下会出现什么性能问题？为什么？</summary>

参考解析：

去掉填充后，intraBarrierPhase、intraBarrierCounter、intraBarrierGate 三个字段会紧密排列在内存中，很可能共享同一个缓存行（通常 64 字节）。

在多进程场景下，每个进程有自己的 ncclComm 副本，但 intraComm0 指向的 leader 通信域的 intraBarrierCounter 和 intraBarrierGate 会被所有进程读写。当进程 A 调用 ncclCommIntraBarrierIn 更新 intraBarrierCounter（📎 src/include/comm.h:943-959）时，会导致进程 B 的 intraBarrierGate 缓存行失效。进程 B 在 ncclCommIntraBarrierOut 中轮询 intraBarrierGate（📎 src/include/comm.h:962-977），每次缓存失效都要重新从内存加载，延迟从纳秒级上升到微秒级。

这就是伪共享（False Sharing）问题。填充 56 字节确保每个字段独占一个缓存行，消除伪共享。

</details>

<details><summary>Q2: 如果将 📎 src/include/collectives.h:106-108 的 incRefCount 从 memory_order_relaxed 改为 memory_order_seq_cst，会有什么影响？为什么作者选择 relaxed？</summary>

参考解析：

memory_order_seq_cst 会强制全局顺序一致性，每次增加引用计数都要插入内存屏障，导致性能下降。

incRefCount 只需要保证原子性，不需要同步其他内存操作。因为增加引用计数不会触发对象销毁，也不会依赖其他线程的写操作。memory_order_relaxed 正好满足这个需求——只保证原子性，不插入屏障。

相比之下，decRefCount（📎 src/include/collectives.h:109-111）使用 memory_order_release，因为减少引用计数可能触发对象销毁，需要确保之前的写操作对其他线程可见。

这是 C++ 内存模型的经典应用：根据操作语义选择最弱的内存序，在保证正确性的前提下最大化性能。

</details>

<details><summary>Q3: 如果将 📎 src/include/channel.h:32-32 的 reverseBits(base, log2Up(comm->p2pnChannels)) 改为直接返回 base % comm->p2pnChannels，在什么场景下会导致性能下降？为什么？</summary>

参考解析：

reverseBits 是位反转操作，用于打散通道分配。直接取模会导致通道分配呈现规律性：round 0 用通道 0，round 1 用通道 1，...，round N 用通道 N%p2pnChannels。

在多节点场景下，如果多个 rank 的 P2P 通信同时进行，规律性的通道分配会导致热点集中——某些通道被多个 rank 同时使用，而其他通道空闲。这会造成链路拥塞，降低整体带宽利用率。

reverseBits 打散了通道分配，让不同 round 使用看似随机的通道，均匀分布负载。这是负载均衡的经典手法。

另外，reverseBits 是纯位操作，比取模运算更快（取模需要除法指令，位操作只需几条指令）。

</details>

---

下一章我们将深入 ncclCommInitRank 的内部实现，看看 NCCL 如何从一个空的 ncclComm 结构体开始，逐步建立拓扑图、初始化通道、建立传输连接，最终构建出一个可用的通信域。本章建立的五件套心智模型，将在下一章中逐一落地。

这五个抽象并非孤立存在：通信域是容器，通道是并行执行的单位，算法决定数据如何规约，协议规定数据如何编码，传输层负责数据如何移动。它们的组合——5 个维度、每个维度 3 到 4 种选择——构成了 NCCL 性能调优的搜索空间。那么，这个通信域对象究竟是如何从零开始被构建出来的？下一章我们将深入 ncclCommInitRank 的调用链，看 NCCL 如何在初始化阶段完成设备探测、拓扑发现与通道分配，并揭示 comm->rank、comm->nRanks、comm->channels 等关键字段的赋值时机。

第 3 章：初始化入局：ncclCommInitRank 如何把一群孤立进程建立成通信域

上一章我们建立了贯穿全书的五个核心抽象：ncclComm、channel、algorithm、protocol 和 transport，它们共同构成了「一次通信 = 若干 channel × 一个 algorithm × 一个 protocol × 若干 transport」的公共词汇表。现在，我们要回答一个更根本的问题：这个 ncclComm 对象究竟是如何从无到有构建出来的？当你调用 ncclCommInitRank 时，NCCL 需要在几百毫秒内完成一系列复杂操作：确认所有 rank 到齐、交换设备信息、探测机器拓扑、计算数据路径、分配 GPU 显存与主机内存，最终将这一切打包成一个 ncclComm 对象。本章将沿着这条调用链，从 API 入口一路下钻到 initTransportsRank 的最后一根毛细血管。

3.1 API 入口：ncclCommInitRank 的同步外壳与异步内核

直觉模型

ncclCommInitRank 表面上是"建一个通信域"，实际上它做的是"发起一个后台任务，然后（默认情况下）等它完成"。这就像你去餐厅点餐：点餐这个动作（API 调用）瞬间返回，但厨房做菜（真正的初始化）是在后台进行的。默认的"阻塞模式"只是让你在柜台前等到菜做好，而"非阻塞模式"则给你一个取餐号，你可以先去干别的。

如果没有这层异步设计，NCCL 在初始化期间就无法与 CUDA Graph 捕获、多通信域并行初始化等场景配合——所有初始化都会变成串行的、无法与用户代码重叠的阻塞操作。

数据结构与内存布局

先看 API 入口本身。ncclCommInitRank 是一个极薄的同步外壳：

📎 src/init.cc:2946-2970

它做了四件事：调用 ncclInitEnv() 加载环境变量插件、打开 NVTX 性能标记、读取当前 CUDA 设备号、然后调用 ncclGroupStartInternal() 进入 group 语义，最后把实际工作委托给 ncclCommInitRankDev。

注意 ncclGroupStartInternal() / ncclGroupEndInternal() 这一对调用——即使你只初始化一个通信域，NCCL 也把它包在 group 语义里。这是为了统一处理"用户在一个 group 里初始化多个通信域"的场景，避免为单通信域和多通信域写两套代码路径。

真正的参数校验和对象分配在 ncclCommInitRankDev 里：

📎 src/init.cc:2851-2943

这个函数是整条链路的"总调度台"。它先做参数校验（nId 范围、nranks/myrank 合法性），然后分配 ncclComm 结构体本身，以及三个与中止机制相关的字段：abortFlag（主机侧原子标志）、abortFlagDev（设备侧可见的固定内存副本）、abortFlagRefCount（引用计数，因为 split 出来的子通信域可能共享父通信域的 abortFlag）。

这里有一个值得注意的细节——comm->startMagic = comm->endMagic = NCCL_MAGIC：

📎 src/init.cc:2886-2886

这对 magic 值像"封条"一样夹在 ncclComm 结构体的首尾。任何越界写入或结构体损坏都会破坏这对 magic，后续操作可以通过校验它们来检测内存踩踏。这是一种廉价但有效的内存完整性防护。

Step-by-Step Walkthrough

当 ncclCommInitRankDev 走到最后，它构造一个 ncclCommInitRankAsyncJob 并启动异步任务：

📎 src/init.cc:2896-2929

job 结构体承载了所有初始化所需的参数。注意 job->commId 是拷贝出来的，而不是直接引用用户传入的 commId：

📎 src/init.cc:2903-2910

为什么要拷贝？源码注释给出了答案：ncclUniqueId 和 ncclBootstrapHandle 的对齐要求不同，用户传入的数组可能没有正确对齐到 ncclBootstrapHandle 所需的边界。拷贝到新分配的内存可以保证对齐。这是一个典型的"ABI 兼容性陷阱"——用户看到的是 ncclUniqueId，内部要当 ncclBootstrapHandle 用，两者大小相同但对齐不同。

最后，根据 ncclParamEnqueueRearchEnable() 的值，任务要么进入管理队列，要么直接通过 ncclAsyncLaunch 启动：

📎 src/init.cc:2922-2929

ncclAsyncLaunch 会创建一个新线程执行 ncclCommInitRankFunc。如果是阻塞模式（默认），调用方会在 ncclGroupEndInternal() 里等待这个线程完成；如果是非阻塞模式，调用方立即返回，用户后续通过 ncclCommGetAsyncError 轮询状态。

设计思考

这里的设计核心是"同步 API + 异步实现"。为什么不让 ncclCommInitRank 直接同步执行所有初始化？因为 NCCL 需要支持 ncclCommInitRankConfig 的非阻塞模式，而非阻塞模式要求初始化在后台线程运行。如果同步路径和异步路径是两套代码，维护成本会翻倍。统一走异步、同步路径只是"启动后立即等待"，代码只有一份。

flowchart TD
    api["ncclCommInitRank(newcomm, nranks, commId, myrank)"]
    env["ncclInitEnv() 加载环境变量插件"]
    group["ncclGroupStartInternal()"]
    dev["ncclCommInitRankDev(...)"]
    check{"nId/nranks/myrank 合法?"}
    alloc["ncclCalloc 分配 comm + abortFlag"]
    parse["parseCommConfig() 解析配置"]
    job["构造 ncclCommInitRankAsyncJob"]
    copyid["拷贝 commId 保证对齐"]
    enq{"ncclParamEnqueueRearchEnable()?"}
    mgmt["ncclMgmtTaskEnqueue()"]
    async["ncclAsyncLaunch() 启动后台线程"]
    func["ncclCommInitRankFunc() 执行初始化"]
    fail["返回 ncclInvalidArgument"]

    api --> env --> group --> dev --> check
    check -->|否| fail
    check -->|是| alloc --> parse --> job --> copyid --> enq
    enq -->|是| mgmt --> func
    enq -->|否| async --> func

3.2 Bootstrap：rank 之间的第一条控制通道

直觉模型

Bootstrap 是 NCCL 的"会前微信群"。在正式通信开始之前，所有 rank 需要先建立一条控制通道，用来交换"我是谁、我在哪台机器、我的 GPU 是什么型号、我的网卡地址是什么"这些元数据。没有 bootstrap，rank 之间就是一群互不相识的陌生人，无法协调任何通信。

如果 bootstrap 失败或超时，整个通信域初始化就会卡死——这是生产环境中最常见的 NCCL 挂起原因之一。

数据结构与内存布局

Bootstrap 的核心状态保存在 bootstrapState 结构体中：

📎 src/bootstrap.cc:527-546

这个结构体有几个关键字段值得展开：

• ring：一个联合体，要么是网络设备句柄（net.sendComm/net.recvComm），要么是一对 socket（socket.send/socket.recv）。这对应两种 bootstrap 模式：基于 socket 的默认模式和基于网络设备的 NCCL_OOB_NET_ENABLE 模式。
• listen：监听端信息，同样有网络和 socket 两种形态。
• peerP2pAddresses / peerProxyAddresses：所有 rank 的 P2P 地址和 proxy 地址数组，通过 ring allgather 填充。
• unexpectedConnections：一个链表，缓存"收到了但还没被匹配"的连接。这是 bootstrap 协议的一个关键设计——因为接收方无法预知谁会先连过来，所以必须先把不匹配的连接存起来。
• asyncSendQueue + asyncSendLock + asyncSendCond：异步发送队列及其同步原语，用于 TLS 加密模式下的并发发送。

bootstrapState 的分配发生在 bootstrapInit 开头：

📎 src/bootstrap.cc:769-776

注意 comm->bootstrap = state 这一行——bootstrap 状态被挂到通信域上，后续所有 bootstrap 操作都通过 comm->bootstrap 访问。

Step-by-Step Walkthrough

bootstrapInit 是 bootstrap 的主干函数。让我们按执行顺序拆解：

第一步：确定 magic 值。 magic 是 bootstrap 通信的"暗号"，只有持有相同 magic 的 rank 才能互相连接。

📎 src/bootstrap.cc:778-788

如果是正常初始化（handles != NULL），magic 来自第一个 handle；如果是 split/grow（parent != NULL），magic 通过 hashCombine(parent->magic, parent->childCount) 派生。这保证了每个子通信域有唯一的 magic。

第二步：创建监听 socket。 每个 rank 需要两个监听端点：一个用于 ring 邻居连接（STATE_LISTEN(state, socket)），一个用于 root 连接（listenSockRoot）：

📎 src/bootstrap.cc:797-831

这里有一个关键的分工：ring 监听 socket 使用 comm->magic，而 root 监听 socket 使用 BOOTSTRAP_HANDLE(handles, curr_root)->magic。为什么？因为 root 是全局协调者，所有 rank 都要连它，所以它用统一的 magic；而 ring 邻居是点对点的，用通信域自己的 magic 就够了。

第三步：错峰连接。 当 rank 数量很大时，所有 rank 同时连 root 会造成连接风暴。NCCL 用 NCCL_UID_STAGGER_RATE 和 NCCL_UID_STAGGER_THRESHOLD 来控制错峰：

📎 src/bootstrap.cc:833-843

当某个 root 负责的 rank 数超过阈值（默认 256）时，每个 rank 根据自己在 root 下的局部 ID 计算延迟微秒数，然后 sleep。这是一个简单但有效的"令牌桶"式限流。

第四步：向 root 发送自己的连接信息。 每个 rank 把自己的监听地址发给 root：

📎 src/bootstrap.cc:845-867

root 收到所有 rank 的信息后，会做一次"环形配对"——把 rank i 的地址发给 rank i-1，把 rank i+1 的地址发给 rank i。这样每个 rank 就知道了自己 ring 上的前后邻居。

第五步：建立 ring 连接。 每个 rank 连接自己的"下一个"邻居，同时接受"上一个"邻居的连接：

📎 src/bootstrap.cc:885-894

这里 socketRingConnect 内部使用了 bootstrapConcurrent——在 TLS 加密模式下，connect 和 accept 必须并发执行，否则会死锁（因为 TLS 握手需要双方同时参与）。非加密模式下则串行执行 connect 再 accept。

第六步：AllGather 所有地址。 ring 建立后，通过 ringAllInfo 把所有 rank 的 P2P 地址、proxy 地址、UDS 地址做一次 allgather：

📎 src/bootstrap.cc:934-938

ringAllInfo 内部调用 bootstrapAllGather，后者在 socket 模式下使用 socketRingAllGather——一个双向 ring allgather 算法，N 个 rank 只需要 N/2 步：

📎 src/bootstrap.cc:1363-1412

这个双向算法是 bootstrap 性能的关键优化。传统的单向 ring allgather 需要 N-1 步，双向版本把步数减半。每一步同时向两个方向发送和接收数据，用 socketDoubleSendRecv 把 4 个操作（2 发 2 收）打包成一次系统调用。

并发控制与底层交互

Bootstrap 的并发控制有几个层次：

第一层：abort 检查。 所有阻塞循环都定期检查 abortFlag：

📎 src/bootstrap.cc:150-159

BOOTSTRAP_N_CHECK_ABORT 设为 10000，意味着每 10000 次循环检查一次 abort 标志。这个数字是性能与响应性的折中——检查太频繁会影响性能，检查太少会导致 abort 响应延迟。

第二层：异步发送队列。 在 TLS 加密模式下，bootstrapSend 不能同步执行（因为 TLS 握手需要接收方也参与），所以 NCCL 把发送操作放到独立线程：

📎 src/bootstrap.cc:1161-1217

这里有一个精妙的顺序保证机制。bootstrapAsyncSendMain 在发送前会检查队列中是否有"更早的、发往同一 (peer, tag) 的发送"：

📎 src/bootstrap.cc:1124-1152

为什么要保证同一 (peer, tag) 的发送顺序？源码注释解释得很清楚：接收方按 (peer, tag) 匹配连接，如果两个发往同一 (peer, tag) 的消息到达顺序颠倒，接收方会把它们匹配错。NVLS 初始化期间会多次向同一 peer 用同一 tag 广播，所以这个顺序保证是必须的。

第三层：意外连接队列。 接收方无法预知谁会先连过来，所以 socketAccept 会把不匹配的连接存入 unexpectedConnections 链表：

📎 src/bootstrap.cc:1276-1300

这个设计解决了一个经典的分布式问题：多个 rank 可能同时向你发起连接，但你的 bootstrapRecv 调用顺序是固定的。如果不匹配的连接被直接丢弃，发送方会超时；如果阻塞等待，又可能死锁。存入队列是最安全的做法。

生产避坑指南

坑一：bootstrap 超时导致初始化挂起。 如果某个 rank 因为网络问题无法连接到 root，其他所有 rank 都会在 ncclSocketAccept 或 ncclSocketRecv 上无限等待。NCCL 没有内置的 bootstrap 超时机制，唯一的逃生通道是 abortFlag。生产环境中建议设置 NCCL_UID_STAGGER_RATE 来缓解大规模集群的连接风暴。

坑二：NCCL_COMM_ID 与多 handle 冲突。 当用户设置 NCCL_COMM_ID 环境变量时，NCCL 会强制把 nId 降为 1：

📎 src/init.cc:2912-2921

这意味着 ncclCommInitRankScalable 的多 handle 特性会被静默禁用。如果你在用 scalable 初始化又设了 NCCL_COMM_ID，行为会和你预期的不一样。

坑三：TLS 模式下的死锁。 在 TLS 加密模式下，如果 connect 和 accept 不并发执行，双方都会卡在 TLS 握手。bootstrapConcurrent 就是为了解决这个问题：

📎 src/bootstrap.cc:648-669

非加密模式下串行执行（先 send 后 recv），加密模式下启动一个线程处理 send，主线程处理 recv。

sequenceDiagram
    participant R0 as Rank 0
    participant Root as Bootstrap Root
    participant R1 as Rank 1
    participant R2 as Rank 2

    R0->>Root: sendToRoot(extInfo{rank=0, listenAddr})
    R1->>Root: sendToRoot(extInfo{rank=1, listenAddr})
    R2->>Root: sendToRoot(extInfo{rank=2, listenAddr})
    Note over Root: 收集所有 rank 的监听地址
    Root-->>R0: rootSend(rank2.addr) 下一个邻居
    Root-->>R1: rootSend(rank0.addr) 下一个邻居
    Root-->>R2: rootSend(rank1.addr) 下一个邻居
    R0->>R1: socketRingConnect(connect to next)
    R1->>R2: socketRingConnect(connect to next)
    R2->>R0: socketRingConnect(connect to next)
    Note over R0,R2: Ring 建立完成
    R0->>R1: socketRingAllGather 双向交换
    R1->>R2: socketRingAllGather 双向交换
    R2->>R0: socketRingAllGather 双向交换
    Note over R0,R2: 所有地址交换完成

3.3 commAlloc：通信域对象的内存骨架

直觉模型

commAlloc 是通信域的"毛坯房交付"——它分配结构体内存、初始化所有字段到安全默认值、创建必要的 CUDA 对象和同步原语，但还没有填充拓扑信息、通道配置、传输连接这些"精装修"内容。如果把 ncclComm 比作一栋大楼，commAlloc 就是打地基和浇筑框架，initTransportsRank 才是内部装修。

如果没有 commAlloc 的初始化，后续代码访问未初始化的字段会导致不可预测的行为——比如 comm->channels[c].id 如果是随机值，通道初始化逻辑就会误判通道状态。

数据结构与内存布局

commAlloc 的签名和开头校验：

📎 src/init.cc:512-526

它首先校验 ndev 和 rank 的合法性，然后构造两个内存栈（memPermanent 和 memScoped），设置 rank 和 nRanks。这两个内存栈是 NCCL 的内存管理基础设施——memPermanent 用于生命周期与通信域相同的分配，memScoped 用于临时分配。

接下来是 CUDA 设备探测：

📎 src/init.cc:528-531

cudaGetDevice 获取当前设备号，ncclCudaCompCap 获取计算能力。源码注释说得很直白："Try to create a CUDA object right away. If there is something wrong with the device we're on, better know it early."——尽早暴露设备问题，避免在初始化后期才发现。

然后是共享资源的分配或继承：

📎 src/init.cc:533-555

这里有一个重要的分支：如果 parent == NULL || !parent->shareResources，就创建新的 ncclSharedResources；否则继承父通信域的共享资源并增加引用计数。ncclSharedResources 包含设备流、主机流、启动事件、scratch 事件等——这些资源在 split 场景下可以被子通信域复用，避免重复创建。

注意 sharedRes->refCount = 1 这一行——初始引用计数为 1，每次 split 共享时递增，最后一个引用释放时才真正销毁。

接下来是网络、RMA、GIN 的初始化：

📎 src/init.cc:547-549

这三个子系统分别负责网络传输、远程内存访问、GPU 发起的网络通信。它们的初始化顺序有讲究——ncclNetInit 必须先于 ncclRmaInit，因为 RMA 依赖网络插件。

内存管理器的初始化：

📎 src/init.cc:567-576

同样有共享/新建两种路径。ncclMemManager 负责管理 CUDA 内存池和注册缓存。

通道初始化标记：

📎 src/init.cc:607-608

这一行把所有通道的 id 设为 -1，表示"未初始化"。后续 setupChannel 会检查这个值来决定是否需要初始化。

中断队列的构造：

📎 src/init.cc:619-632

NCCL 使用侵入式队列（intrusive queue）来管理各种任务。这些队列在 commAlloc 阶段全部构造为空，后续任务入队时直接使用。

CUDA 内存池的创建：

📎 src/init.cc:636-652

如果设备支持内存池（cudaDevAttrMemoryPoolsSupported），就创建一个 pinned 类型的内存池，并把释放阈值设为最大值（~uint64_t(0)），意思是"永远不自动释放"。这是为了避免 CUDA 运行时在 NCCL 不知情的情况下回收内存。

Step-by-Step Walkthrough

让我们跟踪一个具体的初始化场景：单机 8 卡，每个进程一个 rank，正常初始化。

1. commAlloc(comm, NULL, 8, rank) 被调用，parent == NULL。

2. 校验通过，comm->rank = rank，comm->nRanks = 8。

3. cudaGetDevice 返回当前设备号，comm->compCap 被设置。

4. 创建新的 ncclSharedResources，引用计数为 1。

5. ncclNetInit 初始化网络插件（可能是 Socket 或 IB）。

6. ncclMemManagerInit 创建内存管理器。

7. getBusId 获取 PCI 总线 ID，ncclNvmlDeviceGetHandleByPciBusId 获取 NVML 句柄。

8. dmaBufSupported 检测 DMA-BUF 支持。

9. 分配 connectSend / connectRecv 位图数组。

10. 所有通道 id 设为 -1。

11. 构造所有中断队列。

12. 创建 CUDA 内存池。

设计思考

commAlloc 中最值得玩味的设计是"尽早失败"原则。它在函数开头就调用 cudaGetDevice，而不是等到后面需要设备信息时再调用。这样做的好处是：如果设备有问题（比如被其他进程独占），错误会在初始化早期就暴露，而不是在分配了大量内存之后才发现。

另一个设计是 preconnectNext 的初始化：

📎 src/init.cc:598-598

reinterpret_cast<struct ncclComm*>(0x1) 是一个哨兵值，用于标记"下一个预连接"的状态。这种用非法指针值作为状态标记的手法在系统编程中很常见——它比额外的布尔字段更省内存，但需要小心不要解引用。

3.4 initTransportsRank：拓扑发现与通道分配

直觉模型

initTransportsRank 是初始化的"心脏"。它做三件大事：通过两次 AllGather 交换所有 rank 的设备信息和拓扑信息；根据这些信息计算 ring/tree/collnet/nvls 等算法的图结构；最后建立所有传输连接。如果把通信域比作一个城市的交通系统，initTransportsRank 就是规划所有道路、立交桥和公交线路的过程。

如果没有这一步，NCCL 就不知道数据该走哪条路——它可能让数据绕远路，或者根本找不到可达的路径。

数据结构与内存布局

initTransportsRank 的局部变量非常多，我们挑关键的看：

📎 src/init.cc:1163-1179

这里把 comm->graphs 数组中的各个图结构取出来，建立别名。graphs 数组按算法索引，注意 nvlsGraph 被用了两次（NVLS 和 NVLSTree 共享同一个图结构）。

两个关键的临时结构体：

📎 src/init.cc:1181-1206

graphInfo 保存单个 rank 对某个算法的图信息（通道数、带宽、类型等），allGatherInfo 是 AllGather 的数据单元，包含所有算法的图信息加上拓扑 rank 信息。

Step-by-Step Walkthrough

阶段一：AllGather1——交换设备信息。

📎 src/init.cc:1234-1239

每个 rank 调用 fillInfo 填充自己的 ncclPeerInfo，然后通过 bootstrapAllGather 交换。fillInfo 填充的信息包括：rank 号、CUDA 设备号、NVML 设备号、NCCL 版本、git hash、主机 hash、进程 hash、GPU UUID、总线 ID、显存大小、驱动版本等。

📎 src/init.cc:888-982

注意 info->hostHash = getHostHash() + commHash 和 info->pidHash = getPidHash() + commHash——host hash 和 pid hash 都加上了 commHash。这是为了区分同一台机器上的不同通信域。

AllGather 完成后，每个 rank 遍历所有 peer 的信息，计算全局属性：

📎 src/init.cc:1250-1303

这个循环做了很多事：检测版本不匹配、统计节点数、计算 cuMemSupport 的交集、检测是否有多个 rank 使用同一个 GPU、计算 GIN 类型掩码的交集等。注意 nNodes 的统计方式——每当遇到不同 hostHash 就递增，这假设 rank 是按节点连续排列的。

阶段二：拓扑发现。

📎 src/init.cc:1390-1403

这六步是拓扑发现的核心流程：ncclTopoGetSystem 枚举系统设备构建拓扑图，ncclTopoComputePaths 计算 GPU 到 NIC 的路径，ncclTopoTrimSystem 移除不可达设备，再次计算路径，ncclTopoSearchInit 初始化搜索状态，最后打印拓扑。

阶段三：图计算。

📎 src/init.cc:1421-1468

依次计算 ring、tree、collnet chain、collnet direct、nvls 五种图。每种图有不同的 pattern 和通道数约束。注意 treeGraph->minChannels = ringGraph->nChannels——tree 的通道数被约束为与 ring 相同，这是为了保证不同算法之间的通道对齐。

阶段四：AllGather3——交换图信息。

📎 src/init.cc:1490-1533

每个 rank 把自己的图信息填入 allGather3Data[rank]，然后再次 bootstrapAllGather。这次交换的信息包括：每种算法的 pattern/nChannels/bwIntra/bwInter/typeIntra/typeInter/crossNic、CPU 架构、P2P 通道数、网络设备数、CollNet 设备数等。

AllGather3 完成后，每个 rank 遍历所有 peer 的图信息，取最小值/最大值来对齐：

📎 src/init.cc:1687-1703

注意这里的对齐策略：nChannels、sameChannels、bwIntra、bwInter 取最小值，typeIntra、typeInter、crossNic 取最大值。为什么？因为通道数和带宽受限于最弱的链路，而类型和 crossNic 需要取并集以确保兼容性。

阶段五：建立传输连接。

📎 src/init.cc:1811-1892

这里有两个分支：runtimeConn 为真时只做通道 setup 不做连接（延迟到运行时连接），否则立即建立所有连接。连接顺序是：ring → tree → NVLS → PAT → NVLS tree → CollNet。

并发控制与硬件交互

initTransportsRank 中有几个值得注意的并发/硬件交互点：

CPU 亲和性设置：

📎 src/init.cc:1406-1412

NCCL 把当前线程绑定到 GPU 附近的 CPU 核心，确保主机内存分配是本地 NUMA 节点的。这减少了跨 NUMA 访问的延迟。

NVLS 初始化：

📎 src/init.cc:1419-1419

ncclNvlsInit 检测 NVLink SHARP 支持。NVLS 允许交换机直接执行 reduce 操作，大幅降低 AllReduce 延迟。

Proxy 线程创建：

📎 src/init.cc:1780-1786

Proxy 线程负责异步推进网络 I/O。它在 initTransportsRank 中被创建，之后所有网络操作都通过 proxy 进行。

生产避坑指南

坑一：网络设备数不匹配。 如果不同 rank 的本地网卡数量不同，NCCL 会报错：

📎 src/init.cc:1576-1596

除非设置 NCCL_IGNORE_NET_MISMATCH=1。这在异构集群中很常见——有些节点有 8 张网卡，有些只有 4 张。忽略不匹配可能导致性能下降，因为通道数会被最弱的节点限制。

坑二：多 rank 共用同一 GPU。 如果两个 rank 的 GPU UUID 相同，NCCL 会拒绝初始化：

📎 src/init.cc:1291-1296

除非设置 NCCL_MULTI_RANK_GPU_ENABLE=1。这个检查防止了用户误配置导致的性能问题。

坑三：CollNet 节点数不足。 CollNet 需要至少 NCCL_COLLNET_NODE_THRESHOLD 个节点才能启用：

📎 src/init.cc:1720-1728

默认阈值是 2。单节点环境下 CollNet 会被自动禁用。

flowchart TD
    start["initTransportsRank(comm, parent, timers)"]
    ag1["AllGather1: fillInfo + bootstrapAllGather"]
    check_ver{"版本匹配?"}
    fail_ver["返回 ncclInvalidUsage"]
    topo["ncclTopoGetSystem + ComputePaths + TrimSystem"]
    graphs["计算 ring/tree/collnet/nvls 图"]
    ag3["AllGather3: 交换图信息"]
    align["对齐 nChannels/bwIntra/bwInter"]
    setup["setupChannel 初始化所有通道"]
    conn_ring["ncclTransportRingConnect"]
    conn_tree["ncclTransportTreeConnect"]
    conn_nvls["ncclNvlsSetup + ncclNvlsBufferSetup"]
    conn_collnet{"collnetEnable?"}
    conn_collnet_yes["ncclCollNetSetup + BufferSetup"]
    devcomm["devCommSetup 映射到设备"]
    barrier["bootstrapIntraNodeBarrier"]
    done["初始化完成"]

    start --> ag1 --> check_ver
    check_ver -->|否| fail_ver
    check_ver -->|是| topo --> graphs --> ag3 --> align --> setup
    setup --> conn_ring --> conn_tree --> conn_nvls --> conn_collnet
    conn_collnet -->|是| conn_collnet_yes --> devcomm
    conn_collnet -->|否| devcomm
    devcomm --> barrier --> done

3.5 NCCL_PARAM：环境变量体系的编译期魔法

直觉模型

NCCL_PARAM 是 NCCL 的"配置开关工厂"。它用宏在编译期生成一个函数，运行时第一次调用时读取环境变量并缓存结果。这就像家里的电灯开关——你拨一下（调用函数），灯就亮了（返回配置值），之后开关状态被记住，不需要每次都重新拨。

如果没有这套机制，NCCL 就需要在每个使用配置的地方手动调用 getenv 并解析字符串，代码会变得极其冗长且容易出错。

数据结构与内存布局

NCCL_PARAM 宏的定义：

📎 src/include/param.h:22-31

这个宏展开后生成一个函数 ncclParam##name()，内部有三个静态变量：

• uninitialized = INT64_MIN：哨兵值，表示"尚未初始化"。
• noCache：三态标志，-1 表示未初始化，0 表示缓存，1 表示不缓存。
• cache：缓存的值，初始为 uninitialized。

函数逻辑是：如果 cache 还是 uninitialized，调用 ncclLoadParam 加载；否则直接返回 cache。COMPILER_EXPECT(..., false) 告诉编译器这个分支很少走，优化热路径。

ncclLoadParam 的实现：

📎 src/misc/param.cc:78-108

它用互斥锁保护整个加载过程，先检查 noCache 策略，再检查缓存是否有效，然后读取环境变量并解析。解析失败时使用默认值并打印警告。

Step-by-Step Walkthrough

以 NCCL_PARAM(BuffSize, "BUFFSIZE", -2) 为例：

📎 src/init.cc:1007-1007

宏展开后生成：

int64_t ncclParamBuffSize() {
  constexpr int64_t uninitialized = INT64_MIN;
  static int8_t noCache = -1;
  static_assert(-2 != uninitialized, "...");
  static int64_t cache = uninitialized;
  if (COMPILER_EXPECT(COMPILER_ATOMIC_LOAD(&cache, std::memory_order_relaxed) == uninitialized, false)) {
    return ncclLoadParam("NCCL_BUFFSIZE", -2, uninitialized, &cache, &noCache);
  }
  return cache;
}

第一次调用时，cache == uninitialized，进入 ncclLoadParam。它读取 NCCL_BUFFSIZE 环境变量，如果没设置就返回默认值 -2。然后根据 noCache 策略决定是否缓存。

noCache 策略由 ncclParamIsCacheDisabled 决定：

📎 src/misc/param.cc:74-76

如果环境变量名匹配某个模式（比如以 _ 结尾），就不缓存，每次都重新读取。这允许用户在运行时动态修改某些配置。

设计思考

这套设计的精妙之处在于"零成本抽象"：热路径上只有一次原子加载和比较，没有锁、没有字符串解析。冷路径（首次加载）才付出完整代价。COMPILER_EXPECT 提示编译器把热路径放在指令缓存的前面，进一步提高性能。

另一个设计是 noCache 的三态设计。-1 表示"还没决定"，0 表示"缓存"，1 表示"不缓存"。这个决定只在首次加载时做一次，之后不再改变。

生产避坑指南

坑一：环境变量拼写错误。 如果用户写了 NCCL_BUFSIZE 而不是 NCCL_BUFFSIZE，NCCL 不会报错，只会使用默认值。建议用 NCCL_DEBUG=ENV 查看所有被识别的环境变量。

坑二：NCCL_CONF_FILE 的加载顺序。 NCCL 会依次加载 $NCCL_CONF_FILE（或 ~/.nccl.conf）和 /etc/nccl.conf：

📎 src/misc/param.cc:52-67

后加载的文件会覆盖先加载的。如果两个文件都设置了同一个变量，/etc/nccl.conf 的值会生效。

坑三：noCache 变量的线程安全。 源码注释说 "noCache is only load/stored within the mutex, no need for atomic"：

📎 src/misc/param.cc:74-76

这意味着 noCache 的读写都在互斥锁保护下，不需要原子操作。但 cache 的读取是无锁的（热路径），所以用原子加载。

3.6 devCommSetup：把通信域映射到设备

直觉模型

devCommSetup 是通信域的"设备侧投影"。GPU kernel 运行在设备上，无法直接访问主机内存中的 ncclComm 结构体。所以 NCCL 需要把通信域的关键字段拷贝到设备可访问的内存中，形成 ncclDevComm。这就像把公司的通讯录复印一份放到每个员工的工位上——员工不用每次都跑去找前台问同事电话。

如果没有 devCommSetup，GPU kernel 就无法知道自己的 rank、通道配置、缓冲区大小等信息，集合通信 kernel 根本无法启动。

数据结构与内存布局

devCommSetup 使用一个临时结构体 ncclKernelCommAndChannels 来打包要拷贝到设备的数据：

📎 src/init.cc:712-746

这个结构体包含 ncclDevComm（设备侧通信域）和通道数组。函数先把主机侧的数据填入临时结构体，然后一次性 cudaMemcpyAsync 到设备。

关键字段的填充：

📎 src/init.cc:734-746

注意 comm->devComm = &devCommAndChans->comm——主机侧的 comm->devComm 指向设备内存中的 ncclDevComm。后续 kernel 启动时会把 comm->devComm 作为参数传入。

通道信息的填充：

📎 src/init.cc:829-843

每个通道的 peers、ring、tree、collnetChain、collnetDirect、nvls 指针都被拷贝到设备侧。注意 ring.userRanks 需要额外的一次 cudaMemcpyAsync，因为它是一个数组。

Step-by-Step Walkthrough

1. 获取设备流：ncclStrongStreamAcquire 获取一个强流（strong stream），确保后续的异步拷贝有序执行。

2. 分配设备内存：ncclCudaCallocAsync 分配 devCommAndChans。

3. 填充主机侧临时结构体：设置 rank、nRanks、node、nNodes、abortFlag、buffSizes 等。

4. 分配并拷贝 rankToLocalRank 数组。

5. 计算 workFifoBytes：根据 CC（Confidential Computing）状态决定。

6. 分配 workFifo 缓冲区：GDR 模式用 ncclGdrCudaCalloc，否则用 ncclCudaHostCalloc。

7. 分配 profiler 计数器。

8. 分配进度计数器（如果启用）。

9. 填充通道信息。

10. 一次性拷贝到设备：ncclCudaMemcpyAsync(devCommAndChans, &tmpCommAndChans, 1, deviceStream)。

11. 释放强流并同步。

设计思考

devCommSetup 中最值得注意的设计是"批量拷贝"。NCCL 没有为每个字段单独调用 cudaMemcpy，而是把所有字段打包到一个临时结构体，用一次 cudaMemcpyAsync 完成。这大幅减少了 CUDA API 调用次数和同步开销。

另一个设计是 workFifoBytes 的 CC 处理：

📎 src/init.cc:750-763

在 CC（Confidential Computing）模式下，workFifoBytes 被设为 0，因为 GDR 拷贝在 CC 模式下不可用。这是一个硬件限制的优雅降级。

生产避坑指南

坑一：devCommSetup 必须在 barrier 之前调用。 源码注释解释了原因：

📎 src/init.cc:1950-1952

如果在 barrier 之后调用，可能有线程已经开始启动 NCCL kernel，而此时设备内存还没分配完，会导致死锁。

坑二：workFifoBytes 必须是 2 的幂。 如果不是，NCCL 会警告并使用默认值：

📎 src/init.cc:757-762

本章思考与自测

<details><summary>Q1: 如果将 📎 src/init.cc:1291-1296 中检测"多个 rank 使用同一 GPU"的逻辑去掉，在什么场景下会导致问题？为什么 NCCL 默认拒绝这种配置？</summary>

参考解析：

这段代码检测同一主机上两个 rank 的 GPU UUID 是否相同。如果相同且 NCCL_MULTI_RANK_GPU_ENABLE=0（默认），就返回 ncclInvalidUsage。

去掉这个检查后，多个 rank 会共享同一个 GPU。这会导致：

1. P2P 传输冲突：NCCL 的 P2P 传输假设每个 rank 独占一个 GPU。如果两个 rank 共享 GPU，它们会同时向同一个 GPU 的同一块缓冲区写入数据，导致数据竞争和结果错误。

2. 通道分配冲突：comm->channels 中的通道资源（缓冲区、FIFO）是按 rank 分配的。共享 GPU 的 rank 会争抢同一份资源。

3. 性能灾难：即使没有正确性问题，两个 rank 共享一个 GPU 的算力和显存带宽，性能会急剧下降。

NCCL 默认拒绝这种配置是为了"快速失败"——与其让用户在一个错误配置上浪费数小时调试，不如在初始化时就明确报错。NCCL_MULTI_RANK_GPU_ENABLE=1 是给那些明确知道自己在做什么的用户（比如 MPS 场景）准备的逃生通道。

</details>

<details><summary>Q2: 如果将 📎 src/bootstrap.cc:1129-1134 中等待"同一 (peer, tag) 的更早发送"的逻辑去掉，在什么场景下会导致接收方匹配错误？</summary>

参考解析：

这段代码在异步发送线程中等待，直到队列中没有更早的、发往同一 (peer, tag) 的发送。

去掉这个等待后，两个发往同一 (peer, tag) 的发送可能并发执行，到达接收方的顺序不确定。接收方的 socketAccept 按 (peer, tag) 匹配连接：

📎 src/bootstrap.cc:1291-1292

如果发送方 A 先调用 bootstrapSend 但后到达，发送方 B 后调用但先到达，接收方会把 B 的消息当作 A 的响应。这会导致数据错位——接收方以为收到的是第一个请求的响应，实际上是第二个请求的。

源码注释明确指出了这个场景："NVLS setup broadcasts to the same peers with the same tag several times during init"。NVLS 初始化期间会多次向同一 peer 用同一 tag 广播，如果顺序颠倒，NVLS 配置会完全错乱。

这个顺序保证的代价是：同一 (peer, tag) 的发送被串行化。但不同 (peer, tag) 的发送仍然并发，所以整体吞吐量不受影响。

</details>

<details><summary>Q3: 如果将 📎 src/init.cc:1691-1697 中对齐策略从"nChannels 取 min、typeIntra 取 max"改为"全部取 min"或"全部取 max"，会分别导致什么问题？</summary>

参考解析：

当前策略是：nChannels、sameChannels、bwIntra、bwInter 取 min，typeIntra、typeInter、crossNic 取 max。

如果全部取 min：typeIntra 和 typeInter 取 min 会导致某些 rank 的传输类型被降级。比如 rank A 支持 P2P（typeIntra=P2P），rank B 只支持 SHM（typeIntra=SHM），取 min 后所有 rank 都用 SHM。但 SHM 的枚举值可能比 P2P 小，取 min 会选到错误的类型。实际上 typeIntra 是一个位掩码或枚举，取 max 是为了选择"能力最强"的类型。

如果全部取 max：nChannels 取 max 会导致某些 rank 被分配超过其能力的通道数。比如 rank A 只能支持 4 个通道，rank B 支持 8 个，取 max 后所有 rank 都尝试用 8 个通道，rank A 会失败或性能下降。bwIntra 取 max 会导致带宽估计过于乐观，tuning 模块可能选择不适合的算法。

这个对齐策略的本质是：资源约束取交集（min），能力枚举取并集（max）。通道数和带宽是"上限"约束，必须取最保守的值；传输类型是"能力"枚举，取最大值确保所有 rank 都能找到兼容的传输方式。

</details>

下一章我们将深入拓扑发现与图搜索，看 NCCL 如何枚举机器里的 GPU、网卡、PCI 交换机，构建出一张完整的拓扑图，并在这张图上搜索最优的 ring 和 tree 结构。本章建立的 bootstrap 通信、commAlloc 内存骨架、initTransportsRank 主干流程，将在下一章中逐一展开其拓扑细节。

至此，我们已经完整走过了 ncclCommInitRank 的调用链，看清了 ncclComm 对象从零构建的全过程。但初始化过程中有一个关键环节我们只是匆匆掠过：NCCL 是如何探测机器内部的 GPU 和网卡，并据此决定数据该走哪条路的？这正是下一章要深入的主题——拓扑发现与图搜索。我们将拆解 src/graph/topo.cc 如何枚举 PCI/NVLink/网卡设备并构建拓扑图，src/graph/search.cc 如何在该图上搜索最优路径，以及 src/graph/rings.cc 与 trees.cc 如何将搜索结果具体化为 Ring 与 Tree 算法拓扑。理解了这套机制，你就能明白为什么 NCCL 能在不同机器上自动选到合适的算法。

第 4 章：拓扑发现与图搜索：NCCL 如何“看清”多 GPU 系统的物理互联

上一章我们沿 ncclCommInitRank 的调用链逐层下钻，看到了 comm->topo 字段被填充的时机，但并未展开它内部的结构。那么，NCCL 究竟是如何“看见”机器里的 GPU 和网卡，并将它们组织成可用的拓扑信息的？本章将拆解这一过程的三个关键环节：topo.cc 负责将物理设备枚举成一张图，search.cc 在这张图上搜索最优路径，rings.cc 和 trees.cc 则把搜索结果具体化为 Ring 与 Tree 两种算法拓扑。理解这三者的配合，才能明白 NCCL 为何能在不同机器上自动选到合适的算法。

拓扑图：把机器画成一张"地铁线路图"

直觉模型

想象你是一个刚到陌生城市的快递员。你要把包裹从 A 点送到 B 点，但你不知道哪条路最快。你需要一张地图——上面标着所有站点（GPU、网卡、CPU、PCI 交换机）以及站点之间的连接（NVLink、PCIe、网络）。NCCL 的拓扑图就是这张地图。

如果没有这张图，NCCL 只能盲目地假设"所有 GPU 之间带宽相同"，在 8 卡 NVLink 全互联的机器上或许还能凑合，但一旦遇到跨 NUMA、跨 PCI 交换机、混合 NVLink + PCIe 的复杂拓扑，就会选错路径，把本该走 NVLink 的数据塞进慢速 PCIe，性能直接腰斩。

数据结构与内存布局

拓扑图的核心是 ncclTopoSystem，它按节点类型分组存储所有设备。节点类型定义在 topoNodeTypeStr 数组里：

📎 src/graph/topo.cc:33-35

const char* topoNodeTypeStr[] = {"GPU", "PCI", "NVS", "CPU", "NIC", "NET", "GIN", "RMA", "DEV", "CXB"};
const char* topoLinkTypeStr[] = {"LOC", "NVL", "", "C2C", "PCI", "", "", "", "", "SYS", "NET"};
const char* topoPathTypeStr[] = {"LOC", "NVL", "NVB", "C2C", "PIX", "PXB", "P2C", "PXN", "PHB", "SYS", "NET", "DIS"};

这三个数组分别定义了节点类型、链路类型和路径类型的字符串表示。注意 topoPathTypeStr 的顺序——它同时充当了路径质量的排序：索引越小，路径越快。LOC（本地）最快，DIS（断开）最慢。这个顺序在后续搜索中会被反复用来比较路径优劣。

每个节点由 ncclTopoNode 表示，创建时根据类型初始化不同的字段。以 GPU 节点为例：

📎 src/graph/topo.cc:105-141

ncclResult_t ncclTopoCreateNode(struct ncclTopoSystem* system, struct ncclTopoNode** node, int type, uint64_t id) {
  if (system->nodes[type].count == NCCL_TOPO_MAX_NODES) {
    WARN("Error : tried to create too many nodes of type %d", type);
    return ncclInternalError;
  }
  struct ncclTopoNode* n = system->nodes[type].nodes + system->nodes[type].count;
  system->nodes[type].count++;
  n->type = type;
  n->id = id;
  if (type == GPU) {
    n->gpu.dev = NCCL_TOPO_UNDEF;
    n->gpu.rank = NCCL_TOPO_UNDEF;
    n->gpu.cudaCompCap = NCCL_TOPO_UNDEF;
    n->gpu.mloPart = NCCL_TOPO_UNDEF;
  } else if (type == CPU) {
    ...

这里有几个关键设计点。第一，节点存储在一个预分配的数组中（system->nodes[type].nodes），而不是链表。这意味着节点在内存中是连续排列的，遍历时缓存友好。第二，NCCL_TOPO_MAX_NODES 是一个硬上限，超过就报错——这是为了防止拓扑异常时无限增长。第三，每个节点有一个 id 字段，它是一个 64 位整数，高 32 位是 systemId（标识哪台主机），低 32 位是 localId（主机内的设备编号）。

节点之间的连接由 ncclTopoLink 表示。ncclTopoConnectNodes 负责建立双向连接：

📎 src/graph/topo.cc:179-204

ncclResult_t ncclTopoConnectNodes(struct ncclTopoNode* node, struct ncclTopoNode* remNode, int type, float bw) {
  // Aggregate links into higher bw for NVLink
  struct ncclTopoLink* link;
  for (link = node->links; link - node->links != NCCL_TOPO_MAX_LINKS && link->remNode; link++) {
    if (link->remNode == remNode && link->type == type) break;
  }
  if (link - node->links == NCCL_TOPO_MAX_LINKS) {
    WARN("Error : too many Topo links (max %d)", NCCL_TOPO_MAX_LINKS);
    return ncclInternalError;
  }
  if (link->remNode == NULL) node->nlinks++;
  link->type = type;
  link->remNode = remNode;
  link->bw += bw;

  // Sort links in BW descending order
  struct ncclTopoLink linkSave;
  memcpy(&linkSave, link, sizeof(struct ncclTopoLink));
  while (link != node->links) {
    if ((link - 1)->bw >= linkSave.bw) break;
    memcpy(link, link - 1, sizeof(struct ncclTopoLink));
    link--;
  }
  memcpy(link, &linkSave, sizeof(struct ncclTopoLink));
  return ncclSuccess;
}

这个函数做了三件事。第一，查找是否已存在到同一目标、同一类型的链路——如果存在，就把带宽累加（link->bw += bw）。这处理的是多条 NVLink 连到同一个 GPU 的情况：4 条 NVLink 各 25 GB/s，聚合后就是 100 GB/s。第二，如果没找到，就新增一条链路。第三，插入后按带宽降序排列，这样后续遍历时优先看到高带宽链路。

场景驱动的 Step-by-Step Walkthrough

现在代入一个具体场景：一台 8 卡 A100 服务器，每张卡通过 NVLink 全互联，另有 4 张 Mellanox ConnectX-6 网卡插在 PCIe 插槽上。NCCL 初始化时，ncclTopoGetSystem 被调用，它从 XML 文件（由 nvidia-topologyd 或 NCCL 自己生成）读取设备信息，然后构建拓扑图。

第一步，解析 CPU 节点。ncclTopoAddCpu 从 XML 中读取 CPU 的架构、厂商、型号，并创建 CPU 节点：

📎 src/graph/topo.cc:806-875

ncclResult_t ncclTopoAddCpu(struct ncclXmlNode* xmlCpu, struct ncclTopoSystem* system) {
  int numaId;
  NCCLCHECK(xmlGetAttrInt(xmlCpu, "numaid", &numaId));
  int systemId;
  NCCLCHECK(ncclGetSystemId(system, xmlCpu, &systemId));
  struct ncclTopoNode* cpu;
  NCCLCHECK(ncclTopoCreateNode(system, &cpu, CPU, NCCL_TOPO_ID(systemId, numaId)));
  ...
  for (int s = 0; s < xmlCpu->nSubs; s++) {
    struct ncclXmlNode* node = xmlCpu->subs[s];
    if (strcmp(node->name, "pci") == 0) NCCLCHECK(ncclTopoAddPci(node, system, cpu, systemId, numaId));
    if (strcmp(node->name, "nic") == 0) {
      ...
    }
  }
  return ncclSuccess;
}

CPU 节点是拓扑树的根。每个 CPU 下面挂着 PCI 子树和 NIC 节点。ncclTopoAddPci 递归处理 PCI 树，遇到 GPU 就创建 GPU 节点，遇到 NIC 就创建 NIC 节点。

第二步，添加 NVLink 连接。注意 ncclTopoAddGpu 只读取 GPU 的基本属性，注释明确说 "Do not go any further, nvlinks will be added in a second pass"：

📎 src/graph/topo.cc:590-598

ncclResult_t ncclTopoAddGpu(struct ncclXmlNode* xmlGpu, struct ncclTopoSystem* system, struct ncclTopoNode* gpu) {
  NCCLCHECK(xmlGetAttrInt(xmlGpu, "rank", &gpu->gpu.rank));
  NCCLCHECK(xmlGetAttrInt(xmlGpu, "sm", &gpu->gpu.cudaCompCap));
  NCCLCHECK(xmlGetAttrInt(xmlGpu, "dev", &gpu->gpu.dev));
  NCCLCHECK(xmlGetAttrInt(xmlGpu, "gdr", &gpu->gpu.gdrSupport));
  NCCLCHECK(xmlGetAttrIntDefault(xmlGpu, "mlopart", &gpu->gpu.mlopart, NCCL_TOPO_UNDEF));
  // Do not go any further, nvlinks will be added in a second pass
  return ncclSuccess;
}

为什么要分两遍？因为 NVLink 是 GPU 之间的连接，需要两端 GPU 节点都已存在才能建立链路。第一遍创建所有节点，第二遍 ncclTopoAddNvLinks 再连接它们。

第三步，处理网络设备。ncclTopoAddNic 遍历 NIC 下的 net/gin/rma 子节点，分别调用对应的添加函数。以 ncclTopoAddNet 为例：

📎 src/graph/topo.cc:461-503

static ncclResult_t ncclTopoAddNet(struct ncclXmlNode* xmlNet, struct ncclXmlNode* parent,
                                   struct ncclTopoSystem* system, struct ncclTopoNode* nic, int systemId) {
  int dev;
  NCCLCHECK(xmlGetAttrInt(xmlNet, "dev", &dev));
  int64_t netId = NCCL_TOPO_ID(systemId, dev);
  struct ncclTopoNode* net;
  NCCLCHECK(ncclTopoCreateNode(system, &net, NET, netId));
  net->net.dev = dev;
  int mbps;
  NCCLCHECKNOWARN(xmlGetAttrIntDefault(xmlNet, "speed", &mbps, 0), NCCL_GRAPH);
  if (mbps <= 0) mbps = 10000; // Some NICs define speed = -1
  net->net.bw = mbps / 8000.0;
  ...
  NCCLCHECK(ncclTopoConnectNodes(nic, net, LINK_NET, net->net.bw));
  NCCLCHECK(ncclTopoConnectNodes(net, nic, LINK_NET, net->net.bw));
  return ncclSuccess;
}

注意 mbps / 8000.0 这个转换：mbps 是兆比特每秒，除以 8000 得到 GB/s（因为 1 GB/s = 8000 Mbps）。如果网卡报告 speed = -1（某些虚拟网卡会这样），就默认 10000 Mbps = 1.25 GB/s。

第四步，收尾处理。ncclTopoGetSystemFromXml 在完成所有节点和链路添加后，还会做几件清理工作：

📎 src/graph/topo.cc:1080-1088

  NCCLCHECK(ncclTopoAddNvLinks(topNode, *topoSystem, NULL, 0));
  NCCLCHECK(ncclTopoAddC2c(topNode, *topoSystem, NULL, 0));
  NCCLCHECK(ncclTopoAddPciLinks(topNode, *topoSystem, NULL, 0));

  NCCLCHECK(ncclTopoFlattenBcmSwitches(*topoSystem));
  NCCLCHECK(ncclTopoConnectCpus(*topoSystem));
  NCCLCHECK(ncclTopoSortSystem(*topoSystem));

ncclTopoFlattenBcmSwitches 处理 Broadcom Gen4 PCIe 交换机的特殊情况——它们把自己呈现为两层交换机，但实际是全带宽的，需要"压平"以避免搜索算法被误导。ncclTopoConnectCpus 把所有 CPU 节点互相连接（跨 NUMA 访问走 SYS 链路）。ncclTopoSortSystem 对链路排序，让 PCI 下行链路排在前面，方便遍历。

设计思考与生产踩坑

坑点一：ncclTopoGetNode 找不到节点时不报错。 看这个函数：

📎 src/graph/topo.cc:95-103

ncclResult_t ncclTopoGetNode(struct ncclTopoSystem* system, struct ncclTopoNode** node, int type, uint64_t id) {
  for (int i = 0; i < system->nodes[type].count; i++) {
    if (system->nodes[type].nodes[i].id == id) {
      *node = system->nodes[type].nodes + i;
      return ncclSuccess;
    }
  }
  return ncclSuccess;
}

如果没找到，它返回 ncclSuccess 但 *node 保持不变（调用者通常初始化为 NULL）。调用者必须自己检查 *node == NULL。这种设计容易漏检——如果调用者忘了检查，后续解引用就会崩溃。

坑点二：ncclTopoConnectNodes 的带宽累加可能导致溢出。 如果同一对节点之间有大量链路（比如 NVSwitch 场景），link->bw += bw 可能累加到很大。虽然 float 的精度足够，但如果链路数量异常多，排序逻辑可能出问题。

坑点三：ncclTopoRemoveNode 的指针修正。 删除节点时，所有指向被删节点的链路都要移除，且指向被删节点之后节点的指针要前移：

📎 src/graph/topo.cc:143-177

ncclResult_t ncclTopoRemoveNode(struct ncclTopoSystem* system, int type, int index) {
  struct ncclTopoNode* delNode = system->nodes[type].nodes + index;
  for (int t = 0; t < NCCL_TOPO_NODE_TYPES; t++) {
    if (delNode->paths[t] != nullptr) {
      WARN("Cannot remove topology node %d/%lx while paths are computed", type, delNode->id);
      return ncclInternalError;
    }
    for (int n = 0; n < system->nodes[t].count; n++) {
      struct ncclTopoNode* node = system->nodes[t].nodes + n;
      if (node == delNode) continue;
      for (int l = 0; l < node->nlinks; l++) {
        while (l < node->nlinks && node->links[l].remNode == delNode) {
          memmove(node->links + l, node->links + l + 1, (node->nlinks - l - 1) * sizeof(struct ncclTopoLink));
          node->nlinks--;
        }
        if (l < node->nlinks && node->links[l].remNode->type == type && node->links[l].remNode >= delNode) {
          node->links[l].remNode--;
        }
      }
    }
  }
  ...

这里有个微妙之处：node->links[l].remNode-- 是在修正指针。因为节点存储在连续数组中，删除一个节点后，后面的节点地址都会前移一个 sizeof(struct ncclTopoNode)。所以所有指向被删节点之后节点的指针都要减一。这个操作在 memmove 之前执行，顺序很关键。

路径搜索：在图上找"最优路线"

直觉模型

有了地图还不够，你还需要一个导航算法。NCCL 的路径搜索分两层：第一层是预处理，计算所有节点对之间的最短路径（BFS）；第二层是图搜索，在预处理结果上尝试不同的 Ring/Tree 结构，找到带宽最高的那个。

如果没有路径搜索，NCCL 只能硬编码"GPU 0 连 GPU 1 连 GPU 2..."这种固定顺序，在非均匀拓扑上会选到慢速路径。

数据结构与内存布局

路径搜索的核心数据结构是 ncclTopoLinkList，它存储从某个源节点到某个目标节点的完整路径：

struct ncclTopoLinkList {
  struct ncclTopoLink* list[NCCL_TOPO_MAX_HOPS];  // 路径上的链路
  int count;      // 跳数
  float bw;       // 瓶颈带宽
  int type;       // 路径类型（PATH_LOC, PATH_NVL, ...）
  int capacity;   // list 数组的容量
};

每个节点有一个 paths[type] 数组，存储到所有该类型节点的路径。比如 GPU 节点的 paths[NET] 存储到所有网卡的路径。

路径计算由 ncclTopoSetPaths 完成，它是一个 BFS：

📎 src/graph/paths.cc:52-147

static ncclResult_t ncclTopoSetPaths(struct ncclTopoNode* baseNode, struct ncclTopoSystem* system) {
  if (baseNode->paths[baseNode->type] == NULL) {
    NCCLCHECK(ncclCalloc(baseNode->paths + baseNode->type, system->nodes[baseNode->type].count));
    for (int i = 0; i < system->nodes[baseNode->type].count; i++) baseNode->paths[baseNode->type][i].type = PATH_DIS;
  }

  // breadth-first search to set all paths to that node in the system
  struct ncclTopoNodeList nodeList;
  struct ncclTopoNodeList nextNodeList = {{0}, 0};
  nodeList.count = 1;
  nodeList.list[0] = baseNode;
  ...
  while (nodeList.count) {
    nextNodeList.count = 0;
    for (int n = 0; n < nodeList.count; n++) {
      struct ncclTopoNode* node = nodeList.list[n];
      struct ncclTopoLinkList* path;
      NCCLCHECK(getPath(system, node, baseNode->type, baseNode->id, &path));
      for (int l = 0; l < node->nlinks; l++) {
        struct ncclTopoLink* link = node->links + l;
        struct ncclTopoNode* remNode = link->remNode;
        ...
        float bw = std::min(path->bw, link->bw);
        ...
        // Update if better path type, OR same type with higher bw, OR same type/bw with strickly fewer hops.
        if (newType < remPath->type || (newType == remPath->type && remPath->bw < bw) ||
            (newType == remPath->type && remPath->bw == bw && remPath->count > (path->count + 1))) {
          ...
          remPath->bw = bw;
          remPath->type = newType;
          ...
        }
      }
    }
    memcpy(&nodeList, &nextNodeList, sizeof(nodeList));
  }
  return ncclSuccess;
}

BFS 从 baseNode 出发，逐层扩展。每到达一个新节点，就计算路径的瓶颈带宽（std::min(path->bw, link->bw)）和路径类型。路径类型的计算有几个特殊规则：

• 如果经过两个 PCI 交换机，类型升级为 PATH_PXB
• 如果经过 CPU，类型升级为 PATH_PHB
• 如果经过 DEV 节点且是 NVLink，类型升级为 PATH_NVB

更新条件是"更优路径"：类型更好，或类型相同但带宽更高，或类型带宽相同但跳数更少。

场景驱动的 Step-by-Step Walkthrough

现在看第二层搜索。ncclTopoCompute 是入口，它尝试不同的参数组合，调用 ncclTopoSearchRec 进行搜索。

搜索的核心是递归函数 ncclTopoSearchRecGpu。它从某个 GPU 出发，尝试走到下一个 GPU，直到走完所有 GPU 形成一条路径：

📎 src/graph/search.cc:639-756

ncclResult_t ncclTopoSearchRecGpu(struct ncclTopoSystem* system, struct ncclTopoGraph* graph,
                                  struct ncclTopoGraph* saveGraph, struct ncclTopoNode* gpu, int step, int backToNet,
                                  int backToFirstRank, int forcedOrder, int* time) {
  if ((*time) <= 0) return ncclSuccess;
  (*time)--;
  ...
  if (step == ngpus) {
    // Determine whether we found a better solution or not
    int copy = 0;
    graph->nChannels++;
    NCCLCHECKGOTO(ncclTopoCompareGraphs(system, graph, saveGraph, &copy), ret, exit);
    if (copy) {
      memcpy(saveGraph, graph, sizeof(struct ncclTopoGraph));
      if (graph->nChannels == graph->maxChannels) *time = -1;
    }
    if (graph->nChannels < graph->maxChannels) {
      NCCLCHECKGOTO(ncclTopoSearchRec(system, graph, saveGraph, time), ret, exit);
    }
    graph->nChannels--;
    ret = ncclSuccess;
    goto exit;
  }
  graph->intra[graph->nChannels * ngpus + step] = gpu->gpu.rank;
  g = gpu - system->nodes[GPU].nodes;
  if (step == backToNet) {
    // first get back to NIC
    ...
  } else if (graph->pattern == NCCL_TOPO_PATTERN_NVLS) {
    ...
  } else if (step < system->nodes[GPU].count - 1) {
    // Go to next GPU
    ...
  } else if (step == backToFirstRank) {
    // Find first GPU and loop back to it
    ...
  } else {
    // Next path
    NCCLCHECKGOTO(ncclTopoSearchRecGpu(system, graph, saveGraph, gpu, ngpus, -1, -1, forcedOrder, time), ret, exit);
  }
  ...
}

这个函数有几个关键分支：

1. step == ngpus：已经走完所有 GPU，形成了一条完整路径。此时递增 nChannels，比较当前图和保存的最优图，如果更好就保存。然后递归调用 ncclTopoSearchRec 尝试搜索下一个 channel。

2. step == backToNet：需要回到网卡。这发生在 Ring 模式（最后一个 GPU 要连回起始网卡）或 Tree 模式（第一个 GPU 要连到网卡）。

3. step < ngpus - 1：继续走下一个 GPU。这里会调用 ncclTopoSearchNextGpuSort 对候选 GPU 排序。

4. step == backToFirstRank：Ring 模式下，最后一个 GPU 要连回第一个 GPU。

5. else：路径结束，进入下一轮。

ncclTopoSearchNextGpuSort 决定尝试下一个 GPU 的顺序：

📎 src/graph/search.cc:254-327

ncclResult_t ncclTopoSearchNextGpuSort(struct ncclTopoSystem* system, struct ncclTopoGraph* graph,
                                       struct ncclTopoNode* gpu, int* next, int* countPtr, int sortNet) {
  const uint64_t flag = 1ULL << (graph->nChannels);
  int ngpus = system->nodes[GPU].count;
  struct ncclTopoLinkList* paths = gpu->paths[GPU];
  ...
  for (int i = 1; i < ngpus; i++) {
    int g = (start + i) % ngpus;
    if (paths[g].count == 0) continue; // There is no path to that GPU
    if (system->nodes[GPU].nodes[g].used & flag) continue;
    scores[count].g = g;
    scores[count].startIndex = i;
    scores[count].intraNhops = paths[g].count;
    scores[count].intraBw = paths[g].bw;
    if (netPaths) {
      scores[count].interNhops = netPaths[g].count;
      scores[count].interPciBw = gpuPciBw(system->nodes[GPU].nodes + g);
      scores[count].interBw = netPaths[g].bw;
    }
    count++;
  }

  // Sort GPUs
  qsort(scores, count, sizeof(struct ncclGpuScore), cmpScore);
  ...
}

它给每个候选 GPU 打分，排序规则是：先比 interBw（到网卡的带宽），再比 interPciBw，再比 interNhops，再比 intraBw，最后比 intraNhops。这个优先级反映了 NCCL 的优化目标：跨机通信是瓶颈，所以优先选到网卡带宽高的 GPU。

设计思考与生产踩坑

为什么搜索有超时？ 看这些常量：

📎 src/graph/search.cc:329-330

#define NCCL_SEARCH_GLOBAL_TIMEOUT (1ULL << 19)
#define NCCL_SEARCH_TIMEOUT (1 << 14)
#define NCCL_SEARCH_TIMEOUT_TREE (1 << 14)
#define NCCL_SEARCH_TIMEOUT_SAMECHANNELS (1 << 8)

搜索空间是指数级的——每个 channel 有 O(ngpus!) 种排列。8 卡机器就是 40320 种，16 卡就是 2 万亿种。必须限制搜索时间。NCCL_SEARCH_TIMEOUT 是 16384 次迭代，NCCL_SEARCH_GLOBAL_TIMEOUT 是 524288 次。超时后返回当前最优解。

坑点一：ncclTopoFollowPath 的带宽扣减是全局副作用。 看这个函数：

📎 src/graph/search.cc:127-173

static ncclResult_t ncclTopoFollowPath(struct ncclTopoSystem* system, struct ncclTopoGraph* graph, int type1,
                                       int index1, int type2, int index2, float mult, struct ncclTopoNode** node) {
  ...
  bw *= mult;
  // Check there is enough bandwidth on paths.
  int step = 0;
  NCCLCHECK(followPath(path, node1, path->count, bw, &step));
  if (step < path->count) goto rewind;
  // Enough bandwidth : return destination node.
  graph->nHops += mult * path->count;
  *node = system->nodes[type2].nodes + index2;
  return ncclSuccess;
rewind:
  // Not enough bandwidth : rewind and exit.
  NCCLCHECK(followPath(path, node1, step, -bw, &step));
  return ncclSuccess;
}

followPath 会修改路径上每条链路的 bw（扣减已用带宽）。如果搜索失败，必须调用 followPath 用 -bw 恢复。这个"扣减-恢复"模式在递归搜索中很容易出错——如果某个分支忘记恢复，后续搜索就会看到错误的带宽。

坑点二：ncclTopoCompareGraphs 的比较逻辑很微妙。 它优先比较 nChannels * bwIntra，但还有一堆特殊情况：

📎 src/graph/search.cc:446-477

ncclResult_t ncclTopoCompareGraphs(struct ncclTopoSystem* system, struct ncclTopoGraph* graph,
                                   struct ncclTopoGraph* refGraph, int* copy) {
  // 1. Try to get the same nChannels between Rings and Trees
  if (graph->nChannels < graph->minChannels) return ncclSuccess;
  const bool evenReference = refGraph->nChannels > 0 && !(refGraph->nChannels & 1);
  const bool evenReferenceIsBetter = refGraph->nChannels * refGraph->bwIntra >= graph->nChannels * graph->bwIntra;
  // Favor an even number of channels when aggregate bandwidth is equal or better.
  if (graph->pattern != NCCL_TOPO_PATTERN_NVLS && evenReference && (graph->nChannels & 1) &&
      graph->nChannels < system->nodes[NET].count && evenReferenceIsBetter)
    return ncclSuccess;
  ...

Ring 与 Tree：把搜索结果变成算法拓扑

直觉模型

搜索算法找到的是一组路径，但算法需要的是明确的"谁发给谁"的顺序。Ring 把所有 rank 串成一个环，每个 rank 从上一个收、发给下一个。Tree 则是一棵树，数据从根往下流或从叶子往上汇聚。

如果没有这两个模块，搜索算法就只是找到了一堆路径，无法告诉 GPU kernel 具体怎么发数据。

数据结构与内存布局

Ring 的构建由 ncclBuildRings 完成：

📎 src/graph/rings.cc:29-74

ncclResult_t ncclBuildRings(int nrings, int* rings, int rank, int nranks, int* prev, int* next) {
  ncclResult_t ret = ncclSuccess;
  uint64_t* rankFound;
  int rankFoundSize = DIVUP(nranks, 64);
  NCCLCHECK(ncclCalloc(&rankFound, rankFoundSize));

  for (int r = 0; r < nrings; r++) {
    int current = rank;
    for (int i = 0; i < nranks; i++) {
      rankFound[current / 64] |= (1ULL << (current % 64));
      rings[r * nranks + i] = current;
      current = next[r * nranks + current];
    }
    ...
    if (current != rank) {
      WARN("Error : ring %d does not loop back to start (%d != %d)", r, current, rank);
      ret = ncclInternalError;
      goto end;
    }
    // Check that all ranks are there
    for (int i = 0; i < nranks; i++) {
      uint64_t bits = rankFound[i / 64], mask = 1ULL << (i % 64);
      // Fast check 64 ranks at a time
      if (mask == 1 && bits == 0xffffffffffffffff) {
        i += 63;
        continue;
      }
      if ((bits & mask) == 0) {
        WARN("Error : ring %d does not contain rank %d", r, i);
        ret = ncclInternalError;
        goto end;
      }
    }
    memset(rankFound, 0, rankFoundSize * sizeof(uint64_t));
  }
end:
  free(rankFound);
  return ret;
}

输入是 prev 和 next 数组（每个 rank 的前驱和后继），输出是 rings 数组（每个 channel 的完整 rank 顺序）。它从当前 rank 出发，沿着 next 指针走一圈，验证是否回到起点，并检查所有 rank 都被访问到。

Tree 的构建由 ncclGetBtree 完成：

📎 src/graph/trees.cc:32-67

ncclResult_t ncclGetBtree(int nranks, int rank, int* u, int* d0, int* d1, int* parentChildType) {
  int up, down0, down1;
  int bit;
  for (bit = 1; bit < nranks; bit <<= 1) {
    if (bit & rank) break;
  }

  if (rank == 0) {
    *u = -1;
    *d0 = -1;
    // Child rank is > 0 so it has to be our child 1, not 0.
    *d1 = nranks > 1 ? bit >> 1 : -1;
    return ncclSuccess;
  }

  up = (rank ^ bit) | (bit << 1);
  // if smaller than the parent, we are his first child, otherwise we're his second
  if (up >= nranks) up = (rank ^ bit);
  *parentChildType = (rank < up) ? 0 : 1;
  *u = up;

  int lowbit = bit >> 1;
  // down0 is always within bounds
  down0 = lowbit == 0 ? -1 : rank - lowbit;

  down1 = lowbit == 0 ? -1 : rank + lowbit;
  // Make sure down1 is within bounds
  while (down1 >= nranks) {
    down1 = lowbit == 0 ? -1 : rank + lowbit;
    lowbit >>= 1;
  }
  *d0 = down0;
  *d1 = down1;

  return ncclSuccess;
}

这个函数用位运算构建二叉树。核心思想是：找到 rank 的最低非零位 bit，父节点是 (rank ^ bit) | (bit << 1)，左子是 rank - (bit >> 1)，右子是 rank + (bit >> 1)。注释里的 ASCII 图很清楚地展示了这个结构。

场景驱动的 Step-by-Step Walkthrough

以 8 卡 Ring 为例。假设搜索结果给出了每个 rank 的 next 指针：

rank 0 -> rank 1
rank 1 -> rank 2
...
rank 7 -> rank 0

ncclBuildRings 从 rank 0 出发，依次访问 1, 2, ..., 7，最后回到 0。生成的 rings[0..7] = {0, 1, 2, 3, 4, 5, 6, 7}。

对于 Tree，ncclGetBtree 为每个 rank 计算父节点和子节点。以 rank 1 为例：

• bit = 1（最低非零位是第 0 位）
• up = (1 ^ 1) | (1 << 1) = 0 | 2 = 2
• up >= nranks? 2 < 8，所以 up = 2
• parentChildType = (1 < 2) ? 0 : 1 = 0（是父节点的第一个孩子）
• lowbit = 0，所以 down0 = -1
• down1 = -1

所以 rank 1 的父节点是 rank 2，没有子节点。这符合注释里的树结构：rank 1 是叶子。

设计思考与生产踩坑

坑点一：ncclBuildRings 的验证可能被跳过。 如果 next 数组有环（比如 rank 0 -> rank 1 -> rank 0），循环会在 nranks 次迭代后退出，但 current != rank 检查会捕获这个问题。但如果环的长度恰好是 nranks 的因子，且不包含所有 rank，rankFound 检查会捕获。

坑点二：ncclGetDtree 的奇数 rank 处理。 对于奇数个 rank，第二棵树是"移位"而不是"镜像"：

📎 src/graph/trees.cc:90-112

ncclResult_t ncclGetDtree(int nranks, int rank, int* s0, int* d0_0, int* d0_1, int* parentChildType0, int* s1,
                          int* d1_0, int* d1_1, int* parentChildType1) {
  // First tree ... use a btree
  ncclGetBtree(nranks, rank, s0, d0_0, d0_1, parentChildType0);
  // Second tree ... mirror or shift
  if (nranks % 2 == 1) {
    // shift
    int shiftrank = (rank - 1 + nranks) % nranks;
    ...
  } else {
    // mirror
    int u, d0, d1;
    ncclGetBtree(nranks, nranks - 1 - rank, &u, &d0, &d1, parentChildType1);
    *s1 = u == -1 ? -1 : nranks - 1 - u;
    ...
  }
  return ncclSuccess;
}

双二叉树（Double Tree）是 NCCL 的 Tree 算法实现——两棵树同时工作，一棵负责前半段数据，一棵负责后半段，提高带宽利用率。奇数 rank 时镜像会导致 rank 映射不完整，所以改用移位。

三者的配合：从拓扑到算法

现在把三个模块串起来。整个流程可以用一张图表示：

flowchart TD
    A["ncclTopoGetSystem()"] --> B["解析 XML，创建节点"]
    B --> C["ncclTopoConnectNodes() 建立链路"]
    C --> D["ncclTopoComputePaths() 计算所有路径"]
    D --> E{"ncclTopoCompute() 搜索"}
    E -->|"Ring 模式"| F["ncclTopoSearchRecNet()"]
    E -->|"Tree 模式"| G["ncclTopoSearchRecNet()"]
    F --> H["ncclTopoSearchRecGpu() 递归搜索"]
    G --> H
    H --> I{"找到更优解?"}
    I -->|"是"| J["memcpy 保存到 saveGraph"]
    I -->|"否"| K["继续尝试其他路径"]
    J --> L["ncclBuildRings() 或 ncclGetDtree()"]
    K --> H
    L --> M["生成最终算法拓扑"]

这张图展示了从拓扑发现到算法生成的完整流程。注意 ncclTopoSearchRecGpu 是一个递归函数，它会不断尝试不同的 GPU 顺序，直到超时或找到最优解。

再看一个更细粒度的时序图，展示搜索过程中各模块的交互：

sequenceDiagram
    participant Init as ncclTopoCompute
    participant Search as ncclTopoSearchRec
    participant Net as ncclTopoSearchRecNet
    participant Gpu as ncclTopoSearchRecGpu
    participant Follow as ncclTopoFollowPath
    participant Compare as ncclTopoCompareGraphs

    Init->>Search: ncclTopoSearchRec(system, tmpGraph, graph, &time)
    Search->>Net: ncclTopoSearchRecNet(system, graph, saveGraph, backToNet, backToFirstRank, time)
    Net->>Net: ncclTopoSelectNets() 选择候选网卡
    Net->>Gpu: ncclTopoSearchTryGpu(..., NET, n, gpu)
    Gpu->>Follow: ncclTopoFollowPath(system, graph, NET, n, GPU, g, 1, &gpu)
    Follow-->>Gpu: 返回目标 GPU 节点
    Gpu->>Gpu: 递归 ncclTopoSearchRecGpu(step+1)
    Gpu->>Compare: ncclTopoCompareGraphs(system, graph, saveGraph, &copy)
    Compare-->>Gpu: copy=1 表示更优
    Gpu->>Gpu: memcpy(saveGraph, graph)
    Gpu->>Follow: ncclTopoFollowPath(..., -1, &gpu) 恢复带宽

这个时序图展示了搜索的核心循环：选择网卡 -> 尝试 GPU -> 递归搜索 -> 比较结果 -> 恢复带宽。

本章小结

本章拆解了 NCCL 拓扑感知的三个环节：

1. 拓扑发现（topo.cc）：从 XML 读取设备信息，创建 GPU/CPU/PCI/NIC 节点，建立 NVLink/PCIe/网络链路，形成一张完整的拓扑图。

2. 路径搜索（search.cc + paths.cc）：先用 BFS 预计算所有节点对之间的最短路径，再用递归搜索尝试不同的 Ring/Tree 结构，找到带宽最高的方案。

3. 算法拓扑生成（rings.cc + trees.cc）：把搜索结果转换成具体的 rank 顺序，Ring 用 ncclBuildRings 生成环，Tree 用 ncclGetBtree 生成二叉树。

本章思考与自测

<details><summary>Q1: 如果把 ncclTopoConnectNodes 中的带宽累加 link->bw += bw 改成 link->bw = std::max(link->bw, bw)，在什么场景下会导致性能下降？为什么？</summary>

参考解析：带宽累加处理的是多条并行链路的情况。以 4 条 NVLink 各 25 GB/s 为例，累加后是 100 GB/s，取 max 后只有 25 GB/s。在 ncclTopoSetPaths 中，路径带宽是 std::min(path->bw, link->bw)，如果链路带宽被低估，整条路径的带宽都会被低估。这会导致 ncclTopoCompareGraphs 选择错误的图——可能选了一个 channel 数更多但每个 channel 带宽更低的方案，实际性能反而更差。具体场景：8 卡 A100 全 NVLink 互联，每对 GPU 之间有 4 条 NVLink。累加得到 100 GB/s，取 max 得到 25 GB/s。搜索算法会认为 NVLink 和 PCIe Gen4 x16（约 25 GB/s）带宽相同，可能选择走 PCIe 的路径。

</details>

<details><summary>Q2: ncclTopoSearchRecGpu 中 (*time)-- 在函数入口处执行。如果搜索超时（*time <= 0），函数直接返回。这个设计在什么情况下会导致搜索陷入死循环？如何修复？</summary>

参考解析：(*time)-- 在入口处递减，如果 *time 初始值为 0 或负数，函数直接返回，不会递减。但如果 *time 是一个很大的正数，每次递归都会递减，最终会到 0。问题在于：如果某个分支的递归深度很大，但每次递减后 *time 仍然大于 0，搜索会继续。真正的风险是 ncclTopoSearchRec 中的 goto search 循环——如果 time 在循环中没有被正确重置，可能无限循环。看 ncclTopoCompute 中的 globalTimeout 逻辑：globalTimeout -= time 在每次 search 标签处执行，如果 globalTimeout 变成负数，会 goto done。但如果 time 被重置为 NCCL_SEARCH_TIMEOUT，globalTimeout 可能永远不会变成负数。修复方法是确保 globalTimeout 在每次搜索后都递减，且有一个硬上限。

</details>

<details><summary>Q3: ncclTopoFollowPath 在搜索失败时会调用 followPath(path, node1, step, -bw, &step) 恢复带宽。如果某个递归分支在恢复之前就返回了（比如 NCCLCHECKGOTO 跳转到 exit），会发生什么？如何检测这种问题？</summary>

参考解析：如果恢复被跳过，路径上的链路带宽会保持被扣减的状态。后续搜索会看到错误的带宽，可能错过最优解。检测方法：在 ncclTopoCompute 结束后，遍历所有链路，检查带宽是否与初始值一致。如果发现不一致，说明有恢复遗漏。修复方法：使用 RAII 风格的守卫对象，在析构时自动恢复带宽。或者，在每次搜索前保存所有链路的带宽快照，搜索后恢复。NCCL 当前的做法是在每个 ncclTopoFollowPath 调用点手动配对正向和反向调用，这容易出错。一个更健壮的设计是把带宽扣减和恢复封装成一个函数，确保成对出现。

</details>

下一章我们将深入 tuning 模块，看 NCCL 如何根据拓扑搜索结果和消息大小，在 Ring、Tree、CollNet 等算法之间做出最终选择。本章建立的拓扑图、路径搜索结果和算法模板，将成为 tuning 模块的输入。

通过 topo.cc 的图构建、search.cc 的路径搜索以及 rings.cc 和 trees.cc 的拓扑生成，NCCL 实现了用通用图结构描述任意拓扑、用可配置搜索算法找到最优解、用简单模板生成最终算法的设计哲学。这套机制让 NCCL 能在从 2 卡工作站到 10000 卡集群的各种机器上自动选到合适的算法。然而，拓扑图只是提供了算法的候选路径，具体到一次通信该走哪条路、用哪种协议，还需要更精细的决策。下一章我们将聚焦 src/tuning 目录，看看 tuning 模块如何结合代价模型与算法估计，在 Ring/Tree/NVLS/PAT 以及 LL/LL128/Simple 之间做出最终选择。

第 5 章：算法与协议选型：tuning 模块如何决定通信路径

上一章我们拆解了 NCCL 的拓扑感知能力：从 src/graph/topo.cc 枚举设备构建拓扑图，到 src/graph/search.cc 搜索最优路径，再到 rings.cc 与 trees.cc 将搜索结果具体化为 Ring 与 Tree 算法拓扑。但拓扑图只回答了「数据能走哪条路」，它没有回答「这次通信应该走哪条路」。同一台机器上，一次 4KB 的 AllReduce 和一次 400MB 的 AllReduce，最优解可能完全不同：前者拼的是延迟，后者拼的是带宽；前者可能选 Tree/LL，后者可能选 Ring/Simple 或者 NVLS。tuning 模块就是那个「拍板的人」。它的输入是消息大小、rank 数、拓扑图（上一章的产物）和用户环境变量；输出是一个 ncclTuningResult_t，里面写着用哪个算法（algo）、哪个协议（proto）、开多少 channel、用多少 warp。这一章我们按「总调度 → 代价模型 → 各算法估计 → 收尾决策」的顺序，把 src/tuning 目录拆开。核心问题只有一个：NCCL 怎么在几十种 (算法, 协议) 组合里，用一套纯 CPU 的数学模型，在微秒级时间内选出最快的那一个？

一、tuning.cc：总调度与决策主干

直觉模型

把 tuning 模块想象成一家搬家公司。客户（一次集合通信）来了，说「我要搬 100MB 的货，从 8 个仓库搬到 8 个仓库」。调度员（ncclTuningCompute）不会真的去搬一遍试试，而是拿出一张价目表（代价模型），对每种方案（Ring/LL、Tree/Simple、NVLS/Simple……）估算一个「预计耗时」，然后挑最短的那个报价给客户。

如果没有这个调度员，NCCL 就只能写死「AllReduce 永远用 Ring」，那在小消息场景会被 Tree 吊打，在大规模 NVLink 场景会被 NVLS 吊打。代价就是性能在特定场景下腰斩甚至更差。

数据结构与内存布局

决策的载体是 ncclTuningResult_t，候选集合是 ncclTuningResultList_t（一个单链表）。链表节点定义在 tuning_int.h，但 push 逻辑在 tuning.cc 里：

📎 src/tuning/tuning.cc:32-39

ncclResult_t ncclTuningResultListPushFront(struct ncclTuningResultList_t* list, struct ncclTuningResult_t result) {
  struct ncclTuningResultListNode* node = nullptr;
  NCCLCHECK(ncclCalloc(&node, 1));
  node->result = result;
  node->next = list->head;
  list->head = node;
  return ncclSuccess;
}

ncclTuningResult_t 里最关键的两个字段是 timeUs（预计耗时，微秒）和 selectionTimeUs（用于选择的耗时，可能被 tuner 插件覆盖）。选择逻辑只看后者：

📎 src/tuning/tuning.cc:155-173

static ncclResult_t ncclTuningSelectBestTuning(struct ncclTuningResultList_t* tunings,
                                               struct ncclTuningResult_t* const bestTuning) {
  bestTuning->timeUs = FLT_MAX;
  float bestSelectionTimeUs = FLT_MAX;
  struct ncclTuningResultListNode* node = tunings->head;
  while (node != nullptr) {
    const struct ncclTuningResult_t& tuning = node->result;
    float selectionTimeUs = tuning.selectionTimeUs > 0.0f ? tuning.selectionTimeUs : tuning.timeUs;
    ...
    if (selectionTimeUs < bestSelectionTimeUs) {
      *bestTuning = tuning;
      bestSelectionTimeUs = selectionTimeUs;
    }
    node = node->next;
  }
  return ncclSuccess;
}

这里有个细节：bestTuning->timeUs 先被设成 FLT_MAX，然后遍历。如果链表为空（所有候选都无效），bestTuning 会保持 NCCL_TUNING_RESULT_INIT 的初始值，algo/proto 都是 UNDEF。这个「空结果」在调用方会被特殊处理——见后面的错误分支。

Step-by-Step Walkthrough：一次 AllReduce 的决策流

假设应用调用 ncclAllReduce，消息 1MB，8 个 rank 单机 NVLink。我们跟着 ncclTuningCompute 走一遍。

第 0 步：单 rank 短路。 如果 nRanks <= 1，根本不需要通信，直接返回 Ring/Simple，channel 数设 0：

📎 src/tuning/tuning.cc:191-200

  // Set tuning to Ring/Simple for single rank case
  if (input->comm->nRanks <= 1) {
    bestTuning.algo = NCCL_ALGO_RING;
    bestTuning.proto = NCCL_PROTO_SIMPLE;
    bestTuning.symKernelId = ncclSymkKernelId_Count;
    bestTuning.ceMethodId = ncclCeMethodId_Count;
    bestTuning.nChannels = 0;
    bestTuning.maxChannels = 0;
    bestTuning.nWarps = 0;
    bestTuning.forced = 0;
  } else {

这个短路很重要：单 rank 时任何算法估计都会除以 nRanks-1 之类的量，容易出 NaN 或除零。先兜底，再算账，是防御式编程的典型。

第 1 步：枚举所有候选。 进入 ncclTuningComputeAllTunings，它遍历 NCCL_TUNING_COUNT 个 id：

📎 src/tuning/tuning.cc:128-149

ncclResult_t ncclTuningComputeAllTunings(struct ncclTuningInput_t* const input,
                                         struct ncclTuningResultList_t* const tunings) {
  ncclResult_t ret = ncclSuccess;

  for (int i = 0; i < NCCL_TUNING_COUNT; i++) {
    struct ncclTuningResult_t tuning = NCCL_TUNING_RESULT_INIT;
    tuning.id = i;
    tuning.valid = 1;

    if (!(input->tuningMask & (1ULL << i))) {
      tuning.valid = 0;
      continue;
    }
    NCCLCHECK(ncclTuningExpandId(i, &tuning.algo, &tuning.proto, &tuning.symKernelId, &tuning.ceMethodId));
    NCCLCHECKGOTO(ncclTuningComputeTuning(i, input, &tuning), ret, fail);
    if (tuning.valid) NCCLCHECKGOTO(ncclTuningResultListPushFront(tunings, tuning), ret, fail);
  }
...
}

注意 tuningMask 是一个 64 位掩码，第 i 位表示「第 i 个 (algo, proto) 组合是否允许」。这个掩码在更上层根据平台能力、用户环境变量、函数类型算出来。掩码是「粗筛」，代价模型是「精算」——先排除掉根本不可能的（比如 PCI 机器上不可能有 NVLS），再对剩下的算时间。

ncclTuningExpandId 把一维 id 展开成 (algo, proto, symKernelId, ceMethodId)。这个映射关系必须和 cost_model.cc 里的 modelMap 数组严格一致，否则会算错模型。

第 2 步：逐个算代价。 ncclTuningComputeTuning 只有一行，转交给代价模型：

📎 src/tuning/tuning.cc:339-343

ncclResult_t ncclTuningComputeTuning(int id, struct ncclTuningInput_t* const input,
                                     struct ncclTuningResult_t* const result) {
  NCCLCHECK(ncclTuningCostModelSimModel(id, input, result));
  return ncclSuccess;
}

第 3 步：tuner 插件介入（可选）。 如果用户装了 tuner 插件（比如某些云厂商的自研调优器），NCCL 会把所有候选的 timeUs 打包成一个二维表 generalTable[algo][proto] 交给插件，让插件覆盖：

📎 src/tuning/tuning.cc:203-230

    if (input->comm->tuner != NULL) {
      float generalTable[NCCL_NUM_ALGORITHMS][NCCL_NUM_PROTOCOLS];
      for (int i = 0; i < NCCL_NUM_ALGORITHMS; i++) {
        for (int j = 0; j < NCCL_NUM_PROTOCOLS; j++) {
          generalTable[i][j] = NCCL_TUNING_IGNORE;
        }
      }
      struct ncclTuningResultListNode* node = tunings.head;
      while (node != nullptr) {
        const struct ncclTuningResult_t& tuning = node->result;
        node = node->next;
        if (tuning.algo == NCCL_ALGO_UNDEF || tuning.proto == NCCL_PROTO_UNDEF) continue;
        generalTable[tuning.algo][tuning.proto] = tuning.timeUs;
      }
      node = tunings.head;
      int nMaxChannels = 0;
      NCCLCHECKGOTO(input->comm->tuner->getCollInfo(input->comm->tunerContext, input->func, input->nBytes,
                                                    input->numPipeOps, (float**)generalTable, NCCL_NUM_ALGORITHMS,
                                                    NCCL_NUM_PROTOCOLS, input->regBuff, &nMaxChannels),
                    ret, exit);
      while (node != nullptr) {
        struct ncclTuningResult_t& tuning = node->result;
        node = node->next;
        if (tuning.algo == NCCL_ALGO_UNDEF || tuning.proto == NCCL_PROTO_UNDEF) continue;
        tuning.maxChannels = nMaxChannels;
        tuning.timeUs = generalTable[tuning.algo][tuning.proto];
      }
    }

这里 NCCL_TUNING_IGNORE 是一个哨兵值，表示「这个组合没算过/不适用」。插件可以只改它关心的格子，其他格子保持 IGNORE，NCCL 会跳过。

第 4 步：选最优。 调 ncclTuningSelectBestTuning，遍历链表取 selectionTimeUs 最小的。

第 5 步：算 channel 数。 选出算法后，还要决定开多少 channel：

📎 src/tuning/tuning.cc:233-235

  if (bestTuning.algo != NCCL_ALGO_UNDEF && bestTuning.proto != NCCL_PROTO_UNDEF) {
    NCCLCHECKGOTO(ncclTuningGetChannels(input, &bestTuning), ret, exit);
  }

ncclTuningGetChannels 在 tuning_int.h 里，逻辑是根据消息大小和算法类型，在 minChannels 和 maxChannels 之间插值。channel 数直接影响带宽：channel 越多，并行度越高，但每个 channel 的启动开销也越大。

第 6 步：CTA Policy 偏置（NVLS 优先）。 如果用户设了 NCCL_CTA_POLICY_EFFICIENCY，且当前是 AllGather/ReduceScatter 且 buffer 已注册，NCCL 会尝试把结果改成 NVLS：

📎 src/tuning/tuning.cc:240-257

  if (input->comm->tuner == NULL && (input->CTAPolicy & NCCL_CTA_POLICY_EFFICIENCY) &&
      ncclGetEnv("NCCL_ALGO") == NULL && ncclGetEnv("NCCL_PROTO") == NULL && !input->comm->MNNVL &&
      (input->tuningMask & (1ull << (NCCL_ALGO_NVLS * NCCL_NUM_PROTOCOLS + NCCL_PROTO_SIMPLE)))) {
    if (input->regBuff && (input->func == ncclFuncAllGather || input->func == ncclFuncReduceScatter)) {
      if ((input->comm->nNodes > 1 && input->collNetSupport && input->nvlsSupport) ||
          (input->comm->nNodes == 1 && input->nvlsSupport)) {
        int recChannels;
        NCCLCHECKGOTO(ncclNvlsRegResourcesQuery(input->comm, input->func, &recChannels), ret, exit);
        if (recChannels <= bestTuning.nChannels) {
          bestTuning.algo = NCCL_ALGO_NVLS;
          ...

这段代码的注释很关键：EFFICIENCY 偏置必须在 GetChannels 之后跑，因为要用到 bestTuning.nChannels；而且必须检查 tuningMask 里 NVLS 位是否被允许，否则会「复活」一个被上层排除的算法。这是典型的状态依赖顺序陷阱。

第 7 步：对称 kernel 回退。 如果选中的是对称 kernel（symKernelId），但 buffer 没注册、或者平台不支持，需要回退到普通 kernel。这段逻辑在 tuning.cc:258-298，是整章最绕的地方，我们放到第五节专门讲。

第 8 步：无解报错。 如果所有候选都无效，algo/proto 都是 UNDEF，NCCL 会打一条 WARN，并根据用户是否设了环境变量返回不同错误码：

📎 src/tuning/tuning.cc:308-329

  if ((bestTuning.algo == NCCL_ALGO_UNDEF || bestTuning.proto == NCCL_PROTO_UNDEF) &&
      bestTuning.symKernelId == ncclSymkKernelId_Count && bestTuning.ceMethodId == ncclCeMethodId_Count) {
    ...
    WARN("No algorithm/protocol nor symKernelId available for function %s with datatype %s.%s%s%s",
         ncclFuncToString(input->func), ncclDatatypeToString(input->datatype), ncclAlgoEnvStr, ncclProtoEnvStr,
         ncclSymKernelIdEnvStr);
    ret = (algoEnv || protoEnv || symKernelIdEnv) ? ncclInvalidUsage : ncclInternalError;
  }

为什么区分错误码？ 如果用户设了 NCCL_ALGO=ring 但当前平台不支持 ring（比如某些特殊拓扑），那是用户配置错误（ncclInvalidUsage）；如果用户没设任何环境变量却选不出算法，那是 NCCL 内部 bug（ncclInternalError）。这个区分对排障至关重要。

决策主干流程图

flowchart TD
    start["ncclTuningCompute(input)"] --> check_rank{"comm->nRanks <= 1?"}
    check_rank -->|是| single["bestTuning = Ring/Simple<br/>nChannels = 0"]
    check_rank -->|否| enum["ncclTuningComputeAllTunings<br/>遍历 NCCL_TUNING_COUNT"]
    enum --> mask{"tuningMask & (1<<i)?"}
    mask -->|否| skip["tuning.valid = 0<br/>continue"]
    mask -->|是| expand["ncclTuningExpandId(i)"]
    expand --> sim["ncclTuningComputeTuning<br/>-> ncclTuningCostModelSimModel"]
    sim --> valid{"result.valid?"}
    valid -->|是| push["ncclTuningResultListPushFront"]
    valid -->|否| skip
    push --> tuner{"comm->tuner != NULL?"}
    tuner -->|是| plugin["tuner->getCollInfo<br/>覆盖 generalTable"]
    tuner -->|否| select
    plugin --> select["ncclTuningSelectBestTuning<br/>取 selectionTimeUs 最小"]
    select --> getch["ncclTuningGetChannels"]
    getch --> cta{"CTA_POLICY_EFFICIENCY<br/>且 NVLS 在 mask 内?"}
    cta -->|是| nvls["ncclNvlsRegResourcesQuery<br/>可能改写为 NVLS"]
    cta -->|否| symk
    nvls --> symk{"symKernelId 需要回退?"}
    symk -->|是| fallback["ncclTuningCompute(generalInput)<br/>回退普通 kernel"]
    symk -->|否| done
    fallback --> done["*result = bestTuning"]
    single --> done
    done --> undef{"algo/proto 仍 UNDEF?"}
    undef -->|是| warn["WARN + 返回<br/>InvalidUsage 或 InternalError"]
    undef -->|否| ret_ok["返回 ncclSuccess"]

---

二、cost_model.cc：模型注册表与开关矩阵

直觉模型

cost_model.cc 是 tuning 的总账本。它维护一张 modelMap 表，每一行对应一个 (algo, proto) 组合，记录「这个组合的初始化函数是谁、仿真函数是谁、对哪些函数启用」。同时它负责解析用户环境变量 NCCL_ALGO/NCCL_PROTO/NCCL_SYM_KERNEL，把用户的意图翻译成一张 enabled[i][f] 开关矩阵。

如果没有这张表，每加一个新算法就要改一遍 tuning 主流程，代码会烂成一锅粥。表驱动让「加算法」变成「加一行」。

数据结构：modelMap 与开关矩阵

modelMap 是一个静态数组，每个元素是 ncclTuningModelEntry_t：

📎 src/tuning/cost_model.cc:230-277

static struct ncclTuningModelEntry_t modelMap[] = {
  {ncclTuningTreeModelInit, ncclTuningTreeModelSim, nullptr, {0, 0, 0, 0, 1}},       // Tree/LL
  {ncclTuningTreeModelInit, ncclTuningTreeModelSim, nullptr, {0, 0, 0, 0, 1}},       // Tree/LL128
  {ncclTuningTreeModelInit, ncclTuningTreeModelSim, nullptr, {0, 0, 0, 0, 1}},       // Tree/Simple
  {ncclTuningRingModelInit, ncclTuningRingModelSim, nullptr, {1, 1, 1, 1, 1}},       // Ring/LL
  ...
  {nullptr, nullptr, nullptr, {0}}, // CollNetDirect/LL, disabled as there is no implementation
  ...
};

每个 entry 有四个字段：init（初始化，算好 latency/bandwidth 存到 comm 里）、model（仿真，根据消息大小算最终 timeUs）、finalize（清理）、enabled[5]（对 Broadcast/Reduce/AllGather/ReduceScatter/AllReduce 五个函数是否启用）。

注意 enabled 数组的顺序注释在 L234：Enable order: Broadcast, Reduce, AllGather, ReduceScatter, AllReduce。这个顺序必须和 ncclFunc_t 枚举一致，否则会张冠李戴。

Step-by-Step：环境变量解析与开关矩阵构建

第 1 步：默认全开，LL128 特殊。 ncclTuningCostModelInit 一开始把所有 proto 设成 1（启用），但 LL128 设成 2：

📎 src/tuning/cost_model.cc:313-323

  for (int f = 0; f < NCCL_NUM_FUNCTIONS; f++) {
    for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) {
      protoEnable[f * NCCL_NUM_PROTOCOLS + p] = p == NCCL_PROTO_LL128 ? 2 : 1;
    }
    for (int a = 0; a < NCCL_NUM_ALGORITHMS; a++) {
      algoEnable[f * NCCL_NUM_ALGORITHMS + a] = 1;
    }
    for (int k = 0; k < ncclSymkKernelId_Count; k++) {
      symKernelIdEnable[f * ncclSymkKernelId_Count + k] = 1;
    }
  }

为什么 LL128 是 2 而不是 1？ 因为 LL128 不是「默认启用」，而是「有条件启用」。2 是一个特殊标记，表示「用户没显式要求，稍后由 isLL128Enabled 根据平台能力决定」。1 表示「无条件启用」，0 表示「禁用」。这个三态设计在 L366 的判断里体现：

📎 src/tuning/cost_model.cc:364-370

      // Disable LL128 when 1) it is not supported on the platform, and 2) user did not explicitly request it.
      // protoEnable[..] == 2 indicates that user did not set NCCL_PROTO=LL128 explicitly.
      if (proto == NCCL_PROTO_LL128 && protoEnable[f * NCCL_NUM_PROTOCOLS + proto] == 2 &&
          !isLL128Enabled(comm->minCompCap, comm->maxCompCap, comm->graphs[algo].typeInter,
                          comm->graphs[algo].typeIntra, comm->nRanks, f, algo, comm->minDriverVersion)) {
        comm->tuningContext.enabled[i][f] = 0;
      }

第 2 步：解析用户环境变量。 如果用户设了 NCCL_ALGO 或 NCCL_SYM_KERNEL，先把 algo 和 symKernel 全清零（因为用户指定了白名单）：

📎 src/tuning/cost_model.cc:327-345

  if ((algoStr && strlen(algoStr) > 0) || (symKernelIdStr && strlen(symKernelIdStr) > 0)) {
    std::fill_n(algoEnable, NCCL_NUM_FUNCTIONS * NCCL_NUM_ALGORITHMS, 0);
    std::fill_n(symKernelIdEnable, NCCL_NUM_FUNCTIONS * ncclSymkKernelId_Count, 0);
  }
  if (protoStr) {
    INFO(NCCL_ENV, "NCCL_PROTO set by environment to %s", protoStr);
    NCCLCHECK(parseList(protoStr, ncclFuncStr, NCCL_NUM_FUNCTIONS, ncclProtoStr, NCCL_NUM_PROTOCOLS, protoEnable,
                        comm->tuningContext.forced));
  }

注意 proto 没有清零——因为 proto 的默认值是 1/2，用户设 NCCL_PROTO=LL 时，parseList 会把 LL 设成 1、其他设成 0（因为 unset 逻辑）。这个不对称是刻意的：algo 默认全开但用户指定后要收窄，proto 的收窄由 parseList 内部处理。

第 3 步：parseList 的语法。 这个函数支持相当复杂的语法，注释里给了例子：

📎 src/tuning/cost_model.cc:14-32

// Parse a map of prefixes to a list of elements. The first prefix is
// optional and, if not present, the list of elements will be applied
// to all prefixes. Only the first list of elements can lack a
// prefix. Prefixes (if present) are followed by a colon. Lists of
// elements are comma delimited. Mappings of prefix to the lists of
// elements are semi-colon delimited.
//
// For example:
//
//     NCCL_ALGO="ring,collnetdirect;allreduce:tree,collnetdirect;broadcast:ring"
// Enable ring and collnetdirect for all functions, then select tree
// and collnetdirect for allreduce and ring for broadcast.

^ 前缀表示「取反」：

📎 src/tuning/cost_model.cc:59-67

    int unset, set;
    if (elemList[0] == '^') {
      unset = 1;
      set = 0;
      elemList++;
    } else {
      unset = 0;
      set = 1;
    }

所以 NCCL_PROTO="^LL128;allreduce:LL128" 的意思是：全局禁用 LL128，但 AllReduce 例外启用 LL128。

第 4 步：合并 enabled 矩阵。 最后遍历所有 model，把 model->enabled[f] 和用户开关做与运算：

📎 src/tuning/cost_model.cc:371-383

      //  Check the user env vars only for functions that have a forced configuration and not already disabled.
      if (comm->tuningContext.forced[f] == 0 || comm->tuningContext.enabled[i][f] == 0) continue;
      comm->tuningContext.enabled[i][f] = 0;
      ...
      if (((algo != NCCL_ALGO_UNDEF && algoEnable[f * NCCL_NUM_ALGORITHMS + algo] != 0) &&
           (proto != NCCL_PROTO_UNDEF && protoEnable[f * NCCL_NUM_PROTOCOLS + proto] != 0)) ||
          (symKernelId != ncclSymkKernelId_Count && symKernelIdEnable[f * ncclSymkKernelId_Count + symKernelId] != 0)) {
        comm->tuningContext.enabled[i][f] = 1;
      }

逻辑是：只有当用户对某个函数设了 forced 配置时，才用用户配置覆盖模型默认值。如果用户没设，forced[f] == 0，直接 continue，保留模型自己的 enabled。这是「用户显式指定 > 模型默认」的优先级。

模型仿真的统一入口

所有模型最终都通过 ncclTuningCostModelSimModel 调用：

📎 src/tuning/cost_model.cc:470-497

ncclResult_t ncclTuningCostModelSimModel(int id, struct ncclTuningInput_t* const input,
                                         struct ncclTuningResult_t* const result) {
  struct ncclTuningModelEntry_t* model = nullptr;
  ncclResult_t ret = ncclSuccess;
  result->forced = input->comm->tuningContext.forced[input->func];
  NCCLCHECKGOTO(getModelEntry(id, &model), ret, not_valid);
  if (model == nullptr) {
    ret = ncclInternalError;
    goto not_valid;
  }
  if (input->comm->tuningContext.enabled[id][input->func] == 0) {
    goto not_valid;
  }
  if (model->model != nullptr) {
    NCCLCHECKGOTO(model->model(input, result), ret, not_valid);
    if (result->timeUs <= 0.0) {
      goto not_valid;
    }
  } else {
    goto not_valid;
  }
exit:
  return ret;
not_valid:
  result->timeUs = NCCL_TUNING_IGNORE;
  result->valid = 0;
  goto exit;
}

三层过滤：id 越界 → 模型禁用 → 模型返回非正时间，任何一层不过都走 not_valid，把 timeUs 设成 NCCL_TUNING_IGNORE（一个负数哨兵）、valid = 0。调用方看到 valid == 0 就不会把它挂进候选链表。

设计思考

modelMap 的注释里有一句关键警告：

📎 src/tuning/cost_model.cc:229

// IMPORTANT: this table need must be consistent with the algRegistry in src/config/algorithm_registry.cc

---

三、ring.cc：Ring 算法的代价估计

直觉模型

Ring 算法把 N 个 rank 排成一个环，数据沿着环一圈一圈传。它的代价模型要回答两个问题：每步传多少数据（带宽）、一共要多少步（延迟）。

Ring 的直觉是「流水线」：想象 N 个人站成一圈传水桶，每个人接到桶后倒一点水再传给下一个人。桶转一圈，所有人的水都混匀了。桶转得越快（带宽高）、圈越小（步数少），整体越快。

数据结构：latency/bandwidth 表

Ring 模型不引入新结构，它把估计结果写进 comm->tuningContext.generalLatencies[c][algo][proto] 和 generalBandwidths[c][algo][proto]。这两个是三维数组：函数 × 算法 × 协议。

初始化时先全部设成 -1.0（哨兵，表示「没算过」）：

📎 src/tuning/ring.cc:31-33

  for (int c = 0; c < NCCL_NUM_FUNCTIONS; c++) {
    comm->tuningContext.generalLatencies[c][algo][proto] = -1.0;
    comm->tuningContext.generalBandwidths[c][algo][proto] = -1.0;

-1.0 这个哨兵在 sim 阶段被检查：

📎 src/tuning/ring.cc:94-97

  if (inputs->comm->tuningContext.generalBandwidths[inputs->func][tuning->algo][tuning->proto] == -1.0f) {
    tuning->valid = 0;
    return ncclSuccess;
  }

为什么用 -1.0 而不是 0？ 因为 0 是一个合法的带宽值（虽然物理上不可能），而 -1.0 明确表示「未初始化」。浮点比较用 == 在这里是安全的，因为 -1.0 是精确可表示的。

Step-by-Step：Ring 带宽估计

第 1 步：确定用 intra 还是 inter 带宽。 单机（nNodes==1）用 intra，多机用 inter：

📎 src/tuning/ring.cc:34-37

    int nSteps = ncclTuningGetNsteps(c, comm->nRanks);
    float bw = (comm->nNodes == 1 || (comm->nNodes <= 2 && comm->minCompCap < 100)) ? comm->graphs[algo].bwIntra :
                                                                                      comm->graphs[algo].bwInter;
    float busBw = bw * comm->graphs[algo].nChannels;

nSteps 是算法需要的步数，对 Ring 来说 AllReduce 是 2*(nRanks-1)，其他是 nRanks-1。busBw 是「总线带宽」= 单链路带宽 × channel 数。

第 2 步：按协议打折。 LL 协议只用了带宽的一半（因为 LL 的 flag 开销），LL128 用 92%（120/128）：

📎 src/tuning/ring.cc:38-42

    if (proto == NCCL_PROTO_LL) {
      busBw = std::min(llMaxBw, busBw * .5);
    }
    if (proto == NCCL_PROTO_LL128)
      busBw = std::min(busBw * (0.92 /*120.0/128.0*/), comm->graphs[algo].nChannels * perChMaxRingLL128Bw);

0.92 = 120/128 是因为 LL128 每 128 字节里有 8 字节是 flag，有效载荷只有 120 字节。这个数字直接来自协议设计。

第 3 步：算有效带宽。 注意这里乘了 nRanks / nSteps：

📎 src/tuning/ring.cc:44-46

    comm->tuningContext.generalLatencies[c][algo][proto] =
      comm->tuningContext.tuningConstants.baseLatencies[algo][proto];
    comm->tuningContext.generalBandwidths[c][algo][proto] = busBw * comm->nRanks / nSteps;

为什么乘 nRanks / nSteps？ 这是 Ring 算法的核心特性：每个 rank 实际搬运的数据量是 nBytes * nSteps / nRanks（因为数据要绕环多圈）。所以「有效带宽」= 总线带宽 × nRanks / nSteps。对 AllReduce，nSteps = 2(nRanks-1)，所以有效带宽 ≈ busBw/2。

第 4 步：算延迟。 延迟分 intra 和 inter 两部分：

📎 src/tuning/ring.cc:48-63

    int intraHw, interHw;
    ncclTuningGetHwIndexes(comm, algo, &intraHw, &interHw);
    int hwLevel = comm->nNodes == 1 ? intraHw : interHw;

    float intraLat = comm->tuningContext.tuningConstants.hwLatencies[intraHw][algo][proto];
    // Preserve the pre-refactor model: with one rank per node, Ring inter-node steps use the exposed Tree NET latency.
    float interLat;
    if (comm->nNodes == 1) {
      interLat = intraLat;
    } else if (comm->maxLocalRanks == 1) {
      interLat = comm->tuningContext.tuningConstants.hwLatencies[NCCL_HW_NET][NCCL_ALGO_TREE][proto];
    } else {
      interLat = comm->tuningContext.tuningConstants.hwLatencies[interHw][algo][proto];
    }
    interLat += comm->graphs[algo].latencyInter;
    if (proto == NCCL_PROTO_SIMPLE) interLat += comm->graphs[algo].latencyInter;

注意 L57-58 的特殊处理：当 maxLocalRanks == 1（每个节点只有 1 个 rank）时，Ring 的 inter-node 延迟用 Tree 的 NET 延迟。注释说这是「preserve the pre-refactor model」——即为了保持和重构前行为一致，刻意保留的一个「怪癖」。这种历史包袱在成熟系统里很常见，读源码时看到「preserve」字样要格外小心，它往往意味着这里有个不能动的兼容性约束。

第 5 步：按函数类型累加。 Reduce/Broadcast 和 AllReduce/AllGather/ReduceScatter 的延迟模型不同：

📎 src/tuning/ring.cc:65-87

    if ((c == ncclFuncReduce || c == ncclFuncBroadcast)) {
      float lat = comm->tuningContext.tuningConstants.hwLatencies[hwLevel][algo][proto];
      if (comm->graphs[algo].sameChannels) {
        comm->tuningContext.generalLatencies[c][algo][proto] += lat;
      } else {
        if (proto == NCCL_PROTO_SIMPLE)
          lat =
            comm->tuningContext.tuningConstants
              .hwLatencies[hwLevel][NCCL_ALGO_TREE][proto]; // Add some chunk latency, waiting for proper chunk modeling
        comm->tuningContext.generalLatencies[c][algo][proto] += nSteps * lat;
      }
    } else {
      // Inter-node rings still have to launch nsteps * net overhead.
      float netOverhead = 0.0;
      if (comm->nNodes > 1) {
        netOverhead = getNetOverhead(comm);
        if (proto == NCCL_PROTO_SIMPLE) netOverhead *= 3;
      }
      intraLat = std::max(intraLat, netOverhead);
      int nInterSteps = comm->nNodes == 1 ? 0 : c == ncclFuncAllReduce ? 2 * (comm->nNodes - 1) : comm->nNodes - 1;
      comm->tuningContext.generalLatencies[c][algo][proto] +=
        (nSteps - nInterSteps) * intraLat + nInterSteps * interLat;
    }

sameChannels 是一个拓扑属性，表示「环上的 intra 和 inter 步是否用同一组 channel」。如果不同，延迟要乘 nSteps（每步都要等）。netOverhead 是网络 post 开销，Simple 协议要乘 3（因为 Simple 有三次网络往返：send、recv、ack）。

生产避坑：Ring/Simple 的 plateau 效应

ncclTuningRingModelSim 里有一段专门处理「plateau」的代码：

📎 src/tuning/ring.cc:105-137

  // Update Ring/Simple latency for multi-node AllReduce and
  // single NVL Domain AllReduce/AllGather/ReduceScatter for Blackwell
  bool isBlackwellNvLink =
    inputs->comm->minCompCap >= 100 && inputs->comm->graphs[NCCL_ALGO_RING].typeIntra == PATH_NVL;
  bool ringSimplePlateau =
    (inputs->comm->nNodes > 1 && inputs->func == ncclFuncAllReduce) ||
    (inputs->comm->nNodes == 1 && isBlackwellNvLink &&
     (inputs->func == ncclFuncAllReduce || inputs->func == ncclFuncAllGather || inputs->func == ncclFuncReduceScatter));
  size_t bytesPerRankPerChannel = inputs->nBytes / (inputs->comm->nChannels * inputs->comm->nRanks);

  if (tuning->algo == NCCL_ALGO_RING && tuning->proto == NCCL_PROTO_SIMPLE && ringSimplePlateau &&
      bytesPerRankPerChannel >= 64) {
    float plateauFactor = inputs->comm->minCompCap < 80 ? 1.9 : 1.4;
    ...
    lat *= plateauFactor; // Plateau effect of ring
  }

bytesPerRankPerChannel >= 64 是触发条件：每个 rank 每个 channel 至少要传 64 字节，否则 plateau 不成立。这个 64 字节来自 LL 协议的 flag 大小。

踩坑场景：如果你在 Blackwell 上跑一个 1MB 的 AllReduce，发现实际延迟比模型预测的高 40%，不要以为是 bug——这是 plateau 效应，模型已经把它算进去了。如果你手动改小 plateauFactor，模型会低估延迟，导致选错算法。

---

四、tree.cc 与 nvls.cc：Tree 与 NVLS 的代价估计

直觉模型

Tree 算法是「树形广播」：根节点把数据分给子节点，子节点再分给孙节点。它的优势是步数少（log N 而不是 N），适合小消息；劣势是带宽利用率低（每个非叶节点要转发，实际有效带宽只有一半）。

NVLS（NVLink SHARP）是「硬件多播」：交换机直接把数据复制给多个 GPU，不需要软件转发。它的优势是带宽高、延迟低，但需要特定硬件（Hopper 以上）和特定配置。

Tree 模型：只服务 AllReduce

Tree 模型有个硬性限制——只对 AllReduce 启用：

📎 src/tuning/tree.cc:21-27

  for (int c = 0; c < NCCL_NUM_FUNCTIONS; c++) {
    if (c != ncclFuncAllReduce) {
      comm->tuningContext.generalLatencies[c][algo][proto] = -1.0;
      comm->tuningContext.generalBandwidths[c][algo][proto] = -1.0;
      enabled[c] = 0; // Hard disable
      continue;
    }

Tree 带宽估计：

📎 src/tuning/tree.cc:28-43

    float bw = (comm->minCompCap < 100) ?
                 ((comm->nNodes <= 2) ? comm->graphs[algo].bwIntra : comm->graphs[algo].bwInter) :
                 std::min(comm->graphs[algo].bwInter, comm->graphs[algo].bwIntra);
    float busBw = bw * comm->graphs[algo].nChannels;
    if (c == ncclFuncAllReduce) busBw = std::min(busBw * .92, comm->graphs[algo].nChannels * perChMaxTreeBw);
    if (proto == NCCL_PROTO_LL) {
      busBw = std::min(busBw * 1.0 / 3.8, llMaxBw);
    }
    if (proto == NCCL_PROTO_LL128)
      busBw = std::min(busBw * (comm->nNodes == 1 ? 7.0 / 9.0 : 120.0 / 128.0),
                       comm->graphs[algo].nChannels * perChMaxTreeLL128Bw);
    if (comm->maxTreePattern == NCCL_TOPO_PATTERN_TREE) busBw *= .85;

Tree 延迟估计：

📎 src/tuning/tree.cc:55-58

    if (c == ncclFuncAllReduce) {
      comm->tuningContext.generalLatencies[c][algo][proto] +=
        2 * ((comm->nRanks / comm->nNodes - 1) * intraLat + log2i(comm->nNodes) * interLat);
    }

2 * 是因为 AllReduce = ReduceScatter + AllGather，两趟。(nRanks/nNodes - 1) 是节点内步数（每个节点内的 rank 数减一），log2i(nNodes) 是节点间步数（树的高度）。

Tree 的修正因子：Tree 模型在 sim 阶段乘了一个 treeCorrectionFactor：

📎 src/tuning/tree.cc:75-79

  int logSize = log2i(inputs->nBytes >> 6);
  float bw = inputs->comm->tuningContext.generalBandwidths[inputs->func][tuning->algo][tuning->proto];
  float lat = inputs->comm->tuningContext.generalLatencies[inputs->func][tuning->algo][tuning->proto];
  if (inputs->func == ncclFuncAllReduce && logSize >= 0 && logSize < 23)
    bw *= treeCorrectionFactor[tuning->proto][logSize];

treeCorrectionFactor 是一个 3×24 的表：

📎 src/tuning/cost_model.cc:223-227

float treeCorrectionFactor[NCCL_NUM_PROTOCOLS][24] = {
  {1.0, 1.0, 1.0, 1.0, .9, .8, .7, .7, .7, .7, .6, .5, .4, .4, .5, .6, .7, .8, .9, 1.0, 1.0, 1.0, 1.0, 1.0},
  {1.0, 1.0, 1.0, 1.0, 1.0, .9, .8, .8, .8, .7, .6, .6, .6, .6, .6, .6, .8, .9, .9, .9, .9, 1.0, 1.0, 1.0},
  {.9, .9, .9, .9, .9, .9, .9, .8, .7, .6, .6, .5, .5, .5, .5, .6, .7, .8, .7, .7, .8, .9, .9, .9}
};

logSize = log2(nBytes >> 6)，即消息大小以 64 字节为单位取 log2。表的下标 0-23 对应 64B 到 64B×2^23 ≈ 512MB。这个表是实测出来的「Tree 效率曲线」：小消息时效率 1.0（延迟主导），中等消息时效率掉到 0.4-0.5（带宽没打满），大消息时回到 1.0（带宽打满）。这个「中间凹陷」是 Tree 算法的固有特性。

NVLS 模型：硬件多播的代价

NVLS 模型首先检查硬件是否支持：

📎 src/tuning/nvls.cc:19-24

ncclResult_t ncclTuningNvlsModelInit(struct ncclComm* comm, int id, int enabled[NCCL_NUM_FUNCTIONS]) {
  ncclResult_t ret = ncclSuccess;
  if (!ncclNvlsTransportEnabled(comm)) {
    memset(enabled, 0, NCCL_NUM_FUNCTIONS * sizeof(int));
    return ncclSuccess;
  }

然后是一系列硬性约束：只支持 Simple 协议、单机不支持 NVLSTree、多机 NVLS 需要 CollNet：

📎 src/tuning/nvls.cc:28-41

  if ((algo == NCCL_ALGO_NVLS || algo == NCCL_ALGO_NVLS_TREE) && (proto != NCCL_PROTO_SIMPLE)) {
    memset(enabled, 0, NCCL_NUM_FUNCTIONS * sizeof(int));
    return ncclSuccess;
  }

  if (comm->nNodes == 1 && algo == NCCL_ALGO_NVLS_TREE) {
    memset(enabled, 0, NCCL_NUM_FUNCTIONS * sizeof(int));
    return ncclSuccess;
  }

  if (comm->config.collnetEnable == 0 && algo == NCCL_ALGO_NVLS && comm->nNodes > 1) {
    memset(enabled, 0, NCCL_NUM_FUNCTIONS * sizeof(int));
    return ncclSuccess;
  }

NVLS 带宽估计用了一个效率因子：

📎 src/tuning/nvls.cc:12-17

static const float nvlsEfficiency[NCCL_NUM_COMPCAPS] = {
  0.0f, // Volta
  0.0f, // Ampere
  0.85f, // Hopper
  0.74f, // Blackwell
};

带宽计算里有个 (nChannels - 1) / nChannels 因子：

📎 src/tuning/nvls.cc:62-74

    int nSteps = ncclTuningGetNsteps(c, comm->nRanks);
    float intraBw = comm->graphs[algo].bwIntra * nvlsEfficiency[compCapIndex] * (comm->graphs[algo].nChannels - 1) /
                    comm->graphs[algo].nChannels;
    if (c == ncclFuncAllReduce) {
      intraBw *= 2.0f;
    } else {
      float ppn = comm->minLocalRanks;
      intraBw *= (ppn - 1) / ppn;
    }
    float interBw = comm->graphs[algo].bwInter * ((comm->nNodes <= 2 && algo == NCCL_ALGO_NVLS_TREE) ? 2 : 1);
    bw = std::min({intraBw, interBw,
                   algo == NCCL_ALGO_NVLS_TREE ? (float)perChMaxNVLSTreeBw : std::numeric_limits<float>::max()});
    bw = bw * comm->graphs[algo].nChannels;

(nChannels - 1) / nChannels 是因为 NVLS 需要留一个 channel 做同步。(ppn - 1) / ppn 是 AllGather/ReduceScatter 的额外开销（每个 rank 要等前一个 rank 的数据）。

生产避坑：NVLS 的硬性约束

NVLS 模型在 sim 阶段还有一层运行时检查：

📎 src/tuning/nvls.cc:136-156

  int nvlsSupport = inputs->nvlsSupport;
  if (!nvlsSupport) {
    tuning->valid = 0;
    tuning->timeUs = -1.0;
    return ret;
  }
  if (inputs->func != ncclFuncAllReduce && inputs->comm->graphs[tuning->algo].nChannels > NCCL_MAX_NVLS_ARITY) {
    tuning->valid = 0;
    tuning->timeUs = -1.0;
    return ret;
  }
  if (inputs->func != ncclFuncAllReduce && inputs->comm->localRanks > NCCL_MAX_NVLS_ARITY) {
    tuning->valid = 0;
    tuning->timeUs = -1.0;
    return ret;
  }

NCCL_MAX_NVLS_ARITY 是 NVLS 多播组能容纳的最大 GPU 数。如果超过这个数，NVLS 不可用。踩坑场景：在一个 16 卡 NVLink 域里跑 AllGather，如果 NCCL_MAX_NVLS_ARITY 是 8，NVLS 会被禁用，tuning 会回退到 Ring。如果你不知道这个限制，会以为「NVLS 明明硬件支持为什么不用」。

---

五、对称 kernel 回退与错误恢复链

直觉模型

对称 kernel（symmetric kernel）是 NCCL 的新特性：当所有 rank 的 buffer 都注册到对称内存后，kernel 可以用更高效的指令访问对端内存。但如果 buffer 没注册，或者平台不支持，就必须回退到普通 kernel。这个回退逻辑是 tuning 里最绕的部分。

Step-by-Step：回退决策

回退逻辑在 tuning.cc:258-298。我们拆开看。

第 1 步：判断是否需要回退。 入口条件：

📎 src/tuning/tuning.cc:258-263

至此，tuning 模块的决策链条已经清晰：它接收拓扑图与通信参数，通过代价模型和算法估计，在微秒级内输出最优的 (算法, 协议, channel, warp) 组合。但选型只是开始——这个决策结果如何被下游使用？下一章我们将进入 src/enqueue/enqueue.cc 的主干，看一次 ncclAllReduce 调用如何经过参数校验、算法/协议确定、channel 切分，最终生成 ncclInfo 与 ncclTaskColl 结构。这是全书从「用户视角」切换到「引擎视角」的关键一章，你将探明一次集合通信调用在 host 侧被翻译成了什么，以及它与后续 kernel 启动之间的边界。

第 6 章：算子下发全景：ncclAllReduce 如何变成一个可执行的 kernel 任务

上一章我们走完了 tuning 模块，知道 NCCL 会在微秒级内为一次集合通信选定 (算法, 协议, channel, warp) 组合。但选型结果本身只是一堆数字——它需要被“翻译”成 GPU kernel 能读懂的任务描述对象，才能被真正执行。本章进入 src/enqueue/enqueue.cc 的主干，回答一个核心问题：当用户调用 ncclAllReduce 时，host 侧到底发生了什么？从 ncclAllReduce 到 ncclEnqueueCheck，经过参数校验、算法/协议确定、channel 切分，最终生成 ncclInfo 与 ncclTaskColl 结构。这是全书从“用户视角”切换到“引擎视角”的关键一章。如果把 NCCL 比作一家餐厅，那么 enqueue 模块就是“前台点单系统”：用户（应用层）说“我要一份 AllReduce”，前台把它翻译成厨房（GPU kernel）能执行的工单——几号灶台、用什么锅、分几批做。没有这个翻译层，厨房根本不知道要做什么菜。

一、入口：ncclAllReduce 如何构造 ncclInfo

直觉模型

ncclAllReduce 是用户直接调用的 API 函数。它的职责极其单一：把用户传入的裸参数打包成一个 ncclInfo 结构体，然后交给 ncclEnqueueCheck。这就像你去银行柜台办业务，柜员先把你的需求填进一张标准表单，再转交给后台系统。

如果没有这一层，每个集合通信 API 都要自己处理参数校验、group 语义、profiler 埋点——代码会重复到无法维护。

数据结构：ncclInfo 的内存布局

ncclInfo 是贯穿整个 enqueue 流程的核心载体。它的定义在 src/include/info.h：

📎 src/include/info.h:17-44

这个结构体有 20+ 个字段，我们可以按功能分成四组：

注意 collConfig 的注释："A config copied from config passed by user so older user config can be safely accessed during synchronous host scheduling (never at launch/replay)" 📎 src/include/info.h:41-43。这是一个关键设计——用户传入的 config 指针可能在 ncclGroupEnd 之前就被销毁，所以 NCCL 在 ncclInfo 里做了一份拷贝。

Step-by-Step：ncclAllReduce 的调用链

我们以 ncclAllReduce 为例，追踪从用户调用到 ncclInfo 构造的完整路径。

第 1 步：用户调用 ncclAllReduce。 入口在 src/collectives.cc：

📎 src/collectives.cc:206-211

这里做了三件事：

1. NVTX3_FUNC_WITH_PARAMS 打 NVTX 标记（用于 Nsight 等工具可视化）

2. 调用 ncclAllReduceConfigImpl，传入 config = nullptr

3. 返回结果

第 2 步：ncclAllReduceConfigImpl 构造 ncclInfo。 这是关键的一步：

📎 src/collectives.cc:192-202

注意这里用了 C 风格的聚合初始化：

struct ncclInfo info = {ncclFuncAllReduce, "AllReduce",
                        sendbuff, recvbuff, count, datatype, op, 0, comm, stream,
                        ALLREDUCE_CHUNKSTEPS, ALLREDUCE_SLICESTEPS};

字段按 ncclInfo 的声明顺序一一对应。ALLREDUCE_CHUNKSTEPS 和 ALLREDUCE_SLICESTEPS 定义在 src/include/collectives.h：

📎 src/include/collectives.h:19-20

NCCL_STEPS 是环形缓冲区里的步数（通常为 8 或 16），所以 AllReduce 的 chunkSteps 是 NCCL_STEPS/2，sliceSteps 是 NCCL_STEPS/4。这意味着一个 chunk 包含 2 个 slice。

第 3 步：解析用户 config。 ncclParseCollConfig 把用户传入的 ncclCollConfig_t* 解析进 info.collConfig。如果 config == nullptr，这个字段保持零初始化。

第 4 步：交给 ncclEnqueueCheck。 这是 enqueue 模块的真正入口。

设计思考：为什么用聚合初始化而不是逐字段赋值？

生产踩坑：config 生命周期

一个真实的踩坑场景：用户这样写代码：

ncclCollConfig_t config = {...};
ncclAllReduceConfig(..., &config);
// config 在这里被销毁（比如是栈变量，函数返回了）

如果 NCCL 没有在 ncclInfo 里拷贝 config，那么 ncclGroupEnd 时访问 info.collConfig 就会读到已释放的内存。src/include/info.h:41-43 的注释正是为了说明这个设计——config 在 task append 阶段就被解析并拷贝，之后不再依赖用户指针。

---

二、ncclEnqueueCheck：参数校验与 group 语义

直觉模型

ncclEnqueueCheck 是 enqueue 模块的"总闸门"。所有集合通信 API 最终都汇聚到这里。它的职责是：校验参数合法性、处理 group 语义、调用 taskAppend 生成任务。如果把它比作机场安检，那么每个 API 函数就是值机柜台——值机只是收行李，真正的安检在 ncclEnqueueCheck。

如果没有这一层，每个 API 都要自己写一遍参数校验和 group 处理，代码会膨胀数倍，而且容易漏掉某个校验。

Step-by-Step：ncclEnqueueCheck 的执行流程

📎 src/enqueue/enqueue.cc:3478-3527

我们逐步拆解：

第 1 步：CommCheck 校验通信域。 CommCheck(info->comm, info->opName, "comm") 检查 comm 指针是否非空、是否已初始化。如果 comm 被 revoke（比如某个 rank 出错），直接返回错误：

📎 src/enqueue/enqueue.cc:3480-3485

第 2 步：处理 profiler 深度。 如果已经在 group 内部（profilerGroupDepth > 0），递增深度计数。这是为了正确处理隐式的 ncclGroupStartInternal/ncclGroupEndInternal 调用。

第 3 步：进入内部 group。 ncclGroupStartInternal() 是 NCCL 内部的 group 机制。关键点：即使用户没有显式调用 ncclGroupStart，NCCL 也会为每次 API 调用创建一个隐式 group。这保证了单次调用的原子性。

第 4 步：确保 comm 就绪。 ncclCommEnsureReady(info->comm) 等待通信域初始化完成（比如 bootstrap 完成、连接建立）。

第 5 步：ArgsCheck 参数校验。 这是最复杂的校验步骤：

📎 src/enqueue/enqueue.cc:3497-3503

注意 checkMode 的处理：如果是 ncclCheckModeDebugGlobal，ArgsCheck 会把 info 入队，等 ncclGroupEnd 时做全局校验（比如检查所有 rank 的 count 是否一致）。

第 6 步：调用 taskAppend。 这是核心转换步骤：

📎 src/enqueue/enqueue.cc:3513

第 7 步：递增 opCount。 每次成功入队后，comm->opCount++。这个计数器用于匹配 send/recv 操作，也是 profiler 的时间线依据。

第 8 步：退出 group。 ncclGroupEndInternal() 如果 depth 降到 0，会触发真正的 group 操作（调度、启动 kernel）。

并发控制：group 语义与线程安全

一个容易踩的坑：如果用户在 ncclGroupStart 和 ncclGroupEnd 之间调用了非 NCCL 的 CUDA API（比如 cudaMemcpy），可能会导致 stream 顺序问题。NCCL 的 group 机制假设 group 内的操作都在同一组 stream 上。

错误恢复链

ncclEnqueueCheck 的错误处理有一个精巧的设计：

📎 src/enqueue/enqueue.cc:3524-3526

如果 taskAppend 失败，且 comm 是非阻塞模式，会调用 ncclCommSetAsyncError 记录错误。这样后续的 API 调用会立即返回错误，而不是继续尝试。这是异步错误传播机制。

---

三、taskAppend：任务分发的十字路口

直觉模型

taskAppend 是 enqueue 模块的"交通枢纽"。它根据 info->coll 的值，把任务分发到不同的处理路径：P2P、RMA、CE、或者普通集合通信。这就像一个邮局分拣中心——根据信封上的地址，把信件投到不同的邮筒。

如果没有这个分发层，所有类型的操作都要挤在一个巨大的 if-else 里，代码会难以维护。

Step-by-Step：taskAppend 的分发逻辑

📎 src/enqueue/enqueue.cc:3337-3476

第 1 步：判断是否启用新架构。 ncclParamEnqueueRearchEnable() 是一个环境变量开关（默认 0）。如果启用，走 rawTaskAppend 路径——这是 NCCL 正在开发的新任务模型。

第 2 步：P2P 分发。 如果是 Send/Recv，调用 p2pTaskAppend：

📎 src/enqueue/enqueue.cc:3343-3345

第 3 步：RMA 分发。 如果是 PutSignal/Signal/WaitSignal，调用 rmaTaskAppend：

📎 src/enqueue/enqueue.cc:3346-3347

第 4 步：空集合通信提前返回。 if (info->count == 0) return ncclSuccess;——count 为 0 的集合通信直接丢弃。

第 5 步：算法选择校验。 ncclCollConfigGetAlgMask 校验用户传入的算法选择是否合法：

📎 src/enqueue/enqueue.cc:3357-3358

第 6 步：FP8 类型检查。 FP8 归约需要 sm90+：

📎 src/enqueue/enqueue.cc:3360-3366

第 7 步：归约操作转换。 hostToDevRedOp 把 host 侧的 ncclRedOp_t 转换成设备侧的 ncclDevRedOpFull：

📎 src/enqueue/enqueue.cc:3370-3371

第 8 步：单 rank 提前返回。 如果 comm->nRanks == 1，直接调用 ncclLaunchOneRank 执行本地归约，不需要生成任务：

📎 src/enqueue/enqueue.cc:3373-3377

第 9 步：多 rank 路径。 这是最复杂的分支，包含 CE 路由、AllToAll/Gather/Scatter 降级、以及普通集合通信：

📎 src/enqueue/enqueue.cc:3378-3470

数据结构：ncclTaskColl 的字段

collTaskAppend 是生成 ncclTaskColl 的地方。我们看它的核心逻辑：

📎 src/enqueue/enqueue.cc:2757-2851

关键字段赋值：

注意 trafficBytes 的计算：

📎 src/enqueue/enqueue.cc:2813

ncclFuncTrafficPerByte 返回每种集合通信的流量倍数：

📎 src/enqueue/enqueue.cc:123-134

AllReduce 返回 2（因为要 reduce + broadcast），AllGather/ReduceScatter 返回 nRanks，其他返回 1。

设计思考：为什么 AllGather/Broadcast 要转成 int8？

📎 src/enqueue/enqueue.cc:2808-2812

AllGather 和 Broadcast 把 count 乘以 elementSize，然后把 datatype 改成 ncclInt8。这是一个优化：这两种操作不涉及归约，所以不需要关心数据类型，统一按字节处理可以简化 kernel 逻辑。

生产踩坑：CTAPolicy 的解析顺序

📎 src/enqueue/enqueue.cc:3390-3397

CTAPolicy 的解析有一个微妙的优先级：env > per-call > comm。而且 NCCL_CTA_POLICY_ZERO 优先于 NCCL_CTA_POLICY_EFFICIENCY。如果用户同时设置了这两个标志，ZERO 会生效。

一个真实的踩坑场景：用户设置了 NCCL_CTA_POLICY=EFFICIENCY，但发现 CE 路径没有被使用。原因是 CE 路由要求 CTAPolicy & NCCL_CTA_POLICY_ZERO 为真，而 EFFICIENCY 不满足这个条件。

---

四、ncclPrepareTasks：从任务列表到调度队列

直觉模型

ncclPrepareTasks 是 enqueue 模块的"预处理器"。它把散乱的任务列表按 (func, op, datatype) 分桶，然后为每个桶计算算法和协议。这就像一个图书馆管理员——先把还回来的书按类别分好，再决定每类书放在哪个书架。

如果没有这一步，后续的 scheduleCollTasksToPlan 就要为每个任务单独计算算法，效率极低。

Step-by-Step：ncclPrepareTasks 的分桶逻辑

📎 src/enqueue/enqueue.cc:423-642

第 1 步：Broadcast 任务转换。 如果只有一个 broadcast peer，把 broadcast 任务转成 coll 任务：

📎 src/enqueue/enqueue.cc:430-461

注意这里把 bcastTask 的字段拷贝到新的 ncclTaskColl，并计算 trafficBytes。然后从 memPool_ncclTaskBcast 释放原任务。

第 2 步：按 (func, op, datatype) 分桶。 任务从 sorter 出来是按 size 降序的，然后被分到 tasksByFnOpTy 数组：

📎 src/enqueue/enqueue.cc:464-487

索引计算：((int)task->func * ncclNumDevRedOps + (int)task->opDev.op) * ncclNumTypes + (int)task->datatype。这是一个三维数组的线性化。

第 3 步：聚合与算法选择。 对每个桶，聚合大小相近的任务（4 倍以内），然后调用 ncclGetAlgoInfo：

📎 src/enqueue/enqueue.cc:503-547

第 4 步：按 (collnet, nvls) 分桶。 根据算法类型，把任务分到 collBins[2][2]：

📎 src/enqueue/enqueue.cc:517-544

第 5 步：拼接最终队列。 把四个桶拼接成 planner->collTaskQueue：

📎 src/enqueue/enqueue.cc:553-557

数据结构：ncclTaskCollSorter

ncclTaskCollSorter 是一个按 trafficBytes 排序的插入式排序器。ncclTaskCollSorterInsert 把任务插入到正确位置，ncclTaskCollSorterDequeueAll 按顺序取出所有任务。

并发控制：runtimeConn 与连接建立

📎 src/enqueue/enqueue.cc:572-583

如果 comm->runtimeConn 为真（运行时连接模式），且某个算法的 channel 还没初始化，就标记 algoNeedConnect。这会在后续触发连接建立。

生产踩坑：聚合的边界条件

📎 src/enqueue/enqueue.cc:507-508

聚合条件是 aggEnd->trafficBytes < 4 * aggBeg->trafficBytes，且两个任务都不设置 aggIsolate。如果用户设置了 per-call config（比如 maxCTAs），aggIsolate 会被设为 true，这个任务就不会被聚合。

一个真实的踩坑场景：用户为某个 AllReduce 设置了 maxCTAs=4，期望它只用 4 个 CTA。但由于聚合逻辑，这个任务可能和相邻任务合并，导致实际使用的 CTA 数量不符合预期。解决方案是设置 aggIsolate——NCCL 在 collTaskAppend 里已经处理了这一点：

📎 src/enqueue/enqueue.cc:2821-2822

---

五、scheduleCollTasksToPlan：channel 切分与预算控制

直觉模型

scheduleCollTasksToPlan 是 enqueue 模块的"调度器"。它把任务分配到具体的 channel，并计算每个 channel 的数据切分。这就像一个工厂的排产系统——决定每条生产线做什么、做多少。

如果没有这一步，GPU kernel 就不知道自己要处理哪部分数据。

Step-by-Step：channel 切分算法

📎 src/enqueue/enqueue.cc:644-947

第 1 步：预算估算。 先估算能放进这个 plan 的任务数量：

📎 src/enqueue/enqueue.cc:648-689

ncclTestBudget 检查工作字节数是否超出预算：

📎 src/enqueue/enqueue.cc:343-349

第 2 步：计算每个 channel 的流量。 根据 kind（collnet/nvls）计算 trafficPerChannel：

📎 src/enqueue/enqueue.cc:701-707

第 3 步：Collnet 路径。 如果是 collnet 算法，channel 分配比较简单：

📎 src/enqueue/enqueue.cc:709-739

第 4 步：普通路径的 cell 切分。 这是最复杂的部分。NCCL 把数据切成 "cell"，每个 cell 是一个最小传输单元：

📎 src/enqueue/enqueue.cc:740-845

关键变量：

• cellSize：每个 cell 的字节数，至少 MinTrafficPerChannel（32KB）
• cells：总 cell 数
• cellsPerChannel：每个 channel 处理的 cell 数
• cellsLo/cellsHi：首尾 channel 的 cell 数（可能不满）

第 5 步：计算 chunkGrains。 对每个 channel 段调用 calcCollChunking：

📎 src/enqueue/enqueue.cc:811-825

第 6 步：生成 proxyOp。 为每个 channel 生成 proxy 操作：

📎 src/enqueue/enqueue.cc:844-894

数据结构：ncclDevWorkColl

ncclDevWorkColl 是设备侧的工作描述符。它的关键字段：

并发控制：channelMask 的位运算

📎 src/enqueue/enqueue.cc:897

这行代码用位运算设置 channelMask：(2ull << channelHi) - (1ull << channelLo)。比如 channelLo=2, channelHi=5，结果是 (2<<5) - (1<<2) = 64 - 4 = 60 = 0b111100，即 bit 2-5 被设置。

生产踩坑：预算溢出

📎 src/enqueue/enqueue.cc:792-794

如果预算不够，直接返回 ncclSuccess，让外层循环创建新的 plan。这是一个优雅的降级策略——不报错，只是分批处理。

一个真实的踩坑场景：如果 NCCL_WORK_FIFO_BYTES 设置得太小，会导致每个 plan 只能容纳很少的任务，增加 kernel 启动次数，降低性能。

---

六、finishPlan：从任务到 kernel 参数

直觉模型

finishPlan 是 enqueue 模块的"打包器"。它把任务、batch、proxyOp 打包成 kernel 能直接读取的参数结构。这就像快递打包——把散件装进箱子，贴上运单，等待发货。

Step-by-Step：finishPlan 的打包逻辑

📎 src/enqueue/enqueue.cc:236-330

第 1 步：决定存储类型。 如果所有工作都能放进 kernel args，用 ncclDevWorkStorageTypeArgs：

📎 src/enqueue/enqueue.cc:244-250

第 2 步：分配 kernelArgs。 从内存栈分配：

📎 src/enqueue/enqueue.cc:251-255

第 3 步：Round-robin 放置 batch。 每个 channel 的第一个 batch 必须放在 batchZero[blockIdx.x]：

📎 src/enqueue/enqueue.cc:257-280

第 4 步：合并 proxyOp 队列。 按 opCount 归并排序：

📎 src/enqueue/enqueue.cc:282-329

数据结构：ncclDevKernelArgs

ncclDevKernelArgs 是传给 kernel 的参数结构。它包含：

• comm：设备侧通信器
• channelMask：channel 位掩码
• workStorageType：工作存储类型
• workBuf：工作缓冲区指针
• workMask：工作缓冲区掩码

生产踩坑：batch 顺序

📎 src/enqueue/enqueue.cc:257-259

注释说得很清楚："The first batch for each channel must be located at batchZero[blockIdx.x]"。如果这个顺序错了，kernel 会读到错误的 batch，导致数据损坏。

---

本章小结

本章我们追踪了从 ncclAllReduce 到 ncclTaskColl 的完整路径：

1. ncclAllReduce 构造 ncclInfo，打包用户参数

2. ncclEnqueueCheck 校验参数、处理 group 语义

3. taskAppend 根据操作类型分发到不同路径

4. collTaskAppend 生成 ncclTaskColl，解析配置

5. ncclPrepareTasks 按 (func, op, datatype) 分桶，计算算法

6. scheduleCollTasksToPlan 切分 channel，生成 ncclDevWorkColl

7. finishPlan 打包成 kernel 参数

关键设计思想：

• 分层解耦：每个函数只做一件事，通过 ncclInfo 和 ncclTaskColl 传递状态
• 预算控制：通过 ncclTestBudget 控制每个 plan 的大小
• 聚合优化：大小相近的任务会被聚合，减少 kernel 启动次数
• 配置优先级：env > per-call > comm

下一章我们将进入 task_sched，看 NCCL 如何编排多 channel 多 kernel 的执行顺序。

本章思考与自测

<details><summary>Q1: 如果把 collTaskAppend 中的 aggIsolate 判断去掉（即 src/enqueue/enqueue.cc:2821-2822 永远返回 false），在什么场景下会导致用户设置的 maxCTAs 失效？为什么？</summary>

参考解析：aggIsolate 的作用是标记"这个任务不能被聚合"。如果去掉这个判断，设置了 per-call config 的任务会和相邻任务合并。在 ncclPrepareTasks 的聚合循环中（src/enqueue/enqueue.cc:507-508），聚合条件是 aggEnd->trafficBytes < 4 * aggBeg->trafficBytes && !aggBeg->aggIsolate && !aggEnd->aggIsolate。如果 aggIsolate 永远为 false，那么即使任务设置了 maxCTAs=4，它也可能和一个 maxCTAs=32 的任务合并。合并后的 agg 会取两者的某种组合（具体取决于 ncclGetAlgoInfo 的实现），导致实际使用的 CTA 数量不符合用户预期。

更严重的是，在 scheduleCollTasksToPlan 中（src/enqueue/enqueue.cc:665-666），taskAggIsolate 用于确保配置了 per-call 资源的任务单独占一个 plan。如果这个判断失效，多个任务会共享 plan 的 channel 预算，导致资源分配不符合预期。

</details>

<details><summary>Q2: 在 ncclEnqueueCheck 中，如果 ncclGroupEndInternal() 返回错误（比如某个 rank 的 ArgsCheck 失败），但 taskAppend 已经成功执行了，会发生什么？NCCL 如何保证状态一致性？</summary>

参考解析：看 src/enqueue/enqueue.cc:3513-3519 的控制流：

NCCLCHECKGOTO(taskAppend(info->comm, info), ret, fail);
info->comm->opCount++;
exit:
  if (devOld != -1) CUDACHECK(cudaSetDevice(devOld));
  ncclGroupErrCheck(ret);
  NCCLCHECK(ncclGroupEndInternal());

如果 taskAppend 成功但 ncclGroupEndInternal 失败，opCount 已经递增了。这会导致后续操作的 opCount 与对端不匹配，可能触发 hang。

NCCL 的处理方式是：ncclGroupErrCheck(ret) 会检查是否有错误，如果有，会设置 comm 的错误状态。后续的 API 调用会通过 ncclCommGetAsyncError 检测到这个错误并立即返回。这是一种"快速失败"策略——一旦出错，整个 comm 进入错误状态，不再尝试恢复。

在生产环境中，这意味着一旦出现 group 错误，用户需要销毁并重建 communicator。

</details>

<details><summary>Q3: scheduleCollTasksToPlan 中的 cell 切分算法（src/enqueue/enqueue.cc:740-845）有一个边界条件：当 cellsLo == 0 时，会跳过最少的 channel。如果这个跳过逻辑有 bug（比如 channelId 没有正确递增），会导致什么后果？</summary>

参考解析：看 src/enqueue/enqueue.cc:770-780：

if (cellsLo == 0) {
  // Least channel skipped. Make the next channel the new least.
  channelId += 1;
  if (nMidChannels == 0) {
    cellsLo = cellsHi;
    cellsHi = 0;
  } else {
    cellsLo = cellsPerChannel;
    nMidChannels -= 1;
  }
}

如果 channelId 没有正确递增，那么下一个任务会从错误的 channel 开始分配。这会导致：

1. channel 重叠：两个任务可能分配到同一个 channel 的同一段数据

2. 数据损坏：kernel 会重复处理或遗漏数据

3. 性能下降：channel 负载不均衡

更隐蔽的是，这种 bug 可能只在特定消息大小下触发（当 cellsLo == 0 时），难以复现。NCCL 通过 plan->channelMask |= (2ull << devWork->channelHi) - (1ull << devWork->channelLo) 来跟踪已使用的 channel，但这只是记录，不能防止重叠。

</details>

至此，我们已经看清 ncclAllReduce 如何从用户调用变成一串可执行的 kernel 任务：参数校验、算法/协议确定、channel 切分，最终生成 ncclInfo 与 ncclTaskColl。但任务被创建出来只是第一步——它们还需要被调度到多个 channel 上，生成 kernel 启动参数，并在 group 语义下处理批量提交与依赖排序。下一章将深入 src/enqueue/task_sched 与 src/enqueue/task_prep，回答“为什么一次 AllReduce 会启动多个 kernel，它们之间的顺序和依赖是怎么保证的”，同时揭示 src/group.cc 中 ncclGroupStart/ncclGroupEnd 如何把多次 API 调用合并成一次提交。

第 7 章：任务调度器：task_sched 如何编排多 channel 与 kernel 的执行顺序

上一章我们把 ncclAllReduce 一路追到了 ncclTaskColl——任务描述对象已经躺在 comm->planner 里了。但任务描述只是「工单」，还没变成 GPU 上真正跑的 kernel。这一章要回答三个问题：多次 API 调用怎么被攒起来一起提交？攒起来的任务怎么被切到多个 channel 上？多个 kernel 之间的顺序和依赖靠什么保证？先给一个整体心智模型。把 NCCL 想象成一家餐厅：ncclGroupStart/ncclGroupEnd 是「购物车」，用户把好几道菜（多次集合通信调用）丢进购物车；ncclGroupEnd 是「下单」，厨房才开始按订单做菜。而 doLaunches 是「传菜调度员」，它决定哪几道菜先上、哪几道菜可以并行做。没有 group 语义，每道菜单独下单，厨房每做一道就要重新点火（启动 kernel），开销巨大；没有 doLaunches 的轮次调度，多 channel 的 kernel 会乱序启动，导致数据依赖被破坏。

一、Group 语义的全局状态：thread_local 变量与「购物车」模型

直觉模型

ncclGroupStart 和 ncclGroupEnd 之间的所有通信调用，不会立即启动 kernel，而是被「攒」起来。攒在哪里？攒在线程局部（thread_local）的全局变量里。为什么是 thread_local？因为 NCCL 假设同一个线程内的 group 调用是串行的，不同线程各自有独立的购物车，互不干扰。如果这些状态是全局变量而非 thread_local，两个线程同时调用 ncclGroupStart 就会互相踩踏，导致一个线程的任务被另一个线程的 ncclGroupEnd 提交——这是灾难性的。

数据结构与内存布局

先看 group 的全局状态定义。

📎 src/group.cc:34-34

thread_local int ncclGroupDepth = 0; // depth of ncclGroupStart nesting
thread_local ncclResult_t ncclGroupError = ncclSuccess;
thread_local struct ncclComm* ncclGroupCommHead[ncclGroupTaskTypeNum] = {nullptr};
thread_local struct ncclComm* ncclGroupCommPreconnectHead = nullptr;
thread_local struct ncclIntruQueue<struct ncclAsyncJob, &ncclAsyncJob::next> ncclAsyncJobs;
thread_local int ncclGroupBlocking = -1; /* default mode */

逐个字段拆解：

• ncclGroupDepth：嵌套深度。ncclGroupStart 可以嵌套调用（虽然不常见），每次 ncclGroupStart 加一，ncclGroupEnd 减一。只有减到 0 时才真正提交。这就像购物车可以嵌套——你在一个购物车里又开了一个子购物车，只有最外层结算时才真正下单。
• ncclGroupError：group 内任意一次调用出错，错误被记录在这里，ncclGroupEnd 时统一处理。这避免了「一次调用失败后，后续调用还在往购物车里加东西」的不一致状态。
• ncclGroupCommHead[ncclGroupTaskTypeNum]：按任务类型分组的通信域链表头。ncclGroupTaskTypeNum 是任务类型数量（集合通信、原始任务、管理任务、对称注册等）。每个类型一条链表，链表节点是 ncclComm，通过 comm->groupNext[type] 串联。为什么按类型分？因为不同类型的任务提交时机和依赖关系不同——集合通信任务需要先 preconnect，管理任务（如 destroy）需要最后执行。
• ncclGroupCommPreconnectHead：需要预连接的通信域链表。预连接是「提前把网络连接建好」，避免在 kernel 启动时才建连接导致延迟。
• ncclAsyncJobs：异步任务队列。有些任务（如 ncclCommInitRank）是异步的，它们被放进这个队列，在 ncclGroupEnd 时统一启动。
• ncclGroupBlocking：阻塞模式标志。-1 表示还没确定，0 表示非阻塞，1 表示阻塞。同一个 group 内不允许混用阻塞和非阻塞通信域，否则报错。

这里有个关键设计：ncclGroupCommHead 是数组，每个元素是一条链表。链表节点通过 comm->groupNext[type] 串联，而不是用独立的链表节点结构。这意味着 ncclComm 结构体里必须预留 groupNext 数组字段。这种「侵入式链表」的设计避免了额外的内存分配，但代价是 ncclComm 结构体变大。

场景驱动的 Step-by-Step Walkthrough

场景：用户调用 ncclGroupStart()，然后连续调用两次 ncclAllReduce（分别针对两个不同的通信域 commA 和 commB），最后调用 ncclGroupEnd()。

第一步：ncclGroupStart 做了什么？

📎 src/include/group.h:63-66

inline ncclResult_t ncclGroupStartInternal() {
  ncclGroupDepth++;
  return ncclSuccess;
}

极其简单：深度加一。没有内存分配，没有锁，没有系统调用。这就是为什么 ncclGroupStart 几乎零开销。

第二步：ncclAllReduce 在 group 内被调用时发生了什么？

ncclAllReduce 内部会调用 ncclGroupCommJoin(comm, ncclGroupTaskTypeCollective)，把通信域加入 group 链表。

📎 src/include/group.h:80-116

inline void ncclGroupCommJoin(struct ncclComm* comm, int type) {
  if (comm->groupNext[type] == reinterpret_cast<struct ncclComm*>(NCCL_COMM_GROUP_INVALID)) {
    // Insert comm into ncclGroupCommHead adjacent to sibling comms. This preserves
    // the users program order yet insures siblings occur consecutively. This
    // is required by doLaunches() in "group.cc".
    struct ncclComm** pp = &ncclGroupCommHead[type];
    while (*pp != nullptr && comm->intraComm0 != (*pp)->intraComm0) pp = &(*pp)->groupNext[type];

    // didn't find its clique, we need to insert it with ascending order based on commHash
    if (*pp == nullptr) {
      pp = &ncclGroupCommHead[type];
      while (*pp != nullptr && (*pp)->commHash < comm->commHash) pp = &(*pp)->groupNext[type];
    }
    comm->groupNext[type] = *pp;
    *pp = comm;
    // Comms gets a new memory stack scope upon joining. Each task batched for
    // this comm is allocated there.
    if (type == ncclGroupTaskTypeCollective || type == ncclGroupTaskTypeRawTask) {
      // Initialize planner
      ncclMemoryStackPush(&comm->memScoped);
      ncclKernelPlanner::Peer* tmp = comm->planner.peers;
      ncclIntruQueue<ncclTaskRma, &ncclTaskRma::next>* tmpRmaQueues = comm->planner.rmaTaskQueues;
      int numRmaCtx = comm->config.numRmaCtx;
      memset(&comm->planner, 0, sizeof(comm->planner));
      comm->planner.peers = tmp;
      comm->planner.bcast_info.minBcastPeer = INT_MAX;
      comm->planner.bcast_info.maxBcastPeer = INT_MIN;
      comm->planner.rmaTaskQueues = tmpRmaQueues;
      if (comm->planner.rmaTaskQueues != NULL) {
        for (int i = 0; i < numRmaCtx; i++) {
          ncclIntruQueueConstruct(&comm->planner.rmaTaskQueues[i]);
        }
      }
    }
  }
  ncclGroupBlocking = comm->config.blocking;
}

这段代码有几个精妙之处：

1. 幂等性检查：if (comm->groupNext[type] == NCCL_COMM_GROUP_INVALID) 确保同一个通信域在同一个 group 内只被加入一次。如果用户对同一个 comm 调用了两次 ncclAllReduce，第二次不会重复加入链表，但任务会被追加到 comm->planner 里。

2. clique 排序：intraComm0 是「全局实体」的标识。多个通信域如果属于同一个全局实体（比如通过 ncclCommSplit 分裂出来的），它们的 intraComm0 相同，被称为一个 clique。代码先按 intraComm0 找到 clique，把 comm 插入到同 clique 的兄弟节点旁边。如果没找到 clique，就按 commHash 升序插入。这个排序是为了 doLaunches 能正确处理 clique 内的 barrier 同步。

3. 内存栈作用域：ncclMemoryStackPush(&comm->memScoped) 为这个 comm 在 group 内分配一个新的内存栈作用域。所有为这个 comm 分配的任务（ncclTaskColl 等）都从这个栈上分配。ncclGroupCommLeave 时会 ncclMemoryStackPop 一次性释放所有任务内存——这是「批量分配、批量释放」的经典优化，避免了每个任务单独 malloc/free 的开销。

4. planner 重置：memset(&comm->planner, 0, sizeof(comm->planner)) 清空 planner，但保留了 peers 和 rmaTaskQueues 指针（先存到临时变量，memset 后再恢复）。为什么要保留？因为这两个是预分配的数组，不需要每次重新分配。bcast_info 的 min/max 被重置为 INT_MAX/INT_MIN，用于后续 broadcast 任务的合并优化。

第三步：ncclGroupEnd 做了什么？

📎 src/group.cc:1039-1164

ncclGroupEndInternal 是核心。逐段解析：

📎 src/group.cc:1048-1061

if (ncclGroupDepth == 0) {
  WARN("ncclGroupEnd: not in a group call.");
  ret = ncclInvalidUsage;
  goto exit;
}
// ...
if ((--ncclGroupDepth) > 0) goto exit;

先检查深度，然后减一。如果减一后还大于 0，说明还在嵌套的内层 group 里，直接返回，不提交。只有减到 0 才继续。

📎 src/group.cc:1063

if ((ret = ncclGroupError) != ncclSuccess) goto fail;

如果 group 内任何一次调用出过错，直接跳到 fail 清理。

📎 src/group.cc:1084-1093

NEW_NOTHROW_GOTO(groupJob, ncclGroupJob, ret, fail);
ncclIntruQueueConstruct(&groupJob->asyncJobs);
groupJob->groupRefCount = 0;
groupJob->nonBlockingInit = false;
memcpy(groupJob->groupCommHead, ncclGroupCommHead, sizeof(ncclGroupCommHead));
groupJob->groupCommPreconnectHead = ncclGroupCommPreconnectHead;
groupJob->groupError = ncclSuccess;
groupJob->abortFlag = false;
groupJob->joined = false;
ncclIntruQueueTransfer(&groupJob->asyncJobs, &ncclAsyncJobs);

创建一个 ncclGroupJob，把 thread_local 的 group 状态「转移」到 job 对象里。ncclIntruQueueTransfer 把 ncclAsyncJobs 队列整体转移到 groupJob->asyncJobs。这一步很关键：thread_local 状态是「临时」的，job 对象是「持久」的，可以被异步线程持有。

📎 src/group.cc:1095-1147

if (hasCommHead || !ncclIntruQueueEmpty(&groupJob->asyncJobs) || ncclGroupCommPreconnectHead != nullptr) {
  /* make sure ncclGroupBlocking has been set. */
  if (ncclGroupBlocking != 0 && ncclGroupBlocking != 1) {
    WARN("Invalid group blocking state %d", ncclGroupBlocking);
    ret = ncclInternalError;
    goto fail;
  }
  if (ncclGroupBlocking == 0) {
    /* nonblocking group */
    // ... 设置 async error 为 ncclInProgress，创建线程执行 groupLaunchNonBlocking
    groupJob->base.func = groupLaunchNonBlocking;
    STDTHREADCREATE_GOTO(groupJob->base.thread, ncclAsyncJobMain, ret, fail, &groupJob->base);
    groupJob->nonBlockingInit = true;
    ret = ncclInProgress;
  } else {
    /* blocking group */
    int savedDev;
    CUDACHECKGOTO(cudaGetDevice(&savedDev), ret, fail);
    NCCLCHECKGOTO(groupLaunch(&groupJob->base, internalSimInfoPtr), ret, fail);
    CUDACHECKGOTO(cudaSetDevice(savedDev), ret, fail);
    if (simInfo) memcpy((void*)simInfo, (void*)internalSimInfoPtr, realSize);
    delete groupJob;
  }
} else {
  // Free when not needed (single rank case)
  delete groupJob;
}

阻塞模式：直接在当前线程调用 groupLaunch，同步完成。非阻塞模式：创建一个线程执行 groupLaunchNonBlocking，立即返回 ncclInProgress。用户后续通过 ncclCommGetAsyncError 查询进度。

注意 cudaGetDevice/cudaSetDevice 的保存和恢复：groupLaunch 内部会切换 CUDA 设备（因为不同 comm 可能在不同 GPU 上），执行完后恢复用户原来的设备。这是防止「NCCL 内部切换设备后没切回来」导致用户后续 CUDA 调用跑错设备。

设计思考与生产踩坑

坑 1：阻塞和非阻塞通信域混用。ncclAsyncLaunch 里有检查：

📎 src/group.cc:55-64

/* check if there are blocking and nonblocking comms at the same time in group. */
if (comm->destroyFlag) {
  ncclGroupBlocking = 1;
} else if (ncclGroupBlocking == -1) {
  /* first met communicator */
  ncclGroupBlocking = comm->config.blocking;
} else if (ncclGroupBlocking != comm->config.blocking) {
  WARN("Blocking and nonblocking communicators are not allowed in the same group.");
  ret = ncclInvalidArgument;
}

为什么不允许混用？因为阻塞 group 在当前线程同步执行，非阻塞 group 在独立线程异步执行。如果混用，无法确定 ncclGroupEnd 应该同步返回还是返回 ncclInProgress。生产环境中，如果用户不小心把阻塞和非阻塞 comm 放进同一个 group，会收到 ncclInvalidArgument，但此时 group 状态已经被污染，必须重新 ncclGroupStart。

坑 2：ncclGroupError 的传播。如果 group 内某次调用失败，ncclGroupError 被设置，ncclGroupEnd 会跳到 fail 分支执行 groupCleanup。groupCleanup 会遍历所有 comm，释放 planner 里的 plan 内存、重置 planner、清理 rawTaskQueue。如果这一步没做干净，下次 ncclGroupStart 时 planner 里残留旧数据，会导致任务重复提交或内存泄漏。

📎 src/group.cc:514-607

static void groupCleanup(struct ncclComm** groupCommHeadPtr,
                         struct ncclIntruQueue<struct ncclAsyncJob, &ncclAsyncJob::next>* asyncJobsPtr,
                         ncclResult_t error) {
  struct ncclComm* comm;
  for (int type = 0; type < ncclGroupTaskTypeNum; ++type) {
    comm = groupCommHeadPtr[type];
    groupCommHeadPtr[type] = nullptr;
    while (comm != nullptr) {
      struct ncclComm* next = comm->groupNext[type];
      (void)ncclGroupCommLeave(comm, type);
      // We don't know if preconnect succeeded or happened at all, so clear
      // the flags that let `taskAppend()` skip over checking if preconnect
      // is needed.
      if (type == ncclGroupTaskTypeCollective || type == ncclGroupTaskTypeRawTask) {
        comm->preconnectNext = reinterpret_cast<struct ncclComm*>(0x1);
        for (int i = 0; i < comm->nRanks; i++) {
          comm->connectSend[i] = 0UL;
          comm->connectRecv[i] = 0UL;
        }
        // Reclaim abandoned kernel plan memory.
        while (!ncclIntruQueueEmpty(&comm->planner.planQueue)) {
          struct ncclKernelPlan* plan = ncclIntruQueueDequeue(&comm->planner.planQueue);
          if (!plan->persistent) {
            while (!ncclIntruQueueEmpty(&plan->proxyOpQueue)) {
              struct ncclProxyOp* pxop = ncclIntruQueueDequeue(&plan->proxyOpQueue);
              ncclMemoryPoolFree(&comm->memPool_ncclProxyOp, pxop);
            }
            ncclMemoryPoolFree(&comm->memPool_ncclKernelPlan, plan);
          }
        }
        // Reset comm->planner to empty.
        // ...
      }
      // ...
    }
  }
  // ...
}

注意 comm->preconnectNext = reinterpret_cast<struct ncclComm*>(0x1) 这一行。这是一个「哨兵值」，表示「这个 comm 需要重新 preconnect」。为什么？因为 cleanup 时不知道 preconnect 是否成功，所以强制下次重新检查。0x1 这个值很巧妙——它不是一个合法的指针，但可以用来做「未初始化」标记。ncclGroupCommPreconnect 里检查 if (comm->preconnectNext == reinterpret_cast<struct ncclComm*>(0x1)) 来判断是否需要加入 preconnect 链表。

---

二、任务准备：ncclPrepareTasks 如何把任务描述变成可调度单元

直觉模型

ncclPrepareTasks 是「备菜」环节。购物车里的菜（任务描述）还是生的，需要先洗切配（确定算法、协议、channel 切分），才能下锅（启动 kernel）。如果跳过这一步直接启动 kernel，kernel 不知道数据怎么切、走哪条路，会直接崩溃。

场景驱动的 Step-by-Step Walkthrough

ncclPrepareTasks 在 groupLaunchLegacy 里被调用：

📎 src/group.cc:705-746

static ncclResult_t ncclPrepareTasksAndCollPreconnect(
  struct ncclComm* comm, ncclSimInfo_t* simInfo,
  struct ncclIntruQueue<struct ncclAsyncJob, &ncclAsyncJob::next>* asyncCollJobs) {
  if (ncclParamSingleProcMemRegEnable()) {
    // 单进程内存注册模式：把 prepare 和 preconnect 合并成一个异步 job
    struct ncclPrepareTasksAndCollPreconnectJob* job;
    NEW_NOTHROW(job, ncclPrepareTasksAndCollPreconnectJob);
    job->base.func = ncclPrepareTasksAndCollPreconnectFunc;
    // ...
    ncclIntruQueueEnqueue(asyncCollJobs, &job->base);
  } else {
    bool needConnect = false;
    bool algoNeedConnect[NCCL_NUM_ALGORITHMS];
    memset(algoNeedConnect, 0, sizeof(bool) * NCCL_NUM_ALGORITHMS);

    CUDACHECK(cudaSetDevice(comm->cudaDev));
    NCCLCHECK(ncclPrepareTasks(comm, algoNeedConnect, &needConnect, simInfo));

    if (comm->cuMemSupport && needConnect) {
      // 创建 preconnect job
      struct ncclPreconnectJob* job;
      NEW_NOTHROW(job, ncclPreconnectJob);
      job->base.func = ncclCollPreconnectFunc;
      // ...
      ncclIntruQueueEnqueue(asyncCollJobs, &job->base);
    }
  }
  return ncclSuccess;
}

ncclPrepareTasks 的输出是两个东西：algoNeedConnect 数组（哪些算法需要建立连接）和 needConnect 标志（是否需要连接）。如果 needConnect 为真且支持 cuMem，就创建一个 preconnect job 异步执行。

ncclPrepareTasks 内部做了什么？它遍历 comm->planner 里的任务，对每个任务确定算法和协议，然后调用 taskAppend 把任务追加到 planner 的 plan 里。这部分逻辑在上一章已经展开，这里不再重复。

关键点：ncclPrepareTasks 是按 comm 逐个调用的，但 preconnect 是按 clique 批量执行的。为什么？看 groupLaunchLegacy 里的注释：

📎 src/group.cc:818-834

do {
  // We need to preconnect connections for collectives clique by clique to avoid
  // race condition for split shared comms which can connect the same connections
  // at the same time.
  comm = cliqueHead;
  do {
    NCCLCHECKGOTO(ncclPrepareTasksAndCollPreconnect(comm, simInfo, &asyncCollJobs), ret, fail);
    comm = comm->groupNext[ncclGroupTaskTypeCollective];
  } while (comm != nullptr && comm->intraComm0 == cliqueHead->intraComm0);
  // connect
  NCCLCHECKGOTO(asyncJobLaunch(&asyncCollJobs, groupAbortFlag), ret, fail);
  // ...
  cliqueHead = comm;
} while (cliqueHead != nullptr);

注释说得很清楚：按 clique 逐个 preconnect，避免 split shared comms 同时连接同一组连接导致竞态。如果两个 comm 是从同一个父 comm split 出来的，它们可能共享一些连接。如果并行 preconnect，两个线程可能同时尝试建立同一个连接，导致重复连接或连接状态不一致。按 clique 串行执行，保证同一时刻只有一个 clique 在建立连接。

并发控制与底层交互

asyncJobLaunch 是异步任务启动的核心：

📎 src/group.cc:609-678

static ncclResult_t asyncJobLaunch(struct ncclIntruQueue<struct ncclAsyncJob, &ncclAsyncJob::next>* asyncJobsMain,
                                   volatile bool* groupAbortFlag) {
  ncclResult_t ret = ncclSuccess;
  bool jobsDone = false;
  bool errorJobAbortFlag = false;

  if (!ncclIntruQueueEmpty(asyncJobsMain)) {
    struct ncclAsyncJob* job = ncclIntruQueueHead(asyncJobsMain);
    if (job->next == nullptr) {
      // 只有一个 job，直接在当前线程执行，避免线程创建开销
      job->isThreadMain = true;
      ncclAsyncJobMain(job);
      job->state = ncclGroupJobJoined;
      return job->result;
    }
    // 多个 job，每个创建一个线程
    do {
      STDTHREADCREATE(job->thread, ncclAsyncJobMain, job);
      job = job->next;
    } while (job != nullptr);

    do {
      jobsDone = true;
      job = ncclIntruQueueHead(asyncJobsMain);
      do {
        ncclGroupJobState_t state = COMPILER_ATOMIC_LOAD(&job->state, std::memory_order_acquire);
        if (state == ncclGroupJobRunning) {
          jobsDone = false;
        } else if (state == ncclGroupJobDone) {
          int err;
          if ((err = ncclThreadJoin(job->thread)) != ncclSuccess) {
            WARN("asyncJobLaunch: failed to join thread for job");
            ret = ncclSystemError;
          }
          job->state = ncclGroupJobJoined;
          if (job->result != ncclSuccess && ret == ncclSuccess) {
            ret = job->result;
            errorJobAbortFlag = true;
          }
        } else {
          // safety check
          if (state != ncclGroupJobJoined) {
            WARN("Async job state is %d, expected %d", state, ncclGroupJobJoined);
            if (ret == ncclSuccess) ret = ncclInternalError;
            errorJobAbortFlag = true;
          }
        }

        if (!job->destroyFlag &&
            (COMPILER_ATOMIC_LOAD(groupAbortFlag, std::memory_order_acquire) || errorJobAbortFlag == true)) {
          COMPILER_ATOMIC_STORE(job->abortFlag, uint32_t(1), std::memory_order_release);
          COMPILER_ATOMIC_STORE(job->abortFlagDev, uint32_t(1), std::memory_order_release);
          if (job->childAbortFlag) {
            COMPILER_ATOMIC_STORE(job->childAbortFlag, uint32_t(1), std::memory_order_release);
            COMPILER_ATOMIC_STORE(job->childAbortFlagDev, uint32_t(1), std::memory_order_release);
          }
        }

        job = job->next;
      } while (job != nullptr);
      // Let preconnect threads progress.
      if (jobsDone == false) std::this_thread::sleep_for(std::chrono::microseconds(1));
    } while (jobsDone == false);

    if (ret != ncclSuccess) goto fail;
  }

exit:
  return ret;
fail:
  goto exit;
}

这段代码有几个关键设计：

1. 单 job 优化：如果队列里只有一个 job，不创建线程，直接在当前线程执行。这避免了线程创建和 join 的开销。对于单 comm 的 group，这是常见情况。

2. 原子状态机：job->state 是一个原子变量，有三个状态：ncclGroupJobRunning、ncclGroupJobDone、ncclGroupJobJoined。工作线程执行完后用 COMPILER_ATOMIC_STORE(..., std::memory_order_release) 设置为 Done；主线程用 COMPILER_ATOMIC_LOAD(..., std::memory_order_acquire) 读取。release/acquire 配对保证了工作线程的所有内存写入对主线程可见。

3. 忙等待 + 微睡眠：主线程轮询所有 job 的状态，如果还有 job 在跑，sleep_for(1us) 后继续轮询。为什么用 1 微秒而不是条件变量？因为 preconnect 是短任务（通常几十微秒到几毫秒），条件变量的唤醒开销可能比忙等待还大。1 微秒的睡眠避免了纯自旋导致的 CPU 浪费。

4. 错误传播与 abort：如果任何一个 job 失败，errorJobAbortFlag 被设置，后续所有 job 的 abortFlag 被原子设置为 1。工作线程在执行过程中会检查 abortFlag，如果发现被 abort，提前退出。这是「快速失败」机制，避免一个 job 失败后其他 job 还在傻跑。

Mermaid 图：group 提交的控制流

flowchart TD
    gs["ncclGroupStart()"] --> depth_inc["ncclGroupDepth++"]
    depth_inc --> api_calls["用户调用 ncclAllReduce 等"]
    api_calls --> join["ncclGroupCommJoin(comm, type)"]
    join --> check_dup{"comm->groupNext[type]<br/>== NCCL_COMM_GROUP_INVALID?"}
    check_dup -->|是| insert["插入 clique 链表<br/>ncclMemoryStackPush"]
    check_dup -->|否| skip["跳过（已加入）"]
    insert --> ge["ncclGroupEnd()"]
    skip --> ge
    ge --> depth_dec["--ncclGroupDepth"]
    depth_dec --> depth_zero{"depth == 0?"}
    depth_zero -->|否| ret_early["返回（嵌套内层）"]
    depth_zero -->|是| check_err{"ncclGroupError<br/>== ncclSuccess?"}
    check_err -->|否| fail_cleanup["groupCleanup()"]
    check_err -->|是| create_job["创建 ncclGroupJob<br/>转移 thread_local 状态"]
    create_job --> blocking{"ncclGroupBlocking?"}
    blocking -->|0 非阻塞| spawn_thread["STDTHREADCREATE<br/>groupLaunchNonBlocking"]
    blocking -->|1 阻塞| sync_launch["groupLaunch() 同步执行"]
    spawn_thread --> ret_progress["返回 ncclInProgress"]
    sync_launch --> ret_ok["返回 ncclSuccess"]
    fail_cleanup --> reset["groupLocalResetJobState()"]
    ret_progress --> reset
    ret_ok --> reset

---

三、doLaunches：多 channel 多 kernel 的轮次调度

直觉模型

doLaunches 是「传菜调度员」。厨房（GPU）有多个灶台（channel），每道菜（kernel plan）需要按顺序上。但不同 comm 的菜可能可以并行上，同一个 comm 的菜必须按顺序上。调度员要保证：同一个 clique 内的 comm 同步推进（用 barrier），不同 clique 之间可以独立推进。

数据结构与内存布局

doLaunches 的核心数据结构是 ncclKernelPlan 和 comm->planner.unlaunchedPlansHead。

📎 src/group.cc:427-503

ncclResult_t doLaunches(struct ncclComm* head, int taskType) {
  ncclResult_t result = ncclSuccess;
  struct ncclComm* cliqueHead = head;
  struct ncclComm* cliqueNextHead;
  bool useBarrier = ncclParamLaunchMode == ncclLaunchModeGroup;
  // This outer loop iterates over cliques of comms which are siblings of the
  // same global entity. We calculate a clique as all comms which have the same
  // `intraComm0` value.
  do {
    struct ncclComm* comm = cliqueHead;
    bool capturingYes = false, capturingNo = false;
    do {
      (ncclCudaGraphValid(comm->planner.capturingGraph) ? capturingYes : capturingNo) = true;
      CUDACHECKGOTO(cudaSetDevice(comm->cudaDev), result, failure);
      NCCLCHECKGOTO(ncclLaunchPrepare(comm), result, failure);
      if (useBarrier) ncclCommIntraBarrierIn(comm, 1);
      comm = comm->groupNext[taskType];
    } while (comm != nullptr && comm != reinterpret_cast<struct ncclComm*>(NCCL_COMM_GROUP_INVALID) &&
             comm->intraComm0 == cliqueHead->intraComm0);
    cliqueNextHead = comm;

    if (capturingYes && capturingNo) {
      // We have entered barriers but are aborting without leaving them. Thus
      // these comms are permanently trashed. We need a good mechanism for
      // tracking and reporting that.
      WARN("Either none or all communicators in a ncclGroup() can be CUDA graph captured.");
      result = ncclInvalidUsage;
      goto failure;
    }

    while (true) {
      // Iterate rounds of launches for clique.
      bool moreRounds = false;
      comm = cliqueHead;
      do {
        // Iterate clique members.
        struct ncclComm* next = comm->groupNext[taskType];
        if (useBarrier) {
          // Barrier reduction result tells us if this was the final round.
          moreRounds = 0 != ncclCommIntraBarrierOut(comm);
        } else {
          moreRounds |= comm->planner.unlaunchedPlansHead != nullptr;
        }
        if (moreRounds) {
          // Pop next unlaunched kernel
          struct ncclKernelPlan* plan = comm->planner.unlaunchedPlansHead;
          if (plan != nullptr) {
            comm->planner.unlaunchedPlansHead = plan->next;
            CUDACHECKGOTO(cudaSetDevice(comm->cudaDev), result, failure);
            NCCLCHECKGOTO(ncclLaunchKernelBefore_NoUncapturedCuda(comm, plan), result, failure);
            if (plan->isCeColl) {
              NCCLCHECKGOTO(ncclLaunchCeColl(comm, plan), result, failure);
            } else if (plan->isRma) {
              NCCLCHECKGOTO(ncclLaunchRma(comm, plan), result, failure);
            } else {
              NCCLCHECKGOTO(ncclLaunchKernel(comm, plan), result, failure);
            }
          }
          // Barrier reduction input indicates if we require further rounds.
          if (useBarrier) ncclCommIntraBarrierIn(comm, comm->planner.unlaunchedPlansHead != nullptr ? 1 : 0);
          if (plan != nullptr) {
            NCCLCHECKGOTO(ncclLaunchKernelAfter_NoCuda(comm, plan), result, failure);
          }
        } else {
          // Final round.
          CUDACHECKGOTO(cudaSetDevice(comm->cudaDev), result, failure);
          NCCLCHECKGOTO(ncclLaunchFinish(comm), result, failure);
        }
        comm = next;
      } while (comm != reinterpret_cast<struct ncclComm*>(NCCL_COMM_GROUP_INVALID) && comm != cliqueNextHead);
      if (!moreRounds) break;
    }
    cliqueHead = cliqueNextHead;
  } while (cliqueHead != nullptr && cliqueHead != reinterpret_cast<struct ncclComm*>(NCCL_COMM_GROUP_INVALID));
failure:
  return result;
}

场景驱动的 Step-by-Step Walkthrough

场景：两个 comm（commA 和 commB）属于同一个 clique（intraComm0 相同），每个 comm 有 3 个 kernel plan 待启动。

第一层循环：遍历 clique

外层 do-while 遍历所有 clique。cliqueHead 是当前 clique 的第一个 comm。内层 do-while 遍历 clique 内的所有 comm（comm->intraComm0 == cliqueHead->intraComm0）。

对每个 comm：

• cudaSetDevice(comm->cudaDev)：切换到该 comm 对应的 GPU。
• ncclLaunchPrepare(comm)：准备启动，包括设置 CUDA 流、检查资源等。
• ncclCommIntraBarrierIn(comm, 1)：进入 barrier，初始值为 1。

第二层循环：轮次调度

while (true) 循环执行「轮次」。每一轮，clique 内每个 comm 启动一个 kernel plan。

关键在 moreRounds 的计算：

• 有 barrier 模式（useBarrier == true）：moreRounds = 0 != ncclCommIntraBarrierOut(comm)。ncclCommIntraBarrierOut 是一个跨 comm 的 barrier 归约操作。它等待 clique 内所有 comm 都调用了 ncclCommIntraBarrierIn，然后返回所有输入值的归约结果（这里是逻辑或）。如果任何一个 comm 还有未启动的 plan，归约结果为 1，moreRounds 为 true，继续下一轮。如果所有 comm 都没有未启动的 plan，归约结果为 0，moreRounds 为 false，进入 final round。
• 无 barrier 模式：moreRounds |= comm->planner.unlaunchedPlansHead != nullptr。直接检查每个 comm 是否还有未启动的 plan。注意这里用的是 |=，只要有一个 comm 还有 plan，moreRounds 就为 true。

为什么需要 barrier？因为 clique 内的 comm 是「兄弟」，它们可能共享 GPU 资源或网络连接。如果一个 comm 启动了 3 个 kernel，另一个只启动了 1 个，先启动完的 comm 会进入 ncclLaunchFinish，释放资源，而另一个 comm 还在用这些资源，导致 use-after-free。barrier 保证 clique 内所有 comm 同步推进：要么都启动第 N 轮，要么都进入 final round。

kernel 启动分支

📎 src/group.cc:477-483

if (plan->isCeColl) {
  NCCLCHECKGOTO(ncclLaunchCeColl(comm, plan), result, failure);
} else if (plan->isRma) {
  NCCLCHECKGOTO(ncclLaunchRma(comm, plan), result, failure);
} else {
  NCCLCHECKGOTO(ncclLaunchKernel(comm, plan), result, failure);
}

三种 plan 类型：

• isCeColl：CollNet 集合通信（用网卡卸载做集合通信）。
• isRma：RMA（Remote Memory Access）任务。
• 默认：普通 GPU kernel。

每种类型的启动函数不同，但都遵循「Before -> Launch -> After」的模式：

• ncclLaunchKernelBefore_NoUncapturedCuda：启动前准备（设置 kernel 参数、上传到设备等）。
• ncclLaunchKernel：实际启动 kernel（cudaLaunchKernel）。
• ncclLaunchKernelAfter_NoCuda：启动后清理（更新状态、释放临时资源）。

Final round

当 moreRounds 为 false 时，执行 ncclLaunchFinish(comm)。这一步做最终的清理：释放 plan 内存、更新 comm 状态、通知 proxy 线程等。

并发控制与硬件交互

ncclCommIntraBarrierIn/Out 是 clique 内 comm 的同步原语。它的实现涉及原子操作和自旋等待。In 把值写入共享内存，Out 等待所有 comm 都写入后读取归约结果。这个 barrier 是跨进程的（如果 comm 在不同进程），底层可能用共享内存或网络。

为什么用 barrier 而不是简单的「检查所有 comm 是否还有 plan」？因为「检查」是非原子的：commA 检查时 commB 还有 plan，commA 决定继续；但 commB 在 commA 检查后立即启动完最后一个 plan，进入 final round。commA 还在启动 kernel，commB 已经释放了共享资源。barrier 把「检查」和「决定」变成一个原子操作，消除了这个竞态。

生产避坑指南

坑 1：CUDA graph capture 混用。

📎 src/group.cc:448-455

if (capturingYes && capturingNo) {
  // We have entered barriers but are aborting without leaving them. Thus
  // these comms are permanently trashed. We need a good mechanism for
  // tracking and reporting that.
  WARN("Either none or all communicators in a ncclGroup() can be CUDA graph captured.");
  result = ncclInvalidUsage;
  goto failure;
}

如果 clique 内一部分 comm 在 CUDA graph capture 模式下，另一部分不在，直接报错。注释说「these comms are permanently trashed」——因为已经进入了 barrier 但没有退出，这些 comm 的 barrier 状态永远不一致，后续无法再使用。这是一个不可恢复错误，用户必须重建通信域。生产环境中，如果用户混用 graph capture 和非 capture 的 comm，会收到 ncclInvalidUsage，但更严重的是 comm 已经损坏。

坑 2：useBarrier 的配置依赖。useBarrier = ncclParamLaunchMode == ncclLaunchModeGroup。如果用户设置了 NCCL_LAUNCH_MODE=GROUP，走 barrier 路径；否则走非 barrier 路径。非 barrier 路径下，moreRounds 用 |= 累积，但每个 comm 独立判断。如果 commA 还有 plan 而 commB 没有，commB 会进入 final round 执行 ncclLaunchFinish，而 commA 还在启动 kernel。这在某些场景下是安全的（comm 之间没有共享资源），但如果共享了 proxy 线程或网络连接，可能导致问题。所以默认推荐用 barrier 模式。

---

四、groupLaunchLegacy 的完整执行链

场景驱动的 Step-by-Step Walkthrough

groupLaunchLegacy 是阻塞模式下的完整提交流程。按顺序执行：

阶段 1：P2P preconnect

📎 src/group.cc:756-774

if (!simInfo && groupCommPreconnectHeadMain != nullptr) {
  struct ncclComm* comm = groupCommPreconnectHeadMain;
  do {
    struct ncclPreconnectJob* job;
    NEW_NOTHROW_GOTO(job, ncclPreconnectJob, ret, fail);
    job->base.func = ncclP2PPreconnectFunc;
    // ...
    ncclIntruQueueEnqueue(asyncJobsMain, (struct ncclAsyncJob*)job);
    struct ncclComm* next = comm->preconnectNext;
    comm->preconnectNext = reinterpret_cast<struct ncclComm*>(0x1);
    comm = next;
  } while (comm != nullptr);
}
NCCLCHECKGOTO(asyncJobLaunch(asyncJobsMain, groupAbortFlag), ret, fail);

对每个需要 preconnect 的 comm 创建一个 ncclP2PPreconnectFunc job，然后批量启动。ncclP2PPreconnectFunc 内部调用 ncclTransportP2pSetup 建立 P2P 连接。

阶段 2：对称内存注册

📎 src/group.cc:778-808

// only loop through sym alloc and register tasks
for (int type = ncclGroupTaskTypeSymRegister; type <= ncclGroupTaskTypeSymRegister; ++type) {
  if (groupCommHeadMain[type]) {
    // 按 clique 批量执行 ncclCommGroupRegisterSymmetric
  }
}

对称内存注册（ncclCommWindowRegister 等）按 clique 批量执行。

阶段 3：集合通信 preconnect

📎 src/group.cc:810-870

if (groupCommHeadMain[ncclGroupTaskTypeCollective] != nullptr) {
  // 按 clique 逐个 prepare + preconnect
  // 然后 ncclTasksRegAndEnqueue
  // 然后 debug check
}

这是核心阶段。按 clique 逐个调用 ncclPrepareTasksAndCollPreconnect，然后 asyncJobLaunch 执行 preconnect。preconnect 完成后，调用 ncclTasksRegAndEnqueue 把任务注册到 plan 并生成 kernel 启动参数。

阶段 4：doLaunches

📎 src/group.cc:872-874

if ((!simInfo) && (groupCommHeadMain[ncclGroupTaskTypeCollective] != nullptr)) {
  NCCLCHECKGOTO(doLaunches(groupCommHeadMain[ncclGroupTaskTypeCollective], ncclGroupTaskTypeCollective), ret, fail);
}

启动所有 kernel plan。

阶段 5：清理

📎 src/group.cc:876-903

while (!ncclIntruQueueEmpty(asyncJobsMain)) {
  struct ncclAsyncJob* job = ncclIntruQueueDequeue(asyncJobsMain);
  if (!job->destroyFlag && job->comm && !job->comm->config.blocking &&
      groupCommHeadMain[ncclGroupTaskTypeCollective] == nullptr) {
    (void)ncclCommSetAsyncError(job->comm, ret);
  }
  if (job->destructor) job->destructor((void*)job);
}

for (int type = 0; type < ncclGroupTaskTypeNum; ++type) {
  while (groupCommHeadMain[type] != nullptr) {
    struct ncclComm* comm = groupCommHeadMain[type];
    struct ncclComm* next = comm->groupNext[type];
    // Poll for callbacks sent to us from other threads.
    if (comm->reclaimSteps == GROUP_MAX_RECLAIM_STEPS) {
      NCCLCHECKGOTO(ncclCommPollCallbacks(comm, /*waitSome=*/false), ret, fail);
      comm->reclaimSteps = 0;
    } else {
      comm->reclaimSteps++;
    }
    (void)ncclGroupCommLeave(comm, type);
    if (!comm->config.blocking) {
      (void)ncclCommSetAsyncError(comm, ret);
    }
    groupCommHeadMain[type] = next;
  }
}

清理异步 job，然后遍历所有 comm 调用 ncclGroupCommLeave。注意 reclaimSteps 的计数：每 GROUP_MAX_RECLAIM_STEPS（10）次 group 调用，轮询一次 callbacks。这是为了避免每次 group 都轮询 callbacks 的开销，同时保证 callbacks 不会无限堆积。

Mermaid 图：groupLaunchLegacy 的数据流

flowchart LR
    subgraph input["输入"]
        preconnect["ncclGroupCommPreconnectHead"]
        coll["ncclGroupCommHead[Collective]"]
        sym["ncclGroupCommHead[SymRegister]"]
    end

    subgraph phase1["阶段1: P2P preconnect"]
        p2p_job["ncclPreconnectJob<br/>func=ncclP2PPreconnectFunc"]
        p2p_launch["asyncJobLaunch"]
    end

    subgraph phase2["阶段2: 对称内存注册"]
        sym_job["ncclGroupSymmetricJob<br/>func=ncclCommGroupRegisterSymmetric"]
    end

    subgraph phase3["阶段3: 集合通信 prepare+preconnect"]
        prep["ncclPrepareTasksAndCollPreconnect"]
        coll_job["ncclPreconnectJob<br/>func=ncclCollPreconnectFunc"]
        reg_enq["ncclTasksRegAndEnqueue"]
    end

    subgraph phase4["阶段4: kernel 启动"]
        do_launch["doLaunches<br/>轮次调度"]
        plan["ncclKernelPlan"]
        kernel["ncclLaunchKernel"]
    end

    preconnect --> p2p_job --> p2p_launch
    sym --> sym_job
    coll --> prep --> coll_job --> reg_enq
    reg_enq --> plan --> do_launch --> kernel

---

五、groupLaunchEnqueueRearch：新架构的调度器

直觉模型

groupLaunchEnqueueRearch 是 NCCL 正在开发的新调度架构。它把任务准备、调度、启动分成更细的阶段，用异步 job 队列管理。目前调度器和启动器模块「尚未实现」，回退到 legacy 的 doLaunches。

📎 src/group.cc:991-996

// Schedule and launch tasks. Scheduler and launcher module of the enqueue framework
// is not yet implemented and falls back to the legacy launcher: a single phased
// doLaunches over the clique, run here on the user's thread.
if (!simInfo && groupCommHeadMain[ncclGroupTaskTypeRawTask] != nullptr) {
  NCCLCHECKGOTO(doLaunches(groupCommHeadMain[ncclGroupTaskTypeRawTask], ncclGroupTaskTypeRawTask), ret, fail);
}

新架构的执行流程：

1. 管理任务：ncclMgmtTaskJobFunc 处理 mgmtTaskQueue 里的任务（如 destroy）。

2. 任务准备：ncclTaskPrepareJobFunc 调用 ncclTaskPrepare。

3. 调度和启动：回退到 doLaunches。

新架构用 ncclGroupJobLaunch 替代 asyncJobLaunch，增加了更严格的状态检查：

📎 src/group.cc:113-116

} else {
  /* safety check */
  assert(state == ncclGroupJobJoined);
}

legacy 版本用 WARN 而不是 assert，新架构用 assert。这说明新架构对状态机的正确性要求更高。

设计思考

新架构的动机是解耦：legacy 的 groupLaunchLegacy 把所有阶段揉在一个函数里，难以维护和扩展。新架构把每个阶段拆成独立的 job 类型，通过队列串联。但目前调度器和启动器还没实现，所以只是「框架先行」。

ncclParamEnqueueRearchEnable() 控制走新架构还是 legacy：

📎 src/group.cc:1031-1033

static ncclResult_t groupLaunch(struct ncclAsyncJob* job_, ncclSimInfo_t* simInfo = NULL) {
  return ncclParamEnqueueRearchEnable() ? groupLaunchEnqueueRearch(job_, simInfo) : groupLaunchLegacy(job_, simInfo);
}

用户可以通过环境变量 NCCL_ENQUEUE_REARCH_ENABLE 切换。生产环境建议保持默认（legacy），因为新架构还在开发中。

---

六、非阻塞 group 与异步错误处理

场景驱动的 Step-by-Step Walkthrough

非阻塞 group 的核心是 ncclGroupJobComplete 和 ncclGroupJobAbort：

📎 src/group.cc:1166-1190

ncclResult_t ncclGroupJobComplete(struct ncclGroupJob* groupJob) {
  ncclResult_t ret = ncclSuccess;
  if (groupJob && groupJob->nonBlockingInit) {
    if (!COMPILER_ATOMIC_EXCHANGE(&groupJob->joined, true, std::memory_order_acq_rel)) {
      ret = ncclAsyncJobComplete(&groupJob->base);
    }
    if (ncclAtomicRefCountDecrement(&groupJob->groupRefCount) == 0) {
      delete groupJob;
    }
  }
  return ret;
}

ncclResult_t ncclGroupJobAbort(struct ncclGroupJob* groupJob) {
  if (groupJob && groupJob->nonBlockingInit) {
    if (!COMPILER_ATOMIC_EXCHANGE(&groupJob->joined, true, std::memory_order_acq_rel)) {
      COMPILER_ATOMIC_STORE(&groupJob->abortFlag, true, std::memory_order_relaxed);
      ncclAsyncJobComplete(&groupJob->base);
    }
    if (ncclAtomicRefCountDecrement(&groupJob->groupRefCount) == 0) {
      delete groupJob;
    }
  }
  return ncclSuccess;
}

关键设计：

1. joined 原子标志：用 COMPILER_ATOMIC_EXCHANGE 保证只有一个线程能执行 join 逻辑。如果两个线程同时调用 ncclGroupJobComplete，只有一个会真正 join，另一个直接跳过。这防止了 double-join。

2. 引用计数：groupRefCount 记录有多少个 comm 关联到这个 group job。每个 comm 在 ncclGroupEndInternal 里增加引用计数：

📎 src/group.cc:1108-1111

if (job->comm->groupJob == NULL) {
  job->comm->groupJob = groupJob;
  groupJob->groupRefCount++;
}

只有当所有 comm 都调用了 ncclGroupJobComplete 或 ncclGroupJobAbort，引用计数减到 0，才删除 group job。这保证了 group job 的生命周期覆盖所有关联的 comm。

3. abort 语义：ncclGroupJobAbort 先设置 abortFlag，然后 join。工作线程在执行过程中检查 abortFlag，如果发现被 abort，提前退出。这是「协作式取消」——不是强制杀死线程，而是让线程自己检查标志后退出。

生产避坑指南

坑 3：非阻塞 group 的错误查询。非阻塞 group 返回 ncclInProgress，用户需要通过 ncclCommGetAsyncError 查询进度。如果用户忘记查询，直接调用下一次通信，可能遇到 ncclInProgress 错误。更严重的是，如果 group job 还在运行，用户调用了 ncclCommDestroy，会导致 use-after-free。NCCL 通过 comm->groupJob 指针和引用计数来防止这种情况：ncclCommDestroy 会先检查 comm->groupJob，如果有未完成的 group job，会等待或报错。

坑 4：ncclGroupJobComplete 的返回值。如果 group job 执行失败，ncclAsyncJobComplete 返回错误码。但 ncclGroupJobComplete 只在第一次调用时返回这个错误码，后续调用返回 ncclSuccess（因为 joined 已经是 true）。用户必须在第一次调用时检查返回值，否则会丢失错误信息。

---

本章小结

这一章我们拆解了 NCCL 从「任务描述」到「kernel 启动」的完整调度链：

1. Group 语义：ncclGroupStart/ncclGroupEnd 通过 thread_local 变量攒任务，ncclGroupEnd 时统一提交。阻塞模式同步执行，非阻塞模式创建线程异步执行。

2. 任务准备：ncclPrepareTasks 确定算法/协议，ncclPrepareTasksAndCollPreconnect 按 clique 逐个 preconnect，避免 split comms 的竞态。

3. 轮次调度：doLaunches 按 clique 分组，用 barrier 同步 clique 内 comm，每轮启动一个 kernel plan，直到所有 plan 启动完毕。

4. 异步任务：asyncJobLaunch 用原子状态机和忙等待管理异步 job，支持快速失败和 abort。

5. 新架构：groupLaunchEnqueueRearch 是正在开发的新调度框架，目前回退到 legacy 的 doLaunches。

下一章将进入 kernel 启动的最后一公里：ncclLaunchKernel 如何把 ncclKernelPlan 变成 GPU 上真正执行的 kernel，以及设备侧如何读取 DevComm 元数据。

本章思考与自测

<details><summary>Q1: 如果把 ncclGroupCommJoin 中的 ncclMemoryStackPush(&comm->memScoped) 去掉，会发生什么？在什么场景下会导致内存泄漏或数据损坏？</summary>

参考解析：ncclMemoryStackPush 为 comm 在 group

至此，任务描述已经变成了可执行的启动计划：group 语义把多次 API 调用合并成一次提交，channel 切分把任务分配到多个执行流，doLaunches 的轮次调度则保证了 kernel 之间的顺序与依赖。但计划终究只是计划，host 侧的任务描述如何变成 GPU 上的一个 grid？下一章我们将深入 ncclLaunchKernel，看参数准备、kernel 变体选择与 cudaLaunchKernel 调用，完成从 host 到 device 的最后一跃。

第 8 章：Kernel 启动与设备端执行：从 host 侧调用到 GPU 线程块起跑

上一章我们拆解了任务如何被切分到多个 channel、如何生成 kernel 启动参数，以及 group 语义下批量提交与依赖排序的机制。现在，启动计划已经就绪，但它还只是 host 侧的数据结构。本章要回答的核心问题是：ncclKernelPlan 如何变成 GPU 上一个真正在跑的 grid？我们将沿着 ncclLaunchKernel 的调用链，看参数如何被塞进 kernel args、kernel 变体如何被选中、cuLaunchKernelEx 如何被调用，以及设备侧 ncclKernelMain 如何从共享内存里把工作描述读出来并分发到具体实现。

从 Plan 到 Grid：启动路径的全景

在深入细节之前，先建立一个整体心智模型。把 ncclKernelPlan 想象成一张"施工图纸"：它记录了这次要启动几个 channel（几个 block）、每个 block 多少线程、要执行哪些 work、用哪个 kernel 函数。而 ncclLaunchKernel 就是"施工队进场"的动作——它把图纸上的信息翻译成 CUDA 驱动能理解的 CUlaunchConfig，然后调用 cuLaunchKernelEx 把 grid 真正发射到 GPU 上。

如果没有这一层，host 侧的所有调度（上一章的 channel 切分、batch 组织、proxy op 排序）都只是纸上谈兵，GPU 上不会有任何 kernel 运行，通信永远不会发生。这是端到端主干的最后一环，也是 host 与 device 的分界线。

整个启动路径可以概括为三个阶段：

1. 参数准备（finishPlan + uploadWork）：把 work 结构体、batch 描述符、kernel args 组织到一块连续内存里，决定是放在 kernel 参数里、FIFO 里还是持久化缓冲区里。

2. kernel 发射（ncclLaunchKernel）：计算 grid/block 维度，组装 launch attributes（CGA cluster、mem sync domain、launch completion event），调用 cuLaunchKernelEx。

3. 设备侧入口（ncclKernelMain）：每个 block 根据 blockIdx.x 确定自己的 channelId，从 args 或 FIFO 里加载 work batch 到共享内存，然后通过 ncclDevFuncTable 分发到具体的算法/协议实现。

下面这张图展示了从 plan 到 grid 的完整控制流，包含关键的分支判断：

flowchart TD
    plan["ncclKernelPlan<br/>channelMask / workBytes / kernelFn"]
    finish["finishPlan()<br/>决定 workStorageType"]
    check_budget{"sizeof(args)+batchBytes<br/>+workBytes <= workArgsBytes?"}
    args_type["workStorageType = Args<br/>work 直接放 kernel 参数"]
    fifo_type["workStorageType = Fifo/Persistent<br/>work 放外部缓冲区"]
    upload["uploadWork()<br/>拷贝 work 到目标缓冲区"]
    launch["ncclLaunchKernel()<br/>组装 CUlaunchConfig"]
    check_cluster{"compCap >= 90<br/>且 clusterSize > 0?"}
    add_cluster["添加 CLUSTER_DIMENSION<br/>+ SPREAD 调度策略"]
    no_cluster["不添加 cluster 属性"]
    check_event{"userKernelEvent<br/>且 driver >= 12030?"}
    add_event["添加 LAUNCH_COMPLETION_EVENT"]
    no_event["无 completion event"]
    cu_launch["cuLaunchKernelEx()<br/>发射 grid 到 GPU"]

    plan --> finish --> check_budget
    check_budget -->|是| args_type
    check_budget -->|否| fifo_type
    args_type --> upload
    fifo_type --> upload
    upload --> launch --> check_cluster
    check_cluster -->|是| add_cluster
    check_cluster -->|否| no_cluster
    add_cluster --> check_event
    no_cluster --> check_event
    check_event -->|是| add_event
    check_event -->|否| no_event
    add_event --> cu_launch
    no_event --> cu_launch

这张图锚定了本章的三个核心函数：finishPlan、uploadWork、ncclLaunchKernel。接下来我们逐个拆解。

参数准备：work 结构体如何找到自己的位置

直觉模型

finishPlan 的角色类似于快递分拣中心的"装箱员"。它面对一堆零散的 work 结构体（每个 collective 或 p2p 操作对应一个），需要决定：这些 work 是塞进 kernel 参数这个"随身背包"里，还是放进 FIFO 这个"传送带"上，还是放进持久化缓冲区这个"仓库"里？

如果这个决策做错了——比如 work 太大塞不进 kernel 参数却硬塞——kernel 启动会直接失败。如果 work 放错了位置，设备侧读到的就是垃圾数据，通信结果完全错误。

数据结构与内存布局

先看 ncclDevKernelArgs 的结构，它是 host 和 device 之间的"信封"：

📎 src/include/device.h:514-522

struct alignas(16) ncclDevKernelArgs {
  struct ncclKernelComm* comm;      // 指向设备侧通信器元数据
  uint64_t channelMask;             // 哪些 channel 有工作
  enum ncclDevWorkStorageType workStorageType;  // work 存在哪里
  uint32_t workMask;                // FIFO 环形缓冲区的掩码
  void* workBuf;                    // work 缓冲区指针
  // struct ncclDevWorkBatch batches[];  // 紧随其后的是 batch 数组
};

这个结构体只有 5 个字段，但每个字段都承载着关键信息。channelMask 是一个 64 位掩码，每一位对应一个 channel，设备侧通过 __popcll 计算 blockIdx.x 对应的 channelId。workStorageType 决定了设备侧从哪里读 work：Args 表示 work 就在 kernel 参数里，Fifo 表示在环形缓冲区里，Persistent 表示在持久化缓冲区里。

ncclDevWorkBatch 是 batch 描述符，它告诉设备侧"这个 channel 的 work 在哪里、有多少个"：

📎 src/include/device.h:400-421

struct alignas(16) ncclDevWorkBatch {
  union {
    struct {
      uint32_t nextJump:14, nextExtends:1;
      uint32_t workType:2, funcId : NCCL_DEV_WORK_BATCH_FUNC_ID_BITS, func : NCCL_DEV_WORK_BATCH_FUNC_BITS;
    };
    uint32_t flags;
  };
  uint32_t offsetBase;    // work 在 FIFO 中的起始偏移
  uint64_t offsetBitset;  // 哪些 work 属于这个 channel
};

offsetBitset 是一个 64 位掩码，每一位对应一个 work 结构体。设备侧通过 __popc 和 fns（find n-th set）指令来定位每个 work 的偏移。nextJump 和 nextExtends 用于把多个 batch 串联起来——当 work 太多装不下一个 batch 时，会创建"扩展 batch"。

Step-by-Step Walkthrough

现在代入一个具体场景：一次 AllReduce 被切分到 4 个 channel，每个 channel 有 2 个 work 结构体，总共 8 个 work。

第一步：finishPlan 决定存储类型。

📎 src/enqueue/enqueue.cc:245-255

if (sizeof(ncclDevKernelArgs) + batchBytes + workBytes <= comm->workArgsBytes) {
  plan->workStorageType = ncclDevWorkStorageTypeArgs;
}
plan->kernelArgsSize = sizeof(struct ncclDevKernelArgs) + batchBytes;
plan->kernelArgsSize += (plan->workStorageType == ncclDevWorkStorageTypeArgs) ? workBytes : 0;
plan->kernelArgsSize = alignUp(plan->kernelArgsSize, 16);
plan->kernelArgs =
  (struct ncclDevKernelArgs*)ncclMemoryStackAlloc(&comm->memScoped, plan->kernelArgsSize, /*align=*/16);
plan->kernelArgs->comm = comm->devComm;
plan->kernelArgs->channelMask = plan->channelMask;
plan->kernelArgs->workStorageType = plan->workStorageType;

这里的关键判断是：如果 sizeof(ncclDevKernelArgs) + batchBytes + workBytes 能装进 comm->workArgsBytes（通常是 4KB），就把 work 直接放进 kernel 参数里。否则，work 会被放到 FIFO 或持久化缓冲区，kernel 参数里只放 batch 描述符。

第二步：把 batch 按 channel 轮流放入 kernel args。

📎 src/enqueue/enqueue.cc:257-280

uint64_t hasBatchMask = plan->channelMask;
struct ncclDevWorkBatch* batchPrev[MAXCHANNELS] = {};
struct ncclDevWorkBatch* batchZero = (struct ncclDevWorkBatch*)(plan->kernelArgs + 1);
int batchIx = 0;
while (hasBatchMask != 0) {
  uint64_t tmpMask = hasBatchMask;
  do {
    int c = popFirstOneBit(&tmpMask);
    if (!ncclIntruQueueEmpty(&wipChannels[c].workBatchQueue)) {
      struct ncclWorkBatchList* batchNode = ncclIntruQueueDequeue(&wipChannels[c].workBatchQueue);
      if (batchPrev[c] != nullptr) {
        batchPrev[c]->nextJump = int(&batchZero[batchIx] - batchPrev[c]);
      }
      batchPrev[c] = &batchZero[batchIx];
      batchZero[batchIx++] = batchNode->batch;
    }
    if (ncclIntruQueueEmpty(&wipChannels[c].workBatchQueue)) {
      hasBatchMask ^= 1ull << c;
    }
  } while (tmpMask != 0);
}

这段代码的逻辑是"轮询"：每一轮从每个还有 batch 的 channel 里取一个 batch，按 channel 编号升序放入 batchZero 数组。这样做的目的是保证"每个 channel 的第一个 batch 位于 batchZero[blockIdx.x]"——设备侧每个 block 通过 blockIdx.x 直接索引到自己的第一个 batch，不需要搜索。

nextJump 字段记录了同一个 channel 的下一个 batch 相对于当前 batch 的偏移。设备侧通过 batchIx += batch.nextJump 就能跳到下一个 batch，形成一个链表。

第三步：uploadWork 把 work 拷贝到目标缓冲区。

📎 src/enqueue/enqueue.cc:1365-1430

static ncclResult_t uploadWork(struct ncclComm* comm, struct ncclKernelPlan* plan) {
  if (plan->isSymColl || plan->isCeColl || plan->isRma) return ncclSuccess;
  size_t workBytes = plan->workBytes;
  size_t batchBytes = plan->nWorkBatches * sizeof(struct ncclDevWorkBatch);
  void* fifoBufHost;
  uint32_t fifoCursor, fifoMask;
  switch (plan->workStorageType) {
  case ncclDevWorkStorageTypeArgs:
    plan->kernelArgs->workBuf = nullptr;
    fifoBufHost = (void*)plan->kernelArgs;
    fifoCursor = sizeof(ncclDevKernelArgs) + batchBytes;
    fifoMask = ~0u;
    break;
  case ncclDevWorkStorageTypeFifo:
    fifoBufHost = comm->workFifoBuf;
    fifoCursor = comm->workFifoProduced;
    fifoMask = comm->workFifoBytes - 1;
    NCCLCHECK(waitWorkFifoAvailable(comm, fifoCursor + workBytes));
    plan->kernelArgs->workBuf = comm->workFifoBufDev;
    break;
  // ...
  }
  plan->kernelArgs->workMask = fifoMask;
  // 修正 batch 的 offsetBase
  struct ncclDevWorkBatch* batchZero = (struct ncclDevWorkBatch*)(plan->kernelArgs + 1);
  for (int b = 0; b < plan->nWorkBatches; b++) {
    batchZero[b].offsetBase += fifoCursor;
  }
  // 拷贝 work 结构体
  struct ncclWorkList* workNode = ncclIntruQueueHead(&plan->workQueue);
  while (workNode != nullptr) {
    char* dst = (char*)fifoBufHost;
    char* src = (char*)(workNode + 1);
    for (int n = workNode->size; n != 0; n -= 16) {
      memcpy(COMPILER_ASSUME_ALIGNED(dst + (fifoCursor & fifoMask), 16), COMPILER_ASSUME_ALIGNED(src, 16), 16);
      fifoCursor += 16;
      src += 16;
    }
    workNode = workNode->next;
  }
  // ...
}

这里有几个关键点：

1. fifoCursor 的语义：对于 Args 类型，它是相对于 kernelArgs 起始地址的偏移；对于 Fifo 类型，它是相对于 FIFO 基地址的偏移；对于 Persistent 类型，它从 0 开始。

2. offsetBase 的修正：finishPlan 里 batch 的 offsetBase 是相对于 plan 的 work 起始位置的（从 0 开始）。uploadWork 需要把它转换成相对于实际存储位置的偏移。对于 Args 类型，加上 sizeof(ncclDevKernelArgs) + batchBytes；对于 Fifo 类型，加上 comm->workFifoProduced。

3. 16 字节对齐拷贝：work 结构体都是 16 字节对齐的（alignas(16)），所以拷贝时按 16 字节为单位。COMPILER_ASSUME_ALIGNED 告诉编译器这个地址是 16 字节对齐的，让编译器生成更高效的向量化指令。

4. FIFO 等待：对于 Fifo 类型，waitWorkFifoAvailable 会自旋等待 FIFO 有足够空间。这个等待会检查 comm->abortFlag，避免在 abort 时死锁。

设计思考与生产踩坑

• Args：最快（常量内存），但容量有限（4KB）。适合小消息、少量 work。
• Fifo：容量大（环形缓冲区），但设备侧读取要走全局内存。适合中等消息。
• Persistent：用于 CUDA Graph 捕获场景。因为 graph 捕获时不能做 cudaMemcpy，所以需要预先分配持久化缓冲区，把 work 拷贝进去，然后让 kernel 从那里读。

踩坑点 1：FIFO 溢出导致死锁。 如果 waitWorkFifoAvailable 没有检查 abortFlag，当 FIFO 满且消费者（GPU kernel）因为某种原因停止消费时，host 会永远自旋。源码里 📎 src/enqueue/enqueue.cc:1333-1349 明确检查了 abort flag：

if (COMPILER_ATOMIC_LOAD(comm->abortFlag, std::memory_order_acquire)) {
  return ncclInternalError;
}

踩坑点 2：offsetBitset 溢出。 offsetBitset 是 64 位的，最多支持 64 个 work 在一个 batch 里。如果超过 64 个，1ull << (offset / workSize) 会溢出。源码里通过 NCCL_MAX_DEV_WORK_BATCH_BYTES 限制了 batch 的大小（1024 字节），而最小的 work 结构体是 ncclDevWorkColl（约 80 字节），所以最多 12 个 work，不会溢出。

踩坑点 3：Persistent 模式下的内存泄漏。 在 uploadWork 的 Persistent 分支里，fifoBufHost 是通过 ncclOsAlignedAlloc 分配的，需要在 uploadWork_cleanup_fn 里释放。如果 cudaMemcpyAsync 失败，fail 标签会检查 cleanup 是否为 null，如果为 null 就直接释放 fifoBufHost。这个错误恢复链在 📎 src/enqueue/enqueue.cc:1483-1485 可以看到。

Kernel 发射：从 CUlaunchConfig 到 cuLaunchKernelEx

直觉模型

ncclLaunchKernel 的角色类似于"火箭发射控制台"。它接收一个已经装好燃料（work 数据）的 plan，计算出火箭的飞行参数（grid/block 维度），设置好各种发射选项（cluster、mem sync domain、completion event），然后按下发射按钮（cuLaunchKernelEx）。

如果这个环节出错——比如 grid 维度算错了——GPU 上会启动错误数量的 block，导致部分 channel 的工作永远不会被执行，通信挂起。

数据结构与内存布局

CUlaunchConfig 是 CUDA 驱动 API 的启动配置结构体，NCCL 在栈上构造它：

📎 src/enqueue/enqueue.cc:1916-1917

CUlaunchConfig launchConfig = {0};
CUlaunchAttribute launchAttrs[6] = {};
int attrs = 0;

launchAttrs 是一个最多 6 个元素的数组，每个元素是一个 CUlaunchAttribute。NCCL 根据硬件能力和驱动版本，有条件地添加不同的属性：

• CU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION：CGA cluster 维度（sm90+）
• CU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE：cluster 调度策略
• CU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN：内存同步域（CUDA 12.0+）
• CU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT：启动完成事件（CUDA 12.3+）
• CU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_STREAM_SERIALIZATION：程序化流序列化（sym kernel）
• CU_LAUNCH_ATTRIBUTE_NVLINK_UTIL_CENTRIC_SCHEDULING：NVLink 利用率中心调度（CUDA 13.0+）

Step-by-Step Walkthrough

第一步：计算 grid 和 block 维度。

📎 src/enqueue/enqueue.cc:1889-1893

int nChannels = countOneBits(plan->channelMask);
void* sym = plan->kernelFn;
dim3 grid = {(unsigned)nChannels, 1, 1};
dim3 block = {(unsigned)plan->threadPerBlock, 1, 1};
int smem = plan->isSymColl ? plan->kernelDynSmem : ncclShmemDynamicSize(comm->cudaArch);

nChannels 是 channelMask 中置位的个数，也就是这个 plan 要启动多少个 block。每个 block 负责一个 channel。threadPerBlock 是在 scheduleCollTasksToPlan 里通过 plan->threadPerBlock = std::max(plan->threadPerBlock, task->nWarps * WARP_SIZE) 计算出来的，取所有 task 中最大的 nWarps * 32。

smem 是动态共享内存大小。对于普通 kernel，它是 ncclShmemDynamicSize(comm->cudaArch)，这是一个编译期常量，取决于架构（sm70+ 是 ncclShmemScratchWarpSize * (NCCL_MAX_NTHREADS / WARP_SIZE)）。对于 sym kernel，它是 plan->kernelDynSmem，因为 sym kernel 的共享内存需求可能不同。

第二步：组装 kernel 参数。

📎 src/enqueue/enqueue.cc:1902-1903

void* extra[] = {CU_LAUNCH_PARAM_BUFFER_POINTER, plan->kernelArgs, CU_LAUNCH_PARAM_BUFFER_SIZE, &plan->kernelArgsSize,
                 CU_LAUNCH_PARAM_END};

这是 CUDA 驱动 API 的一种参数传递方式：CU_LAUNCH_PARAM_BUFFER_POINTER 告诉驱动"参数不是一个个传的，而是一个连续的内存块"，CU_LAUNCH_PARAM_BUFFER_SIZE 告诉驱动这个块的大小。这样做的好处是 NCCL 可以把 ncclDevKernelArgs 和后面的 batch 数组一次性传进去，不需要逐个参数打包。

第三步：添加 launch attributes。

📎 src/enqueue/enqueue.cc:1929-1936

if (clusterSize) {
  if (grid.x % clusterSize) clusterSize = 1;
  launchAttrs[attrs].id = CU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION;
  launchAttrs[attrs++].value.clusterDim = {clusterSize, 1, 1};
  launchAttrs[attrs].id = CU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE;
  launchAttrs[attrs++].value.clusterSchedulingPolicyPreference = CU_CLUSTER_SCHEDULING_POLICY_SPREAD;
}

CGA（Cooperative Group Array）是 sm90 引入的硬件特性，允许把多个 block 组成一个 cluster，cluster 内的 block 可以保证同时调度到一组 SM 上，并且可以互相访问共享内存。NCCL 用这个特性来实现 NVLS 等需要跨 block 同步的算法。

注意 if (grid.x % clusterSize) clusterSize = 1; 这个保护：cluster 维度必须能整除 grid 维度，否则驱动会报错。如果 grid.x 不能被 clusterSize 整除，就退化为不使用 cluster。

第四步：添加 launch completion event。

📎 src/enqueue/enqueue.cc:1944-1964

#if CUDART_VERSION >= 12030
enum ncclImplicitOrder implicitOrder;
NCCLCHECKGOTO(getImplicitOrder(&implicitOrder, comm, plan->persistent, driverVersion), ret, do_return);
if (implicitOrder == ncclImplicitOrderLaunch) {
  launchAttrs[attrs].id = CU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT;
  launchAttrs[attrs].value.launchCompletionEvent.event = comm->sharedRes->launchEvent;
  launchAttrs[attrs].value.launchCompletionEvent.flags = 0;
  attrs++;
  if (userKernelEvent) {
    NCCLCHECKGOTO(ncclUncapturedStreamPoolAcquire(&comm->sharedRes->uncapturedStreamPool, &relayStream), ret, do_return);
    relayUserLaunchCompletionEvent = true;
    userKernelEventArmed = true;
  }
} else if (userKernelEvent && driverVersion >= 12030) {
  launchAttrs[attrs].id = CU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT;
  launchAttrs[attrs].value.launchCompletionEvent.event = plan->launchCompletionEvent;
  launchAttrs[attrs].value.launchCompletionEvent.flags = 0;
  attrs++;
  userKernelEventArmed = true;
}
#endif

CU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT 是 CUDA 12.3 引入的特性：驱动会在 kernel 真正开始执行时（而不是在 host 侧调用返回时）记录一个事件。这对于实现"隐式顺序"（implicit order）至关重要——NCCL 需要保证多个 kernel 按顺序执行，但又不希望 host 侧阻塞等待。

getImplicitOrder 的逻辑是：如果用户设置了 launchOrderImplicit，并且驱动版本足够新，就使用 ncclImplicitOrderLaunch（用 launch event 排序）；否则使用 ncclImplicitOrderSerial（用 completion event 排序，即串行执行）。

第五步：调用 cuLaunchKernelEx。

📎 src/enqueue/enqueue.cc:1978-1996

launchConfig.gridDimX = grid.x;
launchConfig.gridDimY = grid.y;
launchConfig.gridDimZ = grid.z;
launchConfig.blockDimX = block.x;
launchConfig.blockDimY = block.y;
launchConfig.blockDimZ = block.z;
launchConfig.sharedMemBytes = smem;
launchConfig.attrs = launchAttrs;
launchConfig.numAttrs = attrs;
launchConfig.hStream = launchStream;
if (userKernelEvent && !userKernelEventArmed) {
  WARN("CUDA launch-completion events require CUDA 12.3 or newer; recording the user event before launch");
  CUDACHECKGOTO(cudaEventRecord(plan->launchCompletionEvent, launchStream), ret, do_return);
}
CUCHECKGOTO(cuLaunchKernelEx(&launchConfig, fn, nullptr, extra), ret, do_return);
if (relayUserLaunchCompletionEvent) {
  CUDACHECKGOTO(cudaStreamWaitEvent(relayStream, comm->sharedRes->launchEvent, 0), ret, do_return);
  CUDACHECKGOTO(cudaEventRecord(plan->launchCompletionEvent, relayStream), ret, do_return);
}

cuLaunchKernelEx 是 CUDA 12.0 引入的新 API，支持 launch attributes。对于老驱动（< 11.8），NCCL 会退回到 cuLaunchKernel：

📎 src/enqueue/enqueue.cc:1998-2007

} else {
  // Standard kernel launch
  if (userKernelEvent) {
    WARN("CUDA launch-completion events require CUDA 12.3 or newer; recording the user event before launch");
    CUDACHECKGOTO(cudaEventRecord(plan->launchCompletionEvent, launchStream), ret, do_return);
  }
  CUCHECKGOTO(cuLaunchKernel(fn, grid.x, grid.y, grid.z, block.x, block.y, block.z, smem, launchStream, nullptr,
                             extra),
              ret, do_return);
}

并发控制与硬件交互

Launch completion event 的 relay 机制。 当使用 ncclImplicitOrderLaunch 且用户提供了 launchCompletionEvent 时，NCCL 不能直接把用户的 event 传给驱动，因为驱动只支持一个 launch completion event。NCCL 的做法是：

1. 把 comm->sharedRes->launchEvent 传给驱动。

2. 在 relayStream 上等待 launchEvent。

3. 在 relayStream 上记录用户的 event。

这样用户的 event 会在 kernel 真正开始执行后触发，而不是在 host 侧调用返回时触发。

Mem Sync Domain。 📎 src/enqueue/enqueue.cc:1938-1942 在 sm90+ 上，NCCL 设置 CU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN 为 cudaLaunchMemSyncDomainRemote。这是 Hopper 架构引入的内存同步域机制，用于隔离不同 kernel 的内存屏障，减少不必要的同步开销。

生产踩坑指南

踩坑点 1：cluster 维度不整除导致启动失败。 如果 grid.x 不能被 clusterSize 整除，驱动会返回 CUDA_ERROR_INVALID_VALUE。源码里通过 if (grid.x % clusterSize) clusterSize = 1; 做了保护，但这也意味着 cluster 特性被静默禁用了。如果用户期望 cluster 带来的性能提升，需要检查 cgaClusterSize 和 nChannels 的关系。

踩坑点 2：驱动版本不满足导致 kernel 不可用。 ncclInitKernelsForDevice 会在初始化时检查每个 kernel 的驱动要求：

📎 src/enqueue/enqueue.cc:71-76

for (int k = 0; k < kcount; k++) {
  if (kptrs[k] != nullptr && driverVersion < krequires[k]) {
    INFO(NCCL_INIT, "Skipping %skernel %d which requires driver %d", sym ? "symmetric " : "", k, krequires[k]);
    kptrs[k] = nullptr;
    if (kptrsProfile != nullptr) kptrsProfile[k] = nullptr;
  }

如果驱动版本不够，kernel 指针会被置为 null。后续如果调度器选中了这个 kernel，cuLaunchKernelEx 会失败。NCCL 的 tuner 应该会避免选择不可用的 kernel，但如果用户强制指定了算法（NCCL_ALGO），可能会触发这个问题。

踩坑点 3：launchCompletionEvent 在旧驱动上的行为。 如果驱动版本 < 12.3，NCCL 会在 kernel 启动前记录 event，这意味着 event 会在 kernel 开始执行前就触发，而不是在 kernel 真正开始执行时。这可能导致用户代码的时序假设失效。

设备侧入口：从 blockIdx 到具体实现

直觉模型

ncclKernelMain 是 GPU 上每个 block 的"入口大厅"。当一个 block 被调度到 SM 上开始执行时，它首先进入这个大厅，完成三件事：确定自己的身份（我是哪个 channel）、领取自己的任务（加载 work batch）、然后去对应的窗口办事（调用具体的算法实现）。

如果没有这个入口，每个 kernel 变体都需要自己处理"我是谁、我要干什么"的问题，代码会大量重复。ncclKernelMain 通过模板参数 SpecializedFnId 和 SpecializedRunWorkBatch 实现了"通用入口 + 特化执行"的模式。

数据结构与内存布局

设备侧的共享内存布局是理解 ncclKernelMain 的关键。ncclShmemData 是所有 block 共享的"工作台"：

📎 src/device/common.h:48-72

struct ncclShmemData {
  struct ncclDevKernelArgs args;
  int channelId;
  int aborted;
  alignas(16) struct ncclKernelComm comm;
  alignas(16) struct ncclDevChannel channel;

  int batchIx, nextBatchIx;
  enum ncclDevWorkType workType;
  uint8_t directMode;
  uint16_t funcId;
  int nWorks;
  int workSize;
  uint64_t workCounter;
  bool profilerEnabled;
  uint8_t func;
  struct ncclShmemGroup groups[NCCL_MAX_GROUPS];

  alignas(16) char workStorage[ncclMaxDevWorkBatchBytes()];

  alignas(16) union {
    unpackShmem unpack;
  } devicePlugin;
};

这个结构体的布局经过精心设计：

• args 放在最前面，因为它是从 kernel 参数拷贝过来的，需要 16 字节对齐。
• comm 和 channel 也是 16 字节对齐的，因为它们是通过 copyToShmem16 用向量化指令拷贝的。
• workStorage 是 work 结构体的临时存放区，大小是 ncclMaxDevWorkBatchBytes()（sm90+ 是 16KB）。
• groups 数组用于存储每个 group 的连接信息，NCCL_MAX_GROUPS 是 16。

Step-by-Step Walkthrough

第一步：拷贝 kernel args 到共享内存。

📎 src/device/common.h:426-428

if (tid < sizeof(ncclDevKernelArgs) / sizeof(uint32_t)) {
  ((uint32_t*)&ncclShmem.args)[tid] = ((uint32_t*)args)[tid];
}

这里用前 sizeof(ncclDevKernelArgs) / 4 个线程，每个线程拷贝一个 32 位字。为什么要拷贝到共享内存？因为 kernel 参数在常量内存里，访问速度虽然快，但每个线程都要访问时会有广播开销。拷贝到共享内存后，所有线程访问的是同一块共享内存，效率更高。

第二步：确定 channelId。

📎 src/device/common.h:430-437

if (tid < MAXCHANNELS && (args->channelMask & (1ull << tid))) {
  int n = __popcll(args->channelMask & ((1ull << tid) - 1));
  if (blockIdx.x == n) ncclShmem.channelId = tid;
}
__syncthreads();

这段代码的逻辑是：对于每个置位的 channel（args->channelMask & (1ull << tid)），计算它前面有多少个置位的 channel（__popcll），如果这个数量等于 blockIdx.x，那么当前 block 就负责这个 channel。

举个例子：channelMask = 0b1011（channel 0、1、3 有工作）。blockIdx.x = 0 的 block 负责 channel 0（前面有 0 个置位），blockIdx.x = 1 的 block 负责 channel 1（前面有 1 个置位），blockIdx.x = 2 的 block 负责 channel 3（前面有 2 个置位）。

第三步：加载 comm 和 channel 到共享内存。

📎 src/device/common.h:446-478

switch (tid / WARP_SIZE) {
case 0:
  {
    void* dst = &ncclShmem.comm;
    void* src = ncclShmem.args.comm;
    int bytes = sizeof(ncclKernelComm);
    static_assert(sizeof(ncclKernelComm) <= 16 * WARP_SIZE,
                  "ncclKernelComm cannot be loaded by a single warp in one insn.");
    copyToShmem16(tid, dst, src, bytes);
  }
  break;
case 1:
  {
    void* dst = &ncclShmem.channel;
    void* src = &((ncclKernelCommAndChannels*)ncclShmem.args.comm)->channels[ncclShmem.channelId];
    int bytes = sizeof(ncclDevChannel);
    static_assert(sizeof(ncclDevChannel) <= 16 * WARP_SIZE,
                  "ncclDevChannel cannot be loaded by a single warp in one insn.");
    copyToShmem16(tid - WARP_SIZE, dst, src, bytes);
  }
  break;
default:
  {
    int subtid = tid - 2 * WARP_SIZE;
    int subtn = tn - 2 * WARP_SIZE;
    loadWorkBatchToShmem(subtid, subtn, args, /*batchIx=*/blockIdx.x);
  }
  break;
}
__syncthreads();

这里把线程分成三组：

• 第 0 个 warp：加载 ncclKernelComm（通信器元数据）到共享内存。
• 第 1 个 warp：加载当前 channel 的 ncclDevChannel（channel 元数据）到共享内存。
• 其余 warp：加载 work batch 到共享内存。

copyToShmem16 是一个用内联 PTX 实现的 16 字节拷贝函数：

📎 src/device/common.h:131-139

inline __device__ void copyToShmem16(int tid, void* dst, void const* src, int bytes) {
  int offset = 16 * tid;
  if (offset < bytes) {
    uint64_t a = 0, b = 0;
    asm volatile("ld.v2.u64 {%0,%1},[%2];" : "=l"(a), "=l"(b) : "l"((char const*)src + offset) : "memory");
    uint32_t udst = (uint32_t)__cvta_generic_to_shared(dst);
    asm volatile("st.shared.v2.u64 [%0],{%1,%2};" ::"r"(udst + offset), "l"(a), "l"(b) : "memory");
  }
}

它用 ld.v2.u64 从全局内存加载 16 字节，用 st.shared.v2.u64 存储到共享内存。__cvta_generic_to_shared 把通用地址转换成共享内存地址（共享内存地址空间是 32 位的）。

第四步：加载 work batch。

loadWorkBatchToShmem 是最复杂的部分。它的任务是把 batch 描述符指向的 work 结构体从全局内存（或 kernel 参数）拷贝到共享内存的 workStorage 里。

📎 src/device/common.h:142-260

__device__ __forceinline__ void loadWorkBatchToShmem(int tid, int tn, struct ncclDevKernelArgs const* args,
                                                     int batchIx) {
  int lane = tid % WARP_SIZE;
  int workCursor = 0;
  while (true) {
    struct ncclDevWorkBatch batch = ((struct ncclDevWorkBatch*)(args + 1))[batchIx];

    uint8_t* fnsOfBitset = (uint8_t*)ncclScratchForWarp(threadIdx.x / WARP_SIZE);
    __syncwarp();
    if (uint32_t(batch.offsetBitset) & (1u << lane)) {
      int nWorksBelow = __popc(uint32_t(batch.offsetBitset) & ((1u << lane) - 1));
      fnsOfBitset[nWorksBelow] = lane;
    }
    int nWorksLow32 = __popc(uint32_t(batch.offsetBitset));
    if (uint32_t(batch.offsetBitset >> 32) & (1u << lane)) {
      int nWorksBelow = nWorksLow32;
      nWorksBelow += __popc(uint32_t(batch.offsetBitset >> 32) & ((1u << lane) - 1));
      fnsOfBitset[nWorksBelow] = 32 + lane;
    }
    int nWorks = nWorksLow32 + __popc(uint32_t(batch.offsetBitset >> 32));
    __syncwarp();
    // ...
  }
}

这段代码的核心是计算 fnsOfBitset：对于 offsetBitset 中第 n 个置位，它的位索引是多少。PTX 有 fns 指令可以做这个，但它展开成很多 SASS 指令。NCCL 的做法是用共享内存：每个 lane 检查自己的位是否置位，如果是，计算它前面有多少个置位，然后把自己的 lane 编号写到 fnsOfBitset[nWorksBelow]。

接下来是实际的拷贝：

📎 src/device/common.h:209-241

if (tid < nPacks) {
  int srcWork = fnsOfBitset[dstWork];
  ulonglong2 tmp;
  if (ncclShmem.args.workStorageType == ncclDevWorkStorageTypeArgs) {
    char* src = (char*)args + (batch.offsetBase + srcWork * workSize + packInWork * 16);
    tmp = *(ulonglong2*)src; // becomes ld.param.v2.u64
  } else {
    char* src = (char*)ncclShmem.args.workBuf +
                ((batch.offsetBase + srcWork * workSize + packInWork * 16) & ncclShmem.args.workMask);
    tmp = *(ulonglong2*)src; // becomes ld.v2.u64
  }
  char* dst = ncclShmem.workStorage;
  dst += (workCursor + dstWork) * workSize + packInWork * 16;
  *(ulonglong2*)dst = tmp;
}

这里有一个关键的优化：对于 Args 类型，源码直接写 (char*)args + offset，编译器会识别出这是从 kernel 参数读取，生成 ld.param.v2.u64 指令。对于 Fifo 类型，源码写 (char*)ncclShmem.args.workBuf + (offset & workMask)，编译器生成 ld.v2.u64 指令。

注释里特别强调了不能把这两种情况合并：

📎 src/device/common.h:212-229

// The loads done in these two cases must be kept separate since we are
// relying on the compiler to use "ld.param" in the first one. The parameter
// space is not generically addressable, so any attempt to load through
// a pointer that *might* be parameter space backed will cause the
// compiler to spill the parameter struct (4K!) to each thread's local space
// before creating a pointer (to the spill) and decimate perf.

如果编译器不能确定指针指向的是参数空间还是全局空间，它会把整个参数结构体（4KB）溢出到每个线程的本地内存，性能会急剧下降。

第五步：执行 work。

📎 src/device/common.h:481-497

while (ncclShmem.aborted == 0) {
  profiler(START);
  if (0 <= SpecializedFnId && ncclShmem.funcId == (unsigned)SpecializedFnId) {
    SpecializedRunWorkBatch().run();
  } else {
    ncclDevFuncTable[ncclShmem.funcId]();
  }

  if (ncclShmem.nextBatchIx == -1) break;
  int batchIx = ncclShmem.nextBatchIx;
  __syncthreads();
  profiler(STOP);
  if (ncclShmem.comm.progressCounters != nullptr) __syncthreads();
  loadWorkBatchToShmem(tid, tn, args, batchIx);
  __syncthreads();
}

这里有一个重要的优化：如果 SpecializedFnId 匹配当前 batch 的 funcId，直接调用 SpecializedRunWorkBatch().run()，这是一个编译期特化的函数，没有函数指针调用的开销。否则，通过 ncclDevFuncTable[ncclShmem.funcId]() 间接调用。

ncclDevFuncTable 是一个设备侧的函数指针数组，由 generate.py 生成：

📎 src/device/generate.py:261-270

out("__device__ ncclDevFuncPtr_t const ncclDevFuncTable[] = {\n")
index = 0
for fn in primary_funcs:
  sym = paste("_", "ncclDevFunc", *fn)
  cudart, arch = required_cuda(*fn)
  if (cudart, arch) != (0, 0):
    out("#if CUDART_VERSION >= %d && __CUDA_ARCH__ >= %d\n" % (cudart ,arch))
  out("/*%4d*/ %s,\n" % (index, sym))
  if (cudart, arch) != (0, 0):
    out("#else\n" "/*%4d*/ nullptr,\n" "#endif\n" % index)
  index += 1
out("nullptr};\n")

设计思考与生产踩坑

为什么用 __grid_constant__？ 📎 src/device/common.h:19-24

#if __CUDA_ARCH__ >= 700
// __grid_constant__ appears to break cuda-gdb
#define NCCL_GRID_CONSTANT __grid_constant__
#else
#define NCCL_GRID_CONSTANT
#endif

__grid_constant__ 告诉编译器这个参数是只读的，可以放在常量内存里。这样设备侧读取时走 ld.param 指令，比从全局内存读取快。注释里提到它会破坏 cuda-gdb，所以只在 sm70+ 上启用。

踩坑点 1：workStorage 溢出。 workStorage 的大小是 ncclMaxDevWorkBatchBytes()，sm90+ 是 16KB。如果 nWorks * workSize 超过这个值，会写越界。源码里通过 NCCL_MAX_DEV_WORK_BATCH_BYTES 在 host 侧限制了 batch 的大小，但设备侧没有额外的检查。如果 host 侧的约束被绕过（比如通过修改环境变量），会导致共享内存越界。

踩坑点 2：__syncthreads() 的缺失导致数据竞争。 在 loadWorkBatchToShmem 之后，必须有一个 __syncthreads() 才能让所有线程看到完整的 workStorage。源码里在 📎 src/device/common.h:479 有 __syncthreads(); // publish ncclShmem。如果这个同步被去掉，某些线程可能会在 workStorage 还没写完时就开始读取，导致读到垃圾数据。

踩坑点 3：abort 检查的时机。 while (ncclShmem.aborted == 0) 只在每个 batch 开始时检查 abort。如果某个 batch 执行时间很长，abort 信号可能要等很久才能生效。这是设计上的权衡：更频繁的检查会增加开销，但响应更快。

Kernel 变体选择：generate.py 如何生成 kernel 列表

直觉模型

generate.py 的角色类似于"汽车工厂的生产线规划师"。它面对一个巨大的组合空间（7 种集合操作 × 5 种归约操作 × 12 种数据类型 × 7 种算法 × 3 种协议），需要决定：哪些组合需要生成专门的 kernel？哪些可以共用一个通用 kernel？

如果每个组合都生成一个 kernel，编译时间和二进制大小会爆炸。如果只生成一个通用 kernel，运行时会因为函数指针调用和分支判断而变慢。generate.py 的解决方案是"代表性 kernel"：为每个等价类生成一个 kernel，运行时通过函数指针表分发。

数据结构与内存布局

generate.py 生成三个关键文件：

1. device_table.cu：设备侧的 ncclDevFuncTable，把 funcId 映射到具体的设备函数。

2. host_table.cc：host 侧的 ncclDevKernelList、ncclDevKernelForFunc、ncclDevFuncRowToId 等表。

3. 各个 <coll>_<op>_<ty>.cu：具体的 kernel 实现。

Step-by-Step Walkthrough

第一步：枚举所有函数行。

📎 src/device/generate.py:186-199

def enumerate_func_rows():
  yield ("SendRecv", None, None, None, None)
  for coll in ("AllGather", "Broadcast", "AllGatherV"):
    algos = algos_of_coll[coll]
    for algo in algos:
      for proto in all_protos:
        yield (coll, None, None, algo, proto)
  for coll in ("AllReduce", "Reduce", "ReduceScatter"):
    algos = algos_of_coll[coll]
    for redop in all_redops:
      for ty in all_tys:
        for algo in algos:
          for proto in all_protos:
            yield (coll, redop, ty, algo, proto)

这个枚举顺序必须和 ncclDevFuncId() 的计算公式匹配：

📎 src/include/device.h:646-706

inline int ncclDevFuncId(int coll, int devRedOp, int type, int algo, int proto) {
  constexpr int NumTypes = ncclNumTypes;
  int row;
  do {
    row = 0; // ncclDevFuncIndex_P2p
    if (coll == ncclFuncSendRecv) break;
    row += 1;
    // ...
  } while (false);
  return ncclDevFuncRowToId[row];
}

ncclDevFuncId 计算出的是"行号"，然后通过 ncclDevFuncRowToId 映射到"主函数 ID"。这个映射的原因是：很多行可能映射到同一个主函数（比如所有 AllReduce Sum i32 的行都映射到 AllReduce Sum u32 的主函数）。

第二步：计算主函数和 kernel 函数。

📎 src/device/generate.py:211-225

func_rows = [validate(*fn) for fn in enumerate_func_rows()]
primary_funcs = sorted(set(equivalent_primary(*fn) for fn in func_rows if fn is not None))
primary_to_index = {fn: i for (i,fn) in zip(range(len(primary_funcs)), primary_funcs)}
kernel_funcs = sorted(set(best_kernel(*fn) for fn in primary_funcs))

equivalent_primary 把有符号整数映射到无符号整数（因为加法/乘法对两者是一样的）：

📎 src/device/generate.py:158-166

def equivalent_primary(coll, redop, ty, algo, proto):
  if coll in ("AllReduce", "Reduce", "ReduceScatter"):
    if redop in ("Sum","Prod","PreMulSum","SumPostDiv") and ty[0]=="i":
      return (coll, redop, "u"+ty[1:], algo, proto)
    if redop=="MinMax" and ty[0]=="i" and ("NVLS" not in algo):
      return (coll, redop, "u"+ty[1:], algo, proto)
  return (coll, redop, ty, algo, proto)

best_kernel 把多个主函数映射到同一个 kernel（比如所有 AllGather 的算法都映射到 AllGather RING LL）：

📎 src/device/generate.py:171-183

def best_kernel(coll, redop, ty, algo, proto):
  def best(coll, redop, ty, algo, proto):
    if coll=="Nop": return ("Generic", None, None, None, None)
    if coll=="SendRecv": return ("SendRecv", None, None, None, None)
    if exact_kernel_names: return (coll, redop, ty, algo, proto)
    if coll in ("AllGather","Broadcast","AllGatherV"): return (coll, None, None, "RING", "LL")
    return (coll, "Sum", ty, ("TREE" if algo=="TREE" else "RING"), "LL")
  kfn = equivalent_primary(*best(coll, redop, ty, algo, proto))
  if not func_filter(*kfn): return ("Generic", None, None, None, None)
  return kfn

第三步：生成 kernel 定义。

📎 src/device/generate.py:458-480

(_, kfns) = name_to_kernels.get(name) or (None, [])
for kfn in kfns:
  (coll, redop, ty, algo, proto) = kfn
  sym = kernel_suffix(kfn)
  fn_id = primary_to_index[kfn]
  cudart, arch = required_cuda(*kfn)
  s = "DEFINE_ncclDevKernel({sym}, ncclFunc{coll}, {redop_cxx}, {ty_cxx}, NCCL_ALGO_{algo}, NCCL_PROTO_{proto}, {fn_id})\n"
  # ...
  out(s.format(...))

DEFINE_ncclDevKernel 宏展开后是：

📎 src/device/common.h:507-509

#define DEFINE_ncclDevKernel(suffix, coll, redop, ty, algo, proto, specializedFnId) \
  __global__ void ncclDevKernel_##suffix(ncclDevKernelArgs4K NCCL_GRID_CONSTANT const args4K) { \
    ncclKernelMain<specializedFnId, RunWorkBatch<coll, ty, redop<ty>, algo, proto>>(&args4K.args); \
  }

所以每个 kernel 都是一个 __global__ 函数，调用 ncclKernelMain，模板参数是 specializedFnId 和 RunWorkBatch<coll, ty, redop<ty>, algo, proto>。

设计思考与生产踩坑

踩坑点 1：NCCL_EXACT_KERNEL_NAMES 导致编译爆炸。 如果设置了这个环境变量，best_kernel 会返回原始函数，每个组合都会生成一个 kernel。这在开发时有用（可以精确控制哪个 kernel 被编译），但在生产环境会导致编译时间过长。

踩坑点 2：required_cuda 的版本检查。 某些 kernel 需要特定的 CUDA 版本或架构：

📎 src/device/generate.py:130-154

至此，kernel 已经在 GPU 上启动，设备侧也拿到了工作描述。但真正决定性能的，是设备内部如何搬运数据。下一章将深入 src/device 下的三种协议原语：LL、LL128 和 Simple，看看同一份 AllReduce 逻辑为什么需要三套搬运原语，以及它们在同步方式、缓冲区布局和 flag 语义上的差异。

第 9 章：设备端通信原语：LL、LL128、Simple 三种协议的数据搬运实现

上一章我们追踪了 host 侧如何将一次 AllReduce 翻译成 __global__ kernel，并看到设备侧入口 ncclKernelMain 根据算法与协议完成分发。但分发只是选定了工具，真正决定性能的是这些工具如何执行数据搬运。本章深入 src/device 下的三套搬运原语：LL、LL128 和 Simple，逐一剖析它们的数据搬运实现，理解不同协议在延迟与带宽之间的取舍。

为什么同一份 AllReduce 需要三套搬运原语

先建立一个直觉模型。想象一条流水线工厂：原料（用户数据）从一端进，成品从另一端出，中间有若干工位（rank）要互相交换半成品。搬运半成品的方式有三种：

• LL（Low Latency）：像两个人面对面递纸条，递过去的同时对方就知道「这是给你的」，几乎零握手开销。但纸条很小，一次只能递 8 字节有效数据。适合小消息。
• LL128：把纸条换成 128 字节的便签纸，一次递 120 字节有效数据，但要求便签纸必须 16 字节对齐摆放，否则要先在共享内存里「重新排版」。适合中等消息。
• Simple：像快递柜，先把包裹放进柜子（FIFO 缓冲区），再发一条「第 N 号柜有货」的通知。握手开销大，但一次能搬很多。适合大消息。

三套原语共享同一个模板骨架 Primitives<T, RedOp, Fan, Direct, Proto, P2p, isNetOffload>，通过 Proto 这个模板参数特化出三个版本 📎 src/device/primitives.h:117-117。ProtoLL、ProtoLL128、ProtoSimple 三个结构体各自携带协议相关的常量与计算方法 📎 src/device/primitives.h:25-75，算法代码只调用 prims.send()、prims.recvReduceSend() 这类统一接口，不关心底层是哪种协议。

flowchart TD
    algo["算法层 all_reduce.h<br/>调用 prims.recvReduceSend()"] --> dispatch{"Proto 模板参数?"}
    dispatch -->|ProtoLL| ll["Primitives&lt;..., ProtoLL, ...&gt;<br/>prims_ll.h"]
    dispatch -->|ProtoLL128| ll128["Primitives&lt;..., ProtoLL128, ...&gt;<br/>prims_ll128.h"]
    dispatch -->|ProtoSimple| simple["Primitives&lt;..., ProtoSimple&lt;...&gt;, ...&gt;<br/>prims_simple.h"]
    ll --> llop["LLGenericOp&lt;RECV,SEND,SrcBuf,DstBuf&gt;"]
    ll128 --> ll128op["GenericOp -&gt; recvReduceSendCopy"]
    simple --> simpleop["genericOp -&gt; waitPeer / reduceCopy / postPeer"]

这张图说明了「同一份 AllReduce 逻辑为什么需要三套搬运原语」：算法层是协议无关的，协议差异被封装在 Primitives 的三个特化里。

LL：用 flag 内嵌在数据行里的零握手搬运

直觉模型

LL 的核心思想是：把「数据」和「数据是否就绪」的标记塞进同一个 16 字节的读写单元。接收方不需要额外的「通知消息」，只要轮询数据行里的 flag 字段，flag 匹配就说明数据到了。这就像寄信时把「收件人签名」直接印在信封上，邮递员一看签名就知道该不该投递，不需要另发一张签收单。

如果没有这个设计，接收方就得先等一个「数据已写入」的通知，再回头读数据，两次内存往返，延迟翻倍。

数据结构与内存布局

LL 的搬运单元是 union ncclLLFifoLine，从 storeLL 的汇编可以看出它的布局 📎 src/device/prims_ll.h:154-158：

st.volatile.global.v4.u32 [%0], {%1,%2,%3,%4};
// 写入 4 个 u32：data1, flag, data2, flag

一个 ncclLLFifoLine 是 16 字节，排布为 [data1(4B) | flag(4B) | data2(4B) | flag(4B)]。有效数据只有 8 字节（data1 + data2），另外 8 字节全是 flag。这就是 ProtoLL::calcBytePerGrain() 返回 sizeof(uint64_t) 的原因——「One 16-byte line has 8-bytes of data」📎 src/device/primitives.h:55-57。

关键字段（Primitives 的 LL 特化）📎 src/device/prims_ll.h:20-42：

缓冲区偏移由 recvOffset(i) = (recvStep[i] % NCCL_STEPS) * stepLines 计算 📎 src/device/prims_ll.h:44-46，NCCL_STEPS 是环形缓冲区的槽位数，stepLines 是每槽的行数。flag 值由 recvFlag(i) = NCCL_LL_FLAG(recvStep[i] + 1) 计算 📎 src/device/prims_ll.h:56-58，注意 +1——因为 flag 初值是 0，第一步的 flag 必须是 1 才能和「未写入」区分开。

场景驱动 Walkthrough：一次 recvReduceSend

假设 rank 0 在 Ring AllReduce 中执行 recvReduceSend：从上一个 rank 收数据、和本地数据做 reduce、再发给下一个 rank。调用链是 recvReduceSend(inpIx, eltN) → LLGenericOp<1, 1, Input, -1>(inpIx, -1, eltN, false) 📎 src/device/prims_ll.h:403-405。

第一步：等待发送缓冲区可用。 waitSend 检查 sendConnHeadCache + NCCL_STEPS < sendConnHead + 1 📎 src/device/prims_ll.h:73-89。含义是：如果对端消费进度（head）落后我太多，说明环形缓冲区快满了，必须等。NCCL_STEPS 是缓冲区总槽数，sendConnHead + 1 是我即将占用的槽位。等待时轮询 *sendConnHeadPtr 更新缓存，并周期性调用 checkAbort 检查是否被 abort 📎 src/device/prims_ll.h:73-89。

第二步：加载本地数据。 DataLoader::loadBegin 处理对齐问题 📎 src/device/prims_ll.h:200-216。当 sizeof(T) <= 2（比如 half 或 int8），源地址可能不是 4 字节对齐，所以先按 4 字节对齐读入 u4[0..2]，记录 misalign，然后在 loadFinish 里用 __funnelshift_r 做字节级移位拼出正确的 64 位值 📎 src/device/prims_ll.h:218-225。这是一个典型的「对齐读 + 移位重组」技巧，避免了非对齐访问的性能惩罚。

第三步：读对端数据并等 flag。 readLL 是核心 📎 src/device/prims_ll.h:108-122：

do {
  asm volatile("ld.volatile.global.v4.u32 {%0,%1,%2,%3}, [%4];" ...);
  if (checkAbort(abort, 1, spins)) break;
} while ((flag1 != flag) || (flag2 != flag));

它用 ld.volatile.global.v4.u32 一次性读 16 字节（4 个 u32），然后检查两个 flag 字段是否都等于期望值。volatile 关键字确保编译器不会把这个读优化掉或缓存到寄存器——因为对端可能随时写入新数据。两个 flag 都要匹配，是因为写入方 storeLL 一次写 4 个 u32，理论上可能被拆成两次 8 字节写，两个 flag 都匹配才能保证 16 字节完整。

第四步：reduce 并发送。 收到 peerData 后，applyReduce(redOp, peerData, data) 做归约 📎 src/device/prims_ll.h:279。然后 storeLL(sendPtr(i) + offset, data, sendFlag(i)) 把结果写入发送缓冲区 📎 src/device/prims_ll.h:295-296。注意发送顺序：先发 i=1..MaxSend（通常是网络 peer），最后发 i=0（通常是本地 peer）📎 src/device/prims_ll.h:291-297。注释写得很清楚：「Send : inter-node, then intra-node, then local」——先发慢的（网络），让它在后台飞，再发快的（本地），这样本地 peer 不会等网络。

第五步：推进 step 并 post。 incRecv(i) 递增接收步进 📎 src/device/prims_ll.h:91-93，postRecv() 把 recvConnHead 写回全局指针 📎 src/device/prims_ll.h:94-97，通知对端「我已经消费了这一步」。发送侧 incSend 有个特殊逻辑 📎 src/device/prims_ll.h:99-106：

if ((sendStep[i] & NCCL_LL_CLEAN_MASK) == NCCL_LL_CLEAN_MASK) {
  for (int o = offset; o < stepLines; o += nthreads) storeLL(sendPtr(i) + o, 0, sendFlag(i));
}

当 step 到达 NCCL_LL_CLEAN_MASK 边界时，要把整个 slice 的所有行都用当前 flag 写一遍（数据填 0）。为什么？因为 flag 是循环复用的，如果某一行上次的 flag 恰好等于这次的期望值，接收方会误以为数据已就绪。这个「cleanup」操作把所有行的 flag 统一刷成新值，消除歧义。

并发控制与硬件交互

LL 的同步完全靠 volatile 读写 + flag 轮询，没有锁。barrier() 用 __syncwarp()（单 warp 时）或 barrier_sync(15 - group, nthreads)（多 warp 时）📎 src/device/prims_ll.h:63-69。15 - group 是 barrier 编号，NCCL 用不同的 barrier 编号隔离不同的 group，避免相互干扰。

checkAbort 是防死循环的关键 📎 src/device/primitives.h:154-164：每 NCCL_SPINS_BEFORE_CHECK_ABORT（10000）次自旋才读一次 abortFlag，避免频繁读全局内存拖慢热路径。一旦发现 abort，设置 ncclShmem.aborted 并缓存，后续所有等待循环都会快速退出。

生产踩坑

坑 1：flag 回绕导致的假就绪。 如果 NCCL_LL_CLEAN_MASK 的 cleanup 逻辑被去掉，在长时间运行（step 超过 mask 周期）后，接收方可能读到上一轮残留的 flag，误判数据就绪，读到脏数据。这类 bug 极难复现，因为它依赖 step 恰好回绕到特定值。

坑 2：MaxRecv == 0 的编译陷阱。 代码里 MaxRecv = Fan::MaxRecv > 1 ? Fan::MaxRecv : 1 📎 src/device/prims_ll.h:13，因为即使只发不收，也会分配一个长度为 MaxRecv 的接收缓冲区，如果 MaxRecv 是 0 会导致零长度数组编译失败。Windows 上 MaxSend 也有同样处理 📎 src/device/prims_ll.h:14-19。

LL128：用 128 字节对齐换取更高有效载荷

直觉模型

LL 的痛点是有效载荷只有 50%（16 字节里 8 字节是 flag）。LL128 的思路是：把 flag 集中到每 128 字节的最后 8 字节，前面 120 字节全是数据。这样有效载荷从 50% 提升到 93.75%。代价是必须保证 128 字节对齐，否则要做「共享内存重排版」。

数据结构与内存布局

LL128 的搬运单元是 uint64_t（8 字节），但组织成 128 字节的「line」。NCCL_LL128_LINEELEMS 是每 line 的 64 位元素数（16 个），NCCL_LL128_DATAELEMS 是其中数据元素数（15 个），最后一个元素放 flag。

关键常量 📎 src/device/prims_ll128.h:292-294：

static constexpr int WireWordPerSlice = WARP_SIZE * NCCL_LL128_SHMEM_ELEMS_PER_THREAD;
static constexpr int DataEltPerSlice =
  (WireWordPerSlice - WireWordPerSlice / NCCL_LL128_LINEELEMS) * (sizeof(uint64_t) / sizeof(T));

WireWordPerSlice 是一个 warp 一次搬运的 64 位字数，DataEltPerSlice 是其中有效数据元素数（减去每 line 一个 flag 元素）。

LL128 的 flag 机制和 LL 不同：只有每 8 个线程中的第 7 个（flagThread）负责检查 flag 📎 src/device/prims_ll128.h:373。flagThread = ((tid % 8) == 7)。为什么？因为 flag 是每 128 字节一个，而一个 warp 有 32 个线程，每 8 个线程处理 128 字节（8 线程 × 16 字节 = 128 字节），所以每 8 个线程里只有 1 个需要读 flag。

场景驱动 Walkthrough：一次 recvReduceSendCopy

调用链：recvReduceSend(inpIx, eltN) → GenericOp<1, 1, Input, -1> → recvReduceSendCopy<NCCL_LL128_SHMEM_ELEMS_PER_THREAD, RECV, SEND, SrcBuf, DstBuf> 📎 src/device/prims_ll128.h:422-423, 296-333。

第一步：加载本地数据到寄存器。 loadRegsBegin 分两种情况 📎 src/device/prims_ll128.h:99-142：

• 16 字节对齐：直接 load128 到寄存器，无共享内存中转。注意 flagThread 只加载一半数据（g % 2 == 0），因为它的另一半寄存器要留给 flag 📎 src/device/prims_ll128.h:109-114。
• 非对齐：先把对齐区域加载到共享内存 ncclScratchForWarp(warpInBlock)，__syncwarp() 后从共享内存按正确偏移读回寄存器 📎 src/device/prims_ll128.h:115-141。

第二步：等待并读取对端数据。 recvReduceSendCopy 里的等待循环 📎 src/device/prims_ll128.h:190-207：

do {
  needReload = false;
  for (int u = 0; u < ELEMS_PER_THREAD; u += 2) {
    load128(ptr + u * WARP_SIZE, vr[u], vr[u + 1]);
    needReload |= flagThread && (vr[u + 1] != flag);
  }
  needReload &= (0 == checkAbort(abort, 1, spins));
} while (__any_sync(WARP_MASK, needReload));

关键点：只有 flagThread 检查 flag，然后用 __any_sync 做 warp 级投票——只要有一个 flagThread 发现 flag 不匹配，整个 warp 继续自旋。这比每个线程都检查 flag 更省指令。

第三步：寄存器重排。 loadRegsFinish 把 flagThread 的 flag 寄存器移到空闲寄存器 📎 src/device/prims_ll128.h:145-151。注释解释了这个设计：「By deferring register shuffle here we've overlapped spinning on first peer's data with memory loads of src data」——把寄存器重排推迟到等待之后，让等待时间和本地数据加载重叠。

第四步：reduce 并发送。 收到数据后做 applyReduce 📎 src/device/prims_ll128.h:227-230，然后 store128 写入发送缓冲区 📎 src/device/prims_ll128.h:274-287。注意发送时 flagThread ? flag : v[u+1]——flagThread 写 flag，其他线程写数据。

第五步：推进 step。 和 LL 不同，LL128 的 step 推进在 GenericOp 末尾统一做 📎 src/device/prims_ll128.h:324-332，而不是在 recvReduceSendCopy 里。而且 postSend 用了 __threadfence_system()（SM90+）或 __threadfence() 📎 src/device/prims_ll128.h:87-96，确保数据对其他 GPU/网卡可见后才更新 tail 指针。

并发控制与硬件交互

LL128 的 barrier() 总是用 barrier_sync(15 - group, nthreads) 📎 src/device/prims_ll128.h:64-66，不像 LL 有单 warp 优化。因为 LL128 的数据搬运是 warp 级的，需要跨 warp 同步。

loadRegsBegin 里的共享内存重排版用 __syncwarp() 同步 📎 src/device/prims_ll128.h:129，确保所有线程写完共享内存后再读。

生产踩坑

坑 1：非对齐访问的性能悬崖。 如果用户缓冲区不是 16 字节对齐，每次搬运都要走共享内存中转，性能可能下降 30% 以上。生产环境应确保输入输出缓冲区按 16 字节对齐分配。

坑 2：flagThread 的寄存器压力。 flagThread 只加载一半数据，意味着它的寄存器利用率和其他线程不同。如果编译器没有正确分配寄存器，可能导致寄存器溢出到本地内存，性能骤降。

Simple：用 FIFO + 通知实现大消息高吞吐

直觉模型

Simple 协议像快递柜：发送方把数据放进 FIFO 缓冲区（柜子），然后更新一个「已放入第 N 号柜」的 step 指针（发通知）；接收方轮询 step 指针，看到新值就去对应柜子取货。握手开销大（要写指针 + 读指针），但一次能搬很多数据，适合大消息。

数据结构与内存布局

Simple 的字段比 LL/LL128 复杂得多 📎 src/device/prims_simple.h:28-46：

flags 的位定义 📎 src/device/prims_simple.h:23-27：

RoleInput = 0x01, RoleOutput = 0x02, RoleWaitRecv = 0x04, RoleWaitSend = 0x08,
RolePostSend = 0x10, RolePostRecv = 0x20, Aborted = 0x40, NetRegMode = 0x80,
ConnFifoEnabled = 0x100, DirectWrite = 0x200, DirectRead = 0x400, PatMode = 0x800,
NvlsMinPolling = 0x1000, NetDeviceUnpack = 0x2000, AnyNetDeviceUnpack = 0x4000,
RoleWaitPatNvls = 0x8000, RolePostPatNvls = 0x10000;

这是一个典型的「用位运算代替多个 bool 字段」的设计，节省寄存器。每个线程根据自己的 tid 被分配一个角色 📎 src/device/prims_simple.h:651-666：前 nrecv 个线程是 WaitRecv，接下来 nsend 个是 WaitSend，最后 nrecv 个是 PostRecv，倒数 nsend 个是 PostSend。

场景驱动 Walkthrough：一次 recvReduceSend

调用链：recvReduceSend(inpIx, eltN) → genericOp<0, 0, 1, 1, Input, -1> 📎 src/device/prims_simple.h:994-996。

第一步：计算 slice 大小。 sliceSize = max(divUp(nelem, 16 * SlicePerChunk) * 16, sliceSize / 32) 📎 src/device/prims_simple.h:185-186。这个公式保证 slice 至少是 16 字节对齐，且不会太小。

第二步：worker 循环。 只有 tid < nworkers 的线程进入主循环 📎 src/device/prims_simple.h:190。nworkers = nthreads - (MaxSend > 0 && nthreads >= NCCL_SIMPLE_EXTRA_GROUP_IF_NTHREADS_GE ? WARP_SIZE : 0) 📎 src/device/prims_simple.h:626——预留一个 warp 做 threadfence 和 copy 的重叠。

第三步：等待对端。 waitPeer 是核心 📎 src/device/prims_simple.h:103-164：

while (connStepCache + (isSendNotRecv ? NCCL_STEPS : 0) < step + StepPerSlice) {
  connStepCache = loadStepValue(connStepPtr);
  if (checkAbort(flags, Aborted, spins)) break;
}

isSendNotRecv 区分发送和接收：发送时等的是「对端已消费」（head），接收时等的是「对端已生产」（tail）。NCCL_STEPS 是缓冲区槽数，StepPerSlice 是每 slice 的步进数。

等待完成后，根据 Direct 模式设置 ptrs[index] 📎 src/device/prims_simple.h:123-158。Direct 模式允许直接读写对端缓冲区，绕过 FIFO，减少一次拷贝。

第四步：reduceCopy。 根据 Direct 组合选择不同的 reduceCopy 调用 📎 src/device/prims_simple.h:241-277。最复杂的分支是 srcs[0] && dsts[0] 都存在时 📎 src/device/prims_simple.h:258-271，调用 reduceCopy<Unroll, RedOp, T, MultimemSrcs, Recv+Src, Recv*MaxRecv+Src, MultimemDsts, Send+Dst, Send*MaxSend+Dst, PreOpSrcs>，参数含义是：从 Recv*MaxRecv+Src 个源读，归约后写到 Send*MaxSend+Dst 个目的地。

第五步：postPeer。 postPeer 更新 step 指针 📎 src/device/prims_simple.h:167-175：

if (Send && (flags & RolePostSend) && (dataStored || (flags & ConnFifoEnabled))) {
  fence_acq_rel_sys();
}
st_relaxed_sys_global(connStepPtr, step);

发送侧在更新 step 前要 fence_acq_rel_sys()，确保数据写入对其他 GPU/网卡可见。接收侧不需要 fence，因为接收方只是通知「我已消费」，不涉及数据可见性。

并发控制与硬件交互

Simple 的同步用 st_relaxed_sys_global 写 step 指针 📎 src/device/prims_simple.h:167-175，用 loadStepValue 读 📎 src/device/prims_simple.h:86-100。loadStepValue 在 SM90+ 且启用 NvlsMinPolling 时用 multimem.ld_reduce.acquire.sys.global.min.u64 指令 📎 src/device/prims_simple.h:86-100，这是 NVLink SHARP 的硬件加速轮询。

barrier() 和 subBarrier() 的区别 📎 src/device/prims_simple.h:49-55：barrier() 同步所有 nthreads 个线程，subBarrier() 只同步 nworkers 个 worker 线程。subBarrier 的 barrier 编号是 15 - group - (nworkers != nthreads ? 1 : 0)，当 worker 数不等于总线程数时用不同的 barrier，避免和 barrier() 冲突。

生产踩坑

坑 1：NetRegMode 下的析构等待。 析构函数里有一段特殊逻辑 📎 src/device/prims_simple.h:794-804：

if ((flags & NetRegMode) && (flags & RoleWaitSend)) {
  uint64_t prevStep = step - StepPerSlice;
  volatile ssize_t* ptr = &(connFifo[prevStep % NCCL_STEPS].size);
  while (*ptr != -1) { ... }
}

在 NetRegMode 下，发送缓冲区被网卡直接访问，必须等 proxy 线程确认已发送（size 被设为 -1）才能返回，否则下一个 kernel 可能覆盖正在被网卡读取的数据。

坑 2：DirectRead 的 sendrecv 死锁。 析构函数里还有一段 📎 src/device/prims_simple.h:814-824：

if ((flags & DirectRead) && (flags & RoleWaitSend) && P2p) {
  while (*tail > *head) { ... }
}

在 sendrecv 的 DirectRead 模式下，发送方必须等接收方读完数据才能返回。如果接收方因为某种原因没有推进 tail，发送方会死锁。这个等待必须在 barrier() 之后做，否则可能和 post 线程竞争。

坑 3：roundUp 导致的 step 跳跃。 loadRecvConn 和 loadSendConn 里都有 step = roundUp(step, SlicePerChunk * StepPerSlice) 📎 src/device/prims_simple.h:486, 533。这会把 step 对齐到 slice 边界，但如果上一步的 step 不是对齐的，会导致跳过的槽位没有被正确初始化。代码在 loadRecvConn 里补了一句 *connStepPtr = step 来归还 credit 📎 src/device/prims_simple.h:489。

三套原语的对比与选型

flowchart LR
    subgraph LL["LL 协议"]
        ll_data["ncclLLFifoLine 16B<br/>data1(4B)+flag(4B)+data2(4B)+flag(4B)"]
        ll_sync["flag 内嵌数据行<br/>轮询 flag 匹配"]
    end
    subgraph LL128["LL128 协议"]
        ll128_data["128B line<br/>15×8B data + 1×8B flag"]
        ll128_sync["flagThread 每8线程1个<br/>__any_sync 投票"]
    end
    subgraph Simple["Simple 协议"]
        simple_data["FIFO 缓冲区<br/>connEltsFifo + step*connStepSize"]
        simple_sync["step 指针 + fence<br/>loadStepValue 轮询"]
    end
    ll_data --> ll_sync
    ll128_data --> ll128_sync
    simple_data --> simple_sync

LL 和 LL128 都继承 PrimitivesWithoutDirect 📎 src/device/prims_ll.h:9-10, src/device/prims_ll128.h:13-14，因为它们的缓冲区布局不支持直接读写对端内存。Simple 则完整实现了 Direct 模式，支持 P2P 直连和 NVLS。

设计思考

为什么 Simple 要预留一个 warp？ 📎 src/device/prims_simple.h:625-626 注释说「For send operations, we need an extra warp to overlap the threadfence and the copy」。fence_acq_rel_sys() 是一个昂贵的操作，如果所有线程都等 fence 完成再继续，会浪费大量时间。预留一个 warp 专门做 fence，其他 warp 可以继续搬运下一批数据。

本章小结

本章深入了三套搬运原语的实现：

1. LL：用 16 字节的 ncclLLFifoLine 把 flag 内嵌在数据行里，接收方轮询 flag 匹配即可确认数据就绪。有效载荷 50%，适合小消息。核心是 readLL 的 ld.volatile.global.v4.u32 和 storeLL 的 st.volatile.global.v4.u32。

2. LL128：把 flag 集中到每 128 字节的最后 8 字节，有效载荷提升到 93.75%。用 flagThread（每 8 线程 1 个）检查 flag，__any_sync 做 warp 投票。非对齐时走共享内存重排版。

3. Simple：用 FIFO 缓冲区 + step 指针通知实现大消息高吞吐。flags 位标志编码角色，waitPeer 轮询 step，postPeer 更新 step 并 fence。完整支持 Direct 模式。

三套原语共享同一个模板骨架，通过 Proto 模板参数特化。算法层只调用统一接口，不关心底层协议。这就是「同一份 AllReduce 逻辑为什么需要三套搬运原语」的答案：不同消息大小需要不同的同步策略和缓冲区布局，三套原语分别针对小、中、大消息优化。

本章思考与自测

<details><summary>Q1: 如果把 incSend 里的 cleanup 逻辑（📎 src/device/prims_ll.h:99-106）去掉，在什么场景下会触发数据损坏？为什么？</summary>

参考解析：cleanup 逻辑在 sendStep[i] & NCCL_LL_CLEAN_MASK == NCCL_LL_CLEAN_MASK 时，把整个 slice 的所有行都用当前 flag 写一遍（数据填 0）。如果去掉，当 step 回绕到 NCCL_LL_CLEAN_MASK 边界时，某些行的 flag 可能还是上一轮的值。如果上一轮的 flag 恰好等于这一轮接收方期望的 flag，接收方会误以为数据已就绪，读到上一轮的残留数据。这是一个典型的 ABA 问题。触发条件是长时间运行（step 超过 NCCL_LL_CLEAN_MASK 周期）且 flag 恰好回绕到相同值。这类 bug 极难复现，因为需要精确的 step 对齐。

</details>

<details><summary>Q2: Simple 协议的析构函数里，NetRegMode 下的等待（📎 src/device/prims_simple.h:794-804）和 DirectRead 下的等待（📎 src/device/prims_simple.h:814-824）分别在防什么？如果去掉其中一个，在高并发场景下会发生什么？</summary>

参考解析：NetRegMode 等待的是 proxy 线程把 connFifo[prevStep].size 设为 -1，表示网卡已完成发送。如果去掉，下一个 kernel 可能覆盖正在被网卡 DMA 读取的发送缓冲区，导致网卡读到脏数据。DirectRead 等待的是接收方推进 tail（*tail > *head），表示接收方已读完直接缓冲区。如果去掉，发送方可能在接收方还没读完时就覆盖了缓冲区，导致接收方读到新数据而非旧数据。在高并发场景下，这两个等待都是必须的，去掉任何一个都会导致数据竞争。区别是 NetRegMode 防的是「网卡读」，DirectRead 防的是「对端 GPU 读」。

</details>

<details><summary>Q3: LL128 的 loadRegsBegin 在非对齐时走共享内存重排版（📎 src/device/prims_ll128.h:115-141），这个路径比对齐路径慢多少？为什么 NCCL 不直接要求用户缓冲区必须 16 字节对齐？</summary>

参考解析：非对齐路径多了三步：写共享内存、__syncwarp()、从共享内存读。共享内存的带宽虽然高，但 __syncwarp() 是一个同步点，会阻塞 warp 直到所有线程完成写入。粗略估计，非对齐路径比对齐路径慢 20-40%，具体取决于共享内存 bank 冲突情况。NCCL 不强制要求对齐，是因为用户可能传入任意偏移的缓冲区（比如 tensor 切片），强制对齐会限制 API 的灵活性。NCCL 的策略是「对齐时走快路径，非对齐时走慢路径但保证正确性」。生产环境建议用户尽量按 16 字节对齐分配缓冲区，以走快路径。

</details>

至此，我们已经掌握了 LL、LL128、Simple 三种原语的数据搬运机制，它们为上层算法提供了灵活的性能调节手段。下一章将深入集合通信算法内核，看 AllReduce、AllGather、ReduceScatter 等如何调用这些原语，以及 Ring、Tree、CollNet 等算法如何组织数据流，最终完成端到端的集合通信。

第 10 章：集体通信算法内核：AllReduce、AllGather、ReduceScatter 的设备端实现

上一章拆解了 LL、LL128、Simple 三种协议原语，它们是数据搬运的「发动机」，但发动机本身不知道要搬什么、往哪搬、按什么顺序搬。本章要看的 src/device 下这一组算法内核文件，就是「变速箱」——它们把 AllReduce、AllGather、ReduceScatter 这些集合通信语义，翻译成一连串 prims.directSend、prims.directRecvReduceDirectSend 这样的原语调用。一句话概括本章的核心矛盾：同一个 AllReduce，为什么需要 Ring、Tree、CollNet、NVLS 四套完全不同的设备侧实现？答案藏在「数据流拓扑」与「硬件能力」的匹配里。Ring 用最少的网络带宽做两阶段流水，Tree 用树形归约把延迟压到 log(n)，CollNet/NVLS 则把归约卸载到网卡或 NVLink 交换机上。本章逐个拆开看。

10.1 Ring AllReduce：两阶段流水如何在 kernel 内落地

直觉模型：环形流水线上的「接力赛」

想象 n 个工人站成一圈，每人手里有一箱原料。AllReduce 的目标是让每个人最终都拿到「所有原料混合后的成品」。Ring 算法的做法分两阶段：第一阶段（reduce-scatter）每人把箱子沿环传递，每传一站就混入自己的原料，转 n-1 站后每个人手里恰好有一份「完整混合」的成品，但只有 1/n 的份额；第二阶段（all-gather）这些成品份额再沿环传一圈，每人补齐所有份额。

若没有 Ring，最朴素的做法是每个 rank 把数据发给 root，root 归约后再广播——root 的网络带宽成为瓶颈，n 越大越慢。Ring 的精妙在于：每个 rank 的发送量和接收量都是 2(n-1)/n 倍数据量，与 n 无关地摊平到所有链路。

数据结构与内存布局

Ring 算法的核心状态在 ncclRing 结构里（定义在 device.h，本章不展开），runRing 只取其中两个字段：

• ring->index：本 rank 在环中的逻辑位置，用于计算「第 j 步该处理哪个 chunk」。
• ring->prev / ring->next：前驱和后继 rank 编号，作为 Primitives 构造函数的 recv/send peer 参数。

关键的分块参数由 ncclCollCbdPart 计算（📎 src/device/all_reduce.h:21-22）：

ncclCollCbdPart(work, ncclShmem.channelId, Proto::Id, sizeof(T), (ssize_t*)nullptr, &gridOffset, &channelCount, &chunkCount);

这个函数把整个通信域的数据按 channel 切分，输出三个值：gridOffset（本 channel 负责的数据在整个 buffer 中的起始偏移）、channelCount（本 channel 负责的元素总数）、chunkCount（每个 rank 分到的 chunk 元素数）。chunkCount 是 Ring 算法的粒度——每一步搬运一个 chunk。

loopCount = nranks * chunkCount（📎 src/device/all_reduce.h:23）表示「转一整圈」处理的数据量。外层循环 for (elemOffset = 0; elemOffset < channelCount; elemOffset += loopCount)（📎 src/device/all_reduce.h:34）意味着：如果 channel 数据量超过一圈能处理的量，就分多圈跑。

Step-by-Step Walkthrough：一次 Ring AllReduce 的完整调用流

代入场景：4 个 rank（nranks=4），本 rank 的 ringIx=0，chunkCount=100，channelCount=400（正好一圈）。

第 0 步：把「自己的 chunk」推给下一个 GPU（📎 src/device/all_reduce.h:42-47）

chunk = modRanks(ringIx + nranks - 1);   // = 3
chunkOffset = chunk * chunkCount;         // = 300
offset = gridOffset + elemOffset + chunkOffset;
nelem = min(chunkCount, remCount - chunkOffset);
prims.directSend(offset, offset, nelem);

modRanks 是个 lambda，做模 nranks 的减法（📎 src/device/all_reduce.h:40）。ringIx + nranks - 1 表示「本 rank 的前一个 chunk 编号」。为什么第 0 步发的是 chunk 3？因为 Ring 的 reduce-scatter 阶段，每个 rank 先把自己「不该保留」的那份数据（即前驱 rank 的 chunk）发出去。directSend 只发不接，因为此时还没收到任何数据。

第 1 到 nranks-2 步：边收边归约边转发（📎 src/device/all_reduce.h:50-56）

for (int j = 2; j < nranks; ++j) {
  chunk = modRanks(ringIx + nranks - j);
  ...
  prims.directRecvReduceDirectSend(offset, offset, nelem);
}

directRecvReduceDirectSend 是 Ring 的核心原语：从 prev 收一个 chunk，与本地数据做归约（比如加法），再把结果发给 next。注意 offset 和 nelem 在每次迭代都重新计算——因为每步处理的 chunk 不同。j 从 2 到 nranks-1，共 nranks-2 步。

第 nranks-1 步：收下最后一个 chunk 并归约，产生最终结果（📎 src/device/all_reduce.h:58-64）

chunk = ringIx + 0;
...
prims.directRecvReduceCopyDirectSend(offset, offset, nelem, /*postOp=*/true);

这一步的 postOp=true 是关键：归约完成后要执行后置操作（比如求平均时的除法）。directRecvReduceCopyDirectSend 比上一步多了个 Copy——把归约结果同时写入本地 recvbuff 和发往 next。至此 reduce-scatter 阶段结束，每个 rank 手里有一个「完整归约」的 chunk。

all-gather 阶段：nranks-2 步纯转发（📎 src/device/all_reduce.h:66-73）

for (int j = 1; j < nranks - 1; ++j) {
  chunk = modRanks(ringIx + nranks - j);
  ...
  prims.directRecvCopyDirectSend(offset, offset, nelem);
}

注意这里用的是 directRecvCopyDirectSend，没有 Reduce——因为数据已经归约完了，只需复制转发。

最后一步：收下最后一个 chunk（📎 src/device/all_reduce.h:75-81）

chunk = modRanks(ringIx + 1);
...
prims.directRecv(offset, nelem);

只收不发，补齐最后一块。

整个流程可以用下面的控制流图概括：

flowchart TD
    start["runRing 入口<br/>计算 chunkCount/loopCount"] --> loop{"elemOffset < channelCount?"}
    loop -->|否| done["返回"]
    loop -->|是| s0["step 0: directSend<br/>chunk = ringIx-1"]
    s0 --> mid{"j 从 2 到 nranks-1?"}
    mid -->|是| s1["directRecvReduceDirectSend<br/>chunk = ringIx-j"]
    s1 --> mid
    mid -->|否| s2["step nranks-1<br/>directRecvReduceCopyDirectSend<br/>postOp=true"]
    s2 --> ag{"j 从 1 到 nranks-2?"}
    ag -->|是| s3["directRecvCopyDirectSend<br/>纯转发"]
    s3 --> ag
    ag -->|否| s4["directRecv<br/>收最后一块"]
    s4 --> loop

设计思考：为什么 Ring 的 chunk 顺序是「倒着走」的

注意 chunk 编号的规律：第 0 步发 ringIx-1，第 j 步处理 ringIx-j，最后一步处理 ringIx+0。这是逆时针推进。为什么？因为 Ring 的每个 rank 只保留「自己负责归约的那个 chunk」（即 ringIx+0），其余 chunk 都是路过。逆时针推进保证：当某个 chunk 转完一圈回到起点时，恰好完成了 nranks 次归约，产生最终结果。如果顺时针推进，chunk 会在错误的 rank 上完成归约。

生产踩坑：remCount < loopCount 时的对齐陷阱

📎 src/device/all_reduce.h:38 有一行容易被忽略的代码：

if (remCount < loopCount) chunkCount = alignUp(divUp(remCount, nranks), 16 / sizeof(T));

当剩余数据不足一圈时，chunkCount 要重新计算，并且 alignUp(..., 16/sizeof(T)) 强制按 16 字节对齐。为什么？因为 LL128 协议要求 128 字节对齐，Simple 协议也有向量化访问的对齐需求。如果去掉这个对齐，非对齐的 chunk 会走慢路径，性能下降 20-40%。生产环境中如果发现 Ring AllReduce 在小消息尾部性能抖动，往往就是这个对齐没生效——检查 channelCount 是否是 nranks * 16/sizeof(T) 的整数倍。

10.2 Tree AllReduce：用树形归约把延迟压到 log(n)

直觉模型：公司里的「逐级汇报」

Ring 的延迟是 O(n)——数据要转一圈。当 n 很大（比如 1024 个 GPU）时，即使带宽摊平了，延迟也受不了。Tree 算法换了个思路：像公司组织架构一样，每个 rank 只跟「父节点」和「子节点」通信。归约阶段，叶子节点把数据往上汇报，父节点合并子节点的数据；广播阶段反过来，根节点把结果往下发。延迟从 O(n) 降到 O(log n)。

若没有 Tree，大规模集群的 AllReduce 延迟会随 rank 数线性增长，训练迭代时间被通信拖垮。

数据结构与内存布局

Tree 的状态在 ncclTree 里：

• tree->up：父节点 rank（-1 表示本 rank 是根）。
• tree->down[]：子节点数组，最多 NCCL_MAX_TREE_ARITY 个（典型是 3，即二叉+本地）。

runTreeUpDown 和 runTreeSplit 是两个变体。前者用「先全部归约再全部广播」的两阶段模式，后者把线程拆成两半，一半做归约一半做广播，实现流水重叠。

Step-by-Step Walkthrough：runTreeUpDown 的三分支

runTreeUpDown 的第一个代码块是归约阶段（📎 src/device/all_reduce.h:96-118），根据本 rank 在树中的位置分三种情况：

情况 A：本 rank 是根（tree->up == -1）（📎 src/device/all_reduce.h:99-104）

prims.directRecvReduceCopy(offset, offset, nelem, /*postOp=*/true);

根节点只收不发，从所有子节点收数据、归约、写入 recvbuff。postOp=true 执行后置操作。

情况 B：本 rank 是叶子（tree->down[0] == -1）（📎 src/device/all_reduce.h:105-110）

prims.directSend(offset, offset, nelem);

叶子节点只发不收，把自己的数据发给父节点。

情况 C：中间节点（📎 src/device/all_reduce.h:111-117）

prims.directRecvReduceDirectSend(offset, offset, nelem);

从子节点收、归约、发给父节点。

广播阶段（📎 src/device/all_reduce.h:120-142）逻辑对称：根节点 directSendFromOutput（从 recvbuff 发），叶子节点 directRecv，中间节点 directRecvCopyDirectSend。

runTreeSplit：用线程拆分实现归约-广播流水

runTreeUpDown 的问题是：归约阶段和广播阶段串行，中间有个全局同步点。runTreeSplit 把线程分成两组（📎 src/device/all_reduce.h:155-164）：

if (Proto::Id == NCCL_PROTO_SIMPLE) {
  nthreadsSplit = nthreads / 2;
  if (nthreadsSplit >= 256) nthreadsSplit += 64;
} else {
  nthreadsSplit = (nthreads * 7 / (10 * WARP_SIZE)) * WARP_SIZE;
}

Simple 协议对半分；LL/LL128 协议按 7:3 分，因为「从 3 个源收数据做归约」比「发给 3 个目标」计算密集，所以归约组多分线程。

然后 tid < nthreadsSplit 的线程做归约上推（📎 src/device/all_reduce.h:175-202），其余线程做广播下推（📎 src/device/all_reduce.h:203-224）。两组通过 Proto::MaxGroupWidth 偏移量区分各自的通信组（📎 src/device/all_reduce.h:189 的 0 * Proto::MaxGroupWidth 和 📎 src/device/all_reduce.h:210 的 1 * Proto::MaxGroupWidth）。

设计思考：为什么 Tree 的根节点要特殊处理

树形归约的根节点是「汇聚点」，它的接收量是子节点数倍，发送量为零（归约阶段）。如果根节点也走通用的 directRecvReduceDirectSend，会尝试往 tree->up（-1）发送，导致越界。所以必须用 if (tree->up == -1) 分支单独处理。同理叶子节点的 tree->down[0] == -1 判断。

生产踩坑：Tree 算法的「热点根」问题

Tree 的根节点承担了所有归约流量，如果根节点所在 GPU 恰好是慢节点（比如 PCIe 带宽受限），整个 AllReduce 会被拖慢。NCCL 的应对是：每个 channel 选不同的根，把根节点的负载分散到多个 rank。这就是为什么 runTreeSplit 里根节点分支用 FanSymmetric<NCCL_MAX_TREE_ARITY_TOP>（📎 src/device/all_reduce.h:168）——它要同时处理多个子节点的归约。生产环境如果发现 Tree AllReduce 性能不均，检查 channel 的根节点分布是否均匀。

10.3 AllGather 与 ReduceScatter：Ring 的「半程」变体

直觉模型：AllReduce 拆成两半

AllGather 和 ReduceScatter 本质上是 AllReduce 的两个阶段各自独立成 API。AllGather 只做「收集」——每个 rank 贡献一份数据，最终所有人拿到全部数据。ReduceScatter 只做「归约+分散」——所有人贡献数据，归约后每人拿到一份。

若没有这两个独立 API，用户做「先归约再收集」或「先收集再归约」时只能调 AllReduce 再手动切片，浪费一半带宽。

AllGather 的 Ring 实现

all_gather.h 的 runRing（📎 src/device/all_gather.h:14-88）比 AllReduce 简单：没有归约，只有复制转发。

第 0 步：把自己的数据推给下一个 GPU（📎 src/device/all_gather.h:51-60）

rankDest = ringRanks[0];
offset = dataOffset + rankDest * count;
if ((inputBuf + dataOffset == outputBuf + offset) || isNetOffload) {
  prims.directSend(dataOffset, offset, nelem);
} else {
  prims.directCopySend(dataOffset, offset, nelem);
}

这里有个 in-place 判断：如果 inputBuf + dataOffset == outputBuf + offset，说明输入输出是同一块内存（in-place AllGather），直接 directSend；否则要 directCopySend（先拷贝到输出再发）。

中间 nranks-2 步：纯转发（📎 src/device/all_gather.h:62-67）

prims.directRecvCopyDirectSend(offset, offset, nelem);

最后一步：收下最后一块（📎 src/device/all_gather.h:69-74）

prims.directRecv(offset, nelem);

isNetOffload：单 warp 驱动网络 + 多 warp 并行拷贝

📎 src/device/all_gather.h:28-36 有个特殊分支：

if (isNetOffload) {
  workNthreads = WARP_SIZE;
  chunkCount = NCCL_MAX_NET_SIZE;
} else {
  workNthreads = nthreads;
}

当 isNetOffload=true（单 RPN + 网络注册模式）时，只用 1 个 warp 驱动 Ring 通信，其余 warp 并行做「源数据拷贝到目标 buffer」（📎 src/device/all_gather.h:76-82）。这是为了在非 in-place AllGather 时，把拷贝开销和通信开销重叠。

最后有个 barrier_sync(14, nthreads)（📎 src/device/all_gather.h:87），注释解释得很清楚：必须等所有 warp 完成，否则下一个 work 可能复用 outputBuf 导致竞争。用 barrier 14 是为了避开 prims 自己的 barrier 和 __syncthreads()。

ReduceScatter 的 Ring 实现

reduce_scatter.h 的 runRing（📎 src/device/reduce_scatter.h:14-56）是 AllReduce 的 reduce-scatter 阶段单独抽出：

第 0 步：把自己的数据推给下一个 GPU（📎 src/device/reduce_scatter.h:39-42）

rankDest = ringRanks[nranks - 1];
offset = dataOffset + rankDest * count;
prims.send(offset, nelem);

中间 nranks-2 步：边收边归约边转发（📎 src/device/reduce_scatter.h:44-49）

prims.recvReduceSend(offset, nelem);

最后一步：收下并归约，产生最终结果（📎 src/device/reduce_scatter.h:61-64）

prims.recvReduceCopy(offset, dataOffset, nelem, /*postOp=*/true);

注意最后一步的 recvReduceCopy 有两个 offset：offset（接收源）和 dataOffset（本地输入），归约结果写入 dataOffset。

数据流对比图

flowchart LR
    subgraph AllReduce["AllReduce (两阶段)"]
        A1["reduce-scatter<br/>n-1 步"] --> A2["all-gather<br/>n-1 步"]
    end
    subgraph AG["AllGather (单阶段)"]
        B1["directSend<br/>step 0"] --> B2["directRecvCopyDirectSend<br/>n-2 步"] --> B3["directRecv<br/>step n-1"]
    end
    subgraph RS["ReduceScatter (单阶段)"]
        C1["send<br/>step 0"] --> C2["recvReduceSend<br/>n-2 步"] --> C3["recvReduceCopy<br/>step n-1"]
    end
    AllReduce -.->|"拆解"| AG
    AllReduce -.->|"拆解"| RS

生产踩坑：in-place 判断的边界

📎 src/device/all_gather.h:55 的 in-place 判断 inputBuf + dataOffset == outputBuf + offset 依赖指针精确相等。如果用户传入的 sendbuff 和 recvbuff 有偏移但逻辑上是同一块内存，这个判断会失效，导致走 directCopySend 路径——虽然正确但多一次拷贝。生产环境建议 in-place AllGather 时确保 sendbuff 和 recvbuff 完全一致。

10.4 CollNet 与 NVLS：把归约卸载到硬件

直觉模型：让「交换机」帮忙算

Ring 和 Tree 都是「GPU 自己算归约」。CollNet 和 NVLS 换了个思路：把归约操作卸载到网卡（CollNet）或 NVLink 交换机（NVLS）上。GPU 只负责把数据发出去，硬件完成归约后再广播回来。这就像从「每个工人自己混合原料」变成「把原料送到中央搅拌机，搅拌机混好再分发」。

若没有硬件卸载，归约操作会占用 GPU 的 SM 资源，且归约延迟无法隐藏。

CollNet Direct 的线程分工

RunWorkColl<ncclFuncAllReduce, ..., NCCL_ALGO_COLLNET_DIRECT, ...> 的 run（📎 src/device/all_reduce.h:249-386）把线程分成四组：

const int nThreadsScatter = WARP_SIZE + ((hasUp && hasDn) ? COLLNET_COPY_THREADS : ...);
const int nThreadsGather = ((hasUp && hasDn) ? COLLNET_COPY_THREADS : ...);
const int nThreadsBcast = WARP_SIZE + ((hasUp && hasDn) ? COLLNET_COPY_THREADS : ...);
const int nThreadsReduce = work->nWarps * WARP_SIZE - nThreadsScatter - nThreadsGather - nThreadsBcast;

四组线程分别负责：Scatter（把数据分散到各 rail）、Reduce（归约后发给网络）、Gather（从各 rail 收集）、Bcast（从网络收到后广播）。COLLNET_COPY_THREADS = 96（📎 src/device/all_reduce.h:250）是固定的拷贝线程数。

netRegUsed：网络注册模式下的缓冲区布局

📎 src/device/all_reduce.h:280-288 有个关键分支：

if (work->netRegUsed) {
  offsetBase = bid * chunkSize;
  maxNelems = size;
  peerOffset = nChannels * chunkSize;
} else {
  offsetBase = bid * direct->nHeads * chunkSize;
  maxNelems = direct->nHeads * chunkSize;
  peerOffset = chunkSize;
}

netRegUsed 模式下，缓冲区按 channel 连续排列（bid * chunkSize），peer 偏移是 nChannels * chunkSize；非注册模式下，按 head 排列（bid * nHeads * chunkSize），peer 偏移是 chunkSize。这个差异源于网络注册模式要求缓冲区连续，以便网卡 DMA。

NVLS 的 warp 分配

RunWorkColl<ncclFuncAllReduce, ..., NCCL_ALGO_NVLS, ...> 的 run（📎 src/device/all_reduce.h:391-523）用更精细的 warp 分配：

const int bcastWarps = hasOut ? (work->regUsed ? ((totalWarps - 2) >> 1) - 1 : 2) : 0;
const int reduceWarps = work->regUsed ? (totalWarps - bcastWarps - 2) : (hasOut ? 3 : nranks <= 6 ? 7 : 5);
const int scatterWarps = work->regUsed ? 1 : (totalWarps - reduceWarps - bcastWarps + 1) >> 1;
const int gatherWarps = work->regUsed ? 1 : (totalWarps - reduceWarps - bcastWarps) >> 1;

regUsed 模式下，scatter/gather 各只占 1 warp（因为 NVLS 硬件直接操作注册内存），reduce 占大头；非注册模式下，scatter/gather 各占约一半，reduce 根据 rank 数调整（≤6 用 7 warp，否则 5 warp）。

时序交互图

sequenceDiagram
    participant App as 应用层
    participant Scatter as Scatter Warps
    participant NVLS as NVLS 硬件
    participant Reduce as Reduce Warps
    participant Bcast as Bcast Warps

    App->>Scatter: prims.scatter(offset, nelem, chunkSize)
    Scatter->>NVLS: 写入 NVLink SHARP 缓冲区
    NVLS->>NVLS: 硬件归约 (multimem)
    NVLS->>Reduce: prims.directRecvDirectSend(offset, nelem)
    Reduce->>NVLS: 归约结果写回
    NVLS->>Bcast: prims.directRecvDirectSend(offset, nelem)
    Bcast->>App: 广播到所有 rank

生产踩坑：CollNet 的 direct->out == -1 陷阱

📎 src/device/reduce_scatter.h:521 有一行：

if (direct->out == -1) __trap();

如果 CollNet 的 out 连接未建立（-1），直接 __trap() 让 kernel 崩溃。这是防御性编程——CollNet 依赖网卡，如果网卡初始化失败，out 会是 -1，此时继续执行会导致未定义行为。生产环境如果看到 kernel trap，检查 CollNet 网卡是否正常初始化。

10.5 Broadcast 与 Reduce：最简单的两个集合操作

Broadcast：从 root 扇出

broadcast.h 的 runRing（📎 src/device/broadcast.h:14-64）逻辑很直接：root 节点发数据，其他节点转发，最后一个节点只收。

if (rank == root) {
  if (inputBuf == outputBuf || isNetOffload) {
    prims.directSend(offset, offset, nelem);
  } else {
    prims.directCopySend(offset, offset, nelem);
  }
} else if (nextRank == root) {
  prims.directRecv(offset, nelem);
} else {
  prims.directRecvCopyDirectSend(offset, offset, nelem);
}

三个分支：root 发、root 的前驱收、中间节点转发。注意 nextRank == root 判断的是「本节点的下一个是 root」，即本节点是环上最后一个——它只收不发。

Reduce：向 root 汇聚

reduce.h 的 runRing（📎 src/device/reduce.h:14-53）是 Broadcast 的逆操作：

if (prevRank == root) {
  prims.send(offset, nelem);
} else if (rank == root) {
  prims.recvReduceCopy(offset, offset, nelem, /*postOp=*/true);
} else {
  prims.recvReduceSend(offset, nelem);
}

prevRank == root 的节点只发（它是 root 的前驱），root 只收并归约，中间节点边收边归约边转发。

设计思考：为什么 Broadcast/Reduce 也用 Ring

Broadcast 和 Reduce 理论上可以用 Tree 实现更低延迟，但 NCCL 选择 Ring 是因为：这两个操作的数据量通常较小，Ring 的实现更简单，且能复用 AllReduce 的 Ring 代码路径。Tree 的复杂度（根节点选择、线程拆分）在小消息场景下收益不明显。

生产踩坑：Broadcast 的 root 节点带宽瓶颈

Broadcast 的 root 节点要发送全部数据，如果 root 是慢节点，整个 Broadcast 被拖慢。NCCL 的应对是：Broadcast 也支持多 channel，每个 channel 的 root 可以不同。但注意 work->root 是全局的，所有 channel 共享同一个 root——这是 Broadcast 的语义决定的（只有一个源）。生产环境如果 Broadcast 慢，检查 root 节点的网络带宽。

10.6 算法选择矩阵：RunWorkColl 模板特化

所有算法内核通过 RunWorkColl 模板特化注册（📎 src/device/all_reduce.h:228-788）。每个特化对应「函数 × 算法 × 协议」的组合：

注意：CollNet 和 NVLS 只支持 SIMPLE 协议。因为这两种算法依赖硬件卸载，而 LL/LL128 的低延迟同步机制与硬件卸载不兼容——硬件归约的延迟远大于 LL 的 flag 轮询，用 LL 反而增加开销。

协议选择的内在逻辑

• LL：小消息（< 8KB），低延迟优先。Ring 和 Tree 都支持。
• LL128：中等消息（8KB - 1MB），128 字节对齐。Ring 和 Tree 都支持。
• SIMPLE：大消息（> 1MB），带宽优先。所有算法都支持。

生产踩坑：协议与算法的组合限制

如果用户强制指定 NCCL_PROTO=LL 但算法是 CollNet，NCCL 会在 tuning 阶段回退到 SIMPLE。生产环境如果发现协议设置不生效，检查算法是否支持该协议。

设计思考：为什么同一份 AllReduce 逻辑需要这么多实现

回顾本章，AllReduce 有 Ring、Tree、CollNet Direct、CollNet Chain、NVLS、NVLS Tree 六种算法实现。这不是冗余，而是针对不同硬件拓扑和消息大小的最优解：

• Ring：通用，适合大消息，带宽利用率最高。
• Tree：适合大规模集群，延迟 O(log n)。
• CollNet：适合有支持归约的网卡的集群，卸载 GPU 计算。
• NVLS：适合单节点 NVLink 全连接，硬件多播归约。

NCCL 的 tuning 模块（第 5 章）会根据消息大小、rank 数、拓扑自动选择。设备侧的实现只需要保证「每种组合都正确」，选择逻辑在 host 侧。

本章小结

本章拆解了 src/device 下的六个算法内核文件：

1. Ring AllReduce（📎 src/device/all_reduce.h:14-83）：两阶段流水，reduce-scatter + all-gather，每阶段 n-1 步。

2. Tree AllReduce（📎 src/device/all_reduce.h:86-225）：树形归约，延迟 O(log n)，runTreeSplit 用线程拆分实现归约-广播流水。

3. AllGather（📎 src/device/all_gather.h:14-88）：Ring 单阶段，支持 in-place 和 netOffload。

4. ReduceScatter（📎 src/device/reduce_scatter.h:14-56）：Ring 单阶段，是 AllReduce 的 reduce-scatter 阶段。

5. Broadcast/Reduce（📎 src/device/broadcast.h:14-64、📎 src/device/reduce.h:14-53）：最简单的 Ring 变体。

6. CollNet/NVLS（📎 src/device/all_reduce.h:247-635）：硬件卸载，只支持 SIMPLE 协议。

本章思考与自测

<details><summary>Q1: 在 Ring AllReduce 的 reduce-scatter 阶段，第 0 步用 directSend，中间步用 directRecvReduceDirectSend，最后一步用 directRecvReduceCopyDirectSend。如果去掉最后一步的 postOp=true，在什么场景下会产生错误结果？</summary>

参考解析：postOp=true 触发后置操作（如求平均时的除法）。以 ncclAvg 为例，归约是求和，postOp 是除以 nranks。如果去掉 postOp，最后一步只做归约不做除法，recvbuff 里存的是「和」而非「平均」。在 reduce-scatter 阶段，每个 rank 只保留一个 chunk 的最终结果，这个 chunk 恰好是 ringIx+0（📎 src/device/all_reduce.h:60）。如果 postOp 缺失，这个 chunk 的和没有除以 nranks，后续 all-gather 阶段会把这个错误的「和」传播给所有 rank。注意：只有最后一步需要 postOp，因为只有这一步产生「完整归约」的结果；中间步的归约是部分和，不需要 postOp。生产环境如果发现 AllReduce 结果偏大 nranks 倍，检查 postOp 是否正确传递。

</details>

<details><summary>Q2: runTreeSplit 在 LL/LL128 协议下把线程按 7:3 拆分（📎 src/device/all_reduce.h:163），而 Simple 协议下按 1:1 拆分（📎 src/device/all_reduce.h:157）。如果强行把 LL 协议也改成 1:1，会发生什么？</summary>

参考解析：LL/LL128 的归约组要从最多 3 个子节点收数据并做归约（📎 src/device/all_reduce.h:187 的 FanAsymmetric<NCCL_MAX_TREE_ARITY, 1>），计算密集；广播组只做复制转发（📎 src/device/all_reduce.h:208 的 FanAsymmetric<1, NCCL_MAX_TREE_ARITY>），计算轻。7:3 拆分让归约组有足够线程处理 3 路归约，广播组线程少但够用。如果改成 1:1，归约组线程不足，归约成为瓶颈；广播组线程过剩，浪费。更严重的是，LL 协议的 flag 轮询是忙等待，线程多了会增加 flag 竞争。生产环境如果发现 Tree AllReduce 在 LL 协议下性能异常，检查 nthreadsSplit 的计算是否被修改。

</details>

<details><summary>Q3: AllGather 的 isNetOffload 模式下，只用 1 个 warp 驱动 Ring 通信（📎 src/device/all_gather.h:32），其余 warp 并行拷贝（📎 src/device/all_gather.h:76-82）。如果去掉最后的 barrier_sync(14, nthreads)（📎 src/device/all_gather.h:87），在什么场景下会导致数据竞争？</summary>

参考解析：barrier_sync 保证所有 warp（包括通信 warp 和拷贝 warp）都完成本 work 后才进入下一个 work。如果去掉，通信 warp 可能在拷贝 warp 还没写完 outputBuf 时就开始下一个 work 的通信，而下一个 work 可能复用同一块 outputBuf。具体场景：连续两次 AllGather，第一次的拷贝 warp 还在写 outputBuf 的尾部，第二次的通信 warp 已经开始往 outputBuf 写新数据，导致第一次的数据被覆盖。注释里说得很清楚：「otherwise, we can have contention if next work will use the outputBuf in this work」。用 barrier 14 而非默认 barrier，是为了避开 prims 内部的 barrier 和 __syncthreads()，防止死锁。生产环境如果发现 AllGather 结果偶发错误，检查 isNetOffload 路径的 barrier 是否被优化掉。

</details>

至此，我们已经看完了设备侧算法内核如何组织数据流。每种算法都通过 Primitives 调用上一章的原语，算法层只关心「谁发给谁、发哪个 chunk、归约还是复制」。下一章将深入传输层抽象，看 P2P、SHM、NET、NVLS 如何统一成一套接口，以及 host 侧的 proxy 线程如何与设备侧 kernel 协作完成跨机通信。

核心规律：所有算法都通过 Primitives 模板类调用原语，算法只负责「数据流拓扑」，原语负责「数据搬运」。这种分层让新增算法只需实现拓扑逻辑，无需关心底层同步。但无论拓扑如何变化，数据最终都要通过物理链路传输。下一章将深入 src/transport 目录，看 NCCL 如何用统一的 transport 接口屏蔽 P2P、SHM、NET、NVLS 的差异，以及每种 transport 的 setup/connect/send/recv 语义。这是理解跨机通信的基础。

第 11 章：传输层抽象：P2P、SHM、NET、NVLS 如何统一在同一套接口下

上一章我们深入算法内核，看到 Ring AllReduce 如何将数据切分后两阶段归约，Tree AllReduce 又如何借助树形结构压低延迟——但这些算法只定义了「谁发给谁、发哪个 chunk」的逻辑视图。数据最终必须穿过真实的物理链路：NVLink、PCIe、共享内存或网卡。本章拆解 src/transport 目录，看 NCCL 如何用一套统一的 ncclTransport 接口，把 P2P、SHM、NET、NVLS 四种物理通道屏蔽成同一副面孔，完成从算法拓扑到物理传输的最后一公里。

一、统一接口：ncclTransport 如何屏蔽四种物理通道

直觉模型

想象一家物流公司：无论客户寄的是同城快递（P2P）、楼内传递（SHM）、跨省运输（NET）还是专线直达（NVLS），前台只填一张「运单」。这张运单就是 ncclTransport 结构体——它规定了每种运输方式必须提供 canConnect、setup、connect、free 等固定动作。若没有这层抽象，上层算法就得写四套 if-else 判断走哪条链路，新增一种硬件就要改遍所有算法。

数据结构与内存布局

NCCL 用一个全局数组登记所有 transport，顺序即优先级：

📎 src/transport.cc:15-20

struct ncclTransport* ncclTransports[NTRANSPORTS] = {
  &p2pTransport,
  &shmTransport,
  &netTransport,
  &collNetTransport,
};

数组顺序决定选择顺序：P2P 优先，其次 SHM，再次 NET，最后 CollNet。每种 transport 由 ncclTransport 结构体描述，它包含一个 canConnect 函数指针和两个 ncclTransportComm（send/recv 各一个）。以 P2P 为例：

📎 src/transport/p2p.cc:1493-1498

struct ncclTransport p2pTransport = {"P2P",
                                     p2pCanConnect,
                                     {p2pSendSetup, p2pSendConnect, p2pSendFree, NULL, p2pSendProxySetup, NULL,
                                      p2pSendProxyFree, NULL, p2pProxyRegister, p2pProxyDeregister},
                                     {p2pRecvSetup, p2pRecvConnect, p2pRecvFree, NULL, p2pRecvProxySetup, NULL,
                                      p2pRecvProxyFree, NULL, p2pProxyRegister, p2pProxyDeregister}};

ncclTransportComm 的字段顺序是固定的「生命周期槽位」：setup（准备资源）、connect（交换连接信息）、free（释放）、proxySharedInit（代理共享初始化）、proxySetup、proxyConnect、proxyFree、proxyProgress、proxyRegister、proxyDeregister。注意 P2P 的 proxyProgress 槽位是 NULL——因为 P2P 走的是 GPU 直接读写对端显存，不需要 host 代理线程搬运数据；而 NET 的 proxyProgress 是 sendProxyProgress/recvProxyProgress，因为网卡 I/O 必须由 host 线程驱动。

场景驱动 Walkthrough：一次连接如何选中 transport

当 NCCL 需要为某个 channel 的某个 peer 建立连接时，调用 selectTransport：

📎 src/transport.cc:23-44

template <int type>
static ncclResult_t selectTransport(struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclConnect* connect,
                                    int channelId, int peer, int connIndex, int* transportType) {
  struct ncclPeerInfo* myInfo = comm->peerInfo + comm->rank;
  struct ncclPeerInfo* peerInfo = comm->peerInfo + peer;
  struct ncclConnector* connector = (type == 1) ? comm->channels[channelId].peers[peer]->send + connIndex :
                                                  comm->channels[channelId].peers[peer]->recv + connIndex;
  for (int t = 0; t < NTRANSPORTS; t++) {
    struct ncclTransport* transport = ncclTransports[t];
    struct ncclTransportComm* transportComm = type == 1 ? &transport->send : &transport->recv;
    int ret = 0;
    NCCLCHECK(transport->canConnect(&ret, comm, graph, myInfo, peerInfo));
    if (ret) {
      connector->transportComm = transportComm;
      NCCLCHECK(transportComm->setup(comm, graph, myInfo, peerInfo, connect, connector, channelId, connIndex));
      if (transportType) *transportType = t;
      return ncclSuccess;
    }
  }
  WARN("No transport found for rank %d[%lx] -> rank %d[%lx]", myInfo->rank, myInfo->busId, peerInfo->rank,
       peerInfo->busId);
  return ncclSystemError;
}

type==1 表示 send 方向，type==0 表示 recv 方向。循环依次询问每种 transport 的 canConnect：返回 ret=1 表示「我能干这活」，立刻把 connector->transportComm 指向该 transport 的对应方向，并调用其 setup。若所有 transport 都返回 0，打印警告并返回 ncclSystemError。

canConnect 的判定逻辑体现了各 transport 的「领地边界」。以 P2P 为例：

📎 src/transport/p2p.cc:129-157

ncclResult_t p2pCanConnect(int* ret, struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo* info1,
                           struct ncclPeerInfo* info2) {
  initCeOperation();
  int intermediateRank;
  int isCrossClique;
  NCCLCHECK(ncclTopoCheckP2p(comm, comm->topo, info1->rank, info2->rank, ret, NULL, &intermediateRank, NULL,
                             &isCrossClique));
  if (*ret == 0) return ncclSuccess;
  if (intermediateRank != -1) {
    if (useMemcpy) *ret = 0;
    return ncclSuccess;
  }
  if (!isCrossClique) {
    int useNet = 0;
    NCCLCHECK(ncclTopoCheckNet(comm->topo, info1->rank, info2->rank, &useNet));
    if (useNet) {
      *ret = 0;
      return ncclSuccess;
    }
  }
  if (info1->hostHash != comm->peerInfo[comm->rank].hostHash || info1->hostHash != info2->hostHash) {
    return ncclSuccess;
  }
  ...

P2P 的判定链：先问拓扑「两个 rank 之间有没有 P2P 路径」；如果有中间跳（intermediateRank != -1）且启用了 CE memcpy，则放弃 P2P 让给 SHM/NET；如果拓扑建议走网络（useNet），也放弃；最后检查是否同主机。SHM 的判定更简单：

📎 src/transport/shm.cc:61-83

static ncclResult_t shmCanConnect(int* ret, struct ncclComm* comm, struct ncclTopoGraph* graph,
                                  struct ncclPeerInfo* info1, struct ncclPeerInfo* info2) {
  *ret = 0;
  initShmLocality();
  if (ncclParamShmDisable() == 1) return ncclSuccess;
  int useNet = 0;
  NCCLCHECK(ncclTopoCheckNet(comm->topo, info1->rank, info2->rank, &useNet));
  if (useNet) return ncclSuccess;
  if (info1->hostHash != info2->hostHash) return ncclSuccess;
  if (info1->shmDev != info2->shmDev) return ncclSuccess;
  *ret = 1;
  return ncclSuccess;
}

SHM 要求同主机（hostHash 相同）且共享同一块 /dev/shm（shmDev 相同，用于容器间通信）。NET 则几乎总是返回 1，只在同主机时检查 intra-node net 是否被禁用：

📎 src/transport/net.cc:160-168

static ncclResult_t canConnect(int* ret, struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo* info1,
                               struct ncclPeerInfo* info2) {
  *ret = 1;
  if (info1->hostHash == info2->hostHash) {
    NCCLCHECK(ncclTopoCheckNet(comm->topo, info1->rank, info2->rank, ret));
  }
  return ncclSuccess;
}

NET 是「兜底」——只要前面没人接，它就接。NVLS 的 canConnect 直接返回 0：

📎 src/transport/nvls.cc:21-26

ncclResult_t nvlsCanConnect(int* ret, struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo* info1,
                            struct ncclPeerInfo* info2) {
  // This transport cannot be used for p2p
  *ret = 0;
  return ncclSuccess;
}

NVLS 不走常规的 peer-to-peer 连接路径，它通过 ncclNvlsSetup 单独建立多播组，所以 canConnect 永远返回 0。

flowchart TD
    start["selectTransport(comm, peer, connIndex)"] --> loop{"遍历 ncclTransports[t]"}
    loop -->|t=0| p2p["p2pCanConnect()"]
    p2p --> p2p_chk{"拓扑有P2P路径<br/>且非中间跳<br/>且同主机?"}
    p2p_chk -->|是| use_p2p["connector->transportComm = p2pTransport<br/>调用 p2pSendSetup/p2pRecvSetup"]
    p2p_chk -->|否| shm["shmCanConnect()"]
    shm --> shm_chk{"同hostHash<br/>且同shmDev?"}
    shm_chk -->|是| use_shm["connector->transportComm = shmTransport<br/>调用 shmSendSetup/shmRecvSetup"]
    shm_chk -->|否| net["canConnect() (NET)"]
    net --> net_chk{"同主机时<br/>intra-node net 启用?"}
    net_chk -->|是/跨机| use_net["connector->transportComm = netTransport<br/>调用 sendSetup/recvSetup"]
    net_chk -->|否| collnet["collNetTransport"]
    collnet --> fail["WARN: No transport found<br/>return ncclSystemError"]
    use_p2p --> done["return ncclSuccess"]
    use_shm --> done
    use_net --> done

设计思考

二、P2P：同机 GPU 直连的四种形态

直觉模型

P2P 是「邻居之间直接递东西」——GPU 0 直接读写 GPU 1 的显存，不经过 CPU 或网卡。若没有 P2P，同机多卡通信就得绕道 host 内存，延迟翻倍、带宽腰斩。

数据结构与内存布局

P2P 内部有四种形态，由 enum p2pType 区分：

📎 src/transport/p2p.cc:19-24

enum p2pType {
  P2P_DIRECT,
  P2P_INTERMEDIATE,
  P2P_IPC,
  P2P_CUMEM
};

• P2P_DIRECT：同进程内不同 GPU，直接用指针访问（最快）。
• P2P_INTERMEDIATE：两 GPU 之间没有直连，需经中间 GPU 转发。
• P2P_IPC：跨进程，用传统 cudaIpcOpenMemHandle 导入对端显存。
• P2P_CUMEM：跨进程，用 cuMem API（cuMemExportToShareableHandle）导入，支持更细粒度的内存管理。

核心资源结构体：

📎 src/transport/p2p.cc:79-94

struct p2pResources {
  enum p2pType type;
  union {
    struct ncclSendMem* sendDevMem;
    struct ncclRecvMem* recvDevMem;
  };
  void* sendMemIpc;
  int sendMemSameProc;
  void* recvMemIpc;
  int recvMemSameProc;
  // CE memcpy support
  struct p2pShmProxyInfo proxyInfo;
  struct p2pShm* shm;
  struct p2pShm* devShm;
  ncclShmIpcDesc_t desc;
};

sendDevMem/recvDevMem 是 union——发送方只关心 sendDevMem，接收方只关心 recvDevMem，共用一块内存。sendMemIpc/recvMemIpc 保存导入的对端内存句柄，sendMemSameProc/recvMemSameProc 标记是否同进程（决定释放时用 ncclCuMemFreeAddr 还是 cudaIpcCloseMemHandle）。

连接信息结构体 p2pConnectInfo 通过 bootstrap 交换：

📎 src/transport/p2p.cc:38-44

struct p2pConnectInfo {
  int rank;
  int read;
  struct ncclP2pBuff p2pBuff;
  // Used by CE memcpy
  ncclShmIpcDesc_t desc;
};
static_assert(sizeof(struct p2pConnectInfo) <= CONNECT_SIZE, "p2pConnectInfo is too large");

static_assert 保证连接信息不超过 CONNECT_SIZE（bootstrap 单次交换的固定缓冲区大小）。read 字段决定数据流向：read=1 表示接收方主动读发送方显存（P2P Read），read=0 表示发送方主动写接收方显存（P2P Write）。

场景驱动 Walkthrough：P2P Send 的建立

当 selectTransport 选中 P2P 后，调用 p2pSendSetup：

📎 src/transport/p2p.cc:393-471

ncclResult_t p2pSendSetup(struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo* myInfo,
                          struct ncclPeerInfo* peerInfo, struct ncclConnect* connectInfo, struct ncclConnector* send,
                          int channelId, int connIndex) {
  struct p2pResources* resources;
  struct ncclP2pRequest req;
  NCCLCHECK(ncclCalloc(&resources, 1));
  send->transportResources = resources;
  int useRead, intermediateRank;
  NCCLCHECK(p2pGetInfo(comm, myInfo, peerInfo, &useRead, &intermediateRank));
  if (useMemcpy) useRead = 0;
  ...
  int sendSize = sizeof(struct ncclSendMem);
  if (info->read) sendSize += comm->buffSizes[NCCL_PROTO_SIMPLE];
  ALIGN_SIZE(sendSize, CUDA_IPC_MIN);
  ...

关键点：sendSize 在 P2P Read 模式下要额外加上 SIMPLE 协议缓冲区大小——因为读模式下发送方的 SIMPLE buffer 被接收方直接读取，必须和 ncclSendMem 一起分配在同一块可共享内存里。ALIGN_SIZE(sendSize, CUDA_IPC_MIN) 保证大小对齐到 CUDA IPC 最小粒度。

接着根据 intermediateRank 和进程关系选择形态：

📎 src/transport/p2p.cc:416-437

  if (intermediateRank == -1) {
    info->rank = myInfo->rank;
    if (P2P_SAME_PID(myInfo, peerInfo) && ncclParamP2pDirectDisable() == 0 && useMemcpy == 0) {
      resources->type = P2P_DIRECT;
      ...
    } else {
      if (ncclCuMemEnable()) {
        resources->type = P2P_CUMEM;
        ...
      } else {
        resources->type = P2P_IPC;
        ...
      }
    }
    send->conn.flags |= info->read ? NCCL_P2P_READ : NCCL_P2P_WRITE;
  } else {
    resources->type = P2P_INTERMEDIATE;
    info->rank = intermediateRank;
    ...
  }

P2P_SAME_PID 宏判断同主机同进程：

📎 src/transport/p2p.cc:334-335

#define P2P_SAME_PID(MYINFO, PEERINFO) \
  ((MYINFO->hostHash == PEERINFO->hostHash) && (MYINFO->pidHash == PEERINFO->pidHash))

同进程且未禁用 direct 且未启用 memcpy，就是最快的 P2P_DIRECT——直接拿对端指针。否则走 IPC/CUMEM。

随后通过代理线程分配可共享缓冲区：

📎 src/transport/p2p.cc:457-468

  NCCLCHECK(ncclProxyConnect(comm, TRANSPORT_P2P, 1, info->rank, &send->proxyConn));
  if (useMemcpy) {
    NCCLCHECK(ncclProxyCallBlocking(comm, &send->proxyConn, ncclProxyMsgSetup, NULL, 0, &resources->proxyInfo,
                                    sizeof(struct p2pShmProxyInfo)));
    memcpy(&info->desc, &resources->proxyInfo.desc, sizeof(ncclShmIpcDesc_t));
  } else {
    NCCLCHECK(ncclProxyCallBlocking(comm, &send->proxyConn, ncclProxyMsgSetup, &req, sizeof(struct ncclP2pRequest),
                                    &info->p2pBuff, sizeof(struct ncclP2pBuff)));
    NCCLCHECK(p2pMap(comm, &send->proxyConn, myInfo, comm->peerInfo + info->rank, &info->p2pBuff,
                     (void**)&resources->sendDevMem, &resources->sendMemIpc));
    resources->sendMemSameProc = P2P_SAME_PID(myInfo, (comm->peerInfo + info->rank));
  }

ncclProxyCallBlocking 是同步 RPC：host 线程发消息给代理线程，代理线程调用 p2pSendProxySetup 分配可共享缓冲区，把 ncclP2pBuff（含 IPC 句柄）回传。然后 p2pMap 把对端缓冲区映射到本地地址空间。

p2pMap 是核心映射函数：

📎 src/transport/p2p.cc:349-390

static ncclResult_t p2pMap(struct ncclComm* comm, struct ncclProxyConnector* proxyConn, struct ncclPeerInfo* myInfo,
                           struct ncclPeerInfo* peerInfo, struct ncclP2pBuff* p2pBuff, void** devMem, void** ipcPtr) {
  if (P2P_SAME_PID(myInfo, peerInfo)) {
    if (peerInfo->cudaDev != myInfo->cudaDev) {
      cudaError_t err = cudaDeviceEnablePeerAccess(peerInfo->cudaDev, 0);
      ...
      if (ncclCuMemEnable()) {
        NCCLCHECK(ncclCuMemAllocAddr(devMem, &p2pBuff->ipcDesc.memHandle, p2pBuff->size));
        CUCHECK(cuMemRelease(p2pBuff->ipcDesc.memHandle));
        *ipcPtr = *devMem;
        ...
      } else {
        *devMem = p2pBuff->directPtr;
        *ipcPtr = NULL;
      }
    } else {
      *devMem = p2pBuff->directPtr;
      *ipcPtr = NULL;
    }
  } else {
    NCCLCHECK(ncclP2pImportShareableBuffer(comm, peerInfo->rank, p2pBuff->size, &p2pBuff->ipcDesc, devMem,
                                           p2pBuff->directPtr, ncclMemOffload));
    *ipcPtr = *devMem;
  }
  return ncclSuccess;
}

同进程不同 GPU：先 cudaDeviceEnablePeerAccess 打开 P2P 通道，然后直接用 directPtr（因为同进程地址空间共享）。跨进程：调用 ncclP2pImportShareableBuffer 导入对端内存句柄。

并发控制与硬件交互

P2P 的同步靠 ncclSendMem/ncclRecvMem 里的 head/tail 指针。发送方写 head 告诉接收方「我写到哪了」，接收方写 tail 告诉发送方「我读到哪了」。这是典型的无锁生产者-消费者：

📎 src/transport/p2p.cc:571-576

  } else {
    send->conn.tail = &remDevMem->tail;
    send->conn.head = &resources->sendDevMem->head;
    send->conn.ptrExchange = &resources->sendDevMem->ptrExchange;
    send->conn.redOpArgExchange = resources->sendDevMem->redOpArgExchange;
  }

head 指向本地 sendDevMem，tail 指向对端 remDevMem。GPU kernel 通过读写这两个指针实现跨 GPU 同步，无需 CPU 介入。

生产避坑指南

坑 1：P2P Read 与 memcpy 互斥。 看 p2pSendConnect：

📎 src/transport/p2p.cc:551-559

  for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) {
    if (info->read && p == NCCL_PROTO_SIMPLE) {
      /* For P2P Read the SIMPLE buffer is local (ncclSendMem) */
      if (resources->sendDevMem == NULL) return ncclInternalError; // We should not use read + memcpy
      send->conn.buffs[p] = (char*)(resources->sendDevMem + 1);
    } else {
      send->conn.buffs[p] = buff;
      buff += comm->buffSizes[p];
    }
  }

如果 read=1 但 sendDevMem==NULL，直接返回 ncclInternalError。生产环境若看到这个错误，检查是否同时设置了 NCCL_P2P_READ_ENABLE=1 和 NCCL_P2P_USE_CUDA_MEMCPY=1——这两者语义冲突。

坑 2：跨进程释放顺序。 p2pSendFree 根据 sendMemSameProc 决定释放方式：

📎 src/transport/p2p.cc:624-651

ncclResult_t p2pSendFree(struct ncclComm* comm, struct ncclConnector* send) {
  struct p2pResources* resources = (struct p2pResources*)send->transportResources;
  if (resources) {
    if (ncclCuMemEnable()) {
      if (resources->sendMemIpc) {
        if (resources->sendMemSameProc) {
          NCCLCHECK(ncclCuMemFreeAddr(resources->sendMemIpc, comm->memManager));
        } else {
          NCCLCHECK(ncclCudaFree(resources->sendMemIpc, comm->memManager));
        }
      }
      ...

同进程用 ncclCuMemFreeAddr（只释放地址映射，不释放物理内存），跨进程用 ncclCudaFree（释放物理内存）。搞反会导致内存泄漏或 use-after-free。

三、SHM：共享内存的「谁出内存」之争

直觉模型

SHM 是「两个进程共用一块白板」——发送方写，接收方读。但白板放谁家？放发送方家（sender-side），接收方跑过来读；还是放接收方家（receiver-side），发送方跑过去写？这就是 NCCL_SHM_LOCALITY 参数要解决的问题。

数据结构与内存布局

📎 src/transport/shm.cc:28-34

struct shmSendResources {
  struct ncclRecvMem* remHostMem;
  struct ncclRecvMem* devRemHostMem;
  ncclShmIpcDesc_t remDesc;
  struct ncclSendMem* hostMem;
  struct ncclSendMem* devHostMem;
};

struct shmRecvResources {
  struct ncclSendMem* remHostMem;
  struct ncclSendMem* devRemHostMem;
  ncclShmIpcDesc_t remDesc;
  struct ncclRecvMem* hostMem;
  struct ncclRecvMem* devHostMem;
};

注意 hostMem 和 devHostMem 成对出现：hostMem 是 host 侧指针，devHostMem 是设备侧指针（通过 UVA 或 cuMem 映射）。remHostMem/devRemHostMem 是对端共享内存的本地映射。

场景驱动 Walkthrough：SHM 的 locality 选择

shmSendSetup 根据 locality 决定分配多大内存：

📎 src/transport/shm.cc:88-119

static ncclResult_t shmSendSetup(struct ncclComm* comm, struct ncclTopoGraph* graph, struct ncclPeerInfo* myInfo,
                                 struct ncclPeerInfo* peerInfo, struct ncclConnect* connectInfo,
                                 struct ncclConnector* send, int channelId, int connIndex) {
  struct shmSendResources* resources;
  struct shmConnectInfo* info = (struct shmConnectInfo*)connectInfo;
  size_t shmSize = sizeof(struct ncclSendMem);
  struct shmRequest req;

  NCCLCHECK(ncclCalloc(&resources, 1));
  send->transportResources = resources;

  if (shmLocality == SHM_SEND_SIDE) {
    for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) shmSize += comm->buffSizes[p];
  }
  req.size = shmSize;
  if (myInfo->hostHash == peerInfo->hostHash && myInfo->pidHash == peerInfo->pidHash) req.legacy = true;
  else req.legacy = false;

  NCCLCHECK(ncclProxyConnect(comm, TRANSPORT_SHM, 1, myInfo->rank, &send->proxyConn));
  NCCLCHECK(ncclProxyCallBlocking(comm, &send->proxyConn, ncclProxyMsgSetup, (void*)&req, sizeof(struct shmRequest),
                                  (void*)info, sizeof(struct shmConnectInfo)));

  info->rank = comm->rank;
  resources->hostMem = (struct ncclSendMem*)info->buf.hptr;
  resources->devHostMem = (struct ncclSendMem*)info->buf.dptr;
  ...

shmLocality == SHM_SEND_SIDE 时，发送方分配数据缓冲区（shmSize 加上所有协议缓冲区）；否则只分配 ncclSendMem 控制结构。req.legacy 标记是否同进程——同进程可以用传统 mmap，跨进程需要 cuMem 或 /dev/shm 文件。

shmSendConnect 里根据 locality 决定 buffs 指向本地还是对端：

📎 src/transport/shm.cc:153-176

static ncclResult_t shmSendConnect(struct ncclComm* comm, struct ncclConnect* connectInfo, int nranks, int rank,
                                   struct ncclConnector* send) {
  struct shmConnectInfo* info = (struct shmConnectInfo*)connectInfo;
  struct shmSendResources* resources = (struct shmSendResources*)send->transportResources;
  char* buff;

  NCCLCHECK(ncclShmImportShareableBuffer(comm, info->rank, &info->desc, (void**)&resources->remHostMem,
                                         (void**)&resources->devRemHostMem, &resources->remDesc));

  buff = shmLocality == SHM_SEND_SIDE ? (char*)(resources->devHostMem + 1) : (char*)(resources->devRemHostMem + 1);
  for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) {
    send->conn.buffs[p] = buff;
    buff += comm->buffSizes[p];
  }
  send->conn.tail = &resources->devRemHostMem->tail;
  send->conn.head = &resources->devHostMem->head;
  send->conn.stepSize = comm->buffSizes[NCCL_PROTO_SIMPLE] / NCCL_STEPS;
  ...

SHM_SEND_SIDE：buffs 指向本地 devHostMem（发送方写自己的内存）；SHM_RECV_SIDE：buffs 指向对端 devRemHostMem（发送方写接收方的内存）。head 永远指向本地，tail 永远指向对端——因为发送方更新 head，接收方更新 tail。

设计思考

生产避坑指南

坑：容器间 /dev/shm 不共享。 shmCanConnect 检查 info1->shmDev != info2->shmDev：

📎 src/transport/shm.cc:76-78

  TRACE(NCCL_INIT | NCCL_SHM, "peer1 shmDev %lx peer2 shmDev %lx", info1->shmDev, info2->shmDev);
  if (info1->shmDev != info2->shmDev) return ncclSuccess;

如果两个容器挂载了不同的 /dev/shm，shmDev 不同，SHM 自动降级到 NET。生产环境若发现同主机通信却走了网络，检查容器的 /dev/shm 挂载是否一致。

四、NET：网络传输的映射表与代理进度

直觉模型

NET 是「跨城快递」——数据打包交给网卡，网卡通过光纤送到对端。但网卡不认识 GPU 显存地址，需要一张「地址映射表」把 GPU 虚拟地址翻译成网卡能理解的物理地址。这张表就是 connectMap。

数据结构与内存布局

📎 src/transport/net.cc:73-86

struct connectMapMem {
  char* gpuPtr;
  char* cpuPtr;
  ssize_t size;
  ncclIpcDesc ipcDesc;
  ncclShmIpcDesc_t attachDesc;
  ncclShmIpcDesc_t createDesc;
};

struct connectMap {
  int sameProcess;
  int shared;
  int cudaDev;
  // First 3 bits of offsets determine the mem bank. 001 is host mem, 011 is dev mem, 101 is shared host mem and 111
  // is shared dev mem.
  struct connectMapMem mems[NCCL_NET_MAP_MEMS];
  // Offsets. 3 MSBs indicate mem bank, 111 indicates NULL.
  struct {
    uint32_t sendMem;
    uint32_t recvMem;
    uint32_t buffs[NCCL_NUM_PROTOCOLS];
  } offsets;
};

connectMap 是一个「内存银行」系统：mems 数组有 5 个槽位（NCCL_NET_MAP_MEMS=5），分别对应 host mem、dev mem、shared host mem、shared dev mem、GDC mem。offsets 里的每个字段是一个 32 位整数，高 3 位编码「哪个银行」，低 29 位编码「银行内偏移」。

解码宏：

📎 src/transport/net.cc:36-46

#define NCCL_NET_MAP_OFFSET_BANK(mapStruct, offsetName) ((mapStruct)->offsets.offsetName >> 30)

#define NCCL_NET_MAP_OFFSET_NULL(mapStruct, offsetName) (((mapStruct)->offsets.offsetName >> 29) == 0)

#define NCCL_NET_MAP_GET_POINTER(mapStruct, cpuOrGpu, offsetName) \
  (NCCL_NET_MAP_OFFSET_NULL(mapStruct, offsetName) ? \
     NULL : \
     (mapStruct)->mems[NCCL_NET_MAP_OFFSET_BANK(mapStruct, offsetName)].cpuOrGpu##Ptr + \
       ((mapStruct)->offsets.offsetName & NCCL_NET_MAP_MASK_OFFSET))

#define NCCL_NET_MAP_DEV_MEM(mapStruct, offsetName) (((mapStruct)->offsets.offsetName & NCCL_NET_MAP_MASK_DEVMEM) != 0)

NCCL_NET_MAP_GET_POINTER(map, gpu, sendMem) 展开后：取 offsets.sendMem 的高 2 位作为 bank 索引，从 mems[bank].gpuPtr 加上低 29 位偏移，得到实际指针。这套编码把「哪个内存区域 + 区域内偏移」压缩进一个 32 位整数，节省了 connectMap 的传输大小。

场景驱动 Walkthrough：sendProxyConnect 的映射建立

sendProxyConnect 是 NET 最复杂的函数，负责建立网卡连接、分配缓冲区、注册内存：

📎 src/transport/net.cc:858-1041

static ncclResult_t sendProxyConnect(struct ncclProxyConnection* connection, struct ncclProxyState* proxyState,
                                     void* reqBuff, int reqSize, void* respBuff, int respSize, int* done) {
  struct sendNetResources* resources = (struct sendNetResources*)(connection->transportResources);
  ...
  if (resources->shared) {
    // Shared buffers
    ...
    if (resources->maxRecvs > 1 && ncclParamNetSharedComms()) {
      // Connect or reuse connection for a netdev/remote rank.
      ...
      if (comms->sendComm[resources->channelId] == NULL &&
          comms->activeConnect[resources->channelId] == (resources->tpLocalRank + 1)) {
        ret = proxyState->ncclNet->connect(proxyState->netContext, resources->netDev, req->handle,
                                           comms->sendComm + resources->channelId, &resources->netDeviceHandle);
      }
      ...

maxRecvs > 1 时启用「共享连接」：多个 channel 复用同一个网卡连接，减少连接数。activeConnect 数组保证只有一个 local rank 发起连接，避免重复。

接着分配缓冲区并注册：

📎 src/transport/net.cc:933-956

  if (resources->shared == 0) {
    // Only allocate dedicated buffers for ring/tree, not for p2p
    for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) {
      NCCL_NET_MAP_ADD_POINTER(map, 0, p != NCCL_PROTO_LL && resources->useGdr ? 1 : 0, proxyState->buffSizes[p],
                               buffs[p]);
      resources->buffSizes[p] = proxyState->buffSizes[p];
    }
  } else {
    // Get shared buffers
    int bank = resources->useGdr ? NCCL_NET_MAP_SHARED_DEVMEM : NCCL_NET_MAP_SHARED_HOSTMEM;
    struct connectMapMem* mapMem = map->mems + bank;
    NCCLCHECK(sharedNetBuffersInit(proxyState, resources->useGdr, resources->tpLocalRank, 0, map->sameProcess,
                                   proxyState->p2pnChannels, &mapMem->gpuPtr, &mapMem->cpuPtr, &mapMem->size,
                                   &mapMem->ipcDesc));
    resources->buffSizes[NCCL_PROTO_SIMPLE] = mapMem->size;
    ...

NCCL_NET_MAP_ADD_POINTER 宏把缓冲区登记到 connectMap：

📎 src/transport/net.cc:48-62

#define NCCL_NET_MAP_ADD_POINTER(mapStruct, shared, dev, memSize, offsetName) \
  do { \
    int bank = NCCL_NET_MAP_MASK_USED + (dev) * NCCL_NET_MAP_MASK_DEVMEM + (shared) * NCCL_NET_MAP_MASK_SHARED; \
    if ((shared) == 0) { \
      if (dev) { \
        (mapStruct)->offsets.offsetName = bank + (mapStruct)->mems[NCCL_NET_MAP_DEVMEM].size; \
        (mapStruct)->mems[NCCL_NET_MAP_DEVMEM].size += memSize; \
      } else { \
        (mapStruct)->offsets.offsetName = bank + (mapStruct)->mems[NCCL_NET_MAP_HOSTMEM].size; \
        (mapStruct)->mems[NCCL_NET_MAP_HOSTMEM].size += memSize; \
      } \
    } else { \
      (mapStruct)->offsets.offsetName = bank; \
    } \
  } while (0);

非共享缓冲区：把当前 bank 的 size 作为偏移写入 offsets，然后 size += memSize——这是 bump allocator。共享缓冲区：直接写 bank 编号，偏移为 0（因为共享缓冲区整块就是一个 bank）。

最后注册内存给网卡：

📎 src/transport/net.cc:1004-1035

  for (int p = 0; p < NCCL_NUM_PROTOCOLS; p++) {
    resources->buffers[p] = NCCL_NET_MAP_GET_POINTER(map, cpu, buffs[p]);
    if (resources->buffers[p]) {
#if CUDA_VERSION >= 11070
      int type = NCCL_NET_MAP_DEV_MEM(map, buffs[p]) ? NCCL_PTR_CUDA : NCCL_PTR_HOST;
      if (type == NCCL_PTR_CUDA && resources->useDmaBuf) {
        int dmabuf_fd;
        size_t dmaBufSize = resources->buffSizes[p];
        ALIGN_SIZE(dmaBufSize, ncclOsGetPageSize());
        CUCHECK(cuMemGetHandleForAddressRange((void*)&dmabuf_fd, (CUdeviceptr)resources->buffers[p], dmaBufSize,
                                              CU_MEM_RANGE_HANDLE_TYPE_DMA_BUF_FD,
                                              getHandleForAddressRangeFlags(resources->useGdr)));
        NCCLCHECK(proxyState->ncclNet->regMrDmaBuf(resources->netSendComm, resources->buffers[p],
                                                   resources->buffSizes[p], type, 0ULL, dmabuf_fd,
                                                   &resources->mhandles[p]));
        (void)close(dmabuf_fd);
      } else
#endif
      {
        NCCLCHECK(proxyState->ncclNet->regMr(resources->netSendComm, resources->buffers[p], resources->buffSizes[p],
                                             NCCL_NET_MAP_DEV_MEM(map, buffs[p]) ? NCCL_PTR_CUDA : NCCL_PTR_HOST,
                                             &resources->mhandles[p]));
      }
      ...

优先走 DMA-BUF 路径（cuMemGetHandleForAddressRange 拿到 fd，传给网卡插件），失败则回退到 regMr（传统 nv_peermem GDR）。

并发控制与硬件交互：sendProxyProgress 的三段式流水线

sendProxyProgress 是 NET 的数据搬运引擎，采用「post → transmit → done」三段式：

📎 src/transport/net.cc:1324-1491

static ncclResult_t sendProxyProgress(struct ncclProxyState* proxyState, struct ncclProxyArgs* args) {
  ...
  if (args->state == ncclProxyOpProgress) {
    int p = args->protocol;
    int maxDepth = std::min(NCCL_STEPS, NCCL_SHARED_STEPS / args->nsubs);
    for (int s = 0; s < args->nsubs; s++) {
      struct ncclProxySubArgs* sub = args->subs + s;
      ...
      // Post buffers to the GPU
      if (sub->posted < sub->nsteps && sub->posted < sub->done + maxDepth) {
        ...
        if (resources->shared) {
          ...
          volatile uint64_t* sendHead = resources->gdcSync ? resources->gdcSync : &resources->sendMem->head;
          sub->posted += args->sliceSteps;
          *sendHead = sub->base + sub->posted - NCCL_STEPS;
          if (resources->gdcSync) wc_store_fence(); // Flush out WC write
        } else {
          sub->posted += args->sliceSteps;
        }
        ...
        continue;
      }
      // Check whether we received data from the GPU and send it to the network
      if (sub->transmitted < sub->posted && sub->transmitted < sub->done + NCCL_STEPS) {
        ...
        if (connFifo[buffSlot].size != -1 && (*recvTail > tail || p == NCCL_PROTO_LL)) {
          ...
          if (ready) {
            ...
            NCCLCHECK(proxyState->ncclNet->isend(resources->netSendComm, buff, size, resources->tpRank,
                                                 sub->sendMhandle, phandle, sub->requests + buffSlot));
            ...

• post：代理线程更新 sendMem->head，告诉 GPU「缓冲区已就绪，可以写数据」。
• transmit：检查 recvMem->tail 是否推进（GPU 已写完），检查 connFifo[buffSlot].size != -1（数据大小已填），然后调用 ncclNet->isend 发起异步发送。
• done：调用 ncclNet->test 检查发送完成，更新 sendMem->head 归还缓冲区。

wc_store_fence() 是写合并屏障——GDRCopy 场景下，CPU 写 gdcSync 后必须刷新写合并缓冲区，否则 GPU 看不到更新。

生产避坑指南

坑 1：LL128 协议的 flag 校验。 当数据在 sysmem（非 GDR）时，代理线程必须逐行检查 LL128 flag：

📎 src/transport/net.cc:1388-1403

          if (p == NCCL_PROTO_LL128) {
            ready = resources->useGdr;
            if (!ready) {
              uint64_t flag = sub->base + sub->transmitted + 1;
              int nFifoLines = DIVUP(connFifo[buffSlot].size, sizeof(uint64_t) * NCCL_LL128_LINEELEMS);
              volatile uint64_t* lines = (volatile uint64_t*)buff;
              ready = 1;
              for (int i = 0; i < nFifoLines; i++) {
                if (lines[i * NCCL_LL128_LINEELEMS + NCCL_LL128_DATAELEMS] != flag) {
                  ready = 0;
                  break;
                }
              }
            }
          }

因为 GPU 只调用了 threadfence()，数据可能还在 L2 缓存里没落到 sysmem。代理线程必须确认每一行的 flag 都正确，才能发送。生产环境若发现 LL128 数据损坏，检查 useGdr 是否正确——GDR 路径下数据直接落显存，不需要逐行校验。

坑 2：GDRCopy flush 的内存序。 接收侧在 recvProxyProgress 里有一段精妙的内联汇编：

📎 src/transport/net.cc:1664-1682

          if (totalSize > 0 && p == NCCL_PROTO_SIMPLE && needFlush) {
            struct recvNetResources* resources = (struct recvNetResources*)(subGroup->connection->transportResources);
            if (resources->gdcFlush) {
#if defined(__x86_64__)
              asm volatile("mfence" ::: "memory");
              asm volatile("mov (%0), %%eax" ::"l"(resources->gdcFlush) : "%eax", "memory");
#else
              std::atomic_thread_fence(std::memory_order_seq_cst);
              uint64_t dummy;
              NCCLCHECK(ncclGdrCudaRead(resources->gdrDesc, &dummy, resources->gdcFlush, sizeof(dummy)));
#endif
            }

mfence 保证 CQE poll 的读不会重排到 flush 读之前；mov (%0), %%eax 强制发起一次 PCIe 读，让 CPU 停顿直到所有先前的 PCIe posted write（包括网卡 DMA）都提交。这是 GDRCopy 场景下防止「网卡说写完了但数据还在 PCIe 缓冲区」的关键。去掉这段，接收方可能读到旧数据。

sequenceDiagram
    participant GPU as GPU Kernel
    participant SM as ncclSendMem
    participant Proxy as sendProxyProgress
    participant NIC as ncclNet->isend
    participant Peer as 对端网卡

    GPU->>SM: 写数据到 buffs[p]
    GPU->>SM: 更新 recvMem->tail
    Proxy->>SM: 读 recvTail, connFifo[buffSlot].size
    Proxy->>Proxy: 检查 ready (LL128 flag / GDR)
    Proxy->>NIC: isend(comm, buff, size, mhandle)
    NIC->>Peer: DMA 发送
    Proxy->>NIC: test(request, &done)
    NIC-->>Proxy: done=1
    Proxy->>SM: 更新 sendMem->head (归还缓冲区)
    Proxy->>GPU: 下一轮 post

五、NVLS：多播组与 UC/MC 内存绑定

直觉模型

NVLS 是「广播电台」——一个 rank 把数据写到多播组，硬件自动复制给所有订阅者。传统 AllReduce 需要 N-1 次点对点传输，NVLS 只需 1 次多播写 + 1 次多播读。若没有 NVLS，大规模 AllReduce 的延迟随 rank 数线性增长。

数据结构与内存布局

NVLS 的核心是「UC（单播）内存」和「MC（多播）内存」的绑定。nvlsAllocBindUc 分配 UC 内存并绑定到 MC 组：

📎 src/transport/nvls.cc:225-277

static ncclResult_t nvlsAllocBindUc(struct ncclComm* comm, const struct ncclMcPartition* partition, size_t size,
                                    struct ncclNvlsUcSegment* outUc) {
  CUmemAllocationProp ucprop;
  ...
  ucprop.type = CU_MEM_ALLOCATION_TYPE_PINNED;
  ucprop.location.type = CU_MEM_LOCATION_TYPE_DEVICE;
  ucprop.location.id = comm->cudaDev;
  ucprop.requestedHandleTypes = ncclCuMemHandleType;
  CUCHECKGOTO(cuMemGetAllocationGranularity(&ucgran, &ucprop, CU_MEM_ALLOC_GRANULARITY_RECOMMENDED), ret, fail);
  ALIGN_SIZE(ucsize, ucgran);
  CUCHECKGOTO(cuMemAddressReserve((CUdeviceptr*)&ucptr, ucsize, ucgran, 0U, 0), ret, fail);
  CUCHECKGOTO(cuMemCreate(&ucHandle, ucsize, &ucprop, 0), ret, fail1);
  CUCHECKGOTO(cuMemMap((CUdeviceptr)ucptr, ucsize, 0, ucHandle, 0), ret, fail2);
  CUCHECKGOTO(cuMemSetAccess((CUdeviceptr)ucptr, ucsize, &comm->nvlsResources->accessDesc, 1), ret, fail3);
  CUDACHECKGOTO(cudaMemset(ucptr, 0, ucsize), ret, fail3);
  NCCLCHECKGOTO(ncclMemTrack(comm->memManager, ucptr, ucsize, ucHandle, ncclCuMemHandleType, ncclMemPersist), ret,
                fail3);
  NCCLCHECKGOTO(bootstrapIntraNodeBarrier(comm->bootstrap, comm->localRankToRank, comm->localRank, comm->localRanks,
                                          comm->localRankToRank[0]),
                ret, fail3);
  NCCLCHECKGOTO(ncclMcPartitionBindMem(partition, 0 /*offsetInPartition*/, ucHandle, 0 /*memOffset*/, ucsize), ret,
                fail3);
  ...

流程：cuMemCreate 分配物理内存 → cuMemMap 映射到虚拟地址 → cuMemSetAccess 设置 GPU 访问权限 → ncclMcPartitionBindMem 把 UC 物理内存绑定到 MC 组的指定偏移。绑定后，任何 rank 写 MC 地址，硬件会把数据复制到所有绑定的 UC 内存。

注意 bootstrapIntraNodeBarrier 在 cuMulticastBindMem 之前——注释说这是为了「mitigate the possible hang in cuMulticastBindMem during abort」。这是硬件层面的防御：如果某个 rank 在绑定过程中 abort，其他 rank 可能在 cuMulticastBindMem 里挂起。

场景驱动 Walkthrough：ncclNvlsBufferSetup 的缓冲区布局

📎 src/transport/nvls.cc:279-368

ncclResult_t ncclNvlsBufferSetup(struct ncclComm* comm) {
  ...
  nvlsStepSize = comm->nvlsChunkSize;
  buffSize = nvlsStepSize * NCCL_STEPS;
  nvlsPerRankSize = nChannels * 2 * buffSize;
  nvlsTotalSize = nvlsPerRankSize * nHeads;
  ...
  if (resources->dataUc.ptr == NULL) {
    NCCLCHECKGOTO(nvlsAllocBindUc(comm, &resources->dataPartition, nvlsTotalSize, &resources->dataUc), res, fail);
  }
  ...
  for (int h = 0; h < nHeads; h++) {
    int nvlsPeer = comm->nRanks + 1 + h;
    for (int c = 0; c < nChannels; c++) {
      struct ncclChannel* channel = comm->channels + c;
      struct ncclChannelPeer* peer = channel->peers[nvlsPeer];

      // Reduce UC -> MC
      peer->send[1].conn.buffs[NCCL_PROTO_SIMPLE] = (char*)resources->dataUc.ptr + (h * 2 * nChannels + c) * buffSize;
      peer->recv[0].conn.buffs[NCCL_PROTO_SIMPLE] =
        (char*)resources->dataPartition.ptr + (h * 2 * nChannels + c) * buffSize;

      // Broadcast MC -> UC
      peer->recv[1].conn.buffs[NCCL_PROTO_SIMPLE] =
        (char*)resources->dataUc.ptr + ((h * 2 + 1) * nChannels + c) * buffSize;
      peer->send[0].conn.buffs[NCCL_PROTO_SIMPLE] =
        (char*)resources->dataPartition.ptr + ((h * 2 + 1) * nChannels + c) * buffSize;
      ...

缓冲区布局：每个 head 有 2 * nChannels 个 buffer（一半用于 reduce，一半用于 broadcast）。send[1] 和 recv[0] 是 reduce 方向（UC → MC），recv[1] 和 send[0] 是 broadcast 方向（MC → UC）。dataUc.ptr 是本地 UC 内存，dataPartition.ptr 是 MC 组映射地址。

设计思考

生产避坑指南

坑：MNNVL 不支持 NVLS buffer 注册。 看 ncclNvlsSetup：

至此，NCCL 通过 ncclTransport 抽象层，成功将 P2P、SHM、NET、NVLS 四种异构通道统一为一致的接口，算法内核无需关心底层是 NVLink 还是网卡。但传输层只解决了「通道如何抽象」，尚未回答「数据如何被异步驱动」。下一章我们将聚焦 src/proxy.cc 与 src/include/proxy.h，看 proxy 线程如何在 host 侧异步推进网络收发，与 GPU kernel 形成生产者-消费者关系，揭开 NCCL 异步性的关键机制。

第 12 章：代理线程异步调度：proxy.cc 如何解耦 I/O 与 kernel 执行

上一章拆解了 transport 抽象层，看到 NCCL 如何用统一接口屏蔽 P2P/SHM/NET/NVLS 的差异。但传输层只回答了「数据走哪条通道」，尚未回答「数据如何被异步驱动」。GPU kernel 若直接阻塞在网络等待上，计算单元就会被 I/O 拖死。本章聚焦 src/proxy.cc 与 src/include/proxy.h，看 NCCL 如何用独立的 host 线程把网络 I/O 从 kernel 执行路径中剥离出来，与 GPU 形成生产者-消费者关系。

12.1 为什么需要代理线程：从「谁等网络」说起

直觉模型

想象一家餐厅：厨房（GPU kernel）只负责做菜，传菜员（proxy 线程）负责把菜端给客人（网络对端）。如果让厨师亲自端菜，他每端一趟就得停下炒菜，出餐速度暴跌。NCCL 的 proxy 就是那个专职传菜员——kernel 只管往共享缓冲区里写数据、从缓冲区里读数据，网络收发的脏活累活全交给 host 侧的 proxy 线程。

两类线程的分工

NCCL 在 host 侧启动了两类 proxy 线程，职责截然不同：

• Service 线程（ncclProxyService）：处理控制面请求——连接建立、内存注册、FD 查询。它监听一个 socket，接收来自本地 rank 的 RPC 请求，异步推进 setup/connect 等操作。
• Progress 线程（ncclProxyProgress）：处理数据面——真正驱动网络收发。它从共享内存池里取 proxy op，调用 transport 的 proxyProgress 回调推进数据搬运。

📎 src/include/proxy.h:343-345 显示 ncclProxyState 同时持有 thread（Service）和 threadUDS（UDS 服务），而 Progress 线程的句柄藏在 progressState.thread 里 📎 src/include/proxy.h:261-261。

生产者-消费者关系的建立

📎 src/proxy.cc:2130-2166 的 ncclProxyCreate 是线程诞生的地方：当 refCount == 1（首个 comm 创建）时，它把 comm 的关键字段拷贝进 proxyState，然后启动 Service 线程和 UDS 线程。注意 Progress 线程不在这里启动——它由 proxyProgressInit 在首次需要 proxy progress 的连接建立时才懒启动 📎 src/proxy.cc:1523-1524。

flowchart TD
    create["ncclProxyCreate(comm)"] --> check_ref{"proxyState->refCount == 1?"}
    check_ref -->|否| skip["复用已有线程，直接返回"]
    check_ref -->|是| copy["拷贝 comm 字段到 proxyState"]
    copy --> start_svc["std::thread(ncclProxyService)"]
    start_svc --> start_uds["std::thread(ncclProxyServiceUDS)"]
    start_uds --> wait["等待连接建立请求"]
    wait --> conn_init{"proxyConnInit 发现<br/>tcomm->proxyProgress != NULL?"}
    conn_init -->|是| prog_init["proxyProgressInit()"]
    conn_init -->|否| no_prog["不启动 Progress 线程"]
    prog_init --> shm["ncclShmOpen 创建 opsPool 共享内存"]
    shm --> start_prog["std::thread(ncclProxyProgress)"]

这张图锚定了线程启动的真实分支：只有 tcomm->proxyProgress 非空（即该 transport 需要数据面推进）时，Progress 线程才会被创建。

12.2 数据结构与内存布局：共享内存池与 op 池

核心结构体全景

proxy 的并发模型建立在两块共享内存之上，理解它们的内存布局是理解整个机制的前提。

第一块：ncclProxyOpsPool（📎 src/include/proxy.h:218-226）。这是主线程与 Progress 线程之间的「任务投递箱」，通过 /dev/shm 跨进程共享。

MAX_OPS_PER_PEER 的定义 📎 src/include/proxy.h:218-226 是 2 * MAXCHANNELS * 2 * NCCL_MAX_DEV_WORK_P2P_PER_BATCH。注释解释了为什么是 2 倍：每个 p2p work 包含一个 send 和一个 recv proxy op，所以要乘 2；再乘 2 是为了能存两轮完整操作，否则无法「投递一半、释放一半」。

第二块：ncclProxyArgs（📎 src/include/proxy.h:174-209）。这是 Progress 线程内部使用的「运行时 op 描述」，从 ncclProxyPool 里分配，不跨进程共享。

关键字段：

• subs[NCCL_PROXY_MAX_SUBS]：子操作数组，NCCL_PROXY_MAX_SUBS = MAXCHANNELS 📎 src/include/proxy.h:55-55。多个 channel 的同类操作会被聚合到一个 args 的多个 sub 里。
• progress：函数指针，指向 transport 的 proxyProgress 回调 📎 src/include/proxy.h:176-176。
• next / nextPeer / proxyAppendPtr：三根链表指针，构成复杂的 op 组织关系。
• state：ncclProxyOpNone / ncclProxyOpReady / ncclProxyOpProgress 三态 📎 src/include/proxy.h:48-52。

内存池的分层设计

ncclProxyPool 📎 src/proxy.cc:50-53 是一个批量分配单元，每个 pool 含 PROXYARGS_ALLOCATE_SIZE（即 NCCL_MAX_OPS）个 ncclProxyArgs。allocateArgs 📎 src/proxy.cc:207-231 的分配逻辑值得细看：

if (state->pool == NULL) {
    struct ncclProxyPool* newPool;
    NCCLCHECK(ncclCalloc(&newPool, 1));
    struct ncclProxyArgs* newElems = newPool->elems;
    for (int i = 0; i < PROXYARGS_ALLOCATE_SIZE; i++) {
      if (i + 1 < PROXYARGS_ALLOCATE_SIZE) newElems[i].next = newElems + i + 1;
    }
    state->pool = newElems;
    newPool->next = state->pools;
    state->pools = newPool;
}
elem = state->pool;
state->pool = state->pool->next;

📎 src/proxy.cc:207-231

伪共享与原子变量

ncclProxyOpsPool 里的 nextOps、nextOpsEnd、freeOps[] 都是 volatile int。它们被主线程和 Progress 线程同时读写，但 NCCL 没有用锁保护所有访问——而是用原子操作 + 内存序来保证正确性。

看 ncclLocalOpAppend 里从 freeOps 取空闲 op 的逻辑 📎 src/proxy.cc:503-513：

int freeOp = -1;
while (freeOp == -1) {
  freeOp = COMPILER_ATOMIC_EXCHANGE(&pool->freeOps[tpLocalRank], -1, std::memory_order_acquire);
  if (freeOp == -1) std::this_thread::yield();
}

主线程用 atomic_exchange 把 freeOps[tpLocalRank] 置为 -1 并取回旧值——这是一个「抢占式取用」：谁先 exchange 成功谁拿到整条空闲链表。Progress 线程归还 op 时用 CAS 循环 📎 src/proxy.cc:898-907：

oldFree = COMPILER_ATOMIC_LOAD(&pool->freeOps[i], std::memory_order_acquire);
do {
  pool->ops[freeOpEnd[i]].next = oldFree;
} while (!COMPILER_ATOMIC_COMPARE_EXCHANGE(&pool->freeOps[i], &oldFree, newFree,
                                           std::memory_order_release,
                                           std::memory_order_acquire));

12.3 控制面：连接建立与 RPC 机制

直觉模型

RPC 请求的编码

ncclProxyCallAsync 📎 src/proxy.cc:1369-1394 是 RPC 的发送端。它通过 socket 依次发送：type、connection 指针、reqSize、respSize、reqBuff、opId。