Progreso del libro: Capítulo 2 / 25

Capítulo 2: Modelo de abstracción central: operadores de comunicación, topología, algoritmos, protocolos y capa de transporte

En el capítulo anterior hicimos funcionar NCCL y observamos el comportamiento externo de tres APIs: ncclCommInitRank, ncclAllReduce y ncclCommDestroy. Pero el comportamiento externo es solo la punta del iceberg — cuando ncclAllReduce retorna, ¿qué ocurre realmente en la GPU? ¿Por qué camino viajan los datos? ¿Por qué el mismo AllReduce tiene diferencias de rendimiento enormes en distintas máquinas? Para responder estas preguntas, primero hay que establecer el vocabulario común de NCCL. Este capítulo desglosará uno por uno los cinco conceptos centrales: dominio de comunicación (ncclComm), canal (channel), algoritmo (algorithm), protocolo (protocol) y capa de transporte (transport). Estos cinco conceptos atraviesan todo el libro, y cada capítulo posterior los utilizará en su análisis. Entender las relaciones entre ellos es entender el esqueleto de NCCL.

2.1 Dominio de comunicación ncclComm: el contexto de comunicación de un proceso

Modelo intuitivoncclCommImaginanRankscomo un "chat grupal": cada proceso se une al chat grupal y obtiene un ID de grupo, y luego todos los mensajes se envían en ese grupo. Cuántas personas hay en el grupo (rank), quién soy yo (channels), qué ruta se toma (config), qué reglas se usan (

), todo queda registrado en este objeto de chat grupal.ncclCommSi no existiera

, NCCL no sabría "quién se comunica con quién" ni "a dónde van los datos" — cada llamada a la API tendría que renegociar la lista de ranks y reconstruir las conexiones, con un costo inasumible.

ncclCommEstructura de datos y diseño de memoriasrc/include/comm.hes la estructura más central de todo NCCL, definida en

. Es extremadamente grande (casi 300 líneas); veamos los campos clave agrupados por función.

📎 src/include/comm.h:576-580Identidad y centinelas de ciclo de vidastartMagic，📎 src/include/comm.h:879-881defineendMagicdefine📎 src/include/comm.h:883-885. Estos dos campos no son claves de seguridad, sino centinelas de detección de desbordamiento de memoria. Enstatic_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");

es válido — esto es muy útil para depurar bugs del tipo "acceso de puntero salvaje a un dominio de comunicación ya destruido" en entornos multihilo.

📎 src/include/comm.h:628-629Rank e información de topologíarankdefinenRanksy📎 src/include/comm.h:644-652— mi número en el dominio de comunicación y el número total de participantes.nodedefine los campos relacionados con el nodo:nNodes(el número del nodo donde estoy),localRank(número total de nodos),localRanks(número dentro del nodo),rankToNode、rankToLocalRank、localRankToRank。

Canales y búferes

📎 src/include/comm.h:593-593definechannels[MAXCHANNELS]——este es el arreglo de todos los canales dentro del dominio de comunicación.📎 src/include/comm.h:674-676define el número de canales:nChannels(número de canales de conexión),collChannels(número de canales de encolamiento de comunicación colectiva),nvlsChannels(número de canales NVLS).

📎 src/include/comm.h:691-693define el tamaño del búfer:buffSizes[NCCL_NUM_PROTOCOLS](tamaño del búfer de cada protocolo),p2pChunkSize(tamaño de bloque P2P),nvlsChunkSize(tamaño de bloque NVLS).

Cola de trabajo y FIFO

📎 src/include/comm.h:719-728define los campos relacionados con la FIFO de trabajo:workFifoBytes(tamaño de la FIFO, potencia de 2),workFifoBuf(búfer de la FIFO del lado del host),workFifoBufDev(búfer de la FIFO del lado del dispositivo),workFifoProduced(bytes producidos),workFifoConsumed(bytes consumidos).

Barrera de sincronización intraproceso

📎 src/include/comm.h:731-731define el mecanismo de sincronización de múltiples dominios de comunicación dentro del proceso:

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

NotaintraPad1yintraPad2tienen un tamaño de64 - sizeof(uint64_t), es decir, 56 bytes. Sumado al campouint64_tanterior, cada grupo de campos ocupa exactamente 64 bytes——esto es una línea de caché (Cache Line).

Estado de error asíncrono

📎 src/include/comm.h:705-705defineasyncResult——este campo registra el estado de las operaciones asíncronas del dominio de comunicación. En el capítulo anterior mencionamos que cuandoncclCommFinalizeretorna, el dominio de comunicación puede seguir en estadoncclInProgress, y esto se rastrea mediante este campo.

Walkthrough guiado por escenarios: desde ncclCommInitRank hasta el llenado de la estructura

Cuando el usuario llama ancclCommInitRank(&comm, nranks, commId, rank), internamente NCCL asigna unancclCommestructura y la llena campo por campo. Sigamos este flujo para ver cómo se establecen los campos clave:

Primer paso: asignación y puesta a cero

NCCL usancclCallocpara asignarncclComm, asegurando que todos los campos se inicialicen a 0. En este momentostartMagicyendMagicse establecen enNCCL_MAGIC（📎 src/include/comm.h:563-569definido como0x0280028002800280, y el comentario dice "Nickel atomic number is 28").

Segundo paso: llenado de la información de identidad

rank、nRanks、cudaDevse obtiene de los parámetros y de la API de CUDA.commHashse obtiene por hash dencclCommId, y se usa para la verificación de consistencia en comunicaciones de red posteriores.

Tercer paso: construcción del grafo de topología

NCCL llama al módulo de detección de topología para enumerar todas las GPU, tarjetas de red y switches PCI, y construye el campotopo(📎 src/include/comm.h:595-595). Este grafo de topología determina la selección posterior de algoritmos y la planificación de rutas.

Cuarto paso: inicialización de canales

channels[MAXCHANNELS]El arreglo se inicializa uno por uno. Elidde cada canal se establece en el índice del arreglo,peersy los punterosdevPeersse asignan.

Quinto paso: establecimiento de conexiones de transporte

Según el grafo de topología, NCCL selecciona la capa de transporte (P2P/SHM/NET) para cada par de ranks, y llama a los callbacks correspondientessetupyconnect. La información de conexión se almacena enchannels[i].peers[j].

Sexto paso: establecimiento del número mágico

Finalmente,endMagicse establece enNCCL_MAGIC, marcando que la inicialización de la estructura ha finalizado.

Reflexiones de diseño y trampas en producción

¿Por quéncclCommes tan grande?

Escenario de trampa uno: dominio de comunicación compartido entre múltiples hilos

Escenario de trampa dos: acceso después de la destrucción

ncclCommDestroyDespués de questartMagiclibera la memoria de la estructura, si algún hilo aún conserva el puntero y accede a ella, leerá memoria ya liberada.endMagicy

pueden ayudar a detectar esta situación: si el número mágico no coincide, significa que el puntero ya no es válido.

Escenario de trampa tres: falso compartido de línea de cachéintraBarrierCounterEn escenarios multiproceso (un rank por proceso),intraBarrierGateel relleno de

y

es especialmente importante. Si se omite el relleno, las operaciones de barrera de múltiples procesos interferirán entre sí, haciendo que la latencia de sincronización pase de nanosegundos a microsegundos.

2.2 Canal channel: dividir una comunicación en múltiples líneas de ensamblajechannelEs la «cinta transportadora» de NCCL: divide los datos de una comunicación colectiva en múltiples partes, cada canal transporta una parte de forma independiente, avanzando en paralelo para mejorar la utilización del ancho de banda.

Sin canales, todos los datos solo pueden recorrer una única ruta, y los múltiples enlaces físicos entre GPUs (múltiples NICs, múltiples grupos de NVLink) no pueden utilizarse simultáneamente, lo que reduce drásticamente la utilización del ancho de banda.

Estructura de datos y diseño de memoria

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

Análisis de campos clave

• peers / devPeers: apunta a la información de conexión de todos los ranks dentro de ese canal.peersEs la vista del lado del host,devPeersEs la vista del lado del dispositivo (accedida directamente por el kernel de GPU).
• ring: descripción topológica del algoritmo Ring: predecesor y sucesor de cada rank.
• tree: descripción topológica del algoritmo Tree: nodo padre y lista de nodos hijos.
• collnetChain / collnetDirect: dos variantes topológicas del algoritmo CollNet.
• nvls: descripción topológica de NVLink SHARP.
• id: índice del canal, de 0 anChannels-1。
• workFifoProduced: puntero de producción del FIFO de trabajo de ese canal.

Cálculo del número de canales

El número de canales se define enncclComm(📎 src/include/comm.h:674-676）：

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

Planificación de canales P2P

📎 src/include/channel.h:21-33Define lancclP2pChannelBaseForRoundfunción, utilizada para calcular la dirección base del canal usado en cada round de la comunicación P2P:

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 guiado por escenarios: cómo se asignan los canales en un AllReduce

Supongamos 8 ranks y 4 canales, ejecutando un AllReduce. Los datos se dividen en 4 partes, cada una gestionada por un canal.

Primer paso: selección de algoritmo

El módulo de tuning de NCCL selecciona el algoritmo (por ejemplo, Ring) y el protocolo (por ejemplo, Simple) según el tamaño del mensaje y la topología.

Segundo paso: asignación de canales

ncclTaskCollSe crea la estructura📎 src/include/comm.h:212-273), donde el camponChannelsse establece en 4 (📎 src/include/comm.h:254-254）。channelLoy los camposchannelHi) marcan el rango de canales utilizados por esa tarea.📎 src/include/comm.h:256-257Tercer paso: división de datos

Cada canal se encarga de

elementos. El canal 0 procesa los elementos del 0 al count/4-1, el canal 1 procesa los elementos de count/4 a count/2-1, y así sucesivamente.count / nChannelsCuarto paso: ejecución en paralelo

Los kernels de GPU de los 4 canales se lanzan simultáneamente, cada uno ejecutando Ring AllReduce sobre su propia porción de datos. Dado que no hay dependencias de datos entre canales, pueden ejecutarse completamente en paralelo.

Quinto paso: combinación de resultados

Una vez que todos los canales terminan, el recv buffer de cada rank contiene el resultado completo del AllReduce.

Control de concurrencia e interacción con el hardware

Mapeo entre canales y recursos de GPU

〔Inferencia de diseño y compensaciones arquitectónicas〕

En escenarios con múltiples NICs, distintos canales pueden vincularse a distintas NICs. Por ejemplo, con 4 canales y 2 NICs, los canales 0 y 1 van por la NIC A, y los canales 2 y 3 por la NIC B. Así se aprovecha el ancho de banda de ambas NICs.

Elección del número de canales

〔Inferencia de diseño y compensaciones arquitectónicas〕

• Mayor sobrecarga de establecimiento de conexiones
• Sincronización más compleja
• El módulo de tuning de NCCL selecciona automáticamente el número óptimo de canales según el tamaño del mensaje. Mensajes pequeños usan pocos canales (para reducir sobrecarga), mensajes grandes usan más canales (para aumentar el ancho de banda).

Guía de evitación de problemas en producción

Escenario problemático 1: configuración inadecuada del número de canales

〔Inferencia de diseño y compensaciones arquitectónicas〕

〔Inferencia de diseño y compensaciones arquitectónicas〕

Si la operación

ncclP2pChannelBaseForRounddereverseBitsse implementa incorrectamente, múltiples rounds se asignarán al mismo canal, provocando serialización.📎 src/include/channel.h:32-32La operaciónreverseBits(base, log2Up(comm->p2pnChannels))de

garantiza una asignación uniforme de canales.

2.3 Algoritmo algorithm: organización topológica de Tree/Ring/CollNet/NVLS/PAT

De Beijing a Shanghái se puede ir en tren de alta velocidad, avión o coche, y cada medio se adapta a distintas distancias y números de personas. Los algoritmos de NCCL son esos «medios de transporte»: Ring es adecuado para el ancho de banda estable de mensajes grandes, Tree para la baja latencia de mensajes pequeños, CollNet aprovecha la descarga de la tarjeta de red, NVLS utiliza la aceleración por hardware NVLink SHARP, y PAT es una variante paralelizada de NVLS.

Sin selección de algoritmo, NCCL solo podría comunicarse con un único modo fijo, incapaz de adaptarse a distintos tamaños de mensaje y topologías, y el rendimiento se vería muy degradado.

Estructuras de datos y diseño de memoria

Algoritmo Ring

El núcleo del algoritmo Ring es lancclRingestructura (ensrc/include/comm.hreferenciada mediantechannels[i].ring).📎 src/include/collectives.h:81-116define laRingAlgorithmclase base:

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() {};
};

Análisis de campos clave

• refCount: recuento de referencias, utilizado para que el hilo proxy y el kernel de GPU compartan el objeto de algoritmo.
• nRanks: número de nodos en el anillo.
• nStepsPerLoop: número de pasos por ciclo. AllReduce es2*(nRanks-1)*chunkSteps（📎 src/include/collectives.h:218-218）。
• chunkSteps / sliceSteps: pasos de bloque y pasos de slice, que controlan la granularidad del pipeline.
• sliceSize / loopSize / channelSize: tamaño de slice, tamaño de ciclo, tamaño de canal.
• sendbuff / recvbuff: punteros a los búferes de envío y recepción.
• sendMhandle / recvMhandle / srecvMhandle: manejador de memoria, utilizado para el registro de red.

Operaciones atómicas del recuento de referencias

📎 src/include/collectives.h:106-108muestraincRefCountydecRefCount：

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: implementación Ring de AllReduce

📎 src/include/collectives.h:118-234defineRingARAlgorithm, que hereda deRingAlgorithm. Los métodos principales songetNextSendAddrygetNextRecvAddr。

📎 src/include/collectives.h:126-167degetNextSendAddrlógica:

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

Algoritmo PAT

PAT (Parallel Aggregated Tree) es una variante paralelizada de NVLS.📎 src/include/collectives.h:416-423definencclPatStep：

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-435definencclPatPeer：

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 guiado por escenarios: evolución de los pasos de Ring AllReduce

Supongamos 4 ranks (0, 1, 2, 3), cada rank con 4 elementos, ejecutando Ring AllReduce.

Fase Reduce-Scatter

• Paso 0: el rank 0 envía el elemento 0 al rank 1, el rank 1 envía el elemento 1 al rank 2, el rank 2 envía el elemento 2 al rank 3, el rank 3 envía el elemento 3 al rank 0.
• Paso 1: cada rank suma el elemento recibido con el elemento local correspondiente y luego lo envía al siguiente rank.
• Paso 2: continúa la acumulación y transmisión.
• Paso 3: en este punto cada rank posee un resultado de reducción completo (el rank 0 tiene el resultado del elemento 3, el rank 1 tiene el resultado del elemento 0, etc.).

Fase AllGather

• Pasos 4-6: cada rank propaga por el anillo el resultado de reducción que posee, y finalmente todos los ranks tienen el resultado completo.

📎 src/include/collectives.h:218-218ElnStepsPerLoop = 2 * (nRanks - 1) * chunkStepsde(nRanks-1)*chunkStepscorresponde exactamente a este flujo: Reduce-Scatter requiere(nRanks-1)*chunkStepspasos, AllGather también requiere2*(nRanks-1)*chunkStepspasos, en total

pasos.

Reflexiones de diseño y trampas en producción

El algoritmo Ring tiene una alta utilización de ancho de banda (todos los enlaces están transmitiendo), pero la latencia crece linealmente con el número de ranks. La latencia del algoritmo Tree es logarítmica, pero su utilización de ancho de banda es baja (solo parte de los enlaces trabajan). NCCL selecciona automáticamente según el tamaño del mensaje: mensajes pequeños usan Tree (sensible a la latencia), mensajes grandes usan Ring (sensible al ancho de banda).

Si se fuerza manualmente el uso de Ring para mensajes pequeños, la latencia aumentará significativamente. Se recomienda dejar que el módulo de tuning seleccione automáticamente, a menos que haya datos claros de análisis de rendimiento que respalden la intervención manual.

Escenario de trampa 2: hardware NVLS no compatible📎 src/include/comm.h:755-755NVLS requiere soporte de hardware específico (NVLink SHARP). Si el hardware no lo soporta pero el código fuerza el uso de NVLS, se recurrirá a Ring o Tree, pero puede acompañarse de fluctuaciones de rendimiento.nvlsSupportEl campo

de

marca si el hardware soporta NVLS.aggFactorEscenario de trampa 3: configuración del factor de agregación del algoritmo PAT📎 src/include/collectives.h:537-560ElaggFactordel algoritmo PAT

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

Copiar

〔Inferencia de diseño y compensaciones arquitectónicas〕

Para enviar un paquete se puede elegir «entrega exprés en la misma ciudad», «entrega al día siguiente» o «mensajería normal»; la velocidad y el costo son diferentes. Los protocolos de NCCL son precisamente esas «formas de envío»: LL (Low Latency) es adecuado para la transmisión de mensajes pequeños con baja latencia, LL128 es adecuado para la transmisión de mensajes medianos alineados a 128 bytes, y Simple es adecuado para la transmisión de mensajes grandes con alto ancho de banda.

Si no hubiera selección de protocolo, NCCL solo podría mover datos con una única estrategia fija, sin poder lograr un equilibrio entre latencia y ancho de banda.

Estructuras de datos y diseño de memoria

Enumeración de protocolos

📎 src/include/comm.h:55-57Define los umbrales de hilos relacionados con el protocolo:

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

Búfer de protocolo

📎 src/include/comm.h:691-691DefinebuffSizes[NCCL_NUM_PROTOCOLS]——cada protocolo tiene un tamaño de búfer independiente.

Estructura FIFO relacionada con el protocolo

📎 src/include/comm.h:59-83DefinencclSendMemyncclRecvMem：

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

Lógica de selección de protocolo

• Tamaño del mensaje: los mensajes pequeños usan LL, los medianos usan LL128, los grandes usan Simple.
• Topología: las conexiones NVLink son adecuadas para LL128, las conexiones de red son adecuadas para Simple.
• Capacidad de hardware: algunas arquitecturas de GPU tienen optimizaciones para protocolos específicos.

Walkthrough guiado por escenarios: movimiento de datos con el protocolo LL

Supongamos que se usa el protocolo LL para transmitir 1 KB de datos.

Primer paso: los datos se escriben en el búfer de envío

El lado del host escribe los datos ensendbuff, luego actualizancclSendMem.headel puntero, notificando al kernel de GPU que hay nuevos datos.

Segundo paso: el kernel de GPU lee los datos

El kernel de GPU sondeaheadel puntero; tras detectar nuevos datos, lee los datos desdesendbuff.

Tercer paso: transmisión de datos

El kernel de GPU envía los datos al rank de destino a través de NVLink o de la red.

Cuarto paso: el rank de destino recibe los datos

El kernel de GPU del rank de destino escribe los datos enrecvbuff, luego actualizancclRecvMem.tailel puntero.

Quinto paso: el lado del host lee los datos

El lado del host sondeatailel puntero; tras detectar nuevos datos, lee los datos desderecvbuff.

Control de concurrencia e interacción con el hardware

Mecanismo de baja latencia del protocolo LL

Alineación a 128 bytes del protocolo LL128

• Reducir escrituras parciales de línea de caché (Partial Cache Line Write)
• Mejorar la utilización del ancho de banda de memoria
• Simplificar la lógica de procesamiento del hardware

Transmisión por lotes del protocolo Simple

Guía para evitar errores en producción

Escenario problemático uno: desajuste entre protocolo y tamaño de mensaje

Escenario problemático dos: problema de alineación de LL128

Escenario problemático tres: costo del cambio de protocolo

2.5 Capa de transporte transport: canal subyacente de movimiento P2P/SHM/NET/CollNet

Modelo intuitivo

Para ir del punto A al punto B se puede caminar, ir en bicicleta, tomar el metro o tomar un taxi; la capa de transporte de NCCL son esas distintas «formas de desplazamiento». La capa superior no se preocupa por cómo se recorre exactamente, solo por si se puede entregar. P2P es «caminar» (conexión directa entre GPU de la misma máquina), SHM es «ir en bicicleta» (memoria compartida), NET es «tomar el metro» (red), CollNet es «tomar un taxi» (descarga a la tarjeta de red).

Si no existiera la abstracción de la capa de transporte, los algoritmos de la capa superior tendrían que escribir código diferente para cada enlace físico, sin posibilidad de reutilización.

Estructuras de datos y diseño de memoria

Enumeración de la capa de transporte

📎 src/include/transport.h:18-23Define los tipos de capa de transporte:

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

Interfaz de la capa de transporte

📎 src/include/transport.h:129-146DefinencclTransportComm——la interfaz de comunicación de la capa de transporte:

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

Análisis de callbacks clave

• setup: trabajo preparatorio antes de establecer la conexión, intercambio de parámetros de conexión.
• connect: establecimiento real de la conexión.
• free: liberación de los recursos de conexión.
• proxySharedInit: Inicializa los recursos compartidos del hilo proxy.
• proxySetup / proxyConnect: Establecimiento de conexión del lado del hilo proxy.
• proxyProgress: El hilo proxy impulsa la transferencia de datos.
• proxyRegister / proxyDeregister: Registro y anulación de registro de memoria.

Estructura de la capa de transporte

📎 src/include/transport.h:148-154definencclTransport：

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

Instancias de la capa de transporte

📎 src/include/transport.h:36-36declara cuatro instancias de capa de transporte:

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

📎 src/include/transport.h:36-36define el arreglo de capas de transporte:

extern struct ncclTransport* ncclTransports[];

Información de nodos pares

📎 src/include/transport.h:46-74definencclPeerInfo——metadatos intercambiados entre ranks:

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

• hostHashiguales → mismo host → se puede usar P2P o SHM
• hostHashdiferentes → hosts distintos → se debe usar NET
• gdrSupport→ si soporta GPUDirect RDMA
• cudaCompCap→ capacidad de cómputo de la GPU, afecta la selección del protocolo

Walkthrough guiado por escenarios: establecer una conexión P2P

Supongamos que dos ranks están en el mismo host, NCCL selecciona la capa de transporte P2P.

Primer paso: intercambiar PeerInfo

Los dos ranks intercambian a través del canal bootstrapncclPeerInfo, confirman que están en el mismo host y que la GPU soporta P2P.

Segundo paso: llamar a canConnect

📎 src/include/transport.h:148-154decanConnectse invoca el callback, verifica el grafo de topología para confirmar que hay conexión NVLink o PCIe entre las dos GPU.

Tercer paso: llamar a setup

p2pTransport.send.setupyp2pTransport.recv.setupse invocan, preparan los parámetros de conexión (como el handle IPC).

Cuarto paso: llamar a connect

p2pTransport.send.connectyp2pTransport.recv.connectse invocan, establecen la conexión realmente.

Quinto paso: registrar memoria

Si se necesita RDMA, llamar aproxyRegisterpara registrar los búferes de envío y recepción.

Control de concurrencia e interacción con hardware

Capa de transporte P2P

• que las dos GPU estén en el mismo dominio PCIe o dominio NVLink
• que el sistema operativo soporte CUDA IPC
• permisos suficientes

Capa de transporte SHM

Capa de transporte NET

• que el dispositivo de red soporte GPUDirect RDMA (opcional, pero recomendado)
• configuración de red correcta (dirección IP, máscara de subred, etc.)
• ancho de banda de red suficiente

Capa de transporte CollNet

• una tarjeta de red que soporte SHARP
• configuración correcta de SHARP

Guía de prevención de errores en producción

Escenario de error uno: P2P no disponible

Escenario de error dos: configuración de red incorrecta

Escenario de error tres: GPUDirect RDMA no habilitado

2.6 Cómo se combinan las cinco piezas: el ciclo de vida completo de una comunicación

Diagrama de relaciones de combinación

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"]

Ciclo de vida completo

Fase uno: llamada a la API

El usuario llama ancclAllReduce, pasando el búfer de envío, el búfer de recepción, el número de elementos, el tipo de dato, la operación de reducción, el dominio de comunicación y el stream de CUDA.

Fase dos: creación de la tarea

NCCL crea la estructurancclTaskColl(📎 src/include/comm.h:212-273), rellenafunc（AllReduce）、sendbuff、recvbuff、count、datatype、opHosty otros campos.

Fase tres: selección de algoritmo y protocolo

