PCCL: NCCL APIs and environment variable support (v1.7)

Updated at:
Copy as MD

1. Overview

This document summarizes the differences in APIs and environment variables between PCCL and NCCL 2.22.3, along with their corresponding version information. It also provides recommendations for optimal environment variable configurations in model training and inference scenarios.

2. APIs

2.1 NCCL API compatibility

API name

NCCL

PCCL

Supported version

Remarks

ncclGetVersion

✅

✅

ncclGetUniqueId

✅

✅

ncclCommInitRank

✅

✅

ncclCommInitAll

✅

✅

ncclCommDestroy

✅

✅

ncclCommAbort

✅

✅

ncclGetErrorString

✅

✅

ncclGetLastError

✅

✅

ncclCommGetAsyncError

✅

✅

ncclCommCount

✅

✅

ncclCommCuDevice

✅

✅

ncclCommUserRank

✅

✅

ncclReduce

✅

✅

ncclBroadcast

✅

✅

ncclAllReduce

✅

✅

ncclReduceScatter

✅

✅

ncclAllGather

✅

✅

ncclSend

✅

✅

ncclRecv

✅

✅

ncclGroupStart

✅

✅

ncclGroupEnd

✅

✅

ncclCommInitRankConfig

✅

✅

Since PCCL 1.4.0

ncclCommFinalize

✅

✅

Since PCCL 1.4.0

ncclCommSplit

✅

✅

Since PCCL 1.4.0

PCCL 1.4.0 only supports the splitShare=0 and blocking configurations from pcclConfig_t. Full support is available since PCCL 1.5.0.

ncclCommRegister

✅

✅

Since PCCL 1.4.0

This API is compatible, but it has no effect due to hardware limitations.

ncclCommDeregister

✅

✅

Since PCCL 1.4.0

This API is compatible, but it has no effect due to hardware limitations.

ncclMemAlloc

✅

✅

Since PCCL 1.4.0

Falls back to cudaMalloc() due to hardware limitations.

ncclMemFree

✅

✅

Since PCCL 1.4.0

Falls back to cudaFree() due to hardware limitations.

ncclCommWindowRegister

✅

✅

Since PCCL 1.7.0

ncclCommWindowDeregister

✅

✅

Since PCCL 1.7.0

ncclCommInitRankScalable

✅

✅

Since PCCL 1.7.0

ncclRedOpCreatePreMulSum

✅

❌

ncclRedOpDestroy

✅

❌

ncclGroupSimulateEnd

✅

❌

ncclCommRevoke

✅

❌

ncclCommShrink

✅

❌

ncclAlltoAll

✅

❌

ncclGather

✅

❌

ncclScatter

✅

❌

ncclResetDebugInit

✅

❌

Deprecated and will be removed in a future release.

2.2 PCCL extended APIs

N/A

3. Environment variables

3.1 Supported NCCL environment variables

Note: These statistics are taken from the official NCCL documentation. This list omits a few environment variables that appear in the NCCL code but are undocumented.

Parameter

NCCL

PCCL

PCCL support version

Notes

NCCL_SOCKET_IFNAME

✅

✅

NCCL_SOCKET_FAMILY

✅

✅

NCCL_SOCKET_NTHREADS

✅

✅

NCCL_NSOCKS_PERTHREAD

✅

✅

NCCL_CROSS_NIC

✅

✅

NCCL_IB_HCA

✅

✅

NCCL_IB_TIMEOUT

✅

✅

NCCL_IB_RETRY_CNT

✅

✅

NCCL_IB_GID_INDEX

✅

✅

NCCL_IB_ADDR_FAMILY

✅

✅

NCCL_IB_ADDR_RANGE

✅

✅

NCCL_IB_ROCE_VERSION_NUM

✅

✅

NCCL_IB_PKEY

✅

✅

NCCL_IB_USE_INLINE

✅

✅

NCCL_IB_SL

✅

✅

NCCL_IB_TC

✅

✅

NCCL_TUNER_PLUGIN

✅

✅

NCCL_IGNORE_CPU_AFFINITY

✅

✅

NCCL_DEBUG

✅

✅

NCCL_DEBUG_SUBSYS

✅

✅

NCCL_COLLNET_ENABLE

✅

✅

NCCL_TOPO_FILE

✅

✅

NCCL_TOPO_DUMP_FILE

✅

