vyre-driver-cuda 0.7.2

CUDA/PTX backend for vyre through the CUDA driver API.
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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# 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

```rust
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`](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.

<!-- BEGIN GENERATED CRATE CONTRACT -->
## 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`:

```console
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`](../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.

<!-- END GENERATED CRATE CONTRACT -->