제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구조체를 할당하고 필드별로 채웁니다. 이 흐름을 따라가며 주요 필드가 어떻게 설정되는지 살펴보겠습니다:

1단계: 할당 및 초기화

NCCL은ncclCalloc를 사용하여ncclComm를 할당하고 모든 필드가 0으로 초기화되도록 합니다. 이때startMagic와endMagic는NCCL_MAGIC（📎 src/include/comm.h:563-569로 설정됩니다(0x0280028002800280는

로 정의되며, 주석에는 "Nickel atomic number is 28"이라고 되어 있습니다).

rank、nRanks、cudaDev2단계: 신원 정보 채우기commHash는 매개변수와 CUDA API에서 가져옵니다.ncclCommId는

를 해시하여 얻으며, 이후 네트워크 통신에서 일관성 검증에 사용됩니다.

3단계: 토폴로지 그래프 구축topoNCCL은 토폴로지 탐지 모듈을 호출하여 모든 GPU, NIC, PCI 스위치를 열거하고📎 src/include/comm.h:595-595필드(

)를 구축합니다. 이 토폴로지 그래프가 이후 알고리즘 선택과 경로 계획을 결정합니다.

channels[MAXCHANNELS]4단계: 채널 초기화id배열이 하나씩 초기화됩니다. 각 채널의peers는 배열 인덱스로 설정되고,devPeers와

포인터가 할당됩니다.

5단계: 전송 연결 설정setup토폴로지 그래프에 따라 NCCL은 각 rank 쌍에 대해 전송 계층(P2P/SHM/NET)을 선택하고 해당connect와channels[i].peers[j]콜백을 호출합니다. 연결 정보는

에 저장됩니다.

6단계: 매직 넘버 설정endMagic마지막으로,NCCL_MAGIC가

로 설정되어 구조체 초기화가 완료되었음을 표시합니다.

설계 고찰과 실무 함정ncclComm왜

는 거의 300개의 필드를 포함하는데, 이는 하나의 통신 도메인의 전체 상태를 담고 있기 때문입니다. NCCL의 설계 철학은 '한 번 초기화, 여러 번 재사용'입니다——초기화 시 사용 가능한 모든 정보를 미리 계산하여 저장하고, 런타임에는 테이블을 직접 조회하여 반복 계산을 피합니다. 대가는 메모리 사용량이 다소 크다는 것(통신 도메인당 약 몇 KB)이지만, GPU 메모리와 네트워크 대역폭에 비하면 이 정도 메모리는 미미합니다.

등을 호출하면 필드 경쟁이 발생하여 데이터가 손상됩니다. 올바른 방법은 각 스레드가 독립적인 통신 도메인을 사용하거나 외부 잠금으로 호출을 직렬화하는 것입니다.

ncclCommDestroy함정 시나리오 2: 파괴 후 접근startMagic가 구조체 메모리를 해제한 후에도 스레드가 포인터를 보유하고 접근하면 해제된 메모리를 읽게 됩니다.endMagic와

는 이러한 상황을 감지하는 데 도움이 됩니다——매직 넘버가 일치하지 않으면 포인터가 무효화되었음을 의미합니다.

함정 시나리오 3: 캐시 라인 거짓 공유intraBarrierCounter다중 프로세스 시나리오(프로세스당 하나의 rank)에서intraBarrierGate와

의 패딩은 특히 중요합니다. 패딩을 생략하면 여러 프로세스의 배리어 작업이 서로 간섭하여 동기화 지연이 나노초 수준에서 마이크로초 수준으로 증가합니다.

2.2 채널 channel: 하나의 통신을 여러 파이프라인으로 분할

직관적 모델channelNCCL의 「컨베이어 벨트」——집합 통신 한 번의 데이터를 여러 조각으로 나누고, 각 채널이 독립적으로 한 조각을 운반하며 병렬로 진행하여 대역폭 활용률을 높인다.