✅

NCCL_P2P_DISABLE

✅

✅

NCCL_P2P_LEVEL

✅

✅

NCCL_SHM_DISABLE

✅

✅

NCCL_BUFFSIZE

✅

✅

NCCL_NTHREADS

✅

✅

NCCL_MAX_NCHANNELS

✅

✅

NCCL_MIN_NCHANNELS

✅

✅

NCCL_CHECK_POINTERS

✅

✅

NCCL_LAUNCH_MODE

✅

✅

NCCL_IB_DISABLE

✅

✅

NCCL_IB_AR_THRESHOLD

✅

✅

NCCL_IB_QPS_PER_CONNECTION

✅

✅

NCCL_NET_GDR_LEVEL (formerly NCCL_IB_GDR_LEVEL)

✅

✅

NCCL_NET_SHARED_BUFFERS

✅

✅

NCCL_NET_SHARED_COMMS

✅

✅

NCCL_ALGO

✅

✅

NCCL_PROTO

✅

✅

NCCL_NVB_DISABLE

✅

✅

NCCL_PXN_DISABLE

✅

✅

NCCL_P2P_PXN_LEVEL

✅

✅

NCCL_NET_GDR_READ

✅

✅

NCCL_MIN_P2P_NCHANNELS

✅

✅

NCCL_MAX_P2P_NCHANNELS

✅

✅

NCCL_TOPO_DUMP_FILE_RANK

✅

✅

NCCL_GRAPH_DUMP_FILE_RANK

✅

✅

NCCL_PROXY_DUMP_SIGNAL

✅

✅

NCCL_GDRCOPY_SYNC_ENABLE

✅

✅

NCCL_GDRCOPY_FLUSH_ENABLE

✅

✅

NCCL_GDR_FLUSH_DISABLE

✅

✅

NCCL_LL128_NTHREADS

✅

✅

NCCL_P2P_READ_ENABLE

✅

✅

NCCL_P2P_DIRECT_DISABLE

✅

✅

PCCL 1.4.0 and later

NCCL_NET_PLUGIN

✅

✅

PCCL 1.4.0 and later

NCCL_COMM_BLOCKING

✅

✅

PCCL 1.4.0 and later

NCCL_LOCAL_REGISTER

✅

✅

PCCL 1.4.0 and later

NCCL_REPORT_CONNECT_PROGRESS

✅

✅

PCCL 1.4.0 and later

NCCL_SET_STACK_SIZE

✅

✅

PCCL 1.4.3 and later

NCCL_NET

✅

✅

PCCL 1.5.0 and later

NCCL_U2MM_LOG_LEVEL

❌

✅

PCCL 1.5.0 and later

Supported on EIC NIC platforms

NCCL_P2P_USE_CUDA_MEMCPY

✅

✅

PCCL 1.5.0 and later

NCCL_COMM_SPLIT_SHARE_RESOURCES

✅

✅

PCCL 1.5.0 and later

NCCL_IB_SPLIT_DATA_ON_QPS

✅

✅

PCCL 1.6.0 and later

NCCL_GDRCOPY_ENABLE

✅

✅

PCCL 1.6.1 and later

NCCL_GDRCOPY_FIFO_ENABLE

✅

✅

PCCL 1.6.1 and later

NCCL_RAS_ENABLE

✅

✅

PCCL 1.7.0 and later

NCCL_RAS_ADDR

✅

✅

PCCL 1.7.0 and later

NCCL_RAS_TIMEOUT_FACTOR

✅

✅

PCCL 1.7.0 and later

NCCL_SOCKET_RETRY_SLEEP_MSEC

✅

✅

PCCL 1.7.0 and later

NCCL_GRAPH_REGISTER

✅

✅

PCCL 1.7.0 and later

NCCL_WIN_ENABLE

✅

✅

PCCL 1.7.0 and later

NCCL_WIN_STRIDE

✅

✅

PCCL 1.7.0 and later

NCCL_SOCKET_RETRY_CNT

✅

✅

PCCL 1.7.0 and later

NCCL_UID_STAGGER_THRESHOLD

✅

✅

PCCL 1.7.0 and later

NCCL_UID_STAGGER_RATE

✅

✅

PCCL 1.7.0 and later

NCCL_CUMEM_ENABLE

✅

✅

PCCL 1.7.0 and later

