Repository navigation
RFC: Expose versioned symbols/APIs to cuda-bindings #1228
Description
Doing a long overdue brain-dump here to capture things discussed in past team meetings...
"We're doing the hard work for API / ABI compatibility already and not taking advantage of it." -- @kkraus14
Today, there is one minor difference in calling a CUDA (driver/runtime) API in C/C++ versus in Python via cuda-bindings. In C/C++, for example, most, if not all, of the CUDA APIs are typedef'd to a versioned symbol, for example,
- in CUDA 13,
cuCtxCreateis mapped tocuCtxCreate_v4 - in CUDA 12,
cuCtxCreateis mapped tocuCtxCreate_v2
This is the foundation for CUDA to stay "forever backward compatible" (at the ABI level): The underlying driver is guaranteed to continue offering the older symbols (ex: cuCtxCreate_v2, cuCtxCreate_v3, ...) even if the declarations are removed from the headers of a future major release.
It is not (yet) the case in Python. While cuda-bindings captures all of the symbol redirections so that the mapping is preserved correctly in each cuda-bindings major versions, we do not expose the versioned symbols so that Python programs can continue accessing them from within Python. In other words, unlike a C/C++ executable a Python project cannot call cuCtxCreate_v2 explicitly and expect to work with CUDA drivers of different major versions.
We would like to update the codegen to keep a history of all past symbols, and ensure
- all versioned APIs are exposed to
cuda.bindings.{driver, runtime} - all un-versioned APIs continue to be mapped correctly to the underlying versioned symbols, based on the CUDA major versions
Once this is done in cuda-bindings, in the long term we could re-work cuda-core to always use the versioned APIs, and have a much smoother transition when a new CUDA major release comes out
Activity
mdboom commentedon Jun 23, 2026
In the recent work to move nvrtc and driver to cybind, the status quo was maintained. It should be much easier now to update to include all of the versions (and adding APIs is not an ABI breakage, so we can do it at any time).
I plan to work on this after
runtimeis brought in line withnvrtcanddriver.kkraus14 commentedon Jun 23, 2026
In addition to exposing the symbols as Python APIs, ideally we'd have a reasonably friendly way for someone to get from typical API --> versioned forever stable API. I.E. if I want to use
cuCtxCreate, how do I get to the most appropriate versioned API?Additionally,
cuda.bindingsis currently a single package that bundles driver, runtime, nvrtc, nvjitlink, etc. Everything except for the driver doesn't have forever ABI compatibility as far as I know and has both ABI and API breaking changes at major versions. This leaves some open questions:cuda.bindingsversion, is there still value in these versionedcuda.bindings.driverAPIs? Would we need to commit to no breaking changes incuda.bindings.driverin general moving forward?cuda.bindings.*modules currently usecuda.bindings.drivertypes at runtime. Would we ever want to support different major versions between differentcuda.bindingsmodules? I.E.cuda.bindings.driverv14.x andcuda.bindings.runtimev13.x. In C++ land,cuda.hfor the driver API comes from the CUDA toolkit and so it gets versioned alongside the other libraries, so this isn't really a thing in practice. Is there any use cases we want to support that say uses driver v14.x APIs / symbols with v13.x libraries?mdboom commentedon Aug 10, 2026
Moving to cuda.bindings.next. As in this comment, this needs to be after the cybind migration