채널이 없으면 모든 데이터가 단 하나의 경로로만 흐를 수 있어, GPU 간의 여러 물리 링크(여러 NIC, 여러 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조각으로 나뉘고, 각 조각을 하나의 채널이 담당한다.

1단계: 알고리즘 선택

NCCL의 tuning 모듈이 메시지 크기와 토폴로지에 따라 알고리즘(예: Ring)과 프로토콜(예: Simple)을 선택한다.

2단계: 채널 할당

ncclTaskColl구조체(📎 src/include/comm.h:212-273)가 생성되고, 그중nChannels필드가 4로 설정된다(📎 src/include/comm.h:254-254）。channelLo와channelHi필드(📎 src/include/comm.h:256-257)는 해당 작업이 사용하는 채널 범위를 표시한다.

3단계: 데이터 분할

각 채널이count / nChannels개 요소를 담당한다. 채널 0은 0번째부터 count/4-1번째 요소를 처리하고, 채널 1은 count/4번째부터 count/2-1번째 요소를 처리하는 식이다.

4단계: 병렬 실행

4개 채널의 GPU kernel이 동시에 시작되고, 각자 자신의 데이터 슬라이스에서 Ring AllReduce를 수행한다. 채널 간에 데이터 의존성이 없으므로 완전히 병렬로 실행할 수 있다.

5단계: 결과 병합

모든 채널이 완료되면 각 rank의 recv buffer에는 완전한 AllReduce 결과가 담긴다.

동시성 제어와 하드웨어 상호작용

채널과 GPU 리소스의 매핑

채널과 네트워크 디바이스의 매핑

다중 NIC 시나리오에서는 서로 다른 채널을 서로 다른 NIC에 바인딩할 수 있다. 예를 들어 4개 채널, 2개 NIC라면 채널 0과 1은 NIC A를, 채널 2와 3은 NIC B를 사용한다. 이렇게 하면 두 NIC의 대역폭을 모두 활용할 수 있다.

채널 수 선택

• 더 많은 kernel 시작 오버헤드
• 더 많은 연결 설정 오버헤드
• 더 복잡한 동기화

NCCL의 tuning 모듈은 메시지 크기에 따라 최적의 채널 수를 자동으로 선택한다. 작은 메시지는 적은 채널(오버헤드 감소), 큰 메시지는 많은 채널(대역폭 향상)을 사용한다.

프로덕션 함정 회피 가이드

함정 시나리오 1: 채널 수 설정 부적절

함정 시나리오 2: 채널과 토폴로지 불일치

함정 시나리오 3: 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가 공존하는가?

함정 시나리오 1: 알고리즘 선택 오류

함정 시나리오 2: NVLS 하드웨어 미지원

NVLS는 특정 하드웨어 지원(NVLink SHARP)이 필요합니다. 하드웨어가 지원하지 않는데 코드가 NVLS를 강제 사용하면 Ring 또는 Tree로 폴백되지만, 성능 변동이 동반될 수 있습니다.📎 src/include/comm.h:755-755의nvlsSupport필드는 하드웨어가 NVLS를 지원하는지 표시합니다.

함정 시나리오 3: 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 프로토콜의 배치 전송

프로덕션 함정 회피 가이드

함정 시나리오 1: 프로토콜과 메시지 크기 불일치

함정 시나리오 2: LL128 정렬 문제

함정 시나리오 3: 프로토콜 전환 오버헤드

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를 지원하는 NIC
• 올바른 SHARP 구성

프로덕션 함정 회피 가이드

함정 시나리오 1: P2P 사용 불가

함정 시나리오 2: 네트워크 구성 오류

함정 시나리오 3: 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"]

전체 라이프사이클

단계 1: API 호출

사용자가ncclAllReduce을 호출하여, 송신 버퍼, 수신 버퍼, 요소 수, 데이터 타입, 리덕션 연산, 통신 도메인, CUDA stream을 전달합니다.

단계 2: 작업 생성

NCCL이ncclTaskColl구조체를 생성하고(📎 src/include/comm.h:212-273),func（AllReduce）、sendbuff、recvbuff、count、datatype、opHost등의 필드를 채웁니다.

단계 3: 알고리즘 및 프로토콜 선택

Tuning 모듈이 메시지 크기, 토폴로지 구조, 하드웨어 능력에 따라 알고리즘(Ring/Tree/NVLS)과 프로토콜(LL/LL128/Simple)을 선택합니다. 선택 결과는ncclTaskColl의algorithm과protocol필드에 기록됩니다(📎 src/include/comm.h:227-227）。

단계 4: 채널 할당

알고리즘과 프로토콜에 따라 사용할 채널 수와 채널 범위를 결정합니다.nChannels、channelLo、channelHi필드가 설정됩니다(📎 src/include/comm.h:254-257）。

단계 5: 전송 계층 선택

토폴로지 그래프에 따라 각 rank 쌍에 대해 전송 계층(P2P/SHM/NET/CollNet)을 선택합니다. 연결 정보는channels[i].peers[j]에 저장됩니다.

단계 6: Kernel 시작

NCCL이ncclKernelPlan（📎 src/include/comm.h:357-410)을 구축합니다. 여기에는 작업 큐, 정리 큐, 태스크 큐 등이 포함됩니다. 그런 다음 GPU kernel을 시작합니다.

7단계: 통신 실행

GPU kernel이 작업 FIFO를 읽고 데이터 전송 및 리덕션 연산을 수행한다. Proxy 스레드가 비동기적으로 네트워크 I/O를 진행한다.

8단계: 완료

모든 채널이 완료되면,asyncResult이(가) 로 설정된다ncclSuccess. 사용자는ncclCommGetAsyncError을 통해 상태를 조회할 수 있다.

설계 고찰

왜 다섯 가지 세트가 필요한가?

• ncclComm: 「누가 누구와 통신하는가」 문제를 해결한다.
• channel: 「어떻게 병렬화할 것인가」 문제를 해결한다.
• algorithm: 「어떤 토폴로지를 사용할 것인가」 문제를 해결한다.
• protocol: 「어떤 전략을 사용할 것인가」 문제를 해결한다.
• transport: 「어떤 물리적 링크를 사용할 것인가」 문제를 해결한다.

이들은 직교적으로 조합되어, NCCL이 각 조합마다 전용 코드를 작성할 필요 없이 다양한 하드웨어 구성과 메시지 크기에 적응할 수 있게 한다.

조합의 유연성

• 알고리즘: 5가지 (Tree/Ring/CollNet/NVLS/PAT)
• 프로토콜: 3가지 (LL/LL128/Simple)
• 전송 계층: 4가지 (P2P/SHM/NET/CollNet)

이 장의 고찰과 자가 점검

---

다음 장에서는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.send/socket.recv)인 유니온입니다. 이는 두 가지 bootstrap 모드에 대응합니다: 소켓 기반 기본 모드와 네트워크 디바이스 기반NCCL_OOB_NET_ENABLE모드입니다.
• listen: 리스닝 엔드포인트 정보로, 마찬가지로 네트워크와 소켓 두 가지 형태가 있습니다.
• 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을 갖도록 보장합니다.

두 번째 단계: 리스닝 소켓 생성.각 rank는 두 개의 리스닝 엔드포인트가 필요합니다: 하나는 ring 이웃 연결용(STATE_LISTEN(state, socket)), 하나는 root 연결용(listenSockRoot）：

📎 src/bootstrap.cc:797-831

여기에 핵심적인 역할 분담이 있습니다: ring 리스닝 소켓은comm->magic를 사용하고, root 리스닝 소켓은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를 호출하며, 후자는 소켓 모드에서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호출 순서는 고정되어 있다. 매칭되지 않는 연결을 그냥 버리면 송신 측이 타임아웃되고, 블로킹 대기하면 데드락이 발생할 수 있다. 큐에 저장하는 것이 가장 안전한 방법이다.

프로덕션 함정 회피 가이드

함정 1: bootstrap 타임아웃으로 인한 초기화 중단.특정 rank가 네트워크 문제로 root에 연결할 수 없으면, 다른 모든 rank가ncclSocketAccept또는ncclSocketRecv에서 무한 대기하게 된다. NCCL에는 내장된 bootstrap 타임아웃 메커니즘이 없으며, 유일한 탈출 경로는 abortFlag이다. 프로덕션 환경에서는 대규모 클러스터의 연결 폭풍을 완화하기 위해NCCL_UID_STAGGER_RATE를 설정하는 것이 권장된다.

함정 2:NCCL_COMM_ID과 다중 handle 충돌.사용자가NCCL_COMM_ID환경 변수를 설정하면, NCCL은 강제로nId를 1로 낮춘다:

📎 src/init.cc:2912-2921

이는ncclCommInitRankScalable의 다중 handle 기능이 조용히 비활성화됨을 의미한다. scalable 초기화를 사용하면서NCCL_COMM_ID도 설정했다면, 동작이 예상과 다를 것이다.

함정 3: 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 GPU, 프로세스당 하나의 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. getBusIdPCI 버스 ID 가져오기,ncclNvmlDeviceGetHandleByPciBusIdNVML 핸들 가져오기.

8. dmaBufSupportedDMA-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

1단계: AllGather1 — 장치 정보 교환.

📎 src/init.cc:1234-1239

각 rank는fillInfo를 호출하여 자신의ncclPeerInfo를 채우고,bootstrapAllGather를 통해 교환한다.fillInfo에 채워지는 정보에는 rank 번호, CUDA 장치 번호, NVML 장치 번호, NCCL 버전, git hash, 호스트 hash, 프로세스 hash, GPU UUID, 버스 ID, VRAM 크기, 드라이버 버전 등이 포함된다.

📎 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가 노드별로 연속 배치되어 있다고 가정한다.

2단계: 토폴로지 발견.

📎 src/init.cc:1390-1403

이 여섯 단계는 토폴로지 발견의 핵심 흐름이다:ncclTopoGetSystem는 시스템 장치를 열거하여 토폴로지 그래프를 구축하고,ncclTopoComputePaths는 GPU에서 NIC까지의 경로를 계산하며,ncclTopoTrimSystem는 도달 불가능한 장치를 제거하고 경로를 다시 계산하며,ncclTopoSearchInit는 검색 상태를 초기화하고 마지막으로 토폴로지를 출력한다.

3단계: 그래프 계산.

📎 src/init.cc:1421-1468

ring, tree, collnet chain, collnet direct, nvls 다섯 가지 그래프를 순차적으로 계산한다. 각 그래프는 서로 다른 pattern과 채널 수 제약을 가진다. 참고:treeGraph->minChannels = ringGraph->nChannels— tree의 채널 수는 ring과 동일하게 제한되는데, 이는 서로 다른 알고리즘 간의 채널 정렬을 보장하기 위함이다.

4단계: 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은 호환성을 보장하기 위해 합집합을 취해야 하기 때문이다.

5단계: 전송 연결 설정.

📎 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

ncclNvlsInitNVLink SHARP 지원을 감지합니다. NVLS는 스위치가 직접 reduce 작업을 수행할 수 있게 하여 AllReduce 지연을 크게 줄입니다.

Proxy 스레드 생성:

📎 src/init.cc:1780-1786

Proxy 스레드는 네트워크 I/O를 비동기적으로 진행하는 역할을 합니다. 이는initTransportsRank에서 생성되며, 이후 모든 네트워크 작업은 proxy를 통해 이루어집니다.

프로덕션 함정 회피 가이드

함정 1: 네트워크 장치 수 불일치.서로 다른 rank의 로컬 NIC 수가 다르면 NCCL이 오류를 발생시킵니다:

📎 src/init.cc:1576-1596

다음을 설정하지 않는 한NCCL_IGNORE_NET_MISMATCH=1. 이는 이기종 클러스터에서 흔합니다—어떤 노드는 NIC가 8개, 어떤 노드는 4개뿐입니다. 불일치를 무시하면 채널 수가 가장 약한 노드에 의해 제한되므로 성능 저하가 발생할 수 있습니다.

함정 2: 여러 rank가 동일한 GPU를 공유.두 rank의 GPU UUID가 같으면 NCCL이 초기화를 거부합니다:

📎 src/init.cc:1291-1296

다음을 설정하지 않는 한NCCL_MULTI_RANK_GPU_ENABLE=1. 이 검사는 사용자의 잘못된 구성으로 인한 성능 문제를 방지합니다.

함정 3: 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은 "캐시하지 않음"을 나타냅니다. 이 결정은 최초 로드 시 한 번만 이루어지고 이후 변경되지 않습니다.

프로덕션 함정 회피 가이드

함정 1: 환경 변수 철자 오류.사용자가NCCL_BUFSIZE대신NCCL_BUFFSIZE을 쓰면 NCCL은 오류를 내지 않고 기본값을 사용합니다.NCCL_DEBUG=ENV을 사용하여 인식된 모든 환경 변수를 확인하는 것을 권장합니다.

함정 2:NCCL_CONF_FILE의 로딩 순서.NCCL은$NCCL_CONF_FILE(또는~/.nccl.conf)과/etc/nccl.conf：

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

을 순차적으로 로드합니다. 나중에 로드된 파일이 먼저 로드된 것을 덮어씁니다. 두 파일 모두 같은 변수를 설정하면/etc/nccl.conf의 값이 적용됩니다.

함정 3: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 모드에서 사용할 수 없기 때문입니다. 이는 하드웨어 제약에 대한 우아한 성능 저하입니다.

프로덕션 함정 회피 가이드

함정 1:devCommSetup은 반드시 barrier 이전에 호출해야 합니다.소스 코드 주석이 그 이유를 설명합니다:

📎 src/init.cc:1950-1952

barrier 이후에 호출하면, 일부 스레드가 이미 NCCL kernel을 시작했을 수 있고, 이때 디바이스 메모리가 아직 할당되지 않아 데드락이 발생할 수 있습니다.

함정 2:workFifoBytes은 반드시 2의 거듭제곱이어야 합니다.그렇지 않으면 NCCL이 경고를 표시하고 기본값을 사용합니다:

📎 src/init.cc:757-762

이 장의 고찰과 자가 테스트

다음 장에서는 토폴로지 발견과 그래프 탐색을 깊이 다루며, 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가 된다. 둘째, 찾지 못하면 새 링크를 추가한다. 셋째, 삽입 후 대역폭 내림차순으로 정렬하여 이후 순회 시 고대역폭 링크를 우선적으로 보게 한다.

시나리오 기반 단계별 워크스루

이제 구체적인 시나리오를 대입해 보자: 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는 메가비트 per 초이며, 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 스위치의 특수한 경우를 처리한다——이들은 자신을 2계층 스위치로 표현하지만 실제로는 전대역폭이므로, 검색 알고리즘이 오도되지 않도록 "평탄화"해야 한다.ncclTopoConnectCpus는 모든 CPU 노드를 상호 연결한다(크로스 NUMA 접근은 SYS 링크를 통함).ncclTopoSortSystem는 링크를 정렬하여 PCI 다운스트림 링크가 앞에 오도록 하여 순회를 용이하게 한다.

설계 고찰 및 프로덕션 함정

함정 1: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를 확인해야 한다. 이런 설계는 놓치기 쉽다——호출자가 확인을 잊으면 이후 역참조에서 크래시가 발생한다.

함정 2:ncclTopoConnectNodes의 대역폭 누적이 오버플로를 일으킬 수 있다.동일한 노드 쌍 사이에 많은 링크가 있으면(예: NVSwitch 시나리오),link->bw += bw가 매우 크게 누적될 수 있다. float의 정밀도는 충분하지만, 링크 수가 비정상적으로 많으면 정렬 로직에 문제가 생길 수 있다.

함정 3: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)만큼 앞으로 이동한다. 따라서 삭제된 노드 이후 노드를 가리키는 모든 포인터는 1씩 감소해야 한다. 이 작업은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
• 으로 승격됩니다.PATH_PHB
• CPU를 거치면 유형이PATH_NVB

으로 승격됩니다. DEV 노드를 거치고 NVLink이면 유형이

으로 승격됩니다. 업데이트 조건은 "더 나은 경로"입니다: 유형이 더 좋거나, 유형이 같지만 대역폭이 더 높거나, 유형과 대역폭이 같지만 홉 수가 더 적은 경우입니다.

시나리오 기반 단계별 워크스루ncclTopoCompute이제 두 번째 계층 탐색을 살펴봅니다.ncclTopoSearchRec이 진입점이며, 다양한 매개변수 조합을 시도하고

을 호출하여 탐색을 수행합니다.ncclTopoSearchRecGpu탐색의 핵심은 재귀 함수

📎 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이 함수에는 몇 가지 핵심 분기가 있습니다:nChannels: 모든 GPU를 방문하여 완전한 경로가 형성된 경우입니다. 이때ncclTopoSearchRec을 증가시키고, 현재 그래프와 저장된 최적 그래프를 비교하여 더 좋으면 저장합니다. 그런 다음 재귀적으로

2. step == backToNet을 호출하여 다음 channel 탐색을 시도합니다.

3. step < ngpus - 1: 네트워크 카드로 돌아가야 하는 경우입니다. 이는 Ring 모드(마지막 GPU가 시작 네트워크 카드로 연결) 또는 Tree 모드(첫 번째 GPU가 네트워크 카드로 연결)에서 발생합니다.ncclTopoSearchNextGpuSort: 다음 GPU로 계속 진행합니다. 여기서

4. step == backToFirstRank을 호출하여 후보 GPU를 정렬합니다.

5. else: Ring 모드에서 마지막 GPU가 첫 번째 GPU로 연결됩니다.

ncclTopoSearchNextGpuSort: 경로가 끝나고 다음 라운드로 진입합니다.

📎 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)

복사NCCL_SEARCH_TIMEOUT탐색 공간은 지수적입니다—각 channel은 O(ngpus!) 가지 배열을 가집니다. 8카드 머신은 40320가지, 16카드는 2조 가지입니다. 탐색 시간을 제한해야 합니다.NCCL_SEARCH_GLOBAL_TIMEOUT은 16384회 반복,

은 524288회입니다. 타임아웃 후 현재 최적 해를 반환합니다.ncclTopoFollowPath함정 1:의 대역폭 차감은 전역 부작용입니다.

📎 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함정 2:의 비교 로직은 매우 미묘합니다.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;
  ...

왜 짝수 channel을 선호하는가? Ring 알고리즘이 짝수 channel에서 더 잘 페어링될 수 있기 때문입니다—각 channel을 두 halves로 나누어, 절반은 시계 방향, 절반은 반시계 방향으로 하여 네트워크 혼잡을 줄입니다.

Ring과 Tree: 탐색 결과를 알고리즘 토폴로지로 변환

직관적 모델

탐색 알고리즘이 찾는 것은 경로 집합이지만, 알고리즘이 필요로 하는 것은 명확한 "누가 누구에게 보내는가"의 순서입니다. Ring은 모든 rank를 하나의 고리로 연결하여, 각 rank가 이전에서 받고 다음으로 보냅니다. Tree는 트리로, 데이터가 루트에서 아래로 흐르거나 리프에서 위로 모입니다.

이 두 모듈이 없다면, 탐색 알고리즘은 단지 여러 경로를 찾았을 뿐, GPU kernel에게 구체적으로 데이터를 어떻게 보낼지 알려줄 수 없습니다.

데이터 구조와 메모리 레이아웃ncclBuildRingsRing의 구축은

📎 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과rings배열(각 rank의 전임자와 후임자)이며, 출력은next배열(각 channel의 전체 rank 순서)입니다. 현재 rank에서 출발하여

포인터를 따라 한 바퀴 돌며, 시작점으로 돌아오는지 검증하고 모든 rank가 방문되었는지 확인합니다.ncclGetBtreeTree의 구축은

📎 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;
}

