README.md

LLVM/SPIR-V Bi-Directional Translator

This repository contains source code for the LLVM/SPIR-V Bi-Directional Translator, a library and tool for translation between LLVM IR and SPIR-V.

The LLVM/SPIR-V Bi-Directional Translator is open source software. You may freely distribute it under the terms of the license agreement found in LICENSE.txt.

Directory Structure

The files/directories related to the translator:

• include/LLVMSPIRVLib.h - header file
• lib/SPIRV - library for SPIR-V in-memory representation, decoder/encoder and LLVM/SPIR-V translator
• tools/llvm-spirv - command line utility for translating between LLVM bitcode and SPIR-V binary

Build Instructions

Master branch of this repo is aimed to be buildable with the latest LLVM version.

Build with pre-installed LLVM

The translator can be built with the latest(nightly) package of LLVM. For Ubuntu and Debian systems LLVM provides repositories with nightly builds at http://apt.llvm.org/. For example the latest package for Ubuntu 16.04 can be installed with the following commands:

sudo add-apt-repository "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial main"
sudo apt-get update
sudo apt-get install llvm-7-dev

The intalled version of LLVM will be used by default for out-of-tree build of the translator.

git clone https://github.com/KhronosGroup/SPIRV-LLVM-Translator.git
mkdir SPIRV-LLVM-Translator/build && cd SPIRV-LLVM-Translator/build
cmake ..
make llvm-spirv -j`nproc`

Build with pre-built LLVM

If you have a custom build(based on the latest version) of LLVM libraries you can link the translator against it.

git clone https://github.com/KhronosGroup/SPIRV-LLVM-Translator.git
mkdir SPIRV-LLVM-Translator/build && cd SPIRV-LLVM-Translator/build
cmake .. -DLLVM_DIR=<llvm_build_dir>/lib/cmake/llvm/
make llvm-spirv -j`nproc`

Where llvm_build_dir is the LLVM build directory.

LLVM in-tree build

The translator can be built as a regular LLVM subproject. To do that you need to clone it to llvm/projects or llvm/tools directory.

git clone http://llvm.org/git/llvm.git
cd llvm/project
git clone https://github.com/KhronosGroup/SPIRV-LLVM-Translator.git

Run(re-run) cmake as usually for LLVM. After that you should have llvm-spirv and check-llvm-spirv targets available.

mkdir llvm/build && cd llvm/build 
cmake ..
make llvm-spirv -j`nproc`

Test instructions

All tests related to the translator are placed in the test directory.

Execute the following command to run translator tests:

llvm-lit test

Run Instructions for llvm-spirv

To translate between LLVM IR and SPIR-V:

1. Execute the following command to translate input.bc to input.spv

   llvm-spirv input.bc
   

2. Execute the following command to translate input.spv to input.bc

   llvm-spirv -r input.spv
   

3. Other options accepted by llvm-spirv

   • -o file_name - to specify output name
   • -spirv-debug - output debugging information
   • -spirv-text - read/write SPIR-V in an internal textual format for debugging purpose. The textual format is not defined by SPIR-V spec.
   • -help - to see full list of options