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.

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.