docs/GetStarted/getting_started_windows_vulkan.md

# Getting Started on Windows with Vulkan

[Vulkan](https://www.khronos.org/vulkan/) is a new generation graphics and
compute API that provides high-efficiency, cross-platform access to modern GPUs
used in a wide variety of devices from PCs and consoles to mobile phones and
embedded platforms.

IREE includes a Vulkan/[SPIR-V](https://www.khronos.org/registry/spir-v/) HAL
backend designed for executing advanced ML models in a deeply pipelined and
tightly integrated fashion on accelerators like GPUs.

This guide will walk you through using IREE's compiler and runtime Vulkan
components. For generic Vulkan development environment set up and trouble
shooting, please see [this doc](generic_vulkan_env_setup.md).

## Prerequisites

You should already have IREE cloned and building on your Windows machine. See
the [Getting Started on Windows with CMake](getting_started_windows_cmake.md) or
[Getting Started on Windows with Bazel](getting_started_windows_bazel.md) guide
for instructions.

You must have a physical GPU with drivers supporting Vulkan. We support using
[SwiftShader](https://swiftshader.googlesource.com/SwiftShader/) (a high
performance CPU-based implementation of Vulkan) on platforms where the
[Vulkan-ExtensionLayer](https://github.com/KhronosGroup/Vulkan-ExtensionLayer)
project builds, but it does not currently
[build on Windows](https://github.com/KhronosGroup/Vulkan-ExtensionLayer/issues/16).

Vulkan API version > 1.2 is recommended where available, though older versions
with support for the `VK_KHR_timeline_semaphore` extension may also work.

## Vulkan Setup

### Background

Please see
[Generic Vulkan Development Environment Setup and Troubleshooting](generic_vulkan_env_setup.md)
for generic Vulkan concepts and development environment setup.

### Quick Start

The
[dynamic_symbols_test](https://github.com/google/iree/blob/master/iree/hal/vulkan/dynamic_symbols_test.cc)
checks if the Vulkan loader and a valid ICD are accessible.

Run the test:

```powershell
# -- CMake --
> set VK_LOADER_DEBUG=all
> cmake --build build\ --target iree_hal_vulkan_dynamic_symbols_test
> .\build\iree\hal\vulkan\iree_hal_vulkan_dynamic_symbols_test.exe

# -- Bazel --
> bazel test iree/hal/vulkan:dynamic_symbols_test --test_env=VK_LOADER_DEBUG=all
```

Tests in IREE's HAL "Conformance Test Suite" (CTS) actually exercise the Vulkan
HAL, which includes checking for supported layers and extensions.

Run the
[device creation test](https://github.com/google/iree/blob/master/iree/hal/cts/device_creation_test.cc):

```powershell
# -- CMake --
> set VK_LOADER_DEBUG=all
> cmake --build build\ --target iree_hal_cts_device_creation_test
> .\build\iree\hal\cts\iree_hal_cts_device_creation_test.exe

# -- Bazel --
> bazel test iree/hal/cts:device_creation_test --test_env=VK_LOADER_DEBUG=all --test_output=all
```

If these tests pass, you can skip down to the next section.

### Setting up the Vulkan Loader

IREE relies on the `VK_KHR_timeline_semaphore` extension. The minimal loader
version supporting this extenion is `1.1.124`. So if you see failures regarding
timeline semaphore, please also check to make sure the loader is at a proper
version.

<!--
### Setting up SwiftShader

TODO(scotttodd): Document when SwiftShader supports `VK_KHR_timeline_semaphore`
                 Or Vulkan-ExtensionLayer builds for Windows

### Setting up Vulkan-ExtensionLayer

TODO(scotttodd): Document when Vulkan-ExtensionLayer builds for Windows
-->

## Using IREE's Vulkan Compiler Target and Runtime Driver

### Compiling for the Vulkan HAL

Pass the flag `-iree-hal-target-backends=vulkan-spirv` to `iree-translate.exe`:

```powershell
# -- CMake --
> cmake --build build\ --target iree_tools_iree-translate
> .\build\iree\tools\iree-translate.exe -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb

# -- Bazel --
> bazel run iree/tools:iree-translate -- -iree-mlir-to-vm-bytecode-module -iree-hal-target-backends=vulkan-spirv .\iree\tools\test\simple.mlir -o .\build\module.fb
```

> Tip:<br>
> &nbsp;&nbsp;&nbsp;&nbsp;If successful, this may have no output. You can pass
> other flags like `-print-ir-after-all` to control the program.

### Executing modules with the Vulkan driver

Pass the flag `-driver=vulkan` to `iree-run-module.exe`:

```powershell
# -- CMake --
> cmake --build build\ --target iree_tools_iree-run-module
> .\build\iree\tools\iree-run-module.exe -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"

# -- Bazel --
> bazel run iree/tools:iree-run-module -- -input_file=.\build\module.fb -driver=vulkan -entry_function=abs -inputs="i32=-2"
```

## Running IREE's Vulkan Samples

Install the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/), then run:

```powershell
# -- CMake --
> cmake --build build\ --target iree_samples_vulkan_vulkan_inference_gui
> .\build\iree\samples\vulkan\vulkan_inference_gui.exe

# -- Bazel --
> bazel run iree/samples/vulkan:vulkan_inference_gui
```

## What's next?

More documentation coming soon...

<!-- TODO(scotttodd): link to Vulkan debugging, developer guides -->