Skip to main content

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;