Tickets 9+11: FP32 MATMUL over the shared corpus; docs claim the verified lanes - #187
Merged
Conversation
First operator tier after ticket 8's IDENTITY: a checked-in SPIR-V matmul kernel (3 bindings, M/N/K/batch spec constants, no FMA), admission of CONST zero-point producer graphs, per-kernel dispatch geometry and specialization, a three-binding shared set layout, and the VK_KHR_portability_enumeration instance opt-in MoltenVK requires. Validated end-to-end on Apple M3 via MoltenVK: the shared MATMUL_FP32 oracle matches in every advertised memory domain; the backend hardware suite passes 13/13. spirv-val clean.
This was referenced Sep 4, 2026
SnowCheetos
added
the
area: backend
README Vulkan row flips to IDENTITY + MATMUL; the support section, crate table, and dependency text match. docs/performance.md gains the Vulkan section: warm-path shape, manual hardware commands (the #75 precedent), the three verified driver stacks (Intel ANV, Apple M3/MoltenVK as local validation, lavapipe in CI), and a deliberate no-timing-claims note until the XDNA-structured measurement lands. docs/portability.md and docs/architecture.md claim MATMUL; the crate README documents the tier and the verified stacks. Release-policy unsafe-exception entry was registered with ticket 8's FFI.
SnowCheetos
changed the title
SnowCheetos
marked this pull request as ready for review
September 6, 2026 16:59
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Vulkan instance creation now unconditionally enables VK_KHR_portability_enumeration, which can make initialization fail on loaders/drivers that do not expose that extension.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR extends the virtio-accel-vulkan backend from FP32 IDENTITY-only execution to also cover the shared-corpus FP32 MATMUL case (with the documented zero-zero-point constraint), and updates the workspace documentation to claim exactly the executed/verified Vulkan lanes (including MoltenVK portability behavior and the lavapipe CI lane).
Changes:
- Add a checked-in FP32 MATMUL SPIR-V module (assembled in-crate) plus per-program dispatch geometry and specialization constants.
- Extend Vulkan lowering/admission to accept MATMUL graphs with trailing CONST zero-points that serialize to signed/unsigned zero.
- Update Vulkan native plumbing for 3 storage-buffer bindings (descriptor layout/pool sizing, descriptor writes, 3D dispatch), and refresh docs/tests to reflect the executed tier and verified stacks.
File summaries
| File | Description |
|---|---|
| README.md | Updates the support matrix and Vulkan section to claim FP32 IDENTITY + MATMUL and list verified stacks/lane status. |
| docs/portability.md | Updates CI lane description and portability narrative to include MATMUL. |
| docs/performance.md | Adds a Vulkan evidence-status section documenting warm-path shape, reproduction commands, and verified stacks. |
| docs/architecture.md | Updates Vulkan architecture claims to include MATMUL corpus coverage. |
| crates/virtio-accel-vulkan/tests/vulkan.rs | Adds an end-to-end MATMUL execution test across all advertised memory domains; adjusts out-of-tier rejection test to use MAX_POOL2D. |
| crates/virtio-accel-vulkan/tests/targets.rs | Updates capability assertions to include MATMUL (and explicitly exclude MAX_POOL2D); adds matmul SPIR-V stability checks. |
| crates/virtio-accel-vulkan/src/shader.rs | Introduces MATMUL shader assembly, binding/spec-constant definitions, and workgroup geometry helpers/tests. |
| crates/virtio-accel-vulkan/src/native.rs | Widened descriptor set layout/pool sizing, generalized descriptor writes, 3D dispatch, MATMUL specialization plumbing, and portability-enumeration instance creation. |
| crates/virtio-accel-vulkan/src/lower.rs | Adds MATMUL admission/lowering (zero-zero-point constraint) and captures MATMUL geometry for specialization/dispatch. |
| crates/virtio-accel-vulkan/README.md | Updates crate-level tier description and adds “Verified driver stacks” section covering the new MATMUL tier. |
Review details
- Files reviewed: 10/10 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+111
to
+117
| // MoltenVK and other portability drivers refuse enumeration unless the instance opts | ||
| // into the portability extension; requesting it is a no-op on conformant native drivers. | ||
| let extension_names = [c"VK_KHR_portability_enumeration".as_ptr()]; | ||
| let info = vk::InstanceCreateInfo::default() | ||
| .application_info(&application) | ||
| .flags(vk::InstanceCreateFlags::ENUMERATE_PORTABILITY_KHR) | ||
| .enabled_extension_names(&extension_names); |
Comment on lines
+313
to
+314
| /// MATMUL specialization constants (ids 0..5): output rows `m`, output columns `n`, shared | ||
| /// reduction dimension `k`, and batch. `load_program` overrides every one. |
Comment on lines
+245
to
+246
| # Software ICD rehearsal (the CI lane's shape): | ||
| VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.x86_64.json \ |
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.
Part of wayfinder map #154 tickets 9 and 11; closes #186, resolves ticket 11's docs/plumbing half.
Code (ticket 9)
matmul_fp32_spirv— three storage buffers (lhs/rhs/out), specialization constants M/N/K/batch, one thread per output element over (n, m, batch). SeparateOpFMul/OpFAdd(no contraction) so the shared oracle's tolerance holds under every float-controls mode.spirv-valclean.lower.rs): graphs withCONSTzero-point producers admitted; MATMUL requires both trailing CONST inputs to serialize to zero (ZERO_ZERO_POINTS, matching OpenVINO/Hexagon/XDNA). Golden lowering tests.load_program;submitstays one fence + one descriptor update.VK_KHR_portability_enumerationwithENUMERATE_PORTABILITY_KHR— MoltenVK refuses enumeration otherwise (no-op on conformant drivers).Docs (ticket 11)
Identity + MATMULunder FP32, direct host/shared/device bindings.docs/performance.md: Vulkan section with the warm-path shape (descriptor update +vkQueueSubmit, fence-poll completion, no worker thread), manual hardware commands per the Build the AMD XDNA NPU backend #75 precedent, the three verified driver stacks, and a deliberate no-timing-claims note until the XDNA-structured warm-latency measurement lands.docs/portability.md+docs/architecture.mdclaim MATMUL; crate README documents the tier and the verified stacks. Release-policy unsafe-exception entry was registered with ticket 8's FFI.Evidence (three driver stacks, one crate, zero per-driver code paths)
VIRTIO_ACCEL_VULKAN_REQUIRE_DEVICE=1.vulkan-lavapipe-testCI lane): green on this branch (run 33839537450) — the GPU-less lane the map requires.Debugging trail: the first kernel draft emitted
OpLogicalOrwhere the spec table saysOpLogicalAnd(167) plus an inverted out-of-bounds branch — caught on-device by a focused repro, verified againstspirv-dis, fixed with And+Not.