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
//! `ferrox-vulkan`: the Vulkan **beachhead**, not a backend.
//!
//! # What this crate is
//!
//! One question, answered end to end: *can ferrox reach a Vulkan
//! device from Rust, upload a quantized weight verbatim, run one
//! compute shader, and read back a correct answer?* That is the
//! `vulkan-beachhead` GO/NO-GO in `docs/plans/roadmap.md`'s
//! `d-hardware-reach`, and it is deliberately scoped below a backend:
//! **one kernel, one quant kind, no integration**.
//!
//! It IS now wired into `ferrox-core`, as of 2026-09-01, once
//! `backend-seam-refactor` landed the seam the verdict asked for:
//! `ferrox_core::weight_matrix::gpu_backend::Vulkan` is a third
//! `BackendCaps` / `BackendDispatch`, behind `ferrox-core`'s `vulkan`
//! feature. What it wires up is only what is in here -- ONE Q8_0
//! matvec -- and the seam says so: no GEMM for any kind, no matvec for
//! any other kind, and guard tests that go red if either changes
//! without a shader behind it.
//!
//! That does not promote this crate to a backend. `q8_0_matvec` still
//! rebuilds its entire pipeline per call, weights are still staged
//! rather than imported zero-copy, and nothing here has a measured
//! number. `vulkan-decode-path` and `vulkan-prefill-gemm` are still
//! where a real backend gets decided.
//!
//! # What has actually run
//!
//! See `docs/plans/vulkan-beachhead-verdict.md`. The rule this repo
//! holds CUDA to applies here unchanged: nothing in this crate may be
//! described as a measured capability in `docs/FEATURES.md` or
//! `docs/MODELS.md` on the strength of compiling.
//!
//! # Layout
//!
//! - [`spirv`] -- a minimal SPIR-V word emitter, ~250 lines, no
//! external shader compiler and no build script.
//! - [`q8_0_shader`] -- the Q8_0 matvec compute shader, emitted from
//! Rust.
//! - [`q8_0_reference`] -- its scalar twin, checked against
//! `ferrox_quant` and the `half` crate.
//! - [`device`] -- the `ash` host layer (`--features vulkan`):
//! instance, device, buffers, descriptors, dispatch, readback.
//!
//! The first three compile and are tested **unconditionally**, on a
//! machine with no Vulkan driver at all. A broken shader fails
//! `cargo test -p ferrox-vulkan` with no GPU, which is strictly more
//! than `ferrox-cuda` can say for its kernels (NVRTC compiles at
//! runtime).