복사bit이 함수는 비트 연산으로 이진 트리를 구축합니다. 핵심 아이디어는: rank의 최하위 비트(rank ^ bit) | (bit << 1)를 찾아, 부모 노드는rank - (bit >> 1), 왼쪽 자식은rank + (bit >> 1), 오른쪽 자식은

입니다. 주석의 ASCII 그림이 이 구조를 명확히 보여줍니다.

8개 카드 Ring을 예로 들어보자. 검색 결과가 각 rank의next포인터:

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

ncclBuildRingsrank 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은 리프이다.

설계 고찰과 프로덕션 함정

함정 1:ncclBuildRings의 검증이 건너뛰어질 수 있다.만약next배열에 사이클이 있으면 (예: rank 0 -> rank 1 -> rank 0), 루프는nranks번 반복 후 종료되지만,current != rank검사가 이 문제를 잡아낸다. 하지만 사이클의 길이가 정확히nranks의 약수이고 모든 rank를 포함하지 않으면,rankFound검사가 잡아낸다.

함정 2: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) 恢复带宽

이 타임시퀀스 다이어그램은 검색의 핵심 루프를 보여준다: NIC 선택 -> 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으로 이진 트리를 생성한다.

이 장 사고와 자가 점검

다음 장에서는 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)을, 채널을 몇 개 열고, 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이나 0으로 나누기가 발생하기 쉽다.먼저 방어하고, 그 다음 계산한다는 방어적 프로그래밍의 전형이다.

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은 1차원 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을 2차원 테이블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에 있으며, 전체 장에서 가장 복잡한 부분이므로 5절에서专门 다룬다.

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 내부 버그（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"]

---

2. 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은 1이 아니라 2인가?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을 전부 0으로 초기화(사용자가 화이트리스트를 지정했기 때문):

📎 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를 설정하면,parseListLL을 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]과 사용자 스위치를 AND 연산:

📎 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

---

3. ring.cc: Ring 알고리즘의 비용 추정

직관적 모델

Ring 알고리즘은 N개의 rank를 원형으로 배열하고, 데이터가 원을 따라 한 바퀴씩 전달됨. 그 비용 모델은 두 가지 질문에 답해야 함:각 단계에서 얼마나 많은 데이터를 전송하는가 (대역폭)、총 몇 단계가 필요한가 (지연)。

Ring의 직관은 「파이프라인」: N명이 원형으로 서서 물통을 전달하고, 각자 통을 받으면 물을 조금 붓고 다음 사람에게 전달한다고 상상. 통이 한 바퀴 돌면 모든 사람의 물이 섞임. 통이 빨리 돌수록(대역폭 높음), 원이 작을수록(단계 수 적음), 전체가 빨라짐.

데이터 구조: latency/bandwidth 테이블

Ring 모델은 새로운 구조를 도입하지 않고, 추정 결과를comm->tuningContext.generalLatencies[c][algo][proto]과generalBandwidths[c][algo][proto]에 기록. 이 둘은 3차원 배열: 함수 × 알고리즘 × 프로토콜.

초기화 시 먼저 전부 -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;
  }

왜 0이 아니라 -1.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/128LL128은 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(각 노드에 rank가 1개만 있을 때) 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 단계가 같은 채널 그룹을 사용하는지'를 나타낸다. 다르면 지연에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의 각 채널이 최소 64바이트를 전송해야 하며, 그렇지 않으면 plateau가 성립하지 않는다. 이 64바이트는 LL 프로토콜의 flag 크기에서 온다.