NCCL_LEGACY_CUDA_REGISTER

✅

✅

PCCL 1.7.0 and later

NCCL_CREATE_THREAD_CONTEXT

✅

✅

PCCL 1.7.0 and later

NCCL_CTA_POLICY

✅

✅

PCCL 1.7.0 and later

NCCL_CONF_FILE

✅

✅

PCCL 1.7.0 and later

NCCL_SYM_CTAS

✅

✅

PCCL 1.7.0 and later

NCCL_SYM_KERNEL

✅

✅

PCCL 1.7.0 and later

NCCL_COLLNET_NODE_THRESHOLD

✅

❌

NCCL_NVB_PRECONNECT

✅

❌

NCCL_GRAPH_HELPER_DISABLE

✅

❌

NCCL_SET_THREAD_NAME

✅

❌

NCCL_IB_PCI_RELAXED_ORDERING

✅

❌

NCCL_IGNORE_DISABLED_P2P

✅

❌

NCCL_NCHANNELS_PER_NET_PEER

✅

❌

NCCL_GRAPH_MIXING_SUPPORT

✅

❌

NCCL_DMABUF_ENABLE

✅

❌

NCCL_SHM_USE_CUDA_MEMCPY

✅

❌

NCCL_SHM_MEMCPY_MODE

✅

❌

NCCL_SHM_LOCALITY

✅

❌

NCCL_P2P_NET_CHUNKSIZE

✅

❌

NCCL_NET_DISABLE_INTRA

✅

❌

NCCL_P2P_LL_THRESHOLD

✅

❌

NCCL_ALLOC_P2P_NET_LL_BUFFERS

✅

❌

NCCL_NET_FORCE_FLUSH

✅

❌

NCCL_IB_ADAPTIVE_ROUTING

✅

❌

NCCL_MEM_SYNC_DOMAIN

✅

❌

NCCL_CGA_CLUSTER_SIZE

✅

❌

NCCL_P2P_PCI_CHUNKSIZE

✅

❌

NCCL_P2P_NVL_CHUNKSIZE

✅

❌

NCCL_PROXY_APPEND_BATCH_SIZE

✅

❌

NCCL_PROGRESS_APPENDOP_FREQ

✅

❌

NCCL_L1_SHARED_MEMORY_CARVEOUT

✅

❌

NCCL_MAX_CTAS

✅

❌

NCCL_MIN_CTAS

✅

❌

NCCL_NVLS_ENABLE

✅

❌

NCCL_NVLS_NCHANNELS

✅

❌

NCCL_NET_OVERHEAD

✅

❌

NCCL_CUMEM_HOST_ENABLE

✅

❌

Supported in NCCL 2.23 and later

NCCL_IB_MERGE_VFS

✅

❌

NCCL_CONNECT_ROUND_MAX_PEERS

✅

❌

NCCL_IB_MERGE_NICS

✅

❌

Supported in NCCL 2.20 and later

NCCL_MNNVL_ENABLE

✅

❌

Supported in NCCL 2.21 and later

NCCL_NVLS_CHUNKSIZE

✅

❌

NCCL_CHUNK_SIZE

✅

❌

NCCL_NVLSTREE_MAX_CHUNKSIZE

✅

❌

NCCL_UNPACK_DOUBLE_NCHANNELS

✅

❌

NCCL_RUNTIME_CONNECT

✅

❌

Supported in NCCL 2.22 and later

NCCL_WORK_FIFO_BYTES

✅

❌

NCCL_WORK_ARGS_BYTES

✅

❌

NCCL_IB_ROUTABLE_FLID_GID_INDEX

✅

❌

NCCL_IB_FIFO_TC

✅

❌

Supported in NCCL 2.22 and later

NCCL_IB_RETURN_ASYNC_EVENTS

✅

❌

Supported in NCCL 2.23 and later

NCCL_OOB_NET_ENABLE

✅

❌

Supported in NCCL 2.23 and later

NCCL_OOB_NET_IFNAME

✅

❌

Supported in NCCL 2.23 and later

NCCL_IB_ECE_ENABLE

✅

❌

Supported in NCCL 2.23 and later

NCCL_PROFILER_PLUGIN

✅

❌

NCCL_ENV_PLUGIN

✅

❌

NCCL_DEBUG_TIMESTAMP_FORMAT

✅

❌

NCCL_DEBUG_TIMESTAMP_LEVELS

