The cudawrappers library is a C++ wrapper for the Nvidia C libraries such as the CUDA driver, NVRTC, and cuFFT.
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](https://www.nvidia.com/en-in/geforce/products/10series/architecture/) or newer| | AMD GPU | RDNA2 or newer, CDNA2 or newer | ## Usage CMake is used to build cudawrappers. To build the library, run: ```shell git clone https://github.com/nlesc-recruit/cudawrappers cd cudawrappers cmake -S . -B build make -C build ``` This creates a `build` directory. Since cudawrappers is header-only, no library objects will be built. For more details on the building requirements and testing, see the [developer documentation](README.dev.md). To install cudawrappers to a specific location (e.g., ~/.local), use: ```shell cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local -S . -B build make -C build make -C build install ``` You can optionally select what cudawrappers components should be enabled by specifying the `CUDAWRAPPERS_COMPONENTS` option. To build all components, specify: `-DCUDAWRAPPERS_COMPONENTS=all`. By default, only the `cu` and `nvrtc` components are enabled. The other components include: `cufft`, `nvml` (CUDA only) and `nvtx`. ### Enabling HIP Support To enable HIP: 1. Add the following code to your project's `CMakeLists.txt` file: ```cmake enable_language(HIP) set(CUDAWRAPPERS_BACKEND "HIP") ``` Alternatively, use the `-DCUDAWRAPPERS_BACKEND=HIP` argument when running CMake. 2. Ensure that every target your project builds is 'hipfied'. This is done by marking relevant source files as 'HIP' compatible: ```cmake set_source_files_properties(source.cpp PROPERTIES LANGUAGE HIP) ``` 3. Optionally, use `#ifdef (__HIP__)` directives in your source code to enable/disable certain sections for HIP. 4. **Build**: ensure that the `hipcc` compiler is selected. This can be done via the command line: ```shell CXX=hipcc cmake -B build ``` **Note**: When building for both NVIDIA and AMD HIP, using **seperate** build folders (e.g, `build_nvidia` and `build_amd`) is encouraged. Additionally, please note that contrary to CUDA, the HIP backend does not implement GPU contexts. For library interoperability, it provides a (non-functioning) mock implementation. Still, the usage of `cu::Context` is strongly discouraged, and has been marked deprecated since cudawrappers version `0.9.0`. Support will likely be dropped in a future release.