Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit a4bf709

Browse files
benvanikbenvanik
committed
[Vulkan] Document device compatibility
1 parent b46def4 commit a4bf709

10 files changed

Lines changed: 74 additions & 23 deletions

File tree

‎docs/website/docs/developers/vulkan-environment-setup.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,12 @@ function together.
103103

104104
### Android
105105

106-
Please make sure your Android device is Vulkan capable. Vulkan is supported on
107-
Android since 7, but we track newer Android versions (10+) closely and haven't
108-
set a clear min version yet.
106+
Please make sure your Android device is Vulkan capable and exposes the features
107+
required by the IREE Vulkan HAL. IREE's current runtime baseline is Vulkan 1.3
108+
with compute queues, timeline semaphores, scalar block layout, and
109+
synchronization2. Android version alone is not enough to determine
110+
compatibility; use `vulkaninfo` or `iree-run-module --dump_devices` on the
111+
device to inspect the selected physical device.
109112

110113
## Multiple Vulkan SDKs
111114

‎docs/website/docs/guides/deployment-configurations/gpu-vulkan.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,16 +29,51 @@ Qualcomm Adreno GPU | Mobile | Reasonable | 640+
2929
AMD GPU | Desktop/server | Good | RDNA+
3030
NVIDIA GPU | Desktop/server | Reasonable | Turing+
3131

32+
## :octicons-cpu-16: Device compatibility
33+
34+
IREE's Vulkan HAL targets modern compute-capable Vulkan implementations. The
35+
runtime baseline is Vulkan 1.3 with a compute queue and the
36+
`timelineSemaphore`, `scalarBlockLayout`, and `synchronization2` device
37+
features. Devices missing that baseline still appear in device dumps, but are
38+
reported below the supported feature tier and are not selected for execution.
39+
40+
Descriptor-set dispatch is the portable baseline executable ABI. Buffer device
41+
address (BDA) dispatch is an optional faster ABI used when the device exposes
42+
`bufferDeviceAddress` and the program was compiled with BDA support. The
43+
runtime default accepts all supported executable ABI variants and prefers BDA
44+
when available; descriptor executables remain the fallback for devices without
45+
BDA.
46+
47+
Other Vulkan features are enabled opportunistically when the implementation
48+
reports them:
49+
50+
* `VK_KHR_push_descriptor` reduces descriptor allocation and update overhead.
51+
* `VK_EXT_calibrated_timestamps` enables device-side queue and dispatch timing
52+
in IREE HAL profile captures.
53+
* External memory extensions enable native interop and file/staging strategies
54+
when the platform and driver expose compatible handle types.
55+
* Sparse binding and residency features are used only when explicitly requested
56+
and supported by an appropriate queue family.
57+
* Validation layers, debug utils, robust buffer access, object names, and
58+
command labels are debug/profiling features rather than execution
59+
requirements.
60+
61+
Use `iree-run-module --dump_devices` to inspect the exact Vulkan API version,
62+
feature tier, device features, queues, and enabled extension opportunities for a
63+
machine. A supported device reports `feature_tier[vulkan-1.3]: supported`.
64+
3265
## :octicons-download-16: Prerequisites
3366

3467
In order to use Vulkan to drive the GPU, you need to have a functional Vulkan
35-
environment. IREE requires Vulkan 1.1 on Android and 1.2 elsewhere. It can be
36-
verified by the following steps:
68+
environment. IREE requires a device satisfying the Vulkan 1.3 baseline above.
69+
It can be verified by the following steps:
3770

3871
=== "Android"
3972

40-
Android mandates Vulkan 1.1 support since Android 10. You just need to
41-
make sure the device's Android version is 10 or higher.
73+
Android version alone is not enough to determine IREE compatibility. Run
74+
`vulkaninfo` or `iree-run-module --dump_devices` on the device and verify
75+
that the selected physical device reports Vulkan 1.3 and the required
76+
baseline features.
4277

4378
=== ":fontawesome-brands-linux: Linux"
4479

@@ -53,7 +88,7 @@ verified by the following steps:
5388
repository is recommended, as it places Vulkan libraries and tools under
5489
system paths so it's easy to discover.
5590

56-
If the listed version is lower than Vulkan 1.2, you will need to update the
91+
If the listed version is lower than Vulkan 1.3, you will need to update the
5792
driver for your GPU.
5893

