Chisel, Amaranth, Bluespec and HLS

The counter of this module took 11 lines of Python in Amaranth and became 55 lines of Verilog, and the reading lesson’s SystemVerilog testbench printed done: q=2 wraps=1 errors=0 for it, as for the hand-written counter. The alternative hardware languages end where every flow starts: in Verilog.

Here you see how Chisel, Amaranth and Bluespec turn a program into Verilog, how high-level synthesis turns C++ into clock cycles, how to read and lint what they write, and when one of them helps a project.

A program in another language builds the hardware, then writes Verilog

amaranth_counter.py describes the counter as a Python class. Running it prints the Verilog that Amaranth 0.5.10 makes from the class, through Yosys, and Icarus Verilog runs that Verilog under the testbench:

"""The 4-bit counter of this module written in Amaranth 0.5, a hardware language embedded in Python.

Running the file prints the Verilog that Amaranth generates for it, through Yosys. The counter has the ports of
counter.sv: q goes up by one at every rising edge of clk at which en is 1 and wraps from 15 to 0; rst is synchronous
and wins over en; wrap is 1 for the one cycle after q went from 15 to 0.
"""
from amaranth import Module
from amaranth.back import verilog
from amaranth.lib import wiring
from amaranth.lib.wiring import In, Out


class Counter(wiring.Component):
    en: In(1)
    q: Out(4)
    wrap: Out(1)

    def elaborate(self, platform):
        m = Module()
        with m.If(self.en):
            m.d.sync += self.q.eq(self.q + 1)
        m.d.sync += self.wrap.eq(self.en & (self.q == 15))
        return m


if __name__ == "__main__":
    print(verilog.convert(Counter(), name="counter"))

from session import run

# The Amaranth counter becomes Verilog through Yosys, then the reading lesson's SystemVerilog testbench runs it on
# Icarus Verilog. grep counts the lines of the generated file and shows its module line and its registers.
run("""
python amaranth_counter.py > counter_am.v
grep -c "" counter_am.v
grep -E "^module|always @|reg \\[3:0\\] q" counter_am.v
iverilog -g2012 -Wall -o am.vvp tb_counter.sv counter_am.v
vvp -n am.vvp
""", packages=("amaranth",), simulators=("yosys",))

# Python 3.14.8 · amaranth 0.5.10 · Icarus Verilog 13.0 (stable) · Yosys 0.69
$ python amaranth_counter.py > counter_am.v
$ grep -c "" counter_am.v
55
$ grep -E "^module|always @|reg \[3:0\] q" counter_am.v
module counter(clk, rst, q, wrap, en);
  reg [3:0] q = 4'h0;
  always @(posedge clk)
  always @(posedge clk)
  always @* begin
  always @* begin
$ iverilog -g2012 -Wall -o am.vvp tb_counter.sv counter_am.v
$ vvp -n am.vvp
done: q=2 wraps=1 errors=0
tb_counter.sv:29: $finish called at 240 (1s)

An embedded HDLembedded HDL: A hardware description language built as a library of a programming language, its host, such as Chisel in Scala or Amaranth in Python. A program builds the design, and a compiler writes it out as Verilog. is a library of a programming language, its host. The program runs once, builds a description of registers and logic in memory, and a compiler writes it out as Verilog. The host’s loops, functions and classes therefore decide what hardware exists, which is what these languages offer over SystemVerilog’s generate blocks. What they describe is still register-transfer level: the code says what each register takes at each clock edge. Step through the counter’s path:

The languages differ in their host and in the compiler that writes the HDL:

• Amaranth is a Python library for register-transfer modelling, under BSD-2-Clause. It hands the design to Yosys, which wrote the 55 lines above, and it has its own simulator, written in Python.
• Chisel is a hardware design language whose designs are Scala programs, under Apache-2.0. A Chisel program produces FIRRTL, and firtool, from the CIRCT project, writes the Verilog; Chisel manages the firtool version it needs.
• Bluespec describes modules by their methods and by rules, guarded atomic actions that the compiler schedules. Its compiler, BSC, takes two syntaxes, BSV and Bluespec Haskell, and emits standard Verilog.
• SpinalHDL is embedded in Scala too, and its generator writes VHDL or Verilog.
• Veryl is a language of its own, close to SystemVerilog, whose transpiler writes readable SystemVerilog.

High-level synthesis schedules C++ into clock cycles

High-level synthesishigh-level synthesis (HLS): Turning a C or C++ function into RTL with a tool that chooses the clock cycle of every operation and the unit that runs it, then writes a state machine and a datapath in Verilog or VHDL. starts from a C or C++ function instead of registers. The tool decides what RTL would make you decide: in which clock cycle each operation runs, its schedulescheduling (HLS): The step of high-level synthesis that gives each operation of the C or C++ code a clock cycle to start in, within the units available and after the operations whose results it reads., and which unit runs it. For y = a*b + c*d with one pipelined multiplier, the products cannot start together:

The program below makes the same decisions, the way Bambu, an open-source HLS tool, schedules by default: each cycle it starts every operation whose inputs are ready, while a unit of its kind is idle. Change MULTIPLIERS and run it again:

"""What high-level synthesis does with y = a*b + c*d: it gives every operation a clock cycle and a unit to run on.

A multiplier takes 2 cycles and accepts a new pair every cycle (it is pipelined); an adder takes 1. The program lists,
cycle by cycle, which operation each unit starts, with one multiplier and with two, and prints the latency: the
cycles from the first operation starting to y being ready. Change MULTIPLIERS to try other numbers.
"""

