RFC: Expose versioned symbols/APIs to `cuda-bindings`

[leofang]

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, cuCtxCreate is mapped to cuCtxCreate_v4
• in CUDA 12, cuCtxCreate is mapped to cuCtxCreate_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

[mdboom]

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 runtime is brought in line with nvrtc and driver.

[kkraus14]

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.bindings is 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:

• If we want to do breaking changes at a major cuda.bindings version, is there still value in these versioned cuda.bindings.driver APIs? Would we need to commit to no breaking changes in cuda.bindings.driver in general moving forward?
• Other cuda.bindings.* modules currently use cuda.bindings.driver types at runtime. Would we ever want to support different major versions between different cuda.bindings modules? I.E. cuda.bindings.driver v14.x and cuda.bindings.runtime v13.x. In C++ land, cuda.h for 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?