iron_cuda_sys/lib.rs
1//! # `ironaccelerator-cuda-sys`
2//!
3//! Clean-room, hand-written FFI for the **CUDA Toolkit 13.2** library surface
4//! used by IronAccelerator. This crate is a drop-in replacement for
5//! `cudarc`'s sys layer — it depends on nothing from that project.
6//!
7//! ## Design
8//!
9//! - **Fully dynamic loading.** No `extern "C"` link-time dependency on any
10//! CUDA library — everything is resolved lazily via [`libloading`] at
11//! first use. Consequence: the crate compiles on machines without CUDA
12//! installed, tests run, and CI stays green.
13//!
14//! - **One `Fns` struct per library.** Each loaded library exposes its
15//! function pointers as fields on a struct; a `LazyLock<Result<&Fns, _>>`
16//! amortises the `dlopen`+`dlsym` cost. Call sites look like
17//! `driver::fns()?.cuLaunchKernel(…)`.
18//!
19//! - **No opaque-pointer guesswork.** Handle types are `#[repr(transparent)]`
20//! newtypes over `*mut ()` with matching `Send`/`Sync` and `Default`
21//! impls. Result enums are `#[repr(u32)]` with `Success = 0`.
22//!
23//! - **Only what we use.** Every function, every type in this crate is
24//! exercised by the safe layer. No dead FFI.
25//!
26//! ## Modules
27//!
28//! | Module | Library | Purpose |
29//! |---------------|--------------------|-----------------------------------------|
30//! | [`driver`] | `libcuda` / `nvcuda` | Core driver API (context, stream, module, kernel, memcpy, graph, event, peer access) |
31//! | [`nvrtc`] | `libnvrtc` | Runtime compilation of CUDA C++ → PTX |
32//! | [`cublas_lt`] | `libcublasLt` | Matmul descriptor-based API (FP8 GEMM) |
33//! | [`cublas`] | `libcublas` | Legacy BLAS (fallback) |
34//! | [`cudnn`] | `libcudnn` | Deep-learning primitives (MHA, conv) |
35//! | [`curand`] | `libcurand` | RNG |
36//! | [`cufft`] | `libcufft` | FFTs |
37//! | [`cusparse`] | `libcusparse` | Sparse BLAS (SpMM, SDDMM) |
38//! | [`cusolver`] | `libcusolverDn` | Dense linear solvers |
39//! | [`cutensor`] | `libcutensor` | N-dim tensor contraction |
40//! | [`nccl`] | `libnccl` | Collectives |
41//! | [`nvtx`] | `libnvToolsExt` | Profiler ranges/marks |
42//! | [`cupti`] | `libcupti` | Profiling/tracing activity records |
43//!
44//! ## Documentation policy
45//!
46//! Items here mirror the CUDA C headers one-to-one: a `Fns` field is named
47//! exactly after the C symbol it resolves, and enum variants and struct
48//! fields carry the C names minus their prefix. They are deliberately not
49//! documented item by item — NVIDIA's reference for the same symbol is the
50//! authority, and a paraphrase here could only drift from it. The safe crate
51//! (`ironaccelerator-cuda`) is fully documented and enforces `missing_docs`.
52
53#![allow(non_snake_case, non_camel_case_types, non_upper_case_globals)]
54#![allow(
55 clippy::missing_safety_doc,
56 clippy::too_many_arguments,
57 clippy::type_complexity,
58 clippy::missing_transmute_annotations
59)]
60
61pub mod cublas;
62pub mod cublas_lt;
63pub mod cudnn;
64pub mod cufft;
65pub mod cupti;
66pub mod curand;
67pub mod cusolver;
68pub mod cusparse;
69pub mod cutensor;
70pub mod driver;
71pub mod loader;
72pub mod nccl;
73pub mod nvrtc;
74pub mod nvtx;
75
76pub use loader::{LoadError, LoaderResult};
77
78/// CUDA Toolkit version this binding targets. Packed `MMmm` (13.20 = 1320).
79pub const CUDA_VERSION: u32 = 13_20;