virtio_accel_vulkan/
lib.rs

1//! Vendor-neutral Vulkan compute host backend for `virtio-accel`.
2//!
3//! The native path binds Vulkan 1.3 through the pinned [`ash`] crate, loading the platform's
4//! Vulkan loader at run time (ADR 0002). It executes device-neutral TOSA 1.0 programs admitted by
5//! [`lower`](crate::VULKAN_TOSA_FP16_CAPABILITY) — the 42 FP32-tier operators shared with the
6//! Core ML and OpenVINO backends over FP32 and FP16 tensors, with `BOOL`/`INT32` auxiliaries —
7//! on crate-authored SPIR-V compute kernels specialized at `load_program` (ADR 0003, ADR 0007).
8//! The FP16 tier needs no device feature: its binary16 conversions are crate-owned integer and
9//! binary32 code (ADR 0008), so every device that hosts the FP32 tier hosts the FP16 tier with
10//! identical numerics. A whole graph is one submission: constants and intermediates live in a
11//! per-program arena and dependent dispatches are separated by compute barriers. Buffers are
12//! dedicated `VkDeviceMemory` allocations bound directly as storage buffers, persistently mapped
13//! wherever their memory type allows (ADR 0012); completion is a
14//! nonblocking `vkGetFenceStatus` read over a bounded per-context ring of command buffers,
15//! fences, and descriptor sets (ADR 0006); no worker thread exists.
16//!
17//! The native module compiles on the host operating systems enumerated by `build.rs` (`va_vulkan`).
18//! Loader absence is a run-time fact reported as [`InitError::RuntimeUnavailable`], never a build
19//! probe. `VIRTIO_ACCEL_VULKAN=0` forces the placeholder, `=1` makes an unsupported target a loud
20//! build failure. The design decisions live in [`docs/adr/`](../../../docs/adr/) (ADRs 0001–0013);
21//! ADR 0010 records the kernel geometries and the benchmark (`cargo bench -p virtio-accel-vulkan`)
22//! that measures them, ADR 0011 the MATMUL numerics (fused multiply-add, split-`k`), and
23//! ADR 0012 the mapped `Device` domain on unified-memory devices and the boundary views.
24
25#![cfg_attr(not(va_vulkan), forbid(unsafe_code))]
26
27mod lower;
28pub mod nvfp4;
29pub mod shader;
30
31pub use lower::{
32    LoweringError, VULKAN_TOSA_CAPABILITY, VULKAN_TOSA_FP8_CAPABILITY, VULKAN_TOSA_FP8_TARGET,
33    VULKAN_TOSA_FP16_CAPABILITY, VULKAN_TOSA_INTEGER_TARGET, VULKAN_TOSA_TARGET,
34    supports_tosa_dtype, supports_tosa_operator,
35};
36
37#[cfg(not(va_vulkan))]
38use virtio_accel_tosa::{CapabilityDescriptor, TosaCapabilityProvider};
39
40/// TOSA capability list of the placeholder build: nothing. The native backend advertises
41/// [`VULKAN_TOSA_FP16_CAPABILITY`] on every device (ADR 0008); see `native`'s
42/// `TosaCapabilityProvider` implementation.
43#[cfg(not(va_vulkan))]
44const TOSA_CAPABILITIES: &[CapabilityDescriptor] = &[];
45
46/// Vulkan publishes no bound on what a driver retains for a compiled pipeline, so the provider
47/// promises the maximal charge; anything less would under-report `ArtifactRef::resident_bytes`.
48pub const REQUIRED_RESIDENT_BYTES: u64 = u64::MAX;
49
50/// Failure to initialize a Vulkan backend instance.
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52pub enum InitError {
53    /// No Vulkan loader could be loaded, or it predates Vulkan 1.3 (or this is a placeholder
54    /// build).
55    RuntimeUnavailable,
56    /// `vkCreateInstance` failed.
57    InstanceCreationFailed,
58    /// Physical-device enumeration failed inside the loader or an ICD.
59    DeviceEnumerationFailed,
60    /// No requested or suitable Vulkan 1.3 compute device is available on this host.
61    DeviceUnavailable,
62    /// `vkCreateDevice` or the device-level setup failed.
63    DeviceCreationFailed,
64}
65
66impl core::fmt::Display for InitError {
67    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
68        match self {
69            Self::RuntimeUnavailable => write!(formatter, "no Vulkan 1.3 loader initialized"),
70            Self::InstanceCreationFailed => write!(formatter, "Vulkan instance creation failed"),
71            Self::DeviceEnumerationFailed => {
72                write!(formatter, "Vulkan physical-device enumeration failed")
73            }
74            Self::DeviceUnavailable => write!(formatter, "no suitable Vulkan compute device"),
75            Self::DeviceCreationFailed => write!(formatter, "Vulkan device creation failed"),
76        }
77    }
78}
79
80impl std::error::Error for InitError {}
81
82#[cfg(va_vulkan)]
83mod native;
84#[cfg(va_vulkan)]
85pub use native::{
86    LiveResources, VulkanAccelerator, VulkanBuffer, VulkanContext, VulkanEvent, VulkanGateSignal,
87    VulkanHostGate, VulkanOptions, VulkanProgram, VulkanQueue,
88};
89
90/// Placeholder that keeps workspace consumers portable where no Vulkan loader host exists.
91#[cfg(not(va_vulkan))]
92#[derive(Clone, Copy, Debug, Default)]
93pub struct VulkanAccelerator;
94
95#[cfg(not(va_vulkan))]
96impl VulkanAccelerator {
97    /// Report that the native backend is not available in this build.
98    pub fn new() -> Result<Self, InitError> {
99        Err(InitError::RuntimeUnavailable)
100    }
101
102    /// Report that the native backend is not available in this build.
103    pub fn with_device(_device: &str) -> Result<Self, InitError> {
104        Err(InitError::RuntimeUnavailable)
105    }
106
107    /// Enumerate nothing in the placeholder; the native path reports one entry per physical
108    /// device.
109    pub fn available_devices() -> Result<Vec<String>, InitError> {
110        Err(InitError::RuntimeUnavailable)
111    }
112}
113
114#[cfg(not(va_vulkan))]
115impl TosaCapabilityProvider for VulkanAccelerator {
116    fn tosa_capabilities(&self) -> &'static [CapabilityDescriptor] {
117        TOSA_CAPABILITIES
118    }
119}
virtio_accel_vulkan/lib.rs

virtio_accel_vulkan/
lib.rs
