vyre-driver-cuda

CUDA/PTX backend for vyre through cudarc.

This crate is the NVIDIA backend implementation point and the 0.7.2 release fast path. It owns CUDA device probing, hardware capability reporting, PTX lowering, and dispatch integration behind the frozen VyreBackend contract.

Current Contract

The backend probes the live CUDA device for compute capability, VRAM, launch limits, warp size, cooperative-launch support, concurrent-kernel support, and async-engine count. Backend capability methods are derived from those device attributes. Dispatch routes through PTX lowering first and returns structured backend errors when a program or launch path is not supported by the current implementation. A failed CUDA probe is a configuration or capability error; it is never silently downgraded to CPU execution.

CUDA is release-preferred on NVIDIA systems. WGPU remains the portable GPU fallback backend for non-CUDA deployments. Release evidence must prove CUDA conformance, performance, feature-surface coverage, and metadata publication for vyre-driver-cuda@0.7.2.

Quick start

use vyre_driver_cuda::CudaBackend;

let backend = CudaBackend::acquire()?;
let outputs = backend.dispatch(&program, &inputs, &config)?;

Architecture decisions

• #![allow(unsafe_code)] is policy, not accident. CUDA driver bindings (cudarc::driver::sys::cu*) are inherently unsafe FFI. The rest of the workspace keeps unsafe_code = "deny"; this crate documents its policy in src/lib.rs and gates every unsafe block through scripts/check_unsafe_justifications.sh.
• PTX-only emit path. The CUDA backend never emits SPIR-V or WGSL. Cross-substrate parity is verified by the conformance runner against the wgpu and reference backends.
• No peer-backend deps. The crate must not pull vyre-driver-wgpu or vyre-driver-spirv; the boundary is enforced by OWNERSHIP.md and scripts/check_architectural_invariants.sh.

Where to look

• src/backend/mod.rs - VyreBackend implementation and capability probing.
• src/codegen.rs - PTX emit pipeline.
• ARCHITECTURE.md describes the CUDA driver boundary.
• docs/optimization/OWNERSHIP.toml and docs/optimization/README.md define CUDA optimization ownership and the patch proof contract.
• docs/OWNERSHIP.md defines workspace ownership.

Crate contract

This section is generated by python3 scripts/crate_readmes.py --write from the crate manifest, release train, ownership registry, and crate-guide metadata.

Purpose

Own pure PTX target compilation, native device acquisition, materialization, dispatch, graphs, and release-path evidence.

Boundaries

The cuda-driver owner maintains this concrete-backend crate at vyre-driver-cuda. Its allowed internal production dependencies are: vyre-driver, vyre-emit-ptx, vyre-foundation, vyre-lower, vyre-megakernel, vyre-self-substrate, vyre-spec. Any other normal or build dependency requires an ownership-registry change.

Minimal real example

Run the checked-in behavior from vyre-driver-cuda/examples/cuda_release_surface.rs:

CARGO_BUILD_JOBS=1 ./cargo_full run -p vyre-driver-cuda --example cuda_release_surface

Features

• Manifest features: cuda, default
• Default feature members: None

Errors and unsupported behavior

Device acquisition, lowering, allocation, and dispatch failures are explicit backend errors. A requested device path never falls back to another backend.

Testing

Use docs/testing/vyre-driver-cuda.md for exact commands, Cargo targets, hardware requirements, evidence outputs, expected skips, and failure semantics.

Release status

vyre-driver-cuda@0.7.2 is a publishable crate on the current Vyre release train. Publication still requires the release evidence and user-approval gates.

Ownership

docs/CRATE_OWNERSHIP.toml is authoritative for this crate's responsibility and allowed internal edges. Regenerate docs/CRATE_GRAPH.md and docs/OWNERSHIP.md after changing that registry.

License

Licensed under either of

• Apache License, Version 2.0, or
• MIT license

at your option. See the workspace LICENSE-APACHE and LICENSE-MIT files.