함정 시나리오: Blackwell에서 1MB AllReduce를 실행했는데 실제 지연이 모델 예측보다 40% 높다면 버그라고 생각하지 마라 — 이것은 plateau 효과이며 모델이 이미それを 계산에 넣은 것이다. 만약 수동으로plateauFactor을 줄이면 모델이 지연을 과소평가하여 잘못된 알고리즘을 선택하게 된다.

---

4. tree.cc와 nvls.cc: Tree와 NVLS의 비용 추정

직관적 모델

Tree 알고리즘은 '트리 브로드캐스트'이다: 루트 노드가 데이터를 자식 노드에 나누고, 자식 노드가 다시 손자 노드에 나눈다. 장점은단계 수가 적다(N이 아닌 log 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 수 빼기 1)이고,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가 동기화를 위해 채널 하나를 남겨둬야 하기 때문입니다.(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가 분명히 하드웨어 지원이 되는데 왜 안 쓰지」라고 생각하게 됩니다.

---

5. 대칭 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_PARAMSNVTX 마커를 찍는다(Nsight 등 도구 시각화용)

2.ncclAllReduceConfigImpl을 호출하며,config = nullptr

을 전달한다

3. 결과를 반환한다2단계: ncclAllReduceConfigImpl이 ncclInfo를 생성한다.

📎 src/collectives.cc:192-202

이것이 핵심 단계이다:

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는NCCL_STEPS/2에 정의되어 있다.NCCL_STEPS/4는 링 버퍼의 스텝 수(보통 8 또는 16)이므로, AllReduce의 chunkSteps는

, sliceSteps는 ncclParseCollConfig이다. 이는 하나의 chunk가 2개의 slice를 포함한다는 뜻이다.ncclCollConfig_t*3단계: 사용자 config를 파싱한다.info.collConfig사용자가 전달한config == nullptr을

로 파싱한다. 만약이면, 이 필드는 0으로 초기화된 상태를 유지한다.

4단계: ncclEnqueueCheck에 넘긴다.

는 점이다. 만약 누군가

중간에 필드를 삽입하면, 모든 집합 초기화 지점이 조용히 어긋난다. 이는 NCCL 코드에 내재된 유지보수 위험이다.

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

실제 함정 시나리오: 사용자가 이렇게 코드를 작성한다:ncclInfo복사ncclGroupEnd만약 NCCL이info.collConfig에서 config를 복사하지 않았다면,src/include/info.h:41-43시에 접근할 때 이미 해제된 메모리를 읽게 된다.。

---

의 주석은 바로 이 설계를 설명하기 위한 것이다.

config는 task append 단계에서 파싱되고 복사되며, 이후에는 사용자 포인터에 의존하지 않는다

ncclEnqueueCheck二、ncclEnqueueCheck：参数校验与 group 语义직관적 모델는 enqueue 모듈의 "메인 게이트"이다. 모든 집합 통신 API가 최종적으로 여기로 모인다. 그 역할은:ncclEnqueueCheck。

파라미터 유효성 검증, group 시맨틱 처리, taskAppend 호출로 작업 생성

Step-by-Step: ncclEnqueueCheck의 실행 흐름

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

단계별로 분석해 보겠습니다:

1단계: CommCheck로 통신 도메인 검증. CommCheck(info->comm, info->opName, "comm")comm 포인터가 null이 아닌지, 초기화되었는지 확인합니다. 만약 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 호출이 계속 시도하는 대신 즉시 오류를 반환합니다. 이것이 비동기 오류 전파 메커니즘입니다.

---

3. 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 분배.rmaTaskAppend：

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

PutSignal/Signal/WaitSignal인 경우, if (info->count == 0) return ncclSuccess;호출

4단계: 빈 집합 통신 조기 반환. ncclCollConfigGetAlgMask——count가 0인 집합 통신은 바로 폐기합니다.

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

5단계: 알고리즘 선택 검증.사용자가 전달한 알고리즘 선택이 유효한지 검증합니다:

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

6단계: FP8 타입 검사. hostToDevRedOpFP8 리덕션은 sm90+가 필요합니다:ncclRedOp_t7단계: 리덕션 작업 변환.ncclDevRedOpFull：

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

host 측을 디바이스 측comm->nRanks == 1로 변환ncclLaunchOneRank8단계: 단일 rank 조기 반환.

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

만약이면,

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

을 직접 호출하여 로컬 리덕션을 수행하고, 작업을 생성할 필요가 없습니다:

collTaskAppend9단계: 다중 rank 경로.ncclTaskColl이것이 가장 복잡한 분기로, CE 라우팅, AllToAll/Gather/Scatter 강등, 그리고 일반 집합 통신을 포함합니다:

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

데이터 구조: ncclTaskColl의 필드

설정 파싱trafficBytes리소스 상한

📎 src/enqueue/enqueue.cc:2813

ncclFuncTrafficPerByte알고리즘 선택 마스크

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

주의

계산:

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

은 각 집합 통신의 트래픽 배수를 반환합니다: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는 이 조건을 충족하지 않기 때문입니다.

---

4. ncclPrepareTasks: 작업 목록에서 스케줄링 큐까지

직관적 모델

ncclPrepareTasks은 enqueue 모듈의 "전처리기"입니다. 흩어진 작업 목록을 (func, op, datatype)별로 버킷팅한 다음, 각 버킷에 대해 알고리즘과 프로토콜을 계산합니다. 이는 마치 도서관 사서와 같습니다 — 반납된 책을 먼저 분류별로 정리한 다음, 각 분류의 책을 어느 서가에 놓을지 결정합니다.

이 단계가 없으면 이후의scheduleCollTasksToPlan이 각 작업에 대해 개별적으로 알고리즘을 계산해야 하므로 효율이 매우 낮습니다.

단계별: 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차원 배열의 선형화입니다.

3단계: 집계 및 알고리즘 선택.각 버킷에 대해 크기가 비슷한 작업(4배 이내)을 집계한 다음ncclGetAlgoInfo：

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

을 호출합니다4단계: (collnet, nvls)별 버킷팅.collBins[2][2]：

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

알고리즘 유형에 따라 작업을에 할당합니다planner->collTaskQueue：

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

5단계: 최종 큐 연결.

ncclTaskCollSorter네 개의 버킷을trafficBytes로 연결합니다ncclTaskCollSorterInsert데이터 구조: ncclTaskCollSorterncclTaskCollSorterDequeueAll은

이 정렬기의 설계 동기는:

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

대형 작업 우선 스케줄링comm->runtimeConn. 대형 작업은 전송 시간이 길기 때문에 먼저 시작하면 계산과 통신을 더 잘 중첩할 수 있습니다.algoNeedConnect동시성 제어: runtimeConn과 연결 설정

만약

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

이 참이면(런타임 연결 모드), 그리고 특정 알고리즘의 channel이 아직 초기화되지 않았다면aggEnd->trafficBytes < 4 * aggBeg->trafficBytes을 표시합니다. 이는 이후에 연결 설정을 트리거합니다.aggIsolate프로덕션 함정: 집계의 경계 조건maxCTAs），aggIsolate집계 조건은

이고, 두 작업 모두maxCTAs=4을 설정하지 않아야 합니다. 사용자가 per-call config를 설정하면(예:aggIsolate가 true로 설정됨), 이 작업은 집계되지 않습니다.collTaskAppend실제 함정 시나리오: 사용자가 특정 AllReduce에

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

---

를 설정하여 4개의 CTA만 사용하기를 기대했습니다. 그러나 집계 로직으로 인해 이 작업이 인접 작업과 병합되어 실제 사용되는 CTA 수가 예상과 다를 수 있습니다. 해결책은

을 설정하는 것입니다 — NCCL은

scheduleCollTasksToPlan에서 이미 이를 처리했습니다:

5. scheduleCollTasksToPlan: channel 분할과 예산 제어

직관적 모델

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

은 enqueue 모듈의 "스케줄러"입니다. 작업을 구체적인 channel에 할당하고 각 channel의 데이터 분할을 계산합니다. 이는 공장의 생산 계획 시스템과 같습니다 — 각 생산 라인이 무엇을, 얼마나 만들지 결정합니다.이 단계가 없으면 GPU kernel은 자신이 어느 부분의 데이터를 처리해야 하는지 알 수 없습니다.

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

ncclTestBudget단계별: channel 분할 알고리즘

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

1단계: 예산 추정.먼저 이 plan에 넣을 수 있는 작업 수를 추정합니다:trafficPerChannel：

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

작업 바이트 수가 예산을 초과하는지 확인합니다:2단계: 각 channel의 트래픽 계산.

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

kind(collnet/nvls)에 따라을 계산합니다

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

3단계: Collnet 경로.

• cellSizecollnet 알고리즘이면 channel 할당이 비교적 간단합니다:MinTrafficPerChannel（32KB）
• cells4단계: 일반 경로의 cell 분할.
• cellsPerChannel이것이 가장 복잡한 부분입니다. NCCL은 데이터를 "cell"로 나누며, 각 cell은 최소 전송 단위입니다:
• cellsLo/cellsHi핵심 변수:

: 각 cell의 바이트 수, 최소: 총 cell 수calcCollChunking：

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

: 각 channel이 처리하는 cell 수: 처음과 끝 channel의 cell 수(불완전할 수 있음)

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

5단계: chunkGrains 계산.

ncclDevWorkColl각 channel 세그먼트에 대해

버퍼 포인터

📎 src/enqueue/enqueue.cc:897

channel 범위(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 시작 횟수가 증가하고 성능이 저하됩니다.

---

6. finishPlan: 작업에서 kernel 파라미터로

직관적 모델

finishPlan은 enqueue 모듈의 "패커"입니다. 작업, batch, proxyOp를 kernel이 직접 읽을 수 있는 파라미터 구조로 패킹합니다. 이는 택배 포장과 같습니다——낱개 물품을 상자에 넣고, 운송장을 붙여, 발송을 기다립니다.

단계별: 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: 디바이스 측 communicator
• 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(func, op, datatype) 기준 버킷팅, 알고리즘 계산

5. ncclPrepareTaskschannel 분할,

6. scheduleCollTasksToPlan을 생성하여 kernel 파라미터로 패킹ncclDevWorkColl

7. finishPlan핵심 설계 사상:

계층적 디커플링

• : 각 함수는 한 가지 일만 하며,과ncclInfo을 통해 상태 전달ncclTaskColl예산 제어
• :을 통해 각 plan의 크기 제어ncclTestBudget집계 최적화
• : 크기가 비슷한 작업이 집계되어 kernel 시작 횟수 감소설정 우선순위
• 다음 장에서는：env > per-call > comm

으로 들어가, NCCL이 다중 channel 다중 kernel의 실행 순서를 어떻게 편성하는지 살펴봅니다.task_sched이 장 생각해보기와 자가 점검

Q1: 만약

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

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;
  }
}