El módulo Tuning selecciona el algoritmo (Ring/Tree/NVLS) y el protocolo (LL/LL128/Simple) según el tamaño del mensaje, la topología y la capacidad del hardware. El resultado de la selección se escribe enncclTaskColldealgorithmyprotocolcampos (📎 src/include/comm.h:227-227）。

Fase cuatro: asignación de canales

Según el algoritmo y el protocolo, se determina el número de canales y el rango de canales a usar.nChannels、channelLo、channelHiEl campo se establece (📎 src/include/comm.h:254-257）。

Fase cinco: selección de la capa de transporte

Según el grafo de topología, se selecciona la capa de transporte (P2P/SHM/NET/CollNet) para cada par de ranks. La información de conexión se almacena enchannels[i].peers[j].

Fase seis: lanzamiento del kernel

NCCL construyencclKernelPlan（📎 src/include/comm.h:357-410), que incluye la cola de trabajo, la cola de limpieza, la cola de tareas, etc. Luego lanza el kernel de GPU.

Fase siete: ejecución de la comunicación

El kernel de GPU lee la FIFO de trabajo y ejecuta las operaciones de transferencia y reducción de datos. El hilo Proxy impulsa asíncronamente la E/S de red.

Fase ocho: finalización

Después de que todos los canales se completen,asyncResultse establece enncclSuccess. El usuario puede consultar el estado mediantencclCommGetAsyncError.

Reflexiones de diseño

¿Por qué se necesitan los cinco componentes?

• ncclComm: resuelve el problema de «quién se comunica con quién».
• channel: resuelve el problema de «cómo paralelizar».
• algorithm: resuelve el problema de «qué topología usar».
• protocol: resuelve el problema de «qué estrategia usar».
• transport: resuelve el problema de «qué enlace físico recorrer».

Se combinan de forma ortogonal, lo que permite a NCCL adaptarse a diversas configuraciones de hardware y tamaños de mensaje sin necesidad de escribir código específico para cada combinación.

Flexibilidad de combinación

• Algoritmo: 5 tipos (Tree/Ring/CollNet/NVLS/PAT)
• Protocolo: 3 tipos (LL/LL128/Simple)
• Capa de transporte: 4 tipos (P2P/SHM/NET/CollNet)

Reflexiones y autoevaluación de este capítulo

---

En el próximo capítulo profundizaremos en la implementación interna dencclCommInitRankpara ver cómo NCCL, partiendo de una estructurancclCommvacía, construye gradualmente el grafo de topología, inicializa los canales, establece las conexiones de transporte y finalmente construye un dominio de comunicación utilizable. El modelo mental de los cinco componentes establecido en este capítulo se materializará uno por uno en el próximo capítulo.

Estas cinco abstracciones no existen de forma aislada: el dominio de comunicación es el contenedor, el canal es la unidad de ejecución paralela, el algoritmo determina cómo se reducen los datos, el protocolo especifica cómo se codifican los datos y la capa de transporte se encarga de cómo se mueven los datos. Su combinación —5 dimensiones, cada una con 3 a 4 opciones— constituye el espacio de búsqueda para el ajuste de rendimiento de NCCL. Entonces, ¿cómo se construye exactamente este objeto de dominio de comunicación desde cero? En el próximo capítulo profundizaremos en la cadena de llamadas de ncclCommInitRank para ver cómo NCCL completa la detección de dispositivos, el descubrimiento de topología y la asignación de canales durante la fase de inicialización, y revelaremos el momento de asignación de campos clave como comm->rank, comm->nRanks y comm->channels.

Capítulo 3: Entrada a la inicialización: cómo ncclCommInitRank convierte un grupo de procesos aislados en un dominio de comunicación

En el capítulo anterior establecimos las cinco abstracciones centrales que recorren todo el libro: ncclComm, channel, algorithm, protocol y transport, que en conjunto constituyen el vocabulario común de «una comunicación = varios channels × un algorithm × un protocol × varios transports». Ahora debemos responder una pregunta más fundamental: ¿cómo se construye realmente este objeto ncclComm desde cero? Cuando llamas a ncclCommInitRank, NCCL necesita completar en unos pocos cientos de milisegundos una serie de operaciones complejas: confirmar que todos los ranks están presentes, intercambiar información de dispositivos, detectar la topología de la máquina, calcular las rutas de datos, asignar memoria de GPU y memoria de host, y finalmente empaquetar todo esto en un objeto ncclComm. Este capítulo seguirá esa cadena de llamadas, descendiendo desde la entrada de la API hasta el último capilar de initTransportsRank.

3.1 Entrada de la API: la capa síncrona y el núcleo asíncrono de ncclCommInitRank

Modelo intuitivo

ncclCommInitRankEn apariencia es «crear un dominio de comunicación», pero en realidad lo que hace es «lanzar una tarea en segundo plano y, por defecto, esperar a que termine». Es como pedir comida en un restaurante: la acción de pedir (la llamada a la API) regresa al instante, pero la cocina (la inicialización real) ocurre en segundo plano. El «modo bloqueante» por defecto solo te hace esperar en el mostrador hasta que la comida esté lista, mientras que el «modo no bloqueante» te da un número de pedido para que puedas ir a hacer otras cosas.

Sin este diseño asíncrono, NCCL no podría coordinarse durante la inicialización con escenarios como la captura de CUDA Graph o la inicialización paralela de múltiples dominios de comunicación; toda inicialización se convertiría en operaciones bloqueantes seriales que no podrían solaparse con el código del usuario.

Estructuras de datos y diseño de memoria

Veamos primero la entrada de la API en sí.ncclCommInitRankEs una capa síncrona extremadamente delgada:

📎 src/init.cc:2946-2970

Hace cuatro cosas: llama ancclInitEnv()carga el plugin de variables de entorno, activa las marcas de rendimiento NVTX, lee el número de dispositivo CUDA actual y luego llama ancclGroupStartInternal()entra en la semántica de group y, finalmente, delega el trabajo real ancclCommInitRankDev。

Atención ancclGroupStartInternal() / ncclGroupEndInternal()este par de llamadas: incluso si solo inicializas un dominio de comunicación, NCCL lo envuelve en la semántica de group. Esto es para manejar de forma unificada el escenario en el que «el usuario inicializa múltiples dominios de comunicación dentro de un group», evitando escribir dos rutas de código para un solo dominio y para múltiples dominios.

La validación real de parámetros y la asignación de objetos están enncclCommInitRankDevdentro de:

📎 src/init.cc:2851-2943

Esta función es la «mesa de despacho central» de toda la cadena. Primero valida parámetros (rango denId, legalidad denranks/myrank), luego asignancclCommla estructura en sí, así como tres campos relacionados con el mecanismo de aborto:abortFlag(indicador atómico del lado del host),abortFlagDev(copia en memoria fija visible desde el lado del dispositivo),abortFlagRefCount(conteo de referencias, porque los subdominios de comunicación creados por split pueden compartir el abortFlag del dominio padre).

Aquí hay un detalle que vale la pena notar:comm->startMagic = comm->endMagic = NCCL_MAGIC：

📎 src/init.cc:2886-2886

este par de valores mágicos actúa como un «sello» colocado al principio y al final de la estructurancclComm. Cualquier escritura fuera de límites o corrupción de la estructura romperá este par de valores mágicos, y las operaciones posteriores pueden detectar el pisoteo de memoria verificándolos. Esta es una protección de integridad de memoria barata pero efectiva.

Step-by-Step Walkthrough

CuandoncclCommInitRankDevllega al final, construye unncclCommInitRankAsyncJobe inicia la tarea asíncrona:

📎 src/init.cc:2896-2929

jobLa estructura contiene todos los parámetros necesarios para la inicialización. Nota quejob->commIdesuna copia, en lugar de referenciar directamente elcommId：

📎 src/init.cc:2903-2910

pasado por el usuario. ¿Por qué copiar? El comentario del código fuente da la respuesta:ncclUniqueIdyncclBootstrapHandletienen requisitos de alineación diferentes; el array pasado por el usuario puede no estar correctamente alineado al límite requerido porncclBootstrapHandle. Copiar a memoria recién asignada garantiza la alineación. Esta es una típica «trampa de compatibilidad ABI»: el usuario vencclUniqueId, pero internamente debe tratarse comoncclBootstrapHandle; ambos tienen el mismo tamaño pero distinta alineación.

Finalmente, según el valor dencclParamEnqueueRearchEnable(), la tarea entra en la cola de gestión o se inicia directamente mediantencclAsyncLaunch:

📎 src/init.cc:2922-2929

ncclAsyncLaunchcrea un nuevo hilo que ejecutancclCommInitRankFunc. Si es modo bloqueante (por defecto), el llamador espera enncclGroupEndInternal()a que este hilo termine; si es modo no bloqueante, el llamador regresa de inmediato y el usuario posteriormente consulta el estado mediantencclCommGetAsyncError.

Reflexiones de diseño

El núcleo del diseño aquí es «API síncrona + implementación asíncrona». ¿Por qué no hacer quencclCommInitRankejecute directamente toda la inicialización de forma síncrona? Porque NCCL necesita soportar el modo no bloqueante dencclCommInitRankConfig, y el modo no bloqueante requiere que la inicialización se ejecute en un hilo en segundo plano. Si la ruta síncrona y la ruta asíncrona fueran dos conjuntos de código, el costo de mantenimiento se duplicaría. Al unificar todo por la vía asíncrona, la ruta síncrona solo es «iniciar y esperar de inmediato», y el código existe en una sola versión.

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: el primer canal de control entre ranks

Modelo intuitivo

Bootstrap es el «grupo de WeChat previo a la reunión» de NCCL. Antes de que comience la comunicación formal, todos los ranks necesitan establecer primero un canal de control para intercambiar metadatos como «quién soy, en qué máquina estoy, qué modelo es mi GPU, cuál es la dirección de mi tarjeta de red». Sin bootstrap, los ranks serían un grupo de extraños que no se conocen entre sí y no podrían coordinar ninguna comunicación.

Si bootstrap falla o expira, toda la inicialización del dominio de comunicación se bloqueará; esta es una de las causas más comunes de cuelgues de NCCL en entornos de producción.

Estructuras de datos y diseño de memoria

El estado central de Bootstrap se guarda enbootstrapStatedentro de la estructura:

📎 src/bootstrap.cc:527-546

Este struct tiene varios campos clave que merecen ser desarrollados:

• ring: una unión, que es o bien un handle de dispositivo de red (net.sendComm/net.recvComm), o bien un par de sockets (socket.send/socket.recv). Esto corresponde a dos modos de bootstrap: el modo predeterminado basado en socket y el modoNCCL_OOB_NET_ENABLEbasado en dispositivo de red.
• listen: información del extremo de escucha, que igualmente tiene dos formas: red y socket.
• peerP2pAddresses / peerProxyAddresses: arreglo de direcciones P2P y direcciones proxy de todos los ranks, rellenado mediante ring allgather.
• unexpectedConnections: una lista enlazada que almacena en caché las conexiones "recibidas pero aún no emparejadas". Este es un diseño clave del protocolo bootstrap, porque el receptor no puede prever quién se conectará primero, así que debe guardar primero las conexiones no emparejadas.
• asyncSendQueue + asyncSendLock + asyncSendCond: cola de envío asíncrono y sus primitivas de sincronización, usadas para envíos concurrentes en modo de cifrado TLS.

bootstrapStateLa asignación de se produce al comienzo debootstrapInit:

📎 src/bootstrap.cc:769-776

Nótese la líneacomm->bootstrap = state: el estado de bootstrap se adjunta al dominio de comunicación, y todas las operaciones posteriores de bootstrap se acceden a través decomm->bootstrap.

Step-by-Step Walkthrough

bootstrapInites la función principal del bootstrap. Desglosémosla en orden de ejecución:

Primer paso: determinar el valor magic.magic es la "señal secreta" de la comunicación bootstrap; solo los ranks que poseen el mismo magic pueden conectarse entre sí.

📎 src/bootstrap.cc:778-788

Si es una inicialización normal (handles != NULL), magic proviene del primer handle; si es split/grow (parent != NULL), magic se deriva mediantehashCombine(parent->magic, parent->childCount). Esto garantiza que cada subdominio de comunicación tenga un magic único.

Segundo paso: crear el socket de escucha.Cada rank necesita dos extremos de escucha: uno para la conexión con el vecino del ring (STATE_LISTEN(state, socket)), y otro para la conexión con el root (listenSockRoot）：

📎 src/bootstrap.cc:797-831

Aquí hay una división clave del trabajo: el socket de escucha del ring usacomm->magic, mientras que el socket de escucha del root usaBOOTSTRAP_HANDLE(handles, curr_root)->magic. ¿Por qué? Porque el root es el coordinador global, todos los ranks deben conectarse a él, así que usa un magic unificado; mientras que los vecinos del ring son punto a punto, con el magic propio del dominio de comunicación es suficiente.

Tercer paso: conexión escalonada.Cuando el número de ranks es muy grande, que todos los ranks se conecten al root al mismo tiempo causaría una tormenta de conexiones. NCCL usaNCCL_UID_STAGGER_RATEyNCCL_UID_STAGGER_THRESHOLDpara controlar el escalonamiento:

📎 src/bootstrap.cc:833-843

Cuando el número de ranks a cargo de un root supera el umbral (por defecto 256), cada rank calcula los microsegundos de retardo según su ID local bajo el root, y luego duerme. Esta es una limitación de tasa simple pero efectiva al estilo "token bucket".

Cuarto paso: enviar al root la propia información de conexión.Cada rank envía su dirección de escucha al root:

📎 src/bootstrap.cc:845-867

Después de que el root recibe la información de todos los ranks, realiza un "emparejamiento en anillo": envía la dirección del rank i al rank i-1, y la dirección del rank i+1 al rank i. Así cada rank conoce a sus vecinos anterior y posterior en el ring.

Quinto paso: establecer la conexión del ring.Cada rank se conecta a su vecino "siguiente", y al mismo tiempo acepta la conexión del vecino "anterior":

📎 src/bootstrap.cc:885-894

AquísocketRingConnectinternamente usabootstrapConcurrent——en modo de cifrado TLS, connect y accept deben ejecutarse concurrentemente, de lo contrario se produciría un deadlock (porque el handshake TLS requiere la participación simultánea de ambas partes). En modo sin cifrado, se ejecuta connect y luego accept de forma serial.

Sexto paso: AllGather de todas las direcciones.Una vez establecido el ring, medianteringAllInfose hace un allgather de las direcciones P2P, direcciones proxy y direcciones UDS de todos los ranks:

📎 src/bootstrap.cc:934-938

ringAllInfointernamente llama abootstrapAllGather, que en modo socket usasocketRingAllGather——un algoritmo de ring allgather bidireccional, donde N ranks solo necesitan N/2 pasos:

📎 src/bootstrap.cc:1363-1412

Este algoritmo bidireccional es la optimización clave del rendimiento del bootstrap. El ring allgather unidireccional tradicional necesita N-1 pasos; la versión bidireccional reduce los pasos a la mitad. Cada paso envía y recibe datos simultáneamente en ambas direcciones, usandosocketDoubleSendRecvpara empaquetar 4 operaciones (2 envíos y 2 recepciones) en una sola llamada al sistema.

Control de concurrencia e interacción de bajo nivel

El control de concurrencia del Bootstrap tiene varios niveles:

Primer nivel: verificación de abort.Todos los bucles bloqueantes verifican periódicamente abortFlag:

📎 src/bootstrap.cc:150-159

BOOTSTRAP_N_CHECK_ABORTSe establece en 10000, lo que significa que se verifica el indicador de abort cada 10000 iteraciones. Este número es un compromiso entre rendimiento y capacidad de respuesta: verificar con demasiada frecuencia afecta el rendimiento, y verificar muy poco provoca retardo en la respuesta al abort.

Segundo nivel: cola de envío asíncrono.En modo de cifrado TLS,bootstrapSendno puede ejecutarse de forma síncrona (porque el handshake TLS requiere que el receptor también participe), así que NCCL coloca la operación de envío en un hilo independiente:

📎 src/bootstrap.cc:1161-1217

Aquí hay un mecanismo ingenioso de garantía de orden.bootstrapAsyncSendMainAntes de enviar, se verifica si en la cola hay "envíos anteriores dirigidos al mismo (peer, tag)":

📎 src/bootstrap.cc:1124-1152

¿Por qué es necesario garantizar el orden de envío para el mismo (peer, tag)? Los comentarios del código fuente lo explican con claridad: el receptor empareja conexiones por (peer, tag), y si dos mensajes enviados al mismo (peer, tag) llegan en orden invertido, el receptor los emparejará incorrectamente. Durante la inicialización de NVLS se difunde múltiples veces al mismo peer con el mismo tag, por lo que esta garantía de orden es imprescindible.

Tercera capa: cola de conexiones inesperadas.El receptor no puede predecir quién se conectará primero, así quesocketAcceptalmacena las conexiones no coincidentes en unaunexpectedConnectionslista enlazada:

📎 src/bootstrap.cc:1276-1300

Este diseño resuelve un problema distribuido clásico: múltiples ranks pueden iniciar conexiones hacia ti simultáneamente, pero tubootstrapRecvorden de llamadas es fijo. Si las conexiones no coincidentes se descartaran directamente, el emisor agotaría el tiempo de espera; si se bloqueara la espera, podría producirse un interbloqueo. Almacenarlas en una cola es la opción más segura.

Guía para evitar problemas en producción

Problema uno: el tiempo de espera de bootstrap provoca que la inicialización se cuelgue.Si algún rank no puede conectarse al root por problemas de red, todos los demás ranks esperarán indefinidamente enncclSocketAcceptoncclSocketRecv. NCCL no tiene un mecanismo de tiempo de espera de bootstrap incorporado; la única vía de escape es abortFlag. En entornos de producción se recomienda configurarNCCL_UID_STAGGER_RATEpara mitigar la tormenta de conexiones en clústeres a gran escala.

Problema dos:NCCL_COMM_IDconflicto con múltiples handle.Cuando el usuario configura laNCCL_COMM_IDvariable de entorno, NCCL fuerza a reducirnIda 1:

📎 src/init.cc:2912-2921

Esto significa quencclCommInitRankScalablela característica de múltiples handle queda silenciosamente deshabilitada. Si estás usando inicialización scalable y además configurasNCCL_COMM_ID, el comportamiento será diferente de lo que esperas.

Problema tres: interbloqueo en modo TLS.En modo de cifrado TLS, si connect y accept no se ejecutan de forma concurrente, ambas partes se quedarán atascadas en el handshake TLS.bootstrapConcurrentEsto es precisamente para resolver ese problema:

📎 src/bootstrap.cc:648-669

En modo no cifrado se ejecuta en serie (primero send, luego recv); en modo cifrado se lanza un hilo para manejar el send y el hilo principal maneja el 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: el esqueleto de memoria del objeto de dominio de comunicación

Modelo intuitivo

commAllocEs la "entrega en obra gris" del dominio de comunicación: asigna la memoria de la estructura, inicializa todos los campos a valores predeterminados seguros, crea los objetos CUDA y las primitivas de sincronización necesarias, pero aún no ha rellenado la información de topología, la configuración de canales ni las conexiones de transporte, que serían la "decoración de interiores". Si comparamosncclCommcon un edificio,commAllocsería echar los cimientos y levantar la estructura,initTransportsRanksería la decoración interior.

Si no existiera la inicialización decommAlloc, el código posterior accedería a campos no inicializados provocando comportamientos impredecibles; por ejemplo, sicomm->channels[c].idtuviera un valor aleatorio, la lógica de inicialización de canales juzgaría erróneamente el estado del canal.

Estructura de datos y diseño de memoria

commAllocLa firma y validación inicial de

📎 src/init.cc:512-526

Primero valida la legalidad dendevyrank, luego construye dos pilas de memoria (memPermanentymemScoped), configurarankynRanks. Estas dos pilas de memoria son la infraestructura de gestión de memoria de NCCL:memPermanentse usa para asignaciones cuyo ciclo de vida es igual al del dominio de comunicación,memScopedse usa para asignaciones temporales.

A continuación viene la detección del dispositivo CUDA:

📎 src/init.cc:528-531

cudaGetDeviceobtiene el número de dispositivo actual,ncclCudaCompCapobtiene la capacidad de cómputo. El comentario del código fuente lo dice sin rodeos: "Try to create a CUDA object right away. If there is something wrong with the device we're on, better know it early." — exponer los problemas del dispositivo cuanto antes, para evitar descubrirlos en una fase tardía de la inicialización.

Luego viene la asignación o herencia de recursos compartidos:

📎 src/init.cc:533-555

Aquí hay una bifurcación importante: siparent == NULL || !parent->shareResources, se crea un nuevoncclSharedResources; de lo contrario, se heredan los recursos compartidos del dominio de comunicación padre y se incrementa el contador de referencias.ncclSharedResourcesincluye device stream, host stream, eventos de lanzamiento, eventos de scratch, etc. — estos recursos pueden reutilizarse en escenarios de split por los subdominios de comunicación, evitando creaciones duplicadas.

Nótese la líneasharedRes->refCount = 1— el contador de referencias inicial es 1, se incrementa cada vez que se comparte en un split, y solo se destruye realmente cuando se libera la última referencia.

A continuación viene la inicialización de red, RMA y GIN:

📎 src/init.cc:547-549

Estos tres subsistemas se encargan respectivamente de la transmisión por red, el acceso remoto a memoria y la comunicación por red iniciada por la GPU. Su orden de inicialización es importante:ncclNetInitdebe ir antes dencclRmaInit, porque RMA depende del plugin de red.

Inicialización del gestor de memoria:

📎 src/init.cc:567-576

Igualmente hay dos rutas: compartir o crear nuevo.ncclMemManagerse encarga de gestionar el pool de memoria CUDA y la caché de registros.

Marcador de inicialización de canales:

📎 src/init.cc:607-608

Esta línea pone elidde todos los canales a -1, indicando "no inicializado". PosteriormentesetupChannelcomprobará este valor para decidir si es necesaria la inicialización.

Construcción de las colas de interrupción:

📎 src/init.cc:619-632

NCCL utiliza colas intrusivas (intrusive queue) para gestionar diversas tareas. Estas colas se construyen todas vacías en la fase decommAlloc, y las tareas posteriores las usan directamente al encolarse.

Creación del pool de memoria CUDA:

📎 src/init.cc:636-652

Si el dispositivo soporta pool de memoria (cudaDevAttrMemoryPoolsSupported), se crea un pool de memoria de tipo pinned y se establece el umbral de liberación al valor máximo (~uint64_t(0)), es decir, "nunca liberar automáticamente". Esto es para evitar que el runtime de CUDA reclame memoria sin que NCCL lo sepa.

Step-by-Step Walkthrough

Sigamos un escenario de inicialización concreto: una sola máquina con 8 GPUs, un rank por proceso, inicialización normal.

1. commAlloc(comm, NULL, 8, rank)es invocado,parent == NULL。

2. La validación pasa,comm->rank = rank，comm->nRanks = 8。

3. cudaGetDevicedevuelve el número de dispositivo actual,comm->compCapqueda configurado.

4. Se crea un nuevoncclSharedResources, con contador de referencias 1.

5. ncclNetInitInicializar el plugin de red (posiblemente Socket o IB).

6. ncclMemManagerInitCrear el gestor de memoria.

7. getBusIdObtener el ID del bus PCI,ncclNvmlDeviceGetHandleByPciBusIdObtener el handle de NVML.

8. dmaBufSupportedDetectar soporte de DMA-BUF.

9. AsignarconnectSend / connectRecvel arreglo de bitmap.

10. Todos los canalesidse establecen en -1.

11. Construir todas las colas de interrupción.

12. Crear el pool de memoria CUDA.

Reflexiones de diseño

commAllocEl diseño más interesante es el principio de "fallar lo antes posible". Llama acudaGetDeviceal inicio de la función, en lugar de esperar hasta que se necesite información del dispositivo más adelante. La ventaja de esto es que: si el dispositivo tiene problemas (por ejemplo, está siendo utilizado exclusivamente por otro proceso), el error se expondrá temprano durante la inicialización, en lugar de descubrirse después de asignar una gran cantidad de memoria.

Otro diseño es la inicialización depreconnectNext:

📎 src/init.cc:598-598

reinterpret_cast<struct ncclComm*>(0x1)Es un valor centinela utilizado para marcar el estado de "próxima preconexión". Esta técnica de usar un valor de puntero inválido como marcador de estado es muy común en programación de sistemas — ahorra más memoria que un campo booleano adicional, pero requiere cuidado para no desreferenciarlo.

3.4 initTransportsRank: Descubrimiento de topología y asignación de canales

Modelo intuitivo

initTransportsRankEs el "corazón" de la inicialización. Hace tres cosas importantes: intercambiar la información de dispositivos y topología de todos los ranks mediante dos AllGather; calcular las estructuras de grafo de algoritmos como ring/tree/collnet/nvls basándose en esa información; y finalmente establecer todas las conexiones de transporte. Si comparamos el dominio de comunicación con el sistema de tráfico de una ciudad,initTransportsRankes el proceso de planificar todas las carreteras, pasos a desnivel y rutas de autobús.

Sin este paso, NCCL no sabría por qué camino deben ir los datos — podría hacer que los datos tomen un camino más largo, o simplemente no encontrar una ruta alcanzable.

Estructuras de datos y diseño de memoria

initTransportsRankTiene muchísimas variables locales, veamos las clave:

📎 src/init.cc:1163-1179

Aquí se extraencomm->graphslas distintas estructuras de grafo del arreglo y se crean alias.graphsEl arreglo está indexado por algoritmo, nótese quenvlsGraphse usa dos veces (NVLS y NVLSTree comparten la misma estructura de grafo).

Dos estructuras temporales clave:

📎 src/init.cc:1181-1206

graphInfoAlmacena la información de grafo de un solo rank para un algoritmo determinado (número de canales, ancho de banda, tipo, etc.),allGatherInfoEs la unidad de datos del AllGather, contiene la información de grafo de todos los algoritmos más la información de rank de topología.

Step-by-Step Walkthrough

Fase uno: AllGather1 — intercambio de información de dispositivos.

📎 src/init.cc:1234-1239

Cada rank llama afillInfopara llenar su propioncclPeerInfo, luego mediantebootstrapAllGatherse intercambia.fillInfoLa información que se llena incluye: número de rank, número de dispositivo CUDA, número de dispositivo NVML, versión de NCCL, git hash, host hash, process hash, GPU UUID, ID de bus, tamaño de memoria de video, versión de driver, etc.

📎 src/init.cc:888-982

Nóteseinfo->hostHash = getHostHash() + commHashyinfo->pidHash = getPidHash() + commHash— tanto host hash como pid hash tienen añadido el commHash. Esto es para distinguir diferentes dominios de comunicación en la misma máquina.

Después de completar el AllGather, cada rank recorre la información de todos los peers y calcula propiedades globales:

📎 src/init.cc:1250-1303

Este bucle hace muchas cosas: detecta incompatibilidad de versiones, cuenta el número de nodos, calcula la intersección decuMemSupport, detecta si múltiples ranks usan la misma GPU, calcula la intersección de máscaras de tipo GIN, etc. NótesenNodesla forma de contar — incrementa cada vez que encuentra un hostHash diferente, esto asume que los ranks están ordenados consecutivamente por nodo.

Fase dos: Descubrimiento de topología.

📎 src/init.cc:1390-1403

Estos seis pasos son el flujo central del descubrimiento de topología:ncclTopoGetSystemEnumera los dispositivos del sistema para construir el grafo de topología,ncclTopoComputePathsCalcula las rutas de GPU a NIC,ncclTopoTrimSystemElimina dispositivos inalcanzables, vuelve a calcular rutas,ncclTopoSearchInitInicializa el estado de búsqueda, finalmente imprime la topología.

Fase tres: Cálculo de grafos.

📎 src/init.cc:1421-1468

Calcula secuencialmente los cinco grafos: ring, tree, collnet chain, collnet direct, nvls. Cada grafo tiene diferentes restricciones de pattern y número de canales. NótesetreeGraph->minChannels = ringGraph->nChannels— el número de canales de tree se restringe para ser igual al de ring, esto es para garantizar la alineación de canales entre diferentes algoritmos.

Fase cuatro: AllGather3 — intercambio de información de grafos.

📎 src/init.cc:1490-1533

Cada rank llena su información de grafo enallGather3Data[rank], luego nuevamentebootstrapAllGather. La información intercambiada esta vez incluye: pattern/nChannels/bwIntra/bwInter/typeIntra/typeInter/crossNic de cada algoritmo, arquitectura de CPU, número de canales P2P, número de dispositivos de red, número de dispositivos CollNet, etc.

Después de completar AllGather3, cada rank recorre la información de grafo de todos los peers, tomando el mínimo/máximo para alinear:

📎 src/init.cc:1687-1703

Nótese la estrategia de alineación aquí:nChannels、sameChannels、bwIntra、bwInterSe toma el mínimo,typeIntra、typeInter、crossNicSe toma el máximo. ¿Por qué? Porque el número de canales y el ancho de banda están limitados por el enlace más débil, mientras que el tipo y crossNic necesitan tomar la unión para garantizar compatibilidad.

Fase cinco: Establecer conexiones de transporte.

📎 src/init.cc:1811-1892

Aquí hay dos ramas:runtimeConnCuando es verdadero, solo se hace setup de canales sin establecer conexiones (se pospone la conexión hasta el tiempo de ejecución), de lo contrario se establecen todas las conexiones inmediatamente. El orden de conexión es: ring → tree → NVLS → PAT → NVLS tree → CollNet.

Control de concurrencia e interacción con hardware

initTransportsRankHay varios puntos notables de concurrencia/interacción con hardware en :

Configuración de afinidad de CPU:

📎 src/init.cc:1406-1412

NCCL vincula el hilo actual a un núcleo de CPU cercano a la GPU, asegurando que la asignación de memoria del host sea del nodo NUMA local. Esto reduce la latencia de acceso entre nodos NUMA.

Inicialización de NVLS:

📎 src/init.cc:1419-1419

ncclNvlsInitDetecta el soporte de NVLink SHARP. NVLS permite que el switch ejecute directamente operaciones de reducción, reduciendo drásticamente la latencia de AllReduce.

Creación del hilo Proxy:

📎 src/init.cc:1780-1786

El hilo Proxy se encarga de impulsar asíncronamente la E/S de red. Se crea eninitTransportsRanky posteriormente todas las operaciones de red se realizan a través del proxy.

Guía de prevención de errores en producción

Error uno: Número de dispositivos de red no coincidente.Si el número de NICs locales difiere entre distintos ranks, NCCL reportará un error:

📎 src/init.cc:1576-1596

A menos que se configureNCCL_IGNORE_NET_MISMATCH=1. Esto es común en clústeres heterogéneos — algunos nodos tienen 8 NICs, otros solo 4. Ignorar la falta de coincidencia puede degradar el rendimiento, ya que el número de canales quedará limitado por el nodo más débil.

Error dos: Múltiples ranks compartiendo la misma GPU.Si dos ranks tienen el mismo UUID de GPU, NCCL rechazará la inicialización:

📎 src/init.cc:1291-1296

A menos que se configureNCCL_MULTI_RANK_GPU_ENABLE=1. Esta verificación previene problemas de rendimiento causados por configuraciones erróneas del usuario.

Error tres: Número insuficiente de nodos para CollNet.CollNet requiere al menosNCCL_COLLNET_NODE_THRESHOLDnodos para habilitarse:

📎 src/init.cc:1720-1728

El umbral predeterminado es 2. En entornos de un solo nodo, CollNet se deshabilita automáticamente.

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: La magia en tiempo de compilación del sistema de variables de entorno

Modelo intuitivo

NCCL_PARAMEs la "fábrica de interruptores de configuración" de NCCL. Utiliza macros para generar una función en tiempo de compilación, que en la primera llamada en tiempo de ejecución lee la variable de entorno y almacena el resultado en caché. Esto es como un interruptor de luz en casa — lo accionas (llamas a la función), la luz se enciende (devuelve el valor de configuración), y luego el estado del interruptor queda memorizado, sin necesidad de volver a accionarlo cada vez.

Sin este mecanismo, NCCL tendría que llamar manualmente agetenvy analizar la cadena en cada lugar donde se use la configuración, lo que haría el código extremadamente verboso y propenso a errores.

Estructura de datos y diseño de memoria

NCCL_PARAMDefinición de la macro

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

Esta macro, al expandirse, genera una funciónncclParam##name(), con tres variables estáticas internas:

• uninitialized = INT64_MIN: valor centinela, que indica "aún no inicializado".
• noCache: indicador de tres estados, -1 indica no inicializado, 0 indica almacenar en caché, 1 indica no almacenar en caché.
• cache: el valor almacenado en caché, inicialmenteuninitialized。

La lógica de la función es: sicachesigue siendouninitialized, llamar ancclLoadParampara cargar; de lo contrario, devolver directamentecache。COMPILER_EXPECT(..., false)indica al compilador que esta rama rara vez se ejecuta, optimizando la ruta caliente.

ncclLoadParamImplementación de

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

Protege todo el proceso de carga con un mutex, primero verifica la política denoCache, luego comprueba si la caché es válida, y después lee la variable de entorno y la analiza. Si el análisis falla, usa el valor predeterminado e imprime una advertencia.

Step-by-Step Walkthrough

TomandoNCCL_PARAM(BuffSize, "BUFFSIZE", -2)como ejemplo:

📎 src/init.cc:1007-1007

Tras la expansión de la macro se genera:

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

En la primera llamada,cache == uninitialized, entra enncclLoadParam. Lee la variable de entornoNCCL_BUFFSIZE, y si no está configurada, devuelve el valor predeterminado -2. Luego, según la política denoCache, decide si almacenar en caché.

noCacheLa política dencclParamIsCacheDisabledse determina por

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

Si el nombre de la variable de entorno coincide con algún patrón (por ejemplo, termina en_), no se almacena en caché y se relee cada vez. Esto permite al usuario modificar dinámicamente ciertas configuraciones en tiempo de ejecución.

Reflexión sobre el diseño

Lo ingenioso de este diseño es la "abstracción de costo cero": en la ruta caliente solo hay una carga atómica y una comparación, sin bloqueos ni análisis de cadenas. Solo la ruta fría (primera carga) paga el costo completo.COMPILER_EXPECTIndica al compilador que coloque la ruta caliente al frente de la caché de instrucciones, mejorando aún más el rendimiento.

Otro aspecto del diseño es el esquema de tres estados denoCache. -1 significa "aún no decidido", 0 significa "almacenar en caché", 1 significa "no almacenar en caché". Esta decisión se toma solo una vez en la primera carga y no cambia después.

Guía de prevención de errores en producción

Error uno: Errores tipográficos en variables de entorno.Si el usuario escribeNCCL_BUFSIZEen lugar deNCCL_BUFFSIZE, NCCL no reportará error, solo usará el valor predeterminado. Se recomienda usarNCCL_DEBUG=ENVpara ver todas las variables de entorno reconocidas.

Error dos: Orden de carga deNCCL_CONF_FILE.NCCL carga secuencialmente$NCCL_CONF_FILE(o~/.nccl.conf) y/etc/nccl.conf：

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

Los archivos cargados después sobrescriben a los cargados antes. Si ambos archivos configuran la misma variable,/etc/nccl.confel valor de

prevalecerá.noCacheError tres: Seguridad de hilos de la variable.

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

El comentario en el código fuente dice "noCache is only load/stored within the mutex, no need for atomic":noCacheEsto significa que la lectura y escritura decacheestán protegidas por el mutex, sin necesidad de operaciones atómicas. Pero la lectura de

es sin bloqueo (ruta caliente), por lo que se usa carga atómica.

3.6 devCommSetup: Mapear el dominio de comunicación al dispositivo

devCommSetupModelo intuitivoncclCommEs la "proyección del lado del dispositivo" del dominio de comunicación. Los kernels de GPU se ejecutan en el dispositivo y no pueden acceder directamente a la estructurancclDevCommen la memoria del host. Por lo tanto, NCCL necesita copiar los campos clave del dominio de comunicación a memoria accesible por el dispositivo, formando

. Esto es como fotocopiar la guía telefónica de la empresa y colocarla en el escritorio de cada empleado — el empleado no tiene que ir cada vez a recepción a preguntar el teléfono de un colega.devCommSetupSin

, el kernel de GPU no podría conocer su rank, configuración de canales, tamaño de búfer, etc., y el kernel de comunicación colectiva simplemente no podría iniciarse.

devCommSetupEstructura de datos y diseño de memoriancclKernelCommAndChannelsUtiliza una estructura temporal

📎 src/init.cc:712-746

para empaquetar los datos que se copiarán al dispositivo:ncclDevCommEsta estructura contienecudaMemcpyAsync(dominio de comunicación del lado del dispositivo) y el arreglo de canales. La función primero llena la estructura temporal con los datos del lado del host, y luego realiza una copia

al dispositivo de una sola vez.

📎 src/init.cc:734-746

Llenado de campos clave:comm->devComm = &devCommAndChans->commNótese quecomm->devComm— elncclDevCommdel lado del host apunta acomm->devCommen la memoria del dispositivo. Posteriormente, al lanzar el kernel, se pasará

Relleno de la información de canales:

📎 src/init.cc:829-843

Los punteros peers, ring, tree, collnetChain, collnetDirect y nvls de cada canal se copian al lado del dispositivo. Notaring.userRanksse necesita una copia adicional decudaMemcpyAsync, porque es un arreglo.

Step-by-Step Walkthrough

1. Obtener el flujo del dispositivo:ncclStrongStreamAcquireObtener un flujo fuerte (strong stream) para asegurar que las copias asíncronas posteriores se ejecuten en orden.

2. Asignar memoria del dispositivo:ncclCudaCallocAsyncAsignardevCommAndChans。

3. Rellenar la estructura temporal del lado del host: establecer rank, nRanks, node, nNodes, abortFlag, buffSizes, etc.

4. Asignar y copiar el arreglorankToLocalRank.

5. CalcularworkFifoBytes: se decide según el estado de CC (Confidential Computing).

6. Asignar el búfer workFifo: en modo GDR usarncclGdrCudaCalloc, de lo contrario usarncclCudaHostCalloc。

7. Asignar los contadores del profiler.

8. Asignar los contadores de progreso (si están habilitados).

9. Rellenar la información de canales.

10. Copiar de una sola vez al dispositivo:ncclCudaMemcpyAsync(devCommAndChans, &tmpCommAndChans, 1, deviceStream)。

11. Liberar el flujo fuerte y sincronizar.

Reflexiones de diseño

devCommSetupEl diseño más notable en es la "copia por lotes". NCCL no llama a por separado para cada campocudaMemcpy, sino que empaqueta todos los campos en una estructura temporal y realiza una solacudaMemcpyAsync. Esto reduce drásticamente el número de llamadas a la API de CUDA y la sobrecarga de sincronización.

Otro diseño es el manejo de CC deworkFifoBytes:

📎 src/init.cc:750-763

En modo CC (Confidential Computing),workFifoBytesse establece en 0, porque la copia GDR no está disponible en modo CC. Esta es una degradación elegante ante una limitación de hardware.

Guía de prevención de errores en producción

Error uno:devCommSetupdebe llamarse antes de la barrera.Los comentarios del código fuente explican la razón:

📎 src/init.cc:1950-1952

Si se llama después de la barrera, puede que algunos hilos ya hayan comenzado a lanzar el kernel de NCCL, y en ese momento la memoria del dispositivo aún no se ha asignado por completo, lo que provocará un interbloqueo.

Error dos:workFifoBytesdebe ser una potencia de 2.Si no lo es, NCCL emitirá una advertencia y usará el valor predeterminado:

📎 src/init.cc:757-762

Reflexiones y autoevaluación de este capítulo

En el próximo capítulo profundizaremos en el descubrimiento de topología y la búsqueda en grafos, para ver cómo NCCL enumera las GPU, las tarjetas de red y los switches PCI de la máquina, construye un grafo de topología completo y busca en él las estructuras óptimas de ring y tree. La comunicación bootstrap, el esqueleto de memoria commAlloc y el flujo principal initTransportsRank establecidos en este capítulo se desplegarán uno a uno en sus detalles de topología en el próximo capítulo.

Hasta aquí, hemos recorrido por completo la cadena de llamadas de ncclCommInitRank y visto con claridad todo el proceso de construcción del objeto ncclComm desde cero. Pero hay un paso clave durante la inicialización que solo hemos rozado de pasada: ¿cómo detecta NCCL las GPU y las tarjetas de red dentro de la máquina y, en función de ello, decide por qué ruta deben ir los datos? Este es precisamente el tema que se profundizará en el próximo capítulo: descubrimiento de topología y búsqueda en grafos. Desglosaremos cómo src/graph/topo.cc enumera los dispositivos PCI/NVLink/tarjetas de red y construye el grafo de topología, cómo src/graph/search.cc busca la ruta óptima en dicho grafo, y cómo src/graph/rings.cc y trees.cc concretan los resultados de búsqueda en las topologías de los algoritmos Ring y Tree. Una vez comprendido este mecanismo, entenderás por qué NCCL puede seleccionar automáticamente el algoritmo adecuado en distintas máquinas.

Capítulo 4: Descubrimiento de topología y búsqueda en grafos: cómo NCCL "ve" la interconexión física de un sistema multi-GPU

En el capítulo anterior descendimos capa por capa a lo largo de la cadena de llamadas de ncclCommInitRank y vimos cuándo se rellena el campo comm->topo, pero no desplegamos su estructura interna. Entonces, ¿cómo "ve" exactamente NCCL las GPU y las tarjetas de red de la máquina y las organiza en información de topología utilizable? Este capítulo desglosará los tres pasos clave de este proceso: topo.cc se encarga de enumerar los dispositivos físicos en un grafo, search.cc busca la ruta óptima en dicho grafo, y rings.cc y trees.cc concretan los resultados de búsqueda en las dos topologías de algoritmos Ring y Tree. Solo comprendiendo la cooperación entre estos tres se puede entender por qué NCCL puede seleccionar automáticamente el algoritmo adecuado en distintas máquinas.

Grafo de topología: dibujar la máquina como un "mapa de líneas de metro"

Modelo intuitivo

Imagina que eres un repartidor que acaba de llegar a una ciudad desconocida. Tienes que llevar un paquete del punto A al punto B, pero no sabes qué camino es el más rápido. Necesitas un mapa: en él están marcadas todas las estaciones (GPU, tarjetas de red, CPU, switches PCI) y las conexiones entre estaciones (NVLink, PCIe, red). El grafo de topología de NCCL es ese mapa.

Sin este mapa, NCCL solo puede suponer ciegamente que "todas las GPU tienen el mismo ancho de banda"; en una máquina de 8 tarjetas totalmente interconectadas por NVLink quizá aún se pueda apañar, pero en cuanto se enfrenta a topologías complejas con cruce de NUMA, cruce de switches PCI o mezcla de NVLink + PCIe, elegirá la ruta incorrecta y meterá por PCIe lento datos que deberían ir por NVLink, con una caída directa del rendimiento a la mitad.

Estructuras de datos y diseño de memoria

El núcleo del grafo de topología esncclTopoSystem, que almacena todos los dispositivos agrupados por tipo de nodo. Los tipos de nodo se definen en el arraytopoNodeTypeStr:

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

Estos tres arrays definen respectivamente las representaciones de cadena de los tipos de nodo, los tipos de enlace y los tipos de ruta. Nótese el orden detopoPathTypeStr: también actúa como ordenación de la calidad de las rutas: cuanto menor es el índice, más rápida es la ruta.LOC(local) es la más rápida,DIS(desconectado) es la más lenta. Este orden se usará repetidamente en las búsquedas posteriores para comparar la calidad de las rutas.

Cada nodo está representado porncclTopoNodey al crearse inicializa campos diferentes según su tipo. Tomemos como ejemplo un nodo 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) {
    ...

Aquí hay varios puntos de diseño clave. Primero, los nodos se almacenan en un array preasignado (system->nodes[type].nodes), en lugar de una lista enlazada. Esto significa que los nodos están dispuestos de forma contigua en memoria, lo que favorece la caché durante el recorrido. Segundo,NCCL_TOPO_MAX_NODESes un límite máximo estricto; si se supera, se produce un error; esto evita un crecimiento infinito ante anomalías topológicas. Tercero, cada nodo tiene un campoidque es un entero de 64 bits, donde los 32 bits superiores son el systemId (identifica qué host) y los 32 bits inferiores son el localId (número de dispositivo dentro del host).

Las conexiones entre nodos están representadas porncclTopoLink.ncclTopoConnectNodesse encarga de establecer conexiones bidireccionales:

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

Esta función hace tres cosas. Primero, busca si ya existe un enlace hacia el mismo destino y del mismo tipo; si existe, acumula el ancho de banda (link->bw += bw). Esto maneja el caso de múltiples NVLink conectados al mismo GPU: 4 NVLink de 25 GB/s cada uno, tras agregarse dan 100 GB/s. Segundo, si no lo encuentra, añade un nuevo enlace. Tercero, tras insertar, ordena de forma descendente por ancho de banda, de modo que en recorridos posteriores se vean primero los enlaces de mayor ancho de banda.

Recorrido paso a paso guiado por escenarios

Ahora pongámonos en un escenario concreto: un servidor A100 de 8 tarjetas, donde cada tarjeta está totalmente interconectada mediante NVLink, y además hay 4 tarjetas de red Mellanox ConnectX-6 insertadas en ranuras PCIe. Durante la inicialización de NCCL,ncclTopoGetSystemes invocado; lee la información de dispositivos desde un archivo XML (generado pornvidia-topologydo por el propio NCCL) y luego construye el grafo de topología.

Primer paso, analizar el nodo CPU.ncclTopoAddCpulee desde el XML la arquitectura, el fabricante y el modelo de la CPU, y crea el nodo 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;
}

El nodo CPU es la raíz del árbol de topología. Debajo de cada CPU cuelgan el subárbol PCI y los nodos NIC.ncclTopoAddPciprocesa recursivamente el árbol PCI; al encontrar un GPU crea un nodo GPU, y al encontrar un NIC crea un nodo NIC.

Segundo paso, añadir conexiones NVLink. Nótese quencclTopoAddGpusolo lee los atributos básicos del GPU; el comentario dice explícitamente "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;
}

