Known limitations
What Volt 0.1 does not do yet, so you can decide early whether it fits your design. Each limit says what happens when you hit it, how to work around it where a way exists, and where the work is planned in the roadmap.
Stability
No stability promise. Volt 0.1 is an early release. Syntax,
diagnostic codes and the shape of the generated SystemVerilog may change
in any later release, without a deprecation period. Pin the Volt version
you use (the install script takes VOLT_VERSION) and read the changelog
before upgrading. Roadmap:
A stability policy.
Volt is used by its maintainer, nobody else yet. There are no FPGA board or tape-out results; the examples run in simulation and formal verification.
Known bugs
These are bugs, not design limits: each one has an issue and is planned
for a fix. Until then, the workaround after each one avoids it. The
division bug (#150) and
the cut operand of +, - and *
(#266) are under
Language below.
volt build follows links out of the project. When build/, or a
file in it, is a symbolic link, volt build writes through the link. A
cloned repository can carry such a link, so building it can overwrite a
file anywhere you can write; on Windows a directory junction in place of
build/ does the same. Do not build a repository you do not trust;
before building one, check that build/ and the files in it are not
links. Tracked in issue #221.
A struct let whose flattened field name equals another name. A
struct let in a block becomes one signal per field in the generated
SystemVerilog: let p : S with a field x becomes p_x. If a port or
signal is also called p_x, a read of it in that block reads the field
of the local, without a warning. Do not name a port or signal
<let>_<field>; rename the let. Tracked in
issue #154.
A module-level let with the name of a bundle port or of regs is
accepted without error E1003, and the name then means two different
things: the port in one place, the let in another. Give the let a
name of its own. Tracked in
issue #155.
An import alias reaches the generated SystemVerilog. With
use other::X as J, a constant used as a value (y = J) is written
into the SystemVerilog as assign y = J;, a name that does not exist
there, without a diagnostic; an aliased type, function, domain or module
is rejected. Import such items without as. Tracked in
issue #161.
A test block can read a private constant of another file, without
error E1001. Make the constant pub and import it with use in the
test file, as the visibility rules require. Tracked in
issue #162.
Constant evaluation stops at depth 64 in for bounds and bundle
arrays. A module-level for bound or a bundle array length that is a
constant expression deeper than 64 levels, or the end of a chain of 64
constants, is rejected with E2021; a cycle there is E2021 instead of
E2020; and a counter whose limit is such a chain gets no inferred
contract. Keep constant chains and expressions shallower than 64 levels.
Tracked in issue #159.
A generic module that is never instantiated and uses its parameter in
a type (in x : uint<N>) is rejected with E2021 (“this is a generic
parameter (runtime value)”), also in a file loaded with use. Instantiate
the module once, for example Fir<8> { ... }. Tracked in
issue #172.
A match is computed at a narrower width than the type checker
uses. With u8 operands, let m = match sel { 0 => a + b, _ => a - b }
is an 8-bit signal in the generated SystemVerilog, so 200 + 100 gives 44;
match a + b with an arm 44 => also takes the value 300; and a
contract with prev(a + b) or a signed prev() compares at the wrong
width. Write the choice as if/else, or put the subject in a let
with an explicit width (let s : u9 = a + b, then match s). Tracked in
issue #215.
In a statement match, an arm after the wildcard wins. In a comb
block, match s { 0 => { … } _ => { y = 7 } 1 => { y = 9 } } gives 9 for
s = 1, while the same match written as an expression gives 7. Write
the wildcard arm last. Tracked in
issue #216.
A const that does not fit its type is accepted. With
const A : u8 = 255 and const B : u8 = A + 1, compile time sees 256 (a
bits<B> port is 256 bits wide) and the hardware sees 0. Make sure every
constant computed from other constants fits its declared type. Tracked
in issue #214.
The clock outputs of an extern module have no clock domain. With a
PLL or a clock buffer declared as an extern module with
out c0 : clock, nothing clocked by c0 is checked: a crossing between
the input clock and an output clock gets no E3001. Synchronize every
value between these clocks yourself with sync() or an AsyncFifo.
Tracked in issue #208.
A register’s reset value can be a signal, and it is not checked.
reg r : u8 = a loads a at reset without the clock-domain check
(E3001) and the trust check (E3009). Use a constant reset value and
load the signal in the on block. Tracked in
issue #209.
A clock port declared through a type alias is not a clock everywhere.
With type Clk = clock, an asynchronous reset shared by two clock
domains gets no E3003, the SDC file has no create_clock for the
clock, and a test block can drive it. Write clock for clock ports.
Tracked in issue #234.
E5010 is missed in a comb block. In an @strict_timing module,
choosing between values of different delays inside a comb block
(comb { if x[0] { w = a } else { w = b } }) compiles, while the same
choice written as let w = if x[0] { a } else { b } gets E5010. Write
such a choice as a let. Tracked in
issue #217.
A timing constraint can apply to a second register. @multicycle,
@false_path and @timing(max_delay) on a register slow are written
to the SDC file as get_cells {slow_reg*}, which also matches a
register named slow_reg. Do not name a register <name>_reg… next to
a constrained register <name>. Tracked in
issue #219.
A secret passes through an unclassified input port of a submodule.
With module Mid { in x : u8 out o : u8 @Pub o = x }, binding a
@Sec value to x carries it to a public output without E3009.
Annotate the input ports of submodules with their trust domain. Tracked
in issue #210.
The trust annotation of a wire or a let is not read. In a module
without a clock, wire w : u8 @Pub driven by a @Sec value gets no
E3009; in a module whose clock is @Pub, wire w : u8 @Sec gets a
false E3009. Annotate the ports instead. Tracked in
issue #211.
An @mmio module next to a declared AXI bundle name does not
compile. When the file declares AxiWriteAddr or another of the five
AXI bundle names itself, the generated module reports E1001 for names
such as aw_valid that you did not write. Do not declare these names
next to an @mmio module. Tracked in
issue #244.
A bits<K> value cannot cross a pipeline stage. It is rejected with
E2003 on a literal that the compiler generates. Carry the value as
uK across the stage and cast it back to bits<K> where it is used.
Tracked in issue #245.
frequency = 100mhz gets errors that do not say what is wrong. The
domain key gets W0020 “unknown domain key: ‘mhz’” followed by E0001.
Write 100.mhz. Tracked in
issue #223.
An incomplete assignment in a comb block infers a latch.
comb { if c { y = 1 } else { if d { y = 2 } } } compiles, and the
generated always_comb keeps the old y when c and d are both false
(Verilator reports LATCH). A wire that is read and never driven
compiles too (Verilator reports UNDRIVEN). Assign every output of a
comb block on every path, for example with a default assignment at the
top of the block (y = 0), and drive every wire. Tracked in
issue #230.
A port bound twice in one instance takes the last binding.
Child { x: 1, x: a } compiles without a diagnostic and connects x to
a. Bind each port once. Tracked in
issue #229.
The fix that E5010 suggests does not change the hardware. The help
suggests delay<1>(a) to align a value of one cycle with a value of two;
let sum = delay<1>(a) + b then compiles, but delay<1> adds no
register, and the two values are still of different ages. Add the
register yourself: a reg a2 : Delayed<u32, 2> loaded with a2 <= a,
and let sum = a2 + b. Tracked in
issue #232.
@false_path and @multicycle are not checked. They are written to
the SDC file for any two registers, also for a real one-cycle path, and
the timing tool then leaves that path untimed. volt explain E6003 and
E6004 say that Volt proves these attributes; it does not, and the two
codes are never reported. Treat both attributes as your own claim. On a
port whose type is a struct or a struct port, neither attribute
constrains anything: @false_path in cfg : Cfg writes
get_ports cfg, which matches none of the generated ports (cfg_a,
cfg_b), or no line at all for a struct port. Declare such inputs as
plain ports. Tracked in
issue #226,
issue #231 and
issue #229.
Reading an input port of an instance writes an undeclared name. With
let s = Sub { x: a }, p = s.x compiles and is written as
assign p = s_x;, which Verilator rejects. Read the value you bound
(p = a). Tracked in
issue #218.
An array literal assigned to an array wire fails in Verilator.
xs = [x0, x1] with wire xs : [u8; 2] is written as
assign xs = '{x0, x1};. Assign the elements one by one:
comb { xs[0] = x0 xs[1] = x1 }. Tracked in
issue #135.
A constant index of a wider type than the address stops volt test.
With const K : u4 = 2, a[K] on a u8 is written as a[4'd2], and
Verilator stops with WIDTHTRUNC. Give the constant the width of the
address (const K : u3 = 2 for an 8-bit value). Tracked in
issue #134.
Two @mmio modules in one design do not compile, and some @mmio
arguments are not checked. The second @mmio module gets E1001 for
the AXI bundle names, also in another file. A base address that is not a
multiple of 4 is accepted, a repeated argument takes the last value, and
a /// comment is copied into the generated C header as it is, so a */
in it ends the C comment. Use one @mmio module per design, a base
address that is a multiple of 4, each argument once, and no */ in the
comments of an @mmio module. Tracked in
issue #220.
A struct port whose field has a private struct type of its own file is
rejected with E1001 where the port is used. Make the field’s struct
pub and import it too. Tracked in
issue #163.
declassify() in a module-level for or a generic module gets a
false E3009. Write the assignments without the for, one per
element, and keep declassify() out of generic modules. Tracked in
issue #212.
A submodule output that depends on public inputs alone is taken as
secret when another input of the same instance is secret, and gets a
false E3009. Put the public part in a submodule of its own, whose
inputs are all public. Tracked in
issue #195.
A source file that begins with a byte order mark is rejected
(E0001: unexpected character: "\u{feff}"). Some Windows editors write
this mark when they save as “UTF-8 with BOM”; save the file as UTF-8
without it. Tracked in
issue #229.
A malformed Volt.toml is ignored. When Volt.toml is not valid
TOML, volt build compiles and exits with 0, without a diagnostic. If a
setting seems to have no effect, check the syntax of the file. Tracked
in issue #222.
Some explanations in volt explain are wrong. The solution of
E3012 and E3011 (r <= sync(fast_data, slow_clk) in an on block)
gets E0003: write let s = sync(x, clk) at module level, as the
compiler’s own help says. W0010 says that == binds before &; Volt
reads a & b == c as (a & b) == c. E3004, E3005, E6001,
E6003, E6004, E7001, E7002, E9001, E9002, W2011, W2020
and W2021 are explained as checks, but the compiler never reports
them. Where an explanation and the compiler disagree, follow the
compiler. Tracked in
issue #225 and
issue #226.
The project that volt new creates names its module Counter, a
name of the standard library, so instantiating it from another module
gets E1016. Rename the module (and top in Volt.toml) before you
use it in a larger design. Tracked in
issue #101.
Language
Some constructs pass the type checker but have no SystemVerilog mapping
yet. They are rejected with E0003 (“not supported yet”), and
volt explain E0003 describes the error. Today this covers:
- integer types wider than 64 bits written as
u128ori100. Usebits<N>, which has no width limit; - arrays of structs, arrays of enums, generic structs, enums whose variants carry data, and generic enums;
- generic functions, contracts on a function, and
forinside a function body; matcharm guards (0 if c =>) and matching a whole struct value. Range, binding and struct patterns do not exist;todo!(). It is parsed, butvolt checkandvolt buildreject it. Roadmap: todo!() placeholders.
The README’s Limitations section has the details and the measurements behind some of these decisions.
SystemVerilog is the sole output language. There is no VHDL output.
Integer literals stop at 2¹²⁸ - 1. A literal holds a value up to
2¹²⁸ - 1 in any base. A larger one, such as
0x1_0000_0000_0000_0000_0000_0000_0000_0000, is E0005 (“value does
not fit in 128 bits”), also when the target is bits<256>. Nothing is cut
silently: a literal up to 2¹²⁸ - 1 cast to bits<256> keeps its value
and the upper bits are zero. To build a wider constant, write it in
128-bit parts and join them with a struct cast. hi, declared before
lo, holds the upper 128 bits:
struct Key256 {
hi : bits<128>,
lo : bits<128>,
}
module Key {
out key : bits<256>
let k : Key256 = Key256 {
hi: 0x0123_4567_89AB_CDEF_0011_2233_4455_6677 as bits<128>,
lo: 0x8899_AABB_CCDD_EEFF_FEDC_BA98_7654_3210 as bits<128>,
}
key = k as bits<256>
}
key[255:192] is 0x0123_4567_89AB_CDEF and key[63:0] is
0xFEDC_BA98_7654_3210.
The width of a division with a wider arithmetic operand will change.
/ and % do not widen: a * b / c (all u8) divides at 8 bits, and
the product, up to 16 bits wide, is cut to 8 bits before the division.
The generated SystemVerilog does not always do the same, and the rule
changes in v0.2.0. Until then Volt warns (W2015) wherever an operand is
cut. Write the width you mean on both operands, as in
(a * b) as u16 / (c as u16): the warning goes away and the value does
not depend on the rule. Tracked in
issue #150.
The width of a sum, difference or product with a wider arithmetic
operand will change. +, - and * are done at the width both
operands share, plus their own carry: a * b - a (all i32) is computed
at 33 bits, and the product, up to 64 bits wide, is cut to 33 bits before
the subtraction. With a = b = 2²⁰ the result is -2²⁰ instead of
2⁴⁰ - 2²⁰. The rule changes in v0.2.0. Until then Volt warns
(W2016) wherever the cut can change the value you read; a result
assigned to a declared width keeps that many bits anyway and gets no
warning. Put the intermediate result in a let with an explicit width,
as in let d : i64 = a * b - a: the warning goes away and the value does
not depend on the rule. A product of two i64 or u64 values has no
wider integer type yet, so before v0.2.0 there is no way around the cut.
Tracked in issue #266.
Combinational loops are not detected. volt check and volt build
accept wires that feed each other (a = b + x and b = a), a comb
block that reads the signal it assigns, and a loop through an output port
or a submodule instance. volt build writes the looping SystemVerilog
without a warning. When volt test or volt run builds such a design,
Verilator stops with %Warning-UNOPTFLAT ... Circular combinational logic followed by an example path around the loop, and the command
fails: that message is the loop in your design, not a Verilator problem.
Break it by removing one dependency on the path, or by registering one
of its signals in an on block. A
register cannot close a loop this way: assigning it with = outside an
on block is E0019. Roadmap:
Combinational loop check.
The handshake check does not look inside an extern module with a
clock. On a Handshake<T> output, valid must not be computed from
the same port’s ready without a register in between: if each side
waits for the other, no transfer ever finishes. Volt reports this as
E4007 when the path runs through assignments, lets, comb blocks,
if and match conditions, function calls, submodules, extern
modules without a clock and the built-in modules whose outputs follow
their inputs in the same cycle (EdgeDetect, RoundRobinArbiter,
PriorityArbiter). An extern module with a clock is not looked into:
when ready goes into such a module and valid comes out of it through
a path inside it, the design compiles without an error. Volt cannot tell
that path from a registered one, such as the empty flag of a FIFO,
which is the common and safe case. Register the value that comes back
from the module, or compute valid in the module that owns the port.
Tracked in issue #196.
Clock and reset domains
CDC bridges are sync(), sync3() and the built-in dual-clock
components (AsyncFifo, HandshakeSync, PulseSync,
AsyncDualPortRam). A synchronizer you write yourself is not recognized
as a bridge: the crossing into it is an E3001 error. Wrap a
hand-written or vendor synchronizer as an extern module with a clock
domain on each port. A multi-bit sync() is a warning (W3003), not an
error; use AsyncFifo or HandshakeSync for data.
A submodule’s dependencies are tracked per port, not per bit. For
each output port of a module, Volt records which input ports it depends
on without a register in between. An output whose bit 0 follows a and
whose bit 1 follows b counts as depending on both. Through a module
without a clock, a from one clock domain and b from another then
make that output an E3001 error, although each bit stays in its own
domain; through a submodule on a handshake path, the same output can
give an E4007 that the bits do not deserve. Split such an output into
two ports. An extern module without a clock is assumed to connect each
output to every input, because its body is not visible: give its ports
clock domain annotations when its paths belong to different domains.
A handshake path through an extern module without a clock is
assumed. Volt cannot see inside such a module, so it assumes that each
output depends on every input. When ready goes into it and valid
comes out of it, E4007 is reported even if the real module has no path
from that input to that output; the error’s note says that the path
rests on this assumption. @no_protocol_check does not change this: it
turns off the automatic protocol contracts of the port, not the check.
Decide valid from a register, as E4007’s help shows (reg valid_r ...; on clk { ... }; tx.valid = valid_r): that cuts the path whatever
the module does. A way to declare which outputs of an extern module
depend on which inputs is planned for v0.2.0.
Reset checks cover reset release, not reset ordering. Volt reports an
asynchronous reset shared by several clock domains or synchronized twice
(E3003), but it does not check the order in which resets are released,
and conditional resets are not modelled. extern modules carry no reset
contract. The domain keys reset_cycles and reset_sequence are
reserved for this: writing one is E0003 (“not supported yet”). Keep
the reset length and order in your reset generator.
An extern gets the raw reset, not the synchronized one. For a raw
reset port (in rst : reset(...)) Volt puts a release synchronizer in
front of the module’s own registers. An extern instance connected to
the same port gets the port itself, so its flip-flops leave reset on a
different cycle than the registers beside it, and their release is not
aligned to the clock unless the SystemVerilog module synchronizes it.
Volt warns about this (W3011) and changes nothing in the output; there
is no way yet to hand the synchronized copy to an extern. Tracked in
issue #93.
No crossing report. Volt knows every crossing, but it does not list
them in a report. With volt build --emit=sdc (or xdc), the
constraint file has a comment line for each crossing with its kind and
its source and destination clocks. Roadmap:
CDC crossing report.
No power domains. The @Domain annotation covers clock, reset and
trust level; power domains, isolation checks and UPF output do not exist.
The power keys of a domain (voltage, always_on, retention,
isolation) are reserved words: volt check rejects them with E0003,
so a design cannot declare a power domain at all. The power-domain codes
E3006, E3007 and E3008 are defined and volt explain describes the
planned checks, but the compiler never reports them: nothing checks
isolation, power-up order or retention. Roadmap:
Power domains and UPF.
Simulation and tests
No built-in simulator. volt test and volt run need Verilator. When
Verilator is not installed and Docker is running, Volt runs it in a
pinned container image by itself; volt doctor shows which way each
command will run.
Verilator runs with its DFG optimizer turned off. volt test and
volt run pass -fno-dfg to every Verilator build, locally and in
Docker. With that optimizer on, Verilator 5.052 prints wrong values for
some correct SystemVerilog
(#148). On the example
designs the option changed the time of volt test by less than the
difference between two runs. If you run Verilator on the generated
SystemVerilog yourself, add -fno-dfg too.
Every clock runs at the same rate in simulation. volt test and
volt run give each clock port of the design one rising edge per cycle,
all at the same moment. A design with several clocks cannot be simulated
with clocks of different speeds or with a phase shift between them, so
a test checks the order and the latency of a crossing, not its timing.
The crossing itself is checked by the compiler (E3001). An example is
in Two clocks and CDC.
Test values are at most 64 bits wide. The test language cannot write
to a port wider than 64 bits or compare a wider value. A module with an
input wider than 64 bits cannot be tested directly: volt test stops
with a C++ error from the Verilator build (VlWide), also when the test
does not use that input
(issue #224).
Workaround: test the design through a small wrapper module whose ports
are 64 bits or narrower, for example Wide { key: lo as uint<128> as bits<128> }
with in lo : u64. volt run does drive and print wide ports.
Roadmap:
Port values wider than 64 bits in tests.
The test language has no if or match expressions, and it cannot
call a design’s functions (E8505).
No machine-readable test results. volt test and volt run write
their report for people; they have no --format=json option yet, unlike
volt check, volt build and volt verify. In CI, use the exit code
(volt test exits with 5 when a test fails) and keep the text report as
a log. Roadmap:
Machine-readable test results.
Generated drivers are not simulated. The C and Rust drivers generated
from an @mmio register map are not run against the RTL. volt check-regmap checks that a driver matches the register map. Roadmap:
Generated drivers in simulation.
Formal verification
volt verify needs SymbiYosys, Yosys and an SMT solver. They run on
Linux; on Windows use WSL, or let Volt run them in Docker.
Properties look back with prev(), nothing more. There are no
sequences (##) and no liveness properties; the proof is bounded
(--depth).
No modular proofs. Each module is verified with the logic of its
submodules included; a verified submodule is not replaced by its
contracts. A submodule’s requires and assume are checked as
obligations of the module that instantiates it. Large hierarchies take
longer to prove. Roadmap:
Assume-guarantee verification.
Contracts need a clock port. Properties are checked on a clock edge,
so volt verify stops with E5005 on a contract in a module without a
clock port. Give the module a clock port, or state the property in the
clocked module that instantiates it.
Array literals in contracts are not supported yet. A contract that
compares with an array literal (r == [prev(a), prev(b)]) is passed to
the tools as an assignment pattern, and most tools reject it: volt verify stops with a Yosys syntax error (unexpected OP_CAST) for every
form; volt test and a separate .sva file fail in Verilator when the
literal is compared with another literal or with an array port, and a
separate .sva file comparing an array register with a literal that
uses prev() makes Verilator report an internal fault. volt test
does compile the comparison of an array register with a literal. Volt
does not report the failing forms itself yet. Workaround: compare element by element
(r[0] == prev(a) && r[1] == prev(b)). Roadmap:
Array literals in contracts.
Contradictory assumptions are not detected. If the requires and
assume contracts of the module under proof cannot hold together, every
assertion passes without proving anything; the solver can also hold
reset for the whole run. Check that a cover of the behaviour you care
about is reached with --mode cover. Roadmap:
Vacuity check.
A submodule’s reset assumption stays an assumption in its parent’s proof. Each module with a reset assumes that reset is asserted when the proof starts, also when it is an instance in a parent’s proof. When the parent drives the submodule’s reset from its own logic or from another reset domain, this assumption constrains the parent: it can hide a failure, or contradict the parent’s reset so that every assertion passes without proving anything. Designs whose submodules use the parent’s reset are not affected. Roadmap: Submodule reset assumptions.
Information flow is checked by types, not proved formally. E3009
catches secret data that reaches a public output at compile time; no
formal property is generated for it.
Generated output
Most of the generated SystemVerilog carries no Volt line numbers.
Each file names its source file, and contract assertions and expanded
function calls carry file:line comments. Other statements do not, and
no command maps a SystemVerilog line back to Volt. Signal names follow
the Volt names, so searching for the name is the workaround. Roadmap:
Source mapping.
No parameterized SystemVerilog modules. A generic module becomes
SystemVerilog when it is instantiated: Fir<8> { ... } generates the
module Fir_8, with the parameter replaced by its value. A generic module
that nothing in the file instantiates generates no SystemVerilog file, and
Volt warns about it (W1006). Writing it as a parameterized module
(module Fir #(parameter N)) is a proposal for v0.2.0, tracked in
issue #171.
Register maps use AXI4-Lite with 32-bit registers, and reset values
are 0. Register documentation is Markdown (--emit=regmap-md); there is
no SVD, IP-XACT or UVM output.
Constraints, not projects. --emit=sdc,xdc writes timing constraints.
There are no Vivado or Quartus project files and no pin constraints.
Roadmap:
FPGA project files.
No diagrams and no project documentation. Volt does not draw state machines or generate documentation for a whole project. Roadmap: FSM state diagrams, Project documentation.
Editor
Some language server features see one file. Diagnostics, inlay hints
and quick fixes analyze every file a design loads with use. Hover,
completion, go to definition and the symbol outline look at the open
file: go to definition does not jump into another file. Roadmap:
Multi-file language server features.
The VS Code extension is a .vsix file from the release page. It is
not on the Visual Studio Marketplace or Open VSX, it needs volt on
PATH (or the volt.serverPath setting), and it has no “Run test”
action. Roadmap:
VS Code extension.
Projects and installation
No package dependencies. use loads files inside the project.
Volt.toml has no dependency section and there is no lock file; copy
shared files into the project. Roadmap:
Package dependencies.
No package managers. Install Volt with the install script or from source, as Install Volt shows; winget, Scoop and Homebrew packages do not exist. Roadmap: Package managers.
No browser playground. Volt runs on your machine. Roadmap: Browser playground.
The design decisions are in Turkish. The book, the language
specification and the diagnostics are in English (diagnostics also in
Turkish, --lang=tr); the ADRs are not translated. Roadmap:
English summary of the design decisions.