Skip to main content

ironaccelerator_cuda/
lib.rs

1//! # `ironaccelerator-cuda`
2//!
3//! Low-level, hardware-agnostic CUDA interface. Targets the **CUDA Toolkit
4//! 13.2** API surface via [`iron_cuda_sys`], with safe wrappers around the
5//! driver, NVRTC, and every major vendor library (cuBLAS / cuBLASLt / cuDNN
6//! / cuRAND / cuSPARSE / cuSOLVER / cuFFT / cuTENSOR / NCCL / NVTX / CUPTI).
7//!
8//! **Scope.** This crate is a *driver substrate*. It does **not** ship
9//! kernels, workload planners, FP8 recipes, attention/MoE implementations,
10//! or autotuners — those belong to downstream libraries layered on top.
11//! What's here:
12//!
13//! - [`drv`] — Device / Stream / Event / DeviceBuf / Module / Function
14//! - [`kernel`] — NVRTC compile + in-memory and on-disk PTX cache
15//! - [`blas`], [`cudnn`], [`fft`], [`cusparse`], [`cusolver`], [`cutensor`],
16//!   [`rng`], [`nccl`] — per-library handle plumbing
17//! - [`advanced`] — VMM, green contexts, multicast teams, conditional graph nodes
18//! - [`graph`], [`launch`], [`peer`], [`pinned`], [`streams`],
19//!   [`events`], [`alloc`] — driver-level primitives
20//! - [`observe`], [`profile`], [`cupti`] — NVTX / profiler hooks
21//! - [`cudarc_compat`] — drop-in compatibility surface for cudarc users
22//! - [`sys`] — the raw FFI re-export for callers that need it
23//!
24//! ## If you want to…
25//!
26//! | Task                                       | Use                                                          |
27//! |--------------------------------------------|--------------------------------------------------------------|
28//! | port existing cudarc 0.19 code             | [`cudarc_compat`] (drop-in `use` swap)                       |
29//! | open a device + create a stream            | [`drv::Device::open`] then [`drv::Stream::new`]              |
30//! | allocate a typed device buffer             | [`drv::DeviceBuf::alloc`] / [`alloc::alloc`]                 |
31//! | copy host ↔ device on a stream             | [`drv::DeviceBuf::copy_from_host`] / `copy_to_host`          |
32//! | compile a CUDA C++ kernel at runtime       | [`kernel::get_or_compile`] (cached on disk per arch+source)  |
33//! | launch a kernel with typed args            | [`drv::Function::launch`] or [`launch::launch_1d`] / `_2d`   |
34//! | record + measure GPU time                  | [`events::Timer`] (or [`drv::TimingEvent`] directly)         |
35//! | capture & replay a stream as a CUDA graph  | [`drv::Stream::begin_capture`] → [`drv::GraphExec`]          |
36//! | call cuBLASLt / cuDNN / cuFFT / NCCL       | the matching `blas`/`cudnn`/`fft`/`nccl` module              |
37//! | drop down to raw FFI                       | [`sys`] (re-exports [`iron_cuda_sys`])                       |
38//!
39//! ## Performance posture
40//!
41//! Every hot path is `#[inline]`. The driver `fns()` lookup uses an
42//! `AtomicPtr<DriverFns>` fast-path cache, and each `Device`/`Stream`/`Event`/
43//! `Module`/`Function` caches `&'static DriverFns` at construction — so a
44//! wrapped op costs one struct-field load + one FFI entry. See the workspace
45//! README for benchmarks against `cudarc` 0.19; alloc/free is **~2× faster**.
46
47#![warn(missing_docs)]
48#![allow(
49    clippy::missing_safety_doc,
50    clippy::too_many_arguments,    // intrinsic to FFI wrappers (cublasLtMatmul &c.)
51    clippy::type_complexity,       // libloading::Symbol<fn(...)> types
52    clippy::missing_transmute_annotations,
53    clippy::field_reassign_with_default,
54    clippy::if_same_then_else,
55    clippy::doc_lazy_continuation,
56)]
57
58pub use iron_cuda_sys as sys;
59
60pub mod drv;
61
62pub mod advanced;
63pub mod alloc;
64pub mod blas;
65pub mod cudarc_compat;
66pub mod cudnn;
67pub mod cupti;
68pub mod cusolver;
69pub mod cusparse;
70pub mod cutensor;
71pub mod events;
72pub mod fft;
73pub mod graph;
74pub mod kernel;
75pub mod launch;
76pub mod nccl;
77pub mod observe;
78pub mod peer;
79pub mod pinned;
80pub mod pool;
81pub mod profile;
82pub mod rng;
83pub mod safe;
84pub mod streams;