¿Por qué dividir en dos pasadas? Porque NVLink es una conexión entre GPUs y se necesita que los nodos GPU de ambos extremos ya existan para poder establecer el enlace. La primera pasada crea todos los nodos; la segunda pasadancclTopoAddNvLinkslos conecta.

Tercer paso, procesar los dispositivos de red.ncclTopoAddNicrecorre los subnodos net/gin/rma bajo el NIC y llama respectivamente a las funciones de añadido correspondientes. Tomemos como ejemploncclTopoAddNet:

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

Nótese la conversiónmbps / 8000.0: mbps son megabits por segundo; al dividir entre 8000 se obtiene GB/s (porque 1 GB/s = 8000 Mbps). Si la tarjeta de red informa speed = -1 (algunas tarjetas de red virtuales lo hacen), se asume por defecto 10000 Mbps = 1.25 GB/s.

Cuarto paso, procesamiento final.ncclTopoGetSystemFromXmldespués de completar la adición de todos los nodos y enlaces, también realiza varias tareas de limpieza:

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

ncclTopoFlattenBcmSwitchesmaneja el caso especial de los switches PCIe Broadcom Gen4: se presentan como switches de dos capas, pero en realidad son de ancho de banda completo, y hay que "aplanarlos" para evitar que el algoritmo de búsqueda se vea inducido a error.ncclTopoConnectCpusinterconecta todos los nodos CPU entre sí (el acceso entre NUMA va por enlaces SYS).ncclTopoSortSystemordena los enlaces para que los enlaces descendentes PCI queden delante y facilitar el recorrido.

Reflexiones de diseño y trampas en producción

Trampa uno:ncclTopoGetNodeno reporta error cuando no encuentra un nodo.Véase esta función:

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

Si no lo encuentra, devuelvencclSuccesspero*nodepermanece sin cambios (el llamador normalmente lo inicializa a NULL). El llamador debe comprobar por sí mismo*node == NULL. Este diseño facilita pasar por alto la comprobación: si el llamador olvida verificarla, una desreferencia posterior provocará un fallo.

Trampa dos:ncclTopoConnectNodesla acumulación de ancho de banda puede provocar desbordamiento.Si hay una gran cantidad de enlaces entre el mismo par de nodos (por ejemplo, en escenarios NVSwitch),link->bw += bwpuede acumularse hasta un valor muy grande. Aunque la precisión de float es suficiente, si el número de enlaces es anormalmente alto, la lógica de ordenamiento puede fallar.

Trampa tres:ncclTopoRemoveNodela corrección de punteros enAl eliminar un nodo, todos los enlaces que apuntan al nodo eliminado deben eliminarse, y los punteros que apuntan a nodos posteriores al nodo eliminado deben desplazarse hacia delante:

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

Aquí hay una sutileza:node->links[l].remNode--está corrigiendo punteros. Como los nodos se almacenan en un array contiguo, tras eliminar un nodo las direcciones de los nodos posteriores se desplazan una posiciónsizeof(struct ncclTopoNode). Por lo tanto, todos los punteros que apuntan a nodos posteriores al nodo eliminado deben decrementarse en uno. Esta operación enmemmoveejecutado antes, el orden es clave.

Búsqueda de rutas: encontrar la "ruta óptima" en el grafo

Modelo intuitivo

Tener un mapa no es suficiente, también necesitas un algoritmo de navegación. La búsqueda de rutas de NCCL se divide en dos capas: la primera capa es el preprocesamiento, que calcula la ruta más corta entre todos los pares de nodos (BFS); la segunda capa es la búsqueda en el grafo, que prueba diferentes estructuras Ring/Tree sobre los resultados del preprocesamiento para encontrar la de mayor ancho de banda.

Sin la búsqueda de rutas, NCCL solo podría codificar de forma fija secuencias como "GPU 0 conectada a GPU 1 conectada a GPU 2...", lo que en topologías no uniformes seleccionaría rutas lentas.

Estructuras de datos y diseño de memoria

La estructura de datos central de la búsqueda de rutas esncclTopoLinkList, que almacena la ruta completa desde un nodo origen hasta un nodo destino:

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

Cada nodo tiene un arraypaths[type]que almacena las rutas hacia todos los nodos de ese tipo. Por ejemplo, elpaths[NET]de un nodo GPU almacena las rutas hacia todas las tarjetas de red.

El cálculo de rutas lo realizancclTopoSetPaths, que es un 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;
}

El BFS parte desdebaseNodey se expande capa por capa. Cada vez que alcanza un nuevo nodo, calcula el ancho de banda cuello de botella de la ruta (std::min(path->bw, link->bw)) y el tipo de ruta. El cálculo del tipo de ruta tiene algunas reglas especiales:

• Si pasa por dos switches PCI, el tipo se eleva aPATH_PXB
• Si pasa por CPU, el tipo se eleva aPATH_PHB
• Si pasa por un nodo DEV y es NVLink, el tipo se eleva aPATH_NVB

La condición de actualización es "ruta mejor": mejor tipo, o mismo tipo pero mayor ancho de banda, o mismo tipo y ancho de banda pero menos saltos.

Recorrido paso a paso guiado por escenarios

Ahora veamos la búsqueda de la segunda capa.ncclTopoComputees el punto de entrada, prueba diferentes combinaciones de parámetros y llama ancclTopoSearchRecpara realizar la búsqueda.

El núcleo de la búsqueda es la función recursivancclTopoSearchRecGpu. Parte de una GPU, intenta avanzar a la siguiente GPU, hasta recorrer todas las GPUs formando una ruta:

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

Esta función tiene varias ramas clave:

1. step == ngpus: ya se recorrieron todas las GPUs, se formó una ruta completa. En este punto se incrementanChannels, se compara el grafo actual con el mejor grafo guardado, y si es mejor se guarda. Luego se llama recursivamente ancclTopoSearchRecpara intentar buscar el siguiente channel.

2. step == backToNet: es necesario volver a la tarjeta de red. Esto ocurre en modo Ring (la última GPU debe conectarse de vuelta a la tarjeta de red inicial) o en modo Tree (la primera GPU debe conectarse a la tarjeta de red).

3. step < ngpus - 1: continuar hacia la siguiente GPU. Aquí se llama ancclTopoSearchNextGpuSortpara ordenar las GPUs candidatas.

4. step == backToFirstRank: en modo Ring, la última GPU debe conectarse de vuelta a la primera GPU.

5. else: la ruta termina, se pasa a la siguiente ronda.

ncclTopoSearchNextGpuSortdetermina el orden en que se intenta la siguiente GPU:

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

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

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

Puntúa cada GPU candidata y la regla de ordenamiento es: primero compara interBw (ancho de banda hacia la tarjeta de red), luego interPciBw, luego interNhops, luego intraBw, y finalmente intraNhops. Esta prioridad refleja el objetivo de optimización de NCCL: la comunicación entre máquinas es el cuello de botella, por lo que se priorizan las GPUs con mayor ancho de banda hacia la tarjeta de red.

Reflexiones de diseño y problemas en producción

¿Por qué la búsqueda tiene timeout?Observa estas constantes:

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

El espacio de búsqueda es exponencial: cada channel tiene O(ngpus!) permutaciones. Una máquina de 8 GPUs tiene 40320, una de 16 GPUs tiene 2 billones. Es obligatorio limitar el tiempo de búsqueda.NCCL_SEARCH_TIMEOUTes 16384 iteraciones,NCCL_SEARCH_GLOBAL_TIMEOUTes 524288. Tras el timeout se devuelve la mejor solución actual.

Problema uno:ncclTopoFollowPathla deducción de ancho de banda es un efecto secundario global.Observa esta función:

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

followPathmodifica elbwde cada enlace en la ruta (deduciendo el ancho de banda ya usado). Si la búsqueda falla, es obligatorio llamar afollowPathpara restaurar con-bw. Este patrón de "deducir-restaurar" es muy propenso a errores en búsquedas recursivas: si alguna rama olvida restaurar, las búsquedas posteriores verán anchos de banda incorrectos.

Problema dos:ncclTopoCompareGraphsla lógica de comparación es muy sutil.Prioriza compararnChannels * bwIntra, pero además hay un montón de casos especiales:

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

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

Ring y Tree: convertir los resultados de búsqueda en topología de algoritmo

Modelo intuitivo

El algoritmo de búsqueda encuentra un conjunto de rutas, pero el algoritmo necesita un orden explícito de "quién envía a quién". Ring encadena todos los ranks en un anillo, cada rank recibe del anterior y envía al siguiente. Tree es un árbol, donde los datos fluyen desde la raíz hacia abajo o se concentran desde las hojas hacia arriba.

Sin estos dos módulos, el algoritmo de búsqueda solo encontraría un montón de rutas y no podría indicar al kernel de GPU cómo enviar los datos concretamente.

Estructuras de datos y diseño de memoria

La construcción de Ring la realizancclBuildRings:

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

La entrada son los arraysprevynext(el predecesor y sucesor de cada rank), la salida es el arrayrings(el orden completo de ranks de cada channel). Parte del rank actual, recorre una vuelta siguiendo los punterosnext, verifica si vuelve al punto de inicio y comprueba que todos los ranks hayan sido visitados.

La construcción de Tree la realizancclGetBtree:

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

Esta función construye un árbol binario usando operaciones de bits. La idea central es: encontrar el bit no nulo más bajo del rankbit, el nodo padre es(rank ^ bit) | (bit << 1), el hijo izquierdo esrank - (bit >> 1), el hijo derecho esrank + (bit >> 1). El diagrama ASCII en los comentarios muestra claramente esta estructura.

Recorrido paso a paso guiado por escenarios

Tomemos como ejemplo un Ring de 8 GPUs. Supongamos que los resultados de búsqueda proporcionan para cada rank elnextpuntero:

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

ncclBuildRingsPartiendo del rank 0, se visitan sucesivamente 1, 2, ..., 7, y finalmente se regresa al 0. El generadorings[0..7] = {0, 1, 2, 3, 4, 5, 6, 7}。

Para Tree,ncclGetBtreese calcula el nodo padre y los nodos hijos para cada rank. Tomando como ejemplo el rank 1:

• bit= 1 (el bit distinto de cero más bajo es el bit 0)
• up = (1 ^ 1) | (1 << 1) = 0 | 2 = 2
• up >= nranks? 2 < 8, entoncesup = 2
• parentChildType = (1 < 2) ? 0 : 1 = 0(es el primer hijo del nodo padre)
• lowbit = 0, entoncesdown0 = -1
• down1 = -1

Por lo tanto, el nodo padre del rank 1 es el rank 2, y no tiene nodos hijos. Esto concuerda con la estructura de árbol en los comentarios: el rank 1 es una hoja.

Reflexiones de diseño y trampas en producción

Trampa uno:ncclBuildRingsla verificación de puede ser omitida.Si elnextarreglo tiene un ciclo (por ejemplo, rank 0 -> rank 1 -> rank 0), el bucle saldrá después denranksiteraciones, pero lacurrent != rankverificación capturará este problema. Pero si la longitud del ciclo es exactamentenranksun factor de, y no contiene todos los ranks,rankFoundla verificación lo capturará.

Trampa dos:ncclGetDtreeel manejo de ranks impares en.Para un número impar de ranks, el segundo árbol es un "desplazamiento" en lugar de un "espejo":

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

El Doble Árbol (Double Tree) es la implementación del algoritmo Tree de NCCL: dos árboles trabajan simultáneamente, uno se encarga de la primera mitad de los datos y el otro de la segunda mitad, mejorando la utilización del ancho de banda. Con ranks impares, el espejo provocaría un mapeo de ranks incompleto, por lo que se usa el desplazamiento.

La coordinación de los tres: de la topología al algoritmo

Ahora conectemos los tres módulos. Todo el flujo se puede representar con un diagrama:

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["生成最终算法拓扑"]

Este diagrama muestra el flujo completo desde el descubrimiento de topología hasta la generación del algoritmo. Nótese quencclTopoSearchRecGpues una función recursiva, que intentará continuamente diferentes órdenes de GPUs hasta que se agote el tiempo o se encuentre la solución óptima.

Veamos ahora un diagrama de secuencia de granularidad más fina, que muestra la interacción de los módulos durante el proceso de búsqueda:

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) 恢复带宽

Este diagrama de secuencia muestra el bucle central de la búsqueda: seleccionar NIC -> probar GPU -> búsqueda recursiva -> comparar resultados -> restaurar ancho de banda.

Resumen del capítulo

Este capítulo desglosó los tres eslabones de la percepción de topología de NCCL:

1. Descubrimiento de topología（topo.cc): lee la información de dispositivos desde XML, crea nodos GPU/CPU/PCI/NIC, establece enlaces NVLink/PCIe/red, formando un grafo de topología completo.

2. Búsqueda de rutas（search.cc + paths.cc): primero usa BFS para precalcular las rutas más cortas entre todos los pares de nodos, luego usa búsqueda recursiva para probar diferentes estructuras Ring/Tree, encontrando la solución con mayor ancho de banda.

3. Generación de topología de algoritmo（rings.cc + trees.cc): convierte los resultados de búsqueda en un orden específico de ranks, Ring usancclBuildRingspara generar el anillo, Tree usancclGetBtreepara generar el árbol binario.

Reflexiones y autoevaluación del capítulo

En el próximo capítulo profundizaremos en el módulo tuning para ver cómo NCCL, basándose en los resultados de búsqueda topológica y el tamaño del mensaje, toma la decisión final entre algoritmos como Ring, Tree, CollNet, etc. El grafo topológico, los resultados de búsqueda de rutas y las plantillas de algoritmos establecidos en este capítulo serán la entrada del módulo tuning.

Mediante la construcción del grafo en topo.cc, la búsqueda de rutas en search.cc y la generación de topologías en rings.cc y trees.cc, NCCL implementa la filosofía de diseño de describir cualquier topología con una estructura de grafo genérica, encontrar la solución óptima con algoritmos de búsqueda configurables y generar el algoritmo final con plantillas simples. Este mecanismo permite a NCCL seleccionar automáticamente el algoritmo adecuado en diversas máquinas, desde estaciones de trabajo con 2 GPU hasta clústeres con 10000 GPU. Sin embargo, el grafo topológico solo proporciona rutas candidatas para el algoritmo; decidir qué ruta tomar y qué protocolo usar en una comunicación concreta requiere decisiones más finas. En el próximo capítulo nos centraremos en el directorio src/tuning para ver cómo el módulo tuning combina el modelo de costos con las estimaciones de algoritmos para tomar la decisión final entre Ring/Tree/NVLS/PAT y LL/LL128/Simple.

Capítulo 5: Selección de algoritmo y protocolo: cómo el módulo tuning decide la ruta de comunicación

En el capítulo anterior desglosamos la capacidad de reconocimiento topológico de NCCL: desde la enumeración de dispositivos en src/graph/topo.cc para construir el grafo topológico, pasando por la búsqueda de rutas óptimas en src/graph/search.cc, hasta la materialización de los resultados de búsqueda en topologías de algoritmos Ring y Tree en rings.cc y trees.cc. Pero el grafo topológico solo responde a «por dónde pueden ir los datos», no responde a «por dónde debería ir esta comunicación». En una misma máquina, un AllReduce de 4KB y uno de 400MB pueden tener soluciones óptimas completamente distintas: el primero compite por latencia, el segundo por ancho de banda; el primero podría elegir Tree/LL, el segundo Ring/Simple o NVLS. El módulo tuning es ese «árbitro». Sus entradas son el tamaño del mensaje, el número de ranks, el grafo topológico (producto del capítulo anterior) y las variables de entorno del usuario; su salida es un ncclTuningResult_t, que indica qué algoritmo (algo), qué protocolo (proto), cuántos channels y cuántos warps usar. En este capítulo desglosamos el directorio src/tuning en el orden «planificación general → modelo de costos → estimación por algoritmo → decisión final». La pregunta central es una sola: ¿cómo selecciona NCCL, entre docenas de combinaciones (algoritmo, protocolo), la más rápida en tiempo de microsegundos usando un modelo matemático puramente de CPU?

I. tuning.cc: planificación general y tronco de decisión

Modelo intuitivo

Imagina el módulo tuning como unaempresa de mudanzas. Llega un cliente (una comunicación colectiva) y dice «quiero mover 100MB de mercancía, de 8 almacenes a 8 almacenes». El despachador (ncclTuningCompute) no va a moverla de verdad para probar, sino que saca unatabla de precios(modelo de costos), estima un «tiempo estimado» para cada opción (Ring/LL, Tree/Simple, NVLS/Simple…) y elige la cotización más corta para el cliente.

Sin este despachador, NCCL solo podría codificar «AllReduce siempre usa Ring», lo que en escenarios de mensajes pequeños sería aplastado por Tree, y en escenarios NVLink a gran escala sería aplastado por NVLS.El costo es que el rendimiento se reduce a la mitad o incluso peor en escenarios específicos.

Estructuras de datos y diseño de memoria

El portador de la decisión esncclTuningResult_t, y el conjunto de candidatos esncclTuningResultList_t(una lista simplemente enlazada). Los nodos de la lista se definen entuning_int.h, pero la lógica de push está entuning.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_tLos dos campos más críticos sontimeUs(tiempo estimado, microsegundos) yselectionTimeUs(tiempo usado para la selección, puede ser sobrescrito por el plugin tuner). La lógica de selección solo mira el segundo:

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

Aquí hay un detalle:bestTuning->timeUsprimero se establece enFLT_MAX, luego se recorre. Si la lista enlazada está vacía (todos los candidatos son inválidos),bestTuningmantendráNCCL_TUNING_RESULT_INITel valor inicial de, algo/proto sonUNDEF. Este «resultado vacío» se maneja de forma especial en el llamador — véase la rama de error más adelante.

Step-by-Step Walkthrough: el flujo de decisión de un AllReduce

Supongamos que la aplicación llama ancclAllReduce, mensaje de 1MB, 8 ranks en una sola máquina con NVLink. SeguimosncclTuningComputepaso a paso.

Paso 0: cortocircuito de un solo rank.SinRanks <= 1, no se necesita comunicación en absoluto, se devuelve directamente Ring/Simple, con el número de channels establecido en 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 {

Este cortocircuito es importante: con un solo rank, cualquier estimación de algoritmo se dividiría pornRanks-1o cantidades similares, lo que fácilmente produciría NaN o división por cero.Primero la red de seguridad, luego las cuentas, es un ejemplo típico de programación defensiva.

Paso 1: enumerar todos los candidatos.Entra enncclTuningComputeAllTunings, que recorreNCCL_TUNING_COUNTids:

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

Nótese quetuningMaskes una máscara de 64 bits, donde el bit i indica «si la i-ésima combinación (algo, proto) está permitida». Esta máscara se calcula en capas superiores según las capacidades de la plataforma, las variables de entorno del usuario y el tipo de función.La máscara es el «filtro grueso», el modelo de coste es el «cálculo fino»— primero se descartan los imposibles (por ejemplo, NVLS no puede existir en una máquina PCI), y luego se calcula el tiempo de los restantes.

ncclTuningExpandIdexpande el id unidimensional a (algo, proto, symKernelId, ceMethodId). Esta relación de mapeo debe ser estrictamente consistente concost_model.ccenmodelMapel array, de lo contrario el modelo se calcularía mal.

Paso 2: calcular el coste uno por uno. ncclTuningComputeTuningsolo tiene una línea, que delega al modelo de coste:

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

Paso 3: intervención del plugin tuner (opcional).Si el usuario ha instalado un plugin tuner (por ejemplo, los ajustadores propios de algunos proveedores cloud), NCCL empaqueta lostimeUsde todos los candidatos en una tabla bidimensionalgeneralTable[algo][proto]y la entrega al plugin para que este la sobrescriba:

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

AquíNCCL_TUNING_IGNOREes un valor centinela que indica «esta combinación no se ha calculado / no aplica». El plugin puede modificar solo las celdas que le interesan, dejando las demás en IGNORE, y NCCL las omitirá.

Paso 4: elegir el óptimo.llama ancclTuningSelectBestTuning, recorre la lista enlazada y toma elselectionTimeUsmínimo.

Paso 5: calcular el número de channels.Tras elegir el algoritmo, aún hay que decidir cuántos channels abrir:

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

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

ncclTuningGetChannelsEntuning_int.h, la lógica consiste en interpolar entreminChannelsymaxChannelssegún el tamaño del mensaje y el tipo de algoritmo. El número de channels afecta directamente al ancho de banda: cuantos más channels, mayor paralelismo, pero también mayor coste de arranque por channel.

Paso 6: sesgo de CTA Policy (prioridad NVLS).Si el usuario ha establecidoNCCL_CTA_POLICY_EFFICIENCY, y actualmente es AllGather/ReduceScatter y el buffer está registrado, NCCL intentará cambiar el resultado a 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;
          ...

El comentario de este código es clave:el sesgo EFFICIENCY debe ejecutarse después deGetChannels, porque necesita usarbestTuning.nChannels; además, debe comprobarse si el bit NVLS entuningMaskestá permitido, de lo contrario se «resucitaría» un algoritmo excluido por las capas superiores. Esta es la típicatrampa de orden de dependencia de estado。

Paso 7: retroceso a kernel simétrico.Si el seleccionado es un kernel simétrico (symKernelId), pero el buffer no está registrado o la plataforma no lo soporta, hay que retroceder a un kernel normal. Esta lógica está entuning.cc:258-298, es la parte más enrevesada de todo el capítulo, y la trataremos en detalle en la sección quinta.

Paso 8: error por falta de solución.Si todos los candidatos son inválidos, algo/proto son UNDEF, NCCL emitirá un WARN y devolverá códigos de error distintos según si el usuario ha establecido variables de entorno:

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

¿Por qué distinguir los códigos de error?Si el usuario ha establecidoNCCL_ALGO=ringpero la plataforma actual no soporta ring (por ejemplo, ciertas topologías especiales), eso eserror de configuración del usuario（ncclInvalidUsage); si el usuario no ha establecido ninguna variable de entorno y aun así no se puede elegir un algoritmo, eso esun bug interno de NCCL（ncclInternalError). Esta distinción es crucial para la resolución de problemas.

Diagrama de flujo del tronco de decisión

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"]

---

II. cost_model.cc: registro de modelos y matriz de interruptores

Modelo intuitivo

cost_model.cces ellibro mayordel tuning. Mantiene una tablamodelMap, donde cada fila corresponde a una combinación (algo, proto) y registra «quién es la función de inicialización de esta combinación, quién es la función de simulación y para qué funciones está habilitada». Además, se encarga de parsear la variable de entorno del usuarioNCCL_ALGO/NCCL_PROTO/NCCL_SYM_KERNEL, traduciendo la intención del usuario en una matriz de interruptoresenabled[i][f].

Sin esta tabla, cada vez que se añadiera un nuevo algoritmo habría que modificar el flujo principal de tuning, y el código se convertiría en un desastre.La tabla como driverconvierte «añadir un algoritmo» en «añadir una fila».

Estructuras de datos: modelMap y matriz de interruptores

modelMapes un array estático, cada elemento esncclTuningModelEntry_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
  ...
};

Cada entry tiene cuatro campos:init(inicialización, calcula latency/bandwidth y lo guarda en comm),model(simulación, calcula el timeUs final según el tamaño del mensaje),finalize(limpieza),enabled[5](sobre si se habilitan las cinco funciones Broadcast/Reduce/AllGather/ReduceScatter/AllReduce).

NotaenabledEl comentario sobre el orden del array está en L234:Enable order: Broadcast, Reduce, AllGather, ReduceScatter, AllReduce. Este orden debe coincidir conncclFunc_tel enum, de lo contrario se confundirán los elementos.

Paso a paso: análisis de variables de entorno y construcción de la matriz de interruptores

Paso 1: por defecto todo activado, LL128 es especial. ncclTuningCostModelInitAl principio se ponen todos los proto a 1 (habilitado), pero LL128 se pone a 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;
    }
  }

¿Por qué LL128 es 2 y no 1?Porque LL128 no está «habilitado por defecto», sino «habilitado condicionalmente». 2 es una marca especial que indica «el usuario no lo pidió explícitamente, más adelanteisLL128Enabledlo decidirá según la capacidad de la plataforma». 1 significa «habilitado incondicionalmente», 0 significa «deshabilitado». Este diseño de tres estados se refleja en la condición de 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;
      }

Paso 2: analizar las variables de entorno del usuario.Si el usuario configuróNCCL_ALGOoNCCL_SYM_KERNEL, primero se ponen a cero todos los algo y symKernel (porque el usuario especificó una lista blanca):

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

Nota: proto no se pone a cero — porque el valor por defecto de proto es 1/2, cuando el usuario configuraNCCL_PROTO=LL,parseListpondrá LL a 1 y los demás a 0 (debido a la lógica deunset). Esta asimetría es intencional: algo está todo activado por defecto pero tras la especificación del usuario debe reducirse, la reducción de proto la maneja internamenteparseList.

Paso 3: sintaxis de parseList.Esta función soporta una sintaxis bastante compleja, en los comentarios se dan ejemplos:

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

^El prefijo indica «negación»:

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

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

Por lo tantoNCCL_PROTO="^LL128;allreduce:LL128"significa: deshabilitar LL128 globalmente, pero habilitar LL128 como excepción para AllReduce.

Paso 4: fusionar la matriz enabled.Finalmente se recorren todos los model, y se hace una operación AND entremodel->enabled[f]y los interruptores del usuario:

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

La lógica es:Solo cuando el usuario ha configurado forced para alguna función, se sobrescribe el valor por defecto del modelo con la configuración del usuario. Si el usuario no lo configuró,forced[f] == 0, directamentecontinue, conservando elenableddel propio modelo. Esta es la prioridad de «especificación explícita del usuario > valor por defecto del modelo».

Entrada unificada de la simulación de modelos

Todos los modelos finalmente se invocan a través dencclTuningCostModelSimModel:

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

Tres capas de filtrado:id fuera de rango → modelo deshabilitado → el modelo devuelve un tiempo no positivo, si alguna capa no pasa se va anot_valid, poniendotimeUsaNCCL_TUNING_IGNORE(un centinela negativo),valid = 0. Cuando el llamador vevalid == 0no lo insertará en la lista enlazada de candidatos.

Reflexión de diseño

modelMapEn los comentarios de

📎 src/tuning/cost_model.cc:229

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

---

Una práctica más robusta sería usar el nombre del enum como key en lugar del índice, pero eso sacrificaría un poco de optimización en tiempo de compilación.

III. ring.cc: estimación del coste del algoritmo Ring

Modelo intuitivoEl algoritmo Ring coloca N ranks en un anillo, y los datos se transmiten vuelta tras vuelta a lo largo del anillo. Su modelo de coste debe responder dos preguntas:、Cuántos datos se transmiten en cada paso (bandwidth)。

Cuántos pasos se necesitan en total (latency)La intuición de Ring es «pipeline

»: imagina N personas en círculo pasándose un cubo, cada persona al recibir el cubo vierte un poco de agua y lo pasa a la siguiente. Cuando el cubo da una vuelta, el agua de todos se ha mezclado uniformemente. Cuanto más rápido gire el cubo (mayor bandwidth), cuanto más pequeño sea el círculo (menos pasos), más rápido será en conjunto.

Estructura de datos: tabla latency/bandwidthcomm->tuningContext.generalLatencies[c][algo][proto]El modelo Ring no introduce nuevas estructuras, escribe los resultados de la estimación engeneralBandwidths[c][algo][proto]y

. Estos dos son arrays tridimensionales: función × algoritmo × protocolo.

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

Copiar

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

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

Copiar¿Por qué usar -1.0 en lugar de 0?==Porque 0 es un valor de bandwidth legal (aunque físicamente imposible), mientras que -1.0 indica claramente «no inicializado». La comparación de punto flotante con

aquí es segura, porque -1.0 es exactamente representable.

Paso a paso: estimación de bandwidth de RingPaso 1: determinar si usar bandwidth intra o 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;

nStepsCopiar2*(nRanks-1)es el número de pasos que necesita el algoritmo, para Ring AllReduce esnRanks-1。busBw, los demás son

es el «bandwidth de bus» = bandwidth de enlace único × número de channels.El protocolo LL solo usa la mitad del ancho de banda (debido al overhead de flag de LL), LL128 usa el 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/128Esto se debe a que en LL128, de cada 128 bytes, 8 bytes son flag, y la carga útil es solo de 120 bytes. Este número proviene directamente del diseño del protocolo.

Paso 3: Calcular el ancho de banda efectivo.Nota: aquí se multiplica pornRanks / 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;

