Skip to main content

Crate iron_cuda_sys

Crate iron_cuda_sys 

Source
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 via libloading at first use. Consequence: the crate compiles on machines without CUDA installed, tests run, and CI stays green.

  • One Fns struct per library. Each loaded library exposes its function pointers as fields on a struct; a LazyLock<Result<&Fns, _>> amortises the dlopen+dlsym cost. Call sites look like driver::fns()?.cuLaunchKernel(…).

  • No opaque-pointer guesswork. Handle types are #[repr(transparent)] newtypes over *mut () with matching Send/Sync and Default impls. Result enums are #[repr(u32)] with Success = 0.

  • Only what we use. Every function, every type in this crate is exercised by the safe layer. No dead FFI.

§Modules

ModuleLibraryPurpose
driverlibcuda / nvcudaCore driver API (context, stream, module, kernel, memcpy, graph, event, peer access)
nvrtclibnvrtcRuntime compilation of CUDA C++ → PTX
cublas_ltlibcublasLtMatmul descriptor-based API (FP8 GEMM)
cublaslibcublasLegacy BLAS (fallback)
cudnnlibcudnnDeep-learning primitives (MHA, conv)
curandlibcurandRNG
cufftlibcufftFFTs
cusparselibcusparseSparse BLAS (SpMM, SDDMM)
cusolverlibcusolverDnDense linear solvers
cutensorlibcutensorN-dim tensor contraction
nccllibncclCollectives
nvtxlibnvToolsExtProfiler ranges/marks
cuptilibcuptiProfiling/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 *_sys module 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).