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 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-projectsfolder. 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 testruns the Verilator simulator in Docker. If Verilator is installed on your computer, Docker is not needed;volt doctorsays which onevolt testuses.
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:
| State | Means | Moves on |
|---|---|---|
Up | the button is released | to GoingDown when the input is on |
GoingDown | the input is on, but not for long enough yet | to Down after a steady stretch, back to Up if the input drops |
Down | the button is pressed | to GoingUp when the input is off |
GoingUp | the input is off, but not for long enough yet | to 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 = 4names 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::Upis one of them.reg state_r : Button = Button::Upis the state register. It holds one of the four values, and starts inUpafter 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 writestate_rstays where it is.count_rcounts how long the input has been steady. Each “going” state sets it to 0 on the way in and counts up; when it reachesSTABLE - 1, the machine moves on.pressedandclickare outputs computed from the state.==compares two enum values.clickis true for the one cycle in whichGoingDowndecides 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:21is the linestate_r <= Button::GoingDownin theUparm: the transition fromUptoGoingDown. It was taken 4 times, at least once in each test.debounce.volt:41is the linestate_r <= Button::Downin theGoingUparm: a bounce while the button is being released.NEVER HITmeans that no test made that transition, so it was never tested.auto counter wrapcounts the cycles in whichcount_rholds 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; aregof that type,reg state_r : Name = Name::A, is the state register, with a state as its reset value.matchon the state register gives each state an arm; an arm that does not write the register keeps the state.- A
matchmust handle every state: a missing one is errorE0014. Prefer an arm per state over a_arm. constnames a number, such as how long an input must stay steady.- Volt generates a cover for every transition, and
volt testlists them:NEVER HITpoints at a transition no test took.
Next: two clocks and CDC moves data between parts of a design that run on different clocks.