여기까지 우리는 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는 1 증가,ncclGroupEnd는 1 감소한다. 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극히 단순하다: 깊이를 1 증가시킨다. 메모리 할당도, 락도, 시스템 콜도 없다. 이것이

가 거의 제로 오버헤드인 이유이다.ncclAllReduce두 번째 단계:

ncclAllReduce가 group 내에서 호출되면 무슨 일이 발생하는가?ncclGroupCommJoin(comm, ncclGroupTaskTypeCollective)내부에서

📎 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)멱등성 검사ncclAllReduce는 동일한 통신 도메인이 동일한 group 내에서 한 번만 추가되도록 보장한다. 만약 사용자가 동일한 comm에 대해comm->planner를 두 번 호출하면, 두 번째는 연결 리스트에 중복 추가되지 않지만, 태스크는

2. 에追加된다.：intraComm0clique 정렬ncclCommSplit는 「전역 엔티티」의 식별자이다. 여러 통신 도메인이 동일한 전역 엔티티에 속하면 (예를 들어intraComm0를 통해 분할된 경우), 그들의intraComm0가 동일하며, 이를 하나의 clique라고 한다. 코드는 먼저commHash로 clique를 찾아 comm을 동일 clique의 형제 노드 옆에 삽입한다. clique를 찾지 못하면doLaunches오름차순으로 삽입한다. 이 정렬은

3. 가 clique 내의 barrier 동기화를 올바르게 처리할 수 있도록 하기 위한 것이다.：ncclMemoryStackPush(&comm->memScoped)메모리 스택 스코프ncclTaskColl는 이 comm을 위해 group 내에 새로운 메모리 스택 스코프를 할당한다. 이 comm을 위해 할당된 모든 태스크(ncclGroupCommLeave등)는 이 스택에서 할당된다.ncclMemoryStackPop시malloc/free가 모든 태스크 메모리를 한 번에 해제한다——이는 「일괄 할당, 일괄 해제」의 고전적인 최적화로, 각 태스크마다 개별적으로

4. 하는 오버헤드를 방지한다.：memset(&comm->planner, 0, sizeof(comm->planner))planner 리셋peers는 planner를 비우지만,rmaTaskQueues와bcast_info포인터는 유지한다 (먼저 임시 변수에 저장하고, memset 후 복원). 왜 유지하는가? 이 둘은 사전 할당된 배열이므로 매번 재할당할 필요가 없기 때문이다.INT_MAX/INT_MIN의 min/max는

로 리셋되어 이후 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;

복사

📎 src/group.cc:1063

if ((ret = ncclGroupError) != ncclSuccess) goto 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。

를 다시 해야 한다.ncclGroupError함정 2:의 전파ncclGroupError. 만약 group 내에서 어느 한 번의 호출이 실패하면ncclGroupEnd가 설정되고,groupCleanup。groupCleanup는 fail 분기로 점프하여ncclGroupStart를 실행한다.

📎 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.
        // ...
      }
      // ...
    }
  }
  // ...
}

시 planner에 이전 데이터가 남아 있어 태스크 중복 제출이나 메모리 누수가 발생한다.comm->preconnectNext = reinterpret_cast<struct ncclComm*>(0x1)복사0x1주의:ncclGroupCommPreconnect이 줄. 이것은 「센티넬 값」으로, 「이 comm은 preconnect를 다시 해야 한다」를 나타낸다. 왜인가? cleanup 시 preconnect가 성공했는지 알 수 없으므로, 다음 번에 강제로 다시 검사하도록 하기 때문이다.if (comm->preconnectNext == reinterpret_cast<struct ncclComm*>(0x1))이 값은 매우 정교하다——합법적인 포인터는 아니지만, 「미초기화」 마커로 사용할 수 있다.

---

에서ncclPrepareTasks를 검사하여 preconnect 연결 리스트에 추가해야 하는지 판단한다.

二、태스크 준비:

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 그룹의 경우, 이것이 일반적인 상황입니다.

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

---

3.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를 호출할 때까지 기다린 후, 모든 입력값의 리덕션 결과(여기서는 논리 OR)를 반환합니다. 만약 어떤 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 집합 통신 (NIC offload로 집합 통신 수행).
• 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이 서로 다른 프로세스에 있는 경우), 하위 레벨에서 공유 메모리나 네트워크를 사용할 수 있다.

왜 단순한 "모든 comm에 plan이 남아 있는지 확인" 대신 barrier를 사용하는가? "확인"은 비원자적이기 때문이다: 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 모드를 권장한다.

---

4.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에 대해ncclP2PPreconnectFuncjob을 생성한 후 일괄 시작한다.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

---

5.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)을 유지하는 것을 권장합니다.

---

6. 논블로킹 group과 비동기 오류 처리

시나리오 기반 단계별 워크스루

논블로킹 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는 이 group job에 몇 개의 comm이 연관되어 있는지 기록합니다. 각 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。

로 폴백합니다.ncclLaunchKernel다음 장에서는 kernel 시작의 마지막 단계로 들어갑니다:ncclKernelPlan가 어떻게 GPU에서 실제로 실행되는 kernel이 되는지, 그리고 디바이스 측에서 어떻게DevComm메타데이터를 읽는지입니다.

이 장 생각해보기와 자가 점검

제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는 영구 버퍼에 있음을 의미한다.

ncclDevWorkBatchbatch 디스크립터로, 디바이스 측에 "이 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
};

offsetBitset64비트 마스크로, 각 비트가 하나의 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를 커널 파라미터에 직접 넣습니다. 그렇지 않으면 work는 FIFO 또는 영구 버퍼에 배치되고, 커널 파라미터에는 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를 복사한 다음 커널이 거기서 읽도록 해야 합니다.

함정 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비트로, 하나의 batch에 최대 64개의 work를 지원합니다. 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호출.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 메커니즘.ncclImplicitOrderLaunchlaunchCompletionEvent를 사용하고 사용자가

를 제공한 경우, NCCL은 사용자의 event를 드라이버에 직접 전달할 수 없습니다. 드라이버는 하나의 launch completion event만 지원하기 때문입니다. NCCL의 방식은:comm->sharedRes->launchEvent1.

를 드라이버에 전달합니다.relayStream2.launchEvent。

에서relayStream를 기다립니다.

3.

Mem Sync Domain。 📎 src/enqueue/enqueue.cc:1938-1942에 사용자의 event를 기록합니다.CU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN이렇게 하면 사용자의 event는 host 측 호출이 반환될 때가 아니라 kernel이 실제로 실행을 시작한 후에 트리거됩니다.cudaLaunchMemSyncDomainRemote

sm90+에서 NCCL은

를로 설정합니다. 이는 Hopper 아키텍처에서 도입된 메모리 동기화 도메인 메커니즘으로, 서로 다른 kernel의 메모리 배리어를 격리하여 불필요한 동기화 오버헤드를 줄입니다.grid.x프로덕션 함정 가이드clusterSize함정 1: cluster 차원이 나누어지지 않아 런치 실패.CUDA_ERROR_INVALID_VALUE만약if (grid.x % clusterSize) clusterSize = 1;이cgaClusterSize로 나누어지지 않으면 드라이버는nChannels를 반환합니다. 소스 코드에서는