✅

❌

NCCL_NETDEVS_POLICY

✅

❌

NCCL_NET_GDR_C2C

✅

❌

NCCL_PXN_C2C

✅

❌

NCCL_MNNVL_UUID

✅

❌

NCCL_MNNVL_CLIQUE_ID

✅

❌

NCCL_LAUNCH_ORDER_IMPLICIT

✅

❌

NCCL_LAUNCH_RACE_FATAL

✅

❌

3.2 PCCL extended environment variables

PCCL-specific environment variables are prefixed with PCCL_ for easy identification.

Parameter

Supported version

Description

PCCL_ICN_SCALE_OUT_DISABLE

PCCL_NET_BYPASS

PCCL_FORCE_ICN_SCALE_OUT

PCCL_DISABLE_ADJUST_SYSTEM

PCCL_DUMP_CONN_INFO

PCCL_CU_MASK

PCCL_BLOCKS_PER_FC_LINK

PCCL_P2P_NCHANNELS_FACTOR_NPATHS

PCCL_DISABLE_ABORT

PCCL_CHANNEL_SHUFFLE

PCCL_DUMP_WORK_ELEMS

Dumps the ncclWorkElem information for each active ncclWork in the channel.

PCCL_REVERSE_RING_INTERLEAVE

PCCL_ONEBATCH_PER_CE

PCCL_IB_DISABLE_ACC_BONDING_PORT

PCCL_BOOTSTRAP_DEBUG

PCCL_USE_STATIC_LAUNCH_GRID

PCCL_RING_DUMP_FILE

PCCL_DISABLE_TORUS_GRAPH

PCCL_CE_MASK

PCCL_GRAPH_TREE_PATTERN

PCCL_PROXY_DUMP_FILE

PCCL_DISP_MODE

PCCL_QUADRUPLE_CHANNELS

PCCL_PER_COMM_HASH_DEBUG_FILE

PCCL_COMM_DUMP_SIGNAL

PCCL_GLOBAL_TOPO_FILE

PCCL_PERFMODEL_SPEEDUP

PCCL_IGNORE_TOPO_DETECTION

PCCL_SINGLE_HOST_CROSS_NODE_TEST

PCCL_BLOCKING_BOOTSTRAP

PCCL_NO_MEMSET

PCCL_GET_MIN_PATH_NUM_BY_DRIVER

PCCL_MULTI_HOSTS_BULK_MODE

PCCL_GROUP_HGGC_STREAM

PCCL_DISABLE_FC_GRAPH

PCCL_ADJUST_SYSTEM_MIN_NET_NUM

PCCL_TB_PER_CU

PCCL_TRAVERSE_Y

PCCL_IGNORE_INTEL_P2P_OVERHEAD

PCCL_GRAPH_SEARCH_START_INTER_TYPE

Configures the starting interconnect type for cross-node graph searches, such as PXN, to accelerate the search.

PCCL_INJECTION64_PATH

PCCL_DEBUG_DEV

PCCL_ERROR_YIELD

PCCL_GRAPH_SPEEDS

PCCL_COMM_DUMP_FILE

PCCL_ENABLE_ABORT_DUMP

PCCL_ENABLE_EXT_KERNEL

Introduced in PCCL version 1.4.0

PCCL_EXT_KERNEL_PLUGIN

Introduced in PCCL version 1.4.0

PCCL_COMM_DUMP_LEVEL

Introduced in PCCL version 1.4.0

PCCL_STATE_MONITOR_DISABLE

Introduced in PCCL version 1.4.0

Controls the PCCL kernel state monitor.

PCCL_STATE_MONITOR_TRIGGER_PIPE

Introduced in PCCL version 1.4.0

PCCL_STATE_MONITOR_SLEEP_US

Introduced in PCCL version 1.4.0

PCCL_STATE_MONITOR_QUIT_WHEN_EXCEPTION

Introduced in PCCL version 1.4.0

PCCL_STATE_MONITOR_DUMP_WHEN_EXCEPTION_DISABLE

Introduced in PCCL version 1.4.0

PCCL_STATE_SYNC_POLL_INTERVAL_MS

Introduced in PCCL version 1.4.0

PCCL_STATE_MONITOR_LOG_EVERY_MS

Introduced in PCCL version 1.4.0

PCCL_GDR_USE_DEV_MEM_FOR_RX_TAIL

