Repository navigation
Releases
Volt 0.1.2
Volt 0.1.2 fixes bugs of 0.1.1 that produced wrong SystemVerilog, or
skipped a safety check, without a diagnostic: the design compiled, and
the generated hardware did something other than what the source says.
The bugs fall into five groups:
- wrong constant values: integer literals of 2¹²⁷ and above were
written as 2¹²⁷ - 1, a negative literal that does not fit its type was
written as a different positive number, and a generic argument too
wide for its parameter was passed on unchecked; - wrong module bodies and lost files: a generic instance could be
bound to the body of another generic module, and two modules whose
names differ in letter case alone wrote one file; - lost errors: a warning could swallow the error right after it, so a
source with a syntax error compiled and parts of it (contracts,
registers, stall logic) disappeared; - skipped checks: the field shorthand
S { x }andInst { x }
skipped the type, clock domain, trust, handshake and timing checks; - checks that stopped at submodules: a clock-domain crossing through
a module without a clock, and aready-to-validpath through a
submodule, got no error.
Upgrading is recommended. Most of these fixes reject input that 0.1.1
accepted; in each such case the 0.1.1 output was wrong. One rule changed:
a clockless extern module is now taken to connect every output to
every input (see
Clock domains through submodules).
The release also adds warning W2016, which marks arithmetic whose value
changes in 0.2.0. Read Behavior changes before
upgrading, and the security issue under Known issues before
you build a repository that you did not write.
Behavior changes
Upgrading from 0.1.1: for each item below, the same input gives a
different result in 0.1.2. Where 0.1.1 compiled a design and 0.1.2
reports an error or writes different SystemVerilog, the 0.1.1 output went
against the language specification, with one exception: the new worst-case
reading of a clockless extern module, which can reject a design that
was correct.
Literals
-
Integer literals of 2¹²⁷ and above are written with their value
(#207). 0.1.1 wrote every
literal between 2¹²⁷ and 2¹²⁸ - 1 as128'h7FFF…FFFF: a reset value,
a mask or a comparison such as
a == 0x8000_0000_0000_0000_0000_0000_0000_0001 as bits<128>compared
with the wrong number, also in abits<256>context. A generic argument
of that size became 2¹²⁷ - 1 in the body: with
module G<const K: uint<128>>, the instance
G<0x8000_0000_0000_0000_0000_0000_0000_0001>(2¹²⁷ + 1) saw 2¹²⁷ - 1.
Literals below 2¹²⁷ are written as before.- Inside a
constexpression a literal of 2¹²⁷ or more is now error
E2022. 0.1.1 read it as another value there:
const K : u64 = 0xFFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF / 0x1_0000_0000_0000_0001
(2¹²⁸ - 1 divided by 2⁶⁴ + 1) was 0 at compile time, andvolt build
stopped with anE0003that did not say why. The literal -2¹²⁷ in a
constexpression is no longerE2022; a constant that uses it still
getsE0003where it is written into the SystemVerilog. - A literal in a signed context wider than 128 bits, as in
-(a * b) > -0x8000_0000_0000_0000_0000_0000_0000_0000(-2¹²⁷) with
i64operands, is written correctly. 0.1.1 wrote it as -(2¹²⁷ - 1),
and a debug build of the compiler stopped on it.
What to do: nothing for designs that compile. If a
constnow gets
E2022, keep the literals of the constant expression below 2¹²⁷. - Inside a
-
A negative literal must fit its type
(#213).-<literal>is
checked like a literal without a sign. 0.1.1 wroteb : i8 = -129as
+127, compiledi < -500(i : i8) asi < 12, a reset value
reg r : i8 = -200as +56,i + -300asi - 44,a : u8 = -1as
255, and amatcharm-5 =>on ani3as3. These are nowE2010:
"literal expression evaluates to -129, which does not fit in type i8
(-128..=127)". -2¹²⁷ does not fiti64:E2010.
What to do: widen the type or change the literal; the error says the
range. Negative literals that fit compile as before. -
Literal expressions are range-checked in contexts of 127 bits and
more (#272). 0.1.1 did
not check them at these widths:a * b == -1withu64operands (a
128-bit context) compiled and compared with 2¹²⁸ - 1. It is now
E2010.
What to do: write a value the type can hold. -
A const generic argument must fit its parameter's type
(#262). With
module G<const K: u64>, 0.1.1 accepted
G<0xFFFF_FFFF_FFFF_FFFF_FFFF>and the hardware saw an 80-bit value.
This is nowE2010("generic argument … does not fit in the parameter
K : u64 of G"), foruN,iN,uint<W>andsint<W>parameters,
whereWis a literal or an earlier const parameter
(<const W: u32, const K: uint<W>>withG<4, 16>isE2010).
What to do: pass a value that fits, or declare the parameter with a
wider type. -
A pipeline stage offset is read like any integer literal
(#263):stage(-0x1)is
stage(-1). 0.1.1 read decimal offsets and nothing else:stage(-0x1)
gotE5012, andstage(+0x1)or an offset larger thani64stopped a
debug build of the compiler. An offset that lands on no stage is
E5012.
What to do: nothing; a hexadecimal or binary offset now works. -
A literal cast that does not fit its target warns
(#207).0x1FF as bits<8>
and300 as u8keep the low bits of the literal (8'hFF,8'h2C), as
in 0.1.1, and now getW2010; see New warnings. A
parenthesized negative literal can now be cast:(-128) as i8is
−128,(-1) as u8is 255 withW2010(0.1.1 rejected both with
E2005). Without parentheses,-1 as u8means-(1 as u8)(E2002).
What to do: write the value that fits (the warning says it), or use a
wider target. A build that treats warnings as errors may now fail.
Generic modules and module names
- A generic module instantiated without its generic arguments is an
error (#249). Generic
parameters have no default value. Withmodule M_1<const C: u32>,
let q = M_1 { x: x }compiled in 0.1.1:volt buildexited with 0 and
wrote aTop.svthat instantiates a moduleM_1that was never
generated, with a misleadingW1006("M_1is never instantiated").
If another instance built the same name (M<1>buildsM_1), the
instance was silently bound to that body and computedx + 1instead
ofx ^ C. It is nowE2003: "'M_1' expects 1 generic argument(s),
got 0".
What to do: write the arguments,M_1<8> { x: x }. Instances of
modules that are not generic do not change. - Two modules whose names differ in letter case alone are an error
(#250),E1003:
module names 'Foo' and 'foo' differ only in letter case. Each module
name becomes file names. Withmodule Fooandmodule foo, ormodule m_8
next to theM_8thatM<8>builds, 0.1.1 wrote oneformal/foo.sva
on every system, so the contracts of one module were missing from
--emit sva; on Windows and macOSrtl/Foo.sv,constraints/Foo.sdc
andconstraints/Foo.xdcwere one file too, and the SystemVerilog of
one module was lost. The rule covers user modules, generic modules that
are never instantiated and the names generic instances build.
What to do: rename one of the modules. Volt does not rename generated
names itself. - Two generic modules that build the same module name are an error
(#205). A generic instance
is named<module>_<argument values>:M<1, 8>andM_1<8>are both
M_1_8. 0.1.1 wroteM_1_8.svonce, with the body ofM, and bound
the second instance to it too:M_1<8>computedx + 1instead of
x ^ 8. It is nowE1003: "'M_1_8' is the generated module name of
both M<1, 8> and M_1<8>".
What to do: rename one of the two generic modules.
Diagnostics
-
A warning no longer swallows the error that follows it
(#206). In 0.1.1 a warning
such asW0010orW0020hid an error one or two tokens later, and the
broken source compiled with exit code 0. Some of what this lost:- the extra
)inr = a & b | c )got noE0001, and the
invariantafter it was missing from the generated.sva; - an
invariant cnt < 200without its colon, after a line with
W0010, disappeared; - a warning on the last statement of a file hid every error of an
@mmiomodule, and the invalid registers were missing from the RTL
and the drivers; on the last statement of a pipeline it hid the
E5013of an invalidstall, and no stall logic was generated; frequency = 100mhzin a domain (the correct form is100.mhz) got
W0020"unknown domain key: 'mhz'", and the clock was constrained
as 100 Hz (create_clock -period 10000000.000)
(#223).
These sources are now rejected with the error's own code (
E0001,
E0015,E5013, …). Several errors in one@mmiomodule or one
pipeline are now all reported; 0.1.1 reported the earliest one.
What to do: fix the reported error. Sources without errors give the
same SystemVerilog. - the extra
-
The field shorthand goes through every check
(#204).S { x }and
Inst { x }are now checked exactly likeS { x: x }and
Inst { x: x }. 0.1.1 skipped the type, clock do...
Volt 0.1.1
Volt 0.1.1 fixes bugs of 0.1.0 that produced wrong SystemVerilog without
a diagnostic: the design compiled, and the generated hardware did
something other than what the source says. Upgrading is recommended.
This is a bug-fix release. No rule that decides whether a design is
accepted, or what it computes, changed; the specification gained one
warning (a generic parameter that hides a top-level item now gets
W1002). Some input that 0.1.0 accepted is now rejected, and some input
now gives different SystemVerilog. In all but one of these cases the
0.1.0 result went against the language specification; the exception is a
new limit on long enum constant chains (see Constants).
They are listed under Behavior changes; read that
section before upgrading.
Behavior changes
Upgrading from 0.1.0: for each item below, the same input gives a
different result in 0.1.1. Where 0.1.0 compiled a design and 0.1.1
reports an error or writes different SystemVerilog, the 0.1.0 output went
against the specification: in most cases it computed a wrong value; in
the visibility cases (#139)
it read a name that the file is not allowed to see. The one exception is
under Constants.
Names in inlined functions, generic modules and loops
-
A name in an inlined function body is resolved where the function is
declared (#128). A
constant in afnbody no longer takes the value of a loop variable
with the same name around the call. Withconst I = 1and
fn pick(x: [u8; 4]) -> u8 { x[I] }, the call
for I in 0..4 { ys[I] = pick(xs) }gaveys[k] = xs[k]; it now gives
ys[k] = xs[1]. The same holds for a constant in a part-select start,
a range bound, a nested call and amatchpattern in the body, and for
a constant's value (const J = I + 1) read inside a loop overI. A
blockletor a loop variable now also hides an outer name with the
same spelling in a computed index and in a value. A type width
(uint<W>) or a constant array (T[i]) in the body is no longer
rejected withE2005because the caller has a nameWori.
What to do: a design that reuses a name of a function body or of a
constant for a loop variable, a blockletor a port may get different
SystemVerilog; warningW1002points at these places. -
An inner declaration hides a generic parameter or a module-level
forvariable (#130).
A blocklet, aforinsidecombor a nestedfor, or aletin a
loop body with the name of a generic parameter or a loop variable is no
longer replaced with the parameter's value. InG<3>,
comb { let N = s y = N }gavey = 3; it now givesy = s. In
for i in 0..1 { let i = s y = i }, 0.1.0 wrotey = 0; 0.1.1 writes
y = s. Two inputs that were rejected now compile:
comb { for N in 0..2 { ys[N] = N } }in a module with a genericN
(it wasE2006), and the shorthand connectionP { i }(it was
E1001). -
New
W1002warnings for a name that hides another
(#130): a module-level
forvariable that hides a top-level item, a port, a module signal or a
generic parameter; aletin a loop body that hides the loop variable,
a top-level item or aletof the enclosing body; a generic parameter
of an instantiated generic module that hides a top-level item; a block
letor acombloop variable that hides a generic parameter.
What to do: rename the inner name. A build that treats warnings as
errors may now fail. -
Some inputs that 0.1.0 accepted are now errors
(#130); in each of them
the 0.1.0 output used the hidden value (the literal of the generic
parameter or of the loop, or the top-level constant):- a port or a module
letwith the name of a generic parameter:
E1003; - a module-level loop variable in a pattern, and a block
letthat
hides a generic parameter used in a pattern:E1015; - a block
letthat hides a generic parameter used in a type width
(uint<N>):E2005; - a
letof a loop body used as a generic argument (W<i>):E2008;
used in a type width:E2021; - a port or a module signal that hides a top-level constant, used in a
module-levelforbound:E2021.
What to do: give the inner name a name of its own; the error points
at it. - a port or a module
-
A block
letor a loop variable hides a bundle port, aninout
port, the@mmiohandleregsand a pipeline stage value
(#136,
#137,
#138). A use of the name
now reads the local. Afterlet tx : Flags = ...,tx.firedread the
port'stx_valid && tx_ready; it now reads the field of the local. The
same holds fordq.releasedafterlet dq : St = ...(it read
!dq_oe) andregs.control.enableafterlet regs : Regs = ...(it
read the register map). In a pipeline stage,
for a in 0..2 { r[a] <= x }wroter[a_a_r]twice; it now writes
r[0]andr[1].- The index and the length of a bundle array are evaluated where they
are used: a port, a modulelet, a blockletor a loop variable
that hides a top-level constant there is nowE2008(0.1.0 read the
constant and selectedrx[0]). - Inferred contracts: a counter or a state machine whose limit or
written value is a blockletno longer gets an inferred contract.
0.1.0 took theletfor the constant it hides and generated an
invariantthat does not hold (a failure involt test, a
counterexample involt verify) or a cover point for a transition
that does not exist. Amatchon an enum local that hides the state
register (comb { let st : Color = c; match st { ... } }) no longer
removes the cover points of the state machine. - A local
letwith the name of a stage value in the module-level
combof a pipeline compiles; it wasE5012. - New diagnostics: a local that hides a bundle port or
regsgets
W1002; a field access on au8local that hides a bundle port is
E2003;dq.drive(v)on a local that hides aninoutport is
E0001; a write to a field of a localregsisE4001(it was
E4006).
What to do: a design that reuses the name of a port, of
regs, of a
stage value or of a top-level constant in a block may get different
SystemVerilog and different inferred contracts; the newW1002
warnings andE2008errors point at these places. - The index and the length of a bundle array are evaluated where they
Visibility across files
- A constant or a struct of another file needs
pubandusein every
position (#139). A
constant that is notpubor not imported withuse, read in a
module-levelforbound or in the length or index of a bundle array,
and such a struct used as a bundle type or aHandshakepayload, are
nowE1001. 0.1.0 read them without a word: with a privateK = 1in
another file,y = rx[K].dataselectedrx_1_data. A glob import
(use a::*) does not bring private items. The body of a generic module
is resolved in the file that declares it. A constant or bundle type
imported withuse a::X as Jnow resolves in these positions (it was
E2008,E2021orE4001). A loop variable with the name of a hidden
item of another file no longer getsW1002.
What to do: a newE1001says that the file that uses the name does
not see it. Make the itempubin the file that declares it, and add
use package::Name;to the file that uses it.
Widths
- The untyped
letof an inlined function keeps its flexible width in
acombblock (#132),
as it already did at module level and now also in aforinside a
block, a contract and a register's reset value. With
fn g(a: u8, b: u8, c: u8) -> u9 { let s = a + b; (s | c) + c }and
a = b = c = 255,comb { x = g(a, b, c) }gave 254 and the
module-levely = g(a, b, c)gave 510; both now give 510. Some designs
of the same kind stoppedvolt testwith a Verilator width warning
((s | c) as u16); they now simulate.
What to do: the SystemVerilog of afncalled fromcombwhose
untypedletis used in a narrower operation changes. No source change
is needed.
Literal arithmetic
-
Arithmetic on literals alone is computed at compile time with its
exact value (#144,
#152,
#153): arithmetic whose
operands are all literals, generic parameters or loop variables of a
forinsidecomb. The result is written as one literal. 0.1.0 cut every literal
to the width of its context and left the operation to SystemVerilog:
y : u2 = 7 / 3was written2'h3 / 2'd3(1) and is now2'd2;
x == 7 / 3andx < 5 % 3compared with a wrong value. New errors:E2010when the result does not fit its target:
y : u2 = 5 + 2,const X : u8 = 200 + 100,x < 3 - 1with
x : u1. 0.1.0 wrapped the value without a word. The same for a
combloop variable that does not fit (ys[i] = iwhereigoes
past the range of the target); every combination of nested loops is
checked.E2023for a division or a remainder by zero:7 / 0,
5 % (2 - 2).
What to do: if the build now reports
E2010orE2023, the 0.1.0
SystemVerilog of that line already computed a wrong value. Widen the
target, or fix the constant; the help line of the error says how.
Constants
- A
matchon an enum constant defined through a chain of more than 63
constants (`const A0 : E...
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 with...