로 보호하고 있지만, 이는 cluster 기능이 조용히 비활성화되었음을 의미합니다. 사용자가 cluster로 인한 성능 향상을 기대한다면 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로 변환하는지 추적했고, device 측 진입점인 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캐시를 갱신하고, 주기적으로📎 src/device/prims_ll.h:73-89。

을 호출하여 abort되었는지 확인한다 DataLoader::loadBegin두 번째 단계: 로컬 데이터를 로드한다.📎 src/device/prims_ll.h:200-216은 정렬 문제를 처리한다sizeof(T) <= 2.u4[0..2]일 때(예: half 또는 int8), 소스 주소가 4바이트 정렬이 아닐 수 있으므로, 먼저 4바이트 정렬로misalign에 읽어들이고,loadFinish을 기록한 후,__funnelshift_r에서📎 src/device/prims_ll.h:218-225을 사용하여 바이트 수준 시프트로 올바른 64비트 값을 조립한다

. 이것은 전형적인 "정렬 읽기 + 시프트 재조립" 기법으로, 비정렬 접근의 성능 페널티를 피한다. readLL세 번째 단계: 상대방 데이터를 읽고 flag를 기다린다.📎 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

checkAbort는 barrier 번호로, NCCL은 서로 다른 barrier 번호로 서로 다른 group을 격리해 상호 간섭을 피한다.📎 src/device/primitives.h:154-164NCCL_SPINS_BEFORE_CHECK_ABORT는 무한 루프 방지의 핵심이다abortFlag: 매ncclShmem.aborted(10000)번 스핀마다 한 번씩

를 읽어, 잦은 전역 메모리 읽기로 핫 패스가 느려지는 것을 피한다. abort가 발견되면

를 설정하고 캐시하여, 이후 모든 대기 루프가 빠르게 빠져나간다.프로덕션 함정NCCL_LL_CLEAN_MASK함정 1: flag 랩어라운드로 인한 가짜 준비 상태.

만약MaxRecv == 0의 cleanup 로직이 제거되면, 장시간 실행(step이 mask 주기를 초과) 후 수신 측이 이전 라운드의 잔류 flag를 읽어 데이터가 준비된 것으로 오판하고 더티 데이터를 읽을 수 있다. 이런 버그는 step이 특정 값으로 정확히 랩어라운드되는 것에 의존하기 때문에 재현이 극히 어렵다.함정 2:MaxRecv = Fan::MaxRecv > 1 ? Fan::MaxRecv : 1 📎 src/device/prims_ll.h:13의 컴파일 함정.MaxSend코드에서📎 src/device/prims_ll.h:14-19。

, 왜냐하면 송신만 하고 수신하지 않더라도 길이가 MaxRecv인 수신 버퍼를 할당하기 때문에, MaxRecv가 0이면 길이 0 배열 컴파일 실패가 발생한다. Windows에서

도 동일하게 처리한다

LL128: 128바이트 정렬로 더 높은 페이로드를 얻는다직관적 모델LL의痛点은 페이로드가 50%에 불과하다는 것(16바이트 중 8바이트가 flag)이다. LL128의 아이디어는:

flag를 매 128바이트의 마지막 8바이트에 집중시키고, 앞의 120바이트는 전부 데이터로 채우는 것이다

. 이렇게 하면 페이로드가 50%에서 93.75%로 향상된다. 대가는 128바이트 정렬을 반드시 보장해야 하며, 그렇지 않으면 「공유 메모리 재배치」를 해야 한다.uint64_t데이터 구조와 메모리 레이아웃NCCL_LL128_LINEELEMSLL128의 전송 단위는NCCL_LL128_DATAELEMS(8바이트)이지만, 128바이트 「line」으로 구성된다.

📎 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));

WireWordPerSliceDataEltPerSlice는 그중 데이터 요소 수(15개)이며, 마지막 요소에 flag를 넣는다.

핵심 상수복사flagThread 📎 src/device/prims_ll128.h:373。flagThread = ((tid % 8) == 7)는 하나의 warp가 한 번에 전송하는 64비트 워드 수이고,

는 그중 유효 데이터 요소 수(각 line마다 flag 요소 하나를 뺀 값)이다.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。

LL128의 flag 메커니즘은 LL과 다르다: loadRegsBegin매 8개 스레드 중 7번째(📎 src/device/prims_ll128.h:99-142：

• )만 flag를 검사한다. 왜인가? flag는 매 128바이트마다 하나이고, 하나의 warp에는 32개 스레드가 있으며, 매 8개 스레드가 128바이트를 처리하므로(8스레드 × 16바이트 = 128바이트), 매 8개 스레드 중 1개만 flag를 읽으면 된다.load128시나리오 기반 Walkthrough: 한 번의 recvReduceSendCopyflagThread호출 체인:g % 2 == 0첫 번째 단계: 로컬 데이터를 레지스터에 로드.📎 src/device/prims_ll128.h:109-114。
• 두 가지 경우로 나뉜다16바이트 정렬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: 먼저 정렬된 영역을 공유 메모리__any_sync에 로드한 후 공유 메모리에서 올바른 오프셋으로 레지스터에 다시 읽는다

두 번째 단계: 상대방 데이터를 기다리고 읽기. loadRegsFinish📎 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. postPeerstep 포인터 업데이트📎 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는 SM90+에서📎 src/device/prims_simple.h:86-100。loadStepValue가 활성화된 경우NvlsMinPolling명령을 사용한다multimem.ld_reduce.acquire.sys.global.min.u64, 이는 NVLink SHARP의 하드웨어 가속 폴링이다.📎 src/device/prims_simple.h:86-100와

barrier()의 차이subBarrier()는 모든📎 src/device/prims_simple.h:49-55：barrier()개 스레드를 동기화하고,nthreads는subBarrier()개 worker 스레드만 동기화한다.nworkers의 barrier 번호는subBarrier이며, worker 수가 전체 스레드 수와 다를 때 다른 barrier를 사용하여15 - group - (nworkers != nthreads ? 1 : 0)와의 충돌을 피한다.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에서는 송신 버퍼가 NIC에 의해 직접 접근되므로, proxy 스레드가 전송 완료(size가 -1로 설정됨)를 확인할 때까지 반환해서는 안 됩니다. 그렇지 않으면 다음 kernel이 NIC가 읽고 있는 데이터를 덮어쓸 수 있습니다.

함정 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 로직에 왜 세 가지 전송 프리미티브가 필요한가」에 대한 답입니다: 메시지 크기마다 다른 동기화 전략과 버퍼 레이아웃이 필요하며, 세 프리미티브는 각각 작은, 중간, 큰 메시지에 최적화되어 있습니다.

이 장의 생각과 자가 점검

여기까지 우리는 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은 최소한의 네트워크 대역폭으로 2단계 파이프라인을 수행하고, Tree는 트리형 리덕션으로 지연을 log(n)까지 압축하며, CollNet/NVLS는 리덕션을 NIC나 NVLink 스위치에 오프로드한다. 이번 장에서 하나씩 풀어본다.

10.1 Ring AllReduce: 2단계 파이프라인이 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 알고리즘의 입도(granularity)이다 — 매 단계마다 하나의 chunk를 전송한다.

loopCount = nranks * chunkCount（📎 src/device/all_reduce.h:23)는 "한 바퀴 전체를 도는" 처리 데이터량을 나타낸다. 외부 루프for (elemOffset = 0; elemOffset < channelCount; elemOffset += loopCount)（📎 src/device/all_reduce.h:34)는 다음을 의미한다: channel 데이터량이 한 바퀴로 처리할 수 있는 양을 초과하면 여러 바퀴로 나누어 실행한다.

단계별 분석: 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은 두 가지 변형이다. 전자는 「먼저 전부 reduce한 후 전부 broadcast」하는 2단계 모드를 사용하고, 후자는 스레드를 반으로 나누어 절반은 reduce, 절반은 broadcast를 수행하여 파이프라인 오버랩을 구현한다.

Step-by-Step Walkthrough: runTreeUpDown의 세 가지 분기

runTreeUpDown의 첫 번째 코드 블록은 reduce 단계(📎 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);

루트 노드는 받기만 하고 보내지 않으며, 모든 자식 노드로부터 데이터를 받아 reduce하고 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);

자식으로부터 받아 reduce하고 부모로 보낸다.

broadcast 단계(📎 src/device/all_reduce.h:120-142)는 논리가 대칭적이다: 루트 노드directSendFromOutput(recvbuff에서 보냄), 리프 노드directRecv, 중간 노드directRecvCopyDirectSend。

runTreeSplit: 스레드 분할로 reduce-broadcast 파이프라인 구현

runTreeUpDown의 문제는 reduce 단계와 broadcast 단계가 직렬로 진행되며 중간에 전역 동기화 지점이 있다는 것이다.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개의 소스에서 데이터를 받아 reduce하는 것」이 「3개의 대상에게 보내는 것」보다 계산 집약적이기 때문에 reduce 그룹에 더 많은 스레드를 할당한다.

