Getting started

This section demonstrates the basic Amaranth workflow to provide a cursory overview of the language and the toolchain. See thetutorial for a step-by-step introduction to the language, and thelanguage guide for a detailed explanation of every language construct.

A counter

As a first example, consider a counter with a fixed limit, enable, and overflow. The code for this example is shown below.Download and run it:

$python3up_counter.py

Implementing a counter

A 16-bit up counter with enable input, overflow output, and a limit fixed at design time can be implemented in Amaranth as follows:

 1fromamaranthimport* 2fromamaranth.libimportwiring 3fromamaranth.lib.wiringimportIn,Out 4 5 6classUpCounter(wiring.Component): 7""" 8    A 16-bit up counter with a fixed limit. 910    Parameters11    ----------12    limit : int13        The value at which the counter overflows.1415    Attributes16    ----------17    en : Signal, in18        The counter is incremented if ``en`` is asserted, and retains19        its value otherwise.20    ovf : Signal, out21        ``ovf`` is asserted when the counter reaches its limit.22    """2324en:In(1)25ovf:Out(1)2627def__init__(self,limit):28self.limit=limit29self.count=Signal(16)3031super().__init__()3233defelaborate(self,platform):34m=Module()3536m.d.comb+=self.ovf.eq(self.count==self.limit)3738withm.If(self.en):39withm.If(self.ovf):40m.d.sync+=self.count.eq(0)41withm.Else():42m.d.sync+=self.count.eq(self.count+1)4344returnm

The reusable building block of Amaranth designs is aComponent: a Python class declares its interface (en andovf, in this case) and implements theelaborate method that defines its behavior.

Mostelaborate implementations use aModule helper to describe combinational (m.d.comb) and synchronous (m.d.sync) logic controlled with conditional syntax (m.If,m.Elif,m.Else) similar to Python’s. They can also instantiate vendor-defined black boxes or modules written in other HDLs.

Testing a counter

To verify its functionality, the counter can be simulated for a small amount of time, with a test bench driving it and checking a few simple conditions:

46fromamaranth.simimportSimulator,Period474849dut=UpCounter(25)50asyncdefbench(ctx):51# Disabled counter should not overflow.52ctx.set(dut.en,0)53for_inrange(30):54awaitctx.tick()55assertnotctx.get(dut.ovf)5657# Once enabled, the counter should overflow in 25 cycles.58ctx.set(dut.en,1)59for_inrange(24):60awaitctx.tick()61assertnotctx.get(dut.ovf)62awaitctx.tick()63assertctx.get(dut.ovf)6465# The overflow should clear in one cycle.66awaitctx.tick()67assertnotctx.get(dut.ovf)686970sim=Simulator(dut)71sim.add_clock(Period(MHz=1))72sim.add_testbench(bench)73withsim.write_vcd("up_counter.vcd"):74sim.run()

The testbench is implemented as a Pythonasync function that is simulated concurrently with the counter itself. The testbench can inspect the simulated signals usingctx.get(sig), update them usingctx.set(sig,val), and advance the simulation by one clock cycle withawaitctx.tick(). See thesimulator documentation for details.

When run, the testbench finishes successfully, since all of the assertions hold, and produces a VCD file with waveforms recorded for everySignal as well as the clock of thesync domain:

{'signal': [{'name': 'clk', 'wave': 'p..........'}, {'name': 'count', 'wave': '===========', 'data': ['17', '18', '19', '20', '21', '22', '23', '24', '25', '0', '1']}, {'name': 'en', 'wave': '1..........'}, {'name': 'ovf', 'wave': '0.......10.'}], 'head': {'tock': 48}, 'config': {'skin': 'default'}}

Converting a counter

Although some Amaranth workflows do not include Verilog at all, it is still the de facto standard for HDL interoperability. Any Amaranth design can be converted to synthesizable Verilog using the corresponding backend:

76fromamaranth.backimportverilog777879top=UpCounter(25)80withopen("up_counter.v","w")asf:81f.write(verilog.convert(top))

The signals that will be connected to the ports of the top-level Verilog module should be specified explicitly. The rising edge clock and synchronous reset signals of thesync domain are added automatically; if necessary, the control signals can be configured explicitly. The result is the following Verilog code (lightly edited for clarity):

 1(*generator="Amaranth"*) 2moduletop(ovf,clk,rst,en); 3reg\$auto$verilog_backend.cc:2255:dump_module$1=0; 4(*src="up_counter.py:36"*) 5wire\$1; 6(*src="up_counter.py:42"*) 7wire[16:0]\$3; 8(*src="up_counter.py:42"*) 9wire[16:0]\$4;10(*src="<site-packages>/amaranth/hdl/ir.py:509"*)11inputclk;12wireclk;13(*src="up_counter.py:29"*)14reg[15:0]count=16'h0000;15(*src="up_counter.py:29"*)16reg[15:0]\count$next;17(*src="<site-packages>/amaranth/lib/wiring.py:1647"*)18inputen;19wireen;20(*src="<site-packages>/amaranth/lib/wiring.py:1647"*)21outputovf;22wireovf;23(*src="<site-packages>/amaranth/hdl/ir.py:509"*)24inputrst;25wirerst;26assign\$1=count==(*src="up_counter.py:36"*)5'h19;27assign\$4=count+(*src="up_counter.py:42"*)1'h1;28always@(posedgeclk)29count<=\count$next;30always@*begin31if(\$auto$verilog_backend.cc:2255:dump_module$1)beginend32\count$next=count;33(*src="up_counter.py:38"*)34if(en)begin35(*full_case=32'd1*)36(*src="up_counter.py:39"*)37if(ovf)begin38\count$next=16'h0000;39endelsebegin40\count$next=\$4[15:0];41end42end43(*src="<site-packages>/amaranth/hdl/xfrm.py:534"*)44if(rst)begin45\count$next=16'h0000;46end47end48assign\$3=\$4;49assignovf=\$1;50endmodule

To aid debugging, the generated Verilog code has the same general structure as the Amaranth source code (although more verbose), and contains extensive source location information.

Note

Unfortunately, at the moment none of the supported toolchains will use the source location information in diagnostic messages.

A blinking LED

Although Amaranth works well as a standalone HDL, it also includes a build system that integrates with FPGA toolchains, and many board definition files for common developer boards that include pinouts and programming adapter invocations. The following code will blink a LED with a frequency of 1 Hz on any board that has a LED and an oscillator:

 1fromamaranthimport* 2 3 4classLEDBlinker(Elaboratable): 5defelaborate(self,platform): 6m=Module() 7 8led=platform.request("led") 910half_freq=int(platform.default_clk_period.hertz//2)11timer=Signal(range(half_freq+1))1213withm.If(timer==half_freq):14m.d.sync+=led.o.eq(~led.o)15m.d.sync+=timer.eq(0)16withm.Else():17m.d.sync+=timer.eq(timer+1)1819returnm

TheLEDBlinker module will use the first LED available on the board, and derive the clock divisor from the oscillator frequency specified in the clock constraint. It can be used, for example, with theLattice iCEStick evaluation board, one of the many boards already supported by Amaranth:

Todo

Link to the installation instructions for the FOSS iCE40 toolchain, probably as a part of board documentation.

21fromamaranth_boards.icestickimportICEStickPlatform222324ICEStickPlatform().build(LEDBlinker(),do_program=True)

With only a single line of code, the design is synthesized, placed, routed, and programmed to the on-board Flash memory. Although not all applications will use the Amaranth build system, the designs that choose it can benefit from the “turnkey” built-in workflows; if necessary, the built-in workflows can be customized to include user-specified options, commands, and files.