¿Por qué multiplicar pornRanks / nSteps？Esta es la característica central del algoritmo Ring: la cantidad de datos que cada rank realmente transporta esnBytes * nSteps / nRanks(porque los datos deben dar varias vueltas alrededor del anillo). Por lo tanto, el "ancho de banda efectivo" = ancho de banda del bus × nRanks / nSteps. Para AllReduce, nSteps = 2(nRanks-1), así que el ancho de banda efectivo ≈ busBw/2.

Paso 4: Calcular la latencia.La latencia se divide en dos partes: intra e 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;

Nota el manejo especial en L57-58: cuandomaxLocalRanks == 1(cada nodo tiene solo 1 rank), la latencia inter-node de Ring usala latencia NET de Tree. El comentario dice que esto es "preserve the pre-refactor model" — es decir, una "rareza" conservada deliberadamente para mantener la consistencia con el comportamiento previo a la refactorización.Este tipo de lastre histórico es muy común en sistemas maduros. Al leer el código fuente, hay que tener especial cuidado cuando se ve la palabra "preserve", ya que a menudo implica que hay una restricción de compatibilidad que no se puede modificar.

Paso 5: Acumular según el tipo de función.Los modelos de latencia de Reduce/Broadcast y AllReduce/AllGather/ReduceScatter son diferentes:

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

sameChannelsEs una propiedad topológica que indica "si los pasos intra e inter en el anillo usan el mismo conjunto de channels". Si son diferentes, la latencia debe multiplicarse pornSteps(hay que esperar en cada paso).netOverheadEs el overhead de post de red; el protocolo Simple debe multiplicarse por 3 (porque Simple tiene tres idas y vueltas de red: send, recv, ack).

Evitar trampas en producción: el efecto plateau de Ring/Simple

ncclTuningRingModelSimHay una sección de código dedicada a manejar el "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 >= 64Es la condición de activación: cada rank debe transmitir al menos 64 bytes por channel, de lo contrario el plateau no se cumple. Estos 64 bytes provienen del tamaño del flag del protocolo LL.

Escenario de trampa: Si ejecutas un AllReduce de 1MB en Blackwell y descubres que la latencia real es un 40% mayor que la predicha por el modelo, no pienses que es un bug — esto es el efecto plateau, y el modelo ya lo ha tenido en cuenta. Si modificas manualmenteplateauFactora un valor menor, el modelo subestimará la latencia, lo que llevará a elegir el algoritmo incorrecto.

---

IV. tree.cc y nvls.cc: Estimación de costos de Tree y NVLS

Modelo intuitivo

El algoritmo Treees una "difusión en árbol": el nodo raíz distribuye los datos a los nodos hijos, y estos a su vez a los nodos nietos. Su ventaja es que tienepocos pasos(log N en lugar de N), adecuado para mensajes pequeños; su desventaja es que tienebaja utilización del ancho de banda(cada nodo no hoja debe reenviar, por lo que el ancho de banda efectivo real es solo la mitad).

NVLS(NVLink SHARP) es "multicast por hardware": el switch copia directamente los datos a múltiples GPUs, sin necesidad de reenvío por software. Su ventaja es que tienealto ancho de banda y baja latencia, pero requiere hardware específico (Hopper o superior) y una configuración específica.

Modelo Tree: solo sirve para AllReduce

El modelo Tree tiene una restricción estricta —solo se habilita para 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;
    }

copiar：

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

copiar：

📎 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 *Es el número de pasos intra-nodo (el número de ranks dentro de cada nodo menos uno),(nRanks/nNodes - 1)es el número de pasos inter-nodo (la altura del árbol).log2i(nNodes)El factor de corrección de Tree

Tree 的修正因子: El modelo Tree multiplica en la fase de sim untreeCorrectionFactor：

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

treeCorrectionFactores una tabla de 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), es decir, el tamaño del mensaje se toma en log2 con unidades de 64 bytes. Los índices 0-23 de la tabla corresponden desde 64B hasta 64B×2^23 ≈ 512MB.Esta tabla es la «curva de eficiencia de Tree» medida empíricamente: con mensajes pequeños la eficiencia es 1.0 (dominada por la latencia), con mensajes medianos la eficiencia cae a 0.4-0.5 (el ancho de banda no se satura), y con mensajes grandes vuelve a 1.0 (ancho de banda saturado). Esta «depresión intermedia» es una característica inherente del algoritmo Tree.

Modelo NVLS: el costo de la multidifusión por hardware

El modelo NVLS primero verifica si el hardware lo soporta:

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

Luego hay una serie de restricciones estrictas: solo soporta el protocolo Simple, no soporta NVLSTree en una sola máquina, y NVLS multi-máquina requiere 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;
  }

Estimación de ancho de banda de NVLSSe utiliza un factor de eficiencia:

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

En el cálculo del ancho de banda hay un(nChannels - 1) / nChannelsfactor:

📎 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) / nChannelses porque NVLS necesita reservar un canal para sincronización.(ppn - 1) / ppnes el costo adicional de AllGather/ReduceScatter (cada rank debe esperar los datos del rank anterior).

Evitando trampas en producción: las restricciones estrictas de NVLS

El modelo NVLS en la fase de sim tiene además una capa de verificación en tiempo de ejecución:

📎 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_ARITYes el número máximo de GPUs que puede contener un grupo de multidifusión NVLS. Si se supera este número, NVLS no está disponible.Escenario problemático: al ejecutar AllGather en un dominio NVLink de 16 tarjetas, siNCCL_MAX_NVLS_ARITYes 8, NVLS se deshabilitará y el tuning recurrirá a Ring. Si no conoces esta limitación, pensarás «si NVLS tiene soporte de hardware, ¿por qué no se usa?».

---

V. Retroceso a kernel simétrico y cadena de recuperación de errores

Modelo intuitivo

El kernel simétrico (symmetric kernel) es una nueva característica de NCCL: cuando los buffers de todos los ranks están registrados en memoria simétrica, el kernel puede acceder a la memoria del par con instrucciones más eficientes. Perosi el buffer no está registrado, o la plataforma no lo soporta, se debe recurrir al kernel normal. Esta lógica de retroceso es la parte más enrevesada del tuning.

Paso a paso: decisión de retroceso

La lógica de retroceso está entuning.cc:258-298. Vamos a desglosarla.

Paso 1: determinar si se necesita retroceso.Condición de entrada:

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

Hasta aquí, la cadena de decisiones del módulo de tuning ya está clara: recibe el grafo de topología y los parámetros de comunicación, y mediante modelos de costo y estimaciones de algoritmos, produce en microsegundos la combinación óptima de (algoritmo, protocolo, channel, warp). Pero la selección es solo el comienzo—¿cómo se utiliza este resultado de decisión aguas abajo? En el próximo capítulo entraremos en el tronco de src/enqueue/enqueue.cc, para ver cómo una llamada a ncclAllReduce pasa por validación de parámetros, determinación de algoritmo/protocolo, división de channels, y finalmente genera las estructuras ncclInfo y ncclTaskColl. Este es el capítulo clave del libro donde se cambia de la «perspectiva del usuario» a la «perspectiva del motor»; descubrirás en qué se traduce una llamada de comunicación colectiva en el lado del host, y cuál es su frontera con el lanzamiento posterior del kernel.

Capítulo 6: Panorama del despacho de operadores: cómo ncclAllReduce se convierte en una tarea de kernel ejecutable

En el capítulo anterior recorrimos el módulo de tuning y vimos que NCCL selecciona en microsegundos la combinación (algoritmo, protocolo, channel, warp) para una comunicación colectiva. Pero el resultado de la selección en sí es solo un montón de números: necesita ser "traducido" a un objeto de descripción de tarea que el kernel de GPU pueda entender para poder ejecutarse realmente. Este capítulo entra en el cuerpo principal de src/enqueue/enqueue.cc y responde a una pregunta central: cuando el usuario llama a ncclAllReduce, ¿qué ocurre exactamente en el lado del host? Desde ncclAllReduce hasta ncclEnqueueCheck, pasando por la validación de parámetros, la determinación de algoritmo/protocolo y la división en channels, hasta generar finalmente las estructuras ncclInfo y ncclTaskColl. Este es el capítulo clave en el que el libro pasa de la "perspectiva del usuario" a la "perspectiva del motor". Si comparamos NCCL con un restaurante, el módulo enqueue sería el "sistema de toma de pedidos en recepción": el usuario (capa de aplicación) dice "quiero un AllReduce" y recepción lo traduce a una orden de trabajo que la cocina (kernel de GPU) puede ejecutar: qué fogón, con qué sartén, en cuántos lotes. Sin esta capa de traducción, la cocina no sabría qué plato preparar.

I. Entrada: cómo ncclAllReduce construye ncclInfo

Modelo intuitivo

ncclAllReduceEs la función API que el usuario llama directamente. Su responsabilidad es extremadamente única:empaquetar los parámetros sin procesar que pasa el usuario en una estructurancclInfoy luego entregarla ancclEnqueueCheck. Esto es como cuando vas a la ventanilla de un banco a hacer una gestión: el cajero primero rellena tu necesidad en un formulario estándar y luego lo transfiere al sistema de back office.

Sin esta capa, cada API de comunicación colectiva tendría que encargarse por sí misma de la validación de parámetros, la semántica de group y el instrumentado del profiler; el código se duplicaría hasta ser imposible de mantener.

Estructura de datos: el diseño de memoria de ncclInfo

ncclInfoEs el vehículo central que atraviesa todo el flujo de enqueue. Su definición está ensrc/include/info.h：

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

Esta estructura tiene más de 20 campos, que podemos dividir en cuatro grupos según su función:

Atención al comentario decollConfig:"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. Este es un diseño clave: el puntero de config que pasa el usuario puede ser destruido antes dencclGroupEnd, así que NCCL hace una copia enncclInfo.

Paso a paso: la cadena de llamadas de ncclAllReduce

TomemosncclAllReducecomo ejemplo y sigamos la ruta completa desde la llamada del usuario hasta la construcción dencclInfo.

Paso 1: el usuario llama a ncclAllReduce.La entrada está ensrc/collectives.cc：

📎 src/collectives.cc:206-211

Aquí se hacen tres cosas:

1. NVTX3_FUNC_WITH_PARAMS1. Marcar con NVTX (para visualización en herramientas como Nsight)

2. Llamar ancclAllReduceConfigImpl, pasandoconfig = nullptr

3. Devolver el resultado

Paso 2: ncclAllReduceConfigImpl construye ncclInfo.Este es el paso clave:

📎 src/collectives.cc:192-202

Observa que aquí se usa inicialización agregada al estilo C:

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

Los campos se corresponden uno a uno según el orden de declaración dencclInfo.ALLREDUCE_CHUNKSTEPSyALLREDUCE_SLICESTEPSestán definidos ensrc/include/collectives.h：

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

NCCL_STEPSes el número de pasos en el búfer circular (normalmente 8 o 16), así que el chunkSteps de AllReduce esNCCL_STEPS/2y el sliceSteps esNCCL_STEPS/4. Esto significa que un chunk contiene 2 slices.

Paso 3: analizar el config del usuario. ncclParseCollConfigAnaliza elncclCollConfig_t*pasado por el usuario dentro deinfo.collConfig. Siconfig == nullptr, este campo permanece inicializado a cero.

Paso 4: entregar a ncclEnqueueCheck.Esta es la verdadera entrada del módulo enqueue.

Reflexión de diseño: ¿por qué usar inicialización agregada en lugar de asignar campo por campo?

Trampa en producción: ciclo de vida de config

Un escenario real de trampa: el usuario escribe el código así:

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

Si NCCL no copiara el config enncclInfo, entonces al acceder ancclGroupEndduranteinfo.collConfigse leería memoria ya liberada.src/include/info.h:41-43El comentario desirve precisamente para explicar este diseño:。

---

config se analiza y se copia en la fase de task append, y después ya no depende del puntero del usuario

II. ncclEnqueueCheck: validación de parámetros y semántica de group

ncclEnqueueCheckModelo intuitivoEs la "compuerta principal" del módulo enqueue. Todas las API de comunicación colectiva confluyen finalmente aquí. Su responsabilidad es:validar la legalidad de los parámetros, gestionar la semántica de group y llamar a taskAppend para generar tareasncclEnqueueCheck。

. Si lo comparamos con el control de seguridad de un aeropuerto, cada función API sería el mostrador de facturación: facturar solo consiste en recoger el equipaje; el control de seguridad real está en

Paso a paso: el flujo de ejecución de ncclEnqueueCheck

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

Desglosémoslo paso a paso:

Paso 1: CommCheck valida el dominio de comunicación. CommCheck(info->comm, info->opName, "comm")Verifica si el puntero comm no es nulo y si ya está inicializado. Si comm ha sido revocado (por ejemplo, si algún rank falló), devuelve error directamente:

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

Paso 2: manejar la profundidad del profiler.Si ya está dentro de un group (profilerGroupDepth > 0), incrementa el contador de profundidad. Esto es para manejar correctamente las llamadas implícitas dencclGroupStartInternal/ncclGroupEndInternal.

Paso 3: entrar en el group interno. ncclGroupStartInternal()Es el mecanismo interno de group de NCCL.Punto clave: aunque el usuario no llame explícitamente ancclGroupStart, NCCL también crea un group implícito para cada llamada a la API. Esto garantiza la atomicidad de una sola llamada.

Paso 4: asegurar que comm esté listo. ncclCommEnsureReady(info->comm)Espera a que finalice la inicialización del dominio de comunicación (por ejemplo, que termine el bootstrap y se establezcan las conexiones).

Paso 5: validación de parámetros con ArgsCheck.Este es el paso de validación más complejo:

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

Atención al manejo decheckMode: si esncclCheckModeDebugGlobal，ArgsCheckencola info y espera hastancclGroupEndpara hacer la validación global (por ejemplo, comprobar si el count de todos los ranks coincide).

Paso 6: llamar a taskAppend.Este es el paso central de conversión:

📎 src/enqueue/enqueue.cc:3513

Paso 7: incrementar opCount.Después de cada encolado exitoso,comm->opCount++. Este contador se usa para emparejar operaciones send/recv y también es la base de la línea temporal del profiler.

Paso 8: salir del group. ncclGroupEndInternal()Si depth baja a 0, se dispara la operación real de group (planificación, lanzamiento del kernel).

Control de concurrencia: semántica de group y seguridad de hilos

Un error fácil de cometer: si el usuario llama a una API de CUDA que no es de NCCL entrencclGroupStartyncclGroupEnd(por ejemplo,cudaMemcpy), puede provocar problemas de orden de streams. El mecanismo de group de NCCL asume que las operaciones dentro del group están todas en el mismo conjunto de streams.

Cadena de recuperación de errores

ncclEnqueueCheckEl manejo de errores de tiene un diseño ingenioso:

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

SitaskAppendfalla y comm está en modo no bloqueante, se llama ancclCommSetAsyncErrorpara registrar el error. Así, las llamadas posteriores a la API devuelven error inmediatamente en lugar de seguir intentándolo. Este es el mecanismo de propagación asíncrona de errores.

---

Tres, taskAppend: la encrucijada de la distribución de tareas

Modelo intuitivo

taskAppendEs el "centro de tráfico" del módulo enqueue. Según el valor deinfo->coll, distribuye las tareas a distintas rutas de procesamiento: P2P, RMA, CE o comunicación colectiva normal. Es como un centro de clasificación de correos: según la dirección del sobre, mete la carta en un buzón distinto.

Sin esta capa de distribución, todos los tipos de operaciones tendrían que apiñarse en un enorme if-else y el código sería difícil de mantener.

Paso a paso: la lógica de distribución de taskAppend

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

Paso 1: determinar si se habilita la nueva arquitectura. ncclParamEnqueueRearchEnable()Es un interruptor de variable de entorno (por defecto 0). Si se habilita, se sigue la rutarawTaskAppend— este es el nuevo modelo de tareas que NCCL está desarrollando.

Paso 2: distribución P2P.Si es Send/Recv, llamar ap2pTaskAppend：

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

Paso 3: distribución RMA.Si es PutSignal/Signal/WaitSignal, llamar armaTaskAppend：

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

Paso 4: retorno anticipado para comunicación colectiva vacía. if (info->count == 0) return ncclSuccess;— la comunicación colectiva con count 0 se descarta directamente.

Paso 5: validación de selección de algoritmo. ncclCollConfigGetAlgMaskValida si la selección de algoritmo pasada por el usuario es legal:

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

Paso 6: comprobación de tipo FP8.La reducción FP8 requiere sm90+:

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

Paso 7: conversión de operación de reducción. hostToDevRedOpConvierte elncclRedOp_tdel lado host alncclDevRedOpFull：

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

del lado dispositivoPaso 8: retorno anticipado para un solo rank.comm->nRanks == 1SincclLaunchOneRank, llamar directamente a

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

para ejecutar la reducción local, sin necesidad de generar tareas:Paso 9: ruta multirank.

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

Esta es la rama más compleja, e incluye enrutamiento CE, degradación de AllToAll/Gather/Scatter y comunicación colectiva normal:

collTaskAppendEstructura de datos: campos de ncclTaskCollncclTaskCollEs donde se genera

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

. Veamos su lógica central:

Máscara de selección de algoritmotrafficBytesAtención al cálculo de

📎 src/enqueue/enqueue.cc:2813

ncclFuncTrafficPerByte:

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

devuelve el multiplicador de tráfico de cada tipo de comunicación colectiva:

AllReduce devuelve 2 (porque hay que reduce + broadcast), AllGather/ReduceScatter devuelve nRanks, y los demás devuelven 1.

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

Reflexión de diseño: ¿por qué AllGather/Broadcast se convierten a int8?ncclInt8. Esta es una optimización:Estas dos operaciones no implican reducción, por lo que no es necesario preocuparse por el tipo de dato; procesarlas uniformemente por bytes simplifica la lógica del kernel。

Experiencia real en producción: el orden de análisis de CTAPolicy

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

El análisis de CTAPolicy tiene una prioridad sutil:env > per-call > comm. Y ademásNCCL_CTA_POLICY_ZEROtiene prioridad sobreNCCL_CTA_POLICY_EFFICIENCY. Si el usuario establece ambos flags a la vez, ZERO tendrá efecto.

Un escenario real de problema: el usuario configuróNCCL_CTA_POLICY=EFFICIENCY, pero descubrió que la ruta CE no se estaba usando. La razón es que el enrutamiento CE requiere queCTAPolicy & NCCL_CTA_POLICY_ZEROsea verdadero, y EFFICIENCY no cumple esta condición.

---

Cuatro, ncclPrepareTasks: de la lista de tareas a la cola de programación

Modelo intuitivo

ncclPrepareTaskses el "preprocesador" del módulo enqueue. Agrupa la lista dispersa de tareas por (func, op, datatype) en buckets y luego calcula el algoritmo y el protocolo para cada bucket. Esto es como un bibliotecario: primero clasifica los libros devueltos por categoría y luego decide en qué estantería va cada categoría.

Sin este paso, el posteriorscheduleCollTasksToPlantendría que calcular el algoritmo individualmente para cada tarea, con una eficiencia extremadamente baja.

Paso a paso: la lógica de agrupación en buckets de ncclPrepareTasks

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

Paso 1: Conversión de tareas Broadcast.Si solo hay un broadcast peer, convierte la tarea broadcast en una tarea coll:

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

Observa que aquí se copian los campos debcastTaskal nuevoncclTaskColl, y se calculatrafficBytes. Luego se libera la tarea original dememPool_ncclTaskBcast.

Paso 2: Agrupar en buckets por (func, op, datatype).Las tareas salen del sorter en orden descendente por size y luego se asignan al arraytasksByFnOpTy:

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

Cálculo del índice:((int)task->func * ncclNumDevRedOps + (int)task->opDev.op) * ncclNumTypes + (int)task->datatype. Esta es una linealización de un array tridimensional.

Paso 3: Agregación y selección de algoritmo.Para cada bucket, agrega tareas de tamaño similar (dentro de 4 veces) y luego llama ancclGetAlgoInfo：

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

Paso 4: Agrupar en buckets por (collnet, nvls).Según el tipo de algoritmo, asigna las tareas acollBins[2][2]：

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

Paso 5: Concatenar la cola final.Concatena los cuatro buckets enplanner->collTaskQueue：

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

Estructura de datos: ncclTaskCollSorter

ncclTaskCollSorteres un sorter de inserción ordenado portrafficBytes.ncclTaskCollSorterInsertInserta la tarea en la posición correcta,ncclTaskCollSorterDequeueAllextrae todas las tareas en orden.

Control de concurrencia: runtimeConn y establecimiento de conexión

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

Sicomm->runtimeConnes verdadero (modo de conexión en runtime), y el channel de algún algoritmo aún no se ha inicializado, se marcaalgoNeedConnect. Esto activará el establecimiento de conexión más adelante.

Experiencia real en producción: condiciones límite de la agregación

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

La condición de agregación esaggEnd->trafficBytes < 4 * aggBeg->trafficBytes, y ninguna de las dos tareas estableceaggIsolate. Si el usuario establece per-call config (por ejemplo,maxCTAs），aggIsolatese establecerá en true, esta tarea no se agregará.

Un escenario real de problema: el usuario configurómaxCTAs=4para cierto AllReduce, esperando que usara solo 4 CTA. Pero debido a la lógica de agregación, esta tarea puede fusionarse con tareas adyacentes, provocando que la cantidad real de CTA usados no coincida con lo esperado. La solución es estableceraggIsolate—NCCL ya ha manejado esto encollTaskAppend:

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

---

Cinco, scheduleCollTasksToPlan: división de channels y control de presupuesto

Modelo intuitivo

scheduleCollTasksToPlanes el "planificador" del módulo enqueue. Asigna tareas a channels concretos y calcula la división de datos de cada channel. Esto es como el sistema de planificación de producción de una fábrica: decide qué hace cada línea de producción y cuánto hace.

Sin este paso, el kernel de GPU no sabría qué parte de los datos debe procesar.

Paso a paso: algoritmo de división de channels

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

Paso 1: Estimación del presupuesto.Primero estima cuántas tareas pueden caber en este plan:

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

ncclTestBudgetComprueba si los bytes de trabajo superan el presupuesto:

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

Paso 2: Calcular el tráfico de cada channel.Según kind (collnet/nvls), calculatrafficPerChannel：

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

Paso 3: Ruta Collnet.Si es un algoritmo collnet, la asignación de channels es relativamente simple:

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

Paso 4: División en celdas de la ruta normal.Esta es la parte más compleja. NCCL divide los datos en "cells", y cada cell es una unidad mínima de transferencia:

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

Variables clave:

• cellSize: bytes por cell, al menosMinTrafficPerChannel（32KB）
• cells: número total de cells
• cellsPerChannel: número de cells procesadas por cada channel
• cellsLo/cellsHi: número de cells de los channels inicial y final (puede no estar completo)

Paso 5: Calcular chunkGrains.Llama acalcCollChunking：

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

para cada segmento de channelPaso 6: Generar proxyOp.

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

Genera operaciones proxy para cada channel:

ncclDevWorkCollEstructura de datos: ncclDevWorkColl

Flag directo

📎 src/enqueue/enqueue.cc:897

Control de concurrencia: operaciones de bits de channelMask(2ull << channelHi) - (1ull << channelLo). Por ejemplo, channelLo=2, channelHi=5, el resultado es(2<<5) - (1<<2) = 64 - 4 = 60 = 0b111100, es decir, los bits 2-5 quedan establecidos.

Problemas en producción: desbordamiento de presupuesto

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

Si el presupuesto no es suficiente, se devuelve directamentencclSuccess, dejando que el bucle externo cree un nuevo plan. Esta es una estrategia de degradación elegante:no genera error, simplemente procesa por lotes。

Un escenario real de problemas: siNCCL_WORK_FIFO_BYTESse configura demasiado pequeño, cada plan solo podrá contener muy pocas tareas, aumentando el número de lanzamientos de kernel y reduciendo el rendimiento.

---

Seis, finishPlan: de tareas a parámetros de kernel

Modelo intuitivo

finishPlanes el "empaquetador" del módulo enqueue. Empaqueta tareas, batch y proxyOp en una estructura de parámetros que el kernel puede leer directamente. Esto es como empaquetar un envío: meter piezas sueltas en una caja, pegar la etiqueta de envío y esperar a que salga.

Paso a paso: la lógica de empaquetado de finishPlan

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

Paso 1: decidir el tipo de almacenamiento.Si todo el trabajo cabe en kernel args, usarncclDevWorkStorageTypeArgs：

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

Paso 2: asignar kernelArgs.Asignar desde la pila de memoria:

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

Paso 3: colocar los batch en round-robin.El primer batch de cada channel debe colocarse enbatchZero[blockIdx.x]：

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

Paso 4: fusionar las colas de proxyOp.Ordenar por mezcla según opCount:

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

Estructura de datos: ncclDevKernelArgs

ncclDevKernelArgses la estructura de parámetros que se pasa al kernel. Contiene:

• comm: comunicador del lado del dispositivo
• channelMask: máscara de bits de channel
• workStorageType: tipo de almacenamiento de trabajo
• workBuf: puntero del búfer de trabajo
• workMask: máscara del búfer de trabajo

Problemas en producción: orden de batch

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

El comentario lo dice muy claro: "The first batch for each channel must be located at batchZero[blockIdx.x]". Si este orden es incorrecto, el kernel leerá el batch equivocado, provocando corrupción de datos.

---

Resumen del capítulo

En este capítulo hemos seguido la ruta completa desdencclAllReducehastancclTaskColl:

1. ncclAllReduceconstruyencclInfo, empaqueta los parámetros del usuario

2. ncclEnqueueCheckvalida parámetros, maneja la semántica de group

3. taskAppenddistribuye a distintas rutas según el tipo de operación

4. collTaskAppendgenerancclTaskColl, analiza la configuración

5. ncclPrepareTasksagrupa por (func, op, datatype), calcula el algoritmo

6. scheduleCollTasksToPlandivide channels, generancclDevWorkColl

7. finishPlanempaqueta en parámetros de kernel

Ideas clave de diseño:

• Desacoplamiento por capas: cada función hace solo una cosa, pasando estado mediantencclInfoyncclTaskColl
• Control de presupuesto: mediantencclTestBudgetse controla el tamaño de cada plan
• Optimización por agregación: las tareas de tamaño similar se agregan, reduciendo el número de lanzamientos de kernel
• Prioridad de configuración：env > per-call > comm

En el próximo capítulo entraremos entask_sched, para ver cómo NCCL organiza el orden de ejecución de múltiples channels y múltiples kernels.

Reflexión y autoevaluación de este capítulo

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

Hasta aquí, hemos visto claramente cómo ncclAllReduce pasa de ser una llamada del usuario a una serie de tareas kernel ejecutables: validación de parámetros, determinación de algoritmo/protocolo, división de canales, y finalmente la generación de ncclInfo y ncclTaskColl. Pero crear las tareas es solo el primer paso: aún necesitan ser programadas en múltiples canales, generar parámetros de lanzamiento del kernel, y manejar el envío por lotes y el ordenamiento de dependencias bajo la semántica de grupo. El siguiente capítulo profundizará en src/enqueue/task_sched y src/enqueue/task_prep, respondiendo a "por qué un solo AllReduce lanza múltiples kernels, y cómo se garantiza el orden y las dependencias entre ellos", mientras revela cómo ncclGroupStart/ncclGroupEnd en src/group.cc fusionan múltiples llamadas a la API en un solo envío.

Capítulo 7: Planificador de tareas: cómo task_sched orquesta la ejecución de múltiples canales y kernels

En el capítulo anterior seguimos ncclAllReduce hasta ncclTaskColl: el objeto descriptor de tarea ya está en comm->planner. Pero el descriptor de tarea es solo una "orden de trabajo", aún no se ha convertido en el kernel que realmente se ejecuta en la GPU. Este capítulo responde a tres preguntas: ¿cómo se acumulan múltiples llamadas a la API para enviarlas juntas? ¿Cómo se dividen las tareas acumuladas entre múltiples canales? ¿Qué garantiza el orden y las dependencias entre múltiples kernels? Primero, un modelo mental general. Imagina NCCL como un restaurante: ncclGroupStart/ncclGroupEnd es el "carrito de compras", el usuario añade varios platos (múltiples llamadas de comunicación colectiva) al carrito; ncclGroupEnd es "hacer el pedido", y la cocina empieza a preparar los platos según el pedido. Y doLaunches es el "coordinador de entrega de platos", que decide qué platos salen primero y cuáles se pueden preparar en paralelo. Sin la semántica de grupo, cada plato se pide por separado, y la cocina tiene que encender el fuego de nuevo para cada plato (lanzar el kernel), lo que supone un coste enorme; sin la programación por rondas de doLaunches, los kernels de múltiples canales se lanzarían fuera de orden, rompiendo las dependencias de datos.

I. Estado global de la semántica de Group: variables thread_local y el modelo de "carrito de compras"

Modelo intuitivo

ncclGroupStartyncclGroupEndTodas las llamadas de comunicación entre ellos no lanzan el kernel inmediatamente, sino que se "acumulan". ¿Dónde se acumulan? Se acumulan envariables globales thread_local (locales al hilo)¿Por qué thread_local? Porque NCCL asume que las llamadas de grupo dentro del mismo hilo son secuenciales, y diferentes hilos tienen cada uno su propio carrito de compras independiente, sin interferir entre sí. Si estos estados fueran variables globales en lugar de thread_local, dos hilos llamando simultáneamente ancclGroupStartse pisarían mutuamente, provocando que las tareas de un hilo sean enviadas por elncclGroupEndde otro hilo, lo cual sería catastrófico.

Estructuras de datos y diseño de memoria

Primero veamos la definición del estado global del grupo.

📎 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 */

Desglose campo por campo:

• ncclGroupDepth: profundidad de anidamiento.ncclGroupStartSe puede llamar de forma anidada (aunque no es común), cadancclGroupStartincrementa en uno,ncclGroupEnddecrementa en uno. Solo cuando llega a 0 se envía realmente. Esto es como un carrito de compras que se puede anidar: abres un subcarrito dentro de un carrito, y solo al finalizar el carrito más externo se hace realmente el pedido.
• ncclGroupError: si cualquier llamada dentro del grupo falla, el error se registra aquí,ncclGroupEndse maneja de forma unificada. Esto evita el estado inconsistente de "después de que una llamada falla, las llamadas posteriores siguen añadiendo cosas al carrito".
• ncclGroupCommHead[ncclGroupTaskTypeNum]: cabezas de listas enlazadas de dominios de comunicación agrupadas por tipo de tarea.ncclGroupTaskTypeNumes el número de tipos de tarea (comunicación colectiva, tareas primitivas, tareas de gestión, registro simétrico, etc.). Cada tipo tiene una lista enlazada, y los nodos de la lista sonncclComm, enlazados mediantecomm->groupNext[type]¿Por qué agrupar por tipo? Porque diferentes tipos de tareas tienen diferentes momentos de envío y relaciones de dependencia: las tareas de comunicación colectiva necesitan preconnect primero, y las tareas de gestión (como destroy) deben ejecutarse al final.
• ncclGroupCommPreconnectHead: lista enlazada de dominios de comunicación que necesitan preconexión. La preconexión es "establecer las conexiones de red de antemano", para evitar la latencia de establecer conexiones en el momento de lanzar el kernel.
• ncclAsyncJobs: cola de tareas asíncronas. Algunas tareas (comoncclCommInitRank) son asíncronas, se colocan en esta cola y se lanzan de forma unificada enncclGroupEnd.
• ncclGroupBlocking: indicador de modo bloqueante.-1indica que aún no se ha determinado,0indica no bloqueante,1indica bloqueo. No se permite mezclar dominios de comunicación bloqueantes y no bloqueantes dentro del mismo grupo; de lo contrario, se produce un error.

Aquí hay un diseño clave:ncclGroupCommHeadesarray, cada elemento es una lista enlazada. Los nodos de la lista se enlazan mediantecomm->groupNext[type], en lugar de usar una estructura de nodo de lista enlazada independiente. Esto significa quencclCommdentro de la estructura se debe reservar el campo de arraygroupNext. Este diseño de «lista enlazada intrusiva» evita asignaciones de memoria adicionales, pero a costa de que la estructurancclCommse vuelva más grande.

Recorrido paso a paso guiado por escenarios

Escenario: el usuario llama ancclGroupStart(), luego llama dos veces consecutivas ancclAllReduce(respectivamente para dos dominios de comunicación diferentes, commA y commB), y finalmente llama ancclGroupEnd()。

Primer paso:ncclGroupStart¿qué hizo?

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

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

Extremadamente simple: incrementar la profundidad en uno. Sin asignación de memoria, sin bloqueos, sin llamadas al sistema. Por esoncclGroupStarttiene casi cero sobrecarga.

Segundo paso:ncclAllReduce¿qué sucede cuando se llama dentro del grupo?

ncclAllReduceinternamente llamará ancclGroupCommJoin(comm, ncclGroupTaskTypeCollective), agregando el dominio de comunicación a la lista enlazada del grupo.

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

Este código tiene varios puntos ingeniosos:

1. Verificación de idempotencia：if (comm->groupNext[type] == NCCL_COMM_GROUP_INVALID)garantiza que el mismo dominio de comunicación solo se agregue una vez dentro del mismo grupo. Si el usuario llama dos veces ancclAllReducepara el mismo comm, la segunda vez no se volverá a agregar a la lista enlazada, pero la tarea se añadirá acomm->planner.

2. Ordenación por clique：intraComm0es el identificador de la «entidad global». Si múltiples dominios de comunicación pertenecen a la misma entidad global (por ejemplo, divididos mediantencclCommSplit), suintraComm0es el mismo y se denominan un clique. El código primero busca el clique porintraComm0e inserta el comm junto a los nodos hermanos del mismo clique. Si no encuentra el clique, inserta en orden ascendente porcommHash. Esta ordenación es para quedoLaunchespueda manejar correctamente la sincronización de barrera dentro del clique.

3. Ámbito de la pila de memoria：ncclMemoryStackPush(&comm->memScoped)asigna un nuevo ámbito de pila de memoria para este comm dentro del grupo. Todas las tareas asignadas para este comm (ncclTaskColl, etc.) se asignan desde esta pila.ncclGroupCommLeaveal hacerncclMemoryStackPoplibera de una vez toda la memoria de las tareas; esta es la optimización clásica de «asignación por lotes, liberación por lotes», que evita la sobrecarga demalloc/freeindividual para cada tarea.

4. Reinicio del planner：memset(&comm->planner, 0, sizeof(comm->planner))vacía el planner, pero conserva los punterospeersyrmaTaskQueues(primero se guardan en variables temporales y se restauran después de memset). ¿Por qué conservarlos? Porque estos dos son arrays preasignados y no necesitan reasignarse cada vez.bcast_infolos valores min/max se restablecen aINT_MAX/INT_MIN, para la optimización de fusión de tareas broadcast posteriores.

Tercer paso:ncclGroupEnd¿qué hizo?

📎 src/group.cc:1039-1164

ncclGroupEndInternales el núcleo. Análisis por secciones:

📎 src/group.cc:1048-1061

if (ncclGroupDepth == 0) {
  WARN("ncclGroupEnd: not in a group call.");
  ret = ncclInvalidUsage;
  goto exit;
}
// ...
if ((--ncclGroupDepth) > 0) goto exit;

Primero verifica la profundidad y luego la decrementa en uno. Si después de decrementar sigue siendo mayor que 0, significa que todavía está dentro de un grupo anidado interno, así que retorna directamente sin enviar. Solo continúa cuando llega a 0.

📎 src/group.cc:1063

if ((ret = ncclGroupError) != ncclSuccess) goto fail;

Si alguna llamada dentro del grupo produjo un error, salta directamente a la limpieza 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);

