Thin C++-flavored wrappers for the CUDA APIs:
Runtime, Driver, NVRTC, PTX compiler and NVTX
This is a header-only library of integrated wrappers around the core parts of NVIDIA's CUDA execution ecosystem:
It is intended for those who would otherwise use these APIs directly, to make working with them be more intuitive and consistent, making use of modern C++ language capabilities, programming idioms and best practices. In a nutshell - making CUDA API work more fun :-)
Also, and importantly - while the wrappers seem to be "high-level", more "abstract" code - they are nothing more than a modern-C++-aesthetic arrangement of NVIDIA's own APIs. The wrapper library does not force any abstractions above CUDA's own, nor conventions regarding where to place data, how and when to perform synchronization, etc.; you have the complete range of expression of the underlying APIs.
In contrast to the above, this library provides:
There is one noteworthy caveat: The wrapper API calls cannot make assumptions about previous or later code of yours, which means some of them require more calls to obtain the current context handle or push a(n existing) context, then pop it. While these calls are cheap, they are still non-trivial and can't be optimized away.
NVIDIA provides two main APIs for using CUDA: The Runtime API and the Driver API. These suffer from several deficiencies:
You may have noticed this list reads like the opposite of the key features, listed above: The idea is to make this library overcome and rectify all of these deficiencies as much as possible.
Detailed Doxygen-genereated documentation is available. It is mostly complete for the Runtime API wrappers, less so for the rest of the wrappers.
CUDA: v11.x or later recommended, v9.0 or later supported.
Remember that an NVIDIA driver compatible with your CUDA version also needs to be installed. Typically, this can be the one bundled in your CUDA distribution itself.
Other software:
An NVIDIA GPU supporting Unified Virtual Addressing (UVA), i.e. Fermi microarchitecture or later. With earlier GPUs, memory copying, and other functionality relying on automtically determining where a memory address is located, will fail.
Use involving CMake:
find_package(cuda_api_wrappers)
and make sure the library's install location is in CMake's package search path. This will let you use three targets within the cuda-api-wrappers::
namespace: runtime-and-driver
, nvrtc
and nvtx
.FetchContent
module to obtain the project source code and make it part of your own project's build, e.g.:include(FetchContent)
FetchContent_Declare(cuda-api-wrappers_library
GIT_REPOSITORY https://github.com/eyalroz/cuda-api-wrappers.git
GIT_TAG v12.34.56 # Replace this with a real available version
)
FetchContent_MakeAvailable(cuda-api-wrappers_library)
Use not involving CMake:
src/
subdirectory as one of your project's include directories. However, if you do this, it will be up to you to make sure and have the CUDA include directory in you include path as well, and to link against the CUDA driver, runtime API, nvrtc and/or nvtx libraries as appropriate.Finally, if you've started using the library in a publicly-available (FOSS or commercial) project, please consider emailing @eyalroz, or open an issue, to announce this.
Most, but not all, API calls in the Runtime, Driver, NVTX and NVRTC are covered by these wrappers. Specifically, the following are missing:
Support for textures, arrays and surfaces exists, but is partial: Not all relevant API functions are covered.
The Milestones indicates some features which aren't covered and are slated for future work. Since I am not currently working on anything graphics-related, there are no short-term plans to extend coverage to more graphics-related APIs; however - PRs are welcome.
We've all dreamed of being able to type in:
auto callback = [&foo] { std::cout << "Hello " << foo << " world!\n"; }
my_stream.enqueue.host_invokable(callback);
... and have that just work, right? Well, now it does!
On a slightly more serious note, though, let's demonstrate the principles listed above:
With this library, you would do cuda::memory::host::allocate()
instead of cudaMallocHost()
or cuMemAllocHost()
and cuda::device_t::memory::allocate()
instead of setting the current device and then cudaMalloc()
or cuMemAlloc()
. Note, though, that device_t::memory::allocate()
is not a freestanding function but a method of an internal class, so a call to it might be cuda::device::get(my_device_id).memory.allocate(my_size)
. The compiled version of this supposedly complicated construct will be nothing but the sequence of API calls: cuInit()
, cuDevicePrimaryCtxRetain()
, cuCtxPushCurrent()
, cuMemAlloc()
etc.
The expression
my_device.compute_capability() >= cuda::make_compute_capability(60)
is a valid comparison, true for all devices with a Pascal-or-later micro-architecture. This, despite the fact that struct cuda::compute_capability_t
is a POD type with two unsigned integer fields, not a scalar.
Instead of using
cudaError_t cudaEventCreateWithFlags(
cudaEvent_t* event,
unsigned int flags)
which requires you remember what you need to specify as flags and how, you create a cuda::event_t
proxy object, using the function:
cuda::event_t cuda::event::create(
cuda::device_t device,
bool uses_blocking_sync,
bool records_timing = cuda::event::do_record_timing,
bool interprocess = cuda::event::not_interprocess)
The default values here are enum : bool
's, which you can use yourself when creating non-default-parameter events - to make the call more easily readable than with true
or false
.
In lieu of a full-fledged user's guide, I'm providing several kinds of example programs; browsing their source you'll know most of what there is to know about the API wrappers. To build and run the examples (just as a sanity check), execute the following (in a Unix-style command shell):
cmake -S . -B build -DCAW_BUILD_EXAMPLES=ON .
cmake --build build/
find build/examples/bin -type f -executable -exec "{}" ";"
The two main kinds of example programs are:
The CUDA distribution contains sample programs demostrating various features and concepts. A few of these - which are not focused on device-side work - have been adapted to use the API wrappers - completely foregoing direct use of the CUDA Runtime API itself. You will find them in the modified CUDA samples example programs folder.
Gradually, an example program is being added for each one of the CUDA Runtime API Modules, in which the approach replacing use of those module API calls by use of the API wrappers is demonstrated. These per-module example programs can be found here.
Author: eyalroz
Source: https://github.com/eyalroz/cuda-api-wrappers
License: BSD-3-Clause license