cudawrappers

This library is a C++ wrapper for the Nvidia C libraries (e.g. CUDA driver, nvrtc, cuFFT etc.). The main purposes are:

1. easier resource management, leading to lower risk of programming errors;
2. better fault handling (through exceptions);
3. more compact user code.

This library also supports AMD GPUs through the HIP: C++ Heterogeneous-Compute Interface for Portability.

Originally, the API enforced RAII to even further reduce the risk of faulty code, but enforcing RAII and compatibility with (unmanaged) objects obtained outside this API are mutually exclusive.

Requirements

Software	Minimum version
CUDA	10.0 or later
ROCM	6.1.0 or later
CMake	3.17 or later
gcc	9.3 or later
OS	Linux distro (amd64)

Hardware	Type
NVIDIA GPU
Pascal
or newer
AMD GPU	RDNA2 or newer, CDNA2 or newer

Usage

We use CMake in this project, so you can clone and build this library with the following steps:

git clone https://github.com/nlesc-recruit/cudawrappers
cd cudawrappers
cmake -S . -B build
make -C build

This command will create a build directory. Cudawrappers is header only, so no library objects are being built. For more details on the building requirements and on testing, check the developer documentation.

To install to ~/.local, use

git clone https://github.com/nlesc-recruit/cudawrappers
cd cudawrappers
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local -S . -B build
make -C build
make -C build install

Usage (HIP)

To enable HIP, make sure to build cudawrappers with -DCUDAWRAPPERS_BACKEND=HIP, or when using FetchContent, use set(CUDAWRAPPERS_BACKEND "HIP"). In your project's CMakeLists.txt, add enable_language(HIP). Furthermore, every target that includes a cudawrappers header file needs to be 'hipified', to this end, add set_source_files_properties(source.cpp PROPERTIES LANGUAGE HIP) for every relevant source.cpp file. Some CUDA specific features may not be available or not work on non-NVIDIA GPUs, in those cases use #ifdef(__HIP__) guards to patch your code wherever this is needed.

Usage examples

You can include the cudawrappers library in your own projects in various ways. We have created a few repositories with example setups to get you started:

1. cudawrappers-usage-example-git-submodules Example project that uses the cudawrappers library as a dependency by using git submodules on its source tree.
2. cudawrappers-usage-example-locally-installed Example project that uses the cudawrappers library as a dependency by having it locally installed.
3. cudawrappers-usage-example-cmake-pull Example project that uses the cudawrappers library as a dependency by having cmake pull it in from github.

Used by

This section aims to provide an overview of projects that use this repo's library (or something very similar), e.g. through git submodules or by including copies of this library in their source tree:

1. https://git.astron.nl/RD/dedisp/
2. https://git.astron.nl/RD/idg
3. https://git.astron.nl/RD/tensor-core-correlator

Alternatives

This section provides an overview of similar tools in this space, and how they are different.

cuda-api-wrappers

• Aims to provide wrappers for the CUDA runtime API
• Development has slowed a bit recently
• Has 1 or 2 main developers
• Has gained quite a bit of attention (e.g. 440 stars; 57 forks)

The project is planning to support more of the Driver API (for fine-grained control of CUDA devices) and NVRTC API (for runtime compilation of kernels); there is a release candidate (v0.5.0-rc1). It doesn't provide support for cuFFT and cuBLAS though.

cuda-wrapper

• Aims to provide a C++ wrapper for the CUDA Driver and Runtime APIs

CudaPlusPlus

• Aims to provide a C++ wrapper for the CUDA Driver API
• Project appears inactive

Contributing

See CONTRIBUTING.md for a guide on how to contribute.

Developer documentation

See README.dev.md for documentation on setting up your development environment.