Crea unncclGroupJob, «transfiriendo» el estado del grupo thread_local al objeto job.ncclIntruQueueTransfertransfiere por completo la colancclAsyncJobsagroupJob->asyncJobs. Este paso es clave: el estado thread_local es «temporal», el objeto job es «persistente» y puede ser retenido por hilos asíncronos.

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

Modo bloqueante: llama directamente agroupLaunchen el hilo actual, completándose de forma síncrona. Modo no bloqueante: crea un hilo que ejecutagroupLaunchNonBlockingy retorna inmediatamentencclInProgress. El usuario posteriormente consulta el progreso mediantencclCommGetAsyncError.

Atención al guardado y restauración decudaGetDevice/cudaSetDevice:groupLaunchinternamente cambiará el dispositivo CUDA (porque distintos comm pueden estar en distintas GPU) y, tras ejecutar, restaura el dispositivo original del usuario. Esto evita que «NCCL cambie internamente de dispositivo y no lo restaure», provocando que llamadas CUDA posteriores del usuario se ejecuten en el dispositivo equivocado.

Reflexiones de diseño y trampas en producción

Trampa 1: mezcla de dominios de comunicación bloqueantes y no bloqueantes。ncclAsyncLaunchcontiene una verificación:

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

¿Por qué no se permite mezclarlos? Porque el grupo bloqueante se ejecuta de forma síncrona en el hilo actual y el grupo no bloqueante se ejecuta de forma asíncrona en un hilo independiente. Si se mezclan, no se puede determinar sincclGroupEnddebe retornar de forma síncrona o retornarncclInProgress. En producción, si el usuario coloca accidentalmente comm bloqueantes y no bloqueantes en el mismo grupo, recibiráncclInvalidArgument, pero en ese momento el estado del grupo ya ha sido contaminado y es necesario volver ancclGroupStart。

Trampa 2:ncclGroupErrorpropagación de. Si alguna llamada dentro del grupo falla,ncclGroupErrorse establece,ncclGroupEndsaltará a la rama fail y ejecutarágroupCleanup。groupCleanuprecorrerá todos los comm, liberará la memoria del plan en el planner, reiniciará el planner y limpiará rawTaskQueue. Si este paso no se hace limpiamente, la próxima vezncclGroupStartel planner tendrá datos antiguos residuales, lo que provocará envíos duplicados de tareas o fugas de memoria.

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

Atención a la líneacomm->preconnectNext = reinterpret_cast<struct ncclComm*>(0x1). Este es un «valor centinela», que indica que «este comm necesita reconectar preconnect». ¿Por qué? Porque durante cleanup no se sabe si preconnect tuvo éxito, así que se fuerza a verificarlo de nuevo la próxima vez.0x1este valor es muy ingenioso: no es un puntero válido, pero puede usarse como marca de «no inicializado».ncclGroupCommPreconnectverificaif (comm->preconnectNext == reinterpret_cast<struct ncclComm*>(0x1))para determinar si es necesario agregarlo a la lista enlazada de preconnect.

---

Dos, preparación de tareas:ncclPrepareTaskscómo convertir la descripción de una tarea en una unidad programable

Modelo intuitivo

ncclPrepareTasksEs la fase de «preparación de ingredientes». Los ingredientes en el carrito de compras (descripción de la tarea) aún están crudos; primero hay que lavarlos, cortarlos y prepararlos (determinar el algoritmo, el protocolo, la división de channels) antes de poder cocinarlos (lanzar el kernel). Si se omite este paso y se lanza el kernel directamente, el kernel no sabrá cómo dividir los datos ni qué ruta tomar, y fallará de inmediato.

Recorrido paso a paso guiado por escenarios

ncclPrepareTasksSe invoca engroupLaunchLegacy:

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

ncclPrepareTasksLa salida son dos cosas:algoNeedConnectEl arreglo (qué algoritmos necesitan establecer conexión) y la bandera (si se necesita conexión). SineedConnectes verdadero y se soporta cuMem, se crea un preconnect job que se ejecuta de forma asíncrona.needConnect¿Qué hace internamente? Recorre las tareas en

ncclPrepareTasks, para cada tarea determina el algoritmo y el protocolo, y luego llama acomm->plannerpara agregar la tarea al plan del planner. Esta lógica ya se desarrolló en el capítulo anterior, así que no se repetirá aquí.taskAppendPuntos clave:

Se llamancclPrepareTaskscomm por comm, pero preconnect se ejecutapor clique en lote. ¿Por qué? Véase el comentario en:groupLaunchLegacyCopiar

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

Se hace preconnect clique por clique para evitar que split shared comms conecten simultáneamente el mismo grupo de conexiones y provoquen una condición de carrera. Si dos comm se dividieron a partir del mismo comm padre, pueden compartir algunas conexiones. Si se hace preconnect en paralelo, dos hilos podrían intentar establecer la misma conexión al mismo tiempo, causando conexiones duplicadas o un estado de conexión inconsistente. Al ejecutar por clique de forma serial, se garantiza que solo un clique esté estableciendo conexiones a la vez.Control de concurrencia e interacción de bajo nivel

Es el núcleo del lanzamiento de tareas asíncronas:

asyncJobLaunchCopiar

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

Optimización de job único

1. : si solo hay un job en la cola, no se crea un hilo y se ejecuta directamente en el hilo actual. Esto evita la sobrecarga de crear y hacer join de un hilo. Para un grupo de un solo comm, este es el caso común.Máquina de estados atómica

2. es una variable atómica con tres estados:：job->state. Después de que el hilo de trabajo termina, usancclGroupJobRunning、ncclGroupJobDone、ncclGroupJobJoinedpara establecerCOMPILER_ATOMIC_STORE(..., std::memory_order_release); el hilo principal usaDonepara leer. El emparejamiento release/acquire garantiza que todas las escrituras en memoria del hilo de trabajo sean visibles para el hilo principal.COMPILER_ATOMIC_LOAD(..., std::memory_order_acquire)Espera ocupada + microsueño

3. : el hilo principal sondea el estado de todos los jobs; si todavía hay jobs en ejecución,y continúa sondeando. ¿Por qué usar 1 microsegundo en lugar de una variable de condición? Porque preconnect es una tarea corta (normalmente de decenas de microsegundos a unos pocos milisegundos), y la sobrecarga de despertar una variable de condición puede ser mayor que la espera ocupada. El sueño de 1 microsegundo evita el desperdicio de CPU causado por el giro puro.sleep_for(1us)Propagación de errores y abort

4. : si cualquiera de los jobs falla,se establece, y elerrorJobAbortFlagde todos los jobs posteriores se establece atómicamente en 1. El hilo de trabajo verificaabortFlagdurante la ejecución y, si detecta que se ha abortado, sale antes de tiempo. Este es el mecanismo de «fallo rápido», que evita que después de que un job falle los demás sigan ejecutándose inútilmente.abortFlagDiagrama Mermaid: flujo de control del envío de group

Copiar

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

---

: programación por rondas de múltiples channels y múltiples kernelsdoLaunchesModelo intuitivo

es el «despachador de platos». La cocina (GPU) tiene varios fogones (channels), y cada plato (kernel plan) debe servirse en orden. Pero los platos de distintos comm pueden servirse en paralelo, mientras que los platos del mismo comm deben servirse en orden. El despachador debe garantizar que: los comm dentro del mismo clique avancen sincronizados (usando barrier), y que distintos cliques puedan avanzar de forma independiente.

doLaunchesEstructuras de datos y diseño de memoria

Las estructuras de datos centrales de

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

Recorrido paso a paso guiado por escenarios

Escenario: dos comm (commA y commB) pertenecen al mismo clique (intraComm0igual), y cada comm tiene 3 kernel plans pendientes de lanzar.

Primer nivel de bucle: recorrer clique

El bucle externodo-whilerecorre todos los cliques.cliqueHeades el primer comm del clique actual. El bucle internodo-whilerecorre todos los comm dentro del clique (comm->intraComm0 == cliqueHead->intraComm0）。

Para cada comm:

• cudaSetDevice(comm->cudaDev): cambia a la GPU correspondiente a ese comm.
• ncclLaunchPrepare(comm): prepara el lanzamiento, incluyendo configurar el stream de CUDA, verificar recursos, etc.
• ncclCommIntraBarrierIn(comm, 1): entra en la barrier, con valor inicial 1.

Segundo nivel de bucle: programación por rondas

while (true)El bucle ejecuta «rondas». En cada ronda, cada comm dentro del clique lanza un kernel plan.

La clave está en el cálculo demoreRounds:

• Hay modo barrier（useBarrier == true）：moreRounds = 0 != ncclCommIntraBarrierOut(comm)。ncclCommIntraBarrierOutes una operación de reducción barrierentre comms. Espera a que todos los comm dentro del clique hayan llamado ancclCommIntraBarrierIn, y luego devuelve el resultado de la reducción de todos los valores de entrada (aquí, un OR lógico). Si algún comm todavía tiene planes sin lanzar, el resultado de la reducción es 1,moreRoundses true, y se continúa con la siguiente ronda. Si ningún comm tiene planes sin lanzar, el resultado de la reducción es 0,moreRoundses false, y se entra en la final round.
• Modo sin barrier：moreRounds |= comm->planner.unlaunchedPlansHead != nullptr. Verificar directamente si cada comm todavía tiene algún plan no iniciado. Nota que aquí se usa|=, siempre que un comm todavía tenga plan,moreRoundsserá true.

¿Por qué se necesita una barrier? Porque los comm dentro del clique son "hermanos", pueden compartir recursos de GPU o conexiones de red. Si un comm lanzó 3 kernels y otro solo lanzó 1, el comm que terminó primero entrará enncclLaunchFinish, liberará recursos, mientras que el otro comm todavía está usando esos recursos, causando use-after-free. La barrier garantiza que todos los comm dentro del clique avancen sincronizados: o todos lanzan la ronda N, o todos entran en la final round.

Rama de lanzamiento de 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);
}

Tres tipos de plan:

• isCeColl: comunicación colectiva CollNet (usar offload de tarjeta de red para comunicación colectiva).
• isRma: tareas RMA (Remote Memory Access).
• Predeterminado: kernel normal de GPU.

La función de lanzamiento es diferente para cada tipo, pero todas siguen el patrón "Before -> Launch -> After":

• ncclLaunchKernelBefore_NoUncapturedCuda: preparación antes del lanzamiento (configurar parámetros del kernel, subir al dispositivo, etc.).
• ncclLaunchKernel: lanzamiento real del kernel (cudaLaunchKernel）。
• ncclLaunchKernelAfter_NoCuda: limpieza después del lanzamiento (actualizar estado, liberar recursos temporales).

Final round

CuandomoreRoundses false, se ejecutancclLaunchFinish(comm). Este paso realiza la limpieza final: liberar memoria del plan, actualizar el estado del comm, notificar al hilo proxy, etc.

Control de concurrencia e interacción con hardware

ncclCommIntraBarrierIn/Outes la primitiva de sincronización de los comm dentro del clique. Su implementación involucra operaciones atómicas y espera activa.Inescribe el valor en memoria compartida,Outespera a que todos los comm escriban y luego lee el resultado de la reducción. Esta barrier esentre procesos(si los comm están en procesos diferentes), la capa inferior puede usar memoria compartida o red.

¿Por qué usar barrier en lugar de simplemente "verificar si todos los comm todavía tienen plan"? Porque "verificar" no es atómico: cuando commA verifica, commB todavía tiene plan, commA decide continuar; pero commB lanza inmediatamente su último plan después de la verificación de commA y entra en la final round. commA todavía está lanzando kernels, commB ya liberó los recursos compartidos. La barrier convierte "verificar" y "decidir" en una operación atómica, eliminando esta condición de carrera.

Guía de prevención de errores en producción

Trampa 1: uso mixto de 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;
}

Si una parte de los comm dentro del clique están en modo CUDA graph capture y otra parte no, se reporta error directamente. El comentario dice "these comms are permanently trashed" — porque ya entraron en la barrier pero no salieron, el estado de barrier de estos comm nunca será consistente, y no podrán usarse posteriormente. Este es unerror irrecuperable, el usuario debe reconstruir el dominio de comunicación. En producción, si el usuario mezcla comm con graph capture y sin capture, recibiráncclInvalidUsage, pero lo más grave es que el comm ya está dañado.

Trampa 2:useBarrierdependencia de configuración de。useBarrier = ncclParamLaunchMode == ncclLaunchModeGroup. Si el usuario configuróNCCL_LAUNCH_MODE=GROUP, se toma la ruta con barrier; de lo contrario se toma la ruta sin barrier. En la ruta sin barrier,moreRoundsse acumula con|=, pero cada comm decide independientemente. Si commA todavía tiene plan y commB no, commB entrará en la final round ejecutandoncclLaunchFinish, mientras que commA todavía está lanzando kernels. Esto es seguro en algunos escenarios (no hay recursos compartidos entre comm), pero si se comparten hilos proxy o conexiones de red, puede causar problemas. Por eso se recomienda usar el modo barrier por defecto.

---

Cuatro,groupLaunchLegacycadena de ejecución completa de

Walkthrough paso a paso guiado por escenarios

groupLaunchLegacyes el flujo completo de envío en modo bloqueante. Se ejecuta en orden:

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

Para cada comm que necesita preconnect, crear unncclP2PPreconnectFuncjob, luego lanzarlos en lote.ncclP2PPreconnectFuncinternamente llama ancclTransportP2pSetuppara establecer la conexión P2P.

Fase 2: registro de memoria simétrica

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

El registro de memoria simétrica (ncclCommWindowRegisteretc.) se ejecuta en lote por clique.

Fase 3: preconnect de comunicación colectiva

📎 src/group.cc:810-870

if (groupCommHeadMain[ncclGroupTaskTypeCollective] != nullptr) {
  // 按 clique 逐个 prepare + preconnect
  // 然后 ncclTasksRegAndEnqueue
  // 然后 debug check
}

Esta es la fase central. Se llama ancclPrepareTasksAndCollPreconnectclique por clique, luegoasyncJobLaunchejecuta el preconnect. Una vez completado el preconnect, se llama ancclTasksRegAndEnqueuepara registrar la tarea en el plan y generar los parámetros de lanzamiento del kernel.

Fase 4:doLaunches

📎 src/group.cc:872-874

if ((!simInfo) && (groupCommHeadMain[ncclGroupTaskTypeCollective] != nullptr)) {
  NCCLCHECKGOTO(doLaunches(groupCommHeadMain[ncclGroupTaskTypeCollective], ncclGroupTaskTypeCollective), ret, fail);
}

Lanzar todos los kernel plan.

Fase 5: limpieza

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

Limpiar los jobs asíncronos, luego recorrer todos los comm llamando ancclGroupCommLeave. Nota el conteo dereclaimSteps: cadaGROUP_MAX_RECLAIM_STEPS(10) llamadas a group, sondeando callbacks una vez. Esto es para evitar la sobrecarga de sondear callbacks en cada group, y al mismo tiempo garantizar que los callbacks no se acumulen indefinidamente.

Diagrama Mermaid:groupLaunchLegacyflujo de datos de

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

---

V.groupLaunchEnqueueRearch: el nuevo planificador de la nueva arquitectura

Modelo intuitivo

groupLaunchEnqueueRearches la nueva arquitectura de planificación que NCCL está desarrollando. Divide la preparación de tareas, la planificación y el lanzamiento en fases más detalladas, gestionadas mediante una cola de jobs asíncronos. Actualmente los módulos de planificador y lanzador "aún no están implementados", y se recurre al legacydoLaunches。

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

Flujo de ejecución de la nueva arquitectura:

1. Gestionar tareas：ncclMgmtTaskJobFuncProcesarmgmtTaskQueuetareas en (como destroy).

2. Preparación de tareas：ncclTaskPrepareJobFuncLlamar ancclTaskPrepare。

3. Planificación y lanzamiento: recurrir adoLaunches。

La nueva arquitectura usancclGroupJobLaunchen lugar deasyncJobLaunch, añadiendo comprobaciones de estado más estrictas:

📎 src/group.cc:113-116

} else {
  /* safety check */
  assert(state == ncclGroupJobJoined);
}

La versión legacy usaWARNen lugar deassert, la nueva arquitectura usaassert. Esto indica que la nueva arquitectura exige una mayor corrección de la máquina de estados.

Reflexión de diseño

La motivación de la nueva arquitectura esdesacoplar: el legacygroupLaunchLegacymezcla todas las fases en una sola función, lo que dificulta su mantenimiento y extensión. La nueva arquitectura divide cada fase en tipos de job independientes, encadenados mediante colas. Pero actualmente el planificador y el lanzador aún no están implementados, así que es solo "el framework primero".

ncclParamEnqueueRearchEnable()controla si se usa la nueva arquitectura o el 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);
}

El usuario puede cambiar mediante la variable de entornoNCCL_ENQUEUE_REARCH_ENABLE. En producción se recomienda mantener el valor predeterminado (legacy), porque la nueva arquitectura aún está en desarrollo.

---

VI. Group no bloqueante y manejo asíncrono de errores

Step-by-Step Walkthrough guiado por escenarios

El núcleo del group no bloqueante esncclGroupJobCompleteyncclGroupJobAbort：

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

Diseño clave:

1. joinedBandera atómica: usarCOMPILER_ATOMIC_EXCHANGEgarantiza que solo un hilo pueda ejecutar la lógica de join. Si dos hilos llaman simultáneamente ancclGroupJobComplete, solo uno hará el join real, el otro lo omitirá directamente. Esto evita el double-join.

2. Conteo de referencias：groupRefCountregistra cuántos comm están asociados a este group job. Cada comm incrementa el conteo de referencias enncclGroupEndInternal:

📎 src/group.cc:1108-1111

if (job->comm->groupJob == NULL) {
  job->comm->groupJob = groupJob;
  groupJob->groupRefCount++;
}

Solo cuando todos los comm hayan llamado ancclGroupJobCompleteoncclGroupJobAbort, y el conteo de referencias llegue a 0, se elimina el group job. Esto garantiza que el ciclo de vida del group job cubra todos los comm asociados.

3. Semántica de abort：ncclGroupJobAbortprimero estableceabortFlag, luego hace join. El hilo de trabajo compruebaabortFlagdurante la ejecución, y si detecta que fue abortado, sale anticipadamente. Esto es "cancelación cooperativa": no se mata el hilo a la fuerza, sino que se deja que el hilo compruebe la bandera y salga por sí mismo.

Guía para evitar problemas en producción

Problema 3: consulta de errores en group no bloqueante. El group no bloqueante devuelvencclInProgress, el usuario necesita consultar el progreso mediantencclCommGetAsyncError. Si el usuario olvida consultar y llama directamente a la siguiente comunicación, puede encontrarse con el errorncclInProgress. Más grave aún, si el group job todavía se está ejecutando y el usuario llama ancclCommDestroy, se producirá un use-after-free. NCCL evita esta situación mediante el punterocomm->groupJoby el conteo de referencias:ncclCommDestroyprimero compruebacomm->groupJob, si hay un group job sin completar, esperará o reportará un error.

Problema 4:ncclGroupJobCompletevalor de retorno de. Si el group job falla en su ejecución,ncclAsyncJobCompletedevuelve un código de error. PeroncclGroupJobCompletesolo devuelve este código de error en la primera llamada, las llamadas posteriores devuelvenncclSuccess(porquejoinedya es true). El usuario debe comprobar el valor de retorno en la primera llamada, de lo contrario perderá la información del error.

---

Resumen del capítulo

En este capítulo hemos desglosado la cadena completa de planificación de NCCL desde la "descripción de tarea" hasta el "lanzamiento del kernel":

1. Semántica de Group：ncclGroupStart/ncclGroupEndacumula tareas mediante variables thread_local,ncclGroupEndy las envía de forma unificada al hacer . El modo bloqueante se ejecuta de forma síncrona, el modo no bloqueante crea hilos para ejecutarse de forma asíncrona.

2. Preparación de tareas：ncclPrepareTasksdetermina el algoritmo/protocolo,ncclPrepareTasksAndCollPreconnecthace preconnect clique por clique, evitando la condición de carrera de split comms.

3. Planificación por rondas：doLaunchesagrupa por clique, sincroniza los comm dentro del clique con barrier, lanza un kernel plan por ronda, hasta que todos los planes se hayan lanzado.

4. Tareas asíncronas：asyncJobLaunchgestiona jobs asíncronos con una máquina de estados atómica y espera activa, soportando fallo rápido y abort.

5. Nueva arquitectura：groupLaunchEnqueueRearches el nuevo framework de planificación en desarrollo, actualmente recurre al legacydoLaunches。

El próximo capítulo entrará en la última milla del lanzamiento del kernel:ncclLaunchKernelcómo convertirncclKernelPlanen un kernel que realmente se ejecute en la GPU, y cómo el lado del dispositivo leeDevCommlos metadatos.

Reflexión y autoevaluación de este capítulo

Capítulo 8: Lanzamiento de kernel y ejecución en el dispositivo: de la llamada en el host al arranque de los bloques de hilos en la GPU

En el capítulo anterior desglosamos cómo se divide la tarea entre múltiples channels, cómo se generan los parámetros de lanzamiento del kernel y el mecanismo de envío por lotes y ordenación de dependencias bajo la semántica de group. Ahora, el plan de lanzamiento está listo, pero sigue siendo solo una estructura de datos en el lado del host. La pregunta central que responde este capítulo es:ncclKernelPlan¿cómo se convierte en un grid que realmente se ejecuta en la GPU? Seguiremos la cadena de llamadas dencclLaunchKernelpara ver cómo se insertan los parámetros en los kernel args, cómo se selecciona la variante de kernel,cuLaunchKernelExcómo se invoca, y cómo en el lado del dispositivoncclKernelMainlee la descripción del trabajo desde la memoria compartida y la distribuye a la implementación concreta.

Del Plan al Grid: panorama completo de la ruta de lanzamiento

Antes de entrar en detalles, establezcamos un modelo mental global. ImaginemosncclKernelPlancomo un "plano de construcción": registra cuántos channels se van a lanzar (cuántos blocks), cuántos hilos por block, qué work se va a ejecutar y qué función de kernel se usará. YncclLaunchKerneles la acción de "entrada del equipo de construcción": traduce la información del plano a lo que el driver de CUDA puede entender,CUlaunchConfig, y luego llama acuLaunchKernelExpara lanzar realmente el grid a la GPU.

Sin esta capa, toda la programación del lado del host (la división por channel del capítulo anterior, la organización de batches, la ordenación de proxy ops) sería pura teoría: no se ejecutaría ningún kernel en la GPU y la comunicación nunca ocurriría. Este es el último eslabón del tronco de extremo a extremo y también la frontera entre host y device.

Toda la ruta de lanzamiento se puede resumir en tres fases:

1. Preparación de parámetros（finishPlan + uploadWork): organizar las estructuras work, los descriptores de batch y los kernel args en un bloque de memoria contigua, y decidir si se colocan en los parámetros del kernel, en la FIFO o en un búfer persistente.

2. Lanzamiento del kernel（ncclLaunchKernel): calcular las dimensiones de grid/block, ensamblar los launch attributes (CGA cluster, mem sync domain, launch completion event), llamar acuLaunchKernelEx。

3. Entrada en el lado del dispositivo（ncclKernelMain): cada block determina su channelId segúnblockIdx.x, carga el work batch desde los args o la FIFO a la memoria compartida, y luego, mediantencclDevFuncTable, lo distribuye a la implementación concreta de algoritmo/protocolo.

La siguiente figura muestra el flujo de control completo desde el plan hasta el grid, incluyendo las bifurcaciones clave:

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

Esta figura ancla las tres funciones centrales de este capítulo:finishPlan、uploadWork、ncclLaunchKernel. A continuación las desglosaremos una por una.

Preparación de parámetros: cómo encuentra su lugar la estructura work

Modelo intuitivo

finishPlandesempeña un papel similar al de un "empacador" en un centro de clasificación de paquetes. Se enfrenta a un montón de estructuras work dispersas (una por cada operación collective o p2p) y debe decidir: ¿estos work se meten en la "mochila de mano" que son los parámetros del kernel, o se colocan en la "cinta transportadora" que es la FIFO, o se guardan en el "almacén" que es el búfer persistente?

Si esta decisión se toma mal —por ejemplo, si un work es demasiado grande para caber en los parámetros del kernel pero se fuerza a meterlo— el lanzamiento del kernel fallará directamente. Si el work se coloca en el lugar equivocado, el lado del dispositivo leerá datos basura y el resultado de la comunicación será completamente erróneo.

Estructuras de datos y diseño de memoria

Primero veamosncclDevKernelArgsla estructura de , que es el "sobre" entre host y 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 数组
};

Esta estructura solo tiene 5 campos, pero cada uno transporta información clave.channelMaskes una máscara de 64 bits, cada bit corresponde a un channel, y el lado del dispositivo, mediante__popcll, calculablockIdx.xel channelId correspondiente.workStorageTypedetermina desde dónde lee el work el lado del dispositivo:Argsindica que el work está en los parámetros del kernel,Fifoindica que está en el búfer circular,Persistentindica que está en el búfer persistente.

ncclDevWorkBatches el descriptor de batch, que le dice al lado del dispositivo "dónde está el work de este channel y cuántos hay":

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

offsetBitsetes una máscara de 64 bits, cada bit corresponde a una estructura work. El lado del dispositivo mediante__popcyfns(instrucción find n-th set) localiza el offset de cada work.nextJumpynextExtendsse utilizan para encadenar múltiples batches: cuando hay demasiados work para caber en un batch, se crean "batches extendidos".

Step-by-Step Walkthrough

Ahora introduzcamos un escenario concreto: un AllReduce se divide en 4 channels, cada channel tiene 2 estructuras work, en total 8 work.

Primer paso:finishPlandetermina el tipo de almacenamiento.

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

La decisión clave aquí es: sisizeof(ncclDevKernelArgs) + batchBytes + workBytescabe encomm->workArgsBytes(normalmente 4KB), se coloca el work directamente en los parámetros del kernel. De lo contrario, el work se coloca en el FIFO o en un búfer persistente, y en los parámetros del kernel solo se coloca el descriptor de batch.

Segundo paso: colocar los batches por channel de forma alterna en los 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);
}

La lógica de este código es "round-robin": en cada ronda se toma un batch de cada channel que aún tenga batches, y se colocan en el arreglobatchZeroen orden ascendente por número de channel. El propósito de esto es garantizar que "el primer batch de cada channel esté enbatchZero[blockIdx.x]": el lado del dispositivo, cada block medianteblockIdx.xindexa directamente su primer batch, sin necesidad de búsqueda.

nextJumpEl campobatchIx += batch.nextJumpregistra el offset del siguiente batch del mismo channel respecto al batch actual. El lado del dispositivo mediante

puede saltar al siguiente batch, formando una lista enlazada.uploadWorkTercer paso:

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

copiar

1. fifoCursorAquí hay varios puntos clave:La semántica deArgs: para el tipokernelArgs, es un offset relativo a la dirección inicial deFifo; para el tipoPersistent, es un offset relativo a la dirección base del FIFO; para el tipo

2. offsetBase, comienza desde 0.：finishPlanLa corrección deoffsetBase: eluploadWorkdel batch enArgses relativo a la posición inicial del work del plan (comenzando desde 0).sizeof(ncclDevKernelArgs) + batchBytesnecesita convertirlo a un offset relativo a la ubicación de almacenamiento real. Para el tipoFifo, se sumacomm->workFifoProduced。

3. ; para el tipo, se sumaalignas(16)Copia alineada a 16 bytesCOMPILER_ASSUME_ALIGNED: las estructuras work están alineadas a 16 bytes (

4. ), por lo que la copia se realiza en unidades de 16 bytes.le indica al compilador que esta dirección está alineada a 16 bytes, haciendo que el compilador genere instrucciones vectorizadas más eficientes.FifoEspera del FIFOwaitWorkFifoAvailable: para el tipocomm->abortFlag,

espera en spin hasta que el FIFO tenga suficiente espacio. Esta espera verifica

• Args¿Por qué debe haber tres tipos de almacenamiento?
• FifoEsta es una compensación entre espacio y latencia:
• Persistent: el más rápido (memoria constante), pero de capacidad limitada (4KB). Adecuado para mensajes pequeños y poco work.cudaMemcpy: gran capacidad (búfer circular), pero la lectura en el lado del dispositivo pasa por memoria global. Adecuado para mensajes medianos.

: se utiliza en escenarios de captura de CUDA Graph. Como durante la captura de graph no se puede hacer, es necesario preasignar un búfer persistente, copiar el work allí y luego hacer que el kernel lea desde ahí.waitWorkFifoAvailableTrampa 1: desbordamiento del FIFO que provoca deadlock.abortFlagSi📎 src/enqueue/enqueue.cc:1333-1349no verifica

if (COMPILER_ATOMIC_LOAD(comm->abortFlag, std::memory_order_acquire)) {
  return ncclInternalError;
}

verifica explícitamente el abort flag:offsetBitsetcopiar offsetBitsetTrampa 2: desbordamiento de1ull << (offset / workSize).NCCL_MAX_DEV_WORK_BATCH_BYTESes de 64 bits, soporta como máximo 64 work en un batch. Si se superan los 64,ncclDevWorkCollse desbordará. En el código fuente, mediante

se limita el tamaño del batch (1024 bytes), y la estructura work más pequeña es(aproximadamente 80 bytes), por lo que como máximo hay 12 work, sin desbordamiento.uploadWorkTrampa 3: fuga de memoria en modo Persistent.PersistentEn la ramafifoBufHostdencclOsAlignedAlloc,uploadWork_cleanup_fnse asigna mediantecudaMemcpyAsyncy debe liberarse enfail. Sicleanupfalla, la etiquetafifoBufHostverificará si📎 src/enqueue/enqueue.cc:1483-1485es null, y si es null liberará directamente

. Esta cadena de recuperación de errores se puede ver en

Lanzamiento del kernel: de CUlaunchConfig a cuLaunchKernelEx