Introduced in PCCL version 1.4.0

Uses device memory for the tail pointer in GDR-path communication.

PCCL_GDR_CPU_FLUSH

Introduced in PCCL version 1.4.0

Uses a PCIe read from CPU memory for the GDR flush operation.

PCCL_DEBUG_DUMP_DIR

Introduced in PCCL version 1.4.3

Specifies the directory path for debug dump files.

PCCL_IB_NIC_SPEED_SCALING_FACTOR

Introduced in PCCL version 1.4.3

Specifies the bandwidth scaling factor for an InfiniBand (IB) NIC to correct speed mismatches when system bonding information is missing.

PCCL_NET_AFFINITY

Introduced in PCCL version 1.5.0

Specifies the network affinity ID for a PPU. The required format is "hgml_dev_id:net_id,hgml_dev_id:net_id".

PCCL_CHECK_ITEMS_ENABLE

Introduced in PCCL version 1.5.0

Specifies whether to enable internal checks for potential topology or environment issues.

PCCL_DOUBLE_EIC_PCI_WIDTH_DISABLE

Introduced in PCCL version 1.5.0

Set to 0 when running on an EIC platform. The default is 0.

PCCL_STATE_MONITOR_LEVEL

Introduced in PCCL version 1.5.0

Specifies the level of detail for the state monitor.

PCCL_D2D_DISP_PING_PONG_EN

Introduced in PCCL version 1.6.0

PCCL_JUMP_DIM

Introduced in PCCL version 1.6.0

PCCL_LAST_ROUND_EN

Introduced in PCCL version 1.6.0

PCCL_ONE_BATCH_PER_CE

Introduced in PCCL version 1.6.0

PCCL_SKEW_EN

Introduced in PCCL version 1.6.0

PCCL_TRAVERSE_Y_STEP

Introduced in PCCL version 1.6.0

PCCL_FB_STALL_ST_TYPE

Introduced in PCCL version 1.6.0

PCCL_TRAVERSE_X_STEP

Introduced in PCCL version 1.6.0

PCCL_LAST_ROUND_TB_PER_CE

Introduced in PCCL version 1.6.0

PCCL_TUNING_FALL_BACK

Introduced in PCCL version 1.6.0

PCCL_FB_STALL_ST_EN

Introduced in PCCL version 1.6.0

PCCL_FORCE_DEFAULT_DISP

Introduced in PCCL version 1.6.0

PCCL_START_CE_ID

Introduced in PCCL version 1.6.0

PCCL_LAST_ROUND_ONETB_PER_CE

Introduced in PCCL version 1.6.0

PCCL_WAIT_EN

Introduced in PCCL version 1.6.0

PCCL_LAST_ROUND_BEGIN_NUMBER

Introduced in PCCL version 1.6.0

PCCL_PRE_ALLOC_EN

Introduced in PCCL version 1.6.0

PCCL_BLOCK_AGE_EN

Introduced in PCCL version 1.6.0

PCCL_NDIES

Introduced in PCCL version 1.6.0

PCCL_START_CE_EN

Introduced in PCCL version 1.6.0

PCCL_FORCE_DEFAULT_CE_MASK

Introduced in PCCL version 1.6.0

4. Net APIs

4.1 Net APIs

NCCL 2.22.3 + Net V8

PCCL 1.5 + Net V6

Description

const char* name

const char* name

Name of the network.

ncclResult_t (*init)(ncclDebugLogger_t logFunction);

pcclResult_t (*init)(pcclDebugLogger_t logFunction);

Initializes the network.

ncclResult_t (*devices)(int* ndev);

pcclResult_t (*devices)(int* ndev);

Returns the number of adapters.

ncclResult_t (*getProperties)(int dev, ncclNetProperties_v8_t* props);

pcclResult_t (*getProperties)(int dev, pcclNetProperties_v6_t* props);

Gets various device properties.

ncclResult_t (*listen)(int dev, void* handle, void** listenComm);

pcclResult_t (*listen)(int dev, void* handle, void** listenComm);

Creates a receiving object and returns a handle for peers to connect.

ncclResult_t (*connect)(int dev, void* handle, void** sendComm, ncclNetDeviceHandle_v8_t** sendDevComm);

pcclResult_t (*connect)(int dev, void* handle, void** sendComm);

