garboard

Safe Rust bindings for the CUDA ecosystem with a host-simulated fallback backend.

Garboard wraps the CUDA Driver API, NVRTC, cuBLAS, and cuDNN behind typed, lifetime-safe Rust APIs. Every public type is an enum dispatching to either a real CUDA backend (requires libcuda, libnvrtc, libcublas, libcudnn) or a host-simulated backend that allows the full API surface to be exercised without a GPU — so libraries built on garboard can be tested in CI without CUDA hardware.

Status

Development. APIs are not yet stable.

Features

• Device, Stream, DeviceSlice, PinnedSlice, Transfer — memory management and async transfers
• Event — GPU-side elapsed-time measurement (timing always enabled)
• Program, Module, TypedKernel<Args> — NVRTC compilation and type-checked kernel launch
• BlasContext — full BLAS Level 3 (GEMM, strided batched GEMM, SYMM, SYRK, SYR2K, TRMM, TRSM) for f32 and f64
• DnnContext — convolution forward, convolution backward data (transposed conv), RNN/LSTM forward inference

Design highlights

• Enum-dispatched backends. Public types are #[non_exhaustive] enums with Host and Cuda variants. The same code compiles and runs on hosts without CUDA.
• Typed kernel launch. TypedKernel<Args> moves the unsafe boundary to kernel signature declaration, analogous to extern "C" { fn ... }. Every launch site is type-checked at compile time.
• Lifetimes enforce correctness. DeviceSlice<'d, T> borrows the device it was allocated from. Streams, events, and modules are tied to device lifetimes.
• No silent unsafety. Every unsafe block wraps exactly one FFI call with a // SAFETY: comment.

Requirements

• Rust 1.85+ (2024 edition)
• For the cuda feature (default): CUDA Toolkit 12.x, cuDNN 9.x, libclang (for bindgen)
• CI runs without CUDA using --no-default-features

Building

# With the CUDA backend (default)
cargo build

# Host-only (no CUDA required)
cargo build --no-default-features

Testing

# Host-only (runnable anywhere)
cargo test -p garboard --no-default-features

# Full (requires GPU)
cargo test -p garboard

Regenerating FFI bindings

Raw bindings in garboard-sys are generated by bindgen and committed. To regenerate:

cd garboard-sys
./regen.sh

License

MIT — see LICENSE.