Repository navigation
Volt 0.1.0
Volt is a hardware description language with a Rust-like syntax. It
compiles to SystemVerilog and checks clock and reset domains in its type
system: a clock domain crossing without a synchronizer is a compile error.
0.1.0 is the earliest Volt release. It makes no stability promise: the
syntax, the diagnostic codes and the generated SystemVerilog may change in
0.2 and later (see Support).
The recording above: volt check reports an unsynchronized crossing, and
the sync() line from its help message fixes it
(the code,
the recording script).
The book: https://volt-hdl.github.io/volt/.
Behavior changes
There is no earlier release to compare with. The changes below matter if
you built Volt from the main branch before this release: the same input
now gives a different result.
Clock and reset domains
- A flip-flop clocked from a domain declared with
clock = none(a domain
with no clock edge) is now errorE3016: in anonblock, as a
sync()destination, on the clock port of a built-in component or a
submodule, and as the sampling clock of contracts. It used to compile to
aposedgeflip-flop. Combinational signals in such a domain, and
sync()from it (an asynchronous input), are still accepted. - An
onblock whose trigger is not a clock port (on dwith
d : bool), and two clock ports annotated with each other's domain,
are now errorE3002, reported byvolt checkand the editor as well
as byvolt build. SystemVerilog generation derives the clock edge and
the reset branch of every flip-flop from the source and no longer
assumes them. - A clock port annotated with the domain of another clock port
(in c2 : clock @c1) takes that clock's domain, in any port order.
Whenc1is in a domain whose edge isnegedge, the flip-flops of
on c2are nownegedge; they used to beposedge. - New warning
W3011: a raw reset port that reaches the module's
registers through a release synchronizer is also connected to an
externinstance, which gets the unsynchronized reset. The output does
not change.
Registers, wires and let
- Writing a
wireor anoutport with<=inside anonblock is now
errorE0020. It used to produce a flip-flop with an empty reset
branch, which kept its old value through reset. The suggestion rewrites
the signal as a register with a reset value. - An untyped
lettakes the natural width of its expression: witha
andbof typeu8,let s = a + bis now 9 bits wide (it was 8, so
255 + 1 gave 0).*doubles the width; a unary-turnsiNinto
i(N+1). Code that relies on wrap-around writes the type:
let addr : u32 = pc + 4. - An untyped literal
let(let k = 100) now compiles, with warning
W2012, as ani32. It used to fail withE2005. A literal that does
not fit in ani32isE2010. - An untyped
letwhose carry bit a comparison reads no longer gets the
comment// carry bit of '...' unusedand anUNUSEDSIGNALlint waiver
in the generated SystemVerilog. Both were wrong: the carry bit is used.
Comparisons
- Comparing two values whose natural widths differ is now error
E2031.
Withaandbof typeu3,b + 1is 4 bits wide, and both
a == b + 1andlet s = b + 1followed bya == sare rejected. They
used to compile to different hardware: the inline form wrapped at 3 bits,
theletform kept the carry, soa = 0,b = 7gave different
results. The same rule applies in contracts. A side that is a constant
known at compile time and fits the other side is accepted
(count == LIMIT - 1). The help line gives both fixes withas:
a == (b + 1)[2:0] as u3wraps,(a as u4) == b + 1keeps the carry. - An accepted comparison is made at the natural width of its sides: with
canddof typeu8,c + d == 5keeps the carry (it used to wrap
at 8 bits), andc + d < 300compares with 300 (it used to compare with
8'd300, which is 44). - A shift or a
~inside a wider arithmetic keeps its own width. With
aof typeu8,let w : u12 = (~a) + 0gives 255 fora = 0; it
used to give 4095, inverting the upper bits too, without a warning.
(a << n) + bin a 12-bitlet, anda << nassigned to a 12-bit
output, used to stopvolt testwith a Verilator width warning. - A bit, range or indexed part-select of a computed value, such as
(a + 1)[3:0]or(a + b)[i +: 4], compiles to valid SystemVerilog
(4'(9'(a) + 9'd1),4'((9'(a) + 9'(b)) >> i)), computed at the
natural width so that the carry can be selected. It used to be
written as(a + 8'd1)[3:0]or(a + b)[i +: 4], which Verilator and
Yosys reject.
Expressions and casts
These were found by the differential test of expression semantics, which
compares the generated SystemVerilog, simulated in Verilator, with a
reference model written from the language specification.
- An
ascast that changes the width takes the sign of its target type
(#115). Withaof typei10,a as i11 > 880is now false for
a = -1. It used to be true: the sign extension{{1{a[9]}}, a}was
compared as an unsigned number. It is now written
$signed({{1{a[9]}}, a}) > 11'sd880. The same mistake made
s as i50 >> 8(s : i7) shift in zeros, and-(s as i4)
(s : i2) give -15 instead of 1 fors = -1. - A hexadecimal, binary or octal literal in a signed expression is a
signed literal (#116). Withsof typei50,s > 0x0is now false
fors = -1; it used to be true, because50'h0made the comparison
unsigned. It is now writtens > 50'sh0. The most negative value of a
width is written as a bit pattern (8'sh80): withsof typei1,
(s * (-1)) as u35gave 34359738367 (all ones) fors = -1instead
of 1. - A sub-expression whose value depends on its width keeps its value
inside a wider expression (#117). Withaandbof typeu8and
cof typeu9,(a - b) + cassigned to au10gave 1023 +c
fora = 0,b = 1, whilelet s = a - bfollowed bys + cgave
511 +c. Both now give 511 +c: the subtraction is computed at its
own width,10'($unsigned(9'(a) - 9'(b))) + 10'(c). The same holds for
an unsigned subtraction in a wider product or cast, a sum whose carry a
bitwise operation drops (((a + b) | c) + c),~under a cast of the
same width,-xinside a shift, and the right shift of a sum, which now
reads the carry ((a + b) >> n). -(-x)compiles to-(-(...))(#118). It used to be written
--(...), the SystemVerilog decrement operator, which Verilator
rejects.- A select of a select of a computed value compiles to valid
SystemVerilog (#119):(q as bits<34>)[28:0][27]is now
1'((29'(q)) >> 27). It used to be29'(q)[27], which Verilator and
Yosys reject. - A bit or range select of a one-bit value (
u1,i1,bits<1>)
compiles to the value itself (#120):x[0],x[0:0]andx[0 +: 1]
are nowx. They used to be written as a select of a scalar, which
Verilator rejects. A select of a signed one-bit value is unsigned
($unsigned(x)). - The generated SystemVerilog no longer causes Verilator width warnings
(#123). These warnings are fatal by default, sovolt teststopped on
a valid design. A variable index or part-select start whose width
differs from the address width of its base is written as a shift: with
xof typeu15andiof typeu3,x[i]is now1'((x) >> i). A
widening cast of a computed value is written at the target width:
(a + b) as i32is now32'((32'(a) + 32'(b)))(it was
32'((a + b))). A literal wider than its context is written as its
truncated bit pattern (1'h1, not1'd3). Values do not change,
except the bits of a variable part-select that fall outside its base:
they are undefined (x) in the language and now read as 0.
Modules
- An
extern modulenamed like a standard library module (EdgeDetect,
SyncFifo,Counter, ...), or a Volt module with such a name
instantiated from another module, is now errorE1016. The built-in
module used to be taken in its place without a word. A top-level module
with such a name (theCounterof thevolt newtemplate) stays valid.
Commands
volt checkwithout arguments (project mode) also checks every test
file thatvolt testfinds, in subdirectories too (build/is
skipped), and prints aChecking <file>line for each. A project that
passed before exits with code 1 if a test file has an error.- A test file
X_test.voltwith no siblingX.voltgets the full check
involt check,volt buildand the editor, as involt test: a
missing module under test isE8501. - The
Compilinglines ofvolt testprint relative paths without a
prefix (counter_test.volt,sim/deep_test.volt; it used to print
.\counter_test.volt). volt --version,voltwithout arguments, theVersion:line of
generated SystemVerilog and the header of SDC/XDC files name the commit
the binary was built from:volt 0.1.0 (abcdefg). A binary built
without git, or from a release source archive, prints the version alone.--color auto|always|never,--no-colorandVOLT_COLORwork with
every command and color error and warning diagnostics. In a terminal,
diagnostics are colored by default; they are not when the output is not
a terminal or whenNO_COLORorCIis set.volt check --colorused
to fail with "unexpected argument" (exit code 2).
Highlights
Clock and reset domains in the type system
Every signal belongs to a clock domain. A crossing without a synchronizer
is error E3001, and its help message holds the line that fixes it. The
bridges are sync(), sync3() and the built-in dual-clock components
(AsyncFifo, HandshakeSync, PulseSync, AsyncDualPortRam); a
multi-bit sync() is warning W3003. For resets, Volt puts a release
synchronizer in front of a raw reset port and reports an asynchronous
reset shared by several clock domains or synchronized twice (E3003).
In the book:
A clock domain crossing error,
Two clocks and CDC,
Reset synchronizers.
Contracts and formal verification
requires, ensures, invariant and cover are part of the language,
with prev(x, N) for the values of earlier cycles. volt verify writes
the model and the SymbiYosys script, runs it and maps the result back to
the line of the contract. A violated contract exits with code 6 and
leaves a counterexample VCD. In the book:
Contracts and formal verification.
Simulation, with Verilator in Docker when it is not installed
test blocks in *_test.volt files run on Verilator with volt test. A
failing test runs again with tracing and names its waveform file;
volt test --watch runs the tests again when a file is saved. When
Verilator or SymbiYosys is not installed and Docker is running,
volt test, volt run and volt verify run the tool in a pinned
container image (Verilator: verilator/verilator:v5.052) and say so in
one line. volt doctor shows which way each command will run. In the
book: Tests and waveforms.
Readable SystemVerilog
volt build writes one SystemVerilog module per Volt module, under the
same name. Ports, registers and let signals keep their names, /// doc
comments become // comments, registers are always_ff blocks with
explicit widths, and a generated synchronizer carries a comment naming
its crossing. The files need no Volt package, include or runtime:
Verilator 5.052 reports nothing on the book's example with
--lint-only -Wall. More outputs on request: SVA for the contracts
(--emit=sva), SDC/XDC constraints (--emit=sdc,xdc), and C and Rust
drivers for an @mmio register map (--emit=rust,c).
Existing SystemVerilog, with extern
extern module with @source("rtl/x.sv") uses an existing SystemVerilog
module from Volt, with a clock domain on each port, and volt test
simulates the two together. In the other direction, a generated module
drops into a SystemVerilog design like any other module, with one port
you did not write: the reset rst. Volt does not read the SystemVerilog
file (Verilator reports a port mismatch), and an extern takes no
parameters and gets the raw reset (W3011 above). In the book:
Using Volt in an existing project.
Also in this release
volt newandvolt initproject templates,volt doctor, and
volt explain <CODE>for every diagnostic code, in English and Turkish
(--lang=tr).- A language server (
volt lsp) and a VS Code extension, attached to
this release asvolt-hdl-0.1.0.vsix(it is not on the Marketplace). - Prebuilt binaries for Windows x86_64, Linux x86_64 (static, musl) and
macOS (Intel and Apple Silicon).
Install
Windows (PowerShell):
irm https://volt-hdl.github.io/volt/install.ps1 | iexLinux and macOS:
curl -fsSL https://volt-hdl.github.io/volt/install.sh | shThe script downloads the archive for your platform from this release,
checks it against SHA256SUMS, installs volt in your user folder (no
administrator rights) and adds it to your PATH. Running it again
updates Volt, VOLT_UNINSTALL=1 removes it, and VOLT_VERSION=0.1.0
installs this release instead of the newest one. In a new terminal,
volt --version prints volt 0.1.0 followed by the commit in
parentheses. For a computer with no development tools yet, the book
walks through it step by step:
Setup and
Install Volt.
By hand: download volt-<target>.zip (Windows) or .tar.gz from the
assets below, unpack it and put volt on your PATH. To verify a
download:
sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify volt-x86_64-unknown-linux-musl.tar.gz -R volt-hdl/voltThe binaries are not code-signed. On Windows, SmartScreen may stop a
downloaded volt.exe ("More info", then "Run anyway"); on macOS, a binary
unpacked from an archive downloaded in a browser needs
xattr -d com.apple.quarantine volt.
Known limitations
The full list, with workarounds:
Known limitations.
The main ones:
- No built-in simulator:
volt testandvolt runneed Verilator,
installed or in Docker. volt verifyneeds SymbiYosys, Yosys and an SMT solver (Linux; WSL or
Docker on Windows). Sequential properties are limited toprev(): no
sequences, no liveness.- Reset checks cover reset release, not reset ordering.
- SystemVerilog is the output language; there is no VHDL output.
- Some constructs pass the type checker but are rejected at generation
withE0003, among them arrays of structs, generic structs and enums
with data-carrying variants. - Volt is used by its maintainer and has no external users yet; there
are no FPGA board or tape-out results.
Support
- The latest release is the supported one. Fixes go into
mainand ship
with the next release; there are no backports and no maintenance
branches. Before reporting a bug, reproduce it on the latest release or
onmain: issues. - Before 1.0, a new middle digit (0.2.0) may break existing code and a
new last digit (0.1.1) brings fixes. A fix for a silent wrong result
may reject input that was accepted before even in a last-digit release;
it is then listed under Behavior changes. - The notes of every release have a Behavior changes section. Read it
before upgrading, and pin a version withVOLT_VERSIONwhere a change
would hurt.
The full change log, in Turkish:
CHANGELOG.md.
Planned work: Roadmap.