Connects to a handle and returns a send communicator for the peer.

ncclResult_t (*accept)(void* listenComm, void** recvComm, ncclNetDeviceHandle_v8_t** recvDevComm);

pcclResult_t (*accept)(void* listenComm, void** recvComm);

Accepts a connection initiated via connect.

ncclResult_t (*regMr)(void* comm, void* data, size_t size, int type, void** mhandle);

pcclResult_t (*regMr)(void* comm, void* data, int size, int type, void** mhandle);

Registers a memory region.

ncclResult_t (*regMrDmaBuf)(void* comm, void* data, size_t size, int type, uint64_t offset, int fd, void** mhandle);

pcclResult_t (*regMrDmaBuf)(void* comm, void* data, size_t size, int type, uint64_t offset, int fd, void** mhandle);

Registers a DMA buffer as a memory region.

ncclResult_t (*deregMr)(void* comm, void* mhandle);

pcclResult_t (*deregMr)(void* comm, void* mhandle);

Deregisters a memory region.

ncclResult_t (*isend)(void* sendComm, void* data, int size, int tag, void* mhandle, void** request);

pcclResult_t (*isend)(void* sendComm, void* data, int size, int tag, void* mhandle, void** request);

Sends data to a peer asynchronously.

ncclResult_t (*irecv)(void* recvComm, int n, void** data, int* sizes, int* tags, void** mhandles, void** request);

pcclResult_t (*irecv)(void* recvComm, int n, void** data, int* sizes, int* tags, void** mhandles, void** request);

Receives data from a peer asynchronously.

ncclResult_t (*iflush)(void* recvComm, int n, void** data, int* sizes, void** mhandles, void** request);

pcclResult_t (*iflush)(void* recvComm, int n, void** data, int* sizes, void** mhandles, void** request);

Flushes the receive queue to ensure all pending data is received.

ncclResult_t (*test)(void* request, int* done, int* sizes);

pcclResult_t (*test)(void* request, int* done, int* size);

Tests whether a request is complete.

ncclResult_t (*closeSend)(void* sendComm);

pcclResult_t (*closeSend)(void* sendComm);

Closes and frees the specified send, receive, or listen communicator.

ncclResult_t (*closeRecv)(void* recvComm);

pcclResult_t (*closeRecv)(void* recvComm);

ncclResult_t (*closeListen)(void* listenComm);

pcclResult_t (*closeListen)(void* listenComm);

ncclResult_t (*getDeviceMr)(void* comm, void* mhandle, void** dptr_mhandle);

❌

Copies the given mhandle to a device pointer.

ncclResult_t (*irecvConsumed)(void* recvComm, int n, void* request);

❌

Notifies the plugin that the device has completed a receive operation.

4.2 Coll Net APIs

NCCL 2.22.3 + Coll Net V8

PCCL 1.5 + Coll Net V6

Description

const char* name

const char* name

Name of the network.

ncclResult_t (*init)(ncclDebugLogger_t logFunction);

pcclResult_t (*init)(pcclDebugLogger_t logFunction);

Initializes the network.

ncclResult_t (*devices)(int* ndev);

pcclResult_t (*devices)(int* ndev);

Returns the number of adapters.

ncclResult_t (*getProperties)(int dev, ncclNetProperties_v8_t* props);

pcclResult_t (*getProperties)(int dev, pcclNetProperties_v4_t* props);

Gets various device properties.

ncclResult_t (*listen)(int dev, void* handle, void** listenComm);

pcclResult_t (*listen)(int dev, void* handle, void** listenComm);

Creates a receiving object and returns a handle for peers to connect.

ncclResult_t (*connect)(void* handles[], int nranks, int rank, void* listenComm, void** collComm);

pcclResult_t (*connect)(void* handles[], int nranks, int rank, void* listenComm, void** collComm);

Creates a communicator group for collective operations.

ncclResult_t (*reduceSupport)(ncclDataType_t dataType, ncclRedOp_t redOp, int* supported);

pcclResult_t (*reduceSupport)(pcclDataType_t dataType, pcclRedOp_t redOp, int* supported);

Checks if a given reduction operation and data type are supported.

ncclResult_t (*regMr)(void* collComm, void* data, size_t size, int type, void** mhandle);

pcclResult_t (*regMr)(void* collComm, void* data, int size, int type, void** mhandle);

Registers a memory region.

