Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Development version

This book follows the main branch and can describe features that are not in a release yet. The book for the latest release, v0.1.2, is here.

Introduction

Volt is a command-line tool: it has no window of its own. You write your designs in a text editor and run volt commands in a terminal (PowerShell on Windows, Terminal on macOS and Linux). Setup shows how, step by step, if you have never used a terminal.

Volt is also the name of the language those designs are written in, a hardware description language. You describe digital circuits in a Rust-like syntax, and the compiler writes readable SystemVerilog for your FPGA or ASIC tools. Clock domains are part of the type system: a signal that crosses from one clock domain to another without a synchronizer is a compile error.

This book teaches Volt by building things. Setup gets your computer ready: a terminal, a folder, an editor, Volt and Docker Desktop. Then come three parts:

  • Part I, the Tour, takes about 15 minutes. You create a project, meet a clock domain crossing error, fix it, run tests and look at a waveform.
  • Part II, the Tutorial, builds one design per chapter: a counter, a state machine, a UART, a design with two clocks, and more.
  • Part III, the Cookbook, is a set of recipes for common hardware tasks: FIFOs, crossings, reset synchronizers, register maps, pipelines.

Status. Volt is an early-stage project (version 0.1). The Tour and the counter chapter are written; the other chapters list what they will cover and point to working examples in the repository.

Two kinds of readers

This book is written for two groups at once:

  • people who are new to hardware and have written software before, and
  • FPGA and ASIC engineers who know SystemVerilog.

The main text is for both. It explains what to type and what happens. Two kinds of side boxes add detail for one group. You can skip either kind; the main text reads the same without them.

New to hardware?

Boxes like this one explain a hardware idea the main text uses: a clock, a flip-flop, a reset. If you have designed digital logic before, skip them.

Coming from SystemVerilog?

Boxes like this one show the SystemVerilog you would write for the same thing, what Volt does differently, and why. If SystemVerilog is new to you, skip them.

Code in this book

Every Volt example in this book is checked by volt check in continuous integration, and the tests in it run in Verilator. Some examples are wrong on purpose, to show an error; the text says so each time. Command output is copied from real runs; the chapter says where it ran.

Setup and the Tour label every block: Type this is a command to copy, You should see is what it prints, and Create this file gives a file’s name and contents. Setup explains the three.

The source of this book is in the book/ directory of the Volt repository. Corrections are welcome.

Setup

In this chapter you will open a terminal, make a folder for your Volt projects, pick an editor and learn three ways to create a file. Then you will install Volt and Docker Desktop and check that both work. If you use a terminal every day, skim the headings and do the last three sections.

Before you start

  • Window: none yet; this page shows how to open a terminal.
  • Folder: none yet; this page makes one.
  • Running: a web browser with this book, and an internet connection.

Volt is a command-line tool

Volt has no window of its own. You use it in two programs side by side:

  • a text editor, where you write designs: files whose names end in .volt;
  • a terminal, where you type commands such as volt check and volt test. Volt reads your files, prints what it found, and writes its results into a folder named build.

Open a terminal

A terminal is a window where you type a command and press Enter, and the command prints its answer below it.

  • Windows: open the Start menu, type PowerShell and press Enter. A window opens with a line like PS C:\Users\you>. Windows 11 may show it inside the Terminal app; that is the same thing. Use PowerShell, not Command Prompt: the Windows commands in this book are PowerShell commands.
  • macOS: press Cmd+Space, type Terminal and press Enter.
  • Linux: press Ctrl+Alt+T, or search for Terminal in your applications.

The text before the cursor (PS C:\Users\you> on Windows, something ending in % or $ on macOS and Linux) is the prompt. It is not part of any command, and the commands in this book never include it.

The three kinds of blocks in this book

The guided pages (this one and the Tour) label every block:

Type this: a command. Copy it with the button in the block’s top right corner, paste it into the terminal (Windows: right-click or Ctrl+V; macOS: Cmd+V; Linux: Ctrl+Shift+V) and press Enter. Or type it.

volt --version

You should see: what the command prints. These blocks have no copy button: you compare them with your terminal, you do not type them. Small differences, such as times like 0.01s, do not matter.

volt 0.1.2 (33354c5)

Create this file: name.volt, followed by the file’s contents. The section Create a file below shows how.

When Windows and macOS or Linux need different commands, the book shows both, each with its own label: Type this (Windows, PowerShell): and Type this (macOS and Linux):, for example. Use the one for your computer.

Make a folder for your projects

A terminal always works in a folder, its working folder. A new terminal starts in your home folder (on Windows C:\Users\<your name>). Commands such as volt new create their files in the working folder.

Make a folder named volt-projects in your home folder. You do this once.

Type this:

mkdir ~/volt-projects

~ means your home folder; it works in PowerShell, on macOS and on Linux. PowerShell answers with a short table that names the new folder; macOS and Linux print nothing.

Now go into it. cd means change directory:

Type this:

cd ~/volt-projects

On Windows the prompt now ends in volt-projects>. On every system, pwd prints the working folder. cd .. goes up one folder; cd ~/volt-projects brings you back here from anywhere. Every Tour page starts with a cd command like this one, in its Before you start box, so you always know where you are.

To see the folder in your file manager:

Type this (Windows, PowerShell):

explorer .

Type this (macOS):

open .

Type this (Linux):

xdg-open .

. means the working folder.

Pick an editor

Any editor that saves plain text works.

  • Visual Studio Code (VS Code) is free and runs on Windows, macOS and Linux. We suggest it: it shows the folder and the terminal in the same window (menu Terminal → New Terminal). Open your project with File → Open Folder.
  • Notepad (Windows) works too. Read the warning about .txt below.
  • On macOS, TextEdit saves formatted text by default; choose Format → Make Plain Text before you save, or use VS Code.

Create a file

A guided page shows a file like this:

Create this file: hello.volt

// A wire from one port to another.
pub module Hello {
    in  a : bool
    out b : bool

    b = a
}

The file goes into the working folder named in the page’s Before you start box. There are three ways to create it. Try one now with hello.volt, in volt-projects.

With the clipboard

Click the copy button of the file’s block. Then, in the terminal:

Type this (Windows, PowerShell):

Get-Clipboard -Raw | Set-Content hello.volt -NoNewline

Type this (macOS):

pbpaste > hello.volt

Type this (Linux):

wl-paste > hello.volt

wl-paste comes with the wl-clipboard package. On an older X11 desktop use xclip -selection clipboard -o > hello.volt (package xclip).

These commands write the file in the working folder and replace a file of the same name if there is one. Put the name of the file you are creating in place of hello.volt.

With VS Code

Open the folder (File → Open Folder), then File → New File, type the name hello.volt and press Enter. Paste the contents and save with Ctrl+S (macOS: Cmd+S).

With Notepad

Open Notepad and paste the contents. Choose File → Save as, go to the folder (volt-projects is in your user folder, C:\Users\<your name>), and set Save as type to All files (*.*). Type the name hello.volt and save.

New to files? The .txt trap

With Save as type left at Text Documents (*.txt), Notepad saves hello.volt.txt. File Explorer hides the .txt part, so the file looks right, and then Volt cannot find hello.volt. Typing the name in quotes, "hello.volt", also stops Notepad from adding .txt.

Check that the file is there

ls lists the files of the working folder, with their full names:

Type this:

ls

You should find hello.volt in the list, not hello.volt.txt.

Replace a file

Some pages change a file you made earlier and say Replace this file: followed by the name. Use the clipboard command again (it replaces the file), or in the editor select everything (Ctrl+A, macOS: Cmd+A), paste the new contents and save.

Install Volt

Type this (Windows, PowerShell):

irm https://volt-hdl.github.io/volt/install.ps1 | iex

Type this (macOS and Linux):

curl -fsSL https://volt-hdl.github.io/volt/install.sh | sh

The script prints each step. When it has finished, close the terminal and open a new one: a terminal that was already open does not know the new volt command. If you use the Windows Terminal app or VS Code, close the whole program, not just the tab.

Install Volt explains what the script changes, how to update or remove Volt, and how to build it from source on a system the script does not support.

Check Volt

In the new terminal:

Type this:

volt --version

You should see:

volt 0.1.2 (33354c5)

This book describes Volt 0.1.2. The book at https://volt-hdl.github.io/volt/ follows the latest release, and the book at https://volt-hdl.github.io/volt/dev/ follows the development version. If volt --version prints another version, some output on these pages may differ from yours. The seven letters and digits in parentheses name the commit your copy of Volt was built from; they differ from the ones above, and a copy built without git shows no parentheses.

If you see “The term ‘volt’ is not recognized” (Windows) or “command not found” (macOS, Linux), the terminal was opened before the install finished: close it, and the program around it, and open a new one.

Install and start Docker Desktop

volt check and volt build need nothing but volt. volt test runs your design in a simulator called Verilator. If Verilator is not installed, Volt runs it inside Docker, a program that starts small prepared Linux systems (containers). So for volt test:

  1. Install Docker Desktop (Windows, macOS) or Docker Engine (Linux).
  2. Start it. On Windows, open the Start menu and type Docker Desktop; on macOS, open it from Applications.
  3. Wait until the Docker Desktop window says Engine running in its bottom left corner.

Installed is not enough: Docker Desktop must be running whenever you run volt test. If you closed it, start it again and wait for Engine running. Its settings have an option to start it when you sign in.

Ask volt doctor

volt doctor checks what works on your computer.

Type this:

volt doctor

Your own user folder appears where this output says C:\Users\you.

You should see (Windows 11, Docker Desktop running):

volt 0.1.2 (windows-x86_64)

✓ build, check, explain — no external tools needed
✓ test, run — via Docker (verilator/verilator:v5.054: Verilator 5.054, g++ 13.3)
✓ verify — via Docker (hdlc/formal:all: Yosys 0.66, SBY 0.69, boolector 3.2.4, yices 2.7.0, z3 4.15.0)
- timing (optional) — OpenSTA not found; checks generated .sdc files
- driver checks (optional) — C compiler not found (found: rustc 1.95.0); compiles drivers from --emit=c,rust
✓ docker — 29.8.1, daemon running
- project — no Volt.toml (search stopped at the home directory C:\Users\you); single .volt files still work

The lines that matter for the Tour are build, check, explain and test, run: both need a ✓. Lines starting with - are optional tools.

If Docker Desktop is installed but not running, these lines change:

You should see (Docker Desktop installed, not running):

✗ test, run — Verilator, C++ compiler, make not found
    fix (Windows): start Docker Desktop: Volt runs Verilator in a container (DOCKER below), or use WSL
    see: volt explain simulation-setup
✗ verify — sby, Yosys not found; no SMT solver found (boolector, bitwuzla, yices, z3)
    fix (Windows): start Docker Desktop: Volt runs sby in a container (DOCKER below), or use WSL
    see: volt explain verify-setup
! docker — 29.8.1 installed, daemon not running (start Docker Desktop or the docker service)

Start Docker Desktop, wait for Engine running, and run volt doctor again. While Docker Desktop is still starting, the docker line may say daemon did not answer within 5 s; wait a little and try again.

Copy what a command printed

When your terminal shows something other than the You should see block, you may want to compare it closely or ask someone for help. Copy the text:

  • Windows: select it with the mouse, then press Enter or Ctrl+C. Careful: Ctrl+C with nothing selected stops the running command.
  • macOS: select it, then Cmd+C.
  • Linux: select it, then Ctrl+Shift+C.

Or run the command again and send everything it prints straight to the clipboard:

Type this (Windows, PowerShell):

volt check 2>&1 | Set-Clipboard

Type this (macOS):

volt check 2>&1 | pbcopy

Type this (Linux):

volt check 2>&1 | wl-copy

2>&1 takes the error messages along with the rest. Then paste where you need it.

Next: Part I, the Tour.

A project in three commands

In this chapter you will create a project with volt new, check it with volt check and turn it into SystemVerilog with volt build. You will also take a short look at the generated code.

Before you start

  • Window: a terminal: PowerShell on Windows, Terminal on macOS and Linux (how to open one). Keep your editor at hand too.

  • Folder: your volt-projects folder. Type this:

    cd ~/volt-projects
    

    No such folder? Setup makes it.

  • Running: nothing else. This page does not need Docker.

The output on this page was recorded with Volt 0.1.2 in PowerShell on Windows 11. On macOS and Linux, paths are written with / instead of \; everything else looks the same.

Create a project

Type this:

volt new blinky

You should see:

    Created minimal project 'blinky' in blinky
             Volt.toml, counter.volt, counter_test.volt, README.md, .gitignore
       Next: cd blinky
             volt check
             volt test

volt new made a folder named blinky with five files in it. (volt new --list shows the other templates: two clock domains, a FIFO, a register map. The default template is a small counter.) Go into the new folder:

Type this:

cd blinky

The rest of the Tour, except the next chapter, works in this folder.

FileWhat it holds
Volt.tomlthe project manifest: its name and its top module, Counter
counter.voltthe design
counter_test.voltsimulation tests for the design
README.mdwhat to try next
.gitignoretells Git, the version control tool, not to track the build folder that Volt writes. You can ignore it if you do not use Git. macOS and Linux hide names that start with .; ls -a lists them

The design

Open counter.volt in your editor (in VS Code: File → Open Folder, choose blinky, then click counter.volt).

You should see:

// An 8-bit counter with an enable input and a wrap-around value.
//
//   volt check     check the design (no output files)
//   volt build     write SystemVerilog to build/rtl/
//   volt test      run counter_test.volt in Verilator
//   volt verify    prove the contracts with SymbiYosys

// The counter goes back to 0 after this value.
const MAX : u8 = 9

// The next count. A `fn` is pure combinational logic, expanded where
// it is called.
fn next(count: u8) -> u8 {
    if count == MAX { 0 } else { count + 1 }
}

pub module Counter {
    in  clk    : clock
    in  enable : bool
    out count  : u8
    out wrap   : bool

    // Contracts. `volt verify` proves them for every input sequence;
    // `volt test` also checks them on every cycle of every test.
    invariant: count_r <= MAX
    cover: count_r == MAX

    reg count_r : u8 = 0

    on clk {
        if enable {
            count_r <= next(count_r)
        }
    }

    count = count_r
    wrap  = enable && count_r == MAX
}

You do not need to follow every line yet; the counter chapter builds a design like this one step by step. In short: Counter has a clock input, an enable input and two outputs. The register count_r counts from 0 to 9 and wraps back to 0. The two lines starting with invariant and cover are contracts: rules about the design that tools can check.

New to hardware? A module is a circuit, not a function

A module describes a piece of hardware that exists all the time. Its in and out ports are wires. A reg is a storage element that takes a new value at each clock tick; everything outside on clk { ... } is wiring that always shows the current result. Nothing “runs” line by line.

Check it

volt check reads every source file and test file of the project and reports errors: each .volt file under src, whether the top module uses it or not, and each *_test.volt file that volt test would run, subdirectories included (build/ is skipped). It writes no files, so it is quick enough to run after every change:

Type this:

volt check

You should see:

    Checking counter.volt
    Checking counter_test.volt
    Finished 0.01s
      Result 0 error(s), 0 warning(s)
       Next: volt build   (emit SystemVerilog)

Build it

volt build writes SystemVerilog for the top module named in Volt.toml. It reads the files that module uses and no others, so an error in a file the design does not use shows up in volt check, not here:

Type this:

volt build

You should see:

   Compiling counter.volt
    Finished 0.00s (1 source file(s), 1 SV file(s))
     Output build\rtl\Counter.sv (37 lines)
       Next: volt run      (simulate)
             volt verify   (prove contracts)

volt build made a folder build inside blinky, and in it the folder rtl with the file Counter.sv. Open build/rtl/Counter.sv in your editor.

You should see:

// This file was generated by Volt.
// Source:  counter.volt
// Module:  Counter
// Version: 0.1.2 (33354c5)
//
// DO NOT EDIT — make changes in the source file instead.

`default_nettype none

module Counter (
    input  logic       clk,
    input  logic       rst,
    input  logic       enable,
    output logic [7:0] count,
    output logic       wrap
);

    logic [7:0] count_r;
    // next(count_r) — counter.volt:32
    wire [7:0] next_0 = (count_r == 8'd9) ? 8'd0 : (count_r + 8'd1);

    always_ff @(posedge clk) begin
        if (rst) begin
            count_r <= 8'd0;
        end else begin
            if (enable) begin
                count_r <= next_0;
            end
        end
    end

    assign count = count_r;
    assign wrap = enable && count_r == 8'd9;

endmodule

`default_nettype wire

Three things to notice:

  • The module has a rst port that the source does not mention. A design with one clock gets a synchronous, active-high reset named rst, and every register goes back to its initial value (= 0) when rst is high.
  • The call next(count_r) became a named wire, next_0, with a comment pointing back to the source line.
  • The names of ports and registers are the names you wrote. The file is meant to be read, linted and fed to any SystemVerilog tool.
  • The Version line names the Volt that wrote the file: the version and, in parentheses, the commit it was built from. Yours shows other letters and digits there.

Coming from SystemVerilog? What the generator promises

