Skip to content

Volt 0.1.2

Latest

Choose a tag to compare

@github-actions github-actions released this 13 Nov 09:38
· 41 commits to main since this release
56e9d97

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 } and Inst { 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 a ready-to-valid path 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 as 128'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 a bits<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 const expression 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, and volt build
      stopped with an E0003 that did not say why. The literal -2¹²⁷ in a
      const expression is no longer E2022; a constant that uses it still
      gets E0003 where 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
      i64 operands, 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 const now gets
    E2022, keep the literals of the constant expression below 2¹²⁷.

  • A negative literal must fit its type
    (#213). -<literal> is
    checked like a literal without a sign. 0.1.1 wrote b : i8 = -129 as
    +127, compiled i < -500 (i : i8) as i < 12, a reset value
    reg r : i8 = -200 as +56, i + -300 as i - 44, a : u8 = -1 as
    255, and a match arm -5 => on an i3 as 3. These are now E2010:
    "literal expression evaluates to -129, which does not fit in type i8
    (-128..=127)". -2¹²⁷ does not fit i64: 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 == -1 with u64 operands (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 now E2010 ("generic argument … does not fit in the parameter
    K : u64 of G"), for uN, iN, uint<W> and sint<W> parameters,
    where W is a literal or an earlier const parameter
    (<const W: u32, const K: uint<W>> with G<4, 16> is E2010).
    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)
    got E5012, and stage(+0x1) or an offset larger than i64 stopped 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>
    and 300 as u8 keep the low bits of the literal (8'hFF, 8'h2C), as
    in 0.1.1, and now get W2010; see New warnings. A
    parenthesized negative literal can now be cast: (-128) as i8 is
    −128, (-1) as u8 is 255 with W2010 (0.1.1 rejected both with
    E2005). Without parentheses, -1 as u8 means -(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. With module M_1<const C: u32>,
    let q = M_1 { x: x } compiled in 0.1.1: volt build exited with 0 and
    wrote a Top.sv that instantiates a module M_1 that was never
    generated, with a misleading W1006 ("M_1 is never instantiated").
    If another instance built the same name (M<1> builds M_1), the
    instance was silently bound to that body and computed x + 1 instead
    of x ^ C. It is now E2003: "'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. With module Foo and module foo, or module m_8
    next to the M_8 that M<8> builds, 0.1.1 wrote one formal/foo.sva
    on every system, so the contracts of one module were missing from
    --emit sva; on Windows and macOS rtl/Foo.sv, constraints/Foo.sdc
    and constraints/Foo.xdc were 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> and M_1<8> are both
    M_1_8. 0.1.1 wrote M_1_8.sv once, with the body of M, and bound
    the second instance to it too: M_1<8> computed x + 1 instead of
    x ^ 8. It is now E1003: "'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 as W0010 or W0020 hid an error one or two tokens later, and the
    broken source compiled with exit code 0. Some of what this lost:

    • the extra ) in r = a & b | c ) got no E0001, and the
      invariant after it was missing from the generated .sva;
    • an invariant cnt < 200 without its colon, after a line with
      W0010, disappeared;
    • a warning on the last statement of a file hid every error of an
      @mmio module, and the invalid registers were missing from the RTL
      and the drivers; on the last statement of a pipeline it hid the
      E5013 of an invalid stall, and no stall logic was generated;
    • frequency = 100mhz in a domain (the correct form is 100.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 @mmio module 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 field shorthand goes through every check
    (#204). S { x } and
    Inst { x } are now checked exactly like S { x: x } and
    Inst { x: x }. 0.1.1 skipped the type, clock domain, trust, handshake
    and timing checks for a field written in the short form:
    o = S { a } with a 16-bit a and an 8-bit field compiled, and
    let w = Flag { fast_flag } followed by slow_flag = w.fast_flag
    crossed clock domains without a synchronizer. These designs now get the
    error the long form gets: E2001, E2002, E2003 (type and width),
    E3001 (clock domain), E3009 (trust), E4007 (handshake), E5010
    (timing).
    What to do: apply the fix the error suggests (sync(),
    declassify(), an explicit cast, a registered valid). The shorthand
    itself does not change.

Clock domains through submodules

The checks below now follow a value through a submodule instance:
each instance's outputs carry the clock domains of the inputs they
depend on (#189,
#193).

  • A crossing through a module without a clock is E3001
    (#189). In 0.1.1,
    let p = Pass { a: fast_flag }; slow_flag = p.y, with a clockless
    Pass whose y = a, compiled and generated an assign without a
    synchronizer. The error now says why: "'p.y' carries @fast: 'Pass' has
    no clock, so its output 'y' carries the domain of the inputs it depends
    on ('a')". A clockless module that joins inputs of two domains in one
    output gets E3001 at the instance, even when the output is not read.
    What to do: name the output and synchronize it, as the help shows:
    let p_y_raw = p.y and sync(p_y_raw, slow_clk).
  • A clockless extern module connects every output to every input.
    This is the one rule change of this release. The body of an extern module is not visible, so each output without a domain annotation is
    taken to depend on every input. 0.1.1 treated its ports as having no
    domain at all. As a result, Bank { a1: fast_in, a2: slow_in } is now
    E3001: the two domains meet in the same output, even if the real
    module keeps them apart.
    What to do: annotate the ports with their domains (in a1 : bool @Fast,
    out y1 : bool @Fast). For an annotated output Volt trusts the
    annotation; the value bound to an annotated input is checked.
  • A value of another domain reaching an annotated output of a
    clockless module is E3001

    (#189). With
    out y : bool @Fast and y = a in a clockless P, 0.1.1 compiled
    P { a: slow_flag } and carried a @Slow value to the @Fast side
    without a synchronizer. The order of statements does not matter: an
    unannotated wire bound to the input and driven from another domain
    after the instance is caught too.
    What to do: synchronize the input into the output's domain before
    the instance; the help shows how.
  • A path from ready to valid through a submodule is E4007
    (#193), through a
    submodule instance, a clockless extern module and the built-in
    EdgeDetect, RoundRobinArbiter and PriorityArbiter. The note of the
    error writes out the path (tx.valid <- g.y (AndGate: y <- b) <- tx_ready). A clocked extern module is not looked into
    (#196). The worst-case
    reading of a clockless extern module can show a path the real module
    does not have; the note says so. @no_protocol_check does not turn off
    E4007, and this release has no way to declare that such a path does
    not exist; explicit dependency declarations are planned for 0.2.0.
    What to do: decide valid in a register of the producer, as the help
    shows (reg valid_r : bool = false; on clk { ... }; tx.valid = valid_r).
  • The index of an assignment target is an operand: after
    y[sel] = d or y[sel +: 2] = d, y depends on sel as well as on
    d. A clockless submodule's output driven this way carries the domain
    of the index too (E3001, as above). A ready read in a target index
    alone, as in vv[tx.ready as u1] = valid_r; tx.valid = vv[1], now gets
    E4007; 0.1.1 missed it.
    What to do: as above.

None of the designs in the examples, the book and the tests gets a new
diagnostic from these checks.

Arithmetic

  • New warning W2016 for an operand of +, - or * that is cut
    before the operation (#266).
    It rejects nothing and the generated SystemVerilog does not change; the
    value of these operations changes in 0.2.0. See
    New warnings and Known issues.
    What to do: put the intermediate result in a let with an explicit
    width. A build that treats warnings as errors may now fail.

Fixed

Each of these produced a wrong result without a diagnostic in 0.1.1,
unless it says otherwise. The input, the old output and the new one are
under Behavior changes.

Literals

  • Integer literals of 2¹²⁷ and above were written as 2¹²⁷ - 1
    (#207).
  • A negative literal that does not fit its type was written as another
    value (#213).
  • Literal expressions in contexts of 127 bits and more were not
    range-checked (#272).
  • A const generic argument too wide for its parameter was accepted
    (#262).
  • A non-decimal pipeline stage offset was misread, or stopped a debug
    build of the compiler
    (#263).

Generic modules and module names

  • Two generic modules that build the same name shared one body
    (#205).
  • A generic instance without arguments was accepted
    (#249).
  • Module names that differ in letter case alone overwrote each other's
    files (#250).

Diagnostics and checks

  • A warning swallowed the next error
    (#206).
  • The field shorthand skipped the checks
    (#204).
  • A clock-domain crossing through a clockless submodule got no E3001
    (#189).
  • E4007 did not follow a ready-to-valid path through a submodule
    (#193).

New warnings

Both warnings reject nothing and leave the generated SystemVerilog as it
was; they make a cut visible that 0.1.1 made without a word.

  • W2016: an operand of +, - or * is an arithmetic value wider
    than the width at which the operation is made, so it is cut before the
    operation, and the cut can change the value. In
    p = a * b - a == -1048576 with i32 operands, a * b (64 bits) is cut to 33 bits: "this operand of '-' is
    cut to 33 bits before the operation (its natural width is 64); the rule
    changes in v0.2.0 (#266)". The rule for the width of these operations
    changes in 0.2.0 (#266),
    and the warning marks every place whose value can change then. The help
    line suggests a let with an explicit width:
    let d : i64 = a * b - a. With i64 or u64 operands no integer type
    is wide enough yet, and the help says so. No warning: a result assigned
    to a declared width (the accumulator acc <= acc + a * b), a result
    that fits the operation's width (the indices of a module-level for),
    and a result read by a division with W2015 or by a narrowing as with
    W2010 (that warning is the one shown there). None of the designs in
    the examples, the tests and the book gets W2016.
  • W2010 on a literal cast: a literal without a type suffix that
    does not fit the target of its as keeps the target's low bits:
    "the literal 300 does not fit in u8; the cast keeps its low 8 bits
    (0x2C)". 0.1.1 cut it the same way without a warning. Unlike W2016,
    this warning does not mark a value that changes in 0.2.0: it marks a
    value that is not the literal you wrote. Write the value that fits, or
    use a wider target. A literal that fits gets no warning, as in
    0x8000_0000_0000_0000_0000_0000_0000_0001 as bits<128>.

W2015 (since 0.1.1) still marks a division whose value can change in
0.2.0 (#150).

Known issues

These bugs are open. Each one is planned for a later release; where a
workaround exists, it is given.

Security

  • volt build follows links out of the project
    (#221): 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 (git keeps symbolic links), so
    building it can overwrite a file anywhere you can write, with a name and
    part of the content chosen by the repository. 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.

Arithmetic widths

  • A wider arithmetic operand is cut before the operation; Volt warns
    (#266): +, - and *
    are done at the width both operands share plus their own carry. In an
    expression such as a * b - a == -1048576 with i32 operands, the
    subtraction is computed at 33 bits (33'(a) * 33'(b) - 33'(a)), so the
    64-bit product is cut to 33 bits before the subtraction and the
    comparison can give the wrong result (at a = b = 2²⁰ it is true).
    The rule does not change in 0.1.2 and the generated SystemVerilog is the same, but the compiler now
    warns at every such place: warning[W2016]: this operand of '-' is cut to 33 bits before the operation (its natural width is 64); the rule changes in v0.2.0 (#266). A result assigned to a declared width keeps
    that many bits anyway and gets no warning (for example the accumulator
    acc <= acc + a * b). The fix the warning suggests: put the
    intermediate result in a let of explicit width and use that,
    let d : i64 = a * b - a and p = d == -1048576. With i64 or u64
    operands the product is wider than any integer type you can write in
    0.1.2; the warning says so, and there is no way around the cut until
    0.2.0, which computes the operand at its natural width.
  • Division with a wider arithmetic operand
    (#150): the generated
    SystemVerilog can compute / or % at a different width than the type
    checker. With u8 operands and a u8 result, o = a * b / c cuts the
    16-bit product to 8 bits before the division. Warning W2015 marks
    every such place. Write the width on both operands and keep the bits
    you need: o = ((a * b) as u16 / (c as u16))[7:0] as u8 divides at
    16 bits and gets no warning.
  • match is computed at a narrower width than the type checker uses
    (#215): with u8
    operands, let m = match sel { 0 => a + b, _ => a - b } is an 8-bit
    signal in the 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 arms as if/else, or put the subject in a let with an explicit
    width (let s : u9 = a + b, then match s).

Constants and match

  • A const that does not fit its type is accepted
    (#214): with
    const A : u8 = 255 and const B : u8 = A + 1, compile time sees 256
    (a bits<B> port is 256 bits wide, B > 255 is true) and the hardware
    sees 0 (r = B gives 8'h0). Make sure every constant computed from
    other constants fits its declared type.
  • In a statement match, arms after the wildcard are emitted and win
    (#216):
    match s { 0 => { … } _ => { stmt = 7 } 1 => { stmt = 9 } } in a
    comb block gives 9 for s = 1, while the same match as an
    expression gives 7. Write the wildcard arm last.

Combinational logic

  • An incomplete assignment in a comb block infers a latch, and a
    wire that is never driven gets no error

    (#230):
    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: LATCH). A wire w : u8 that is read in y = w + a
    and never driven compiles too (Verilator: 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.
  • A port bound twice in one instance takes the last binding
    (#229):
    Child { x: 1, x: a } compiles without a diagnostic and connects x to
    a. Bind each port once.

Clock domains and resets

  • The clock outputs of an extern module have no domain
    (#208): with a PLL or a
    clock buffer declared as extern module with out c0 : clock, nothing
    clocked by c0 is checked: crossings between the input clock and each
    output clock get no E3001, and a reset shared by them gets no
    warning. Synchronize every value between these clocks by hand with
    sync() or an AsyncFifo; the compiler does not check it.
  • A register's reset value can be a signal, and is not checked
    (#209):
    reg r : u8 = a loads a at reset with no clock-domain check (E3001)
    and no trust check (E3009). Use a constant reset value, and load the
    signal in the on block.
  • A clock port declared through a type alias is not treated as a clock
    everywhere
    (#234): with
    type Clk = clock, an asynchronous reset shared by two clock domains
    gets no E3003, the SDC has no create_clock for the clock (or a
    @timing line on it is E0017), and a test block can drive the clock.
    Write clock for clock ports.

Timing

  • E5010 is missed when values of different delays meet in a comb
    block
    (#217): in an
    @strict_timing module, comb { if x[0] { w = a } else { w = b } }
    with a Delayed<u32, 1> and a Delayed<u32, 2> compiles, while the
    same choice written as let w = if x[0] { a } else { b } gets E5010.
    Write such a choice as a let.
  • The fix that E5010 suggests does not change the hardware
    (#232): the help and
    volt explain E5010 suggest 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: the SystemVerilog is a + b, and the
    two values are still of different ages. Add the register yourself: a
    reg a2 : Delayed<u32, 2> loaded with a2 <= a in the on block, and
    let sum = a2 + b.
  • @false_path and @multicycle are written to the SDC file without a
    check
    (#226,
    #231): the constraint is
    written for any two registers, also for a real one-cycle path
    (set_false_path -from [get_cells {a_r_reg*}] -to [get_cells {y_r_reg*}]),
    and the timing tool then leaves that path untimed. volt explain E6003
    and volt explain E6004 say that Volt accepts these attributes when it
    can prove them, but no proof is made and the two codes are never
    reported. Treat both attributes as your own claim, and check every path
    you mark.
  • @false_path and @multicycle on a port of struct type constrain
    nothing
    (#229): the
    SystemVerilog ports are cfg_a, cfg_b, …, one per field. When Cfg
    is a struct, @false_path in cfg : Cfg writes
    set_false_path -from [get_ports cfg], which matches none of them;
    when Cfg is a struct port, it writes no line at all. Neither case
    reports anything, and @multicycle(2) behaves the same. Declare such
    inputs as plain ports (@false_path in cfg_a : u8 writes
    set_false_path -from [get_ports cfg_a]).
  • A timing constraint can apply to a second register
    (#219): @multicycle,
    @false_path and @timing(max_delay) on a register slow are written
    to the SDC as get_cells {slow_reg*}, which also matches a register
    named slow_reg, so that register gets the relaxed constraint too. Do
    not name a register <name>_reg… next to a constrained register
    <name>.

Trust

  • A secret passes through an unclassified input port of a submodule
    (#210): with
    module Mid { in x : u8 out o : u8 @Pub o = x },
    Mid { x: key } (a @Sec value) compiles and o carries the secret
    to a public output without E3009. Annotate the input ports of
    submodules with their trust domain.
  • The trust annotation of a wire or let is not read
    (#211): 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, a wire w : u8 @Sec takes the
    clock's trust level instead and gets a false E3009. Do not rely on a
    trust annotation on a wire or let; annotate the ports.
  • A register's reset value bypasses the trust check too
    (#209, under
    Clock domains and resets).

Names and visibility

  • A struct let whose flattened field name equals another name
    (#154): with
    let p : S (field x) in a block and a port p_x, a read of p_x
    reads the field of the local in the generated SystemVerilog. Do not
    name a port or signal <let>_<field>; rename the let.
  • A module-level let with the name of a bundle port or of regs
    (#155) is accepted
    without error E1003, and the name then means two different things.
    Give the let a name of its own.
  • An import alias (use a::X as J)
    (#161): an aliased
    constant used as a value is written into the SystemVerilog under its
    alias (assign y = J;, an undeclared name), without a diagnostic; an
    aliased type, function, domain or module is rejected. Import such items
    without as.
  • A test block can read a private constant of another file
    (#162) without error
    E1001. Make the constant pub and import it with use in the test
    file, as the visibility rules require.

SystemVerilog that the tools reject

These designs pass volt check and volt build; the error comes later,
from Verilator or another tool.

  • Reading an input port of an instance
    (#218): with
    let s = Sub { x: a }, p = s.x is written as assign p = s_x;, a name
    that is not declared (Verilator: "Can't find definition of variable:
    's_x'"). Read the value you bound instead (p = a).
  • An array literal assigned to an array wire
    (#135): with
    wire xs : [u8; 2], xs = [x0, x1] is written as
    assign xs = '{x0, x1};, which Verilator rejects. Assign the elements
    one by one: comb { xs[0] = x0 xs[1] = x1 }.
  • A constant index of a wider type than the address
    (#134): with
    const K : u4 = 2, a[K] on a u8 is written as a[4'd2], and
    Verilator stops volt test with WIDTHTRUNC. Give the constant the
    width of the address (const K : u3 = 2 for an 8-bit value).
  • volt test of a module with an input wider than 64 bits
    (#224): the test bench
    does not compile (a C++ error on VlWide<4>), also when the test does
    not use that input. Test the module through a wrapper whose inputs are
    64 bits or narrower, for example Wide { key: lo as uint<128> as bits<128> }
    with in lo : u64.

@mmio

  • Two @mmio modules in one design do not compile, and some @mmio
    arguments are not checked

    (#220): a second @mmio
    module gets E1001 for the AXI bundle names (AxiWriteAddr and four
    more), also when the two modules are in different files. A base address
    that is not a multiple of 4 (base = 0x4000_0002) is accepted, although
    no aligned 32-bit access reaches the registers, and a repeated argument
    takes the last value (base = 0x4000_0002, …, base = 0x5000_0003
    gives #define R_BASE 0x50000003U). A /// comment is copied into the
    generated C header as it is, so a */ in it ends the C comment and the
    rest of the line becomes C code. 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.
  • An @mmio module in a unit that defines an AXI bundle name
    (#244): when the unit
    declares AxiWriteAddr (or another of the five AXI bundle names) itself,
    the generated module does not compile and reports E1001 for names
    such as aw_valid that you did not write. Do not declare these names
    next to an @mmio module.

Valid input that is rejected

These give an error, not a wrong result.

  • Constant evaluation in the parser stops at depth 64
    (#159): 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 gets 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.
  • A generic module that is never instantiated and uses its parameter in
    a type
    (in x : uint<N>)
    (#172) 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> { ... }.
  • A bits<K> value that crosses a pipeline stage boundary
    (#245) is rejected with
    E2003 ("expected 'bits<8>', found 'integer literal'") on a literal the
    compiler generates. Carry the value as uK across the stage, and cast
    it back to bits<K> where it is used.
  • A struct port whose field has a private struct type of its own file
    (#163): with a private
    struct Hdr and pub struct port Bus { out h : Hdr } in other.volt,
    a module that uses Bus gets E1001: undefined name: 'Hdr'. Make Hdr
    pub and import it too (use other::Hdr).
  • declassify() in a module-level for or in a generic module
    (#212) gets a false
    E3009 ("secret data flows to a public output"). Write the assignments
    without the for, one per element (dbg[0] = declassify(key[0] != 0, "presence")), and keep declassify() out of generic modules.
  • A submodule output that depends on public inputs alone is taken as
    secret
    (#195) 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.
  • A source file that begins with a byte order mark
    (#229) is rejected with
    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.
  • frequency = 100mhz in a domain
    (#223) gets W0020
    "unknown domain key: 'mhz'" followed by E0001, which do not say what
    is wrong. Write 100.mhz.

Projects and volt explain

  • A malformed Volt.toml is ignored
    (#222): with a Volt.toml
    that is not valid TOML, volt build compiles and exits with 0, without
    a diagnostic. If a setting of Volt.toml seems to have no effect, check
    the syntax of the file.
  • Some solutions in volt explain do not compile
    (#225,
    #170): the solution of
    volt explain 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. volt explain W0010 says that ==
    binds before &, but Volt reads a & b == c as (a & b) == c and
    gives no W0010. The help of E2001 can suggest a cast that gets a
    second E2001 (o = p16 + d8 with a u9 output). Where an explanation
    and the compiler disagree, follow the compiler.
  • volt explain describes checks that are never made
    (#226): E3004, E3005,
    E6001, E6003, E6004, E7001, E7002, E9001, E9002, W2011,
    W2020 and W2021 are explained as if the compiler reported them; it
    never does. Do not rely on these checks.
  • The project that volt new creates names its module Counter
    (#101), a name of the
    standard library: instantiating it from another module gets E1016.
    Rename the module (for example to MyCounter, and top in
    Volt.toml) before you use it in a larger design.

The full list of limitations, with workarounds:
Known limitations.

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

Running the script again updates an installed Volt to this release.
VOLT_VERSION=0.1.2 installs this release instead of the newest one. In
a new terminal, volt --version prints volt 0.1.2 followed by the
commit in parentheses. The VS Code extension is attached to this release
as volt-hdl-0.1.2.vsix. Verifying a download, installing by hand and
the platform notes are unchanged from 0.1.0: see
Install Volt.

Support

The latest release is the supported one. Fixes go into main and ship
with the next release. Before 1.0, a new last digit (0.1.2) brings fixes
and a new middle digit (0.2.0) may break existing code; a fix for a
silent wrong result may reject input that was accepted before even in a
last-digit release, as in this one. Report bugs in the
issues.

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