oxicuda-driver 0.1.1

OxiCUDA Driver - Dynamic CUDA driver API wrapper via libloading (zero SDK dependency)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

# oxicuda-driver

Dynamic, safe Rust bindings for the NVIDIA CUDA Driver API.

Part of the [OxiCUDA](https://github.com/cool-japan/oxicuda) project.

## Overview

`oxicuda-driver` is a pure Rust wrapper around the CUDA Driver API (`cuda.h`).
Unlike traditional approaches that require the CUDA Toolkit at build time,
this crate loads the driver shared library entirely at **runtime** via
[`libloading`](https://crates.io/crates/libloading). No `cuda.h`, no
`libcuda.so` symlink, no `nvcc` -- the crate compiles on any standard Rust
toolchain.

The actual GPU driver is discovered the first time you call `init()` or
`try_driver()`. A global `OnceLock` singleton caches the loaded function
pointers for the lifetime of the process, so subsequent calls are
essentially free.

All public APIs return `CudaResult<T>` rather than panicking. The
`CudaError` enum covers roughly 100 CUDA driver error codes as
strongly-typed variants, making match-based error handling straightforward.
RAII wrappers (`Context`, `Stream`, `Event`, `Module`) automatically release
GPU resources on `Drop`.

## Modules

| Module      | Description                                                  |
|-------------|--------------------------------------------------------------|
| `ffi`       | Raw C-compatible types (`CUdevice`, `CUcontext`, etc.)       |
| `error`     | `CudaError` (~100 variants), `CudaResult`, `check()` helper |
| `loader`    | Runtime library loading with `OnceLock` singleton            |
| `device`    | Device enumeration, attribute queries, `best_device()`       |
| `context`   | RAII CUDA context bound to a device                          |
| `stream`    | Asynchronous command queue within a context                  |
| `event`     | Timing and synchronisation markers on streams                |
| `module`    | PTX/cubin loading, JIT compilation, function lookup          |
| `occupancy` | Occupancy-based launch configuration queries                 |

## Quick Start

```rust,no_run
use oxicuda_driver::prelude::*;

// Initialise the CUDA driver (loads libcuda at runtime).
init()?;

// Pick the first available GPU and create a context.
let dev = Device::get(0)?;
let _ctx = Context::new(&dev)?;

// Load a PTX module and look up a kernel.
let module = Module::from_ptx(ptx_source)?;
let kernel = module.get_function("vector_add")?;
# Ok::<(), oxicuda_driver::CudaError>(())
```

## Features

| Feature     | Description                               |
|-------------|-------------------------------------------|
| `gpu-tests` | Enable tests that require a physical GPU  |

## Runtime Library Resolution

| Platform | Library searched               |
|----------|--------------------------------|
| Linux    | `libcuda.so`, `libcuda.so.1`   |
| Windows  | `nvcuda.dll`                   |
| macOS    | *(returns `UnsupportedPlatform` at runtime -- NVIDIA dropped macOS support)* |

## Platform Support

| Platform | Status                                     |
|----------|--------------------------------------------|
| Linux    | Full support (NVIDIA driver 525+)          |
| Windows  | Full support (NVIDIA driver 525+)          |
| macOS    | Compile only (UnsupportedPlatform at runtime) |

## License

Apache-2.0 -- (C) 2026 COOLJAPAN OU (Team KitaSan)