Talvos

This project provides a SPIR-V interpreter and Vulkan device emulator, with the aim of providing an extensible dynamic analysis framework and debugger for SPIR-V shaders. Talvos provides an implementation of the Vulkan API to enable it to execute real Vulkan applications. Linux, macOS, and Windows are supported.

Talvos is distributed under a three-clause BSD license. For full license terms please see the LICENSE file distributed with this source code.

Status

Talvos is still in the early stages of development. Compute shaders are the current focus, and Talvos is currently capable of executing various SPIR-V shaders generated from OpenCL kernels compiled with Clspv. Talvos can also handle vertex and fragment shaders, with basic support for offscreen rendering currently in progress. Talvos currently passes around 15% of the Vulkan conformance test suite.

The codebase is changing relatively quickly as new features are added, so the internal and external APIs are all subject to change until we reach the 1.0 release (suggestions for improvements always welcome).

Future work may involve extending the emulator to support tessellation and geometry shaders, onscreen rendering, and implementing missing Vulkan API functions to reach conformance. Contributions in these (or other) areas would be extremely welcome.

Building

More detailed build instructions are provided here.

Building Talvos requires a compiler that supports C++17, and Python to enable the internal test suite. Talvos depends on SPIRV-Headers and SPIRV-Tools, and uses GNU readline to enhance the interactive debugger.

Configure with CMake, indicating where SPIRV-Headers and SPIRV-Tools are installed if necessary:

cmake <path_to_talvos_source>                           \
      -DCMAKE_BUILD_TYPE=Debug                          \
      -DCMAKE_INSTALL_PREFIX=<target_install_directory> \
      -DSPIRV_INCLUDE_DIR=<...>                         \
      -DSPIRV_TOOLS_INCLUDE_DIR=<...>                   \
      -DSPIRV_TOOLS_LIBRARY_DIR=<...>

Using the Debug build type is strongly recommended while Talvos is still in the early stages of development, to enable assertions that guard unimplemented features.

Once configured, use make (or your preferred build tool) to build and install. Run make test to run the internal test suite.

Usage

More detailed usage information is provided here.

Talvos provides an implementation of the Vulkan API which allows existing Vulkan applications to be executed through the emulator without modification. Simply linking an application against libtalvos-vulkan.so or talvos-vulkan.lib is enough for it to use Talvos.

Alternatively, the talvos-cmd command provides a simple interface to the emulator. An example that runs a simple N-Body simulation can be found in test/misc/nbody.tcf.

The following command is used to execute a Talvos command file:

talvos-cmd nbody.tcf

The command file contains commands that allocate and initialize storage buffers and launch SPIR-V shaders. There are also commands that dump the output of storage buffers, to verify that the shader executed as expected.

To enable the interactive debugger, set the environment variable TALVOS_INTERACTIVE=1. This will drop to a prompt when a shader begins executing. Use help to list the available commands, which include step to advance through the interpreter, print to view an instruction result, and switch to change the current invocation.

More information

Raise issues and ask questions via GitHub.

The Talvos documentation provides more detailed information about using Talvos, as well as information for developers.

Doxygen documentation for the source code is also available.