Skip to content

Commit 3c00f2e

Browse files
ReubendReubend
committed
Vulkan: support Linux/Windows desktop GPUs and opt-in wheel builds
The Vulkan backend was developed for Android GPUs. This makes it build and run on Linux/Windows desktop discrete GPUs (NVIDIA/AMD/Intel) and adds opt-in pre-built Vulkan wheels, with no change to Android behavior (build divergence is behind compile-time guards; runtime changes key off queried capabilities). Covers build portability, discrete-GPU correctness fixes (real-GPU device/ICD selection, shaderInt16/Int64/Float64 enablement, a blit queue guard, and texel-rounded buffer allocations to avoid out-of-bounds vec4 reads), and EXECUTORCH_BUILD_VULKAN-gated CI/packaging (a new vulkan.yml runs the real-GPU NVIDIA and Windows MSVC jobs, plus opt-in wheel plumbing). Tested on an NVIDIA A100; the SwiftShader CI path is unchanged. This change was authored with Claude.
1 parent e285edf commit 3c00f2e

25 files changed

Lines changed: 647 additions & 92 deletions

‎.ci/scripts/setup-vulkan-linux-deps.sh‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
#!/bin/bash
32
# Copyright (c) Meta Platforms, Inc. and affiliates.
43
# All rights reserved.
@@ -43,7 +42,38 @@ install_vulkan_sdk() {
4342
export PATH="${PATH}:${_vulkan_sdk_dir}/${VULKAN_SDK_VERSION}/x86_64/bin/"
4443
}
4544