ncclLaunchKernelEl rol de es similar a una "consola de control de lanzamiento de cohetes". Recibe un plan que ya tiene el combustible cargado (datos de work), calcula los parámetros de vuelo del cohete (dimensiones de grid/block), configura diversas opciones de lanzamiento (cluster, mem sync domain, completion event) y luego presiona el botón de lanzamiento (cuLaunchKernelEx）。

Si este paso falla —por ejemplo, si las dimensiones del grid se calculan mal— se lanzará un número incorrecto de blocks en la GPU, lo que provocará que el trabajo de algunos channels nunca se ejecute y la comunicación quede colgada.

Estructuras de datos y diseño de memoria

CUlaunchConfigEs la estructura de configuración de lanzamiento de la API del driver de CUDA, y NCCL la construye en la pila:

📎 src/enqueue/enqueue.cc:1916-1917

CUlaunchConfig launchConfig = {0};
CUlaunchAttribute launchAttrs[6] = {};
int attrs = 0;

launchAttrsEs un array de como máximo 6 elementos, cada uno de los cuales es unCUlaunchAttribute. NCCL añade condicionalmente distintos atributos según las capacidades del hardware y la versión del driver:

• CU_LAUNCH_ATTRIBUTE_CLUSTER_DIMENSION: dimensión del CGA cluster (sm90+)
• CU_LAUNCH_ATTRIBUTE_CLUSTER_SCHEDULING_POLICY_PREFERENCE: política de programación del cluster
• CU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAIN: dominio de sincronización de memoria (CUDA 12.0+)
• CU_LAUNCH_ATTRIBUTE_LAUNCH_COMPLETION_EVENT: evento de finalización de lanzamiento (CUDA 12.3+)
• CU_LAUNCH_ATTRIBUTE_PROGRAMMATIC_STREAM_SERIALIZATION: serialización de flujo programática (sym kernel)
• CU_LAUNCH_ATTRIBUTE_NVLINK_UTIL_CENTRIC_SCHEDULING: programación centrada en la utilización de NVLink (CUDA 13.0+)

Step-by-Step Walkthrough

Primer paso: calcular las dimensiones de grid y 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);

nChannelsEs el número de bits establecidos enchannelMask, es decir, cuántos blocks debe lanzar este plan. Cada block se encarga de un channel.threadPerBlockSe calcula enscheduleCollTasksToPlanmedianteplan->threadPerBlock = std::max(plan->threadPerBlock, task->nWarps * WARP_SIZE), tomando el mayor de todos los tasksnWarps * 32。

smemEs el tamaño de memoria compartida dinámica. Para un kernel normal, esncclShmemDynamicSize(comm->cudaArch), que es una constante en tiempo de compilación que depende de la arquitectura (sm70+ esncclShmemScratchWarpSize * (NCCL_MAX_NTHREADS / WARP_SIZE)). Para un sym kernel, esplan->kernelDynSmem, porque los requisitos de memoria compartida del sym kernel pueden ser distintos.

Segundo paso: ensamblar los parámetros del 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};

Esta es una forma de pasar parámetros de la API del driver de CUDA:CU_LAUNCH_PARAM_BUFFER_POINTERle indica al driver que "los parámetros no se pasan uno a uno, sino como un bloque de memoria contiguo",CU_LAUNCH_PARAM_BUFFER_SIZEle indica al driver el tamaño de ese bloque. La ventaja de esto es que NCCL puede pasarncclDevKernelArgsy el array batch posterior de una sola vez, sin necesidad de empaquetar los parámetros uno por uno.

Tercer paso: añadir 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) es una característica de hardware introducida en sm90 que permite agrupar varios blocks en un cluster; los blocks dentro del cluster pueden garantizar su programación simultánea en un conjunto de SMs y pueden acceder a la memoria compartida entre sí. NCCL utiliza esta característica para implementar algoritmos como NVLS que requieren sincronización entre blocks.

Nótese la protecciónif (grid.x % clusterSize) clusterSize = 1;: la dimensión del cluster debe dividir exactamente la dimensión del grid, de lo contrario el driver dará error. Sigrid.xno es divisible porclusterSize, se degrada a no usar cluster.

Cuarto paso: añadir 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_EVENTEs una característica introducida en CUDA 12.3: el driver registra un evento cuando el kernel realmente comienza a ejecutarse (no cuando la llamada del lado del host retorna). Esto es crucial para implementar el "orden implícito" (implicit order): NCCL necesita garantizar que varios kernels se ejecuten en orden, pero sin que el lado del host bloquee la espera.

getImplicitOrderLa lógica de es: si el usuario ha configuradolaunchOrderImplicit, y la versión del driver es lo suficientemente reciente, se usancclImplicitOrderLaunch(ordenar con launch event); de lo contrario, se usancclImplicitOrderSerial(ordenar con completion event, es decir, ejecución en serie).

Quinto paso: llamar acuLaunchKernelEx。

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

cuLaunchKernelExEs una nueva API introducida en CUDA 12.0 que admite launch attributes. Para drivers antiguos (< 11.8), NCCL recurre acuLaunchKernel：

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

Control de concurrencia e interacción con el hardware

Mecanismo de relay del Launch completion event.Cuando se usancclImplicitOrderLaunchy el usuario proporcionalaunchCompletionEvent, NCCL no puede pasar directamente el event del usuario al driver, porque el driver solo admite un launch completion event. La estrategia de NCCL es:

1. Pasarcomm->sharedRes->launchEvental driver.

2. EnrelayStream, esperar alaunchEvent。

3. EnrelayStream, registrar el event del usuario.

De esta forma, el event del usuario se disparará después de que el kernel realmente comience a ejecutarse, y no cuando la llamada del lado del host retorne.

Mem Sync Domain。 📎 src/enqueue/enqueue.cc:1938-1942En sm90+, NCCL configuraCU_LAUNCH_ATTRIBUTE_MEM_SYNC_DOMAINcomocudaLaunchMemSyncDomainRemote. Este es el mecanismo de dominios de sincronización de memoria introducido por la arquitectura Hopper, que sirve para aislar las barreras de memoria de distintos kernels y reducir la sobrecarga de sincronización innecesaria.

Guía de trampas en producción

Trampa 1: la dimensión del cluster no divide exactamente y provoca un fallo de lanzamiento.Sigrid.xno es divisible porclusterSize, el driver devolveráCUDA_ERROR_INVALID_VALUE. En el código fuente se protege medianteif (grid.x % clusterSize) clusterSize = 1;, pero esto también implica que la característica de cluster queda deshabilitada silenciosamente. Si el usuario espera la mejora de rendimiento que aporta el cluster, debe comprobarcgaClusterSizeynChannelsla relación entre ellos.

Trampa 2: la versión del driver no cumple los requisitos y el kernel no está disponible. ncclInitKernelsForDeviceverifica los requisitos de controlador de cada kernel durante la inicialización:

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

Si la versión del controlador no es suficiente, el puntero del kernel se establece en null. Posteriormente, si el planificador selecciona este kernel,cuLaunchKernelExfallará. El tuner de NCCL debería evitar seleccionar kernels no disponibles, pero si el usuario fuerza la especificación de un algoritmo (NCCL_ALGO), podría desencadenar este problema.

Punto problemático 3:launchCompletionEventcomportamiento en controladores antiguos.Si la versión del controlador < 12.3, NCCL registrará un event antes del lanzamiento del kernel, lo que significa que el event se disparará antes de que el kernel comience a ejecutarse, en lugar de cuando el kernel realmente comienza a ejecutarse. Esto puede invalidar las suposiciones de temporización del código del usuario.

Entrada del lado del dispositivo: de blockIdx a la implementación concreta

Modelo intuitivo

ncclKernelMaines el "vestíbulo de entrada" de cada block en la GPU. Cuando un block es programado en un SM para comenzar su ejecución, primero entra en este vestíbulo y completa tres cosas: determinar su identidad (qué channel soy), recibir su tarea (cargar el work batch), y luego ir a la ventana correspondiente para realizar el trabajo (llamar a la implementación concreta del algoritmo).

Sin esta entrada, cada variante de kernel tendría que manejar por sí misma el problema de "quién soy y qué debo hacer", lo que resultaría en una gran cantidad de código duplicado.ncclKernelMainmediante los parámetros de plantillaSpecializedFnIdySpecializedRunWorkBatchimplementa el patrón de "entrada genérica + ejecución especializada".

Estructura de datos y diseño de memoria

El diseño de memoria compartida del lado del dispositivo es clave para entenderncclKernelMain.ncclShmemDataes la "mesa de trabajo" compartida por todos los blocks:

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

El diseño de esta estructura está cuidadosamente elaborado:

• argsse coloca al principio porque se copia desde los parámetros del kernel y requiere alineación de 16 bytes.
• commychanneltambién están alineados a 16 bytes, porque se copian mediantecopyToShmem16con instrucciones vectorizadas.
• workStoragees el área de almacenamiento temporal para la estructura work, su tamaño esncclMaxDevWorkBatchBytes()(16KB para sm90+).
• groupsEl array se utiliza para almacenar la información de conexión de cada group,NCCL_MAX_GROUPSes 16.

Step-by-Step Walkthrough

Primer paso: copiar los kernel args a la memoria compartida.

📎 src/device/common.h:426-428

if (tid < sizeof(ncclDevKernelArgs) / sizeof(uint32_t)) {
  ((uint32_t*)&ncclShmem.args)[tid] = ((uint32_t*)args)[tid];
}

Aquí se utilizan los primerossizeof(ncclDevKernelArgs) / 4hilos, cada hilo copia una palabra de 32 bits. ¿Por qué copiar a la memoria compartida? Porque los parámetros del kernel están en memoria constante; aunque el acceso es rápido, cuando cada hilo necesita acceder hay una sobrecarga de broadcast. Después de copiar a la memoria compartida, todos los hilos acceden al mismo bloque de memoria compartida, lo que es más eficiente.

Segundo paso: determinar el 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();

La lógica de este código es: para cada channel activado (args->channelMask & (1ull << tid)), calcular cuántos channels activados hay antes de él (__popcll), si esta cantidad es igual ablockIdx.x, entonces el block actual se encarga de este channel.

Por ejemplo:channelMask = 0b1011(los channels 0, 1, 3 tienen trabajo).blockIdx.x = 0El block de se encarga del channel 0 (hay 0 activados antes),blockIdx.x = 1El block de se encarga del channel 1 (hay 1 activado antes),blockIdx.x = 2El block de se encarga del channel 3 (hay 2 activados antes).

Tercer paso: cargar comm y channel a la memoria compartida.

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

Aquí se dividen los hilos en tres grupos:

• El warp 0: cargancclKernelComm(metadatos del comunicador) a la memoria compartida.
• El warp 1: carga elncclDevChanneldel channel actual (metadatos del channel) a la memoria compartida.
• Los warps restantes: cargan el work batch a la memoria compartida.

copyToShmem16es una función de copia de 16 bytes implementada con PTX inline:

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

Utilizald.v2.u64para cargar 16 bytes desde la memoria global, yst.shared.v2.u64para almacenar en la memoria compartida.__cvta_generic_to_sharedconvierte una dirección genérica en una dirección de memoria compartida (el espacio de direcciones de memoria compartida es de 32 bits).

Cuarto paso: cargar el work batch.

loadWorkBatchToShmemes la parte más compleja. Su tarea es copiar la estructura work apuntada por el descriptor del batch desde la memoria global (o los parámetros del kernel) aworkStorageen la memoria compartida.

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

El núcleo de este código es calcularfnsOfBitset: paraoffsetBitsetel n-ésimo bit activado, cuál es su índice de bit. PTX tiene la instrucciónfnspara hacer esto, pero se expande en muchas instrucciones SASS. La estrategia de NCCL es usar memoria compartida: cada lane verifica si su bit está activado, si lo está, calcula cuántos bits activados hay antes de él, y luego escribe su número de lane enfnsOfBitset[nWorksBelow]。

A continuación viene la copia real:

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

Aquí hay una optimización clave: para el tipoArgs, el código fuente escribe directamente(char*)args + offset, el compilador reconocerá que esto es una lectura desde los parámetros del kernel y generará la instrucciónld.param.v2.u64. Para el tipoFifo, el código fuente escribe(char*)ncclShmem.args.workBuf + (offset & workMask), el compilador genera la instrucciónld.v2.u64.

En los comentarios se enfatiza especialmente que estos dos casos no se pueden combinar:

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

Si el compilador no puede determinar si el puntero apunta al espacio de parámetros o al espacio global, volcará toda la estructura de parámetros (4KB) a la memoria local de cada hilo, y el rendimiento se degradará drásticamente.

Quinto paso: ejecutar el 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();
}

Aquí hay una optimización importante: siSpecializedFnIdcoincide con elfuncIddel batch actual, se llama directamente aSpecializedRunWorkBatch().run(), que es una función especializada en tiempo de compilación, sin la sobrecarga de una llamada a través de puntero de función. De lo contrario, se llama indirectamente a través dencclDevFuncTable[ncclShmem.funcId]().

ncclDevFuncTablees un array de punteros a función del lado del dispositivo, definido porgenerate.pyGenerar:

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

Reflexiones de diseño y problemas en producción

Por qué usar__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__indica al compilador que este parámetro es de solo lectura y puede colocarse en memoria constante. Así, cuando el lado del dispositivo lee, usa la instrucciónld.param, que es más rápida que leer desde memoria global. El comentario menciona que rompe cuda-gdb, por lo que solo se habilita en sm70+.

Punto problemático 1:workStoragedesbordamiento. workStorageEl tamaño dencclMaxDevWorkBatchBytes()esnWorks * workSize, en sm90+ es 16KB. SiNCCL_MAX_DEV_WORK_BATCH_BYTESsupera este valor, se escribirá fuera de los límites. En el código fuente, mediante

se limita el tamaño del batch en el lado host, pero no hay verificación adicional en el lado del dispositivo. Si se elude la restricción del lado host (por ejemplo, modificando variables de entorno), se producirá un desbordamiento de memoria compartida.__syncthreads()Punto problemático 2:La ausencia deloadWorkBatchToShmemprovoca condiciones de carrera.__syncthreads()Después deworkStorage, debe haber un📎 src/device/common.h:479para que todos los hilos vean el__syncthreads(); // publish ncclShmemcompleto. En el código fuente, enworkStoragehay

. Si se elimina esta sincronización, algunos hilos podrían comenzar a leer antes de que while (ncclShmem.aborted == 0)termine de escribirse, leyendo datos basura.

Punto problemático 3: el momento de la verificación de abort.

Solo verifica abort al comienzo de cada batch. Si un batch tarda mucho en ejecutarse, la señal de abort podría tardar mucho en surtir efecto. Esta es una compensación de diseño: verificaciones más frecuentes aumentan la sobrecarga, pero responden más rápido.

generate.pySelección de variantes de kernel: cómo generate.py genera la lista de kernels

Modelo intuitivogenerate.pyEl rol de

es similar al de un "planificador de líneas de producción de una fábrica de automóviles". Se enfrenta a un enorme espacio combinatorio (7 tipos de operaciones de conjunto × 5 tipos de operaciones de reducción × 12 tipos de datos × 7 algoritmos × 3 protocolos) y necesita decidir: ¿qué combinaciones requieren generar un kernel dedicado? ¿Cuáles pueden compartir un kernel genérico?

generate.pySi se genera un kernel para cada combinación, el tiempo de compilación y el tamaño del binario explotarán. Si solo se genera un kernel genérico, en tiempo de ejecución se volverá más lento debido a llamadas a punteros de función y evaluaciones de ramas.

1. device_table.cuLa solución dencclDevFuncTablees el "kernel representativo": generar un kernel para cada clase de equivalencia y distribuir en tiempo de ejecución mediante una tabla de punteros de función.

2. host_table.ccEstructuras de datos y diseño de memoriancclDevKernelList、ncclDevKernelForFunc、ncclDevFuncRowToIdGenera tres archivos clave:

3. : el<coll>_<op>_<ty>.cudel lado del dispositivo, que mapea funcId a la función de dispositivo concreta.

Step-by-Step Walkthrough

: las tablas

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

CadancclDevFuncId(): la implementación concreta del kernel.

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

ncclDevFuncIdCopiarncclDevFuncRowToIdEste orden de enumeración debe coincidir con la fórmula de cálculo deAllReduce Sum i32:AllReduce Sum u32Copiar

Lo que calcula

📎 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_primaryse mapea al "ID de función principal". La razón de este mapeo es que muchas filas pueden mapearse a la misma función principal (por ejemplo, todas las filas de

📎 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).AllGatherSegundo paso: calcular la función principal y la función kernel.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

Mapea enteros con signo a enteros sin signo (porque la suma/multiplicación es igual para ambos):

📎 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_ncclDevKernelMapea múltiples funciones principales al mismo kernel (por ejemplo, todos los algoritmos de

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

Copiar__global__Tercer paso: generar la definición del kernel.ncclKernelMainCopiarspecializedFnIdDespués de la expansión de la macro es:RunWorkBatch<coll, ty, redop<ty>, algo, proto>。

Copiar

yNCCL_EXACT_KERNEL_NAMESReflexiones de diseño y problemas en producción〔Inferencias de diseño y compensaciones arquitectónicas〕best_kernel¿Por qué usar "kernels representativos" en lugar de un kernel por combinación?

Compensación entre tiempo de compilación y tamaño del binario. El espacio combinatorio completo es 7 × 5 × 12 × 7 × 3 ≈ 8820 kernels, cada kernel tarda unos segundos en compilarse, lo que suma varias horas. Además, el tamaño del binario alcanzaría cientos de MB. Al mapear a kernels representativos, el número real de kernels generados se reduce a unas pocas decenas.required_cudaPunto problemático 1:Provoca una explosión de compilación.

📎 src/device/generate.py:130-154

Si se establece esta variable de entorno,

Capítulo siguiente: Capítulo 9 →

En el capítulo anterior rastreamos cómo el lado host traduce un AllReduce en un kernel __global__, y vimos que el punto de entrada del lado dispositivo ncclKernelMain realiza el despacho según el algoritmo y el protocolo. Pero el despacho solo selecciona las herramientas; lo que realmente determina el rendimiento es cómo estas herramientas ejecutan el movimiento de datos. Este capítulo profundiza en las tres primitivas de transferencia bajo src/device: LL, LL128 y Simple, analizando una por una sus implementaciones de movimiento de datos para comprender las compensaciones entre latencia y ancho de banda de los distintos protocolos.

Por qué el mismo AllReduce necesita tres primitivas de transferencia

Primero establezcamos un modelo intuitivo. Imaginemos una fábrica en línea de ensamblaje: la materia prima (datos del usuario) entra por un extremo, el producto terminado sale por el otro, y en el medio hay varias estaciones (ranks) que deben intercambiar productos semielaborados. Hay tres formas de transferir los semielaborados:

• LL（Low Latency）: como dos personas pasándose un papel cara a cara; en el momento de pasarlo, la otra persona ya sabe que «esto es para ti», con un costo de handshake casi nulo. Pero el papel es muy pequeño: solo se pueden pasar 8 bytes de datos útiles por vez. Adecuado para mensajes pequeños.
• LL128: se cambia el papel por una nota de 128 bytes; se pasan 120 bytes de datos útiles por vez, pero se exige que la nota esté alineada a 16 bytes, de lo contrario primero hay que «recomponerla» en memoria compartida. Adecuado para mensajes medianos.
• Simple: como un casillero de paquetería: primero se coloca el paquete en el casillero (búfer FIFO) y luego se envía una notificación de «hay mercancía en el casillero número N». El costo de handshake es alto, pero se puede mover mucho de una vez. Adecuado para mensajes grandes.

Las tres primitivas comparten el mismo esqueleto de plantillaPrimitives<T, RedOp, Fan, Direct, Proto, P2p, isNetOffload>, y medianteProtoeste parámetro de plantilla se especializan tres versiones📎 src/device/primitives.h:117-117。ProtoLL、ProtoLL128、ProtoSimpleCada una de las tres estructuras porta constantes y métodos de cálculo relacionados con el protocolo📎 src/device/primitives.h:25-75, y el código del algoritmo solo llama aprims.send()、prims.recvReduceSend()este tipo de interfaz unificada, sin preocuparse por cuál protocolo hay debajo.

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"]

Esta figura explica «por qué la misma lógica de AllReduce necesita tres primitivas de transferencia»: la capa de algoritmo es independiente del protocolo, y las diferencias de protocolo quedan encapsuladas enPrimitiveslas tres especializaciones de.

LL: transferencia sin handshake con flag incrustado en la línea de datos

Modelo intuitivo

La idea central de LL es:meter «los datos» y la marca de «si los datos están listos» en la misma unidad de lectura/escritura de 16 bytes. El receptor no necesita un «mensaje de notificación» adicional; basta con sondear el campo flag en la línea de datos: si el flag coincide, los datos han llegado. Es como al enviar una carta imprimir «la firma del destinatario» directamente en el sobre: el cartero, al ver la firma, sabe si debe entregarla, sin necesidad de enviar por separado un acuse de recibo.

Sin este diseño, el receptor tendría que esperar primero una notificación de «datos escritos» y luego volver a leer los datos: dos idas y vueltas a memoria, el doble de latencia.

Estructura de datos y diseño de memoria

La unidad de transferencia de LL esunion ncclLLFifoLine, y por el ensamblado destoreLLse puede ver su diseño📎 src/device/prims_ll.h:154-158：

st.volatile.global.v4.u32 [%0], {%1,%2,%3,%4};
// 写入 4 个 u32：data1, flag, data2, flag

UnncclLLFifoLineson 16 bytes, dispuestos como[data1(4B) | flag(4B) | data2(4B) | flag(4B)]. Los datos útiles son solo 8 bytes (data1 + data2); los otros 8 bytes son todo flag. Esta es la razón por la queProtoLL::calcBytePerGrain()devuelvesizeof(uint64_t): «One 16-byte line has 8-bytes of data»📎 src/device/primitives.h:55-57。

Campos clave (especialización LL dePrimitives)📎 src/device/prims_ll.h:20-42：

El desplazamiento del búfer se calcula medianterecvOffset(i) = (recvStep[i] % NCCL_STEPS) * stepLines:📎 src/device/prims_ll.h:44-46，NCCL_STEPSes el número de ranuras del búfer circular,stepLineses el número de líneas por ranura. El valor del flag se calcula medianterecvFlag(i) = NCCL_LL_FLAG(recvStep[i] + 1):📎 src/device/prims_ll.h:56-58, nótese que+1, porque el valor inicial del flag es 0, y el flag del primer paso debe ser 1 para distinguirse de «no escrito».

Walkthrough guiado por escenario: un recvReduceSend

Supongamos que el rank 0 ejecuta en un Ring AllReducerecvReduceSend: recibir datos del rank anterior, hacer reduce con los datos locales y enviarlos al siguiente rank. La cadena de llamadas esrecvReduceSend(inpIx, eltN) → LLGenericOp<1, 1, Input, -1>(inpIx, -1, eltN, false) 📎 src/device/prims_ll.h:403-405。

Primer paso: esperar a que el búfer de envío esté disponible. waitSendCompruebasendConnHeadCache + NCCL_STEPS < sendConnHead + 1 📎 src/device/prims_ll.h:73-89. El significado es: si el progreso de consumo del par (head) se queda demasiado atrás respecto a mí, significa que el búfer circular está casi lleno y hay que esperar.NCCL_STEPSes el número total de ranuras del búfer,sendConnHead + 1es la ranura que estoy a punto de ocupar. Mientras se espera, se sondea*sendConnHeadPtrpara actualizar la caché y periódicamente se llama acheckAbortpara comprobar si se ha abortado📎 src/device/prims_ll.h:73-89。

Segundo paso: cargar los datos locales. DataLoader::loadBeginSe encarga del problema de alineación📎 src/device/prims_ll.h:200-216. Cuandosizeof(T) <= 2(por ejemplo half o int8), la dirección de origen puede no estar alineada a 4 bytes, así que primero se lee alineado a 4 bytes enu4[0..2], se registramisalign, y luego enloadFinishse usa__funnelshift_rpara hacer desplazamientos a nivel de byte y reconstruir el valor correcto de 64 bits📎 src/device/prims_ll.h:218-225. Esta es una técnica típica de «lectura alineada + reensamblado por desplazamiento», que evita la penalización de rendimiento de los accesos no alineados.

Tercer paso: leer los datos del par y esperar el flag. readLLes el núcleo📎 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));

Utilizald.volatile.global.v4.u32Leer 16 bytes de una vez (4 u32), luego verificar si ambos campos flag son iguales al valor esperado.volatileLa palabra clave garantiza que el compilador no optimice ni almacene en caché esta lectura en un registro—porque el par podría escribir nuevos datos en cualquier momento. Ambos flags deben coincidir porque el escritorstoreLLescribe 4 u32 de una vez, teóricamente podría dividirse en dos escrituras de 8 bytes, ambos flags deben coincidir para garantizar la integridad de los 16 bytes.

Cuarto paso: reduce y enviar.Después de recibir peerData,applyReduce(redOp, peerData, data)realizar la reducción📎 src/device/prims_ll.h:279. LuegostoreLL(sendPtr(i) + offset, data, sendFlag(i))escribir el resultado en el búfer de envío📎 src/device/prims_ll.h:295-296. Nota sobre el orden de envío: primero enviari=1..MaxSend(generalmente el peer de red), finalmente enviari=0(generalmente el peer local)📎 src/device/prims_ll.h:291-297. El comentario lo dice claramente: «Send : inter-node, then intra-node, then local»—primero enviar el lento (red), dejarlo volar en segundo plano, luego enviar el rápido (local), así el peer local no espera por la red.

Quinto paso: avanzar el step y post. incRecv(i)Incrementar el paso de recepción📎 src/device/prims_ll.h:91-93，postRecv()escribirrecvConnHeadde vuelta al puntero global📎 src/device/prims_ll.h:94-97, notificar al par «ya he consumido este paso». El lado de envíoincSendtiene una lógica especial📎 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));
}

cuando el step alcanzaNCCL_LL_CLEAN_MASKel límite, se deben escribir todas las filas del slice completo con el flag actual (datos rellenados con 0). ¿Por qué? Porque el flag se reutiliza cíclicamente, si el flag de la última vez de alguna fila coincide casualmente con el valor esperado de esta vez, el receptor podría pensar erróneamente que los datos están listos. Esta operación de «cleanup» actualiza uniformemente los flags de todas las filas al nuevo valor, eliminando ambigüedades.

Control de concurrencia e interacción con hardware

La sincronización de LL depende completamente devolatilelectura/escritura + sondeo de flag, sin locks.barrier()usar__syncwarp()(en caso de un solo warp) obarrier_sync(15 - group, nthreads)(en caso de múltiples warps)📎 src/device/prims_ll.h:63-69。15 - groupes el número de barrera, NCCL usa diferentes números de barrera para aislar diferentes grupos, evitando interferencias mutuas.

checkAbortes la clave para prevenir bucles infinitos📎 src/device/primitives.h:154-164: cadaNCCL_SPINS_BEFORE_CHECK_ABORT(10000) giros se lee una vezabortFlag, evitando leer frecuentemente memoria global que ralentice la ruta crítica. Una vez que se detecta abort, establecerncclShmem.abortedy almacenar en caché, todos los bucles de espera posteriores saldrán rápidamente.

Problemas en producción

Problema 1: falso listo causado por el desbordamiento del flag.SiNCCL_LL_CLEAN_MASKla lógica de cleanup se elimina, después de un tiempo de ejecución prolongado (step excede el ciclo del mask), el receptor podría leer un flag residual de la ronda anterior, juzgar erróneamente que los datos están listos, y leer datos sucios. Este tipo de bug es extremadamente difícil de reproducir, porque depende de que el step se desborde exactamente a un valor específico.

Problema 2:MaxRecv == 0trampa de compilación.En el códigoMaxRecv = Fan::MaxRecv > 1 ? Fan::MaxRecv : 1 📎 src/device/prims_ll.h:13, porque incluso si solo se envía sin recibir, se asigna un búfer de recepción de longitud MaxRecv, si MaxRecv es 0 causará un fallo de compilación de array de longitud cero. En WindowsMaxSendtambién tiene el mismo tratamiento📎 src/device/prims_ll.h:14-19。

LL128: intercambiar alineación de 128 bytes por mayor payload

Modelo intuitivo

El punto débil de LL es que el payload es solo del 50% (de 16 bytes, 8 bytes son flag). La idea de LL128 es:concentrar los flags en los últimos 8 bytes de cada 128 bytes, los primeros 120 bytes son todos datos. Así el payload aumenta del 50% al 93.75%. El costo es que se debe garantizar la alineación de 128 bytes, de lo contrario hay que hacer «reorganización de memoria compartida».

Estructura de datos y diseño de memoria

La unidad de transferencia de LL128 esuint64_t(8 bytes), pero organizada en «lines» de 128 bytes.NCCL_LL128_LINEELEMSes el número de elementos de 64 bits por line (16),NCCL_LL128_DATAELEMSes el número de elementos de datos entre ellos (15), el último elemento contiene el flag.

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

WireWordPerSlicees el número de palabras de 64 bits que un warp transfiere de una vez,DataEltPerSlicees el número de elementos de datos válidos entre ellos (menos un elemento flag por line).

El mecanismo de flag de LL128 es diferente al de LL:solo el 7º de cada 8 hilos (flagThread) se encarga de verificar el flag 📎 src/device/prims_ll128.h:373。flagThread = ((tid % 8) == 7). ¿Por qué? Porque el flag es uno por cada 128 bytes, y un warp tiene 32 hilos, cada 8 hilos procesan 128 bytes (8 hilos × 16 bytes = 128 bytes), así que de cada 8 hilos solo 1 necesita leer el flag.

Walkthrough guiado por escenario: un recvReduceSendCopy

Cadena de llamadas: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。

Primer paso: cargar datos locales a registros. loadRegsBeginSe dividen en dos casos📎 src/device/prims_ll128.h:99-142：

• Alineación de 16 bytes: directamenteload128a registro, sin transferencia por memoria compartida. NotaflagThreadsolo carga la mitad de los datos (g % 2 == 0), porque su otra mitad de registros se reserva para el flag📎 src/device/prims_ll128.h:109-114。
• No alineado: primero cargar el área alineada a memoria compartidancclScratchForWarp(warpInBlock)，__syncwarp()luego leer de vuelta a registros desde memoria compartida con el desplazamiento correcto📎 src/device/prims_ll128.h:115-141。

Segundo paso: esperar y leer datos del par. recvReduceSendCopyel bucle de espera en📎 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));

Punto clave: soloflagThreadverifica el flag, luego usa__any_syncpara hacer votación a nivel de warp—siempre que un flagThread encuentre que el flag no coincide, todo el warp continúa girando. Esto ahorra más instrucciones que si cada hilo verificara el flag.

Tercer paso: reorganización de registros. loadRegsFinishmover el registro flag de flagThread a un registro libre📎 src/device/prims_ll128.h:145-151. El comentario explica este diseño: «By deferring register shuffle here we've overlapped spinning on first peer's data with memory loads of src data» — se pospone la reorganización de registros hasta después de la espera, superponiendo el tiempo de espera con la carga de datos locales.

Cuarto paso: reduce y enviar.Tras recibir los datos, se haceapplyReduce 📎 src/device/prims_ll128.h:227-230, luegostore128se escribe en el búfer de envío📎 src/device/prims_ll128.h:274-287. Nótese que al enviarflagThread ? flag : v[u+1]—flagThread escribe el flag, los demás hilos escriben los datos.

Quinto paso: avanzar el step.A diferencia de LL, el avance del step en LL128 se hace de forma unificada al final deGenericOpmediante📎 src/device/prims_ll128.h:324-332, en lugar de dentro derecvReduceSendCopy. Además,postSendusa__threadfence_system()(SM90+) o__threadfence() 📎 src/device/prims_ll128.h:87-96, asegurando que los datos sean visibles para otras GPU/tarjetas de red antes de actualizar el puntero tail.

Control de concurrencia e interacción con el hardware

Elbarrier()de LL128 siempre usabarrier_sync(15 - group, nthreads) 📎 src/device/prims_ll128.h:64-66, a diferencia de LL que tiene optimización para un solo warp. Esto se debe a que el movimiento de datos en LL128 es a nivel de warp y requiere sincronización entre warps.

loadRegsBeginLa reorganización en memoria compartida dentro de__syncwarp()usa📎 src/device/prims_ll128.h:129para sincronizar

, asegurando que todos los hilos terminen de escribir en memoria compartida antes de leer.

Problemas en producciónProblema 1: el precipicio de rendimiento por accesos no alineados.

Si el búfer del usuario no está alineado a 16 bytes, cada transferencia debe pasar por memoria compartida como intermediaria, lo que puede degradar el rendimiento en más del 30%. En producción se debe asegurar que los búferes de entrada y salida se asignen alineados a 16 bytes.flagThreadProblema 2:presión de registros en

. flagThread solo carga la mitad de los datos, lo que significa que su utilización de registros difiere de la de los demás hilos. Si el compilador no asigna correctamente los registros, puede provocar desbordamiento de registros a memoria local y una caída drástica del rendimiento.

Simple: alto rendimiento para mensajes grandes con FIFO + notificaciones

Modelo intuitivo