Volt emits plain synthesizable SystemVerilog: always_ff with a synchronous reset, assign for everything combinational, `default_nettype none around each module, one file per module named after it. The constants are folded (MAX became 8'd9), and there are no functions, interfaces or generate blocks in the output. The compiler’s CI lints the SystemVerilog generated for its test designs and examples with verilator --lint-only -Wall and expects zero warnings.

You are in the blinky folder. The next chapter uses a folder of its own.

Next: a clock domain crossing error.

A clock domain crossing error

In this chapter you will write a design with two clocks, pass a signal from one to the other the wrong way, and read the error Volt reports. Then you will fix it with sync() and see what the fix becomes in SystemVerilog.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This chapter makes a new folder there, cdc, next to blinky. Type this:

    cd ~/volt-projects
    
  • Running: nothing else. This page does not need Docker.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11.

Two clocks

Real designs often have more than one clock: a fast one for the core, a slower one for a peripheral. Each clock, with the registers it drives, is a clock domain.

This design is a single file, not a project, so it gets a folder of its own. Make the folder cdc and go into it:

Type this:

mkdir cdc

Type this:

cd cdc

In this folder, create the file crossing.volt (with the clipboard command, VS Code or Notepad, as Setup shows). A button is sampled by the fast clock; a LED is driven by the slow clock:

Create this file: crossing.volt

// A button sampled in one clock domain drives a LED in another.

domain Fast {
    clock = posedge
    reset = sync active_high
}

domain Slow {
    clock = posedge
    reset = sync active_high
}

pub module Crossing {
    in  fast_clk : clock @Fast
    in  slow_clk : clock @Slow
    in  rst      : reset(sync, active_high)
    in  button   : bool  @Fast
    out led      : bool  @Slow

    reg pressed_r : bool = false
    on fast_clk {
        pressed_r <= button
    }

    reg led_r : bool = false
    on slow_clk {
        led_r <= pressed_r
    }

    led = led_r
}

The two domain blocks name the clock domains. @Fast and @Slow put each port into one of them. The reset rst is shared: Volt synchronizes it to each clock by itself. The register pressed_r belongs to Fast, because on fast_clk updates it; led_r belongs to Slow.

This design is wrong on purpose. Check it. Because the folder has no Volt.toml, the command names the file:

Type this:

volt check crossing.volt

You should see:

    Checking crossing.volt
error[E3001]: direct assignment between clock domains
   ┌─ crossing.volt:27:9
   │
 3 │ domain Fast {
   │        ---- source @Fast defined here
   ·
 8 │ domain Slow {
   │        ---- destination @Slow defined here
   ·
27 │         led_r <= pressed_r
   │         ^^^^^    --------- @Fast
   │         │         
   │         @Slow
   │
   = reason: the destination register may sample the source signal during an unstable window (metastability)
   = note: for multi-bit data, AsyncFifo may be safer
   = help: sync() is written at module level: add 'let pressed_r_sync = sync(pressed_r, slow_clk)' above this block and read the synchronized name here
   = for more: volt explain E3001


    Finished 0.00s
      Result 1 error(s), 0 warning(s)

The error says which line crosses (27), where each domain comes from (lines 3 and 8), why this is a problem and how to fix it. volt explain E3001 prints a longer explanation. The command exits with code 1, and volt build would write no SystemVerilog.

New to hardware? Why a crossing needs a synchronizer

A flip-flop samples its input at the clock edge. If the input changes right at that moment, the flip-flop can hang between 0 and 1 for a while before it settles; this is called metastability. Two clocks that are not related drift against each other, so sooner or later a change lands right on an edge. A synchronizer, two flip-flops in a row on the receiving clock, gives the front one a full clock period to settle before anyone reads the value. The bug is rare and random, which is why it is hard to find in the lab and why Volt rejects it at compile time.

The fix

sync() builds the synchronizer. Do what the help line says: add the line let pressed_r_sync = sync(pressed_r, slow_clk) above the on slow_clk block, which brings pressed_r into the Slow domain, and read pressed_r_sync instead of pressed_r under slow_clk. The name pressed_r_sync is the one the help line suggests; any free name works, as long as both lines use the same one.

Replace this file: crossing.volt

// A button sampled in one clock domain drives a LED in another.

domain Fast {
    clock = posedge
    reset = sync active_high
}

domain Slow {
    clock = posedge
    reset = sync active_high
}

pub module Crossing {
    in  fast_clk : clock @Fast
    in  slow_clk : clock @Slow
    in  rst      : reset(sync, active_high)
    in  button   : bool  @Fast
    out led      : bool  @Slow

    reg pressed_r : bool = false
    on fast_clk {
        pressed_r <= button
    }

    let pressed_r_sync = sync(pressed_r, slow_clk)

    reg led_r : bool = false
    on slow_clk {
        led_r <= pressed_r_sync
    }

    led = led_r
}

sync() goes on a line of its own at module level; inside an on block it is not supported yet, which is why the help line puts it above the block. Check again:

Type this:

volt check crossing.volt

You should see:

    Checking crossing.volt
    Finished 0.00s
      Result 0 error(s), 0 warning(s)
       Next: volt build crossing.volt   (emit SystemVerilog)

Now write the SystemVerilog:

Type this:

volt build crossing.volt

You should see:

   Compiling crossing.volt
    Finished 0.00s (1 source file(s), 1 SV file(s))
     Output build\rtl\Crossing.sv (86 lines)
       Next: volt run crossing.volt      (simulate)
             volt verify crossing.volt   (prove contracts)

Open build/rtl/Crossing.sv (in the cdc folder) in your editor. The sync() line became two flip-flops on slow_clk. This is a part of the file (output trimmed):

You should see:

    // CDC synchronizer: pressed_r -> slow_clk
    logic sync_pressed_r_stage0;
    logic sync_pressed_r_stage1;

    always_ff @(posedge slow_clk) begin
        if (rst_sync_slow_clk_stage1) begin
            sync_pressed_r_stage0 <= 1'b0;
            sync_pressed_r_stage1 <= 1'b0;
        end else begin
            sync_pressed_r_stage0 <= pressed_r;
            sync_pressed_r_stage1 <= sync_pressed_r_stage0;
        end
    end

    assign pressed_r_sync = sync_pressed_r_stage1;

The file also holds one reset synchronizer per clock (rst_sync_fast_clk_stage1, rst_sync_slow_clk_stage1): the shared rst is asserted at once but released in step with each clock. Their always_ff blocks react to rst directly (or posedge rst) although both domains say reset = sync. This is on purpose: the reset takes effect even while a clock is stopped, and its release is still aligned to each clock, so every register of a domain sees a synchronous reset and leaves it on the same clock edge.

You are in the cdc folder. The next chapter goes back to blinky.

Coming from SystemVerilog? The same bug compiles there

always_ff @(posedge slow_clk)
    led_r <= pressed_r;   // pressed_r is clocked by fast_clk

SystemVerilog accepts this without a warning; a CDC tool or a review has to catch it later. In Volt every signal carries its clock domain in its type, the way a Rust value carries its type, so a crossing is a type error. sync() is a compiler primitive, not a library module, so the compiler knows the crossing is safe. It is meant for one bit; a multi-bit sync() is a warning (W3003), and words cross through the built-in AsyncFifo. A synchronizer you write by hand out of two registers is not recognized.

Next: tests and waveforms.

Tests and waveforms

In this chapter you will run the project’s tests, write a state machine with a test that fails, and follow the failure to a waveform. In GTKWave the state register shows its state names, not raw bits.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: the blinky project from A project in three commands. The previous chapter left you in the cdc folder, so go back. Type this:

    cd ~/volt-projects/blinky
    
  • Running: Docker Desktop, with Engine running in its window (Setup shows how). volt test runs the Verilator simulator in Docker. You can skip Docker if Verilator is installed on your computer: then volt doctor shows ✓ test, run without “via Docker”.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11, with Docker Desktop running Verilator. On macOS and Linux, paths are written with / instead of \.

Run the tests

The template came with counter_test.volt. Check that Docker Desktop says Engine running, then run every test of the project:

Type this:

volt test

You should see:

   Compiling counter_test.volt
running 3 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
note: downloading verilator/verilator:v5.054 (~250 MB, first use only; this can take several minutes)
note: downloaded verilator/verilator:v5.054 in 2.7s
test counts_while_enabled ... ok
test holds_while_disabled ... ok
test wraps_to_zero_after_MAX ... ok

cover summary:
  Counter.cov_0 (counter.volt:26)  hit 1 time

test result: ok. 3 passed; 0 failed

The two note: lines about the download appear once: Volt downloads the Verilator image the earliest time a test needs it. This run took 70 seconds in total; the next run, with nothing changed, took 3 seconds.

The cover summary lists the cover lines of the design and how often the tests reached them. Its line reads:

  • Counter.cov_0: the module, Counter, and the number of the cover in that module, counted from 0;
  • (counter.volt:26): where the cover is written, line 26 of counter.volt: cover: count_r == MAX;
  • hit 1 time: in how many clock cycles, over all tests together, the condition count_r == MAX was true. Here the third test reached 9 once. A cover that no test reaches says NEVER HIT.

If Docker Desktop is not running, the run stops before any test:

You should see (if Docker Desktop is not running):

   Compiling counter_test.volt
running 3 tests
error: Verilator not found locally, and Docker is installed but its daemon is not running
  = help: start Docker Desktop (or the docker service) and run the command again; Volt then runs Verilator in a container

Start Docker Desktop, wait for Engine running and type volt test again.

Here is counter_test.volt. Open it in your editor.

You should see:

// Simulation tests for Counter. A file named X_test.volt sees the
// modules of X.volt, so counter.volt is loaded automatically.
//
// `let dut = Counter { }` instantiates the design with its reset
// applied; `dut.<input> = value` drives an input, step(n) advances the
// clock n cycles, and assert_eq / assert_true / assert_false check
// outputs.

test "counts while enabled" {
    let dut = Counter { };
    dut.enable = true;
    step(3);
    assert_eq(dut.count, 3);
}

test "holds while disabled" {
    let dut = Counter { };
    dut.enable = true;
    step(2);
    dut.enable = false;
    step(5);
    assert_eq(dut.count, 2);
}

test "wraps to zero after MAX" {
    let dut = Counter { };
    dut.enable = true;
    step(9);
    assert_eq(dut.count, 9);
    assert_true(dut.wrap);
    step(1);
    assert_eq(dut.count, 0);
    assert_false(dut.wrap);
}

Counter { } creates the design with its reset applied, dut.enable = true drives an input, step(3) advances the clock three cycles and assert_eq checks an output.

New to hardware? What a test does to a circuit

A software test calls a function and looks at the result. A hardware test sets input wires, lets the clock tick a number of times, and then looks at the output wires. Between two ticks nothing happens: every register holds its value. step(n) is “let n clock ticks pass”.

A state machine

Add a traffic light to the project. In the blinky folder, next to counter.volt:

Create this file: light.volt (how)

// A traffic light. `go` starts a cycle: green for four clock
// cycles, yellow for one, then red again until the next `go`.

const GREEN_CYCLES : u4 = 4

enum Light { Red, Green, Yellow }

pub module TrafficLight {
    in  clk   : clock
    in  go    : bool
    out red   : bool
    out green : bool

    reg state_r : Light = Light::Red
    reg timer_r : u4    = 0

    on clk {
        match state_r {
            Light::Red => {
                if go {
                    state_r <= Light::Green
                }
            }
            Light::Green => {
                if timer_r == GREEN_CYCLES - 1 {
                    timer_r <= 0
                    state_r <= Light::Yellow
                } else {
                    timer_r <= timer_r + 1
                }
            }
            Light::Yellow => {
                state_r <= Light::Red
            }
        }
    }

    red   = state_r == Light::Red
    green = state_r == Light::Green
}

enum Light lists the states, and match says what each state does at the clock edge. Volt checks that every state has an arm.

Now a test file with two tests. The second one expects the light to be red again four cycles after it turned green:

Create this file: light_test.volt

// Simulation tests for TrafficLight.

test "go turns the light green" {
    let dut = TrafficLight { };
    dut.go = true;
    step(1);
    dut.go = false;
    assert_true(dut.green);
}

test "red again after green" {
    let dut = TrafficLight { };
    dut.go = true;
    step(1);
    dut.go = false;
    step(4);
    assert_true(dut.red);
}

A file named X_test.volt sees the modules of X.volt, so the test finds TrafficLight by itself.

A failing test

Type this:

volt test

You should see:

   Compiling counter_test.volt
   Compiling light_test.volt
running 5 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test counts_while_enabled ... ok
test holds_while_disabled ... ok
test wraps_to_zero_after_MAX ... ok
test go_turns_the_light_green ... ok
test red_again_after_green ... FAILED
   Recording waveform of 1 failed test(s) of TrafficLight

failures:
---- red_again_after_green ----
  assert_true failed at light_test.volt:17
    value: 0
  Waveform gtkwave build\sim\light_test\waves\TrafficLight-red_again_after_green.vcd build\sim\light_test\waves\TrafficLight-red_again_after_green.gtkw

cover summary:
  Counter.cov_0 (counter.volt:26)                          hit 1 time
  TrafficLight.cov_0 (light.volt:21, auto FSM transition)  hit 2 times
  TrafficLight.cov_1 (light.volt:27, auto FSM transition)  hit 1 time
  TrafficLight.cov_2 (light.volt:33, auto FSM transition)  NEVER HIT
  TrafficLight.cov_3 (light.volt:25, auto counter wrap)    hit 1 time

test result: FAILED. 4 passed; 1 failed

The light was not red at line 17 of the test. Volt ran the failed test once more with tracing on and wrote its waveform; the Waveform line is the command that opens it.

The cover summary has new lines. light.volt has no cover line of its own; these are covers that Volt added, marked auto: one for every transition of the state machine (auto FSM transition, at the line that changes the state) and one for the timer’s wrap (auto counter wrap). cov_0, the step from red to green at line 21, is hit twice: once in each test. cov_2, the step from yellow back to red at line 33, reads NEVER HIT: no test reaches it. A cover that is never hit often points to a missing or wrong test, as here.

Read the waveform

A waveform shows every signal of the design over time. Install GTKWave (Linux: your package manager, for example sudo apt install gtkwave; Windows and macOS: GTKWave is part of the OSS CAD Suite), then run the Waveform command from the blinky folder, where you ran volt test. The command is the Waveform line that volt test printed; copy it from your terminal (how) or from here.

Type this (Windows, PowerShell):

gtkwave build\sim\light_test\waves\TrafficLight-red_again_after_green.vcd build\sim\light_test\waves\TrafficLight-red_again_after_green.gtkw

Type this (macOS and Linux):

gtkwave build/sim/light_test/waves/TrafficLight-red_again_after_green.vcd build/sim/light_test/waves/TrafficLight-red_again_after_green.gtkw

GTKWave opens a window of its own.

GTKWave showing clk, go, red, green and state_r. state_r reads Red, then Green from the cycle after go; the marker at the end of the test shows state_r = Yellow.

The screenshot was taken with GTKWave 3.3.116 on Linux, with the marker placed at the end of the test. The .gtkw session file lists the ports of the tested module and the state register state_r. A waveform file has no notion of an enum, so the session also carries a table from each code to its name: state_r reads Red, Green and Yellow instead of 00, 01, 10.

At the end of the test, state_r is Yellow, not Red. The design spends four cycles in green and one in yellow; the test forgot the yellow cycle. The design is right and the test is wrong. Change step(4) to step(5) in the second test:

Replace this file: light_test.volt

// Simulation tests for TrafficLight.

test "go turns the light green" {
    let dut = TrafficLight { };
    dut.go = true;
    step(1);
    dut.go = false;
    assert_true(dut.green);
}

test "red again after green" {
    let dut = TrafficLight { };
    dut.go = true;
    step(1);
    dut.go = false;
    step(5);
    assert_true(dut.red);
}

Save the file and run the tests again:

Type this:

volt test

You should see:

   Compiling counter_test.volt
   Compiling light_test.volt
running 5 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test counts_while_enabled ... ok
test holds_while_disabled ... ok
test wraps_to_zero_after_MAX ... ok
test go_turns_the_light_green ... ok
test red_again_after_green ... ok

cover summary:
  Counter.cov_0 (counter.volt:26)                          hit 1 time
  TrafficLight.cov_0 (light.volt:21, auto FSM transition)  hit 2 times
  TrafficLight.cov_1 (light.volt:27, auto FSM transition)  hit 1 time
  TrafficLight.cov_2 (light.volt:33, auto FSM transition)  hit 1 time
  TrafficLight.cov_3 (light.volt:25, auto counter wrap)    hit 1 time

test result: ok. 5 passed; 0 failed

All tests pass. volt test --watch runs them again every time you save a file.

Coming from SystemVerilog? Tests without a testbench file

A Volt test block compiles to a C++ Verilator testbench: step() toggles every clock of the design, reset is applied before the test body, and the contracts of the design run as monitors on every cycle. There is no initial block, no #delay and no UVM. A passing run records no waveform, so it costs nothing; volt test --waves records every test. The .gtkw file and the translate tables are extra files next to the VCD; the generated SystemVerilog does not change. Volt builds the testbench with Verilator’s -fno-dfg option (Known limitations says why).

Next: what we learned.

What we learned

A short look back at the Tour, and where the Tutorial picks up.

Before you start

  • Window: none. This page has nothing to type.
  • Folder: none. Your work is in volt-projects: the project blinky and the single design in cdc.
  • Running: nothing. You may close Docker Desktop until the next volt test.

In Setup you installed a single binary and asked volt doctor what works on your machine. Then, in about 15 minutes, you have:

  • created a project with volt new, checked it with volt check and turned it into readable SystemVerilog with volt build;
  • written a design with two clock domains in a folder of its own, seen the compiler reject a crossing without a synchronizer (E3001), and fixed it with sync();
  • run simulation tests with volt test, with Verilator running in Docker, and read the cover summary;
  • followed a failing test to its waveform, where a state register shows the names of its states.

The commands you used:

CommandWhat it doesNeeds
cd FOLDERmakes FOLDER the working folder of the terminalnothing
volt new NAMEcreates a project from a templatenothing
volt checkfinds errors, writes no filesnothing
volt buildwrites SystemVerilog to build/rtl/nothing
volt testruns the test blocks of the projectVerilator, or Docker Desktop running
volt explain CODEexplains an error code or a topicnothing
volt doctorsays which commands work herenothing

Two commands did not come up: volt verify, which proves contracts for every input sequence, and volt run, which simulates a design without tests. The Tutorial covers both.

Next

Part II, the Tutorial, starts again from a blank file and builds a counter line by line: modules, ports, registers, clocked blocks, bit widths and tests. Each later chapter adds one idea on top.

A counter

In this chapter you will write a counter from a blank file: a module with ports, a register, a clocked on block and a continuous assignment. You will learn how Volt decides the bit width of a result and why it refuses to drop bits silently, and you will test the counter in simulation.

The output in this chapter was recorded with Volt 0.1.0 on Windows 11, with Verilator running in Docker (see Install Volt).

A file of its own

A project with a Volt.toml is handy, but a single .volt file works too. Make a new directory and create a file named counter.volt in it.

A module, ports and a register

// A free-running 8-bit counter.

pub module Counter {
    in  clk   : clock
    out count : u8

    reg count_r : u8 = 0

    on clk {
        count_r <= count_r + 1
    }

    count = count_r
}

Line by line:

  • pub module Counter { ... } declares a circuit named Counter. pub lets other files use it; a chapter on projects with several files, still planned, comes back to that.
  • in clk : clock and out count : u8 are the ports: the wires that connect the module to the outside. Each port has a direction (in or out), a name and a type. clock is a clock input; u8 is an unsigned number of 8 bits (0 to 255). bool is a single bit that is true or false.
  • reg count_r : u8 = 0 declares a register: 8 bits of storage. The value after = is its reset value.
  • on clk { ... } says what happens at each rising edge of clk. count_r <= count_r + 1 gives the register its next value.
  • count = count_r is a continuous assignment: the output count always shows the current value of count_r.

The _r suffix is a naming habit for registers, not a rule.

New to hardware? Clocks, flip-flops and reset

A clock is a signal that switches between 0 and 1 at a steady rate, for example 50 million times a second. A flip-flop stores one bit and changes it at the moment the clock rises, and at no other time. A register is a row of flip-flops: count_r is eight of them. So the line count_r <= count_r + 1 does not run in a loop; it describes an adder whose output is stored at every clock edge. Reset is a separate input that puts every register back to a known value, here 0, for example after power-up.

Check the file:

Type this:

volt check counter.volt

You should see:

    Checking counter.volt
    Finished 0.00s
      Result 0 error(s), 0 warning(s)
       Next: volt build counter.volt   (emit SystemVerilog)

volt build counter.volt writes build/rtl/Counter.sv. The module part of it:

module Counter (
    input  logic       clk,
    input  logic       rst,
    output logic [7:0] count
);

    logic [7:0] count_r;

    always_ff @(posedge clk) begin
        if (rst) begin
            count_r <= 8'd0;
        end else begin
            count_r <= count_r + 8'd1;
        end
    end

    assign count = count_r;

endmodule

The reset input rst was added for you: a module with a single clock gets a synchronous, active-high reset, and every register returns to its reset value while rst is high.

Coming from SystemVerilog? reg, on and the two kinds of assignment

A reg with its on block becomes one always_ff with the reset branch generated from the initial value; there is no separate reset code to keep in sync. <= is allowed inside an on block and nowhere else, and = outside it: writing o = r inside on clk is error E0006. Unlike Verilog’s reg keyword, a Volt reg is always a flip-flop.

Volt does not yet check that combinational logic assigns every output on every path: an incomplete assignment in a comb block compiles, and the always_comb it becomes infers a latch (see Known limitations). This counter infers no latch, because count is assigned on every path, by the assign above.

Enable and step inputs

A counter that always runs is not very useful. Add an enable input, a step input for the amount to add, and an output low with the lower four bits of the count:

// An 8-bit counter that adds `step` on every clock edge while
// `enable` is high.

pub module Counter {
    in  clk    : clock
    in  enable : bool
    in  step   : u4
    out count  : u8
    out low    : u4

    reg count_r : u8 = 0

    on clk {
        if enable {
            count_r <= count_r + step
        }
    }

    count = count_r
    low   = count_r
}

if enable { ... } inside the on block means: at a clock edge, update the register when enable is high, and keep its value otherwise.

This version has a mistake on purpose. Check it:

Type this:

volt check counter.volt

You should see:

    Checking counter.volt
error[E2001]: an 8-bit value does not fit in a 4-bit target
   ┌─ counter.volt:20:13
   │
20 │     low   = count_r
   │             ^^^^^^^ implicit narrowing is not allowed
   │
   = reason: narrowing drops the upper bits; in hardware that truncation must be visible
   = help: keep the low 4 bits explicitly: (expr)[3:0] as u4
   = for more: volt explain E2001


    Finished 0.00s
      Result 1 error(s), 0 warning(s)

Bit widths

Every value in Volt has a width, and Volt never drops bits without being told. The rules you need for now:

  • An addition can grow by one bit. count_r + step adds an 8-bit and a 4-bit number; the exact sum needs up to 9 bits. Assigned to the 8-bit register, the sum keeps its lower 8 bits: the counter wraps from 255 back to a small number, which is what a counter should do. Assigned to a 9-bit target, the sum keeps its carry. A let without a type keeps the carry too: with a and b both u8, let sum = a + b is a 9-bit value.
  • A wider target is fine. A 12-bit output assigned count_r + step gets the operands widened to 12 bits before the addition.
  • A narrower target is an error. low has 4 bits and count_r has 8. Copying one into the other would lose the upper 4 bits, so Volt asks you to say so (E2001).
  • Literals must fit. reg r : u4 = 20 is an error (E2010), because 4 bits hold at most 15.

The help line shows the fix: name the bits you want. count_r[3:0] selects bits 3 down to 0; the result is bits<4>, four raw bits with no number meaning, and as u4 reads them as a number. Nothing is dropped by the cast, so there is no warning. (A plain count_r as u4 compiles too, but warns with W2010: a narrowing cast can hide a mistake as well as state an intent.)

// An 8-bit counter that adds `step` on every clock edge while
// `enable` is high.

pub module Counter {
    in  clk    : clock
    in  enable : bool
    in  step   : u4
    out count  : u8
    out low    : u4

    reg count_r : u8 = 0

    on clk {
        if enable {
            count_r <= count_r + step
        }
    }

    count = count_r
    low   = count_r[3:0] as u4
}

Type this:

volt check counter.volt

You should see:

    Checking counter.volt
    Finished 0.00s
      Result 0 error(s), 0 warning(s)
       Next: volt build counter.volt   (emit SystemVerilog)

The generated SystemVerilog makes each width explicit:

    always_ff @(posedge clk) begin
        if (rst) begin
            count_r <= 8'd0;
        end else begin
            if (enable) begin
                count_r <= count_r + 8'(step);
            end
        end
    end

    assign count = count_r;
    assign low = count_r[3:0];

Coming from SystemVerilog? No silent truncation or extension

SystemVerilog sizes an expression from its context and truncates or zero-extends to fit: assign low = count_r; compiles, and a lint tool may or may not warn. Volt makes narrowing an error and widening explicit in the output (8'(step)), so verilator -Wall has nothing to say about WIDTHEXPAND or WIDTHTRUNC. The sum of an addition may be assigned at its operand width (it wraps, as a counter needs) or wider (it keeps the carry); a narrower target needs a cast. Signed and unsigned never mix implicitly (E2002).

Test it

Create counter_test.volt next to counter.volt. A file named X_test.volt sees the modules of X.volt:

// Simulation tests for Counter.

test "counts by step while enabled" {
    let dut = Counter { };
    dut.enable = true;
    dut.step = 3;
    step(4);
    assert_eq(dut.count, 12);
    assert_eq(dut.low, 12);
}

test "holds while disabled" {
    let dut = Counter { };
    dut.step = 1;
    step(5);
    assert_eq(dut.count, 0);
}

test "wraps around after 255" {
    let dut = Counter { };
    dut.enable = true;
    dut.step = 15;
    step(17);
    assert_eq(dut.count, 255);
    assert_eq(dut.low, 15);
    step(1);
    assert_eq(dut.count, 14);
    assert_eq(dut.low, 14);
}

Each test starts a fresh counter with its reset applied (Counter { }). Inputs not set by the test are 0, which is why the second test sees no change: enable stays false. step(n) lets n clock edges pass. In the last test, 17 steps of 15 reach 255, and one more step gives 270, which wraps to 270 − 256 = 14.

Type this:

volt test counter_test.volt

You should see:

   Compiling counter_test.volt
running 3 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test counts_by_step_while_enabled ... ok
test holds_while_disabled ... ok
test wraps_around_after_255 ... ok

test result: ok. 3 passed; 0 failed

New to hardware? Why test with numbers that wrap

Hardware counters, timers and addresses have a fixed number of bits, and most bugs hide at the edges: the step from the largest value back to 0, or a value that is one too large for its field. A good test drives the design to those edges on purpose, as the last test does.

What we learned

  • A module has typed in and out ports; clock, bool, u8 and bits<4> are types.
  • reg name : type = value is a register with its reset value; on clk updates registers with <=; = outside it connects outputs.
  • Additions may wrap at the operand width or keep the carry one bit wider; narrowing is an error until you say which bits you want.
  • test blocks drive inputs, advance the clock with step() and check outputs; volt test runs them in Verilator.

Next: a state machine with enum turns a sequence of steps into states.

A state machine with enum

You will turn a sequence of steps into a finite state machine: an enum for the states, a match for the transitions, and the checks Volt adds for you. The compiler requires every state to be handled, and generates a cover for every transition, so a test run shows which transitions your tests never took.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This chapter makes a new folder there, fsm. Type this:

    cd ~/volt-projects
    
  • Running: for the sections from Test it on, Docker Desktop with Engine running in its window (Setup shows how): volt test runs the Verilator simulator in Docker. If Verilator is installed on your computer, Docker is not needed; volt doctor says which one volt test uses.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11, with Docker Desktop running Verilator. On macOS and Linux, paths are written with / instead of \.

A button that bounces

A push button does not switch cleanly. When you press it, the metal contacts bounce for a few milliseconds, and the input goes on and off many times before it stays on. A design that counts presses would count every bounce. A debouncer waits until the input has been steady for a while before it believes it.

The debouncer is a state machine: at any moment it is in one of a few named situations, its states, and at each clock edge it decides from its inputs whether to move to another state. Ours has four:

StateMeansMoves on
Upthe button is releasedto GoingDown when the input is on
GoingDownthe input is on, but not for long enough yetto Down after a steady stretch, back to Up if the input drops
Downthe button is pressedto GoingUp when the input is off
GoingUpthe input is off, but not for long enough yetto Up after a steady stretch, back to Down if the input comes back

Make a folder fsm and go into it:

Type this:

mkdir fsm

Type this:

cd fsm

States as an enum

In this folder, create the file debounce.volt (as Setup shows). This version has a mistake on purpose: one state is missing from the match.

Create this file: debounce.volt

// Cleans up a bouncing push button.

const STABLE : u4 = 4

enum Button { Up, GoingDown, Down, GoingUp }

pub module Debouncer {
    in  clk     : clock
    in  raw     : bool
    out pressed : bool
    out click   : bool

    reg state_r : Button = Button::Up
    reg count_r : u4     = 0

    on clk {
        match state_r {
            Button::Up => {
                if raw {
                    count_r <= 0
                    state_r <= Button::GoingDown
                }
            }
            Button::GoingDown => {
                if !raw {
                    state_r <= Button::Up
                } else if count_r == STABLE - 1 {
                    state_r <= Button::Down
                } else {
                    count_r <= count_r + 1
                }
            }
            Button::Down => {
                if !raw {
                    count_r <= 0
                    state_r <= Button::GoingUp
                }
            }
        }
    }

    pressed = state_r == Button::Down || state_r == Button::GoingUp
    click   = state_r == Button::GoingDown && raw && count_r == STABLE - 1
}

What is new compared with the counter:

  • const STABLE : u4 = 4 names a constant: how many clock cycles the input must stay the same. A real button needs a few milliseconds, hundreds of thousands of cycles; 4 keeps the tests short.
  • enum Button { Up, GoingDown, Down, GoingUp } declares a type whose values are the four states. Button::Up is one of them.
  • reg state_r : Button = Button::Up is the state register. It holds one of the four values, and starts in Up after reset.
  • match state_r { ... } picks the arm for the current state. Each arm, Button::Up => { ... }, says what happens at the clock edge while the machine is in that state. A state that does not write state_r stays where it is.
  • count_r counts how long the input has been steady. Each “going” state sets it to 0 on the way in and counts up; when it reaches STABLE - 1, the machine moves on.
  • pressed and click are outputs computed from the state. == compares two enum values. click is true for the one cycle in which GoingDown decides that the press is real: a single pulse per press, however long the button is held.

New to hardware? A state machine is a register and a decision

In software a sequence of steps is code that runs from top to bottom. In hardware nothing runs from top to bottom: at every clock edge all the logic is evaluated at once. To do one thing after another, the circuit keeps a register that says which step it is at, and logic that picks the next step from that register and the inputs. That pair is a finite state machine (FSM). Naming the steps with an enum makes the register readable: Button::GoingDown instead of the number 1.

Every state needs an arm

Check the file:

Type this:

volt check debounce.volt

You should see:

    Checking debounce.volt
error[E0014]: 'match' on enum 'Button' does not cover every variant: missing Button::GoingUp
   ┌─ debounce.volt:17:9
   │  
17 │ ╭         match state_r {
18 │ │             Button::Up => {
19 │ │                 if raw {
20 │ │                     count_r <= 0
   · │
38 │ │             }
39 │ │         }
   │ ╰─────────^ not every variant is covered
   │  
   = note: an enum match that names every variant needs no '_' arm; its last arm also takes the codes no variant uses
   = help: add an arm for each missing variant (Button::GoingUp => { }) or a final '_ => { }' arm
   = for more: volt explain E0014


    Finished 0.01s
      Result 1 error(s), 0 warning(s)

The match handles three of the four states, and error E0014 names the one that is missing. In SystemVerilog, a case without that branch would compile, and the machine would freeze in GoingUp the earliest time it got there. Volt rejects it at compile time.

The help line offers two fixes: an arm for Button::GoingUp, or a final _ => { } arm that catches every state not named above it. Prefer the arm: with _, a state you add to the enum later is silently caught by it, and the compiler can no longer tell you that you forgot it. Add the missing arm:

Replace this file: debounce.volt

// Cleans up a bouncing push button.

const STABLE : u4 = 4

enum Button { Up, GoingDown, Down, GoingUp }

pub module Debouncer {
    in  clk     : clock
    in  raw     : bool
    out pressed : bool
    out click   : bool

    reg state_r : Button = Button::Up
    reg count_r : u4     = 0

    on clk {
        match state_r {
            Button::Up => {
                if raw {
                    count_r <= 0
                    state_r <= Button::GoingDown
                }
            }
            Button::GoingDown => {
                if !raw {
                    state_r <= Button::Up
                } else if count_r == STABLE - 1 {
                    state_r <= Button::Down
                } else {
                    count_r <= count_r + 1
                }
            }
            Button::Down => {
                if !raw {
                    count_r <= 0
                    state_r <= Button::GoingUp
                }
            }
            Button::GoingUp => {
                if raw {
                    state_r <= Button::Down
                } else if count_r == STABLE - 1 {
                    state_r <= Button::Up
                } else {
                    count_r <= count_r + 1
                }
            }
        }
    }

    pressed = state_r == Button::Down || state_r == Button::GoingUp
    click   = state_r == Button::GoingDown && raw && count_r == STABLE - 1
}

Type this:

volt check debounce.volt

You should see:

    Checking debounce.volt
    Finished 0.02s
      Result 0 error(s), 0 warning(s)
       Next: volt build debounce.volt   (emit SystemVerilog)

Test it

Create debounce_test.volt next to debounce.volt:

Create this file: debounce_test.volt

// Simulation tests for Debouncer.

test "a steady press is seen once" {
    let dut = Debouncer { };
    dut.raw = true;
    step(4);
    assert_false(dut.pressed);
    assert_true(dut.click);
    step(1);
    assert_true(dut.pressed);
    assert_false(dut.click);
    step(10);
    assert_true(dut.pressed);
    assert_false(dut.click);
}

test "a short bounce is ignored" {
    let dut = Debouncer { };
    dut.raw = true;
    step(2);
    dut.raw = false;
    step(1);
    dut.raw = true;
    step(2);
    dut.raw = false;
    step(5);
    assert_false(dut.pressed);
}

test "a release needs a steady low too" {
    let dut = Debouncer { };
    dut.raw = true;
    step(5);
    dut.raw = false;
    step(2);
    assert_true(dut.pressed);
    step(3);
    assert_false(dut.pressed);
}

The earliest test holds the button down. After 4 cycles the machine has been in GoingDown long enough: click is on for that cycle, and from the next one on the button counts as pressed. The second test presses for two cycles, lets go, presses again and lets go: no stretch is long enough, so pressed never turns on. The third test releases the button and checks that pressed stays on until the release has been steady.

Check that Docker Desktop says Engine running, then run the tests:

Type this:

volt test debounce_test.volt

You should see:

   Compiling debounce_test.volt
running 3 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test a_steady_press_is_seen_once ... ok
test a_short_bounce_is_ignored ... ok
test a_release_needs_a_steady_low_too ... ok

cover summary:
  Debouncer.cov_0 (debounce.volt:21, auto FSM transition)  hit 4 times
  Debouncer.cov_1 (debounce.volt:26, auto FSM transition)  hit 2 times
  Debouncer.cov_2 (debounce.volt:28, auto FSM transition)  hit 2 times
  Debouncer.cov_3 (debounce.volt:36, auto FSM transition)  hit 1 time
  Debouncer.cov_4 (debounce.volt:41, auto FSM transition)  NEVER HIT
  Debouncer.cov_5 (debounce.volt:43, auto FSM transition)  hit 1 time
  Debouncer.cov_6 (debounce.volt:27, auto counter wrap)    hit 16 times

test result: ok. 3 passed; 0 failed

The three tests pass. Below them is a cover summary with seven lines, although the design has no cover line. Volt found the state machine in the match and generated a cover for every transition the code can make, plus one for the counter. Each line names where the transition is written, and how many cycles of the test run took it:

  • debounce.volt:21 is the line state_r <= Button::GoingDown in the Up arm: the transition from Up to GoingDown. It was taken 4 times, at least once in each test.
  • debounce.volt:41 is the line state_r <= Button::Down in the GoingUp arm: a bounce while the button is being released. NEVER HIT means that no test made that transition, so it was never tested.
  • auto counter wrap counts the cycles in which count_r holds its largest value, STABLE - 1.

A transition no test took

Add a test for the bounce on release: hold the button, let go for a single cycle, press again. Replace the test file:

Replace this file: debounce_test.volt

// Simulation tests for Debouncer.

test "a steady press is seen once" {
    let dut = Debouncer { };
    dut.raw = true;
    step(4);
    assert_false(dut.pressed);
    assert_true(dut.click);
    step(1);
    assert_true(dut.pressed);
    assert_false(dut.click);
    step(10);
    assert_true(dut.pressed);
    assert_false(dut.click);
}

test "a short bounce is ignored" {
    let dut = Debouncer { };
    dut.raw = true;
    step(2);
    dut.raw = false;
    step(1);
    dut.raw = true;
    step(2);
    dut.raw = false;
    step(5);
    assert_false(dut.pressed);
}

test "a release needs a steady low too" {
    let dut = Debouncer { };
    dut.raw = true;
    step(5);
    dut.raw = false;
    step(2);
    assert_true(dut.pressed);
    step(3);
    assert_false(dut.pressed);
}

test "a bounce on release keeps the press" {
    let dut = Debouncer { };
    dut.raw = true;
    step(5);
    dut.raw = false;
    step(1);
    dut.raw = true;
    step(5);
    assert_true(dut.pressed);
    assert_false(dut.click);
}

Type this:

volt test debounce_test.volt

You should see:

   Compiling debounce_test.volt
running 4 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test a_steady_press_is_seen_once ... ok
test a_short_bounce_is_ignored ... ok
test a_release_needs_a_steady_low_too ... ok
test a_bounce_on_release_keeps_the_press ... ok

cover summary:
  Debouncer.cov_0 (debounce.volt:21, auto FSM transition)  hit 5 times
  Debouncer.cov_1 (debounce.volt:26, auto FSM transition)  hit 2 times
  Debouncer.cov_2 (debounce.volt:28, auto FSM transition)  hit 3 times
  Debouncer.cov_3 (debounce.volt:36, auto FSM transition)  hit 2 times
  Debouncer.cov_4 (debounce.volt:41, auto FSM transition)  hit 1 time
  Debouncer.cov_5 (debounce.volt:43, auto FSM transition)  hit 1 time
  Debouncer.cov_6 (debounce.volt:27, auto counter wrap)    hit 18 times

test result: ok. 4 passed; 0 failed

Every transition is now taken by at least one test. The last assert also checks that the bounce did not produce a second click.

New to hardware? Why count transitions

A test that passes tells you that the design did what the test expected. It does not tell you what the test left out. In a state machine the rare paths, a bounce at the wrong moment or an error in the middle of a transfer, are the ones that break in the lab, and they are easy to forget. Counting the transitions turns “did I test everything?” into a list you can read.

The SystemVerilog

Type this:

volt build debounce.volt

You should see:

   Compiling debounce.volt
    Finished 0.01s (1 source file(s), 1 SV file(s))
     Output build\rtl\Debouncer.sv (72 lines)
       Next: volt run debounce.volt      (simulate)
             volt verify debounce.volt   (prove contracts)

Open build/rtl/Debouncer.sv (in the fsm folder) in your editor. This is a part of it (output trimmed):

You should see:

    localparam logic [1:0] Button_Up        = 2'd0;
    localparam logic [1:0] Button_GoingDown = 2'd1;
    localparam logic [1:0] Button_Down      = 2'd2;
    localparam logic [1:0] Button_GoingUp   = 2'd3;

    logic [1:0] state_r;  // Button
...
            case (state_r)
                Button_Up: begin
                    if (raw) begin
                        count_r <= 4'd0;
                        state_r <= Button_GoingDown;
                    end
                end
...
                default: begin // Button_GoingUp

Each state becomes a localparam with the state’s name, numbered in the order of the enum, and the match becomes a case. The arm of the last state is the default branch, with its name in a comment: a value that names no state, which cannot happen here, is handled like GoingUp.

Coming from SystemVerilog? What the compiler checks for you

In SystemVerilog an FSM is usually a typedef enum, a case with a default, and a lint rule or a review to catch a missing state. Volt makes the missing arm a compile error (E0014) and writes no typedef: the states are localparams, so the output reads the same in every tool. The generated transition covers are SVA cover property statements in volt build --emit=sva, and volt test counts them in simulation. When the states do not fill the bits of the register, for example three states in two bits, Volt also generates an invariant that the register holds a valid state; the four states here use all four codes. The waveform of a failed test shows the state names, as in Tests and waveforms.

You are in the fsm folder.

What we learned

  • enum Name { A, B, C } declares the states; a reg of that type, reg state_r : Name = Name::A, is the state register, with a state as its reset value.
  • match on the state register gives each state an arm; an arm that does not write the register keeps the state.
  • A match must handle every state: a missing one is error E0014. Prefer an arm per state over a _ arm.
  • const names a number, such as how long an input must stay steady.
  • Volt generates a cover for every transition, and volt test lists them: NEVER HIT points at a transition no test took.

Next: two clocks and CDC moves data between parts of a design that run on different clocks.

Two clocks and CDC

You will declare clock domains, see why a signal cannot simply cross from one to another, and use sync() and AsyncFifo to cross safely. The chapter also covers resets in a design with several clocks.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This chapter makes a new folder there, clocks. Type this:

    cd ~/volt-projects
    
  • Running: for the section Test it, Docker Desktop with Engine running in its window (Setup shows how): volt test runs the Verilator simulator in Docker. If Verilator is installed on your computer, Docker is not needed; volt doctor says which one volt test uses. The other sections need nothing but Volt.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11, with Docker Desktop running Verilator. On macOS and Linux, paths are written with / instead of \.

Two clocks, two domains

The Tour moved a single bit, a button, from one clock to another. This chapter moves numbers. A sensor chip, here an analog-to-digital converter (ADC), delivers 8-bit samples with a clock of its own; the rest of the design runs on the system clock. Each clock, with the registers it drives, is a clock domain. The samples have to cross from the ADC domain into the system domain.

Make a folder clocks and go into it:

Type this:

mkdir clocks

Type this:

cd clocks

In this folder, create the file sample_bridge.volt (as Setup shows). This version keeps the latest sample in a register of the ADC domain and copies it into a register of the system domain:

Create this file: sample_bridge.volt

// Samples from a sensor clock reach the system clock.

domain Adc {
    clock = posedge
    reset = sync active_high
}

domain Sys {
    clock = posedge
    reset = sync active_high
}

pub module SampleBridge {
    in  adc_clk      : clock @Adc
    in  sys_clk      : clock @Sys
    in  rst          : reset(sync, active_high)
    in  sample       : u8    @Adc
    in  sample_valid : bool  @Adc
    out data         : u8    @Sys

    reg last_r : u8 = 0
    on adc_clk {
        if sample_valid {
            last_r <= sample
        }
    }

    reg data_r : u8 = 0
    on sys_clk {
        data_r <= last_r
    }

    data = data_r
}

What is new compared with the counter:

  • A domain block names a clock domain and says how its registers work. clock = posedge means they update on the rising edge of the clock. reset = sync active_high means their reset is synchronous, read at a clock edge like any other input, and active high: 1 means reset.
  • @Adc after a port type puts the port into the domain Adc. The clock port adc_clk is the clock of that domain.
  • A register belongs to the domain of the on block that writes it: last_r to Adc, data_r to Sys.
  • in rst : reset(sync, active_high) is the reset input of the design. Reset with two clocks below explains why it is written out here, while the counter got its reset without asking.

A design with a single clock needs no domain at all; Volt puts everything into one domain by itself.

This design is wrong on purpose. Check it:

Type this:

volt check sample_bridge.volt

You should see:

    Checking sample_bridge.volt
error[E3001]: direct assignment between clock domains
   ┌─ sample_bridge.volt:30:9
   │
 3 │ domain Adc {
   │        --- source @Adc defined here
   ·
 8 │ domain Sys {
   │        --- destination @Sys defined here
   ·
30 │         data_r <= last_r
   │         ^^^^^^    ------ @Adc
   │         │          
   │         @Sys
   │
   = reason: the destination register may sample the source signal during an unstable window (metastability)
   = note: for multi-bit data, AsyncFifo may be safer
   = help: synchronize at module level, outside this block: let s = sync(<signal>, <clock of Sys>), then read s here
   = for more: volt explain E3001


    Finished 0.01s
      Result 1 error(s), 0 warning(s)

Line 30 reads last_r, a register of Adc, in an on sys_clk block of Sys. That is a clock domain crossing (CDC) without a synchronizer, error E3001. The note line already points to the way out for a number: AsyncFifo. The next section shows why the sync() of the Tour is not enough here.

Why sync() is not enough for a number

sync() builds a two-flop synchronizer for each bit. Do what the help line suggests: synchronize last_r at module level and read the synchronized name in the on sys_clk block. Replace the file:

Replace this file: sample_bridge.volt

// Samples from a sensor clock reach the system clock.

domain Adc {
    clock = posedge
    reset = sync active_high
}

domain Sys {
    clock = posedge
    reset = sync active_high
}

pub module SampleBridge {
    in  adc_clk      : clock @Adc
    in  sys_clk      : clock @Sys
    in  rst          : reset(sync, active_high)
    in  sample       : u8    @Adc
    in  sample_valid : bool  @Adc
    out data         : u8    @Sys

    reg last_r : u8 = 0
    on adc_clk {
        if sample_valid {
            last_r <= sample
        }
    }

    let last_s = sync(last_r, sys_clk)

    reg data_r : u8 = 0
    on sys_clk {
        data_r <= last_s
    }

    data = data_r
}

Type this:

volt check sample_bridge.volt

You should see:

    Checking sample_bridge.volt
warning[W3003]: two-flop synchronization does not guarantee bit coherence for 8-bit signals
   ┌─ sample_bridge.volt:28:18
   │
28 │     let last_s = sync(last_r, sys_clk)
   │                  ^^^^^^^^^^^^^^^^^^^^^ bits may be captured on different edges
   │
   = reason: a two-flop synchronizer synchronizes each bit independently; when bits are captured on different clock edges an invalid intermediate value appears
   = help: for multi-bit data use one of:
                AsyncFifo<T, N>   — data streams
                HandshakeSync<T>  — single transfers
                gray coding       — counters
                AsyncDualPortRam<T, N> — random-access data
   = for more: volt explain W3003


    Finished 0.01s
      Result 0 error(s), 1 warning(s)
       Next: volt build sample_bridge.volt   (emit SystemVerilog)

The design compiles now, with warning W3003: eight synchronizers side by side do not keep the eight bits together.

New to hardware? Why the bits of a number fall apart

Each synchronizer settles on its own. When last_r goes from 127 (0111_1111) to 128 (1000_0000), all eight bits change at once. If the system clock samples during the change, some synchronizers pass the new bit one cycle before the others, and for that cycle the system domain sees a mix of old and new bits: 255, 0, or any other value that last_r never held. A single bit has no such problem: it is either old or new.

It is a warning and not an error because some values survive it: a counter in Gray code changes one bit at a time, and a setting that is written once and read much later has long settled. For a stream of samples, use a FIFO.

A FIFO between the clocks

AsyncFifo is a built-in component: a small memory written on one clock and read on the other, with the synchronizers it needs inside. Every sample goes in on the ADC side and comes out on the system side, in the same order. This version of the design also says when data holds a new sample (data_valid), and when a sample was lost because the FIFO was full (dropped). Replace the file:

Replace this file: sample_bridge.volt

// Samples from a sensor clock reach the system clock.

domain Adc {
    clock = posedge
    reset = sync active_high
}

domain Sys {
    clock = posedge
    reset = sync active_high
}

pub module SampleBridge {
    in  adc_clk      : clock @Adc
    in  sys_clk      : clock @Sys
    in  rst          : reset(sync, active_high)
    in  sample       : u8    @Adc
    in  sample_valid : bool  @Adc
    out data         : u8    @Sys
    out data_valid   : bool  @Sys
    out dropped      : bool  @Adc

    wire take : bool @Sys

    let fifo = AsyncFifo<u8, 4> {
        wr_clk:  adc_clk,
        wr_data: sample,
        wr_en:   sample_valid,
        rd_clk:  sys_clk,
        rd_en:   take,
    }

    take = !fifo.rd_empty

    reg valid_r : bool = false
    on sys_clk {
        valid_r <= take
    }

    data       = fifo.rd_data
    data_valid = valid_r
    dropped    = sample_valid && fifo.wr_full
}

Type this:

volt check sample_bridge.volt

You should see:

    Checking sample_bridge.volt
    Finished 0.01s
      Result 0 error(s), 0 warning(s)
       Next: volt build sample_bridge.volt   (emit SystemVerilog)

How it works:

  • AsyncFifo<u8, 4> holds up to 4 values of type u8. The size must be a power of two.
  • The ports that start with wr_ belong to the domain of wr_clk, here Adc; the ports that start with rd_ belong to the domain of rd_clk, Sys. Volt checks what you connect: sample is @Adc and goes to wr_data. Connecting sample_valid to rd_en would be error E3001 again.
  • fifo.rd_empty is true when there is nothing to read, and fifo.wr_full is true when there is no room. The read side reads whenever the FIFO is not empty: take = !fifo.rd_empty.
  • wire take : bool @Sys declares the wire, with its domain, above the FIFO, because a name must be declared before it is used (error E1002). Its value is given further down. The @Sys is a promise that Volt checks: assigning it a value of Adc would be an error.
  • fifo.rd_data is a register: a value read with rd_en appears on it one clock cycle later. valid_r delays take by the same cycle, so data_valid is true exactly when data holds a new sample.
  • dropped is in the Adc domain, because both of its inputs are.

Coming from SystemVerilog? A dual-clock FIFO without an IP core

In SystemVerilog you would instantiate a vendor FIFO generator or a hand-written FIFO with Gray-coded pointers, and a CDC tool would be told to trust it. AsyncFifo is generated into the module itself: Gray-coded read and write pointers, a two-flop synchronizer for each pointer, and a comment that names the crossing. The compiler knows which side belongs to which domain, so the crossing is checked like any other. Other built-in bridges: HandshakeSync for a single word now and then, PulseSync for a one-cycle pulse, AsyncDualPortRam for a memory (volt explain stdlib).

Reset with two clocks

A reset has to be released in step with the clock of every register it resets. With one clock that is easy. With two, the moment the reset goes away may be right on an edge of one clock while it is far from the edges of the other.

The line in rst : reset(sync, active_high) declares the reset as a raw input: it comes from outside and is in step with neither clock. For a raw reset, Volt builds one reset synchronizer for each clock that it reaches, two flip-flops that pass the release on in step with that clock. Each domain is then reset from its own copy.

Without that line, Volt still adds a reset port named rst, as for the counter, but it cannot know which clock the reset is in step with, and volt check warns:

You should see (if the rst line is missing):


Keep the line. The recipe Reset synchronizers shows the generated synchronizers, asynchronous resets and the related errors.

Test it

Create sample_bridge_test.volt next to sample_bridge.volt:

Create this file: sample_bridge_test.volt

// Simulation tests for SampleBridge. The test bench drives every clock
// of the design together, one edge per step().

test "samples cross in order" {
    let dut = SampleBridge { };
    dut.sample_valid = true;
    dut.sample = 10;
    step(1);
    dut.sample = 20;
    step(1);
    dut.sample = 30;
    step(1);
    dut.sample_valid = false;
    assert_false(dut.data_valid);
    step(1);
    assert_true(dut.data_valid);
    assert_eq(dut.data, 10);
    step(1);
    assert_eq(dut.data, 20);
    step(1);
    assert_eq(dut.data, 30);
    step(1);
    assert_false(dut.data_valid);
}

test "a full FIFO drops samples" {
    let dut = SampleBridge { };
    dut.sample_valid = true;
    step(3);
    assert_false(dut.dropped);
    step(1);
    assert_true(dut.dropped);
}

The test bench drives both clocks together: step(1) gives one rising edge to adc_clk and one to sys_clk. The tests cannot run the two clocks at different speeds, so they do not show the timing problems a synchronizer protects against. What they show is the order of the samples and how long a crossing takes. In the earliest test, the sample 10 is written on edge 1 and is on data after edge 4: the write pointer has to pass a synchronizer before the read side sees it, and the read itself takes a cycle. In the second test a sample arrives on every edge. After four of them the write side sees the FIFO as full, because it learns about the reads through a synchronizer too, and dropped turns on: the next sample would be lost.

Check that Docker Desktop says Engine running, then run the tests:

Type this:

volt test sample_bridge_test.volt

You should see:

   Compiling sample_bridge_test.volt
running 2 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test samples_cross_in_order ... ok
test a_full_FIFO_drops_samples ... ok

cover summary:
  SampleBridge.fifo_cov_0 (sample_bridge.volt:25)  hit 1 time
  SampleBridge.fifo_cov_1 (sample_bridge.volt:25)  hit 10 times

test result: ok. 2 passed; 0 failed

The cover summary lists two covers that you did not write: AsyncFifo brings them along, which is why both point to line 25, the let fifo line. fifo_cov_0 counts the cycles in which the FIFO was full, fifo_cov_1 those in which it was empty. Both were reached, so the tests drove the FIFO to both of its limits.

The SystemVerilog

Type this:

volt build sample_bridge.volt

You should see:

   Compiling sample_bridge.volt
    Finished 0.01s (1 source file(s), 1 SV file(s))
     Output build\rtl\SampleBridge.sv (127 lines)
       Next: volt run sample_bridge.volt      (simulate)
             volt verify sample_bridge.volt   (prove contracts)

build/rtl/SampleBridge.sv holds one module, with the FIFO and the reset synchronizers inside. These comment lines in it name each part (output trimmed):

You should see:

    // reset synchronizer: rst -> adc_clk (async assert, sync release)
    // reset synchronizer: rst -> sys_clk (async assert, sync release)
    // AsyncFifo 'fifo': adc_clk -> sys_clk, depth 4 (gray-code pointers)

You are in the clocks folder.

What we learned

  • A domain names a clock domain; @Name puts a port or a wire into it, and a register belongs to the domain of its on block.
  • Reading a signal of one domain in another is error E3001.
  • sync() is for a single bit. On a number it is warning W3003, because the bits can arrive in different cycles.
  • AsyncFifo carries a stream of values between two clocks; its wr_ and rd_ ports belong to the two domains.
  • A raw reset port, in rst : reset(...), gets one reset synchronizer per clock.
  • volt test drives every clock together, one edge per step().

Next: contracts and formal verification prove properties of a design for every input, not just the ones a test tries.

Contracts and formal verification

You will state properties of a design with invariant, requires, ensures and cover, and prove them for every input sequence with volt verify. You will read a counterexample and learn when bounded checking is enough and when you need a proof.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This chapter makes a new folder there, formal. Type this:

    cd ~/volt-projects
    
  • Running: volt verify needs three tools that Volt does not bring along: Yosys, SymbiYosys and an SMT solver.

    • Windows: these tools do not run on Windows by themselves. Start Docker Desktop and wait for Engine running in its window (Setup shows how). Volt then runs the tools in a container. The container image is downloaded the earliest time you run volt verify: about 400 MB, which takes a few minutes.
    • macOS and Linux: Docker Desktop works the same way. Instead, you can install the tools: the YosysHQ OSS CAD Suite has all three in one download (volt explain verify-setup says where to get it).

    volt doctor shows how volt verify will run: with Docker Desktop running, its line reads ✓ verify — via Docker.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11, with Docker Desktop running the tools. On macOS and Linux, paths are written with / instead of \.

Tests try some inputs, a proof tries all

The counter chapter tested a design: the test chose the inputs, cycle by cycle, and checked the outputs. A test shows that the design works for those inputs. It says nothing about the inputs nobody thought of.

A contract is a property written into the design itself, such as “the level never goes above 4”. Formal verification asks a solver, a program that searches through every possible input sequence, whether any of them breaks the contract. If one does, you get that input sequence as a counterexample, cycle by cycle. If none does, the property holds for every input the solver could choose.

Volt has four kinds of contract:

KeywordMeansMay read
invariant:always trueports and registers
requires:what the module expects from the module that uses itports
ensures:what the module promises in returnports
cover:something that must be able to happeneverything

volt verify checks them with formal verification. volt test checks them too, while a test runs.

A buffer with four slots

Make a folder formal and go into it:

Type this:

mkdir formal

Type this:

cd formal

The design keeps count of the items in a buffer with four slots: push puts an item in, pop takes one out. Create the file occupancy.volt (as Setup shows):

Create this file: occupancy.volt

// Keeps count of the items in a buffer with four slots.

pub module Occupancy {
    in  clk   : clock
    in  push  : bool
    in  pop   : bool
    out level : u3
    out full  : bool
    out empty : bool

    reg level_r : u3 = 0

    on clk {
        if push && !pop {
            level_r <= level_r + 1
        } else if pop && !push {
            level_r <= level_r - 1
        }
    }

    level = level_r
    full  = level_r == 4
    empty = level_r == 0

    invariant: level_r <= 4
    cover: full
}

The two lines at the bottom are contracts:

  • invariant: level_r <= 4 says that the register never holds more than 4. level_r has 3 bits and could hold up to 7.
  • cover: full says that the buffer can become full. A cover is not a promise that something always happens, but that it can happen at all; Covers below shows why that matters.

push and pop together leave the level as it is: one item goes in and one comes out.

Check that Docker Desktop says Engine running, then verify the design. This takes a few minutes the earliest time, because of the download:

Type this:

volt verify occupancy.volt

You should see:

   Verifying occupancy.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
note: downloading hdlc/formal:all (~404 MB, first use only; this can take several minutes)
note: downloaded hdlc/formal:all in 1m 18s
     [1/1] Occupancy (2 properties) ... FAIL (0.28s)
error[E5001]: contract violated
   ┌─ occupancy.volt:25:16
   │
25 │     invariant: level_r <= 4
   │                ^^^^^^^^^^^^ violated at cycle 3
   │
   = reason: the 'invariant' contract of module 'Occupancy' does not hold for every reachable state
   = counterexample: build\formal\occupancy_cex.vcd
   = help: open the counterexample with 'gtkwave' or 'surfer'
   = for more: volt explain E5001


    Finished 83.09s
    Failures:
      Occupancy.inv_0  E5001 contract violated at cycle 3
      Result 1 of 2 properties failed in 83.1s (16 jobs; bmc, depth 20)
        Next: volt explain E5001   (how to read a counterexample)

The two downloading notes appear once. This run took 83 seconds, almost all of it for the download; the runs after it take about a second and a half.

The invariant is violated. volt verify exits with code 6 and writes the counterexample to build\formal\occupancy_cex.vcd. The summary line counts two properties, the invariant and the cover, and says how the search was made: bmc, depth 20 means the solver looked at the 20 clock cycles after reset (the next sections explain the other modes). 16 jobs is the number of processor cores of the recording computer; your number may differ.

Read the counterexample

A counterexample is a waveform, like the ones a failing test writes. Open it in GTKWave (Tests and waveforms shows how to install it), from the formal folder:

Type this (Windows, PowerShell):

gtkwave build\formal\occupancy_cex.vcd

Type this (macOS and Linux):

gtkwave build/formal/occupancy_cex.vcd

In GTKWave, open Occupancy in the tree at the top left and add the signals to the view. Add smt_step from the top of the tree as well: it numbers the clock cycles of the counterexample from 0.

GTKWave showing smt_step, clk, rst, push, pop and level_r for cycles 0 to 3. In cycle 0 rst is 1 and level_r is 0. In cycle 1 pop is 1 and push is 0 while level_r is 0. From cycle 2 on level_r is 7.

The screenshot was taken with GTKWave 3.3.121 on Linux (Debian 13). Read it cycle by cycle:

  • Cycle 0: rst is 1. The solver always starts from reset, so level_r is 0.
  • Cycle 1: pop is 1 and push is 0, while the buffer is empty.
  • Cycle 2: level_r is 7. 0 - 1 wrapped around in 3 bits.

The invariant is checked at each clock edge, so the error names the edge after cycle 2: cycle 3. The design itself does what it says. The mistake is in what it allows: nothing stops a pop from an empty buffer, or a push into a full one.

New to hardware? Why a test would miss this

A test that pops an empty buffer would find this bug at once, but you have to think of writing that test. The solver does not think about what is sensible: it tries every input, including the ones a careful user would never send, and here it needed two cycles to find one. That is why formal verification is good at finding the cases nobody wrote a test for.

Requires and ensures

There are two ways to fix this. The design could ignore a pop from an empty buffer. Or the module can say that it is never asked to do that, and leave the duty to the module that uses it. That is what requires is for. Replace the file:

Replace this file: occupancy.volt

// Keeps count of the items in a buffer with four slots.

pub module Occupancy {
    in  clk   : clock
    in  push  : bool
    in  pop   : bool
    out level : u3
    out full  : bool
    out empty : bool

    // The module that uses Occupancy promises these.
    requires: !(push && full)
    requires: !(pop && empty)

    reg level_r : u3 = 0

    on clk {
        if push && !pop {
            level_r <= level_r + 1
        } else if pop && !push {
            level_r <= level_r - 1
        }
    }

    level = level_r
    full  = level_r == 4
    empty = level_r == 0

    invariant: level_r <= 4
    ensures: prev(push) && !prev(pop) -> (level as u4) == prev(level) + 1
    cover: full
}

What changed:

  • requires: !(push && full) and requires: !(pop && empty): no push while the buffer is full, no pop while it is empty. While Occupancy is verified, these are taken as given: the solver chooses no input that breaks them.
  • ensures: ... -> ... is a promise about the outputs. a -> b reads “if a, then b”. prev(x) is the value x had one cycle earlier, and prev(x, 2) two cycles earlier. The line says: after a cycle with a push and no pop, the level is exactly one higher than it was.
  • level as u4 makes level one bit wider, for the reason below.

An addition keeps its carry: prev(level) + 1 is a 4-bit value, because 3 bits plus one can need a fourth bit (7 + 1 = 8). Compared with the 3-bit level, the comparison could drop that carry, wrapping at 3 bits, or keep it, and the two answers differ when the sum does not fit. Volt does not guess: written as level == prev(level) + 1, the line is error E2031, and the error offers both ways to write it:

  • level == (prev(level) + 1)[2:0] as u3 keeps the low 3 bits of the sum: it wraps at 3 bits, so 7 + 1 counts as 0;
  • (level as u4) == prev(level) + 1 widens level to 4 bits: it keeps the carry, so 7 + 1 is 8.

Here the carry is kept: the level counts items and never wraps, and the ensures should say so.

Type this:

volt verify occupancy.volt

You should see:

   Verifying occupancy.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Occupancy (3 properties, 2 assumed) ... ok (0.26s)
    Finished 1.28s
        Note 2 assumption(s) about the environment, not verified: Occupancy.req_0, Occupancy.req_1
      Result 3 properties verified in 1.3s (16 jobs; bmc, depth 20)

All three properties hold. The Note line lists the two requires: they were assumed, not checked, because nothing in this file uses Occupancy. When another module uses it, volt verify on that module checks them there, as properties of the module that has to keep them.

Covers: can it happen at all?

A requires that is too strict makes every check pass for a bad reason. Suppose the upper requires read requires: !push: the solver may then never push, the buffer stays empty, and the invariant holds, without saying anything about a buffer that is in use. A cover catches this. Verify again in cover mode:

Type this:

volt verify --mode cover occupancy.volt

You should see:

   Verifying occupancy.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Occupancy (3 properties, 2 assumed) ... ok (0.20s)
    Finished 1.20s
        Note 2 assumption(s) about the environment, not verified: Occupancy.req_0, Occupancy.req_1
      Result 3 properties verified in 1.2s (16 jobs; cover, depth 20)

In cover mode the solver searches for a way to reach each cover within the depth. It found one for cover: full, so the buffer can fill up while the requires hold. With requires: !push in place of the upper requires, the same command reports the cover as an error:

You should see (with requires: !push):


In cover mode the error means “not reached within the depth”: the solver searched the 20 cycles of the depth and found no way to make full true; the cycle in the message is the last one it searched. The words of the message are the ones used for a broken property (“violated”, “does not hold”), and no counterexample file is written, although the help line names one; volt explain E5001 describes both modes. Run --mode cover whenever you add or change a requires.

Twenty cycles, or every cycle

So far volt verify ran in its default mode, bmc (bounded model checking): the solver looked for a counterexample within 20 cycles after reset. That is enough for Occupancy, which reaches each of its levels within a few cycles. It is not enough for a design that needs more cycles to go wrong.

This module gives a pulse every 25 cycles, and has a bug: it counts to 25 instead of 24, so the count reaches 25 for one cycle. Create divider.volt:

Create this file: divider.volt

// Gives a one-cycle tick every 25 clock cycles.

pub module Divider {
    in  clk  : clock
    out tick : bool

    reg count_r : u5 = 0

    on clk {
        if count_r == 25 {
            count_r <= 0
        } else {
            count_r <= count_r + 1
        }
    }

    tick = count_r == 24

    invariant: count_r < 25
}

Type this:

volt verify divider.volt

You should see:

   Verifying divider.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Divider (3 properties) ... ok (0.24s)
    Finished 1.28s
      Result 3 properties verified in 1.3s (16 jobs; bmc, depth 20)

Every property holds, because the count reaches 25 after more than 20 cycles. The design has three properties although you wrote one: for a counter, Volt adds an upper bound and a cover of its wrap by itself.

A passing bmc run says: no counterexample within 20 cycles. To know about every cycle, ask for a proof:

Type this:

volt verify --mode prove divider.volt

You should see:

   Verifying divider.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Divider (3 properties) ... unknown (0.26s)
error[E5002]: contract not proven: the induction step failed
   ┌─ divider.volt:19:16
   │
19 │     invariant: count_r < 25
   │                ^^^^^^^^^^^^ not inductive at depth 20
   │
   = reason: no counterexample exists within 20 cycles from reset, but the induction step starts from an arbitrary state — possibly unreachable — and the 'invariant' contract of module 'Divider' fails from there (sby status UNKNOWN)
   = note: induction trace (may start from an unreachable state): build\formal\divider_induct.vcd
   = help: try a larger --depth, or add an invariant that makes the property inductive
   = for more: volt explain E5002


    Finished 1.29s
    Failures:
      Divider.inv_0  E5002 not proven (induction step failed)
      Result 0 of 3 properties failed, 1 not proven in 1.3s (16 jobs; prove, depth 20)
        Next: volt explain E5002   (why a true property can fail induction)

--mode prove uses induction: if the property held for 20 cycles in a row, starting anywhere, does it hold in the next one? Here it does not, so the proof fails, and the command exits with code 7, “not proven”. That is not yet a bug: the solver may have started from a state the design can never reach. The help line names the two ways on. A larger depth looks further:

Type this:

volt verify --depth 30 divider.volt

You should see:

   Verifying divider.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Divider (3 properties) ... FAIL (0.27s)
error[E5001]: contract violated
   ┌─ divider.volt:19:16
   │
19 │     invariant: count_r < 25
   │                ^^^^^^^^^^^^ violated at cycle 27
   │
   = reason: the 'invariant' contract of module 'Divider' does not hold for every reachable state
   = counterexample: build\formal\divider_cex.vcd
   = help: open the counterexample with 'gtkwave' or 'surfer'
   = for more: volt explain E5001


    Finished 1.34s
    Failures:
      Divider.inv_0  E5001 contract violated at cycle 27
      Result 1 of 3 properties failed in 1.3s (16 jobs; bmc, depth 30)
        Next: volt explain E5001   (how to read a counterexample)

Now bmc finds the bug, at cycle 27. Fix the comparison, count_r == 24:

Replace this file: divider.volt

// Gives a one-cycle tick every 25 clock cycles.

pub module Divider {
    in  clk  : clock
    out tick : bool

    reg count_r : u5 = 0

    on clk {
        if count_r == 24 {
            count_r <= 0
        } else {
            count_r <= count_r + 1
        }
    }

    tick = count_r == 24

    invariant: count_r < 25
}

Type this:

volt verify --mode prove divider.volt

You should see:

   Verifying divider.volt
note: SymbiYosys not found locally; running it in Docker (hdlc/formal:all)
     [1/1] Divider (3 properties) ... ok (0.22s)
    Finished 1.26s
      Result 3 properties verified in 1.3s (16 jobs; prove, depth 20)

Proved: the invariant holds in every cycle, however long the design runs. When to use which mode:

  • bmc (the default) finds bugs that happen within --depth cycles of reset, and gives a counterexample. It is enough when the design reaches all of its states within that depth.
  • --mode prove shows that a property holds forever. Use it for counters, timers and anything else that takes many cycles to come back to where it started. When it says “not proven”, try a larger --depth, or add an invariant that rules out the states the solver started from.
  • --mode cover shows that the covers can be reached, so that a passing proof is not passing because nothing can happen.

You are in the formal folder.

Coming from SystemVerilog? Contracts become SVA

volt build --emit=sva writes the contracts as SystemVerilog assertions in build/formal/, in a checker module with a bind. An invariant becomes an assert property with @(posedge clk) disable iff (rst), a requires becomes an assume property while the module itself is verified, prev(x, N) becomes $past(x, N), and a -> b becomes a |-> b. volt verify writes the SymbiYosys script for you and maps a failure back to the line of the contract. There are no sequences (##) and no liveness properties; see Known limitations.

What we learned

  • invariant, requires, ensures and cover are written into the module; prev(x) reads the value of the previous cycle, a -> b reads “if a, then b”.
  • volt verify exits with code 6 and writes a counterexample waveform when a contract can be broken; read it cycle by cycle.
  • A requires is assumed while its module is verified and checked where the module is used.
  • --mode cover shows that the covers can happen, so a too strict requires does not go unnoticed.
  • bmc looks --depth cycles deep; --mode prove covers every cycle, and says “not proven” (code 7) when induction is not enough.

Next: the chapters after this one in the Tutorial are planned. The Cookbook has recipes that build on this chapter and the previous one, such as Reset synchronizers.

A UART transmitter

You will build a complete serial transmitter from the counter and the state machine of the earlier chapters. The chapter covers constants, bit timing, shifting data out, and a handshake with the rest of the design.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Tests

You will write simulation tests beyond the basics: loops, let bindings, loading memory from a hex file, and tests for designs with several clocks. You will also see how contracts run as monitors in every test.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Waveforms

You will record waveforms from tests and from volt run, open them in GTKWave with enum names, and find a bug by reading signals cycle by cycle.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

A multi-file project

You will split a design into several files, import modules and functions with use, and choose the top module in Volt.toml. The chapter ends with a small system on a chip.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

FIFOs

Buffer data between a producer and a consumer with the built-in SyncFifo, and between clock domains with AsyncFifo. The recipe covers depth, full and empty flags, and struct values in a FIFO.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

CDC patterns

Pick the right crossing for a single bit, a pulse, a multi-bit value and a data stream. Each pattern shows the Volt code, what the compiler checks, and the SystemVerilog it becomes.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Reset synchronizers

Take a raw asynchronous reset into a design with several clocks, and let the compiler generate one synchronizer per clock. The recipe explains the reset warnings W3009 and W3010.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This recipe makes a new folder there, resets. Type this:

    cd ~/volt-projects
    
  • Running: nothing else. This page uses volt check and volt build, which do not need Docker.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11. On macOS and Linux, paths are written with / instead of \. The recipe assumes you know clock domains from Two clocks and CDC.

The rule

A reset has two moments: when it starts (assert) and when it ends (release). Starting at any time is harmless: every register goes to its reset value. Ending is not. A register that sees the release too close to a clock edge can go metastable, and two registers of the same domain can leave reset in different cycles. So the release has to come in step with the clock of the registers it resets.

A reset button, a power-on reset chip or a pin of the board is in step with no clock of your design. Volt calls such an input a raw reset, and you declare it as a port with the type reset(...), for example in rst_n : reset(async, active_low).

For a raw reset port, the compiler builds a reset synchronizer for each clock the reset reaches: two flip-flops that start the reset at once and end it in step with that clock. Each domain is reset from its own synchronizer. Without a raw port, Volt adds a reset port by itself (rst or rst_n) and assumes that whoever drives it releases it in step with the clock; with several clocks it cannot be in step with all of them, and Volt says so.

New to hardware? Synchronous and asynchronous resets

A synchronous reset is an input like any other: a register reads it at the clock edge, so the reset acts at the next edge. An asynchronous reset acts at once, without waiting for an edge, which also works while a clock is stopped. Either way the release must be in step with the clock: for an asynchronous reset the flip-flop has timing rules for it (recovery and removal), and a synchronous reset is sampled like data, so a release close to the edge can be caught in either cycle.

Make a folder resets and go into it:

Type this:

mkdir resets

Type this:

cd resets

Two clocks and a reset button

The design below has a core clock and a slower clock for a serial port. Both domains use an asynchronous reset that is active low (0 means reset), as the reset button of many boards is. Create the file board.volt (as Setup shows):

Create this file: board.volt

// Two clocks reset by one push button.

domain Core {
    clock = posedge
    reset = async active_low
}

domain Uart {
    clock = posedge
    reset = async active_low
}

pub module Board {
    in  core_clk : clock @Core
    in  uart_clk : clock @Uart
    out beat     : bool  @Core
    out tick     : bool  @Uart

    reg beat_r : u4 = 0
    on core_clk {
        beat_r <= beat_r + 1
    }

    reg tick_r : u4 = 0
    on uart_clk {
        tick_r <= tick_r + 1
    }

    beat = beat_r == 15
    tick = tick_r == 15
}

The design has no reset port yet, so Volt adds one, rst_n, and both domains would use it. Check it:

Type this:

volt check board.volt

You should see:

    Checking board.volt
error[E3003]: asynchronous reset 'rst_n' is shared by 2 clock domains without synchronization
   ┌─ board.volt:14:9
   │
 5 │     reset = async active_low
   │     ------------------------ asynchronous reset → port 'rst_n'
   ·
10 │     reset = async active_low
   │     ------------------------ same port 'rst_n'
   ·
14 │     in  core_clk : clock @Core
   │         ^^^^^^^^ 'rst_n' can be released synchronously to at most one of 'core_clk', 'uart_clk'
15 │     in  uart_clk : clock @Uart
   │         -------- also reset by 'rst_n'
   │
   = reason: a reset release that is synchronous to one clock is asynchronous to the other; registers of the second domain can leave reset in different cycles or go metastable (recovery/removal violation)
   = help: declare the reset as a raw input port; the compiler then adds a reset synchronizer for each clock:
         in rst_n : reset(async, active_low)
   = for more: volt explain E3003


    Finished 0.02s
      Result 1 error(s), 0 warning(s)

An asynchronous reset shared by two clocks is error E3003: its release can be in step with one of them at most. The help line has the fix. Add the line in rst_n : reset(async, active_low) below the clock ports:

Replace this file: board.volt

// Two clocks reset by one push button.

domain Core {
    clock = posedge
    reset = async active_low
}

domain Uart {
    clock = posedge
    reset = async active_low
}

pub module Board {
    in  core_clk : clock @Core
    in  uart_clk : clock @Uart
    in  rst_n    : reset(async, active_low)
    out beat     : bool  @Core
    out tick     : bool  @Uart

    reg beat_r : u4 = 0
    on core_clk {
        beat_r <= beat_r + 1
    }

    reg tick_r : u4 = 0
    on uart_clk {
        tick_r <= tick_r + 1
    }

    beat = beat_r == 15
    tick = tick_r == 15
}

The kind of reset in parentheses, (async, active_low), must match the reset line of the domains it feeds; a mismatch is E3003 too. Check again:

Type this:

volt check board.volt

You should see:

    Checking board.volt
    Finished 0.01s
      Result 0 error(s), 0 warning(s)
       Next: volt build board.volt   (emit SystemVerilog)

The generated synchronizers

Type this:

volt build board.volt

You should see:

   Compiling board.volt
    Finished 0.01s (1 source file(s), 1 SV file(s))
     Output build\rtl\Board.sv (69 lines)
       Next: volt run board.volt      (simulate)
             volt verify board.volt   (prove contracts)

Open build/rtl/Board.sv (in the resets folder) in your editor. The port rst_n feeds two synchronizers, one per clock, and the registers of each domain are reset by the output of their own. This is a part of the file (output trimmed):

You should see:

    // reset synchronizer: rst_n -> core_clk (async assert, sync release)
    logic rst_sync_core_clk_stage0;
    logic rst_sync_core_clk_stage1;
    always_ff @(posedge core_clk or negedge rst_n) begin
        if (!rst_n) begin
            rst_sync_core_clk_stage0 <= 1'b0;
            rst_sync_core_clk_stage1 <= 1'b0;
        end else begin
            rst_sync_core_clk_stage0 <= 1'b1;
            rst_sync_core_clk_stage1 <= rst_sync_core_clk_stage0;
        end
    end

    // reset synchronizer: rst_n -> uart_clk (async assert, sync release)
    ...

    always_ff @(posedge core_clk or negedge rst_sync_core_clk_stage1) begin
        if (!rst_sync_core_clk_stage1) begin
            beat_r <= 4'd0;
        end else begin
            beat_r <= beat_r + 4'd1;
        end
    end

Read it like this. While rst_n is 0, both stages are 0 at once, without waiting for a clock edge: the reset starts immediately. After rst_n goes to 1, stage 0 becomes 1 at the next edge of core_clk, and stage 1 one edge later. beat_r is reset while stage 1 is 0, so it leaves reset on an edge of core_clk, two edges after the button was let go. The uart_clk side does the same with its own two stages.

Coming from SystemVerilog? The synchronizer you would write by hand

The chain above is the usual “asynchronous assert, synchronous release” reset synchronizer that a design team keeps in a library and instantiates once per clock. In Volt you do not instantiate it: a raw reset port is enough, and the compiler adds one chain for each clock the port reaches, names it after the clock (rst_sync_<clock>_stage1) and resets that domain’s registers from it. A clock you add later gets its chain without a code change. The chain has two stages; there is no setting for more yet.

One clock: W3009

A module with a single clock and an asynchronous reset, but no raw reset port, gets warning W3009. Create blinker.volt:

Create this file: blinker.volt

// One clock with an asynchronous reset.

domain Core {
    clock = posedge
    reset = async active_low
}

pub module Blinker {
    in  clk : clock @Core
    out led : bool  @Core

    reg count_r : u4 = 0
    on clk {
        count_r <= count_r + 1
    }

    led = count_r[3]
}

Type this:

volt check blinker.volt

You should see:

    Checking blinker.volt
warning[W3009]: asynchronous reset 'rst_n' is assumed to be released synchronously to 'clk'
  ┌─ blinker.volt:9:9
  │
5 │     reset = async active_low
  │     ------------------------ asynchronous reset → port 'rst_n'
  ·
9 │     in  clk : clock @Core
  │         ^^^ 'rst_n' must be released synchronously to this clock
  │
  = reason: 'Blinker' is not instantiated in this unit, so nothing in Volt synchronizes its reset release
  = help: if 'rst_n' comes from a pad or a power-on reset, declare it as raw and the compiler adds the synchronizer:
        in rst_n : reset(async, active_low)
  = for more: volt explain W3009


    Finished 0.01s
      Result 0 error(s), 1 warning(s)
       Next: volt build blinker.volt   (emit SystemVerilog)

The reset port rst_n that Volt adds here carries a promise: it is released in step with clk. Inside a Volt design the promise is kept, because a parent module connects its own synchronized reset to the child (see Submodules below). Blinker is not used by another module in this file, so nothing in Volt keeps it, and W3009 says so. What to do depends on where the reset comes from:

  • From a button, a pin or a power-on reset: add in rst_n : reset(async, active_low), as for Board. The warning goes away and the synchronizer is built.
  • From a design that already synchronizes it, for example when Blinker is handed to a team that puts it into their SystemVerilog design: keep the module as it is. The warning documents what their reset must do.

Two clocks with synchronous resets: W3010

reset = sync (the default) has the same problem in a milder form. A synchronous reset is sampled like data, and when two clocks share the reset port that Volt adds, its release is out of step with at least one of them: warning W3010. The chapter Two clocks and CDC shows the message.

The fix is the same one line, with the kind of reset of those domains: in rst : reset(sync, active_high). It is a warning and not an error because of submodules: a module that is used inside a parent with the same clocks cannot take a raw reset port of its own (the next section shows why), and its one automatic reset port can carry the synchronized reset of a single clock. There is no form of such a module without the warning yet. At the top of a design, add the raw port.

Submodules

A submodule does not synchronize its reset again. Its automatic reset port is connected to the parent’s synchronized reset for its clock. Create board_led.volt, where the core of Board blinks a LED through a submodule:

Create this file: board_led.volt

// A board whose core blinks a LED through a submodule.

domain Core {
    clock = posedge
    reset = async active_low
}

domain Uart {
    clock = posedge
    reset = async active_low
}

module Blinker {
    in  clk : clock @Core
    out led : bool  @Core

    reg count_r : u4 = 0
    on clk {
        count_r <= count_r + 1
    }

    led = count_r[3]
}

pub module Board {
    in  core_clk : clock @Core
    in  uart_clk : clock @Uart
    in  rst_n    : reset(async, active_low)
    out led      : bool  @Core
    out tick     : bool  @Uart

    let blink = Blinker { clk: core_clk }

    reg tick_r : u4 = 0
    on uart_clk {
        tick_r <= tick_r + 1
    }

    led  = blink.led
    tick = tick_r == 15
}

Type this:

volt build board_led.volt

You should see:

   Compiling board_led.volt
    Finished 0.02s (1 source file(s), 2 SV file(s))
     Output build\rtl\Blinker.sv (30 lines)
     Output build\rtl\Board.sv (67 lines)
       Next: volt run board_led.volt      (simulate)
             volt verify board_led.volt   (prove contracts)

Blinker gets no W3009 here, because Board uses it. In build/rtl/Board.sv, the instance is connected to the synchronizer of core_clk (output trimmed):

You should see:

    Blinker blink (
        .clk  (core_clk),
        .rst_n(rst_sync_core_clk_stage1),
        .led  (blink_led)
    );

Do not give Blinker a raw reset port and pass rst_n to it: when the parent synchronizes the same reset to the same clock, the two chains release independently, and volt check reports E3003 (“synchronized twice”).

More than one reset

A design can have one raw reset per domain, for example a separate reset for the serial port. Write the domain after the type:

  • in core_rst_n : reset(async, active_low) @Core
  • in uart_rst_n : reset(async, active_low) @Uart

Each port then feeds the clocks of its domain. When a module has more than one raw reset port, every one needs its @Domain; otherwise Volt cannot tell which clocks a port feeds, and reports E3010.

In simulation and formal verification

You do not drive a raw reset port in a test. volt test and volt run hold it active for two cycles, release it, and wait until the synchronizers have passed the release on, so a test starts with the design out of reset. volt verify assumes the design starts in reset and checks the contracts from the release on.

You are in the resets folder.

What Volt does not check

  • The order of resets. Volt checks that each release is in step with its clock. It does not check that one domain leaves reset before another, and it does not model a reset that depends on a condition. The domain keys reset_cycles and reset_sequence are reserved for this; writing one is E0003 (“not supported yet”).
  • The reset of an extern module. An extern instance connected to a raw reset port gets the raw reset, not the synchronized copy (warning W3011); see Known limitations.
  • The length of the chain. Each synchronizer has two stages.

Summary

Your designWhat Volt does
One clock, reset = sync (the default), no raw portadds rst, assumed in step with the clock; no warning
One clock, reset = async, no raw port, not used by another moduleadds rst_n, warning W3009
Several clocks, reset = sync, no raw portadds rst, warning W3010
Several clocks, reset = async, no raw porterror E3003
A raw port, in rst_n : reset(...)one synchronizer for each clock the port reaches
A submodulegets its parent’s synchronized reset
Several raw portseach needs @Domain, otherwise E3010

volt explain W3009, volt explain W3010 and volt explain E3003 print the reasons in more detail.

Register maps with @mmio, and C and Rust drivers

Describe memory-mapped registers once with @mmio and generate the AXI4-Lite slave, a C header, a Rust driver and a register map document from it. The recipe also shows how to check a hand-edited driver against the design.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Pipelines

Split a long combinational path into stages with a pipeline block, and let Delayed<T, N> catch values that arrive in different cycles. The recipe uses a FIR filter as the example.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Using Volt in an existing project

In this chapter you will take a SystemVerilog module you already have and use it from a Volt design with extern. You will check the design, test it together with the SystemVerilog module, and write it out as SystemVerilog that the rest of your project compiles like any other file.

Before you start

  • Window: a terminal (how to open one) and your editor.

  • Folder: your volt-projects folder. This chapter makes a new folder there, existing. Type this:

    cd ~/volt-projects
    
  • Running: Docker Desktop, with Engine running in its window, for volt test. If Verilator is installed, Docker is not needed; volt doctor says which one volt test uses.

The output on this page was recorded with Volt 0.1.0 in PowerShell on Windows 11, with Docker Desktop.

The module you already have

Make the folder existing, go into it, and make a folder rtl inside it for the SystemVerilog file:

Type this:

mkdir existing

Type this:

cd existing

Type this:

mkdir rtl

The SystemVerilog module below stands for a module of your project. It gives a pulse one clock cycle long each time its input goes from 0 to 1. Create it in the rtl folder (as Setup shows; in the clipboard command, write rtl/RisePulse.sv as the name):

Create this file: rtl/RisePulse.sv

// An existing SystemVerilog module: a one-cycle pulse on each rising
// edge of `level`.
module RisePulse (
    input  logic clk,
    input  logic level,
    output logic rise
);
    logic level_q;

    always_ff @(posedge clk) level_q <= level;

    assign rise = level & ~level_q;
endmodule

Declare it with extern

A Volt design uses a SystemVerilog module through an extern module declaration: the ports of the module, with their names, directions and types, and the file that holds its body. This design counts button presses with RisePulse. Create it in the existing folder:

Create this file: press_counter.volt

// Counts button presses. The rising-edge detector is an existing
// SystemVerilog module, RisePulse, in rtl/RisePulse.sv.

@source("rtl/RisePulse.sv")
extern module RisePulse {
    in  clk   : clock
    in  level : bool
    out rise  : bool
}

pub module PressCounter {
    in  clk    : clock
    in  button : bool
    out count  : u8

    let det = RisePulse { clk: clk, level: button }

    reg count_r : u8 = 0
    on clk {
        if det.rise {
            count_r <= count_r + 1
        }
    }

    count = count_r
}

@source names the SystemVerilog file, relative to the .volt file. let det = RisePulse { ... } places one instance of the module, and det.rise reads its output, as with a Volt module. Check the design:

Type this:

volt check press_counter.volt

You should see:

    Checking press_counter.volt
    Finished 0.05s
      Result 0 error(s), 0 warning(s)
       Next: volt build press_counter.volt   (emit SystemVerilog)

Volt does not read the SystemVerilog file: it checks that the file is there, and it trusts the extern declaration for the ports. If the two disagree, for example a port that the SystemVerilog module does not have, volt check still passes; the mistake shows up as a Verilator error when volt test compiles the two files together.

Test the two together

A test file for this design looks like the one of Tests and waveforms. Create it:

Create this file: press_counter_test.volt

// Simulation tests for PressCounter. The design and the SystemVerilog
// body of RisePulse are simulated together.

test "a held button counts once" {
    let dut = PressCounter { };
    dut.button = true;
    step(5);
    assert_eq(dut.count, 1);
}

test "two presses count twice" {
    let dut = PressCounter { };
    dut.button = true;
    step(2);
    dut.button = false;
    step(2);
    dut.button = true;
    step(2);
    assert_eq(dut.count, 2);
}

Type this:

volt test press_counter_test.volt

You should see:

   Compiling press_counter_test.volt
running 2 tests
note: Verilator not found locally; running it in Docker (verilator/verilator:v5.054)
test a_held_button_counts_once ... ok
test two_presses_count_twice ... ok

test result: ok. 2 passed; 0 failed

volt test hands rtl/RisePulse.sv to Verilator together with the SystemVerilog it generates, so the test runs the real body of RisePulse. Change the line assign rise = level & ~level_q; in rtl/RisePulse.sv to assign rise = level; and both tests fail; change it back before you go on.

Write SystemVerilog for your project

Type this:

volt build press_counter.volt

You should see:

   Compiling press_counter.volt
    Finished 0.01s (1 source file(s), 1 SV file(s))
     Output build\rtl\PressCounter.sv (41 lines)
       Next: volt run press_counter.volt      (simulate)
             volt verify press_counter.volt   (prove contracts)

Open build/rtl/PressCounter.sv in your editor. This is a part of it (output trimmed):

You should see:

module PressCounter (
    input  logic       clk,
    input  logic       rst,
    input  logic       button,
    output logic [7:0] count
);

    logic det_rise;

    RisePulse det (
        .clk  (clk),
        .level(button),
        .rise (det_rise)
    );
    ...

The module and its ports keep the names of press_counter.volt. Volt adds a reset port, rst, which sets count_r back to 0. RisePulse is placed with its ports connected by name, and gets no reset port: an extern module has exactly the ports it declares.

volt build writes PressCounter.sv and nothing else; it does not copy rtl/RisePulse.sv. The rest of your project compiles both files, as it compiles its own.

Coming from SystemVerilog? Placing the generated module

PressCounter u_counter (
    .clk   (clk),
    .rst   (rst),
    .button(button),
    .count (count)
);

The generated file is plain SystemVerilog with no Volt package or include. We placed PressCounter like this in a hand-written testbench and compiled it with Verilator 5.054 from build/rtl/PressCounter.sv and rtl/RisePulse.sv alone: verilator --lint-only -Wall reported nothing, and the testbench counted two presses. If you stop using Volt, the generated files are what you keep; the header says they were generated, and the names in them are the names of your Volt source.

What extern does not do

  • Volt does not read the SystemVerilog file. The ports of the extern declaration are trusted; a mismatch is reported by Verilator during volt test, not by volt check.
  • No parameters. Volt rejects a generic extern module. A parameterized SystemVerilog module is used with its default parameter values. For other values, write a small SystemVerilog wrapper module that sets them, declare the wrapper as the extern, and list both files in @source("rtl/wrapper.sv", "rtl/module.sv").
  • No reset port is added. If the SystemVerilog module has a reset, declare it as a port of the extern and connect it yourself. The module gets the reset you connect; when Volt puts a reset synchronizer in front of its own registers, the extern does not get the synchronized copy (issue #93).
  • volt build does not copy the SystemVerilog file into build/.
  • Clock domains stop at the ports. The ports of an extern can carry clock domains, and Volt checks what you connect to them, but it cannot see a crossing inside the SystemVerilog module.
  • No standard library names. An extern cannot be named like a module of the standard library (EdgeDetect, SyncFifo, Counter, …; volt explain stdlib lists them): volt check reports E1016. The name of an extern is the name of its SystemVerilog module, so a SystemVerilog module called Counter goes behind a small SystemVerilog wrapper module with another name, and the extern declares the wrapper.

You are in the existing folder.

The ports of an extern take clock domains like the ports of a Volt module: Two clocks and CDC shows how to declare domains and write @Domain after a port type.

Wrapping SystemVerilog with extern

Use an existing SystemVerilog module from Volt: declare it with extern, give its ports clock domains, and ship its source with @source so that volt test can simulate it.

This chapter is planned. It will be written after feedback on the Tour and the counter chapter. Until then, these show the same topic:

Glossary

Short definitions of the hardware and Volt terms used in this book. The list grows with the book; the specification’s terms are in docs/spec/GLOSSARY.md.

Clock. A signal that switches between 0 and 1 at a steady rate. Registers change their value at its rising edge.

Clock domain. A clock together with the registers it drives and the signals computed from them. In Volt a domain also fixes the clock edge and the reset style, and every signal belongs to one domain.

CDC (clock domain crossing). A signal from one clock domain read in another. Without a synchronizer it can cause metastability; Volt reports it as E3001.

Combinational logic. Logic whose output depends on its current inputs and nothing else: gates and wires, no storage. In Volt, assignments with = outside an on block, let, and fn calls.

Contract. A rule about a design written in the design: invariant, requires, ensures, cover. volt verify proves it; volt test checks it on every simulated cycle.

Cover. A contract that asks “can this happen?”. Simulation counts how often it was reached; formal verification searches for a way to reach it.

Enum. A type with a fixed set of named values, such as the states of a state machine. Volt encodes the names as numbers in the generated SystemVerilog and shows the names in waveforms.

Flip-flop. A storage element for one bit that takes a new value at a clock edge.

Formal verification. Proving a property for every possible input sequence with a solver, instead of trying some sequences in simulation. Volt uses SymbiYosys.

Metastability. The unstable state of a flip-flop whose input changed right at the clock edge. It settles to 0 or 1 after an unpredictable time.

Module. A circuit with ports. Modules can contain other modules.

Port. A named input (in) or output (out) of a module, with a type.

Register. A group of flip-flops holding a value, declared with reg and updated in an on block.

Reset. An input that puts registers back to a known value. A synchronous reset acts at a clock edge; an asynchronous one acts at once.

Simulation. Computing a design’s signals cycle by cycle for given inputs. Volt uses Verilator.

Synchronizer. Two or more flip-flops in a row on the receiving clock, which give a crossing signal time to settle. In Volt: sync().

SystemVerilog. The hardware description language that Volt generates and that FPGA and ASIC tools read.

Testbench. Code that drives a design’s inputs and checks its outputs in simulation. Volt generates it from test blocks.

Waveform. A recording of signals over time, usually a .vcd file, viewed with a tool such as GTKWave.

Width. The number of bits of a value: u8 has 8, bool has 1.

Where to go next

Where to look when the book does not answer your question: the explanations built into the compiler, the command reference, the design decisions behind the language, and the example designs.

Explanations built into volt

Every error and warning code has a long explanation:

Type this:

volt explain E3001
volt explain --list          # every code
volt explain E3001 --lang=tr # in Turkish

Topics cover larger subjects: getting-started, domains, contracts, stdlib, verify-setup, simulation-setup, waveforms (volt explain --topics lists them).

Commands

volt --help lists the commands, and volt <command> --help their options. The full contract of every command, its exit codes and its output format is in docs/spec/cli-contract.md.

Design decisions

Each language feature was decided in an architecture decision record (ADR). The index, with a “Buradan başla” (start here) reading list, is docs/adr/README.md. The ADRs are written in Turkish; the language specification in docs/spec/ is in English.

What is missing and what is planned

Known limitations lists what Volt does not do yet, with workarounds. The roadmap lists the planned work and the design decision behind each item.

Examples and reference

  • examples/README.md: a UART, I²C, a VGA controller, a RISC-V core that runs C, and more, with their test and verification results.
  • docs/stdlib.md: the built-in components (FIFOs, RAMs, synchronizers, arbiters).
  • volt new --list: project templates.

Known limitations

What Volt 0.1 does not do yet, so you can decide early whether it fits your design. Each limit says what happens when you hit it, how to work around it where a way exists, and where the work is planned in the roadmap.

Stability

No stability promise. Volt 0.1 is an early release. Syntax, diagnostic codes and the shape of the generated SystemVerilog may change in any later release, without a deprecation period. Pin the Volt version you use (the install script takes VOLT_VERSION) and read the changelog before upgrading. Roadmap: A stability policy.

Volt is used by its maintainer, nobody else yet. There are no FPGA board or tape-out results; the examples run in simulation and formal verification.

Known bugs

These are bugs, not design limits: each one has an issue and is planned for a fix. Until then, the workaround after each one avoids it. The division bug (#150) and the cut operand of +, - and * (#266) are under Language below.

volt build follows links out of the project. When build/, or a file in it, is a symbolic link, volt build writes through the link. A cloned repository can carry such a link, so building it can overwrite a file anywhere you can write; on Windows a directory junction in place of build/ does the same. Do not build a repository you do not trust; before building one, check that build/ and the files in it are not links. Tracked in issue #221.

A struct let whose flattened field name equals another name. A struct let in a block becomes one signal per field in the generated SystemVerilog: let p : S with a field x becomes p_x. If a port or signal is also called p_x, a read of it in that block reads the field of the local, without a warning. Do not name a port or signal <let>_<field>; rename the let. Tracked in issue #154.

A module-level let with the name of a bundle port or of regs is accepted without error E1003, and the name then means two different things: the port in one place, the let in another. Give the let a name of its own. Tracked in issue #155.

An import alias reaches the generated SystemVerilog. With use other::X as J, a constant used as a value (y = J) is written into the SystemVerilog as assign y = J;, a name that does not exist there, without a diagnostic; an aliased type, function, domain or module is rejected. Import such items without as. Tracked in issue #161.

A test block can read a private constant of another file, without error E1001. Make the constant pub and import it with use in the test file, as the visibility rules require. Tracked in issue #162.

Constant evaluation stops at depth 64 in for bounds and bundle arrays. A module-level for bound or a bundle array length that is a constant expression deeper than 64 levels, or the end of a chain of 64 constants, is rejected with E2021; a cycle there is E2021 instead of E2020; and a counter whose limit is such a chain gets no inferred contract. Keep constant chains and expressions shallower than 64 levels. Tracked in issue #159.

A generic module that is never instantiated and uses its parameter in a type (in x : uint<N>) is rejected with E2021 (“this is a generic parameter (runtime value)”), also in a file loaded with use. Instantiate the module once, for example Fir<8> { ... }. Tracked in issue #172.

A match is computed at a narrower width than the type checker uses. With u8 operands, let m = match sel { 0 => a + b, _ => a - b } is an 8-bit signal in the generated SystemVerilog, so 200 + 100 gives 44; match a + b with an arm 44 => also takes the value 300; and a contract with prev(a + b) or a signed prev() compares at the wrong width. Write the choice as if/else, or put the subject in a let with an explicit width (let s : u9 = a + b, then match s). Tracked in issue #215.

In a statement match, an arm after the wildcard wins. In a comb block, match s { 0 => { … } _ => { y = 7 } 1 => { y = 9 } } gives 9 for s = 1, while the same match written as an expression gives 7. Write the wildcard arm last. Tracked in issue #216.

A const that does not fit its type is accepted. With const A : u8 = 255 and const B : u8 = A + 1, compile time sees 256 (a bits<B> port is 256 bits wide) and the hardware sees 0. Make sure every constant computed from other constants fits its declared type. Tracked in issue #214.

The clock outputs of an extern module have no clock domain. With a PLL or a clock buffer declared as an extern module with out c0 : clock, nothing clocked by c0 is checked: a crossing between the input clock and an output clock gets no E3001. Synchronize every value between these clocks yourself with sync() or an AsyncFifo. Tracked in issue #208.

A register’s reset value can be a signal, and it is not checked. reg r : u8 = a loads a at reset without the clock-domain check (E3001) and the trust check (E3009). Use a constant reset value and load the signal in the on block. Tracked in issue #209.

A clock port declared through a type alias is not a clock everywhere. With type Clk = clock, an asynchronous reset shared by two clock domains gets no E3003, the SDC file has no create_clock for the clock, and a test block can drive it. Write clock for clock ports. Tracked in issue #234.

E5010 is missed in a comb block. In an @strict_timing module, choosing between values of different delays inside a comb block (comb { if x[0] { w = a } else { w = b } }) compiles, while the same choice written as let w = if x[0] { a } else { b } gets E5010. Write such a choice as a let. Tracked in issue #217.

A timing constraint can apply to a second register. @multicycle, @false_path and @timing(max_delay) on a register slow are written to the SDC file as get_cells {slow_reg*}, which also matches a register named slow_reg. Do not name a register <name>_reg… next to a constrained register <name>. Tracked in issue #219.

A secret passes through an unclassified input port of a submodule. With module Mid { in x : u8 out o : u8 @Pub o = x }, binding a @Sec value to x carries it to a public output without E3009. Annotate the input ports of submodules with their trust domain. Tracked in issue #210.

The trust annotation of a wire or a let is not read. In a module without a clock, wire w : u8 @Pub driven by a @Sec value gets no E3009; in a module whose clock is @Pub, wire w : u8 @Sec gets a false E3009. Annotate the ports instead. Tracked in issue #211.

An @mmio module next to a declared AXI bundle name does not compile. When the file declares AxiWriteAddr or another of the five AXI bundle names itself, the generated module reports E1001 for names such as aw_valid that you did not write. Do not declare these names next to an @mmio module. Tracked in issue #244.

A bits<K> value cannot cross a pipeline stage. It is rejected with E2003 on a literal that the compiler generates. Carry the value as uK across the stage and cast it back to bits<K> where it is used. Tracked in issue #245.

frequency = 100mhz gets errors that do not say what is wrong. The domain key gets W0020 “unknown domain key: ‘mhz’” followed by E0001. Write 100.mhz. Tracked in issue #223.

An incomplete assignment in a comb block infers a latch. comb { if c { y = 1 } else { if d { y = 2 } } } compiles, and the generated always_comb keeps the old y when c and d are both false (Verilator reports LATCH). A wire that is read and never driven compiles too (Verilator reports UNDRIVEN). Assign every output of a comb block on every path, for example with a default assignment at the top of the block (y = 0), and drive every wire. Tracked in issue #230.

A port bound twice in one instance takes the last binding. Child { x: 1, x: a } compiles without a diagnostic and connects x to a. Bind each port once. Tracked in issue #229.

delay<K> adds no register. delay<K>(x) tells the timing check that x is K cycles older than its inferred delay. It adds no hardware, and Volt does not check the claim: let sum = delay<1>(a) + b compiles, but a and b are still of different ages. To align two values, add a stage register, as the help of E5010 shows: a reg a_d2 : Delayed<u32, 2> = 0 loaded with a_d2 <= a in the on block, and let sum = a_d2 + b. Making delay<K> a marked escape is tracked in issue #358.

@false_path and @multicycle are not checked. They are written to the SDC file for any two registers, also for a real one-cycle path, and the timing tool then leaves that path untimed. volt explain E6003 and E6004 say that Volt proves these attributes; it does not, and the two codes are never reported. Treat both attributes as your own claim. On a port whose type is a struct or a struct port, neither attribute constrains anything: @false_path in cfg : Cfg writes get_ports cfg, which matches none of the generated ports (cfg_a, cfg_b), or no line at all for a struct port. Declare such inputs as plain ports. Tracked in issue #226, issue #231 and issue #229.

Reading an input port of an instance writes an undeclared name. With let s = Sub { x: a }, p = s.x compiles and is written as assign p = s_x;, which Verilator rejects. Read the value you bound (p = a). Tracked in issue #218.

An array literal assigned to an array wire fails in Verilator. xs = [x0, x1] with wire xs : [u8; 2] is written as assign xs = '{x0, x1};. Assign the elements one by one: comb { xs[0] = x0 xs[1] = x1 }. Tracked in issue #135.

A constant index of a wider type than the address stops volt test. With const K : u4 = 2, a[K] on a u8 is written as a[4'd2], and Verilator stops with WIDTHTRUNC. Give the constant the width of the address (const K : u3 = 2 for an 8-bit value). Tracked in issue #134.

Two @mmio modules in one design do not compile, and some @mmio arguments are not checked. The second @mmio module gets E1001 for the AXI bundle names, also in another file. A base address that is not a multiple of 4 is accepted, a repeated argument takes the last value, and a /// comment is copied into the generated C header as it is, so a */ in it ends the C comment. Use one @mmio module per design, a base address that is a multiple of 4, each argument once, and no */ in the comments of an @mmio module. Tracked in issue #220.

A struct port whose field has a private struct type of its own file is rejected with E1001 where the port is used. Make the field’s struct pub and import it too. Tracked in issue #163.

declassify() in a module-level for or a generic module gets a false E3009. Write the assignments without the for, one per element, and keep declassify() out of generic modules. Tracked in issue #212.

A submodule output that depends on public inputs alone is taken as secret when another input of the same instance is secret, and gets a false E3009. Put the public part in a submodule of its own, whose inputs are all public. Tracked in issue #195.

A source file that begins with a byte order mark is rejected (E0001: unexpected character: "\u{feff}"). Some Windows editors write this mark when they save as “UTF-8 with BOM”; save the file as UTF-8 without it. Tracked in issue #229.

A malformed Volt.toml is ignored. When Volt.toml is not valid TOML, volt build compiles and exits with 0, without a diagnostic. If a setting seems to have no effect, check the syntax of the file. Tracked in issue #222.

Some explanations in volt explain are wrong. The solution of E3012 and E3011 (r <= sync(fast_data, slow_clk) in an on block) gets E0003: write let s = sync(x, clk) at module level, as the compiler’s own help says. W0010 says that == binds before &; Volt reads a & b == c as (a & b) == c. E3004, E3005, E6001, E6003, E6004, E7001, E7002, E9001, E9002, W2011, W2020 and W2021 are explained as checks, but the compiler never reports them. Where an explanation and the compiler disagree, follow the compiler. Tracked in issue #225 and issue #226.

The project that volt new creates names its module Counter, a name of the standard library, so instantiating it from another module gets E1016. Rename the module (and top in Volt.toml) before you use it in a larger design. Tracked in issue #101.

Language

Some constructs pass the type checker but have no SystemVerilog mapping yet. They are rejected with E0003 (“not supported yet”), and volt explain E0003 describes the error. Today this covers:

  • integer types wider than 64 bits written as u128 or i100. Use bits<N>, which has no width limit;
  • arrays of structs, arrays of enums, generic structs, enums whose variants carry data, and generic enums;
  • generic functions, contracts on a function, and for inside a function body;
  • match arm guards (0 if c =>) and matching a whole struct value. Range, binding and struct patterns do not exist;
  • todo!(). It is parsed, but volt check and volt build reject it. Roadmap: todo!() placeholders.

The README’s Limitations section has the details and the measurements behind some of these decisions.

SystemVerilog is the sole output language. There is no VHDL output.

Integer literals stop at 2¹²⁸ - 1. A literal holds a value up to 2¹²⁸ - 1 in any base. A larger one, such as 0x1_0000_0000_0000_0000_0000_0000_0000_0000, is E0005 (“value does not fit in 128 bits”), also when the target is bits<256>. Nothing is cut silently: a literal up to 2¹²⁸ - 1 cast to bits<256> keeps its value and the upper bits are zero. To build a wider constant, write it in 128-bit parts and join them with a struct cast. hi, declared before lo, holds the upper 128 bits:

struct Key256 {
    hi : bits<128>,
    lo : bits<128>,
}

module Key {
    out key : bits<256>
    let k : Key256 = Key256 {
        hi: 0x0123_4567_89AB_CDEF_0011_2233_4455_6677 as bits<128>,
        lo: 0x8899_AABB_CCDD_EEFF_FEDC_BA98_7654_3210 as bits<128>,
    }
    key = k as bits<256>
}

key[255:192] is 0x0123_4567_89AB_CDEF and key[63:0] is 0xFEDC_BA98_7654_3210.

The width of a division with a wider arithmetic operand will change. / and % do not widen: a * b / c (all u8) divides at 8 bits, and the product, up to 16 bits wide, is cut to 8 bits before the division. The generated SystemVerilog does not always do the same, and the rule changes in v0.2.0. Until then Volt warns (W2015) wherever an operand is cut. Write the width you mean on both operands, as in (a * b) as u16 / (c as u16): the warning goes away and the value does not depend on the rule. Tracked in issue #150.

The width of a sum, difference or product with a wider arithmetic operand will change. +, - and * are done at the width both operands share, plus their own carry: a * b - a (all i32) is computed at 33 bits, and the product, up to 64 bits wide, is cut to 33 bits before the subtraction. With a = b = 2²⁰ the result is -2²⁰ instead of 2⁴⁰ - 2²⁰. The rule changes in v0.2.0. Until then Volt warns (W2016) wherever the cut can change the value you read; a result assigned to a declared width keeps that many bits anyway and gets no warning. Put the intermediate result in a let with an explicit width, as in let d : i64 = a * b - a: the warning goes away and the value does not depend on the rule. A product of two i64 or u64 values has no wider integer type yet, so before v0.2.0 there is no way around the cut. Tracked in issue #266.

Combinational loops are not detected. volt check and volt build accept wires that feed each other (a = b + x and b = a), a comb block that reads the signal it assigns, and a loop through an output port or a submodule instance. volt build writes the looping SystemVerilog without a warning. When volt test or volt run builds such a design, Verilator stops with %Warning-UNOPTFLAT ... Circular combinational logic followed by an example path around the loop, and the command fails: that message is the loop in your design, not a Verilator problem. Break it by removing one dependency on the path, or by registering one of its signals in an on block. A register cannot close a loop this way: assigning it with = outside an on block is E0019. Roadmap: Combinational loop check.

The handshake check does not look inside an extern module with a clock. On a Handshake<T> output, valid must not be computed from the same port’s ready without a register in between: if each side waits for the other, no transfer ever finishes. Volt reports this as E4007 when the path runs through assignments, lets, comb blocks, if and match conditions, function calls, submodules, extern modules without a clock and the built-in modules whose outputs follow their inputs in the same cycle (EdgeDetect, RoundRobinArbiter, PriorityArbiter). An extern module with a clock is not looked into: when ready goes into such a module and valid comes out of it through a path inside it, the design compiles without an error. Volt cannot tell that path from a registered one, such as the empty flag of a FIFO, which is the common and safe case. Register the value that comes back from the module, or compute valid in the module that owns the port. Tracked in issue #196.

Clock and reset domains

CDC bridges are sync(), sync3() and the built-in dual-clock components (AsyncFifo, HandshakeSync, PulseSync, AsyncDualPortRam). A synchronizer you write yourself is not recognized as a bridge: the crossing into it is an E3001 error. Wrap a hand-written or vendor synchronizer as an extern module with a clock domain on each port. A multi-bit sync() is a warning (W3003), not an error; use AsyncFifo or HandshakeSync for data.

A submodule’s dependencies are tracked per port, not per bit. For each output port of a module, Volt records which input ports it depends on without a register in between. An output whose bit 0 follows a and whose bit 1 follows b counts as depending on both. Through a module without a clock, a from one clock domain and b from another then make that output an E3001 error, although each bit stays in its own domain; through a submodule on a handshake path, the same output can give an E4007 that the bits do not deserve. Split such an output into two ports. An extern module without a clock is assumed to connect each output to every input, because its body is not visible: give its ports clock domain annotations when its paths belong to different domains.

A handshake path through an extern module without a clock is assumed. Volt cannot see inside such a module, so it assumes that each output depends on every input. When ready goes into it and valid comes out of it, E4007 is reported even if the real module has no path from that input to that output; the error’s note says that the path rests on this assumption. @no_protocol_check does not change this: it turns off the automatic protocol contracts of the port, not the check. Decide valid from a register, as E4007’s help shows (reg valid_r ...; on clk { ... }; tx.valid = valid_r): that cuts the path whatever the module does. A way to declare which outputs of an extern module depend on which inputs is planned for v0.2.0.

Reset checks cover reset release, not reset ordering. Volt reports an asynchronous reset shared by several clock domains or synchronized twice (E3003), but it does not check the order in which resets are released, and conditional resets are not modelled. extern modules carry no reset contract. The domain keys reset_cycles and reset_sequence are reserved for this: writing one is E0003 (“not supported yet”). Keep the reset length and order in your reset generator.

An extern gets the raw reset, not the synchronized one. For a raw reset port (in rst : reset(...)) Volt puts a release synchronizer in front of the module’s own registers. An extern instance connected to the same port gets the port itself, so its flip-flops leave reset on a different cycle than the registers beside it, and their release is not aligned to the clock unless the SystemVerilog module synchronizes it. Volt warns about this (W3011) and changes nothing in the output; there is no way yet to hand the synchronized copy to an extern. Tracked in issue #93.

No crossing report. Volt knows every crossing, but it does not list them in a report. With volt build --emit=sdc (or xdc), the constraint file has a comment line for each crossing with its kind and its source and destination clocks. Roadmap: CDC crossing report.

No power domains. The @Domain annotation covers clock, reset and trust level; power domains, isolation checks and UPF output do not exist. The power keys of a domain (voltage, always_on, retention, isolation) are reserved words: volt check rejects them with E0003, so a design cannot declare a power domain at all. The power-domain codes E3006, E3007 and E3008 are defined and volt explain describes the planned checks, but the compiler never reports them: nothing checks isolation, power-up order or retention. Roadmap: Power domains and UPF.

Simulation and tests

No built-in simulator. volt test and volt run need Verilator. When Verilator is not installed and Docker is running, Volt runs it in a pinned container image by itself; volt doctor shows which way each command will run.

Verilator runs with its DFG optimizer turned off. volt test and volt run pass -fno-dfg to every Verilator build, locally and in Docker. With that optimizer on, Verilator 5.052 and 5.054 print wrong values for some correct SystemVerilog (#148, reported upstream as verilator#9060). On the example designs the option changed the time of volt test by less than the difference between two runs. If you run Verilator on the generated SystemVerilog yourself, add -fno-dfg too.

Use Verilator 5.054 for volt test. The project tests every simulation result with Verilator 5.054, and the Docker image of volt test holds that release. Verilator 5.050, 5.051 and 5.052 give 0 instead of -1 for a negative signed value shifted right by an amount that is a constant for Verilator and at least the width of a C++ word (32 or 64 bits, or the width rounded up to 32 bits). Volt writes a constant amount in a form those releases compute correctly, but it cannot do that when the amount is a port that a module instance ties to a constant, as G { a: a, k: 64 } with y = a >> k in G (#309). If volt doctor shows a local Verilator 5.050 to 5.052, update it, or set VOLT_TOOL_BACKEND=docker.

A signed shift of a wide sum can simulate wrong in Verilator 5.054. Four conditions together: the value is signed and wider than 64 bits, its width is one more than a multiple of 32 (65, 97, 129 bits), it is computed by an expression such as (e + f) rather than read from a port or signal, and it is shifted right by a port that a module instance ties to a constant at least the width rounded up to 32 bits (96 for 65 bits). For a negative value Verilator 5.054 then gives ...0001 instead of all ones; synthesis, Yosys and volt verify give all ones. Reported upstream as verilator#9256, tracked in issue #311. Workaround: make the amount a const or a generic parameter of the module that shifts (G<130> { ... } with y = (e + f) >> N): Volt then writes the shift in a form that Verilator computes correctly.

Every clock runs at the same rate in simulation. volt test and volt run give each clock port of the design one rising edge per cycle, all at the same moment. A design with several clocks cannot be simulated with clocks of different speeds or with a phase shift between them, so a test checks the order and the latency of a crossing, not its timing. The crossing itself is checked by the compiler (E3001). An example is in Two clocks and CDC.

Test values are at most 64 bits wide. The test language cannot write to a port wider than 64 bits or compare a wider value. A module with an input wider than 64 bits cannot be tested directly: volt test stops with a C++ error from the Verilator build (VlWide), also when the test does not use that input (issue #224). Workaround: test the design through a small wrapper module whose ports are 64 bits or narrower, for example Wide { key: lo as uint<128> as bits<128> } with in lo : u64. volt run does drive and print wide ports. Roadmap: Port values wider than 64 bits in tests.

The test language has no if or match expressions, and it cannot call a design’s functions (E8505).

No machine-readable test results. volt test and volt run write their report for people; they have no --format=json option yet, unlike volt check, volt build and volt verify. In CI, use the exit code (volt test exits with 5 when a test fails) and keep the text report as a log. Roadmap: Machine-readable test results.

Generated drivers are not simulated. The C and Rust drivers generated from an @mmio register map are not run against the RTL. volt check-regmap checks that a driver matches the register map. Roadmap: Generated drivers in simulation.

Formal verification

volt verify needs SymbiYosys, Yosys and an SMT solver. They run on Linux; on Windows use WSL, or let Volt run them in Docker.

Properties look back with prev(), nothing more. There are no sequences (##) and no liveness properties; the proof is bounded (--depth).

No modular proofs. Each module is verified with the logic of its submodules included; a verified submodule is not replaced by its contracts. A submodule’s requires and assume are checked as obligations of the module that instantiates it. Large hierarchies take longer to prove. Roadmap: Assume-guarantee verification.

Contracts need a clock port. Properties are checked on a clock edge, so volt verify stops with E5005 on a contract in a module without a clock port. Give the module a clock port, or state the property in the clocked module that instantiates it.

Array literals in contracts are not supported yet. A contract that compares with an array literal (r == [prev(a), prev(b)]) is passed to the tools as an assignment pattern, and most tools reject it: volt verify stops with a Yosys syntax error (unexpected OP_CAST) for every form; volt test and a separate .sva file fail in Verilator when the literal is compared with another literal or with an array port, and a separate .sva file comparing an array register with a literal that uses prev() makes Verilator report an internal fault. volt test does compile the comparison of an array register with a literal. Volt does not report the failing forms itself yet. Workaround: compare element by element (r[0] == prev(a) && r[1] == prev(b)). Roadmap: Array literals in contracts.

Contradictory assumptions are not detected. If the requires and assume contracts of the module under proof cannot hold together, every assertion passes without proving anything; the solver can also hold reset for the whole run. Check that a cover of the behaviour you care about is reached with --mode cover. Roadmap: Vacuity check.

A submodule’s reset assumption stays an assumption in its parent’s proof. Each module with a reset assumes that reset is asserted when the proof starts, also when it is an instance in a parent’s proof. When the parent drives the submodule’s reset from its own logic or from another reset domain, this assumption constrains the parent: it can hide a failure, or contradict the parent’s reset so that every assertion passes without proving anything. Designs whose submodules use the parent’s reset are not affected. Roadmap: Submodule reset assumptions.

Information flow is checked by types, not proved formally. E3009 catches secret data that reaches a public output at compile time; no formal property is generated for it.

Generated output

Most of the generated SystemVerilog carries no Volt line numbers. Each file names its source file, and contract assertions and expanded function calls carry file:line comments. Other statements do not, and no command maps a SystemVerilog line back to Volt. Signal names follow the Volt names, so searching for the name is the workaround. Roadmap: Source mapping.

No parameterized SystemVerilog modules. A generic module becomes SystemVerilog when it is instantiated: Fir<8> { ... } generates the module Fir_8, with the parameter replaced by its value. A generic module that nothing in the file instantiates generates no SystemVerilog file, and Volt warns about it (W1006). Writing it as a parameterized module (module Fir #(parameter N)) is a proposal for v0.2.0, tracked in issue #171.

Register maps use AXI4-Lite with 32-bit registers, and reset values are 0. Register documentation is Markdown (--emit=regmap-md); there is no SVD, IP-XACT or UVM output.

Constraints, not projects. --emit=sdc,xdc writes timing constraints. There are no Vivado or Quartus project files and no pin constraints. Roadmap: FPGA project files.

No diagrams and no project documentation. Volt does not draw state machines or generate documentation for a whole project. Roadmap: FSM state diagrams, Project documentation.

Editor

Some language server features see one file. Diagnostics, inlay hints and quick fixes analyze every file a design loads with use. Hover, completion, go to definition and the symbol outline look at the open file: go to definition does not jump into another file. Roadmap: Multi-file language server features.

The VS Code extension is a .vsix file from the release page. It is not on the Visual Studio Marketplace or Open VSX, it needs volt on PATH (or the volt.serverPath setting), and it has no “Run test” action. Roadmap: VS Code extension.

Projects and installation

No package dependencies. use loads files inside the project. Volt.toml has no dependency section and there is no lock file; copy shared files into the project. Roadmap: Package dependencies.

No package managers. Install Volt with the install script or from source, as Install Volt shows; winget, Scoop and Homebrew packages do not exist. Roadmap: Package managers.

No browser playground. Volt runs on your machine. Roadmap: Browser playground.

The design decisions are in Turkish. The book, the language specification and the diagnostics are in English (diagnostics also in Turkish, --lang=tr); the ADRs are not translated. Roadmap: English summary of the design decisions.

Install Volt

In this chapter you will install the volt binary with one command, check it with volt --version and ask volt doctor what works on your machine. You will also set up Docker, which runs the simulator for you.

Before you start

  • Window: a terminal: PowerShell on Windows, Terminal on macOS and Linux (how to open one).
  • Folder: any; installing does not depend on the working folder.
  • Running: an internet connection.

Setup already installs Volt with the one-line command and checks it. This page has the details: what the script changes, how to update or remove Volt, how to install it by hand or build it from source, and more about Docker.

The output on this page was recorded with Volt 0.1.2 on Windows 11. On Linux and macOS the paths use / instead of \; everything else looks the same.

Install with one command

No administrator rights are needed.

Type this (Windows, PowerShell):

irm https://volt-hdl.github.io/volt/install.ps1 | iex

Type this (macOS and Linux, any shell):

curl -fsSL https://volt-hdl.github.io/volt/install.sh | sh

No curl? wget -qO- https://volt-hdl.github.io/volt/install.sh | sh does the same.

The script prints each step: the download, the SHA256 check, where it put volt and what it changed on your PATH. On Windows, the PowerShell window that ran the command can use volt at once. Other terminals, and every terminal on Linux and macOS, see it after you open a new one. A terminal program that is already running, such as Windows Terminal or VS Code, hands its old PATH to every new tab: close it completely and start it again.

PlatformSupported by the script
Windows x86_64 (10 and 11)yes
Windows 11 on Armyes, with the x86_64 build (runs through the x64 emulation of Windows 11; there is no native Arm build yet)
Linux x86_64, any distributionyes (static binary)
macOS, Apple siliconyes
macOS, Intelyes
Linux on Arm, other systemsno: the script says so; build from source

Check the install

In a new terminal:

Type this:

volt --version

You should see:

volt 0.1.2 (33354c5)

The part in parentheses names the commit the binary was built from, so yours shows other letters and digits.

If you see command not found (or, on Windows, “The term ‘volt’ is not recognized”), the terminal was opened before the install: close it and open a new one. With Windows Terminal or VS Code, close the whole program, not just the tab. If the script warned that your PATH is longer than 4094 characters, Windows leaves your user PATH out of new windows: follow the warning (it names any entries repeated in the system PATH) or run volt by its full path, %LOCALAPPDATA%\Programs\Volt\bin\volt.exe.

What the script did

  1. It asked GitHub for the newest release, downloaded the archive for your platform and the release’s SHA256SUMS file from https://github.com/volt-hdl/volt/releases/download/<version>/, and checked the archive against it. If the check fails, the script stops and deletes the download: nothing is installed and nothing changes.

  2. It put the binary in a folder of your own account:

    PlatformBinaryAlso there
    Windows%LOCALAPPDATA%\Programs\Volt\bin\volt.exeLICENSE-APACHE, LICENSE-MIT, README.md in ...\Programs\Volt\
    Linux, macOS~/.volt/bin/voltthe same three files in ~/.volt/
  3. It added that bin folder to your PATH, once:

    • Windows: at the front of your user PATH (the registry value HKCU\Environment\Path, the one “Edit environment variables for your account” shows). The system PATH is not touched. If a volt.exe in a system PATH folder would still win, the script warns you.

    • Linux and macOS: one line at the end of your shell’s startup file. The line ends with # added by the Volt installer:

      Your shell ($SHELL)File
      bash on Linux~/.bashrc
      bash on macOS~/.bash_profile
      zsh~/.zshrc
      fish~/.config/fish/config.fish
      any other~/.profile

Update: run the same command again. It replaces the binary (even while an editor runs volt lsp) and leaves the PATH as it is.

Uninstall: run it again with VOLT_UNINSTALL=1. It deletes the files listed above and removes the PATH entry or line, and nothing else:

Type this (Windows, PowerShell):

$env:VOLT_UNINSTALL = 1; irm https://volt-hdl.github.io/volt/install.ps1 | iex; Remove-Item Env:VOLT_UNINSTALL

Type this (macOS and Linux):

curl -fsSL https://volt-hdl.github.io/volt/install.sh | VOLT_UNINSTALL=1 sh

The script reads these settings from environment variables:

VariableEffect
VOLT_VERSION=0.1.0install that release instead of the newest one
VOLT_INSTALL_DIR=<folder>install into <folder> (the binary goes to <folder>/bin); give the same value again to uninstall
VOLT_ARCHIVE=<file>install from an archive you already have; a SHA256SUMS file next to it is used for the check
VOLT_UNINSTALL=1remove Volt again

Each release also carries the two scripts. A copy taken from a release installs that release, for example curl -fsSL https://github.com/volt-hdl/volt/releases/download/v0.1.0/install.sh | sh.

Manual install

Download the archive for your platform. These links always point at the newest release:

PlatformArchive
Windows x86_64volt-x86_64-pc-windows-msvc.zip
Linux x86_64 (static, any distribution)volt-x86_64-unknown-linux-musl.tar.gz
macOS, Apple siliconvolt-aarch64-apple-darwin.tar.gz
macOS, Intelvolt-x86_64-apple-darwin.tar.gz
ChecksumsSHA256SUMS

Older releases are on the Releases page.

Check the download

Compare the archive with its line in SHA256SUMS.

Type this (Linux):

grep volt-x86_64-unknown-linux-musl.tar.gz SHA256SUMS | sha256sum -c

You should see (Linux):

volt-x86_64-unknown-linux-musl.tar.gz: OK

On macOS, use shasum -a 256 -c in place of sha256sum -c. On Windows, PowerShell prints the hash; it must equal the one in SHA256SUMS (the case of the letters does not matter):

Type this (Windows, PowerShell):

(Get-FileHash volt-x86_64-pc-windows-msvc.zip -Algorithm SHA256).Hash
Select-String volt-x86_64-pc-windows-msvc.zip SHA256SUMS

With the GitHub CLI you can also check where the archive was built: gh attestation verify <archive> -R volt-hdl/volt.

Unpack it and put volt on your PATH

Each archive unpacks into a folder of its own, named like the archive. The volt binary is inside that folder.

You should see (Windows archive, unpacked):

volt-x86_64-pc-windows-msvc/
├── volt.exe
├── LICENSE-APACHE
├── LICENSE-MIT
└── README.md

The binary needs nothing else: no Rust, no runtime library, no data files.

Windows. In PowerShell, from the folder that holds the download:

Type this (Windows, PowerShell):

Expand-Archive volt-x86_64-pc-windows-msvc.zip -DestinationPath $env:LOCALAPPDATA\Programs
$dir = "$env:LOCALAPPDATA\Programs\volt-x86_64-pc-windows-msvc"
[Environment]::SetEnvironmentVariable("Path", "$dir;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

Or with the mouse: unpack the .zip, open Settings, search for “environment variables”, choose Edit environment variables for your account, select Path, click New and paste the path of the volt-x86_64-pc-windows-msvc folder. Then open a new terminal.

The binary is not code-signed. If Windows SmartScreen says “Windows protected your PC”, choose More info → Run anyway. You need to do this once.

Type this (Linux):

tar -xzf volt-x86_64-unknown-linux-musl.tar.gz
mkdir -p ~/.local/bin
mv volt-x86_64-unknown-linux-musl/volt ~/.local/bin/

Most distributions put ~/.local/bin on the PATH when it exists; you may need to log in again. If volt is still not found, add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc (or your shell’s startup file).

Type this (macOS):

tar -xzf volt-aarch64-apple-darwin.tar.gz
xattr -d com.apple.quarantine volt-aarch64-apple-darwin/volt
mkdir -p ~/.local/bin
mv volt-aarch64-apple-darwin/volt ~/.local/bin/

Use x86_64-apple-darwin in these names on an Intel Mac, and add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc if volt is not found. A browser marks downloaded files as quarantined, and macOS refuses to start an unsigned binary with that mark (“cannot be opened because the developer cannot be verified”). xattr -d removes the mark. If the file was never marked (for example, downloaded with curl, as the install script does), xattr says so and you can go on.

Build from source

For contributors and for platforms without a prebuilt binary. You need Rust (stable) and Git. The commands are the same on every system:

Type this:

git clone https://github.com/volt-hdl/volt
cd volt
cargo install --locked --path crates/volt-driver

cargo install puts volt into ~/.cargo/bin (on Windows %USERPROFILE%\.cargo\bin), which the Rust installer has already put on your PATH. A cold build takes a few minutes. To update, git pull and run cargo install again; to remove, cargo uninstall volt-driver.

When you need Docker

volt build, volt check, volt explain, volt new, volt doctor and volt lsp need nothing but the binary. volt test and volt run need the Verilator simulator, and volt verify needs SymbiYosys. You can install those yourself; if they are missing and Docker is running, Volt runs them in a container instead. So Docker is needed for simulation and formal verification when the tools are not installed, and never for anything else.

Ask volt doctor

volt doctor lists every command and whether it can run on this machine. Here it is on Windows 11 with Docker Desktop installed but not started (your own user folder in place of C:\Users\you).

Type this:

volt doctor

You should see (Docker Desktop not running):

volt 0.1.2 (windows-x86_64)

✓ build, check, explain — no external tools needed
✗ test, run — Verilator, C++ compiler, make not found
    fix (Windows): start Docker Desktop: Volt runs Verilator in a container (DOCKER below), or use WSL
    see: volt explain simulation-setup
✗ verify — sby, Yosys not found; no SMT solver found (boolector, bitwuzla, yices, z3)
    fix (Windows): start Docker Desktop: Volt runs sby in a container (DOCKER below), or use WSL
    see: volt explain verify-setup
- timing (optional) — OpenSTA not found; checks generated .sdc files
- driver checks (optional) — C compiler not found (found: rustc 1.95.0); compiles drivers from --emit=c,rust
! docker — 29.8.1 installed, daemon not running (start Docker Desktop or the docker service)
- project — no Volt.toml (search stopped at the home directory C:\Users\you); single .volt files still work

volt build, volt check and volt explain work already. Simulation (volt test, volt run) and formal verification (volt verify) need external tools.

New to hardware? Simulation and formal verification

A hardware design is not a program you run. To see what it does, a simulator computes the value of every signal, clock cycle by clock cycle, and a testbench drives the inputs and checks the outputs. Volt uses Verilator, an open-source simulator. Formal verification goes further: a solver searches every possible input sequence for one that breaks a rule you wrote. Volt uses SymbiYosys for that.

Docker: the simulator without an install

You can install Verilator and SymbiYosys yourself (volt explain simulation-setup and volt explain verify-setup say how). The shorter way is Docker: when Verilator or SymbiYosys is missing and Docker is running, Volt runs the tool in a container on its own and says so in one line.

Install Docker Desktop on Windows or macOS, or Docker Engine on Linux, and start it. Wait until the Docker Desktop window says Engine running. Then run volt doctor again.

Type this:

volt doctor

You should see (Docker Desktop running):

volt 0.1.2 (windows-x86_64)

✓ build, check, explain — no external tools needed
✓ test, run — via Docker (verilator/verilator:v5.054: Verilator 5.054, g++ 13.3)
✓ verify — via Docker (hdlc/formal:all: Yosys 0.66, SBY 0.69, boolector 3.2.4, yices 2.7.0, z3 4.15.0)
- timing (optional) — OpenSTA not found; checks generated .sdc files
- driver checks (optional) — C compiler not found (found: rustc 1.95.0); compiles drivers from --emit=c,rust
✓ docker — 29.8.1, daemon running
- project — no Volt.toml (search stopped at the home directory C:\Users\you); single .volt files still work

Expect a download on initial use. The images are downloaded once, when a command needs them: about 250 MB for simulation on your initial volt test, about 404 MB for formal verification on your initial volt verify, so about 650 MB in total. Volt prints the size before the download and the time after it. On our connection the simulation image took between 45 and 57 seconds; on a slow day (0.5 MB/s) the same machine took 8½ minutes for the simulation image and 12 minutes for the formal one. The Tour needs just the simulation image.

Coming from SystemVerilog? Your own tools take priority

If verilator and sby are on your PATH, Volt uses them and never starts a container. The images are pinned by digest (verilator/verilator:v5.054, hdlc/formal:all), so a result does not change when an image tag moves. VOLT_TOOL_BACKEND=local turns the Docker bridge off; VOLT_TOOL_BACKEND=docker forces it. On Linux the files the container writes belong to you, not to root.

Next: a project in three commands.