45+
setup_real_gpu_icd() {
46+
# On a real-GPU runner the system Vulkan ICD is installed by the GPU driver.
47+
# The loader searches both /etc/vulkan/icd.d and /usr/share/vulkan/icd.d, so
48+
# check both. If a system ICD is present, do NOT use SwiftShader so the real
49+
# device (and its fp16/int16/dot-product shader variants) is exercised. Fall
50+
# back to SwiftShader if no system ICD is found so the job stays green either
51+
# way.
52+
# Match each directory separately: a single `ls` over both globs returns
53+
# non-zero if either directory has no match, which would mask a real ICD that
54+
# is present in only one location (e.g. NVIDIA's in /usr/share/vulkan/icd.d).
55+
if compgen -G "/etc/vulkan/icd.d/*.json" >/dev/null || \
56+
compgen -G "/usr/share/vulkan/icd.d/*.json" >/dev/null; then
57+
echo "System Vulkan ICD(s) detected:"
58+
ls /etc/vulkan/icd.d/*.json /usr/share/vulkan/icd.d/*.json 2>/dev/null || true
59+
unset ETVK_USING_SWIFTSHADER || true
60+
else
61+
echo "WARNING: no system Vulkan ICD found; using SwiftShader."
62+
install_swiftshader
63+
fi
64+
}
65+
4666
VULKAN_SDK_VERSION="1.4.321.1"
4767

48-
install_swiftshader
49-
install_vulkan_sdk "${VULKAN_SDK_VERSION}"
68+
# The no-argument default installs SwiftShader so the existing CPU-runner CI is
69+
# unchanged. Pass "real-gpu" to prefer a real system ICD when one is present.
70+
case "${1:-swiftshader}" in
71+
real-gpu)
72+
install_vulkan_sdk "${VULKAN_SDK_VERSION}"
73+
setup_real_gpu_icd
74+
;;
75+
swiftshader | *)
76+
install_swiftshader
77+
install_vulkan_sdk "${VULKAN_SDK_VERSION}"
78+
;;
79+
esac

‎.ci/scripts/setup-vulkan-windows-deps.ps1‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
# Install glslc (the Vulkan shader compiler) on Windows via conda-forge's
8+
# shaderc package, and make sure it is on PATH. glslc is the only build-time
9+
# Vulkan dependency -- the Vulkan headers and the volk loader come from the
10+
# in-tree submodules -- so this avoids depending on the heavyweight LunarG SDK
11+
# installer. Requires conda to be available (the callers create/activate an env).
12+
13+
$ErrorActionPreference = "Stop"
14+
15+
Write-Host "Installing shaderc (provides glslc) from conda-forge..."
16+
conda install -y -c conda-forge shaderc
17+
if ($LASTEXITCODE -ne 0) {
18+
Write-Error "Failed to install shaderc from conda-forge (exit ${LASTEXITCODE})"
19+
exit 1
20+
}
21+
22+
$glslc = Get-Command glslc -ErrorAction SilentlyContinue
23+
if (-not $glslc) {
24+
Write-Error "glslc not found on PATH after installing shaderc"
25+
exit 1
26+
}
27+
28+
# Expose glslc to the current process and, when running as a GitHub Actions step,
29+
# to subsequent steps.
30+
$glslcDir = Split-Path -Parent $glslc.Source
31+
$env:PATH = "${glslcDir};${env:PATH}"
32+
if ($env:GITHUB_PATH) {
33+
Add-Content -Path $env:GITHUB_PATH -Value $glslcDir
34+
}
35+
36+
Write-Host "glslc available at $($glslc.Source)"
37+
& glslc --version

‎.ci/scripts/setup-windows-msvc-vulkan.ps1‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the BSD-style license found in the
5+
# LICENSE file in the root directory of this source tree.
6+
7+
# Build-validation for the Vulkan backend under MSVC on Windows. Mirrors
8+
# setup-windows-msvc.ps1 but installs glslc (the Vulkan shader compiler) and
9+
# configures/builds the vulkan_backend target. This is a bring-up job: it exists
10+
# to surface MSVC portability issues in the Vulkan/volk/VMA code, so it may need
11+
# iteration.
12+
13+
conda create --yes --quiet -n et python=3.12
14+
conda activate et
15+
16+
# Install cmake
17+
conda install -y cmake
18+
19+
# Activate the VS environment - this is required for MSVC to work.
20+
& "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64
21+
22+
# Install glslc (via conda-forge shaderc) and put it on PATH in this process.
23+
.ci/scripts/setup-vulkan-windows-deps.ps1
24+
25+
# Install CI requirements
26+
pip install -r .ci/docker/requirements-ci.txt
27+
28+
$buildDir = "cmake-out-vulkan"
29+
if (Test-Path -Path $buildDir) {
30+
Remove-Item -Path $buildDir -Recurse -Force
31+
}
32+
New-Item -Path $buildDir -ItemType Directory
33+
34+
cmake -S . -B $buildDir `
35+
-DCMAKE_BUILD_TYPE=Release `
36+
-DEXECUTORCH_BUILD_VULKAN=ON `
37+
-DPYTHON_EXECUTABLE=python
38+
39+
if ($LASTEXITCODE -ne 0) {
40+
Write-Host "CMake configuration failed. Exit code: $LASTEXITCODE."
41+
exit $LASTEXITCODE
42+
}
43+
44+
cmake --build $buildDir --config Release --target vulkan_backend -j16
45+
46+
if ($LASTEXITCODE -ne 0) {
47+
Write-Host "Vulkan backend MSVC build failed. Exit code: $LASTEXITCODE."
48+
exit $LASTEXITCODE
49+
}
50+
51+
Write-Host "Vulkan backend MSVC build completed successfully!"

‎.ci/scripts/test_backend.sh‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,15 @@ if [[ "$FLOW" == *qnn* ]]; then
5151
fi
5252

5353
if [[ "$FLOW" == *vulkan* ]]; then
54-
# Setup swiftshader and Vulkan SDK which are required to build the Vulkan delegate.
55-
source .ci/scripts/setup-vulkan-linux-deps.sh
54+
# Setup the Vulkan SDK and select an ICD: use the real system GPU ICD when one
55+
# is present (real-GPU runner), otherwise fall back to SwiftShader (CPU
56+
# runner). The Vulkan loader searches both standard ICD directories.
57+
if ls /etc/vulkan/icd.d/*.json /usr/share/vulkan/icd.d/*.json \
58+
>/dev/null 2>&1; then
59+
source .ci/scripts/setup-vulkan-linux-deps.sh "real-gpu"
60+
else
61+
source .ci/scripts/setup-vulkan-linux-deps.sh "swiftshader"
62+
fi
5663

5764
EXTRA_BUILD_ARGS+=" -DEXECUTORCH_BUILD_VULKAN=ON"
5865
fi

‎.ci/scripts/wheel/pre_build_script.sh‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,37 @@ if [[ "$(uname -s)" == "Linux" && "$(uname -m)" == "x86_64" ]]; then
6969
echo "QNN_SDK_ROOT=${QNN_SDK_ROOT}" >> "${GITHUB_ENV}"
7070
echo "QNN SDK downloaded to ${QNN_SDK_ROOT}"
7171
fi
72+
73+
# Provision the Vulkan SDK (glslc) and submodules ONLY when explicitly requested
74+
# via EXECUTORCH_BUILD_VULKAN. The default wheel build leaves this unset, so it
75+
# does no extra work (no submodule fetch, no SDK download) and is unaffected.
76+
if [[ "${EXECUTORCH_BUILD_VULKAN:-0}" != "0" \
77+
&& "${EXECUTORCH_BUILD_VULKAN:-OFF}" != "OFF" ]]; then
78+
echo "Initializing Vulkan backend third-party submodules..."
79+
VULKAN_SUBMODULES=(
80+
backends/vulkan/third-party/Vulkan-Headers
81+
backends/vulkan/third-party/volk
82+
backends/vulkan/third-party/VulkanMemoryAllocator
83+
)
84+
if [[ $UNAME_S == *"MINGW"* || $UNAME_S == *"MSYS"* ]]; then
85+
git -c http.sslBackend=openssl submodule update --init "${VULKAN_SUBMODULES[@]}"
86+
echo "Installing Vulkan SDK for Windows wheel build..."
87+
powershell -ExecutionPolicy Bypass -File .ci/scripts/setup-vulkan-windows-deps.ps1
88+
else
89+
git submodule update --init "${VULKAN_SUBMODULES[@]}"
90+
echo "Installing Vulkan SDK for Linux wheel build..."
91+
VULKAN_SDK_VERSION="1.4.341.1"
92+
_vulkan_sdk_url="https://sdk.lunarg.com/sdk/download/${VULKAN_SDK_VERSION}/linux/vulkansdk-linux-x86_64-${VULKAN_SDK_VERSION}.tar.xz"
93+
_vulkan_sdk_dir="${HOME}/.vulkan-sdk/${VULKAN_SDK_VERSION}"
94+
mkdir -p "${_vulkan_sdk_dir}"
95+
curl --silent --show-error --location --fail --retry 3 --retry-all-errors \
96+
--output /tmp/vulkansdk.tar.xz "${_vulkan_sdk_url}"
97+
tar -C "${_vulkan_sdk_dir}" -xJf /tmp/vulkansdk.tar.xz
98+
VULKAN_SDK="${_vulkan_sdk_dir}/${VULKAN_SDK_VERSION}/x86_64"
99+
export VULKAN_SDK
100+
export PATH="${VULKAN_SDK}/bin:${PATH}"
101+
echo "VULKAN_SDK=${VULKAN_SDK}" >> "${GITHUB_ENV}"
102+
echo "${VULKAN_SDK}/bin" >> "${GITHUB_PATH}"
103+
echo "Vulkan SDK installed to ${VULKAN_SDK}"
104+
fi
105+
fi

‎.ci/scripts/wheel/test_linux.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@
3131
), f"OpenvinoBackend not found in registered backends: {registered}"
3232
print("✓ OpenvinoBackend is registered")
3333

34+
# Vulkan backend is optional: only present when the wheel was built with
35+
# EXECUTORCH_BUILD_VULKAN=1 and the Vulkan SDK (glslc) was available.
36+
if "VulkanBackend" in registered:
37+
print("✓ VulkanBackend is registered")
38+
else:
39+
print("⚠ VulkanBackend not registered (expected for the default wheel)")
40+
3441
test_base.run_tests(
3542
model_tests=[
3643
test_base.ModelTest(

‎.ci/scripts/wheel/test_windows.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
# This source code is licensed under the BSD-style license found in the
66
# LICENSE file in the root directory of this source tree.
77

8+
import platform
89
from typing import List
910

1011
import torch
@@ -15,6 +16,7 @@
1516
from executorch.examples.xnnpack.quantization.utils import quantize as quantize_xnn
1617
from executorch.exir import EdgeCompileConfig, to_edge_transform_and_lower
1718
from executorch.extension.pybindings.portable_lib import (
19+
_get_registered_backend_names,
1820
_load_for_executorch_from_buffer,
1921
)
2022
from test_base import ModelTest
@@ -63,6 +65,15 @@ def run_tests(model_tests: List[ModelTest]) -> None:
6365

6466

6567
if __name__ == "__main__":
68+
if platform.system() == "Windows":
69+
registered = _get_registered_backend_names()
70+
# Vulkan backend is optional: only present when the wheel was built with
71+
# EXECUTORCH_BUILD_VULKAN=1 and the Vulkan SDK (glslc) was available.
72+
if "VulkanBackend" in registered:
73+
print("✓ VulkanBackend is registered")
74+
else:
75+
print("⚠ VulkanBackend not registered (expected for the default wheel)")
76+
6677
run_tests(
6778
model_tests=[
6879
ModelTest(

‎.github/workflows/test-backend-vulkan.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ concurrency:
1717
cancel-in-progress: true
1818

1919
jobs:
20+
# Default coverage: builds + runs on SwiftShader (software Vulkan) on CPU
21+
# runners. Runs on every PR and nightly.
2022
test-vulkan:
2123
uses: ./.github/workflows/_test_backend.yml
2224
with:
@@ -28,3 +30,6 @@ jobs:
2830
ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
2931
timeout: 120
3032
run-linux: true
33+
34+
# Real-GPU (NVIDIA) and Windows MSVC coverage live in vulkan.yml, which gates
35+
# those scarce/expensive runners behind path filtering.

‎.github/workflows/vulkan.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
name: Test Vulkan Backend (specialized runners)
2+
3+
# Vulkan CI jobs that require special runners (an NVIDIA GPU, or a Windows
4+
# MSVC toolchain). These are separate from test-backend-vulkan.yml (which runs the
5+
# default SwiftShader coverage on standard runners) so that they're only run
6+
# when Vulkan related files change.
7+
8+
on:
9+
push:
10+
branches:
11+
- main
12+
- release/*
13+
tags:
14+
- ciflow/nightly/*
15+
pull_request:
16+
paths:
17+
- .github/workflows/vulkan.yml
18+
- backends/vulkan/**
19+
- examples/vulkan/**
20+
- .ci/scripts/setup-vulkan-linux-deps.sh
21+
- .ci/scripts/setup-vulkan-windows-deps.ps1
22+
- .ci/scripts/setup-windows-msvc-vulkan.ps1
23+
workflow_dispatch:
24+
25+
concurrency:
26+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}-${{ github.event_name == 'workflow_dispatch' }}
27+
cancel-in-progress: true
28+
29+
permissions:
30+
contents: read
31+
32+
jobs:
33+
changed-files:
34+
name: Get changed files
35+
uses: ./.github/workflows/_get-changed-files.yml
36+
with:
37+
include-push-diff: true # so push commits can also be path-filtered
38+
39+
run-decision:
40+
name: CI run decision
41+
uses: ./.github/workflows/_ci-run-decision.yml
42+
43+
test-vulkan-nvidia:
44+
needs: [changed-files, run-decision]
45+
# Path-filtered: skip commits that don't touch Vulkan-relevant paths, except
46+
# on sampled full runs (see _ci-run-decision.yml).
47+
if: |
48+
contains(needs.changed-files.outputs.changed-files, 'backends/vulkan/') ||
49+
contains(needs.changed-files.outputs.changed-files, 'examples/vulkan/') ||
50+
contains(needs.changed-files.outputs.changed-files, '.ci/scripts/setup-vulkan-linux-deps.sh') ||
51+
contains(needs.changed-files.outputs.changed-files, '.github/workflows/vulkan.yml') ||
52+
needs.run-decision.outputs.is-full-run == 'true'
53+
uses: pytorch/test-infra/.github/workflows/linux_job_v2.yml@main
54+
permissions:
55+
id-token: write
56+
contents: read
57+
with:
58+
timeout: 120
59+
runner: linux.g5.4xlarge.nvidia.gpu
60+
gpu-arch-type: cuda
61+
gpu-arch-version: "12.6"
62+
use-custom-docker-registry: false
63+
submodules: recursive
64+
ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
65+
script: |
66+
set -eux
67+
68+
# Install the Vulkan SDK (glslc) and select a real system ICD. The NVIDIA
69+
# driver on this runner provides the ICD; install the loader as well.
70+
# NOTE: first-run check - inspect the vulkaninfo output below to confirm a
71+
# real NVIDIA device is selected (not llvmpipe/SwiftShader). If no system
72+
# ICD is present, setup-vulkan-linux-deps.sh falls back to SwiftShader.
73+
sudo apt-get update && sudo apt-get install -y libvulkan1 vulkan-tools || true
74+
source .ci/scripts/setup-vulkan-linux-deps.sh real-gpu
75+
vulkaninfo --summary || true
76+
77+
# Full from-source install. Unlike the SwiftShader jobs in pull.yml, the
78+
# CUDA runner image does not pre-install ExecuTorch's dependencies, so
79+
# setup-linux.sh's "deps already in the image" assumption does not hold.
80+
# CMAKE_ARGS enables Vulkan in the pybindings so the model --test runs and
81+
# the pt2e/torchao e2e tests below execute on the GPU (default is OFF).
82+
CMAKE_ARGS="-DEXECUTORCH_BUILD_VULKAN=ON" PYTHON_EXECUTABLE=python ./install_executorch.sh
83+
84+
# Model coverage (mirrors test-vulkan-models-linux, on real hardware).
85+
PYTHON_EXECUTABLE=python bash backends/vulkan/test/scripts/test_model.sh --build
86+
87+
models="mv2 mv3 edsr resnet18 resnet50 dl3 w2l ic3 ic4"
88+
for model in $models; do
89+
python -m examples.vulkan.export --model_name=$model --test
90+
done
91+
92+
# For selected vision models, test with dynamic shapes
93+
models="mv2 resnet18 resnet50 ic3 densenet161"
94+
for model in $models; do
95+
python -m examples.vulkan.export --model_name=$model --test -d
96+
done
97+
98+
# Operator coverage (mirrors test-vulkan-operators-linux, on real hardware).
99+
PYTHON_EXECUTABLE=python bash backends/vulkan/test/custom_ops/build_and_run.sh test_add
100+
./cmake-out/backends/vulkan/test/custom_ops/test_q8csw_linear
101+
./cmake-out/backends/vulkan/test/custom_ops/test_q8csw_conv2d
102+
./cmake-out/backends/vulkan/test/custom_ops/test_q4gsw_linear
103+
./cmake-out/backends/vulkan/test/custom_ops/test_choose_qparams_per_row
104+
./cmake-out/backends/vulkan/test/custom_ops/test_q8ta_qdq
105+
./cmake-out/backends/vulkan/test/custom_ops/test_q8ta_clone
106+
./cmake-out/backends/vulkan/test/custom_ops/test_q8ta_binary
107+
108+
PYTHON_EXECUTABLE=python bash backends/vulkan/test/scripts/test_op.sh --build
109+
110+
# Run e2e testing for selected operators.
111+
python -m unittest backends/vulkan/test/test_vulkan_delegate.py -k "*pt2e*"
112+
python -m unittest backends/vulkan/test/test_vulkan_delegate.py -k "*torchao*"
113+
114+
build-vulkan-windows-msvc:
115+
needs: [changed-files, run-decision]
116+
if: |
117+
contains(needs.changed-files.outputs.changed-files, 'backends/vulkan/') ||
118+
contains(needs.changed-files.outputs.changed-files, '.ci/scripts/setup-vulkan-windows-deps.ps1') ||
119+
contains(needs.changed-files.outputs.changed-files, '.ci/scripts/setup-windows-msvc-vulkan.ps1') ||
120+
contains(needs.changed-files.outputs.changed-files, '.github/workflows/vulkan.yml') ||
121+
needs.run-decision.outputs.is-full-run == 'true'
122+
name: build-vulkan-windows-msvc
123+
uses: pytorch/test-infra/.github/workflows/windows_job.yml@main
124+
with:
125+
ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
126+
timeout: 90
127+
script: |
128+
git config --global http.sslBackend openssl
129+
git submodule update --init backends/vulkan/third-party/Vulkan-Headers backends/vulkan/third-party/volk backends/vulkan/third-party/VulkanMemoryAllocator
130+
git submodule update --init
131+
conda init powershell
132+
powershell -Command "& {
133+
Set-PSDebug -Trace 1
134+
\$ErrorActionPreference = 'Stop'
135+
\$PSNativeCommandUseErrorActionPreference = \$true
136+
.ci/scripts/setup-windows-msvc-vulkan.ps1
137+
}"

0 commit comments

Comments
 (0)