El protocolo Simple es como un casillero de paquetería: el emisor coloca los datos en un búfer FIFO (el casillero), luego actualiza un puntero step de «se ha colocado en el casillero N.º N» (envía notificación); el receptor sondea el puntero step y, al ver un valor nuevo, va al casillero correspondiente a recoger el paquete. El coste del handshake es alto (hay que escribir el puntero + leer el puntero), pero se pueden mover muchos datos de una vez, lo que lo hace adecuado para mensajes grandes.

Estructuras de datos y diseño de memoria📎 src/device/prims_simple.h:28-46：

flagsPuntero al búfer directo en modo Direct📎 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;

CopiartidEste es un diseño típico que «usa operaciones de bits en lugar de múltiples campos bool», ahorrando registros. A cada hilo se le asigna un rol📎 src/device/prims_simple.h:651-666según sunrecv: los primerosnsendhilos son WaitRecv, los siguientesnrecvson WaitSend, los últimosnsendson PostRecv, y los penúltimos

son PostSend.

Walkthrough guiado por escenarios: un recvReduceSendrecvReduceSend(inpIx, eltN) → genericOp<0, 0, 1, 1, Input, -1> 📎 src/device/prims_simple.h:994-996。

Cadena de llamadas: sliceSize = max(divUp(nelem, 16 * SlicePerChunk) * 16, sliceSize / 32) 📎 src/device/prims_simple.h:185-186Primer paso: calcular el tamaño del slice.

. Esta fórmula garantiza que el slice esté al menos alineado a 16 bytes y no sea demasiado pequeño.Segundo paso: bucle de workers.tid < nworkersSolo los hilos con📎 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:626entran en el bucle principal

—se reserva un warp para superponer threadfence y copy. waitPeerTercer paso: esperar al extremo remoto.📎 src/device/prims_simple.h:103-164：

while (connStepCache + (isSendNotRecv ? NCCL_STEPS : 0) < step + StepPerSlice) {
  connStepCache = loadStepValue(connStepPtr);
  if (checkAbort(flags, Aborted, spins)) break;
}

isSendNotRecvCopiarNCCL_STEPSDistingue entre envío y recepción: al enviar se espera a que «el extremo remoto haya consumido» (head), al recibir se espera a que «el extremo remoto haya producido» (tail).StepPerSlicees el número de ranuras del búfer,

es el número de pasos por slice.ptrs[index] 📎 src/device/prims_simple.h:123-158Tras completar la espera, se configura

según el modo Direct. El modo Direct permite leer y escribir directamente el búfer del extremo remoto, evitando el FIFO y reduciendo una copia.Cuarto paso: reduceCopy.reduceCopySegún la combinación de Direct se elige una llamada diferente a📎 src/device/prims_simple.h:241-277. La rama más compleja es cuandosrcs[0] && dsts[0]existen ambos📎 src/device/prims_simple.h:258-271, se llama areduceCopy<Unroll, RedOp, T, MultimemSrcs, Recv+Src, Recv*MaxRecv+Src, MultimemDsts, Send+Dst, Send*MaxSend+Dst, PreOpSrcs>, cuyos parámetros significan: leer desdeRecv*MaxRecv+Srcfuentes, reducir y escribir enSend*MaxSend+Dstdestinos.

Quinto paso: postPeer. postPeerActualizar el puntero step📎 src/device/prims_simple.h:167-175：

if (Send && (flags & RolePostSend) && (dataStored || (flags & ConnFifoEnabled))) {
  fence_acq_rel_sys();
}
st_relaxed_sys_global(connStepPtr, step);

El lado emisor debefence_acq_rel_sys()antes de actualizar el step, asegurando que la escritura de datos sea visible para otras GPU/tarjetas de red. El lado receptor no necesita fence, porque el receptor solo notifica «ya he consumido», lo que no implica visibilidad de datos.

Control de concurrencia e interacción con el hardware

La sincronización de Simple usast_relaxed_sys_globalpara escribir el puntero step📎 src/device/prims_simple.h:167-175, yloadStepValuepara leer📎 src/device/prims_simple.h:86-100。loadStepValue. En SM90+ y conNvlsMinPollinghabilitado, se usa la instrucciónmultimem.ld_reduce.acquire.sys.global.min.u64, que es el sondeo acelerado por hardware de NVLink SHARP.📎 src/device/prims_simple.h:86-100La diferencia entre

barrier()ysubBarrier()📎 src/device/prims_simple.h:49-55：barrier()sincroniza todos losnthreadshilos,subBarrier()solo sincroniza losnworkershilos worker.subBarrierEl número de barrier de15 - group - (nworkers != nthreads ? 1 : 0)esbarrier(); cuando el número de workers no es igual al total de hilos, se usa un barrier distinto para evitar conflictos con

.

Problemas en producciónProblema 1: espera en el destructor bajo 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) { ... }
}

En NetRegMode, el búfer de envío es accedido directamente por la tarjeta de red, y debe esperar a que el hilo proxy confirme que se ha enviado (size se establece en -1) antes de retornar; de lo contrario, el siguiente kernel podría sobrescribir datos que la tarjeta de red está leyendo.

Trampa 2: Interbloqueo de sendrecv en DirectRead.En el destructor también hay un fragmento📎 src/device/prims_simple.h:814-824：

if ((flags & DirectRead) && (flags & RoleWaitSend) && P2p) {
  while (*tail > *head) { ... }
}

En el modo DirectRead de sendrecv, el emisor debe esperar a que el receptor termine de leer los datos para poder retornar. Si el receptor, por alguna razón, no avanza el tail, el emisor se bloqueará. Esta espera debe realizarse después debarrier(), de lo contrario podría competir con el hilo post.

Trampa 3:roundUpprovocado por el salto de step. loadRecvConnyloadSendConnambos contienenstep = roundUp(step, SlicePerChunk * StepPerSlice) 📎 src/device/prims_simple.h:486, 533. Esto alinea el step al límite del slice, pero si el step del paso anterior no está alineado, las ranuras omitidas no se inicializarán correctamente. El código enloadRecvConnañade una línea*connStepPtr = steppara devolver el credit📎 src/device/prims_simple.h:489。

Comparación y selección de las tres primitivas

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

Tanto LL como LL128 heredanPrimitivesWithoutDirect 📎 src/device/prims_ll.h:9-10, src/device/prims_ll128.h:13-14, porque el diseño de sus búferes no admite lectura/escritura directa de la memoria del par. Simple, en cambio, implementa completamente el modo Direct, con soporte para P2P directo y NVLS.

Reflexiones de diseño

¿Por qué Simple reserva un warp? 📎 src/device/prims_simple.h:625-626El comentario dice «For send operations, we need an extra warp to overlap the threadfence and the copy».fence_acq_rel_sys()Es una operación costosa; si todos los hilos esperan a que termine el fence para continuar, se desperdicia mucho tiempo. Se reserva un warp exclusivamente para hacer el fence, mientras los demás warps pueden seguir moviendo el siguiente lote de datos.

Resumen del capítulo

Este capítulo profundizó en la implementación de las tres primitivas de transporte:

1. LL: usancclLLFifoLinede 16 bytes para embeber el flag en la línea de datos; el receptor solo necesita sondear la coincidencia del flag para confirmar que los datos están listos. Carga útil del 50%, adecuado para mensajes pequeños. El núcleo esreadLLdeld.volatile.global.v4.u32ystoreLLdest.volatile.global.v4.u32。

2. LL128: concentra el flag en los últimos 8 bytes de cada 128 bytes, elevando la carga útil al 93.75%. UsaflagThread(1 por cada 8 hilos) para verificar el flag,__any_syncpara la votación warp. En caso de desalineación, recurre a reordenamiento en memoria compartida.

3. Simple: usa búfer FIFO + notificación por puntero step para lograr alto rendimiento en mensajes grandes.flagscodifica el rol con bits de bandera,waitPeersondea el step,postPeeractualiza el step y hace fence. Soporte completo del modo Direct.

Las tres primitivas comparten el mismo esqueleto de plantilla, especializado mediante el parámetro de plantillaProto. La capa de algoritmo solo llama a la interfaz unificada y no le importa el protocolo subyacente. Esta es la respuesta a «por qué la misma lógica de AllReduce necesita tres primitivas de transporte»: diferentes tamaños de mensaje requieren diferentes estrategias de sincronización y diseños de búfer; las tres primitivas están optimizadas para mensajes pequeños, medianos y grandes respectivamente.

Reflexiones y autoevaluación de este capítulo

Hasta aquí, hemos dominado los mecanismos de transferencia de datos de las tres primitivas LL, LL128 y Simple, que proporcionan a los algoritmos de capas superiores medios flexibles de ajuste de rendimiento. El siguiente capítulo profundizará en el núcleo de los algoritmos de comunicación colectiva, viendo cómo AllReduce, AllGather, ReduceScatter, etc. invocan estas primitivas, y cómo los algoritmos Ring, Tree, CollNet, etc. organizan el flujo de datos, completando finalmente la comunicación colectiva de extremo a extremo.

Capítulo 10: Núcleo de algoritmos de comunicación colectiva: implementación en dispositivo de AllReduce, AllGather, ReduceScatter

El capítulo anterior desglosó las tres primitivas de protocolo LL, LL128 y Simple; son el "motor" de la transferencia de datos, pero el motor por sí solo no sabe qué mover, hacia dónde ni en qué orden. Los archivos de núcleos de algoritmos bajo src/device que se examinan en este capítulo son la "caja de cambios": traducen semánticas de comunicación colectiva como AllReduce, AllGather y ReduceScatter en una serie de llamadas a primitivas como prims.directSend y prims.directRecvReduceDirectSend. En una frase, la contradicción central de este capítulo: ¿por qué el mismo AllReduce necesita cuatro implementaciones en el lado del dispositivo completamente distintas: Ring, Tree, CollNet y NVLS? La respuesta está en la correspondencia entre la "topología del flujo de datos" y las "capacidades del hardware". Ring usa el mínimo ancho de banda de red para hacer un pipeline de dos fases, Tree comprime la latencia a log(n) mediante reducción en árbol, y CollNet/NVLS descargan la reducción a la tarjeta de red o al conmutador NVLink. Este capítulo los desglosa uno por uno.

10.1 Ring AllReduce: cómo el pipeline de dos fases se implementa dentro del kernel

Modelo intuitivo: "carrera de relevos" en una línea de montaje circular

Imagina n trabajadores en círculo, cada uno con una caja de materia prima. El objetivo de AllReduce es que cada uno obtenga finalmente el "producto terminado de todas las materias primas mezcladas". El algoritmo Ring lo hace en dos fases: la primera fase (reduce-scatter) cada uno pasa su caja a lo largo del anillo, y en cada estación la mezcla con su propia materia prima; tras n-1 estaciones, cada uno tiene exactamente una porción de "mezcla completa" del producto terminado, pero solo una fracción de 1/n; la segunda fase (all-gather) esas porciones del producto terminado se pasan de nuevo alrededor del anillo, y cada uno completa todas las porciones.

Sin Ring, el método más simple sería que cada rank enviara los datos al root, el root redujera y luego difundiera; el ancho de banda de red del root se convertiría en el cuello de botella, y cuanto mayor sea n, más lento. La sutileza de Ring radica en:La cantidad enviada y recibida por cada rank es 2(n-1)/n veces el volumen de datos, distribuida uniformemente entre todos los enlaces independientemente de n。

Estructura de datos y diseño de memoria

El estado central del algoritmo Ring está enncclRingestructura (definida en device.h, no se detalla en este capítulo),runRingsolo se toman dos campos:

• ring->index: la posición lógica de este rank en el anillo, usada para calcular «qué chunk procesar en el paso j».
• ring->prev / ring->next: los números de rank predecesor y sucesor, como parámetros recv/send peer del constructor dePrimitives

Los parámetros clave de particionamiento son calculados porncclCollCbdPart(📎 src/device/all_reduce.h:21-22）：

ncclCollCbdPart(work, ncclShmem.channelId, Proto::Id, sizeof(T), (ssize_t*)nullptr, &gridOffset, &channelCount, &chunkCount);

Esta función divide los datos de todo el dominio de comunicación por channel y produce tres valores:gridOffset(el desplazamiento inicial de los datos que este channel maneja dentro del buffer completo),channelCount(el número total de elementos que este channel maneja),chunkCount(el número de elementos del chunk asignado a cada rank).chunkCountEs la granularidad del algoritmo Ring — cada paso mueve un chunk.

loopCount = nranks * chunkCount（📎 src/device/all_reduce.h:23) representa la cantidad de datos procesados en «una vuelta completa». El bucle externofor (elemOffset = 0; elemOffset < channelCount; elemOffset += loopCount)（📎 src/device/all_reduce.h:34) significa: si el volumen de datos del channel excede lo que una vuelta puede procesar, se ejecutan múltiples vueltas.

Step-by-Step Walkthrough: flujo completo de llamadas de un Ring AllReduce

Escenario: 4 ranks (nranks=4), elringIx=0，chunkCount=100，channelCount=400de este rank (exactamente una vuelta).

Paso 0: enviar «el chunk propio» al siguiente 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);

modRankses una lambda que hace resta módulo nranks (📎 src/device/all_reduce.h:40）。ringIx + nranks - 1representa «el número de chunk anterior de este rank». ¿Por qué en el paso 0 se envía el chunk 3? Porque en la fase reduce-scatter del Ring, cada rank primero envía la porción de datos que «no debería retener» (es decir, el chunk del rank predecesor).directSendsolo envía sin recibir, porque en ese momento aún no ha recibido ningún dato.

Pasos 1 a nranks-2: recibir, reducir y reenviar（📎 src/device/all_reduce.h:50-56）

for (int j = 2; j < nranks; ++j) {
  chunk = modRanks(ringIx + nranks - j);
  ...
  prims.directRecvReduceDirectSend(offset, offset, nelem);
}

directRecvReduceDirectSendes la primitiva central del Ring: recibir un chunk deprev, reducir con los datos locales (por ejemplo, suma), y enviar el resultado anext. Nótese queoffsetynelemse recalculan en cada iteración — porque cada paso procesa un chunk diferente. j va de 2 a nranks-1, en total nranks-2 pasos.

Paso nranks-1: recibir el último chunk y reducir, produciendo el resultado final（📎 src/device/all_reduce.h:58-64）

chunk = ringIx + 0;
...
prims.directRecvReduceCopyDirectSend(offset, offset, nelem, /*postOp=*/true);

ElpostOp=truede este paso es clave: tras completar la reducción se ejecuta la operación posterior (por ejemplo, la división al promediar).directRecvReduceCopyDirectSendtiene unCopymás que el paso anterior — escribe el resultado de la reducción simultáneamente en el recvbuff local y lo envía a next. Con esto termina la fase reduce-scatter, y cada rank tiene un chunk «completamente reducido».

Fase all-gather: nranks-2 pasos de puro reenvío（📎 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);
}

Nótese que aquí se usadirectRecvCopyDirectSend, sinReduce— porque los datos ya están reducidos, solo hay que copiar y reenviar.

Último paso: recibir el último chunk（📎 src/device/all_reduce.h:75-81）

chunk = modRanks(ringIx + 1);
...
prims.directRecv(offset, nelem);

Solo recibe sin enviar, completando el último bloque.

Todo el flujo puede resumirse con el siguiente diagrama de flujo de control:

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

Reflexión de diseño: por qué el orden de chunks del Ring «va hacia atrás»

Nótese el patrón de numeración de chunks: el paso 0 envíaringIx-1, el paso j procesaringIx-j, el último paso procesaringIx+0. Esto avanza en sentidoantihorario. ¿Por qué? Porque cada rank del Ring solo retiene «el chunk que le corresponde reducir» (es decir,ringIx+0), los demás chunks solo pasan de largo. El avance antihorario garantiza: cuando un chunk completa una vuelta y regresa al punto de partida,恰好 ha completado nranks reducciones, produciendo el resultado final. Si avanzara en sentido horario, el chunk completaría la reducción en el rank equivocado.

Errores en producción:remCount < loopCounttrampa de alineación cuando

📎 src/device/all_reduce.h:38Hay una línea de código fácil de pasar por alto:

if (remCount < loopCount) chunkCount = alignUp(divUp(remCount, nranks), 16 / sizeof(T));

Cuando los datos restantes no completan una vuelta, chunkCount debe recalcularse, yalignUp(..., 16/sizeof(T))fuerza alineación a 16 bytes. ¿Por qué? Porque el protocolo LL128 requiere alineación a 128 bytes, y el protocolo Simple también tiene requisitos de alineación para acceso vectorizado. Si se elimina esta alineación, los chunks no alineados toman la ruta lenta, con una caída de rendimiento del 20-40%. En producción, si se observa inestabilidad de rendimiento en Ring AllReduce al final de mensajes pequeños, a menudo es porque esta alineación no está activa — verificar sichannelCountes múltiplo entero denranks * 16/sizeof(T).

10.2 Tree AllReduce: reducir la latencia a log(n) mediante reducción en árbol

Modelo intuitivo: «reporte escalonado» en una empresa

La latencia del Ring es O(n) — los datos deben dar una vuelta completa. Cuando n es muy grande (por ejemplo, 1024 GPUs), incluso con el ancho de banda distribuido uniformemente, la latencia es insoportable. El algoritmo Tree cambia el enfoque: como la estructura organizativa de una empresa, cada rank solo se comunica con su «nodo padre» y «nodos hijo». En la fase de reducción, los nodos hoja reportan datos hacia arriba y los nodos padre combinan los datos de los hijos; en la fase de broadcast, se invierte: el nodo raíz envía el resultado hacia abajo. La latencia baja de O(n) a O(log n).

Sin Tree, la latencia de AllReduce en clústeres a gran escala crecería linealmente con el número de ranks, y el tiempo de iteración de entrenamiento se vería afectado por la comunicación.

Estructura de datos y diseño de memoria

El estado de Tree está enncclTree:

• tree->up: rank del nodo padre (-1 indica que este rank es la raíz).
• tree->down[]: arreglo de nodos hijos, máximoNCCL_MAX_TREE_ARITY(típicamente 3, es decir, binario + local).

runTreeUpDownyrunTreeSplitson dos variantes. La primera usa el patrón de dos fases «primero reducir todo y luego difundir todo», la segunda divide los hilos en dos mitades, una mitad hace la reducción y la otra hace la difusión, logrando superposición de pipeline.

Step-by-Step Walkthrough: las tres ramas de runTreeUpDown

runTreeUpDownEl primer bloque de código de es la fase de reducción (📎 src/device/all_reduce.h:96-118), y según la posición de este rank en el árbol se divide en tres casos:

Caso A: este rank es la raíz (tree->up == -1）（📎 src/device/all_reduce.h:99-104）

prims.directRecvReduceCopy(offset, offset, nelem, /*postOp=*/true);

El nodo raíz solo recibe y no envía, recibe datos de todos los nodos hijos, reduce y escribe en recvbuff.postOp=trueEjecuta la operación posterior.

Caso B: este rank es hoja (tree->down[0] == -1）（📎 src/device/all_reduce.h:105-110）

prims.directSend(offset, offset, nelem);

El nodo hoja solo envía y no recibe, envía sus propios datos al nodo padre.

Caso C: nodo intermedio（📎 src/device/all_reduce.h:111-117）

prims.directRecvReduceDirectSend(offset, offset, nelem);

Recibe de los nodos hijos, reduce y envía al nodo padre.

Fase de difusión (📎 src/device/all_reduce.h:120-142) la lógica es simétrica: nodo raízdirectSendFromOutput(envía desde recvbuff), nodo hojadirectRecv, nodo intermediodirectRecvCopyDirectSend。

runTreeSplit: implementar pipeline reducción-difusión mediante división de hilos

runTreeUpDownEl problema de es: la fase de reducción y la fase de difusión son seriales, con un punto de sincronización global en medio.runTreeSplitdivide los hilos en dos grupos (📎 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;
}

El protocolo Simple se divide por la mitad; los protocolos LL/LL128 se dividen 7:3, porque «recibir datos de 3 fuentes para reducir» es más intensivo en cómputo que «enviar a 3 destinos», así que el grupo de reducción recibe más hilos.

Luegotid < nthreadsSplitlos hilos de hacen la reducción hacia arriba (📎 src/device/all_reduce.h:175-202), y el resto de hilos hacen la difusión hacia abajo (📎 src/device/all_reduce.h:203-224). Los dos grupos se distinguen por el desplazamientoProto::MaxGroupWidthpara identificar sus respectivos grupos de comunicación (📎 src/device/all_reduce.h:189de0 * Proto::MaxGroupWidthy📎 src/device/all_reduce.h:210de1 * Proto::MaxGroupWidth）。

Consideraciones de diseño: por qué el nodo raíz de Tree requiere tratamiento especial

El nodo raíz de la reducción en árbol es el «punto de convergencia», su volumen de recepción es múltiplo del número de nodos hijos, y su volumen de envío es cero (fase de reducción). Si el nodo raíz también usara eldirectRecvReduceDirectSendgenérico, intentaría enviar atree->up(-1), provocando desbordamiento. Por eso debe tratarse por separado con la ramaif (tree->up == -1). De igual forma, el juiciotree->down[0] == -1del nodo hoja.

Problemas en producción: el problema del «nodo raíz caliente» en el algoritmo Tree

El nodo raíz de Tree soporta todo el tráfico de reducción; si la GPU donde está el nodo raíz resulta ser un nodo lento (por ejemplo, con ancho de banda PCIe limitado), todo el AllReduce se verá afectado. La respuesta de NCCL es:elegir una raíz diferente para cada channel, distribuyendo la carga del nodo raíz entre múltiples ranks. Por eso enrunTreeSplitla rama del nodo raíz usaFanSymmetric<NCCL_MAX_TREE_ARITY_TOP>（📎 src/device/all_reduce.h:168) — tiene que manejar simultáneamente la reducción de múltiples nodos hijos. En producción, si se detecta un rendimiento desigual en Tree AllReduce, verificar si la distribución de nodos raíz de los channels es uniforme.

10.3 AllGather y ReduceScatter: las variantes de «medio recorrido» de Ring

Modelo intuitivo: AllReduce dividido en dos mitades

AllGather y ReduceScatter son esencialmente las dos fases de AllReduce convertidas cada una en API independiente. AllGather solo hace «recolección» — cada rank aporta una porción de datos, y al final todos obtienen todos los datos. ReduceScatter solo hace «reducción + dispersión» — todos aportan datos, y tras la reducción cada uno obtiene una porción.

Sin estas dos APIs independientes, cuando el usuario hace «primero reducir y luego recolectar» o «primero recolectar y luego reducir» solo puede llamar a AllReduce y luego cortar manualmente, desperdiciando la mitad del ancho de banda.

Implementación Ring de AllGather

all_gather.hElrunRing（📎 src/device/all_gather.h:14-88de ) es más simple que AllReduce: no hay reducción, solo copia y reenvío.

Paso 0: enviar los propios datos a la siguiente 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);
}

Aquí hay un juicio in-place: siinputBuf + dataOffset == outputBuf + offset, significa que la entrada y la salida son el mismo bloque de memoria (AllGather in-place), directamentedirectSend; de lo contrario hay quedirectCopySend(primero copiar a la salida y luego enviar).

Pasos intermedios nranks-2: reenvío puro（📎 src/device/all_gather.h:62-67）

prims.directRecvCopyDirectSend(offset, offset, nelem);

Último paso: recibir el último bloque（📎 src/device/all_gather.h:69-74）

prims.directRecv(offset, nelem);

isNetOffload: un solo warp impulsa la red + múltiples warps copian en paralelo

📎 src/device/all_gather.h:28-36tiene una rama especial:

if (isNetOffload) {
  workNthreads = WARP_SIZE;
  chunkCount = NCCL_MAX_NET_SIZE;
} else {
  workNthreads = nthreads;
}

CuandoisNetOffload=true(modo single RPN + registro de red), solo se usa 1 warp para impulsar la comunicación Ring, y el resto de warps hacen en paralelo «copiar datos de origen al buffer destino» (📎 src/device/all_gather.h:76-82). Esto es para superponer el costo de copia con el costo de comunicación en AllGather no in-place.

Al final hay unbarrier_sync(14, nthreads)（📎 src/device/all_gather.h:87), y el comentario lo explica claramente: hay que esperar a que todos los warps terminen, de lo contrario el siguiente work podría reutilizar outputBuf y causar una condición de carrera. Se usa barrier 14 para evitar el barrier propio de prims y__syncthreads()。

Implementación Ring de ReduceScatter

reduce_scatter.hElrunRing（📎 src/device/reduce_scatter.h:14-56de ) es la fase reduce-scatter de AllReduce extraída por separado:

Paso 0: enviar los propios datos a la siguiente GPU（📎 src/device/reduce_scatter.h:39-42）

rankDest = ringRanks[nranks - 1];
offset = dataOffset + rankDest * count;
prims.send(offset, nelem);

Pasos intermedios nranks-2: recibir, reducir y reenviar（📎 src/device/reduce_scatter.h:44-49）

prims.recvReduceSend(offset, nelem);

Último paso: recibir y reducir, produciendo el resultado final（📎 src/device/reduce_scatter.h:61-64）

prims.recvReduceCopy(offset, dataOffset, nelem, /*postOp=*/true);

Atención al último paso delrecvReduceCopytiene dos offset:offset(fuente de recepción) ydataOffset(entrada local), el resultado de la reducción se escribe endataOffset。

Diagrama comparativo del flujo de datos

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

Problemas en producción: los límites de la comprobación in-place

📎 src/device/all_gather.h:55la comprobación in-place deinputBuf + dataOffset == outputBuf + offsetdepende de que los punteros sean exactamente iguales. Si el sendbuff y el recvbuff que pasa el usuario tienen un desplazamiento pero lógicamente son la misma memoria, esta comprobación falla y se toma la rutadirectCopySend—aunque es correcta, implica una copia adicional. En producción se recomienda que, al hacer AllGather in-place, sendbuff y recvbuff sean completamente idénticos.

10.4 CollNet y NVLS: descargar la reducción al hardware

Modelo intuitivo: dejar que el «switch» ayude a calcular

Tanto Ring como Tree hacen que «la propia GPU calcule la reducción». CollNet y NVLS cambian el enfoque: descargan la operación de reducción a la tarjeta de red (CollNet) o al switch NVLink (NVLS). La GPU solo se encarga de enviar los datos, y el hardware completa la reducción y luego los retransmite. Es como pasar de «cada trabajador mezcla sus propios ingredientes» a «enviar los ingredientes a una batidora central, que los mezcla y luego los distribuye».

Sin descarga por hardware, la operación de reducción ocuparía recursos SM de la GPU y la latencia de reducción no podría ocultarse.

Reparto de hilos en CollNet Direct

RunWorkColl<ncclFuncAllReduce, ..., NCCL_ALGO_COLLNET_DIRECT, ...>elrun（📎 src/device/all_reduce.h:249-386) divide los hilos en cuatro grupos:

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;

Los cuatro grupos de hilos se encargan respectivamente de: Scatter (dispersar los datos a cada rail), Reduce (reducir y enviar a la red), Gather (recoger de cada rail), Bcast (retransmitir tras recibir de la red).COLLNET_COPY_THREADS = 96（📎 src/device/all_reduce.h:250) es el número fijo de hilos de copia.

netRegUsed: diseño del búfer en modo de registro de red

📎 src/device/all_reduce.h:280-288tiene una bifurcación clave:

if (work->netRegUsed) {
  offsetBase = bid * chunkSize;
  maxNelems = size;
  peerOffset = nChannels * chunkSize;
} else {
  offsetBase = bid * direct->nHeads * chunkSize;
  maxNelems = direct->nHeads * chunkSize;
  peerOffset = chunkSize;
}

netRegUsedEn el modo , los búferes se organizan de forma contigua por channel (bid * chunkSize), y el offset de peer esnChannels * chunkSize; en modo no registrado, se organizan por head (bid * nHeads * chunkSize), y el offset de peer eschunkSize. Esta diferencia proviene de que el modo de registro de red exige que los búferes sean contiguos para permitir el DMA de la tarjeta de red.

Asignación de warps en NVLS

RunWorkColl<ncclFuncAllReduce, ..., NCCL_ALGO_NVLS, ...>elrun（📎 src/device/all_reduce.h:391-523) usa una asignación de warps más fina:

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;

regUsedEn el modo , scatter/gather ocupan solo 1 warp cada uno (porque el hardware NVLS opera directamente sobre memoria registrada) y reduce ocupa la mayor parte; en modo no registrado, scatter/gather ocupan aproximadamente la mitad cada uno y reduce se ajusta según el número de ranks (≤6 usa 7 warps; en caso contrario, 5 warps).

Diagrama de interacción temporal

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

Problemas en producción: la trampa dedirect->out == -1en CollNet

📎 src/device/reduce_scatter.h:521tiene una línea:

if (direct->out == -1) __trap();

Si la conexión out de CollNet no se ha establecido (-1), hacer directamente__trap()provoca que el kernel falle. Esto es programación defensiva: CollNet depende de la tarjeta de red; si la inicialización de la tarjeta falla, out será -1, y continuar la ejecución provocaría comportamiento indefinido. En producción, si se ve un kernel trap, hay que comprobar si la tarjeta de red de CollNet se inicializó correctamente.

10.5 Broadcast y Reduce: las dos operaciones colectivas más simples

Broadcast: difusión en abanico desde el root

broadcast.helrunRing（📎 src/device/broadcast.h:14-64) es muy directo: el nodo root envía los datos, los demás nodos los reenvían y el último nodo solo recibe.

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

Tres ramas: el root envía, el predecesor del root recibe, los nodos intermedios reenvían. Atención:nextRank == rootcomprueba que «el siguiente de este nodo es el root», es decir, que este nodo es el último del anillo: solo recibe, no envía.

Reduce: convergencia hacia el root

reduce.helrunRing（📎 src/device/reduce.h:14-53) es la operación inversa de 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 == rootEl nodo solo envía (es el predecesor del root), el root solo recibe y reduce, y los nodos intermedios reciben, reducen y reenvían a la vez.

Reflexión de diseño: por qué Broadcast/Reduce también usan Ring

En teoría, Broadcast y Reduce podrían usar Tree para lograr menor latencia, pero NCCL elige Ring porque:el volumen de datos de estas dos operaciones suele ser pequeño, la implementación de Ring es más simple y puede reutilizar la ruta de código Ring de AllReduce. La complejidad de Tree (selección del nodo raíz, división de hilos) no aporta beneficios evidentes en escenarios de mensajes pequeños.

Problemas en producción: el cuello de botella de ancho de banda del nodo root en Broadcast

El nodo root de Broadcast debe enviar todos los datos; si el root es un nodo lento, todo el Broadcast se ralentiza. La respuesta de NCCL es:Broadcast también admite múltiples channels, y el root de cada channel puede ser distinto. Pero atención:work->rootes global, y todos los channels comparten el mismo root—esto lo determina la semántica de Broadcast (solo hay una fuente). En producción, si Broadcast va lento, hay que revisar el ancho de banda de red del nodo root.

10.6 Matriz de selección de algoritmos: especialización de plantillas de RunWorkColl

Todos los kernels de algoritmos se registran mediante especialización de plantillasRunWorkColl(📎 src/device/all_reduce.h:228-788). Cada especialización corresponde a una combinación de «función × algoritmo × protocolo»:

Nota:CollNet y NVLS solo admiten el protocolo SIMPLE. Esto se debe a que ambos algoritmos dependen de la descarga a hardware, y el mecanismo de sincronización de baja latencia de LL/LL128 es incompatible con la descarga a hardware: la latencia de la reducción por hardware es mucho mayor que el sondeo de flags de LL, por lo que usar LL en su lugar aumenta la sobrecarga.

Lógica interna de la selección de protocolo

• LL: mensajes pequeños (< 8KB), prioridad a baja latencia. Tanto Ring como Tree lo admiten.
• LL128: mensajes medianos (8KB - 1MB), alineación de 128 bytes. Tanto Ring como Tree lo admiten.
• SIMPLE: mensajes grandes (> 1MB), prioridad al ancho de banda. Todos los algoritmos lo admiten.

Errores en producción: limitaciones de la combinación de protocolo y algoritmo

Si el usuario fuerza la especificación deNCCL_PROTO=LLpero el algoritmo es CollNet, NCCL recurrirá a SIMPLE durante la fase de tuning. En producción, si se descubre que la configuración del protocolo no surte efecto, verificar si el algoritmo admite dicho protocolo.

Reflexión de diseño: por qué la misma lógica de AllReduce necesita tantas implementaciones

Repasando este capítulo, AllReduce tiene seis implementaciones de algoritmos: Ring, Tree, CollNet Direct, CollNet Chain, NVLS y NVLS Tree. Esto no es redundancia, sinola solución óptima para diferentes topologías de hardware y tamaños de mensaje：

• Ring: versátil, adecuado para mensajes grandes, máxima utilización del ancho de banda.
• Tree: adecuado para clústeres a gran escala, latencia O(log n).
• CollNet: adecuado para clústeres con NICs que admiten reducción, descarga el cómputo de la GPU.
• NVLS: adecuado para NVLink de nodo único con conexión completa, reducción por multidifusión de hardware.

