Ticket 3: Vulkan 1.3 baseline + capability probe (ADR 0005, #176) - #177
Merged
Conversation
This was referenced Sep 3, 2026
SnowCheetos
marked this pull request as ready for review
September 3, 2026 08:39
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new ADR contains a Vulkan API naming inaccuracy and a potentially misleading statement about non-coherent flush granularity that should be corrected to avoid guiding an invalid probe implementation.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds ADR 0005 documenting the project’s Vulkan backend “floor” (Vulkan 1.3) and the associated capability-probing and reporting policy that will inform upcoming implementation work (notably ticket 8 / FFI).
Changes:
- Establishes Vulkan 1.3 as the minimum API baseline and clarifies that promoted-to-core features still require explicit enabling at device creation.
- Records a memory-domain mapping policy (Host/Device/Shared) tied to actual memory-type probing (no assumptions).
- Defines probing/reporting expectations for allocation-count limits and per-device alignment-related limits.
File summaries
| File | Description |
|---|---|
docs/adr/0005-vulkan-baseline-probe.md |
New ADR capturing Vulkan 1.3 baseline decisions and the intended capability probe/reporting approach. |
Review details
Suppressed comments (1)
docs/adr/0005-vulkan-baseline-probe.md:42
- The parenthetical “safe superset of observed values (64 vs 128 …)” is easy to misread as 64 being a safe superset; 64 is not safe if a device reports
nonCoherentAtomSize = 128. Consider rewording to explicitly name 128 as the conservative value that covers both.
`minStorageBufferOffsetAlignment` and `nonCoherentAtomSize` per device; the flush/invalidate
granularity uses a safe superset of observed values (64 vs 128 across vendors).
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This was referenced Sep 3, 2026
SnowCheetos
added
the
area: backend
micro-perceptron
approved these changes
Sep 3, 2026
Resolves map ticket 3 / #176 with Sep-2026 Mesa-source evidence: 1.3 floor (synchronization2, dynamic rendering, integer dot product core); Host/Device/Shared memory-domain map; 4096 allocation-count assumption; per-device alignment reporting. Fuels the 1.3-only subclassing in ticket 8.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Cass Sheng <86272122+SnowCheetos@users.noreply.github.com>
micro-perceptron
force-pushed
the
vulkan/probe-3
branch
from
September 3, 2026 21:44
68f1559 to
da20bfa
Compare
micro-perceptron
added a commit
that referenced
this pull request
Sep 3, 2026
Stacked on #177. Resolves map ticket 6 (grilling). Decisions: nonblocking poll_event via vkGetFenceStatus (no worker thread; ticket 8 proves it); bounded (CB, fence, descriptor) ring per context sized at max_events_per_context; vkQueueSubmit success the admission boundary; Timeout::AfterNs rejected pre-admission with DeadlineExpired (Hexagon/XDNA precedent) since Vulkan lacks cancel; DEVICE_LOST maps to Failed(DeviceLost) + sticky instance poisoning; EVENT_CANCELLATION never advertised. Falsification guard: if fence polling dominates steady-state on lavapipe, a worker-thread poll sits behind the same slot ring unchanged.
micro-perceptron
added a commit
that referenced
this pull request
Sep 3, 2026
…apipe) (#182) Stacked on #179. Resolves wayfinder ticket 8 (#181) of map #154: the `ash` FFI, the full `Accelerator` lifecycle, and FP32 IDENTITY executing end-to-end on a real GPU and a software ICD. ## Why The scaffold (#175) and design ADRs (#177, #179) had no execution behind them. Ticket 8 is the proof that the graph-shaped data plane (ADR 0001), runtime-loaded `ash` (ADR 0002), checked-in specialized SPIR-V (ADR 0003), the 1.3 baseline and memory-domain map (ADR 0005), and the no-worker-thread fence-poll execution model (ADR 0006) hold on metal. ## What - **`native.rs`** — Vulkan 1.3 through pinned `ash 0.38.0` (`loaded`, `std`): instance/device enumeration with honest `DeviceIdentity` (device UUID, vendor/device id, `GPU` class; `OTHER` for CPU ICDs), compute-queue selection (compute-only family preferred), per-backend device with `synchronization2` and `bufferDeviceAddress` (the latter only to *measure* allocation alignment). Dedicated `VkBuffer`+`VkDeviceMemory` per buffer, bound directly as storage buffers. `Host`/`Shared` are persistently mapped host-coherent memory (no flush path needed or issued); `Device` is device-local memory reached only through a bounded 4 MiB staging copy inside `write_buffer`/`read_buffer`. Per-context ring of 64 (command buffer, fence, descriptor set) triples; `vkQueueSubmit2` success is the admission boundary; `poll_event` is one `vkGetFenceStatus`; finite timeouts rejected pre-admission; `VK_ERROR_DEVICE_LOST` poisons the instance; parents refuse release while children or in-flight events reference them. Diagnostics: `direct_binding_admissions`, `explicit_transfer_bytes`, `live_resources`. - **`lower.rs`** — hardware-free admission: FP32 target only, one region/block, exactly one boundary-to-boundary IDENTITY, static positive shapes, u32 element domain. `VULKAN_TOSA_CAPABILITY` names exactly that boundary. The integer target stays declared, unadvertised. - **`shader.rs`** — the checked-in SPIR-V 1.3 word-copy kernel, assembled instruction by instruction with its disassembly beside it (no toolchain, no `rspirv`), validated structurally by unit tests and offline with naga's SPIR-V front end. Element count is specialization constant 0. - **Finding recorded in ADR 0005:** ANV exposes memory types a storage buffer may *not* use; the heap list alone mis-selects. The memory-domain map is now chosen against a probe buffer's `memoryTypeBits`. - **SAFETY.md** — real audit: `ash` pin and the exact entry-point inventory, handle lifetime, mappings, ring, device loss, shaders, evidence. Registered in `ci/check-release-policy.py` (`UNSAFE_AUDITS`) and `docs/release-policy.md` (sixth exception). `deny.toml` allows ISC for `libloading`. - **CI** — `vulkan-lavapipe-test` lane mirroring `openvino-host-test`: distribution Mesa, ICD pinned via `VK_DRIVER_FILES`, `VIRTIO_ACCEL_VULKAN=1`, and `VIRTIO_ACCEL_VULKAN_REQUIRE_DEVICE=1` so a missing ICD fails instead of skipping. Ticket 10 still owns the full lane hardening. - **Docs** — README, crate README, `docs/portability.md`, `docs/architecture.md`; ADR 0005/0006 gain a ticket 8 evidence section and the review-flagged wording fixes (`vkGetPhysicalDeviceFeatures2`, the SAFETY.md quote); `docs/release-policy.md` line break, the crate doc link, and the example's `unreachable!` from the #175 review are fixed. ## Validation (2026-09-03, Intel Arc 140V / Lunar Lake, Mesa 26.0.8 ANV, Vulkan 1.4.335; and llvmpipe on the same host) - `cargo test -p virtio-accel-vulkan`: 11 unit + 7 host-independent + 12 native tests pass on **both** devices — lifecycle in every advertised domain (`Host`, `Device`, `Shared` on both), `IDENTITY_EDGES_FP32` bit-exact including NaN payload and subnormal, offset bindings with untouched neighbors, segmented staging to device-local memory, binding/timeout rejection, 16 overlapping read-only submissions in flight with `Busy` on the shared input, ring exhaustion as `ResourceLimit`, parent-release refusal, and the standard conformance suite with accounting and copy-path hooks in every domain. - `cargo run -p virtio-accel-vulkan --example tosa_vulkan` on ANV and pinned to lavapipe: `3.25` round-trips. - Warm FP32 identity (release, 200 samples): ANV admission p50 16.6 µs / submit-to-complete p50 259 µs; llvmpipe 4.3 µs / 58 µs. - `cargo fmt --check`, `cargo clippy --workspace --all-targets --all-features -D warnings`, `python3 ci/check-release-policy.py`, `cargo deny --workspace --all-features check`, `cargo test --workspace --all-targets --all-features` (one pre-existing OpenVINO failure on this host, `executes_boolean_boundaries_on_every_available_device`, reproduces on `main` and is unrelated), placeholder build (`VIRTIO_ACCEL_VULKAN=0`) clippy/tests/example, `cargo doc -D warnings`. ## Not in this ticket Operator tiers beyond IDENTITY (ticket 9), FP16/INT8 gating (ticket 5), full CI lane hardening and the numerical corpus (ticket 10), performance doc and manual hardware commands (ticket 11). Grid-stride dispatch for tensors beyond `maxComputeWorkGroupCount[0] × 64` elements is rejected as `ResourceLimit` at load until ticket 9. Closes #181 once merged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #175. Resolves wayfinder ticket #176 (research; agent-grounded against Mesa source and gpuinfo). Decides: Vulkan 1.3 floor (synchronization2, dynamicRendering, maintenance4, shaderIntegerDotProduct core; feature-enable still required); memory-domain map (Host→HOST_VISIBLE|HOST_COHERENT persistently mapped; Device→DEVICE_LOCAL staging confined to read/write — first backend advertising DEVICE_LOCAL_MEMORY; Shared→DEVICE_LOCAL|HOST_VISIBLE advertised only on ReBAR/UMA probe); allocation count assumed 4096 (NVIDIA/WDDM binds), dedicated allocations with honest low limits, suballocation permitted while staying DIRECT_BINDING-legal; alignment reported per device, no RADV assumption. All findings verified against Mesa sources and gpuinfo as of 2026-09-03.