MULTIPLIERS = (1, 2)
LATENCY = {"mul": 2, "add": 1}
# The operations, the kind of unit each needs and the operations whose results it reads.
OPS = {
    "a*b": ("mul", []),
    "c*d": ("mul", []),
    "y": ("add", ["a*b", "c*d"]),
}


def schedule(units):
    """List scheduling: each cycle, start every operation whose inputs are ready, while units of its kind are free."""
    done_at = {}
    start = {}
    cycle = 0
    while len(start) < len(OPS):
        free = dict(units)
        for name, (kind, inputs) in OPS.items():
            ready = all(i in done_at and done_at[i] <= cycle for i in inputs)
            if name not in start and ready and free[kind] > 0:
                start[name] = cycle
                done_at[name] = cycle + LATENCY[kind]
                free[kind] -= 1
        cycle += 1
    return start, max(done_at.values())


for count in MULTIPLIERS:
    start, latency = schedule({"mul": count, "add": 1})
    print(f"{count} multiplier(s), 1 adder:")
    for name, cycle in sorted(start.items(), key=lambda item: item[1]):
        print(f"  cycle {cycle}: start {name} on the {OPS[name][0]} unit")
    print(f"  y is ready after {latency} cycles")

1 multiplier(s), 1 adder:
  cycle 0: start a*b on the mul unit
  cycle 1: start c*d on the mul unit
  cycle 3: start y on the add unit
  y is ready after 4 cycles
2 multiplier(s), 1 adder:
  cycle 0: start a*b on the mul unit
  cycle 0: start c*d on the mul unit
  cycle 2: start y on the add unit
  y is ready after 3 cycles

One multiplier gave a latency of 4 cycles and two gave 3: the tool trades units for cycles, a trade that RTL makes you write by hand. HLS fits algorithms on data, such as filters, codecs and transforms, which are easier to state in C++ than as a pipeline. It fits control logic badly, because a protocol fixes the cycle of each action, and the tool picks cycles itself. Its RTL is verified like any other, and AMD’s guide to Vitis HLS has a section on C/RTL co-simulation, which runs the C++ test against the generated design.

Reading and linting generated Verilog, measured on two generators Pro: opens with a Pro, Premium or Ultimate pass

HLS by numbers: latency and initiation interval of a filter Pro: opens with a Pro, Premium or Ultimate pass

Choosing a language for a block, with your answers Pro: opens with a Pro, Premium or Ultimate pass

Practise: write the list scheduler

The exercise is the scheduler of schedule_two.py made general: any operations, any units and any latencies. Its sample tests include a chain that a second multiplier cannot speed up.

def schedule(ops, units, latency):
    """List-schedules ops onto pipelined units; returns ({name: start cycle}, last finish cycle)."""
    return {}, 0

from schedule import schedule

LATENCY = {"mul": 2, "add": 1}
TWO_PRODUCTS = {"a*b": ("mul", []), "c*d": ("mul", []), "y": ("add", ["a*b", "c*d"])}


def test_one_multiplier():
    """schedules y = a*b + c*d on one multiplier: y starts at cycle 3 and is ready after 4"""
    assert schedule(TWO_PRODUCTS, {"mul": 1, "add": 1}, LATENCY) == ({"a*b": 0, "c*d": 1, "y": 3}, 4)


def test_two_multipliers():
    """with two multipliers both products start at cycle 0 and y is ready after 3"""
    assert schedule(TWO_PRODUCTS, {"mul": 2, "add": 1}, LATENCY) == ({"a*b": 0, "c*d": 0, "y": 2}, 3)


def test_chain_ignores_extra_units():
    """a chain of two multiplies needs 4 cycles however many multipliers there are"""
    chain = {"p": ("mul", []), "q": ("mul", ["p"])}
    assert schedule(chain, {"mul": 2}, LATENCY) == ({"p": 0, "q": 2}, 4)


def test_three_products_on_two():
    """three independent products on two multipliers start at cycles 0, 0 and 1"""
    ops = {"m0": ("mul", []), "m1": ("mul", []), "m2": ("mul", [])}
    assert schedule(ops, {"mul": 2}, LATENCY) == ({"m0": 0, "m1": 0, "m2": 1}, 3)


def test_missing_unit():
    """refuses an operation whose kind has no units"""
    try:
        schedule(TWO_PRODUCTS, {"mul": 1}, LATENCY)
    except ValueError:
        return
    raise AssertionError("no ValueError when there is no adder")

Interview questions

Warm-up (2 to 5 years): what is an embedded HDL, and what does it generate?

It is a hardware description language built as a library of a programming language, such as Chisel in Scala or Amaranth in Python. A program in that language runs once, builds the design in memory and hands it to a compiler that writes Verilog, so the host’s loops, functions and classes decide what hardware exists. The result is ordinary RTL: this lesson’s 11-line Amaranth counter became 55 lines of Verilog that passed the same testbench as the hand-written counter.

Key takeaways

• An embedded HDL is a program in Python or Scala that builds the hardware and hands it to a compiler that writes Verilog: Amaranth through Yosys, Chisel through firtool; Bluespec has its own compiler, BSC.
• What they describe is still register-transfer level, and Amaranth’s Verilog passed the same testbench as the hand-written counter.
• High-level synthesis schedules a C or C++ function into clock cycles and units: one more multiplier cut y = a*b + c*d from 4 cycles to 3. It suits algorithms on data, not protocols.