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-projectsfolder. 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 testruns the Verilator simulator in Docker. If Verilator is installed on your computer, Docker is not needed;volt doctorsays which onevolt testuses. 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
domainblock names a clock domain and says how its registers work.clock = posedgemeans they update on the rising edge of the clock.reset = sync active_highmeans their reset is synchronous, read at a clock edge like any other input, and active high: 1 means reset. @Adcafter a port type puts the port into the domainAdc. The clock portadc_clkis the clock of that domain.- A register belongs to the domain of the
onblock that writes it:last_rtoAdc,data_rtoSys. 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 typeu8. The size must be a power of two.- The ports that start with
wr_belong to the domain ofwr_clk, hereAdc; the ports that start withrd_belong to the domain ofrd_clk,Sys. Volt checks what you connect:sampleis@Adcand goes towr_data. Connectingsample_validtord_enwould be errorE3001again. fifo.rd_emptyis true when there is nothing to read, andfifo.wr_fullis true when there is no room. The read side reads whenever the FIFO is not empty:take = !fifo.rd_empty.wire take : bool @Sysdeclares the wire, with its domain, above the FIFO, because a name must be declared before it is used (errorE1002). Its value is given further down. The@Sysis a promise that Volt checks: assigning it a value ofAdcwould be an error.fifo.rd_datais a register: a value read withrd_enappears on it one clock cycle later.valid_rdelaystakeby the same cycle, sodata_validis true exactly whendataholds a new sample.droppedis in theAdcdomain, 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.052)
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
domainnames a clock domain;@Nameputs a port or a wire into it, and a register belongs to the domain of itsonblock. - Reading a signal of one domain in another is error
E3001. sync()is for a single bit. On a number it is warningW3003, because the bits can arrive in different cycles.AsyncFifocarries a stream of values between two clocks; itswr_andrd_ports belong to the two domains.- A raw reset port,
in rst : reset(...), gets one reset synchronizer per clock. volt testdrives every clock together, one edge perstep().
Next: contracts and formal verification prove properties of a design for every input, not just the ones a test tries.