ncclResult_t (*regMrDmaBuf)(void* collComm, void* data, size_t size, int type, uint64_t offset, int fd, void** mhandle);

pcclResult_t (*regMrDmaBuf)(void* collComm, void* data, size_t size, int type, uint64_t offset, int fd, void** mhandle);

Registers a DMA buffer as a memory region.

ncclResult_t (*deregMr)(void* collComm, void* mhandle);

pcclResult_t (*deregMr)(void* collComm, void* mhandle);

Deregisters a memory region.

ncclResult_t (*iallreduce)(void* collComm, void* sendData, void* recvData, int count,

ncclDataType_t dataType, ncclRedOp_t redOp, void* sendMhandle, void* recvMhandle, void** request);

pcclResult_t (*iallreduce)(void* collComm, void* sendData, void* recvData, int count,

pcclDataType_t dataType, pcclRedOp_t redOp, void* sendMhandle, void* recvMhandle, void** request);

Performs an asynchronous all-reduce operation.

ncclResult_t (*iallgather)(void* collComm, void* sendData, int nRecvParts, ncclNetSGE_v8_t* recvParts,

size_t bytesPerRank, size_t windowOffset, size_t windowBytes,

void* sendMhandle, void** request);

❌

Performs an asynchronous all-gather operation.

ncclResult_t (*ireducescatter)(void* collComm, int nSendParts, ncclNetSGE_v8_t* sendParts, void* recvData,

size_t bytesPerRank, size_t windowOffset, size_t windowBytes,

ncclDataType_t dataType, ncclRedOp_t redOp,

void* recvMhandle, void** request);

❌

Performs an asynchronous reduce-scatter operation.

ncclResult_t (*iflush)(void* collComm, void* data, int size, void* mhandle, void** request);

pcclResult_t (*iflush)(void* collComm, void* data, int size, void* mhandle, void** request);

Flushes the receive queue to ensure all pending data is received.

ncclResult_t (*test)(void* request, int* done, int* size);

pcclResult_t (*test)(void* request, int* done, int* size);

Tests whether a request is complete.

ncclResult_t (*closeColl)(void* collComm);

pcclResult_t (*closeColl)(void* collComm);

Closes and frees the specified communicator (collective or listening).

ncclResult_t (*closeListen)(void* listenComm);

pcclResult_t (*closeListen)(void* listenComm);

5. Environment variables for model training and inference

Based on extensive performance analysis, PCCL provides several environment variables that you can set to improve model training performance.

5.1 CUDA_VISIBLE_DEVICES

For parallel training configurations based on Megatron core, you can run a pre-scan script to find the optimal setting for CUDA_VISIBLE_DEVICES. The script searches for the best configuration based on your specified parallel parameters. Using the recommended configuration can significantly improve communication efficiency and model training performance compared to the default settings.

5.2 Zhenwu 810E multi-node training (not required in v1.5.2 and later)

Note: This configuration is no longer required for PCCL version 1.5.2 and later, as PCCL automatically detects and uses the affinity network interfaces.

If your model training involves multi-node communication, configure the following environment variables to assign the optimal network interfaces for Zhenwu 810E. This setup ensures traffic uses the highest-performance GPUDirect RDMA (GDR) path and excludes the head node network interface, improving end-to-end training performance. These settings are critical for optimal performance in multi-node allToAll operations.

image

// PCCL_NET_AFFINITY format: "hgml_dev_id:net_id,hgml_dev_id:net_id"
// NCCL_IB_HCA typically filters out the head node network interface, which causes a -1 offset for the NET ID.
export PCCL_NET_AFFINITY=0:3,1:3,4:1,5:1,8:2,9:2,12:0,13:0
export NCCL_NET_GDR_LEVEL=PHBH
export NCCL_IB_HCA=mlx5_bond_1,mlx5_bond_2,mlx5_bond_3,mlx5_bond_4

5.3 PPU resource control

When compute and communication overlap, you can set the following environment variables to reduce the communication library's compute resource usage. This can improve end-to-end training performance. (This is an experimental feature, and its effectiveness depends on the actual workload.)

export PCCL_CU_MASK=8
export NCCL_NTHREADS=256
export NCCL_LL128_NTHREADS=320
export PCCL_CU_MASK=12
export NCCL_NTHREADS=256
export NCCL_LL128_NTHREADS=320