그런 다음tid < nthreadsSplit의 스레드는 reduce 상향 전파(📎 src/device/all_reduce.h:175-202)를, 나머지 스레드는 broadcast 하향 전파(📎 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의 루트 노드를 왜 특별 처리해야 하는가

트리 reduce의 루트 노드는 「집결점」으로, 수신량이 자식 노드 수의 배수이고 송신량은 0이다(reduce 단계). 만약 루트 노드도 일반적인directRecvReduceDirectSend를 따르면tree->up(-1)로 보내려고 시도하여 범위를 벗어난다. 따라서 반드시if (tree->up == -1)분기로 별도 처리해야 한다. 마찬가지로 리프 노드의tree->down[0] == -1판단도 마찬가지다.

프로덕션 함정: Tree 알고리즘의 「핫스팟 루트」 문제

Tree의 루트 노드는 모든 reduce 트래픽을 담당하는데, 만약 루트 노드가 위치한 GPU가 마침 느린 노드라면(예: PCIe 대역폭 제한), 전체 AllReduce가 느려진다. NCCL의 대응은:각 channel이 서로 다른 루트를 선택하여 루트 노드의 부하를 여러 rank에 분산시키는 것이다. 이것이runTreeSplit에서 루트 노드 분기가FanSymmetric<NCCL_MAX_TREE_ARITY_TOP>（📎 src/device/all_reduce.h:168)를 사용하는 이유다 — 동시에 여러 자식 노드의 reduce를 처리해야 하기 때문이다. 프로덕션 환경에서 Tree AllReduce 성능이 불균일하다면 channel의 루트 노드 분포가 균일한지 확인하라.

10.3 AllGather와 ReduceScatter: Ring의 「절반」 변형

직관적 모델: AllReduce를 둘로 쪼개기

AllGather와 ReduceScatter는 본질적으로 AllReduce의 두 단계를 각각 독립 API로 만든 것이다. AllGather는 「수집」만 수행한다 — 각 rank가 데이터를 하나씩 기여하고, 최종적으로 모든 사람이 전체 데이터를 받는다. ReduceScatter는 「reduce+분산」만 수행한다 — 모든 사람이 데이터를 기여하고, reduce 후 각자 한 조각을 받는다.

이 두 독립 API가 없다면, 사용자가 「먼저 reduce 후 수집」 또는 「먼저 수집 후 reduce」를 할 때 AllReduce를 호출한 뒤 수동으로 슬라이스해야 하므로 대역폭의 절반을 낭비한다.

AllGather의 Ring 구현

all_gather.h의runRing（📎 src/device/all_gather.h:14-88)는 AllReduce보다 간단하다: reduce 없이 복사-전달만 한다.

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 단계: 받으면서 reduce하고 전달（📎 src/device/reduce_scatter.h:44-49）

prims.recvReduceSend(offset, nelem);

마지막 단계: 받아서 reduce하여 최종 결과 생성（📎 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는 다른 접근을 취합니다: 리덕션 연산을 NIC(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. 이 차이는 네트워크 등록 모드가 NIC 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은 NIC에 의존하므로, NIC 초기화가 실패하면 out이 -1이 되고, 이때 계속 실행하면 정의되지 않은 동작이 발생합니다. 프로덕션 환경에서 kernel trap이 발생하면 CollNet NIC가 정상적으로 초기화되었는지 확인하세요.

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: 리덕션을 지원하는 NIC가 있는 클러스터에 적합, GPU 계산을 오프로드.
• NVLS: 단일 노드 NVLink 전연결에 적합, 하드웨어 멀티캐스트 리덕션.

NCCL의 tuning 모듈(제5장)은 메시지 크기, rank 수, 토폴로지에 따라 자동으로 선택한다. 디바이스 측 구현은 「각 조합이 모두 정확함」만 보장하면 되고, 선택 로직은 host 측에 있다.

이 장 요약

이 장에서는src/device아래의 여섯 가지 알고리즘 커널 파일을 분석했다:

1. Ring AllReduce（📎 src/device/all_reduce.h:14-83): 2단계 파이프라인, 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 프로토콜만 지원.

이 장 사고와 자가 점검

여기까지 우리는 디바이스 측 알고리즘 커널이 어떻게 데이터 흐름을 조직하는지 살펴보았다. 각 알고리즘은Primitives를 통해 이전 장의 원시 연산을 호출하며, 알고리즘 계층은 「누가 누구에게, 어느 chunk를 보내는지, reduce인지 copy인지」만 신경 쓴다. 다음 장에서는 전송 계층 추상화를 깊이 파고들어 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가 어떻게 데이터를 분할한 후 두 단계로 reduce하는지, Tree AllReduce가 어떻게 트리 구조를 통해 지연을 낮추는지 살펴보았다. 그러나 이러한 알고리즘은 「누가 누구에게, 어느 chunk를 보내는지」의 논리적 뷰만 정의한다. 데이터는 결국 실제 물리적 링크, 즉 NVLink, PCIe, 공유 메모리 또는 네트워크 카드를 통과해야 한다. 이 장에서는 src/transport 디렉터리를 해부하여 NCCL이 어떻게 통일된 ncclTransport 인터페이스로 P2P, SHM, NET, NVLS 네 가지 물리적 채널을 동일한 얼굴로 가리는지, 알고리즘 토폴로지에서 물리적 전송까지의 마지막 1마일을 완성하는지 살펴본다.

1. 통일 인터페이스: 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==1send 방향을 나타내고,type==0recv 방향을 나타냅니다. 루프는 각 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

설계 고찰

2. P2P: 동일 머신 GPU 직결의 네 가지 형태

직관적 모델

P2P는 「이웃 간에 직접 물건을 전달」하는 것입니다 — GPU 0이 CPU나 네트워크 카드를 거치지 않고 GPU 1의 메모리를 직접 읽고 씁니다. P2P가 없으면 동일 머신 다중 GPU 통신은 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핵심 포인트:ncclSendMem는 P2P Read 모드에서 SIMPLE 프로토콜 버퍼 크기를 추가로 더해야 합니다 — 읽기 모드에서는 송신 측의 SIMPLE buffer를 수신 측이 직접 읽으므로 반드시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))

복사P2P_DIRECT동일 프로세스이고 direct가 비활성화되지 않았으며 memcpy가 활성화되지 않았다면 가장 빠른

입니다 — 상대방 포인터를 직접 가져옵니다. 그렇지 않으면 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복사p2pSendProxySetup는 동기 RPC입니다: host 스레드가 프록시 스레드에 메시지를 보내고, 프록시 스레드가ncclP2pBuff를 호출하여 공유 가능 버퍼를 할당한 뒤p2pMap(IPC 핸들 포함)를 반환합니다. 그런 다음

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;
}

복사cudaDeviceEnablePeerAccess동일 프로세스 다른 GPU: 먼저directPtr로 P2P 채널을 열고, 그런 다음ncclP2pImportShareableBuffer를 직접 사용합니다(동일 프로세스 주소 공간 공유이므로). 프로세스 간:

를 호출하여 상대방 메모리 핸들을 임포트합니다.

동시성 제어와 하드웨어 상호작용ncclSendMem/ncclRecvMemP2P의 동기화는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은 이 두 포인터를 읽고 써서 CPU 개입 없이 GPU 간 동기화를 구현합니다.프로덕션 함정 회피 가이드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이면, 직접

를 반환합니다. 프로덕션 환경에서 이 오류가 보이면 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가 발생한다.

3. 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 선택

shmSendSetuplocality에 따라 얼마나 큰 메모리를 할당할지 결정한다:

📎 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마운트가 일치하는지 확인하라.

4. NET: 네트워크 전송의 매핑 테이블과 프록시 진행

직관적 모델

NET은 「도시 간 택배」다 — 데이터를 패키징해서 NIC에 넘기면, NIC가 광섬유를 통해 상대방에게 보낸다. 하지만 NIC는 GPU 메모리 주소를 인식하지 못하므로, GPU 가상 주소를 NIC가 이해할 수 있는 물리 주소로 변환하는 「주소 매핑 테이블」이 필요하다. 이 테이블이 바로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에서 가장 복잡한 함수로, NIC 연결 설정, 버퍼 할당, 메모리 등록을 담당한다:

📎 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이 동일한 NIC 연결을 재사용하여 연결 수를 줄인다.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);

복사size비공유 버퍼: 현재 bank의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]));
      }
      ...

복사cuMemGetHandleForAddressRangeDMA-BUF 경로를 우선한다(regMr로 fd를 얻어 NIC 플러그인에 전달). 실패하면

로 폴백한다(전통적인 nv_peermem GDR).

sendProxyProgress동시성 제어와 하드웨어 상호작용: sendProxyProgress의 3단계 파이프라인

