Fault Hardware Testing Framework

4.0.1 · active · verified Fri Apr 17

Fault is a Python package for testing hardware designs, forming a core part of the magma ecosystem. It provides a unified, high-level interface to simulate and verify digital circuits directly from Python, supporting various hardware description languages and simulation targets like Verilator and Icarus. Currently at version 4.0.1, Fault is actively maintained with major versions typically introducing significant API improvements and architectural refactorings.

Common errors

```
ModuleNotFoundError: No module named 'magma'
```
cause The core `magma` library, which `fault` depends on, has not been installed.

fix Install `magma` explicitly: `pip install magma`.
```
AttributeError: module 'fault' has no attribute 'CoreTester'
```
cause This typically occurs when attempting to import from internal or deprecated submodules due to the package restructuring in `fault` 3.0.0.

fix Use top-level imports directly from the `fault` package (e.g., `from fault import Tester`) or install and import from `fault-core` if you need the low-level components directly.
```
RuntimeError: Target 'verilator' not found. Is it installed and in your PATH?
```
cause The specified hardware simulator (e.g., Verilator) is either not installed on your system, not accessible via the system PATH, or its corresponding `fault-` Python wrapper is missing.

fix Install the simulator executable (e.g., `sudo apt-get install verilator` on Debian/Ubuntu) and/or its Python wrapper (`pip install fault-verilator`). Ensure the simulator executable's directory is included in your system's PATH environment variable.

Warnings

breaking Fault 4.0.0 and higher require Magma 3.0.0 or higher. Older versions of Magma are incompatible and will lead to import errors or unexpected behavior.
Fix: Upgrade Magma to the latest 3.x version: `pip install --upgrade magma`.
breaking The package structure underwent a significant refactoring in Fault 3.0.0. Direct imports from internal or deprecated submodules like `fault.core` (which became `fault-core`) may no longer work. Users should rely on top-level imports from `fault`.
Fix: Update import statements to use top-level `from fault import ...` or directly import from `fault-core` if low-level components are explicitly needed.
breaking The `Target` API was substantially revised in Fault 2.0.0, affecting how simulation targets are configured and used. Custom targets or direct interaction with `SimulatorTarget` will require updates, and `compile_and_run` method signatures changed.
Fix: Consult the `fault` documentation for the 2.x API to adapt custom targets and `compile_and_run` calls.
gotcha Simulation targets (e.g., Verilator, Icarus, Eldo) often require both a Python wrapper package (e.g., `fault-verilator`) AND the external simulator executable to be installed on your system and discoverable via your system's PATH.
Fix: Ensure the specific `fault-` Python package for your target is installed (e.g., `pip install fault-verilator`), and that the corresponding external simulator executable (e.g., `verilator`) is installed and available in your system's PATH.

Install

pip install fault Install core Fault library
pip install fault-verilator Install Verilator simulation target (optional)

Imports

Tester
```
from fault import Tester
```

MagmaTarget

from fault.magma_target import MagmaTarget

VerilatorTarget

from fault.verilator_target import VerilatorTarget

Quickstart

This quickstart demonstrates how to define a simple Magma circuit, create a `fault.Tester` for it, apply inputs (`poke`), verify outputs (`expect`), and run the simulation using a Verilator target. Note that external simulators like Verilator often require system-level installation in addition to Python packages.

import magma as m
import fault

# Define a simple circuit using Magma
class MyCircuit(m.Circuit):
    io = m.IO(I=m.In(m.Bit), O=m.Out(m.Bit))
    io.O @= io.I

# Create a Tester instance for the circuit
tester = fault.Tester(MyCircuit)

# Poke inputs and expect outputs
tester.poke(MyCircuit.I, 1)
tester.expect(MyCircuit.O, 1)
tester.poke(MyCircuit.I, 0)
tester.expect(MyCircuit.O, 0)

# Compile and run the test using a target (e.g., Verilator)
# Ensure 'verilator' is installed on your system and 'fault-verilator' is installed via pip
try:
    tester.compile_and_run("verilator", magma_output="mlir")
    print("Test passed successfully with Verilator!")
except Exception as e:
    print(f"Test failed: {e}")
    print("Make sure 'verilator' is installed and in your PATH, and 'pip install fault-verilator' has been run.")

view raw JSON →