Skip to content

Volt 0.1.0

Choose a tag to compare

@github-actions github-actions released this 04 Nov 13:23
· 67 commits to main since this release
5eff136

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).

A terminal: volt check reports error E3001 on crossing.volt, the sync() line from its help line is added in nano, and volt check reports 0 errors

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 error E3016: in an on block, 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
    a posedge flip-flop. Combinational signals in such a domain, and
    sync() from it (an asynchronous input), are still accepted.
  • An on block whose trigger is not a clock port (on d with
    d : bool), and two clock ports annotated with each other's domain,
    are now error E3002, reported by volt check and the editor as well
    as by volt 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.
    When c1 is in a domain whose edge is negedge, the flip-flops of
    on c2 are now negedge; they used to be posedge.
  • New warning W3011: a raw reset port that reaches the module's
    registers through a release synchronizer is also connected to an
    extern instance, which gets the unsynchronized reset. The output does
    not change.

Registers, wires and let

  • Writing a wire or an out port with <= inside an on block is now
    error E0020. 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 let takes the natural width of its expression: with a
    and b of type u8, let s = a + b is now 9 bits wide (it was 8, so
    255 + 1 gave 0). * doubles the width; a unary - turns iN into
    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 an i32. It used to fail with E2005. A literal that does
    not fit in an i32 is E2010.
  • An untyped let whose carry bit a comparison reads no longer gets the
    comment // carry bit of '...' unused and an UNUSEDSIGNAL lint 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.
    With a and b of type u3, b + 1 is 4 bits wide, and both
    a == b + 1 and let s = b + 1 followed by a == s are rejected. They
    used to compile to different hardware: the inline form wrapped at 3 bits,
    the let form kept the carry, so a = 0, b = 7 gave 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 with as:
    a == (b + 1)[2:0] as u3 wraps, (a as u4) == b + 1 keeps the carry.
  • An accepted comparison is made at the natural width of its sides: with
    c and d of type u8, c + d == 5 keeps the carry (it used to wrap
    at 8 bits), and c + d < 300 compares 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
    a of type u8, let w : u12 = (~a) + 0 gives 255 for a = 0; it
    used to give 4095, inverting the upper bits too, without a warning.
    (a << n) + b in a 12-bit let, and a << n assigned to a 12-bit
    output, used to stop volt test with 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 as cast that changes the width takes the sign of its target type
    (#115). With a of type i10, a as i11 > 880 is 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 for s = -1.
  • A hexadecimal, binary or octal literal in a signed expression is a
    signed literal (#116). With s of type i50, s > 0x0 is now false
    for s = -1; it used to be true, because 50'h0 made the comparison
    unsigned. It is now written s > 50'sh0. The most negative value of a
    width is written as a bit pattern (8'sh80): with s of type i1,
    (s * (-1)) as u35 gave 34359738367 (all ones) for s = -1 instead
    of 1.
  • A sub-expression whose value depends on its width keeps its value
    inside a wider expression (#117). With a and b of type u8 and
    c of type u9, (a - b) + c assigned to a u10 gave 1023 + c
    for a = 0, b = 1, while let s = a - b followed by s + c gave
    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, -x inside 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 be 29'(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] and x[0 +: 1]
    are now x. 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, so volt test stopped 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
    x of type u15 and i of type u3, x[i] is now 1'((x) >> i). A
    widening cast of a computed value is written at the target width:
    (a + b) as i32 is now 32'((32'(a) + 32'(b))) (it was
    32'((a + b))). A literal wider than its context is written as its
    truncated bit pattern (1'h1, not 1'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 module named like a standard library module (EdgeDetect,
    SyncFifo, Counter, ...), or a Volt module with such a name
    instantiated from another module, is now error E1016. The built-in
    module used to be taken in its place without a word. A top-level module
    with such a name (the Counter of the volt new template) stays valid.

Commands

  • volt check without arguments (project mode) also checks every test
    file that volt test finds, in subdirectories too (build/ is
    skipped), and prints a Checking <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.volt with no sibling X.volt gets the full check
    in volt check, volt build and the editor, as in volt test: a
    missing module under test is E8501.
  • The Compiling lines of volt test print relative paths without a
    prefix (counter_test.volt, sim/deep_test.volt; it used to print
    .\counter_test.volt).
  • volt --version, volt without arguments, the Version: 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-color and VOLT_COLOR work 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 when NO_COLOR or CI is set. volt check --color used
    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 new and volt init project 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 as volt-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 | iex

Linux and macOS:

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

The 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/volt

The 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 test and volt run need Verilator,
    installed or in Docker.
  • volt verify needs SymbiYosys, Yosys and an SMT solver (Linux; WSL or
    Docker on Windows). Sequential properties are limited to prev(): 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
    with E0003, 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 main and ship
    with the next release; there are no backports and no maintenance
    branches. Before reporting a bug, reproduce it on the latest release or
    on main: 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 with VOLT_VERSION where a change
    would hurt.

The full change log, in Turkish:
CHANGELOG.md.
Planned work: Roadmap.