📎 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: 프록시 스레드가
• transmit를 갱신하여 GPU에 「버퍼가 준비되었으니 데이터를 써도 된다」고 알린다.recvMem->tail:connFifo[buffSlot].size != -1가 진행되었는지 확인하고(GPU가 쓰기를 완료함),ncclNet->isend를 확인한 후(데이터 크기가 채워짐),
• done를 호출하여 비동기 전송을 시작한다.ncclNet->test:sendMem->head를 호출하여 전송 완료를 확인하고,

wc_store_fence()를 갱신하여 버퍼를 반환한다.gdcSync는 쓰기 결합 배리어다 — GDRCopy 시나리오에서 CPU가

를 쓴 후 반드시 쓰기 결합 버퍼를 플러시해야 하며, 그렇지 않으면 GPU가 갱신을 볼 수 없다.

프로덕션 함정 회피 가이드함정 1: 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;
                }
              }
            }
          }

복사threadfence()GPU가useGdr올바른가——GDR 경로에서는 데이터가 직접 VRAM에 저장되므로 행별 검증이 필요 없다.

함정 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
            }

mfenceCQE poll의 읽기가 flush 읽기 이전으로 재배열되지 않도록 보장한다;mov (%0), %%eaxPCIe 읽기를 강제로 한 번发起하여, 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

5. NVLS: 멀티캐스트 그룹과 UC/MC 메모리 바인딩

직관적 모델

NVLS는 「방송국」이다——하나의 rank가 데이터를 멀티캐스트 그룹에 쓰면, 하드웨어가 자동으로 모든 구독자에게 복사한다. 전통적인 AllReduce는 N-1번의 점대점 전송이 필요하지만, NVLS는 단 1번의 멀티캐스트 쓰기 + 1번의 멀티캐스트 읽기만 필요하다. NVLS가 없으면 대규모 AllReduce의 지연은 rank 수에 따라 선형으로 증가한다.

데이터 구조와 메모리 레이아웃

NVLS의 핵심은 「UC(유니캐스트) 메모리」와 「MC(멀티캐스트) 메모리」의 바인딩이다.nvlsAllocBindUcUC 메모리를 할당하고 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가상 주소에 매핑 →cuMemSetAccessGPU 접근 권한 설정 →ncclMcPartitionBindMemUC 물리 메모리를 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.

NCCLCHECKGOTO(ncclSocketSend(sock, &type, sizeof(int)), ret, error);
NCCLCHECKGOTO(ncclSocketSend(sock, &proxyConn->connection, sizeof(void*)), ret, error);
NCCLCHECKGOTO(ncclSocketSend(sock, &reqSize, sizeof(int)), ret, error);
NCCLCHECKGOTO(ncclSocketSend(sock, &respSize, sizeof(int)), ret, error);
if (reqSize) NCCLCHECKGOTO(ncclSocketSend(sock, reqBuff, reqSize), ret, error);
NCCLCHECKGOTO(ncclSocketSend(sock, &opId, sizeof(opId)), ret, error);
NCCLCHECK(expectedProxyResponseEnqueue(sharedProxyState, opId, respSize));

📎 src/proxy.cc:1369-1394

마지막 단계에 주목하세요: 요청을 보낸 후 즉시 opId를expectedResponses큐에 등록합니다. 이것이 비동기 RPC의 핵심입니다——호출자는 응답을 기다리지 않고, 먼저 「나는 이 opId의 응답을 기대한다」고 등록한 후, 나중에ncclPollProxyResponse로 폴링합니다.

응답 큐의 연결 리스트 구현

expectedProxyResponseEnqueue 📎 src/proxy.cc:97-117은 단방향 연결 리스트로 대기 중인 op를 저장합니다.expectedProxyResponseStore 📎 src/proxy.cc:67-95은 응답 수신 시 opId로 매칭하여 응답 데이터를 미리 할당된respBuff에 memcpy하고,done = true。expectedProxyResponseDequeue 📎 src/proxy.cc:119-141을 표시합니다. 폴링 시 완료된 응답을 찾아 제거합니다.

여기에는 디테일이 있습니다:expectedProxyResponseStore은respSize이📎 src/proxy.cc:72-75과 일치하는지 확인하고, 일치하지 않으면ncclInternalError을 보고합니다. 이것은 방어적 프로그래밍입니다——요청자와 응답자가 응답 크기에 대한 이해가 다르다면 프로토콜이 어긋난 것이므로, 조용히 계속하지 말고 즉시 실패해야 합니다.

Service 스레드의 메인 루프

ncclProxyService 📎 src/proxy.cc:1789-2016의 핵심은 poll 루프입니다.pollfds배열로 모든 연결을 관리하며, listen socket과 각 peer의 socket을 포함합니다.

while (stop == PROXY_RUNNING || npeers > 0) {
    if (COMPILER_ATOMIC_LOAD(proxyState->abortFlag, std::memory_order_acquire) != 0) stop = PROXY_ABORT;
    int ret = 0;
    const int timeout = asyncOpCount ? 0 : 500;
    ...
    ret = poll(activePollfds, nfds_to_poll, timeout);

📎 src/proxy.cc:1842-1863

timeout의 선택은 매우 신중합니다: 진행 중인 비동기 op가 있으면(asyncOpCount > 0), timeout을 0(논블로킹 폴링)으로 설정합니다. 왜냐하면proxyProgressAsync을 자주 호출하여 그것들을 진행시켜야 하기 때문입니다. 그렇지 않으면 500ms로 설정하여 공회전으로 CPU를 태우는 것을 방지합니다. 주석 「never let proxy service thread blocks in poll, or it cannot receive abortFlag」📎 src/proxy.cc:1847-1847는 왜 무한 블로킹할 수 없는지 명확히 합니다——주기적으로 깨어나 abortFlag를 확인해야 합니다.

비동기 op의 진행

proxyProgressAsync 📎 src/proxy.cc:1626-1700은 Service 스레드가 비동기 작업을 진행하는 핵심입니다. op 유형에 따라 서로 다른 transport 콜백으로 분배합니다:

if (op->type == ncclProxyMsgSetup) {
    res = op->connection->tcomm->proxySetup(op->connection, proxyState, op->reqBuff, op->reqSize, op->respBuff,
                                            op->respSize, &done);
} else if (op->type == ncclProxyMsgConnect) {
    res = op->connection->tcomm->proxyConnect(...);
} else if (op->type == ncclProxyMsgInit) {
    res = proxyConnInit(peer, connectionPool, proxyState, ...);
}

📎 src/proxy.cc:1631-1664

각 콜백은done출력 파라미터를 가집니다. 만약done == 0이면 작업이 아직 완료되지 않았음을 의미하며(예: 네트워크 연결이 아직 3-way handshake 중),ncclInProgress을 반환하고 다음 루프에서 계속 진행합니다. 만약done == 1이면 요청자에게 응답 헤더 + 응답 본문을 전송합니다📎 src/proxy.cc:1681-1689。

sequenceDiagram
    participant Main as 主线程 (ncclSend)
    participant Svc as Service 线程
    participant Net as 网络插件 (ncclNet)
    Main->>Svc: ncclProxyCallAsync(ncclProxyMsgConnect)
    Note over Main: expectedProxyResponseEnqueue(opId)
    Svc->>Svc: proxyServiceInitOp 读取请求
    Svc->>Net: proxyConnect() 调用 ncclNet->connect
    alt connect 未完成
        Net-->>Svc: netSendComm == NULL, done=0
        Svc->>Svc: 返回 ncclInProgress，下次 poll 重试
    else connect 完成
        Net-->>Svc: netSendComm != NULL, done=1
        Svc->>Main: ncclSocketSend(resp header + connectMap)
    end
    Main->>Main: ncclPollProxyResponse 轮询
    Main->>Main: expectedProxyResponseDequeue 取回结果

이 시퀀스 다이어그램은sendProxyConnect에 있는*done = 0; return ncclInProgress의 실제 분기를 고정합니다📎 src/transport/net.cc:913-916。

12.4 데이터 평면: Progress 스레드가 네트워크 송수신을 구동하는 방법

직관적 모델

Progress 스레드는 「컨베이어 벨트 운영자」입니다: 공유 버퍼의 FIFO를 주시하다가 GPU가 데이터를 다 쓰면(FIFO에서 size != -1), 즉시isend을 호출하여 데이터를 전송합니다. 네트워크가 데이터 수신을 완료하면 recvTail을 업데이트하여 GPU에 읽어도 된다고 알립니다. 전체 과정에서 GPU와 proxy는 FIFO의 head/tail 포인터로 동기화하며, 어떤 락도 필요하지 않습니다.

op의 전달: 메인 스레드에서 Progress 스레드로

메인 스레드는ncclProxySaveOp 📎 src/proxy.cc:591-761에서 pattern에 따라 필요한 proxy op를 결정한 후,SaveProxy → ncclLocalOpAppend을 통해 op를 공유 메모리 풀에 씁니다.

ncclLocalOpAppend 📎 src/proxy.cc:488-554의 흐름:

1.proxyOps->freeOp또는pool->freeOps[tpLocalRank]에서 유휴 op 슬롯을 가져옵니다.