ferrox_vulkan/lib.rs
1//! `ferrox-vulkan`: the Vulkan **beachhead**, not a backend.
2//!
3//! # What this crate is
4//!
5//! One question, answered end to end: *can ferrox reach a Vulkan
6//! device from Rust, upload a quantized weight verbatim, run one
7//! compute shader, and read back a correct answer?* That is the
8//! `vulkan-beachhead` GO/NO-GO in `docs/plans/roadmap.md`'s
9//! `d-hardware-reach`, and it is deliberately scoped below a backend:
10//! **one kernel, one quant kind, no integration**.
11//!
12//! It IS now wired into `ferrox-core`, as of 2026-09-01, once
13//! `backend-seam-refactor` landed the seam the verdict asked for:
14//! `ferrox_core::weight_matrix::gpu_backend::Vulkan` is a third
15//! `BackendCaps` / `BackendDispatch`, behind `ferrox-core`'s `vulkan`
16//! feature. What it wires up is only what is in here -- ONE Q8_0
17//! matvec -- and the seam says so: no GEMM for any kind, no matvec for
18//! any other kind, and guard tests that go red if either changes
19//! without a shader behind it.
20//!
21//! That does not promote this crate to a backend. `q8_0_matvec` still
22//! rebuilds its entire pipeline per call, weights are still staged
23//! rather than imported zero-copy, and nothing here has a measured
24//! number. `vulkan-decode-path` and `vulkan-prefill-gemm` are still
25//! where a real backend gets decided.
26//!
27//! # What has actually run
28//!
29//! See `docs/plans/vulkan-beachhead-verdict.md`. The rule this repo
30//! holds CUDA to applies here unchanged: nothing in this crate may be
31//! described as a measured capability in `docs/FEATURES.md` or
32//! `docs/MODELS.md` on the strength of compiling.
33//!
34//! # Layout
35//!
36//! - [`spirv`] -- a minimal SPIR-V word emitter, ~250 lines, no
37//! external shader compiler and no build script.
38//! - [`q8_0_shader`] -- the Q8_0 matvec compute shader, emitted from
39//! Rust.
40//! - [`q8_0_reference`] -- its scalar twin, checked against
41//! `ferrox_quant` and the `half` crate.
42//! - [`device`] -- the `ash` host layer (`--features vulkan`):
43//! instance, device, buffers, descriptors, dispatch, readback.
44//!
45//! The first three compile and are tested **unconditionally**, on a
46//! machine with no Vulkan driver at all. A broken shader fails
47//! `cargo test -p ferrox-vulkan` with no GPU, which is strictly more
48//! than `ferrox-cuda` can say for its kernels (NVRTC compiles at
49//! runtime).
50
51pub mod q8_0_reference;
52pub mod q8_0_shader;
53pub mod spirv;
54
55#[cfg(feature = "vulkan")]
56pub mod device;
57
58#[cfg(feature = "vulkan")]
59pub mod dispatch;