# 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.

## 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

Vulkan applications interface with Vulkan "drivers", "layers", and "extensions"
through the Vulkan loader. See LunarG's
[Architecture of the Vulkan Loader Interfaces](https://vulkan.lunarg.com/doc/view/latest/windows/loader_and_layer_interface.html)
page for more information.

### 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

If you see failures to find `vulkan-1.dll` (the Vulkan loader), install it by
either:

*   Updating your system's GPU drivers
*   Installing the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/)
*   Building the Vulkan loader
    [from source](https://github.com/KhronosGroup/Vulkan-Loader)

<!--
### 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 -->