SPIRVSmith

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 16 Open GitHub ↗

A differential testing tool targeting SPIRV based on structured fuzzing techniques

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SPIRVSmith

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/rayanht/SPIRVSmith/Build,%20Test%20and%20Deploy)
![GitHub](https://img.shields.io/github/license/rayanht/SPIRVSmith)
[![Test Coverage](https://api.codeclimate.com/v1/badges/5f91595e621ebb1f1da2/test_coverage)](https://codeclimate.com/github/rayanht/SPIRVSmith/test_coverage)
[![Maintainability](https://api.codeclimate.com/v1/badges/5f91595e621ebb1f1da2/maintainability)](https://codeclimate.com/github/rayanht/SPIRVSmith/maintainability)
[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B22322%2Fgithub.com%2Frayanht%2FSPIRVSmith.svg?type=shield)](https://app.fossa.com/projects/custom%2B22322%2Fgithub.com%2Frayanht%2FSPIRVSmith?ref=badge_shield)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![DOI](https://zenodo.org/badge/429076310.svg)](https://zenodo.org/badge/latestdoi/429076310)

## SPIRVSmith

SPIRVSmith is a differential testing tool that leverages structured fuzzing techniques to find bugs in producers and consumers of SPIRV shaders.

SPIRVSmith attempts to find bugs in the following projects:
- [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools) - mostly the validator and reducer components.
- [SPIRV-Cross](https://github.com/KhronosGroup/SPIRV-Cross)
- [Amber](https://github.com/google/amber)
- [SwiftShader](https://github.com/google/swiftshader)
- [MoltenVK](https://github.com/KhronosGroup/MoltenVK)
- ...and more to come!

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [How does it work?](#how-does-it-work)
  - [Differential testing](#differential-testing)
  - [Program Reconditioning](#program-reconditioning)
- [SPIR-V Language Coverage](#spirv-language-coverage)
- [Contributing](#contributing)
- [Authors](#authors)
- [License](#license)

## Installation

SPIRVSmith uses `poetry` to manage Python dependencies and ships with scripts to install external dependencies.

1. Follow the poetry [installation instructions](https://python-poetry.org/docs/#installation) for your platform.

1. Grab a local copy of SPIRVSmith:

```bash
$ git clone https://github.com/rayanht/SPIRVSmith.git && cd SPIRVSmith
```

3. Install Python dependencies using `poetry` and start a `poetry` shell:

```bash
$ poetry install && poetry shell
```

4. Install the external dependencies:

```bash
$ mkdir bin
$ sh scripts/get_spirv_tools.sh <platform>
```

Replace `<platform>` by either `linux` or `macos` (No support for Windows :sob:)

## Usage

The first step is to run `SPIRVSmith` is to head to `config.py`. That file contains the various parameters that are used to dictate the behaviour of the fuzzer.

`SPIRVSmith` is highly parametrizable, you can choose to disable certain features of the SPIR-V language (e.g. do not emit any control flow operation), limit the number of global constants generated, favour the generation of certain kinds of instructions etc.

Once you are happy with your parametrization, make sure you are in a `poetry` virtual environment (`$ poetry shell`) and run `SPIRVSmith`:

```bash
$ sh scripts/run.sh
```

SPIR-V assembly files will be saved as they are generated to the `out/` directory and the fuzzer can be stopped at any time by pressing `Ctrl+C`.

## How does it work?

### Differential Testing
The bread and butter of `SPIRVSmith` is **differential testing** (sometimes called differential fuzzing), in which we provide the same SPIRV shader to similar consumers (say three different SPIRV compilers for example), execute the three resulting programs and compare the values contained inside all buffers at the end of exeuction.

In a **fully deterministic** program `(== synchronous && free of undefined behaviour)`, we expect all these buffers to be exactly the same at the end of execution, regardless of what compiler was used to generate said program. If one program ends up with different buffers than the other two, we have a strong reason to believe that the compiler that generated it has a **bug**.

This concept can be extended further by varying the platform that executes the shader. If we get different results by running the same shader on an Nvidia GPU, an AMD GPU, and an Intel integrated graphics chip then there is a good chance that either the underlying Vulkan engine or the GPU driver has a **bug** (possibly both).

The constraint on determinism creates an interesting problem, how can we ensure that the **randomly** generated programs are free of undefined behaviour? Unlike existing differential testing tools, `SPIRVSmith` does not perform any static analysis or backtracking at generation-time to enforce this constraint, we rather implement the idea of **program reconditioning** by **Donaldson et al.**

### Program Reconditioning

**Donaldson et al.** introduce the idea of program reconditioning as "a method for leveraging off-the-shelf test case reducers to simplify programs that expose miscompilation bugs during randomised differential testing".

This approach solves the issues raised by **Yang et al.** in the case of [CSmith](https://github.com/csmith-project/csmith) where test case reducers couldn't be used to provide concise, actionable bug reports since they would themselves often introduce undefined behaviour.

Program reconditioning works by decoupling the process of generating a program and the process of ensuring that said program is free of undefined behaviour. This is in contrast to **Livinskii et al.** in [YARPGen](https://github.com/intel/yarpgen) where code generation steps and static analysis steps are interleaved.

**Donaldson et al.** describe a **rule-based reconditioning approach** where transforms are applied to constructs that **could** exhibit undefined behaviour. Transforms are applied to all eligible construct in a blanket manner, **no** static analysis is performed to determine which constructs are in fact worth reconditioning. Here is example of reconditioning a **GLSL** shader:

#### Original
```glsl
float A [3]; // Not initialised
void main () {
    int i = int (A[0]);
    float f = 2000000.0;
    while (i != -42) { // Might not terminate
        A[i] = f; // Out of  bounds ?
        f = f + f; // Roundoff
        int j = i ++ + ( i / ( i - 1)); // Order of side effects, divide by zero?
        i = j;
    }
}
```

#### Reconditioned
```glsl
// [ Declarations of SAFE_ABS , MAKE_IN_RANGE and SAFE_DIV ]
uint _loop_count = 0u;
const uint _loop_limit = 100u;
float A [3] = float [3](1.0 , 1.0 , 1.0);
void main () {
    int i = int (A[0]);
    float f = 2000000.0;
    while (i != -42) {
        if (_loop_count >= _loop_limit) break;
        _loop_count ++;
        A[SAFE_ABS(i) % 3] = f ;
        f = MAKE_IN_RANGE(f + f);
        int _t = SAFE_DIV(i , i - 1);
        int j = i ++ + _t;
        i = j;
    }
}
```

## SPIRV Language Coverage

<summary>Expand</summary>

### Instructions

#### Miscellanous

<summary>Expand</summary>

</details>

#### Debug

<summary>Expand</summary>

</details>

#### Annotation

<summary>Expand</summary>

</details>

#### Extension

<summary>Expand</summary>

</details>

#### Mode-Setting

<summary>Expand</summary>

</details>

#### Type-Declaration

<summary>Expand</summary>

</details>

#### Constant-Creation

<summary>Expand</summary>

</details>

#### Memory

<summary>Expand</summary>

</details>

#### Function

<summary>Expand</summary>

</details>

#### Image

<summary>Expand</summary>

</details>

#### Conversion

<summary>Expand</summary>

</details>

#### Composite

<summary>Expand</summary>

</details>

#### Arithmetic

<summary>Expand</summary>

</details>

#### Bit

<summary>Expand</summary>

</details>

#### Relational and Logical

<summary>Expand</summary>

</details>

#### Control Flow

<summary>Expand</summary>

</details>

## Contributing

Encountered a bug? Have an idea for a new feature? This project is open to all
sorts of contribution! Feel free to head to the `Issues` tab and describe your
request!

## Authors

* **Rayan Hatout** - [GitHub](https://github.com/rayanht)
  | [Twitter](https://twitter.com/rayanhtt)
  | [LinkedIn](https://www.linkedin.com/in/rayan-hatout/)

## License
This project is licensed under the Apache 2.0 license.

[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B22322%2Fgithub.com%2Frayanht%2FSPIRVSmith.svg?type=large)](https://app.fossa.com/projects/custom%2B22322%2Fgithub.com%2Frayanht%2FSPIRVSmith?ref=badge_large)

SPIRVSmith

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README