Expand description
§ironaccelerator-cuda-sys
Clean-room, hand-written FFI for the CUDA Toolkit 13.2 library surface
used by IronAccelerator. This crate is a drop-in replacement for
cudarc’s sys layer — it depends on nothing from that project.
§Design
-
Fully dynamic loading. No
extern "C"link-time dependency on any CUDA library — everything is resolved lazily vialibloadingat first use. Consequence: the crate compiles on machines without CUDA installed, tests run, and CI stays green. -
One
Fnsstruct per library. Each loaded library exposes its function pointers as fields on a struct; aLazyLock<Result<&Fns, _>>amortises thedlopen+dlsymcost. Call sites look likedriver::fns()?.cuLaunchKernel(…). -
No opaque-pointer guesswork. Handle types are
#[repr(transparent)]newtypes over*mut ()with matchingSend/SyncandDefaultimpls. Result enums are#[repr(u32)]withSuccess = 0. -
Only what we use. Every function, every type in this crate is exercised by the safe layer. No dead FFI.
§Modules
| Module | Library | Purpose |
|---|---|---|
driver | libcuda / nvcuda | Core driver API (context, stream, module, kernel, memcpy, graph, event, peer access) |
nvrtc | libnvrtc | Runtime compilation of CUDA C++ → PTX |
cublas_lt | libcublasLt | Matmul descriptor-based API (FP8 GEMM) |
cublas | libcublas | Legacy BLAS (fallback) |
cudnn | libcudnn | Deep-learning primitives (MHA, conv) |
curand | libcurand | RNG |
cufft | libcufft | FFTs |
cusparse | libcusparse | Sparse BLAS (SpMM, SDDMM) |
cusolver | libcusolverDn | Dense linear solvers |
cutensor | libcutensor | N-dim tensor contraction |
nccl | libnccl | Collectives |
nvtx | libnvToolsExt | Profiler ranges/marks |
cupti | libcupti | Profiling/tracing activity records |
§Documentation policy
Items here mirror the CUDA C headers one-to-one: a Fns field is named
exactly after the C symbol it resolves, and enum variants and struct
fields carry the C names minus their prefix. They are deliberately not
documented item by item — NVIDIA’s reference for the same symbol is the
authority, and a paraphrase here could only drift from it. The safe crate
(ironaccelerator-cuda) is fully documented and enforces missing_docs.
Re-exports§
pub use loader::LoadError;pub use loader::LoaderResult;
Modules§
- cublas
- Legacy cuBLAS — used as a fallback path for BF16/F16/F32 GEMM when cuBLASLt’s heuristic returns nothing (tiny matrices, odd strides).
- cublas_
lt - cuBLASLt — descriptor-based matmul API. The path to FP8 GEMM.
- cudnn
- cuDNN — deep-learning primitives (MHA, convolution).
- cufft
- cuFFT — batched 1D/2D/3D FFTs.
- cupti
- CUPTI — CUDA Profiling Tools Interface.
- curand
- cuRAND — pseudo-random number generation.
- cusolver
- cuSOLVER Dense — LU/QR/SVD/Cholesky on dense matrices.
- cusparse
- cuSPARSE — sparse BLAS (SpMM, SDDMM, SpMV).
- cutensor
- cuTENSOR — N-dimensional tensor contractions, reductions, element-wise ops.
- driver
- CUDA Driver API (
libcuda.so/nvcuda.dll). Targets 13.2. - loader
- Dynamic library loader shared by every
*_sysmodule in this crate. - nccl
- NCCL — GPU collective communication (all-reduce, all-gather, broadcast).
- nvrtc
- NVRTC — runtime compilation of CUDA C++ to PTX.
- nvtx
- NVTX — profiler range/mark annotations.
Constants§
- CUDA_
VERSION - CUDA Toolkit version this binding targets. Packed
MMmm(13.20 = 1320).