AI/rocm-systems
2
0
Garpu 0
Kode Masalah Tarik Permintaan Actions Packages Projects Rilis Wiki Kegiatan

what-is-rccl (#1312)

Telusuri Sumber 
* what-is-rccl

* create Installation instreuctions from README

* update README link

* Add using-nccl

* Add note about docs

* correct doc path

* sources to source

* correct docs link
This commit is contained in:
randyh62
2024-09-05 06:54:48 -07:00
committed by GitHub
orang tua e056fe8f7e
melakukan 391c7ea070
5 mengubah file dengan 474 tambahan dan 10 penghapusan
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -1
Melihat File
@@ -2,6 +2,8 @@
ROCm Communication Collectives Library
**Note:** The published documentation is available at [RCCL](https://rocm.docs.amd.com/projects/rccl/en/latest/index.html) in an organized easy-to-read format that includes a table of contents and search functionality. The documentation source files reside in the [rccl/docs](https://github.com/ROCm/rccl/tree/develop/docs) folder in this repository. As with all ROCm projects, the documentation is open source. For more information, see [Contribute to ROCm documentation](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
## Introduction
RCCL (pronounced "Rickle") is a stand-alone library of standard collective communication routines for GPUs, implementing all-reduce, all-gather, reduce, broadcast, reduce-scatter, gather, scatter, and all-to-all. There is also initial support for direct GPU-to-GPU send and receive operations. It has been optimized to achieve high bandwidth on platforms using PCIe, xGMI as well as networking using InfiniBand Verbs or TCP/IP sockets. RCCL supports an arbitrary number of GPUs installed in a single node or multiple nodes, and can be used in either single- or multi-process (e.g., MPI) applications.
@@ -109,8 +111,8 @@ Filtering of rccl unit tests should be done with environment variable and by pas
```shell
UT_DATATYPES=ncclBfloat16 UT_REDOPS=prod ./rccl-UnitTests --gtest_filter="AllReduce.C*"
```
will run only AllReduce correctness tests with float16 datatype. A list of available filtering environment variables appears at the top of every run. See "Running a Subset of the Tests" at https://chromium.googlesource.com/external/github.com/google/googletest/+/HEAD/googletest/docs/advanced.md for more information on how to form more advanced filters.
will run only AllReduce correctness tests with float16 datatype. A list of available filtering environment variables appears at the top of every run. See "Running a Subset of the Tests" at https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests for more information on how to form more advanced filters.
There are also other performance and error-checking tests for RCCL. These are maintained separately at https://github.com/ROCm/rccl-tests.
See the rccl-tests README for more information on how to build and run those tests.
docs/how-to/using-nccl.rst
+281
Melihat File
@@ -0,0 +1,281 @@
.. meta::
:description: RCCL is a stand-alone library that provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs
:keywords: RCCL, ROCm, library, API
.. _using-nccl:
*********************
Using NCCL Net Plugin
*********************
NCCL provides a way to use external plugins to let NCCL run on many network types. This
topic describes the NCCL Net plugin API and how to implement a network plugin for NCCL.
Plugins implement the NCCL network API, and decouple NCCL binary builds which are built against a
particular version of the GPU stack (i.e. CUDA) from the network code which is built against a
particular version of the networking stack. That way, you can easily integrate any CUDA version
with any network stack version.
NCCL network plugins come as a shared library called ``libnccl-net.so``. That shared library
contains one or more implementations of the NCCL NET API, in the form of versioned structs,
filled with pointers to all required functions.
Plugin architecture
===================
When NCCL is initialized, it will look for a ``libnccl-net.so`` library and dynamically load it,
then look for symbols inside the library.
The ``NCCL_NET_PLUGIN`` environment variable allows multiple plugins to coexist. If set, NCCL
will look for a library with a name of ``libnccl-net-${NCCL_NET_PLUGIN}.so``. It is therefore
advised to name the library following that pattern, with a symlink pointing ``libnccl-net.so``
to ``libnccl-net-${NCCL_NET_PLUGIN}.so``. That way, if there are multiple plugins in the path,
setting ``NCCL_NET_PLUGIN`` will allow users to select the right plugin.
Struct versioning
-----------------
Once a library is found, NCCL will look for a symbol named ``ncclNet_vX``, with ``X`` increasing
over time. The versioning ensures that the plugin and the NCCL core are compatible.
Plugins are encouraged to provide multiple of those symbols, implementing multiple versions
of the NCCL NET API, so that the same plugin can be compiled and support a wide range of NCCL
versions.
Conversely, and to ease transition, NCCL can choose to support different plugin versions, looking
for the latest ncclNet struct version, but also looking for older ones so that older plugins
would still work.
In-network collective operations (``collNet``)
----------------------------------------------
Additionally to the ``ncclNet`` structure, network plugins can provide a ``collNet`` structure which
implements in-network collective operations, if supported. That can be used by the NCCL ``collNet``
algorithm to accelerate inter-node reductions in allReduce.
The ``collNet`` struct is a different, optional struct provided by the network plugin, but its
versioning is tied to the ncclNet struct and many functions are common between the two to
ease the implementation.
Headers management
------------------
To help users build plugins effortlessly, plugins should copy the ``ncclNet_vX`` definitions
they support to their internal includes. An example is shown in ``ext-net/example/`` where we keep
all headers in the ``nccl/`` directory and provide thin layers to implement old versions on top
of newer ones.
The ``nccl/`` directory is populated with ``net_vX.h`` files extracting all relevant definitions
from old API versions. It also provides error codes in ``err.h``.
API (v6)
=========
Below is the main ``ncclNet_v6`` struct. Each function is explained in later sections.
.. code:: shell
typedef struct {
// Name of the network (mainly for logs)
const char* name;
// Initialize the network.
ncclResult_t (*init)(ncclDebugLogger_t logFunction);
// Return the number of adapters.
ncclResult_t (*devices)(int* ndev);
// Get various device properties.
ncclResult_t (*getProperties)(int dev, ncclNetProperties_v6_t* props);
// Create a receiving object and provide a handle to connect to it. The
// handle can be up to NCCL_NET_HANDLE_MAXSIZE bytes and will be exchanged
// between ranks to create a connection.
ncclResult_t (*listen)(int dev, void* handle, void** listenComm);
// Connect to a handle and return a sending comm object for that peer.
// This call must not block for the connection to be established, and instead
// should return successfully with sendComm == NULL with the expectation that
// it will be called again until sendComm != NULL.
ncclResult_t (*connect)(int dev, void* handle, void** sendComm);
// Finalize connection establishment after remote peer has called connect.
// This call must not block for the connection to be established, and instead
// should return successfully with recvComm == NULL with the expectation that
// it will be called again until recvComm != NULL.
ncclResult_t (*accept)(void* listenComm, void** recvComm);
// Register/Deregister memory. Comm can be either a sendComm or a recvComm.
// Type is either NCCL_PTR_HOST or NCCL_PTR_CUDA.
ncclResult_t (*regMr)(void* comm, void* data, int size, int type, void** mhandle);
/* DMA-BUF support */
ncclResult_t (*regMrDmaBuf)(void* comm, void* data, size_t size, int type, uint64_t offset, int fd, void** mhandle);
ncclResult_t (*deregMr)(void* comm, void* mhandle);
// Asynchronous send to a peer.
// May return request == NULL if the call cannot be performed (or would block)
ncclResult_t (*isend)(void* sendComm, void* data, int size, int tag, void* mhandle, void** request);
// Asynchronous recv from a peer.
// May return request == NULL if the call cannot be performed (or would block)
ncclResult_t (*irecv)(void* recvComm, int n, void** data, int* sizes, int* tags, void** mhandles, void** request);
// Perform a flush/fence to make sure all data received with NCCL_PTR_CUDA is
// visible to the GPU
ncclResult_t (*iflush)(void* recvComm, int n, void** data, int* sizes, void** mhandles, void** request);
// Test whether a request is complete. If size is not NULL, it returns the
// number of bytes sent/received.
ncclResult_t (*test)(void* request, int* done, int* sizes);
// Close and free send/recv comm objects
ncclResult_t (*closeSend)(void* sendComm);
ncclResult_t (*closeRecv)(void* recvComm);
ncclResult_t (*closeListen)(void* listenComm);
} ncclNet_v6_t;
Error codes
-----------
All plugins functions use NCCL error codes as return value. `ncclSuccess` should be returned upon
success.
Otherwise, plugins can return one of the following:
* ``ncclSystemError`` is the most common error for network plugins, when a call to the linux kernel or a system library fails. This typically includes all network/hardware errors.
* ``ncclInternalError`` is returned when the NCCL core code is using the network plugin in an incorrect way, for example allocating more requests than it should, or passing an invalid argument to calls.
* ``ncclInvalidUsage`` should be returned when the error is most likely a user error. This can include misconfiguration, but also sizes mismatch.
* ``ncclInvalidArgument`` should usually not be used by plugins since arguments should be checked by the NCCL core layer.
* ``ncclUnhandledCudaError`` is returned when an error comes from CUDA. Since network plugins should not need to rely on CUDA, this should not be common.
Operation overview
------------------
NCCL will call the ``init`` function first, then query the number of network devices with the
``devices`` function, getting each network device properties with ``getProperties``.
To establish a connection between two network devices, NCCL will first call ``listen`` on the
receiving side, pass the returned handle to the sender side of the connection, and call ``connect``
with that handle. Finally, `accept` will be called on the receiving side to finalize the connection
establishment.
Once the connection is established, communication will be done using the functions ``isend``,
``irecv`` and ``test``. Prior to calling ``isend`` or ``irecv``, NCCL will call the ``regMr`` function on
all buffers to allow RDMA NICs to prepare buffers. ``deregMr`` will be used to unregister buffers.
In certain conditions, ``iflush`` will be called after a receive calls completes to allow the network
plugin to flush data and ensure the GPU will observe the newly written data.
To close the connections NCCL will call ``closeListen`` to close the object returned by ``listen``,
``closeSend`` to close the object returned by ``connect`` and ``closeRecv`` to close the object returned
by ``accept``.
API Functions
-------------
Initialization
^^^^^^^^^^^^^^
* ``name`` - The ``name`` field should point to a character string with the name of the network plugin. This will be used for all logging, especially when ``NCCL_DEBUG=INFO`` is set.
.. note::
Setting ``NCCL_NET=<plugin name>`` will ensure a specific network implementation is used, with
a matching ``name``. This is not to be confused with ``NCCL_NET_PLUGIN`` which defines a suffix to the
``libnccl-net.so`` library name to load.
* ``init`` - As soon as NCCL finds the plugin and the correct ncclNet symbol, it will call the ``init`` function. This will allow the plugin to discover network devices and make sure they are usable. If the ``init`` function does not return ``ncclSuccess``, then NCCL will not use the plugin and fall back on internal ones.
To allow the plugin logs to integrate into the NCCL logs seemlessly, NCCL provides a logging function to ``init``. This function is typically used to allow for ``INFO`` and ``WARN`` macros within the plugin code adding the following definitions:
.. code:: shell
#define WARN(...) logFunction(NCCL_LOG_WARN, NCCL_ALL, __FILE__, __LINE__, __VA_ARGS__)
#define INFO(FLAGS, ...) logFunction(NCCL_LOG_INFO, (FLAGS), __func__, __LINE__, __VA_ARGS__)
* ``devices`` - Once the plugin is initialized, NCCL will query the number of devices available. It should not be zero, otherwise NCCL initialization will fail. If no device is present or usable, the ``init`` function should not return ``ncclSuccess``.
* ``getProperties`` - Right after getting the number of devices, NCCL will query properties for each available network device. These properties are critical when multiple adapters are present to ensure NCCL uses each adapter in the most optimized way.
The ``name`` is only used for logging.
The ``pciPath`` is the base for all topology detection and should point to the PCI device directory
in ``/sys``. This is typically the directory pointed by ``/sys/class/net/eth0/device`` or
``/sys/class/infiniband/mlx5_0/device``. If the network interface is virtual, then ``pciPath`` should
be ``NULL``.
The ``guid`` field is used to determine when network adapters are connected to multiple PCI
endpoints. For normal cases, it can be set to the device number. If multiple network devices have
the same guid, then NCCL will consider the are sharing the same network port to the fabric, hence
it will not use the port multiple times.
The ``ptrSupport`` field indicates whether or not CUDA pointers are supported. If so, it should be
set to ``NCCL_PTR_HOST``|``NCCL_PTR_CUDA``, otherwise it should be set to ``NCCL_PTR_HOST``. If the plugin
supports ``dmabuf``, it should set ``ptrSupport`` to ``NCCL_PTR_HOST``|``NCCL_PTR_CUDA``|``NCCL_PTR_DMABUF`` and
provide a ``regMrDmaBuf`` function.
The ``speed`` field indicates the speed of the network port in Mbps (10^6 bits per second). This is important to ensure proper optimization of flows within the node.
The ``port`` field indicates the port number. This is important again for topology detection and flow optimization within the node when a NIC with a single PCI connection is connected to the fabric with multiple ports.
The ``latency`` field indicates the network latency in microseconds. This can be useful to improve the NCCL tuning and make sure NCCL switches from tree to ring at the right size.
The ``maxComms`` field indicates the maximum number of connections we can create.
The ``maxRecvs`` field indicates the maximum number for grouped receive operations (see grouped receive).
Connection establishment
^^^^^^^^^^^^^^^^^^^^^^^^
Connections are used in an unidirectional manner. There is therefore a sender side and a receiver
side.
* ``listen`` - To create a connection, NCCL will start by calling ``listen`` on the receiver side. This function takes a device number as input argument, and should return a local ``listenComm`` object, and a ``handle`` to pass to the other side, so that the sender side can connect to the receiver.
The ``handle`` is a buffer of size ``NCCL_NET_HANDLE_MAXSIZE`` and is provided by NCCL.
This call should never block, but contrary to ``connect`` and ``accept``, ``listenComm`` should never be ``NULL`` if the call succeeds.
* ``connect`` - NCCL will use its bootstrap infrastructure to provide the ``handle`` to the sender side, then call ``connect`` on the sender side on a given device index ``dev``, providing the ``handle``. ``connect`` should not block either, and instead set ``sendComm`` to ``NULL`` and return ``ncclSuccess``. In that case, NCCL will call ``accept`` again until it succeeds.
* ``accept`` - To finalize the connection, the receiver side will call ``accept`` on the ``listenComm`` returned by the ``listen`` call previously. If the sender did not connect yet, ``accept`` should not block. It should return ``ncclSuccess``, setting ``recvComm`` to ``NULL``. NCCL will call ``accept`` again until it succeeds.
* ``closeListen``/``closeSend``/``closeRecv`` - Once a ``listenComm``/``sendComm``/``recvComm`` is no longer needed, NCCL will call ``closeListen``/``closeSend``/``closeRecv`` to free the associated resources.
Communication
^^^^^^^^^^^^^
Communication is done using asynchronous send and receive operations: ``isend``, ``irecv`` and ``test``.
To support RDMA capabilities, buffer registration and flush functions are provided.
To keep track of asynchronous send, receive and flush operations, requests are returned to NCCL,
then queried with ``test``. Each ``sendComm`` or ``recvComm`` must be able to handle
``NCCL_NET_MAX_REQUESTS`` requests in parallel.
.. note::
That value should be multiplied by the multi-receive capability of the plugin for the sender
side, so that we can effectively have ``NCCL_NET_MAX_REQUESTS`` multi-receive operations happening
in parallel. So, if we have a `maxRecvs`value of 8 and ``NCCL_NET_MAX_REQUESTS`` is 8, then each
``sendComm`` must be able to handle up to 8x8=64 concurrent ``isend`` operations.
* ``regMr`` - Prior to sending or receiving data, NCCL will call ``regMr`` with any buffers later used for communication. It will provide a ``sendComm`` or ``recvComm`` as ``comm`` argument, then the buffer pointer ``data``, ``size``, and ``type`` being either ``NCCL_PTR_HOST``, or ``NCCL_PTR_CUDA`` if the network supports CUDA pointers.
The network plugin can use the output argument `mhandle` to keep any reference to that memory registration, as this ``mhandle`` will be passed back for all ``isend``, ``irecv``, ``iflush`` and ``deregMr`` calls.
* ``regMrDmaBuf`` - If the plugin has set the ``NCCL_PTR_DMABUF`` property in ``ptrSupport``, NCCL will use ``regMrDmaBuf`` instead of ``regMr``. If the property was not set, ``regMrDmaBuf`` can be set to ``NULL``.
* ``deregMr`` - When buffers will no longer be used for communication, NCCL will call ``deregMr`` to let the plugin free resources. This function is used to deregister handles returned by both ``regMr`` and ``regMrDmaBuf``.
* ``isend`` - Data will be sent through the connection using ``isend``, passing the ``sendComm`` previously created by ``connect``, and the buffer described by ``data``, ``size``, and ``mhandle``. A ``tag`` must be used if the network supports multi-receive operations (see ``irecv``) to distinguish between different sends matching the same multi-receive. Otherwise it can be set to 0.
The ``isend`` operation returns a handle in the ``request`` argument for further calls to ``test``. If the ``isend`` operation cannot be initiated, ``request`` can be set to ``NULL`` and NCCL will call ``isend`` again later.
* ``irecv`` - To receive data, NCCL will call ``irecv`` with the ``recvComm`` returned by ``accept``. The argument ``n`` will allow NCCL to perform a multi-receive, to allow grouping of multiple sends through a single network connection. Each buffer will be described by the ``data``, ``sizes``, and ``mhandles`` arrays. ``tags`` will specify a tag for each receive so that each of the ``n`` independent ``isend`` operations is received into the right buffer.
If all receive operations can be initiated, ``irecv`` will return a handle in the ``request`` pointer, otherwise it will set it to ``NULL``. In the case of multi-receive, all ``n`` receive operations are handled by a single request handle.
The sizes provided to ``irecv`` can (and will) be larger than the size of the ``isend`` operation. However, if the receive size is smaller than the send size this is an error.
.. note::
For a given connection, send/receive operations should always match in the order they were
posted. Tags provided for receive operations are only used to assign a given send operation to one
of the buffers of the first (multi-)receive in the queue, not to allow for out-of-order tag
matching on any receive operation posted.
* ``test`` - After an ``isend`` or ``irecv`` operation is initiated, NCCL will call `test` on the request handles until they complete. When that happens, ``done`` will be set to 1 and ``sizes`` will be set to the real size sent or received, the latter being potentially lower than the size passed to ``irecv``.
In the case of a multi-receive, all receives will be considered as done as a single operation (the goal being to allow aggregation), hence they share a single request and a single ``done`` status. However, they can have different sizes, so when ``done`` is non-zero, the ``sizes`` array should contain the ``n`` sizes corresponding to the buffers passed to ``irecv``.
Once ``test`` returns 1 in ``done``, the request handle can be freed, meaning that NCCL will never call ``test`` again on that request (until it is reallocated by another call to ``isend`` or ``irecv``).
* ``iflush`` - After a receive operation completes, if the operation was targeting GPU memory and received a non-zero number of bytes, NCCL will call ``iflush`` to let the network flush any buffer and ensure the GPU can read it right after without seeing stale data. This flush operation is decoupled from the ``test`` code to improve latency of ``LL*`` protocols, as those are capable of determining when data is valid or not.
``iflush`` returns a request which needs to be queried with ``test`` until it completes.
docs/index.rst
+16 -8
Melihat File
@@ -4,24 +4,32 @@
.. _index:
===========================
******************
RCCL documentation
===========================
******************
RCCL (pronounced “Rickel”) is a stand-alone library that provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs.
It implements routines such as ``all-reduce``, ``all-gather``, ``reduce``, ``broadcast``, ``reduce-scatter``, ``gather``, ``scatter``, ``all-to-allv``, and ``all-to-all`` as well as direct point-to-point (GPU-to-GPU) send and receive operations.
The provided collective communication routines are implemented using Ring and Tree algorithms. They are optimized to achieve high bandwidth and low latency by leveraging topology awareness, high-speed interconnects, and RDMA based collectives.
The ROCm Communication Collectives Library (RCCL) is a stand-alone library that provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs.
It implements routines such as ``all-reduce``, ``all-gather``, ``reduce``, ``broadcast``, ``reduce-scatter``, ``gather``, ``scatter``, ``all-to-allv``, and ``all-to-all`` as well as direct point-to-point (GPU-to-GPU) send and receive operations. It has been optimized to achieve high bandwidth on platforms using PCIe, xGMI as well as networking using InfiniBand Verbs or TCP/IP sockets. RCCL supports an arbitrary number of GPUs installed in a single node or multiple nodes, and can be used in either single- or multi-process (e.g., MPI) applications.
RCCL utilizes PCIe and xGMI high-speed interconnects for intra-node communication as well as InfiniBand, RoCE, and TCP/IP for inter-node communication.
It supports an arbitrary number of GPUs installed in a single-node or multi-node platform and can be easily integrated into single- or multi-process (e.g., MPI) applications.
The collective operations are implemented using Ring and Tree algorithms, and have been optimized for throughput and latency by leveraging topology awareness, high-speed interconnects, and RDMA based collectives. For best performance, small operations can be either batched into larger operations or aggregated through the API.
You can access RCCL code on our `GitHub repository <https://github.com/ROCm/rccl>`_.
RCCL utilizes PCIe and xGMI high-speed interconnects for intra-node communication as well as InfiniBand, RoCE, and TCP/IP for inter-node communication. It supports an arbitrary number of GPUs installed in a single-node or multi-node platform and can be easily integrated into single- or multi-process (e.g., MPI) applications.
You can access RCCL code on the `RCCL GitHub repository <https://github.com/ROCm/rccl>`_.
The documentation is structured as follows:
.. grid:: 2
:gutter: 3
.. grid-item-card:: Installation
* :ref:`install`
.. grid-item-card:: How to
* :ref:`using-nccl`
.. grid-item-card:: API reference
* :ref:`Library specification<library-specification>`
docs/install/installation.rst
+166
Melihat File
@@ -0,0 +1,166 @@
.. meta::
:description: RCCL is a stand-alone library that provides multi-GPU and multi-node collective communication primitives optimized for AMD GPUs
:keywords: RCCL, ROCm, library, API
.. _install:
***************
Installing RCCL
***************
Requirements
============
1. ROCm supported GPUs
2. ROCm stack installed on the system (HIP runtime & HIP-Clang)
Quickstart RCCL Build
=====================
RCCL directly depends on HIP runtime plus the HIP-Clang compiler, which are part of the ROCm software stack.
For ROCm installation instructions, see https://github.com/ROCm/ROCm.
The root of this repository has a helper script ``install.sh`` to build and install RCCL with a single command. It hard-codes configurations that can be specified through invoking cmake directly, but it's a great way to get started quickly and can serve as an example of how to build/install RCCL.
To build the library using the install script:
----------------------------------------------
.. code-block:: shell
./install.sh
For more info on build options/flags when using the install script, use the following:
.. code-block:: shell
./install.sh --help
RCCL build & installation helper script options:
.. code-block:: shell
--address-sanitizer Build with address sanitizer enabled
-d|--dependencies Install RCCL depdencencies
--debug Build debug library
--enable_backtrace Build with custom backtrace support
--disable-colltrace Build without collective trace
--disable-msccl-kernel Build without MSCCL kernels
--disable-mscclpp Build without MSCCL++ support
-f|--fast Quick-build RCCL (local gpu arch only, no backtrace, and collective trace support)
-h|--help Prints this help message
-i|--install Install RCCL library (see --prefix argument below)
-j|--jobs Specify how many parallel compilation jobs to run ($nproc by default)
-l|--local_gpu_only Only compile for local GPU architecture
--amdgpu_targets Only compile for specified GPU architecture(s). For multiple targets, seperate by ';' (builds for all supported GPU architectures by default)
--no_clean Don't delete files if they already exist
--npkit-enable Compile with npkit enabled
--openmp-test-enable Enable OpenMP in rccl unit tests
--roctx-enable Compile with roctx enabled (example usage: rocprof --roctx-trace ./rccl-program)
-p|--package_build Build RCCL package
--prefix Specify custom directory to install RCCL to (default: `/opt/rocm`)
--rm-legacy-include-dir Remove legacy include dir Packaging added for file/folder reorg backward compatibility
--run_tests_all Run all rccl unit tests (must be built already)
-r|--run_tests_quick Run small subset of rccl unit tests (must be built already)
--static Build RCCL as a static library instead of shared library
-t|--tests_build Build rccl unit tests, but do not run
--time-trace Plot the build time of RCCL (requires `ninja-build` package installed on the system)
--verbose Show compile commands
.. tip::
By default, RCCL builds for all GPU targets defined in ``DEFAULT_GPUS`` in `CMakeLists.txt <https://github.com/ROCm/rccl/blob/develop/CMakeLists.txt>`_. To target specific GPU(s), and potentially reduce build time, use ``--amdgpu_targets`` as a ``;`` separated string listing GPU(s) to target.
Manual build
============
To build the library using CMake:
---------------------------------
.. code-block:: shell
$ git clone https://github.com/ROCm/rccl.git
$ cd rccl
$ mkdir build
$ cd build
$ cmake ..
$ make -j 16 # Or some other suitable number of parallel jobs
You may substitute an installation path of your own choosing by passing ``CMAKE_INSTALL_PREFIX``. For example:
.. code-block:: shell
$ cmake -DCMAKE_INSTALL_PREFIX=$PWD/rccl-install ..
.. note::
Ensure rocm-cmake is installed, ``apt install rocm-cmake``.
To build the RCCL package and install package:
----------------------------------------------
Assuming you have already cloned this repository and built the library as shown in the previous section:
.. code-block:: shell
$ cd rccl/build
$ make package
$ sudo dpkg -i *.deb
RCCL package install requires sudo/root access because it creates a directory called "rccl" under ``/opt/rocm/``. This is an optional step and RCCL can be used directly by including the path containing ``librccl.so``.
Enabling peer-to-peer transport
===============================
In order to enable peer-to-peer access on machines with PCIe-connected GPUs, the HSA environment variable ``HSA_FORCE_FINE_GRAIN_PCIE=1`` is required to be set, on top of requiring GPUs that support peer-to-peer access and proper large BAR addressing support.
Testing RCCL
============
There are rccl unit tests implemented with the Googletest framework in RCCL. The rccl unit tests require Googletest 1.10 or higher to build and execute properly (installed with the ``-d`` option to ``install.sh``).
To invoke the rccl unit tests, go to the build folder, then the test subfolder, and execute the appropriate rccl unit test executable(s).
rccl unit test names are now of the format:
.. code-block:: shell
CollectiveCall.[Type of test]
Filtering of rccl unit tests should be done with environment variable and by passing the ``--gtest_filter`` command line flag:
.. code-block:: shell
UT_DATATYPES=ncclBfloat16 UT_REDOPS=prod ./rccl-UnitTests --gtest_filter="AllReduce.C*"
This will run only ``AllReduce`` correctness tests with float16 datatype. A list of available filtering environment variables appears at the top of every run. See https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests for more information on how to form more advanced filters.
There are also other performance and error-checking tests for RCCL. These are maintained separately at https://github.com/ROCm/rccl-tests.
.. note::
See the `rccl-tests/README <https://github.com/ROCm/rccl-tests/blob/develop/README.md>`_ for more information on how to build and run those tests.
NPKit
=====
RCCL integrates `NPKit <https://github.com/microsoft/npkit>`_, a profiler framework that enables collecting fine-grained trace events in RCCL components, especially in giant collective GPU kernels.
Please check `NPKit sample workflow for RCCL <https://github.com/microsoft/NPKit/tree/main/rccl_samples>`_ as a fully automated usage example. It also provides good templates for the following manual instructions.
To manually build RCCL with NPKit enabled, pass ``-DNPKIT_FLAGS="-DENABLE_NPKIT -DENABLE_NPKIT_...(other NPKit compile-time switches)"`` with ``cmake`` command. All NPKit compile-time switches are declared in the RCCL code base as macros with prefix ``ENABLE_NPKIT_``, and they control which information will be collected. Also note that currently NPKit only supports collecting non-overlapped events on GPU, and ``-DNPKIT_FLAGS`` should follow this rule.
To manually run RCCL with NPKit enabled, environment variable ``NPKIT_DUMP_DIR`` needs to be set as the NPKit event dump directory. Also note that currently NPKit only supports 1 GPU per process.
To manually analyze NPKit dump results, please leverage `npkit_trace_generator.py <https://github.com/microsoft/NPKit/blob/main/rccl_samples/npkit_trace_generator.py>`_.
MSCCL/MSCCL++
=============
RCCL integrates `MSCCL <https://github.com/microsoft/msccl>`_ and `MSCCL++ <https://github.com/microsoft/mscclpp>`_ to leverage the highly efficient GPU-GPU communication primitives for collective operations. Thanks to Microsoft Corporation for collaborating with us in this project.
MSCCL uses XMLs for different collective algorithms on different architectures. RCCL collectives can leverage those algorithms once the corresponding XML has been provided by the user. The XML files contain the sequence of send-recv and reduction operations to be executed by the kernel. On MI300X, MSCCL is enabled by default. On other platforms, the users may have to enable this by setting ``RCCL_MSCCL_FORCE_ENABLE=1``.
On the other hand, RCCL allreduce and allgather collectives can leverage the efficient MSCCL++ communication kernels for certain message sizes. MSCCL++ support is available whenever MSCCL support is available. Users need to set the RCCL environment variable ``RCCL_ENABLE_MSCCLPP=1`` to run RCCL workload with MSCCL++ support. It is also possible to set the message size threshold for using MSCCL++ by using the environment variable ``RCCL_MSCCLPP_THRESHOLD``. Once ``RCCL_MSCCLPP_THRESHOLD`` (the default value is 1MB) is set, RCCL will invoke MSCCL++ kernels for all message sizes less than or equal to the specified threshold.
Improving performance on MI300 when using less than 8 GPUs
==========================================================
On a system with 8\*MI300X GPUs, each pair of GPUs are connected with dedicated XGMI links in a fully-connected topology. So, for collective operations, one can achieve good performance when all 8 GPUs (and all XGMI links) are used. When using less than 8 GPUs, one can only achieve a fraction of the potential bandwidth on the system.
But, if your workload warrants using less than 8 MI300 GPUs on a system, you can set the run-time variable `NCCL_MIN_NCHANNELS` to increase the number of channels.
For example: ``export NCCL_MIN_NCHANNELS=32``
Increasing the number of channels can be beneficial to performance, but it also increases GPU utilization for collective operations.
Additionally, we have pre-defined higher number of channels when using only 2 GPUs or 4 GPUs on a 8\*MI300 system. Here, RCCL will use **32 channels** for the 2 MI300 GPUs scenario and **24 channels** for the 4 MI300 GPUs scenario.
docs/sphinx/_toc.yml.in
+8 -1
Melihat File
@@ -1,6 +1,14 @@
root: index
subtrees:
- caption: Installation
entries:
- file: install/installation
- caption: How to
entries:
- file: how-to/using-nccl
- caption: API reference
entries:
- file: api-reference/library-specification
@@ -11,4 +19,3 @@ subtrees:
entries:
- file: license
- file: attributions