5994
=== ":fontawesome-brands-windows: Windows"
@@ -67,7 +102,7 @@ verified by the following steps:
67102
If `vulkaninfo` does not exist, you will need to [install the latest Vulkan
68103
SDK](https://vulkan.lunarg.com/sdk/home/).
69104

70-
If the listed version is lower than Vulkan 1.2, you will need to update the
105+
If the listed version is lower than Vulkan 1.3, you will need to update the
71106
driver for your GPU.
72107

73108
### Get the IREE compiler
@@ -158,15 +193,27 @@ With the requirements out of the way, we can now compile a model and run it.
158193

159194
Then run the following command to compile with the `vulkan` target device:
160195

161-
``` shell hl_lines="2 3"
196+
``` shell hl_lines="2 3 4"
162197
iree-compile \
163198
--iree-hal-target-device=vulkan \
199+
--iree-vulkan-dispatch-abi=all \
164200
--iree-vulkan-target=<...> \
165201
mobilenetv2.mlir -o mobilenet_vulkan.vmfb
166202
```
167203

168204
--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
169205

206+
`--iree-vulkan-dispatch-abi` controls which Vulkan executable ABI variants are
207+
emitted:
208+
209+
* `descriptors` emits the portable descriptor-set ABI.
210+
* `bda` emits only the BDA root binding table ABI.
211+
* `all` emits all supported ABI variants in runtime preference order.
212+
213+
Use `all` when producing a program intended to run across multiple Vulkan
214+
devices. Use `bda` only when the deployment fleet is known to support
215+
`bufferDeviceAddress`.
216+
170217
#### Choosing Vulkan targets
171218

172219
The `--iree-vulkan-target` specifies the GPU architecture to target. It

‎runtime/src/iree/hal/drivers/vulkan/api.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ typedef enum iree_hal_vulkan_feature_bits_t {
9090
IREE_HAL_VULKAN_FEATURE_ENABLE_SCALAR_BLOCK_LAYOUT = 1u << 9,
9191
// Requests and reports subgroup size control on a logical device.
9292
IREE_HAL_VULKAN_FEATURE_ENABLE_SUBGROUP_SIZE_CONTROL = 1u << 10,
93-
// Required enabled logical-device feature set for the rewrite baseline.
93+
// Required enabled logical-device feature set for the Vulkan HAL baseline.
9494
IREE_HAL_VULKAN_FEATURE_REQUIRED_BASELINE =
9595
IREE_HAL_VULKAN_FEATURE_ENABLE_TIMELINE_SEMAPHORES |
9696
IREE_HAL_VULKAN_FEATURE_ENABLE_SYNCHRONIZATION2 |

‎runtime/src/iree/hal/drivers/vulkan/buffer.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ iree_status_t iree_hal_vulkan_buffer_handle(iree_hal_buffer_t* buffer,
364364
}
365365
if (!iree_hal_vulkan_buffer_isa(allocated_buffer)) {
366366
return iree_make_status(IREE_STATUS_FAILED_PRECONDITION,
367-
"buffer is not backed by the Vulkan HAL rewrite");
367+
"buffer is not backed by the Vulkan HAL");
368368
}
369369
iree_hal_vulkan_buffer_t* vulkan_buffer =
370370
iree_hal_vulkan_buffer_cast(allocated_buffer);
@@ -388,7 +388,7 @@ iree_status_t iree_hal_vulkan_buffer_device_address(
388388
}
389389
if (!iree_hal_vulkan_buffer_isa(allocated_buffer)) {
390390
return iree_make_status(IREE_STATUS_FAILED_PRECONDITION,
391-
"buffer is not backed by the Vulkan HAL rewrite");
391+
"buffer is not backed by the Vulkan HAL");
392392
}
393393
iree_hal_vulkan_buffer_t* vulkan_buffer =
394394
iree_hal_vulkan_buffer_cast(allocated_buffer);

‎runtime/src/iree/hal/drivers/vulkan/command_buffer.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -531,7 +531,7 @@ static iree_status_t iree_hal_vulkan_command_buffer_resolve_native_buffer_ref(
531531
return iree_make_status(
532532
IREE_STATUS_FAILED_PRECONDITION,
533533
"Vulkan command buffer %.*s buffer reference is not backed by the "
534-
"Vulkan HAL rewrite",
534+
"Vulkan HAL",
535535
(int)usage.size, usage.data);
536536
}
537537

‎runtime/src/iree/hal/drivers/vulkan/cts/BUILD.bazel‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# See https://llvm.org/LICENSE.txt for license information.
55
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
66

7-
# Focused CTS coverage for the Vulkan HAL rewrite.
7+
# Focused CTS coverage for the Vulkan HAL.
88

99
load("//build_tools/bazel:build_defs.oss.bzl", "iree_runtime_cc_library", "iree_runtime_cc_test")
1010
load("//build_tools/bazel:iree_hal_cts_test_suite.bzl", "iree_hal_cts_testdata")

‎runtime/src/iree/hal/drivers/vulkan/cts/backends.cc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// See https://llvm.org/LICENSE.txt for license information.
55
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
66

7-
// CTS backend registration for the Vulkan HAL rewrite.
7+
// CTS backend registration for the Vulkan HAL.
88

99
#include "iree/hal/api.h"
1010
#include "iree/hal/cts/util/registry.h"

‎runtime/src/iree/hal/drivers/vulkan/logical_device.c‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,8 @@ static iree_status_t iree_hal_vulkan_select_physical_device(
215215
} else {
216216
status = iree_make_status(
217217
IREE_STATUS_UNAVAILABLE,
218-
"Vulkan physical device %u does not satisfy the rewrite baseline",
218+
"Vulkan physical device %u does not satisfy the Vulkan 1.3 "
219+
"baseline",
219220
i);
220221
}
221222
}
@@ -228,7 +229,7 @@ static iree_status_t iree_hal_vulkan_select_physical_device(
228229
case IREE_HAL_VULKAN_PHYSICAL_DEVICE_SELECTOR_DEFAULT:
229230
status = iree_make_status(
230231
IREE_STATUS_UNAVAILABLE,
231-
"no Vulkan physical device satisfies the rewrite baseline");
232+
"no Vulkan physical device satisfies the Vulkan 1.3 baseline");
232233
break;
233234
case IREE_HAL_VULKAN_PHYSICAL_DEVICE_SELECTOR_ID:
234235
status = iree_make_status(IREE_STATUS_NOT_FOUND,
@@ -908,7 +909,7 @@ static iree_hal_vulkan_logical_device_t* iree_hal_vulkan_logical_device_cast(
908909
static iree_status_t iree_hal_vulkan_unimplemented(
909910
iree_string_view_t operation) {
910911
return iree_make_status(IREE_STATUS_UNIMPLEMENTED,
911-
"Vulkan %.*s is not implemented in the rewrite HAL",
912+
"Vulkan %.*s is not implemented in the Vulkan HAL",
912913
(int)operation.size, operation.data);
913914
}
914915

@@ -2277,7 +2278,7 @@ static iree_status_t iree_hal_vulkan_verify_external_enabled_features(
22772278
if (!iree_hal_vulkan_physical_device_supports_baseline(snapshot)) {
22782279
return iree_make_status(
22792280
IREE_STATUS_UNAVAILABLE,
2280-
"external Vulkan physical device does not satisfy the rewrite "
2281+
"external Vulkan physical device does not satisfy the Vulkan 1.3 "
22812282
"baseline");
22822283
}
22832284
if (iree_all_bits_set(enabled_features,

‎runtime/src/iree/hal/drivers/vulkan/physical_device.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ void iree_hal_vulkan_physical_device_snapshot_deinitialize(
160160
bool iree_hal_vulkan_physical_device_has_compute_queue(
161161
const iree_hal_vulkan_physical_device_snapshot_t* snapshot);
162162

163-
// Returns true if |snapshot| satisfies the current Vulkan rewrite baseline.
163+
// Returns true if |snapshot| satisfies the current Vulkan HAL baseline.
164164
bool iree_hal_vulkan_physical_device_supports_baseline(
165165
const iree_hal_vulkan_physical_device_snapshot_t* snapshot);
166166

‎runtime/src/iree/hal/drivers/vulkan/queue.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8394,7 +8394,7 @@ static iree_status_t iree_hal_vulkan_queue_resolve_dispatch_descriptor_binding(
83948394
!iree_hal_vulkan_sparse_buffer_isa(allocated_buffer)) {
83958395
return iree_make_status(IREE_STATUS_FAILED_PRECONDITION,
83968396
"Vulkan queue_dispatch binding %" PRIhsz
8397-
" buffer is not backed by the Vulkan HAL rewrite",
8397+
" buffer is not backed by the Vulkan HAL",
83988398
binding_ordinal);
83998399
}
84008400

@@ -8503,7 +8503,7 @@ static iree_status_t iree_hal_vulkan_queue_resolve_dispatch_indirect_parameters(
85038503
return iree_make_status(
85048504
IREE_STATUS_FAILED_PRECONDITION,
85058505
"Vulkan queue_dispatch indirect workgroup parameter buffer is not "
8506-
"backed by the Vulkan HAL rewrite");
8506+
"backed by the Vulkan HAL");
85078507
}
85088508

85098509
VkDeviceMemory memory = VK_NULL_HANDLE;

0 commit comments

Comments
 (0)