El módulo de tuning de NCCL (capítulo 5) selecciona automáticamente según el tamaño del mensaje, el número de ranks y la topología. La implementación del lado del dispositivo solo necesita garantizar que «cada combinación sea correcta»; la lógica de selección está en el lado del host.

Resumen de este capítulo

Este capítulo desglosósrc/devicelos seis archivos de kernel de algoritmos bajo

1. Ring AllReduce（📎 src/device/all_reduce.h:14-83): pipeline de dos fases, reduce-scatter + all-gather, cada fase con n-1 pasos.

2. Tree AllReduce（📎 src/device/all_reduce.h:86-225): reducción en árbol, latencia O(log n),runTreeSplitutiliza división de hilos para implementar el pipeline reducción-broadcast.

3. AllGather（📎 src/device/all_gather.h:14-88): Ring de una sola fase, admite in-place y netOffload.

4. ReduceScatter（📎 src/device/reduce_scatter.h:14-56): Ring de una sola fase, es la fase reduce-scatter de AllReduce.

5. Broadcast/Reduce（📎 src/device/broadcast.h:14-64、📎 src/device/reduce.h:14-53): la variante más simple de Ring.

6. CollNet/NVLS（📎 src/device/all_reduce.h:247-635): descarga a hardware, solo admite el protocolo SIMPLE.

Reflexiones y autoevaluación de este capítulo

Hasta aquí, hemos visto cómo el kernel del algoritmo del lado del dispositivo organiza el flujo de datos. Cada algoritmo llama a las primitivas del capítulo anterior a través dePrimitives, y la capa de algoritmo solo se preocupa por «quién envía a quién, qué chunk envía, si reduce o copia». El siguiente capítulo profundizará en la abstracción de la capa de transporte, viendo cómo P2P, SHM, NET y NVLS se unifican en un conjunto de interfaces, y cómo los hilos proxy del lado host colaboran con el kernel del lado del dispositivo para completar la comunicación entre máquinas.

Regla fundamental: todos los algoritmos llaman a las primitivas a través de la clase plantilla Primitives; el algoritmo solo se encarga de la «topología del flujo de datos» y las primitivas se encargan del «movimiento de datos». Esta estratificación permite que agregar un nuevo algoritmo solo requiera implementar la lógica de topología, sin preocuparse por la sincronización subyacente. Pero sin importar cómo cambie la topología, los datos finalmente deben transmitirse por un enlace físico. El siguiente capítulo profundizará en el directorio src/transport, viendo cómo NCCL utiliza una interfaz transport unificada para ocultar las diferencias entre P2P, SHM, NET y NVLS, y la semántica setup/connect/send/recv de cada transport. Esta es la base para entender la comunicación entre máquinas.

Capítulo 11: Abstracción de la capa de transporte: cómo P2P, SHM, NET y NVLS se unifican bajo un mismo conjunto de interfaces

En el capítulo anterior profundizamos en el kernel del algoritmo y vimos cómo Ring AllReduce divide los datos y realiza una reducción en dos fases, y cómo Tree AllReduce reduce la latencia gracias a una estructura de árbol; pero estos algoritmos solo definen la vista lógica de «quién envía a quién, qué chunk envía». Los datos finalmente deben atravesar enlaces físicos reales: NVLink, PCIe, memoria compartida o tarjeta de red. Este capítulo desglosa el directorio src/transport para ver cómo NCCL utiliza un conjunto unificado de interfaces ncclTransport para enmascarar los cuatro canales físicos P2P, SHM, NET y NVLS bajo una misma cara, completando el último kilómetro desde la topología del algoritmo hasta la transmisión física.

I. Interfaz unificada: cómo ncclTransport enmascara los cuatro canales físicos

Modelo intuitivo

Imagina una empresa de logística: sin importar si el cliente envía un mensajería urbana (P2P), una entrega dentro del edificio (SHM), un transporte interprovincial (NET) o una línea dedicada directa (NVLS), en recepción solo se rellena una «orden de envío». Esta orden de envío es la estructurancclTransport: especifica que cada modo de transporte debe proporcionar acciones fijas comocanConnect、setup、connect、free, etc. Sin esta capa de abstracción, los algoritmos de nivel superior tendrían que escribir cuatro conjuntos deif-elsepara determinar qué enlace tomar, y agregar un nuevo hardware obligaría a modificar todos los algoritmos.

Estructuras de datos y diseño de memoria

NCCL utiliza un arreglo global para registrar todos los transport, y el orden es la prioridad:

📎 src/transport.cc:15-20

struct ncclTransport* ncclTransports[NTRANSPORTS] = {
  &p2pTransport,
  &shmTransport,
  &netTransport,
  &collNetTransport,
};

El orden del arreglo determina el orden de selección: P2P primero, luego SHM, después NET y finalmente CollNet. Cada transport se describe mediante la estructurancclTransport, que contiene un puntero a funcióncanConnecty dosncclTransportComm(uno para send y otro para recv). Tomando P2P como ejemplo:

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

ncclTransportCommEl orden de los campos desetupes una «ranura de ciclo de vida» fija:connect(preparar recursos),free(intercambiar información de conexión),proxySharedInit(liberar),proxySetup、proxyConnect、proxyFree、proxyProgress、proxyRegister、proxyDeregister(inicialización compartida del proxy),proxyProgress. Nótese que la ranuraNULLde P2P esproxyProgress—porque P2P consiste en que la GPU lee y escribe directamente la memoria del par, sin necesidad de un hilo proxy del host para mover datos; mientras que lasendProxyProgress/recvProxyProgressde NET es

, porque la E/S de la tarjeta de red debe ser impulsada por un hilo del host.

Walkthrough guiado por escenarios: cómo una conexión selecciona un transportselectTransport：

📎 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==1indica la dirección send,type==0indica la dirección recv. El bucle pregunta sucesivamente a cada transport sucanConnect: devuelveret=1significa «puedo hacer este trabajo», inmediatamente apuntaconnector->transportComma la dirección correspondiente de ese transport y llama a susetup. Si todos los transport devuelven 0, imprime una advertencia y devuelvencclSystemError。

canConnectLa lógica de decisión refleja las «fronteras de territorio» de cada transport. Tomando P2P como ejemplo:

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

Cadena de decisión de P2P: primero pregunta a la topología «¿hay una ruta P2P entre los dos ranks?»; si hay saltos intermedios (intermediateRank != -1) y CE memcpy está habilitado, abandona P2P y lo cede a SHM/NET; si la topología sugiere ir por red (useNet), también abandona; finalmente verifica si están en el mismo host. La decisión de SHM es más simple:

📎 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 requiere mismo host (hostHashiguales) y compartir el mismo bloque/dev/shm（shmDeviguales, usado para comunicación entre contenedores). NET casi siempre devuelve 1, solo verifica si intra-node net está deshabilitado cuando están en el mismo host:

📎 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 es el «último recurso» — siempre que nadie más lo tome, él lo toma. ElcanConnectde NVLS devuelve directamente 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 no sigue la ruta de conexión peer-to-peer convencional, establece un grupo multicast por separado a través dencclNvlsSetup, por lo quecanConnectsiempre devuelve 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

Reflexión de diseño

Dos, P2P: las cuatro formas de conexión directa entre GPUs del mismo equipo

Modelo intuitivo

P2P es «pasar cosas directamente entre vecinos» — GPU 0 lee y escribe directamente la memoria de GPU 1, sin pasar por la CPU o la tarjeta de red. Sin P2P, la comunicación multi-GPU en el mismo equipo tendría que desviarse por la memoria del host, duplicando la latencia y reduciendo el ancho de banda a la mitad.

Estructuras de datos y diseño de memoria

P2P tiene internamente cuatro formas, diferenciadas porenum p2pType:

📎 src/transport/p2p.cc:19-24

enum p2pType {
  P2P_DIRECT,
  P2P_INTERMEDIATE,
  P2P_IPC,
  P2P_CUMEM
};

• P2P_DIRECT: diferentes GPUs dentro del mismo proceso, acceso directo mediante punteros (el más rápido).
• P2P_INTERMEDIATE: no hay conexión directa entre las dos GPUs, se requiere reenvío a través de una GPU intermedia.
• P2P_IPC: entre procesos, se usa el tradicionalcudaIpcOpenMemHandlepara importar la memoria del par.
• P2P_CUMEM: entre procesos, se importa usando la API cuMem (cuMemExportToShareableHandle), soporta gestión de memoria de granularidad más fina.

Estructura de recursos central:

📎 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/recvDevMemes una union — el emisor solo se preocupa porsendDevMem, el receptor solo se preocupa porrecvDevMem, comparten un mismo bloque de memoria.sendMemIpc/recvMemIpcguarda el handle de memoria importada del par,sendMemSameProc/recvMemSameProcmarca si es el mismo proceso (determina si al liberar se usancclCuMemFreeAddrocudaIpcCloseMemHandle）。

Estructura de información de conexiónp2pConnectInfose intercambia a través de 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_assertgarantiza que la información de conexión no excedaCONNECT_SIZE(tamaño de búfer fijo para un único intercambio de bootstrap).readEl campo determina la dirección del flujo de datos:read=1indica que el receptor lee activamente la memoria del emisor (P2P Read),read=0indica que el emisor escribe activamente en la memoria del receptor (P2P Write).

Walkthrough guiado por escenarios: establecimiento de P2P Send

CuandoselectTransportselecciona P2P, llama ap2pSendSetup：

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

Puntos clave:sendSizeEn modo P2P Read se debe añadir adicionalmente el tamaño del búfer del protocolo SIMPLE — porque en modo lectura el búfer SIMPLE del emisor es leído directamente por el receptor, debe asignarse junto conncclSendMemen el mismo bloque de memoria compartible.ALIGN_SIZE(sendSize, CUDA_IPC_MIN)garantiza que el tamaño se alinee a la granularidad mínima de CUDA IPC.

Luego, segúnintermediateRanky la relación de procesos, se elige la forma:

📎 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_PIDMacro que determina mismo host y mismo proceso:

📎 src/transport/p2p.cc:334-335

#define P2P_SAME_PID(MYINFO, PEERINFO) \
  ((MYINFO->hostHash == PEERINFO->hostHash) && (MYINFO->pidHash == PEERINFO->pidHash))

Mismo proceso y direct no deshabilitado y memcpy no habilitado, es el más rápidoP2P_DIRECT— toma directamente el puntero del par. De lo contrario, va por IPC/CUMEM.

Posteriormente, a través del hilo proxy se asigna el búfer compartible:

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

ncclProxyCallBlockinges una RPC síncrona: el hilo host envía un mensaje al hilo proxy, el hilo proxy llama ap2pSendProxySetuppara asignar el búfer compartible, y devuelvencclP2pBuff(incluyendo el handle IPC). Luegop2pMapmapea el búfer del par al espacio de direcciones local.

p2pMapes la función central de mapeo:

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

Mismo proceso, diferentes GPUs: primerocudaDeviceEnablePeerAccessabre el canal P2P, luego usa directamentedirectPtr(porque el espacio de direcciones se comparte en el mismo proceso). Entre procesos: llama ancclP2pImportShareableBufferpara importar el handle de memoria del par.

Control de concurrencia e interacción con hardware

La sincronización de P2P se basa enncclSendMem/ncclRecvMemdentro dehead/tailel punterohead. El emisor escribetailpara decirle al receptor «hasta dónde he escrito», el receptor escribe

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

headCopiarsendDevMem，tailapunta al localremDevMemapunta al par

. El kernel de GPU logra la sincronización entre GPUs leyendo y escribiendo estos dos punteros, sin intervención de la CPU.

Guía de evitación de errores en producciónError 1: P2P Read y memcpy son mutuamente excluyentes.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];
    }
  }

Copiarread=1SisendDevMem==NULLperoncclInternalError, devuelve directamenteNCCL_P2P_READ_ENABLE=1. Si en producción ves este error, verifica si se configuraron simultáneamenteNCCL_P2P_USE_CUDA_MEMCPY=1y

— estos dos tienen semántica conflictiva. p2pSendFreeError 2: orden de liberación entre procesos.sendMemSameProcSegún

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

CopiarncclCuMemFreeAddrMismo proceso usancclCudaFree(liberar memoria física). Hacerlo al revés provoca fugas de memoria o use-after-free.

Tres, SHM: la disputa sobre «quién pone la memoria» en la memoria compartida

Modelo intuitivo

SHM es «dos procesos compartiendo una pizarra»: el emisor escribe, el receptor lee. Pero, ¿en casa de quién se pone la pizarra? ¿En la casa del emisor (sender-side), y el receptor va a leerla; o en la casa del receptor (receiver-side), y el emisor va a escribir en ella? Esto es lo que resuelve el parámetroNCCL_SHM_LOCALITY.

Estructuras de datos y diseño de memoria

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

AtenciónhostMemydevHostMemaparecen en pares:hostMemes un puntero del lado host,devHostMemes un puntero del lado dispositivo (mediante UVA o mapeo cuMem).remHostMem/devRemHostMemes el mapeo local de la memoria compartida del par.

Walkthrough guiado por escenarios: elección de locality en SHM

shmSendSetupSegún la locality se decide cuánta memoria asignar:

📎 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, el emisor asigna el búfer de datos (shmSizemás todos los búferes de protocolo); de lo contrario, solo asigna la estructura de controlncclSendMem.req.legacyMarca si es el mismo proceso: dentro del mismo proceso se puede usar el tradicionalmmap, entre procesos se necesita cuMem o el archivo/dev/shm.

shmSendConnectSegún la locality se decide sibuffsapunta a local o al par:

📎 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：buffsapunta al localdevHostMem(el emisor escribe su propia memoria);SHM_RECV_SIDE：buffsapunta al pardevRemHostMem(el emisor escribe la memoria del receptor).headsiempre apunta a local,tailsiempre apunta al par, porque el emisor actualizaheady el receptor actualizatail。

Reflexiones de diseño

Guía de evitación de errores en producción

Problema: entre contenedores/dev/shmno se comparte. shmCanConnectComprobarinfo1->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;

Si dos contenedores montan/dev/shm，shmDevdiferentes, SHM degrada automáticamente a NET. Si en producción se detecta que una comunicación entre el mismo host está usando la red, comprobar si los montajes de/dev/shmde los contenedores son consistentes.

Cuatro, NET: tabla de mapeo y progreso del proxy en la transmisión por red

Modelo intuitivo

NET es «mensajería interurbana»: los datos se empaquetan y se entregan a la tarjeta de red, que los envía por fibra óptica al par. Pero la tarjeta de red no reconoce direcciones de memoria de GPU, por lo que necesita una «tabla de mapeo de direcciones» que traduzca las direcciones virtuales de GPU a direcciones físicas que la tarjeta de red pueda entender. Esta tabla esconnectMap。

Estructuras de datos y diseño de memoria

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

connectMapes un sistema de «banco de memoria»:memsEl array tiene 5 ranuras (NCCL_NET_MAP_MEMS=5), correspondientes a host mem, dev mem, shared host mem, shared dev mem, GDC mem.offsetsCada campo dentro de

es un entero de 32 bits; los 3 bits altos codifican «qué banco» y los 29 bits bajos codifican «el desplazamiento dentro del banco».

📎 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)Copiaroffsets.sendMemTras expandir: se toman los 2 bits altos demems[bank].gpuPtrcomo índice de banco, se suma aconnectMapel desplazamiento de los 29 bits bajos y se obtiene el puntero real. Esta codificación comprime «qué región de memoria + desplazamiento dentro de la región» en un entero de 32 bits, ahorrando el tamaño de transmisión de

Walkthrough guiado por escenarios: establecimiento del mapeo en sendProxyConnect

sendProxyConnectes la función más compleja de NET; se encarga de establecer la conexión con la tarjeta de red, asignar búferes y registrar memoria:

📎 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 > 1Se habilita la «conexión compartida»: varios channels reutilizan la misma conexión de tarjeta de red, reduciendo el número de conexiones.activeConnectEl array garantiza que solo un local rank inicie la conexión, evitando duplicados.

A continuación se asignan los búferes y se registran:

📎 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_POINTERLa macro registra el búfer enconnectMap：

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

Búfer no compartido: se escribe elsizedel banco actual como desplazamiento enoffsets, y luegosize += memSize: esto es un bump allocator. Búfer compartido: se escribe directamente el número de banco, con desplazamiento 0 (porque el búfer compartido completo es un solo banco).

Por último, se registra la memoria para la tarjeta de red:

📎 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]));
      }
      ...

Se prioriza la ruta DMA-BUF (cuMemGetHandleForAddressRangeobtiene el fd y lo pasa al plugin de la tarjeta de red); si falla, se recurre aregMr(el tradicional nv_peermem GDR).

Control de concurrencia e interacción con hardware: la canalización en tres etapas de sendProxyProgress

sendProxyProgresses el motor de transferencia de datos de NET y adopta tres etapas: «post → transmit → done»:

📎 src/transport/net.cc:1324-1491

static ncclResult_t sendProxyProgress(struct ncclProxyState* proxyState, struct ncclProxyArgs* args) {
  ...
  if (args->state == ncclProxyOpProgress) {
    int p = args->protocol;
    int maxDepth = std::min(NCCL_STEPS, NCCL_SHARED_STEPS / args->nsubs);
    for (int s = 0; s < args->nsubs; s++) {
      struct ncclProxySubArgs* sub = args->subs + s;
      ...
      // Post buffers to the GPU
      if (sub->posted < sub->nsteps && sub->posted < sub->done + maxDepth) {
        ...
        if (resources->shared) {
          ...
          volatile uint64_t* sendHead = resources->gdcSync ? resources->gdcSync : &resources->sendMem->head;
          sub->posted += args->sliceSteps;
          *sendHead = sub->base + sub->posted - NCCL_STEPS;
          if (resources->gdcSync) wc_store_fence(); // Flush out WC write
        } else {
          sub->posted += args->sliceSteps;
        }
        ...
        continue;
      }
      // Check whether we received data from the GPU and send it to the network
      if (sub->transmitted < sub->posted && sub->transmitted < sub->done + NCCL_STEPS) {
        ...
        if (connFifo[buffSlot].size != -1 && (*recvTail > tail || p == NCCL_PROTO_LL)) {
          ...
          if (ready) {
            ...
            NCCLCHECK(proxyState->ncclNet->isend(resources->netSendComm, buff, size, resources->tpRank,
                                                 sub->sendMhandle, phandle, sub->requests + buffSlot));
            ...

• post: el hilo proxy actualizasendMem->head, indicando a la GPU «el búfer está listo, puedes escribir datos».
• transmit: comprueba sirecvMem->tailha avanzado (la GPU ya terminó de escribir), compruebaconnFifo[buffSlot].size != -1(el tamaño de datos ya está rellenado) y luego llama ancclNet->isendpara iniciar el envío asíncrono.
• done: llama ancclNet->testpara comprobar que el envío ha finalizado, actualizasendMem->heady devuelve el búfer.

wc_store_fence()es una barrera de combinación de escritura: en el escenario GDRCopy, tras la escritura de CPU engdcSynces obligatorio vaciar el búfer de combinación de escritura; de lo contrario, la GPU no verá la actualización.

Guía de evitación de errores en producción

Problema 1: validación del flag del protocolo LL128.Cuando los datos están en sysmem (no GDR), el hilo proxy debe comprobar línea por línea el flag de LL128:

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

Como la GPU solo ha llamado athreadfence(), es posible que los datos sigan en la caché L2 y no hayan llegado a sysmem. El hilo proxy debe confirmar que el flag de cada línea es correcto antes de enviar. Si en producción se detectan datos LL128 corruptos, comprobaruseGdr¿Es correcto? — En la ruta GDR, los datos van directamente a la memoria de la GPU, sin necesidad de verificación línea por línea.

Trampa 2: El orden de memoria del flush de GDRCopy.El lado receptor tiene enrecvProxyProgressun fragmento de ensamblado en línea ingenioso:

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

mfenceGarantiza que las lecturas del poll de CQE no se reordenen antes de la lectura del flush;mov (%0), %%eaxFuerza una lectura PCIe, haciendo que la CPU se detenga hasta que todas las escrituras posted previas de PCIe (incluyendo el DMA de la tarjeta de red) se hayan confirmado. Esta es la clave en escenarios GDRCopy para evitar que «la tarjeta de red dice que terminó de escribir pero los datos aún están en el búfer PCIe». Si se elimina esto, el receptor podría leer datos obsoletos.

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

V. NVLS: Grupos de multicast y enlace de memoria UC/MC

Modelo intuitivo

NVLS es una «estación de radio» — un rank escribe datos al grupo de multicast, y el hardware los copia automáticamente a todos los suscriptores. El AllReduce tradicional requiere N-1 transferencias punto a punto; NVLS solo necesita 1 escritura multicast + 1 lectura multicast. Sin NVLS, la latencia de AllReduce a gran escala crece linealmente con el número de ranks.

Estructuras de datos y diseño de memoria

El núcleo de NVLS es el enlace entre «memoria UC (unicast)» y «memoria MC (multicast)».nvlsAllocBindUcAsignar memoria UC y enlazarla al grupo 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);
  ...

Flujo:cuMemCreateAsignar memoria física →cuMemMapMapear a dirección virtual →cuMemSetAccessConfigurar permisos de acceso de GPU →ncclMcPartitionBindMemEnlazar la memoria física UC al offset especificado del grupo MC. Tras el enlace, cualquier rank que escriba a una dirección MC hará que el hardware copie los datos a toda la memoria UC enlazada.

NotabootstrapIntraNodeBarrierantes decuMulticastBindMem— el comentario dice que esto es para «mitigate the possible hang in cuMulticastBindMem during abort». Esta es una defensa a nivel de hardware: si un rank aborta durante el enlace, otros ranks podrían colgarse encuMulticastBindMemWalkthrough guiado por escenarios: diseño de búfer de ncclNvlsBufferSetup

Copiar

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

buffers (la mitad para reduce, la mitad para broadcast).2 * nChannelsysend[1]son la dirección reduce (UC → MC),recv[0]yrecv[1]son la dirección broadcast (MC → UC).send[0]es memoria UC local,dataUc.ptres la dirección mapeada del grupo MC.dataPartition.ptrReflexiones de diseño

〔Inferencia de diseño y compensaciones arquitectónicas〕

Guía de evitación de trampas en producción

Trampa: MNNVL no soporta el registro de búfer NVLS.VerncclNvlsSetup：

Hasta aquí, NCCL, a través de la capa de abstracción ncclTransport, ha unificado exitosamente los cuatro canales heterogéneos P2P, SHM, NET y NVLS en una interfaz consistente, y el kernel del algoritmo no necesita preocuparse por si la capa subyacente es NVLink o tarjeta de red. Pero la capa de transporte solo resuelve «cómo se abstraen los canales», aún no responde «cómo se impulsan los datos de forma asíncrona». En el próximo capítulo nos centraremos en src/proxy.cc y src/include/proxy.h, para ver cómo el hilo proxy impulsa asíncronamente el envío/recepción de red en el lado host, formando una relación productor-consumidor con el kernel de GPU, y revelando el mecanismo clave de la asincronía de NCCL.

Capítulo 12: Programación asíncrona del hilo proxy: cómo proxy.cc desacopla la E/S de la ejecución del kernel

El capítulo anterior desglosó la capa de abstracción de transport, mostrando cómo NCCL usa una interfaz unificada para ocultar las diferencias entre P2P/SHM/NET/NVLS. Pero la capa de transporte solo responde «por qué canal van los datos», aún no responde «cómo se impulsan los datos de forma asíncrona». Si el kernel de GPU se bloquea directamente esperando la red, las unidades de cómputo quedarían estranguladas por la E/S. Este capítulo se centra ensrc/proxy.ccysrc/include/proxy.h, para ver cómo NCCL usa hilos host independientes para separar la E/S de red de la ruta de ejecución del kernel, formando una relación productor-consumidor con la GPU.

12.1 Por qué se necesitan hilos proxy: empezando por «quién espera la red»

Modelo intuitivo

Imagina un restaurante: la cocina (GPU kernel) solo se encarga de cocinar, y el camarero (hilo proxy) se encarga de llevar los platos a los clientes (el extremo de red). Si se deja que el chef sirva los platos él mismo, tendría que detener la cocción cada vez que lleva un plato, y la velocidad de servicio se desplomaría. El proxy de NCCL es precisamente ese camarero dedicado: el kernel solo escribe datos en el búfer compartido y lee datos de él, mientras que todo el trabajo sucio de envío y recepción de red se delega a los hilos proxy del lado del host.

La división de trabajo entre los dos tipos de hilos

NCCL inicia dos tipos de hilos proxy en el lado del host, con responsabilidades completamente distintas:

• Hilo Service（ncclProxyService): maneja solicitudes del plano de control — establecimiento de conexiones, registro de memoria, consulta de FD. Escucha un socket, recibe solicitudes RPC del rank local y avanza asíncronamente operaciones como setup/connect.
• Hilo Progress（ncclProxyProgress): maneja el plano de datos — realmente impulsa el envío y recepción de red. Toma proxy ops del pool de memoria compartida, llama alproxyProgresscallback del transport para avanzar el movimiento de datos.

📎 src/include/proxy.h:343-345muestrancclProxyStatey mantiene simultáneamentethread(Service) ythreadUDS(servicio UDS), mientras que el handle del hilo Progress está oculto enprogressState.thread📎 src/include/proxy.h:261-261。

Establecimiento de la relación productor-consumidor

📎 src/proxy.cc:2130-2166ElncclProxyCreatees donde nace el hilo: cuandorefCount == 1(creación del primer comm), copia los campos clave del comm enproxyStatey luego inicia el hilo Service y el hilo UDS. Nota que el hilo Progress no se inicia aquí — es iniciado porproxyProgressInitde forma perezosa solo cuando se establece la primera conexión que necesita 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)"]

Esta imagen ancla la rama real de inicio del hilo: solo cuandotcomm->proxyProgressno está vacío (es decir, ese transport necesita avance del plano de datos), se crea el hilo Progress.

12.2 Estructuras de datos y diseño de memoria: pool de memoria compartida y pool de ops

Panorama de las estructuras centrales

El modelo de concurrencia del proxy se construye sobre dos bloques de memoria compartida; entender su diseño de memoria es el prerrequisito para comprender todo el mecanismo.

Primer bloque:ncclProxyOpsPool（📎 src/include/proxy.h:218-226). Este es el "buzón de entrega de tareas" entre el hilo principal y el hilo Progress, compartido entre procesos mediante/dev/shm

MAX_OPS_PER_PEERDefinición de📎 src/include/proxy.h:218-226es2 * MAXCHANNELS * 2 * NCCL_MAX_DEV_WORK_P2P_PER_BATCH. El comentario explica por qué es 2 veces: cada p2p work contiene un send y un recv proxy op, por lo que se multiplica por 2; multiplicar de nuevo por 2 es para poder almacenar dos rondas completas de operaciones, de lo contrario no se podría "entregar la mitad y liberar la mitad".

Segundo bloque:ncclProxyArgs（📎 src/include/proxy.h:174-209). Esta es la "descripción de op en tiempo de ejecución" usada internamente por el hilo Progress, asignada desdencclProxyPool, no compartida entre procesos.

Campos clave:

• subs[NCCL_PROXY_MAX_SUBS]: array de suboperaciones,NCCL_PROXY_MAX_SUBS = MAXCHANNELS 📎 src/include/proxy.h:55-55. Operaciones del mismo tipo de múltiples channels se agregan en múltiples sub dentro de un args.
• progress: puntero a función, apunta alproxyProgresscallback del transport📎 src/include/proxy.h:176-176。
• next / nextPeer / proxyAppendPtr: tres punteros de lista enlazada, que forman una compleja relación de organización de ops.
• state：ncclProxyOpNone / ncclProxyOpReady / ncclProxyOpProgressTres estados de📎 src/include/proxy.h:48-52。

Diseño en capas del pool de memoria

ncclProxyPool 📎 src/proxy.cc:50-53es una unidad de asignación por lotes, cada pool contienePROXYARGS_ALLOCATE_SIZE(es decir,NCCL_MAX_OPS)ncclProxyArgs。allocateArgs 📎 src/proxy.cc:207-231La lógica de asignación de

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

, y cada sub tiene

ncclProxyOpsPool), si cada op se malloc individualmente, causaría grave fragmentación de memoria y sobrecarga de asignación. Asignación por lotes + reutilización de lista de libres reduce el costo de asignación a casi cero. El comentario "Make sure we allocate the memory close to the network thread" sugiere que esto es por afinidad NUMA — el pool se crea en la primera asignación del hilo Progress, naturalmente cerca de la CPU donde se ejecuta ese hilo.nextOps、nextOpsEnd、freeOps[]Falso compartir y variables atómicasvolatile intLos

enncclLocalOpAppendson todos📎 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();
}

Observa la lógica de tomar una op libre de freeOps enatomic_exchangecopiafreeOps[tpLocalRank]se establece en -1 y se recupera el valor antiguo——esto es una «toma preventiva»: quien logre exchange primero obtiene toda la lista de libres. Cuando el hilo Progress devuelve una op, usa un bucle 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 Plano de control: establecimiento de conexión y mecanismo RPC

Modelo intuitivo

Codificación de solicitudes RPC

ncclProxyCallAsync 📎 src/proxy.cc:1369-1394Es el extremo emisor del RPC. Envía secuencialmente a través del socket: type, puntero de 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

Nótese el último paso: tras enviar la solicitud, registra inmediatamente el opId en laexpectedResponsescola. Esta es la clave del RPC asíncrono——el invocador no espera la respuesta, sino que primero registra «espero la respuesta de este opId», y luego usancclPollProxyResponsepara hacer polling.

Implementación de lista enlazada de la cola de respuestas

expectedProxyResponseEnqueue 📎 src/proxy.cc:97-117Utiliza una lista enlazada simple para almacenar las op pendientes de respuesta.expectedProxyResponseStore 📎 src/proxy.cc:67-95Al recibir una respuesta, se empareja por opId, se hace memcpy de los datos de respuesta en elrespBuffpreasignado, se marcadone = true。expectedProxyResponseDequeue 📎 src/proxy.cc:119-141En el polling se buscan las respuestas completadas y se extraen.

Aquí hay un detalle:expectedProxyResponseStoreCompruebarespSizesi coincide con📎 src/proxy.cc:72-75, si no coincide reportancclInternalError. Esto es programación defensiva——si el solicitante y el respondedor tienen entendimientos inconsistentes sobre el tamaño de la respuesta, significa que el protocolo está corrupto, y debe fallar inmediatamente en lugar de continuar silenciosamente.

Bucle principal del hilo Service

ncclProxyService 📎 src/proxy.cc:1789-2016El núcleo es un bucle poll. Utilizapollfdsun array para gestionar todas las conexiones, incluyendo el listen socket y el socket de cada peer.

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

timeoutLa elección de es muy cuidadosa: si hay ops asíncronas en progreso (asyncOpCount > 0), el timeout se establece en 0 (polling no bloqueante), porque se necesita llamar frecuentemente aproxyProgressAsyncpara avanzarlas; de lo contrario se establece en 500ms, para evitar girar en vacío quemando CPU. El comentario «never let proxy service thread blocks in poll, or it cannot receive abortFlag»📎 src/proxy.cc:1847-1847señala por qué no se puede bloquear indefinidamente——debe despertar periódicamente para comprobar abortFlag.

Avance de ops asíncronas

proxyProgressAsync 📎 src/proxy.cc:1626-1700Es el núcleo del hilo Service para avanzar operaciones asíncronas. Distribuye a diferentes callbacks de transport según el tipo de op:

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

Cada callback lleva undoneparámetro de salida. Sidone == 0, significa que la operación aún no ha terminado (por ejemplo, la conexión de red todavía está en el three-way handshake), devuelvencclInProgress, y el siguiente ciclo continúa avanzando. Sidone == 1, entonces envía la cabecera de respuesta + cuerpo de respuesta al solicitante📎 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 取回结果

Este diagrama de secuencia anclasendProxyConnectdentro de*done = 0; return ncclInProgressla rama real de📎 src/transport/net.cc:913-916。

12.4 Plano de datos: cómo el hilo Progress impulsa el envío/recepción de red

Modelo intuitivo

El hilo Progress es un «operador de cinta transportadora»: vigila la FIFO en el búfer compartido, y en cuanto la GPU ha escrito los datos (size != -1 en la FIFO), llama inmediatamente aisendpara enviar los datos; en cuanto la red termina de recibir los datos, actualiza recvTail para notificar a la GPU que puede leer. Todo el proceso sincroniza GPU y proxy a través de los punteros head/tail en la FIFO, sin necesidad de ningún lock.

Entrega de ops: del hilo principal al hilo Progress

El hilo principal enncclProxySaveOp 📎 src/proxy.cc:591-761decide según el pattern qué proxy ops se necesitan, y luego medianteSaveProxy → ncclLocalOpAppendescribe las ops en el pool de memoria compartida.

ncclLocalOpAppend 📎 src/proxy.cc:488-554El flujo de :

1. DeproxyOps->freeOpopool->freeOps[tpLocalRank]toma un slot de op libre.