Copyright © 2015-2020 LunarG, Inc.
This document is an overview of how to use the LunarG Vulkan Installation Analyzer (VIA).
VIA is a tool that can:
- Determine the state of Vulkan components on your system
- Validate that your Vulkan Loader and drivers are installed properly
- Capture your system state in a form that can be used as an attachment when submitting bugs
This document describes where to find the source for VIA, building it, running it, and how to understand the resulting command line output that is generated. VIA is pre-built and delivered with the Vulkan SDK. As well, it can be invoked from the Vulkan Configurator included with the Vulkan SDK.
Many components of the Vulkan SDK are Open Source, including VIA. VIA is currently part of the LunarG VulkanTools GitHub respository.
Note: VIA is already pre-built as part of the Windows and MacOS Vulkan SDK, but should you wish to build a debug version or find the source, this section should provide you with the information you need. Otherwise, simply skip down to the "Running" section below.
Because it is part of a group of tools, you build it from the top folder by following the instructions in the VulkanTools/BUILD.md file at the top of the source tree.
The source for VIA can also be found in the Linux Vulkan SDK in the "source/via" directory.
- Download and install the Linux SDK
- Run "source setup-env.sh" in the SDK root directory
- Run "./vulkansdk lunarg-tools"
You will find the VIA binary in a different location depending on which OS you are using and whether you have built it, or installed it as part of the SDK. The following information states where to find the proper executable.
When running, if VIA detects an installed Vulkan SDK, it will attempt to run the Vulkan Cube demo in several ways to make sure the install truly appears valid. The first run of Vulkan Cube it attempts will run in the standard way, but only for a few frames. After that completes, it will attempt to run Vulkan Cube with validation enabled, again, for only a few frames. Because of this, you may notice Vulkan Cube popping up several times while running VIA. When it has completed the tests, it will then record the results as normal to the HTML file.
Please note that if you are trying to diagnose a troublesome application, the best way to run VIA to assist in diagnosis is to change to the location of the application, and run via in that folder locally (by typing in a relative or absolute path to the vkvia executable).
VIA is installed into your start menu as part of the Windows Vulkan SDK. Simply open your start menu, search for the "Vulkan SDK" and click "VIA". This will output the resulting vkvia.html directly to your desktop.
If you need to run VIA from the command-line, you will find it in your SDK folder (defined by the environment variable "VULKAN_SDK") under the "Bin" folder for 64-bit executables, and "Bin32" folder for 32-bit executables. From there, simply run:
vkvia.exe
Once built, VIA can be found in the x86_64/bin directory. You can simply execute it from there using:
vkvia
VIA can be found in the macOS/bin directory. You can simply execute it from there using:
vkvia
Go into the folder where you generated the build items from the above building step.
Linux and MacOS
Simply run:
vkvia
Windows
Windows has an additional required step to perform if you are building from VulkanTools before you can run VIA in the proper way. This is because the CMake scripts have an important folder being copied one level too low. To run, the first time you will have to copy this folder into the appropriate location.
Steps to run the first time:
- Go into the folder you built, and then go into the "via" sub-folder.
- In this folder you should see an "images" folder. Copy this into either or both of your "Debug" or "Release" folders.
- Go into the "Debug" or "Release" folder (whichever you are desiring to work with)
- Run
vkvia.exe
After the first time, you just need to go into the folder and re-run "vkvia.exe".
VIA outputs two things:
- A command-line output indicating the overall status
- An HTML file (called vkvia.html) containing the details which will be output to one of two locations:
- If the current directory is writable, the HTML will be placed in that location.
- Otherwise, it will be saved to your home folder, except for the Windows Start Menu short-cut which writes the file to your desktop.
Your home folder is the following location (based on your OS):
- Windows: Wherever your environment variables %HOMEDRIVE%%HOMEPATH% point to.
- Linux and MacOS: It will be placed in your home folder ("~/.").
There are additional command-line parameters which can be used. These simply augment existing behavior and do not capture any more information. The available command-line arguments are:
The --unique_output argument, if provided, will cause the output html to be generated with a date/time suffix. This will allow you to perform multiple state captures on your system without accidentally erasing previous results. The new file has the following format:
via_YYYY_MM_DD_HH_MM.html
Where each component stands for the numeric values for year (YYYY), month (MM), day (DD), hour (HH), and minute (MM).
The --output_path arument allows the user to specify a location for the output html file. For
example, if the user runs via --output_path /home/me/Documents, then the output file will be
/home/me/Documents/vkvia.html.
LunarG's VIA could detect no problems with your setup. In fact it was able to create an instance and device up through Vulkan version X.Y.
Your system is likely set up properly. If you have trouble running Vulkan from another location, it could be that your environment variables aren't set up properly.
Re-run VIA from the location your Vulkan application/game is supposed to run.
LunarG's VIA could detect no problems with your setup other than a missing SDK. It was able to run some limited tests and create both a Vulkan instance and device.
Your system is likely set up properly, but is either missing an installed Vulkan SDK or you didn't set up your environment variable to point at an installed SDK. If you have trouble running Vulkan from another location, it could be that your environment variables aren't set up properly.
Install the Vulkan SDK and define the environment variable to point to the location of the installed SDK. See the getting started guide for your platform on how to set up your environment variables.
This is a Windows-specific error that indicates that no Vulkan Driver JSON files were referenced in the appropriate place in the Windows Registry.
This can indicate that a Vulkan driver failed to install properly.
See the Vulkan Graphics Driver Problems section for more info.
The Vulkan loader on your system failed to find any Vulkan Driver JSON files in the appropriate places.
This can indicate that a Vulkan driver failed to install properly.
See the Vulkan Graphics Driver Problems section for more info.
The Vulkan loader on your system found at least one Vulkan Driver JSON file, but it contained invalid data.
This can indicate that a Vulkan driver failed to install properly.
See the Vulkan Graphics Driver Problems section for more info.
The Vulkan loader on your system found at least one Vulkan Driver JSON file, but the Driver library referenced in that file appears invalid.
This can indicate that a Vulkan driver failed to install properly.
See the Vulkan Graphics Driver Problems section for more info.
Normally a layer isn't a requirement, but in this case a layer was attempted to be used by VIA, which should have existed, and did not exist in the appropriate location.
If the layer is associated with a driver vendor (for example Nvidia), it likely failed during the driver install. If the layer is associated with an application (for example RenderDoc), then it likely failed during application install. Otherwise, it could be an invalid runtime or SDK install.
Look at the HTML file to determine which layer caused the problem, and then contact the appropriate person. If it's an SDK layer, or you are having a hard time figuring out exactly what the problem is, follow the instructions in the Vulkan SDK Issues section below.
Normally a layer isn't a requirement, but in this case a layer was attempted to be used by VIA, and the JSON file was found to be invalid.
If the layer is associated with a driver vendor (for example Nvidia), it likely failed during the driver install. If the layer is associated with an application (for example RenderDoc), then it likely failed during application install. Otherwise, it could be an invalid runtime or SDK install.
Look at the HTML file to determine which layer caused the problem, and then contact the appropriate person. If it's an SDK layer, or you are having a hard time figuring out exactly what the problem is, follow the instructions in the Vulkan SDK Issues section below.
Normally a layer isn't a requirement, but in this case a layer was attempted to be used by VIA, and the JSON file was found to point to an invalid layer library file.
If the layer is associated with a driver vendor (for example Nvidia), it likely failed during the driver install. If the layer is associated with an application (for example RenderDoc), then it likely failed during application install. Otherwise, it could be an invalid runtime or SDK install.
Look at the HTML file to determine which layer caused the problem, and then contact the appropriate person. If it's an SDK layer, or you are having a hard time figuring out exactly what the problem is, follow the instructions in the Vulkan SDK Issues section below.
All the components appeared to be in place to allow Vulkan to load (from an external stand-point), but the loader still failed to find a Vulkan compatible driver.
This can indicate that either a Vulkan driver failed to install properly, or the run-time is failing for some reason.
See the Vulkan Graphics Driver Problems section for more info.
The Vulkan loader "vulkan-1.dll" couldn't be found on your system. This file is typically installed with some Vulkan driver installs, some Vulkan-capable games, or the Vulkan SDK.
The last Vulkan Runtime install that executed on your system failed to behave properly. Or, you have never installed a Vulkan loader on your system.
See the Vulkan SDK Issues section below.
Some error occurred when trying to call Vulkan's vkCreateInstance function.
This can usually indicate that there's something about the installed driver that the Vulkan Loader does not like.
See the Vulkan SDK Issues section below.
Some error occurred when trying to call Vulkan's vkCreateDevice function.
This can usually indicate that there's something about the installed driver that the Vulkan Loader does not like.
See the Vulkan SDK Issues section below.
Some error occurred when trying to query the available drivers for the Vulkan Extensions that are supported.
This can usually indicate that there's something about the installed driver that the Vulkan Loader does not like.
See the Vulkan SDK Issues section below.
The Vulkan Loader, a Layer, or a Vulkan Driver failed to be able to allocate memory for a required item.
Check to see how much memory is available on your system. It could also be caused by low hard-drive space.
Attempt to free up some hard-drive space if you're currently using more that 90% of your hard-drive.
Other things to try:
- Follow the instructions in Vulkan SDK Issues section below.
- If that doesn't help, try installing a new Vulkan Driver
One of the Vulkan tests failed for some reason.
This could just indicate an error in setting up the test environment. Currently, the only tests used are in the SDK, so it's possible the SDK did not install properly.
See the Vulkan SDK Issues section below.
The Vulkan loader "vulkan-1.dll" couldn't be found on your system. This file is typically installed with some Vulkan driver installs, some Vulkan-capable games, or the Vulkan SDK.
The last Vulkan Runtime install that executed on your system failed to behave properly. Or, you have never installed a Vulkan loader on your system.
See the Vulkan SDK Issues section below.
The Vulkan loader "libvulkan.so.1" couldn't be found on your system. This file is typically installed with some Vulkan driver installs, some Vulkan-capable games, or the Vulkan SDK.
- There is no Vulkan loader installed to a system folder.
- The user didn't set up the LD_LIBRARY_PATH environment variable to point to a local folder containing libvulkan.so.1.
export LD_LIBRARY_PATH=/home/<user>/sdk/VulkanSDK/1.0.39.0/x64_86/lib
See the Vulkan SDK Issues section below.
If the problem you've encountered is possibly related to an SDK issue. Visit vulkan.lunarg.com, and install the latest Vulkan SDK. If that does not help, attempt to install a new Vulkan Driver. If that still fails, file an issue at vulkan.lunarg.com. To file an issue, you may be required to create a free account (only requires an email address).
If the problem is possibly related to your Graphics Driver, it could be for several reasons:
- The hardware you have doesn't support Vulkan.
- Your hardware supports Vulkan, but you haven't yet installed a driver with Vulkan support.
- There is no Vulkan driver with support for the OS on which you are currently running.
- Sometimes, the company may provide Vulkan support for some devices on one Operating System (say Windows), while still waiting to complete Vulkan on other systems.
- Everything supports Vulkan, but the driver failed to install properly.
Before approaching your Graphics driver vendor, it would help if you verified that your current driver for your current hardware on your current operating system does support Vulkan.