Amaranth HDL Documentation

Amaranth is an open-source toolchain for developing hardware based on synchronous digital logic using Python. It provides a complete FPGA development workflow including:

• Amaranth language: A Python library for register transfer level (RTL) modeling of synchronous logic.
• Standard library: A collection of essential digital design components (FIFOs, CDC primitives, I/O buffers).
• Simulator: An event-driven Python-based simulator for testing designs using Python generator functions.
• Build system: An integration layer for FPGA toolchains and development board definitions.

The toolchain is designed to be interoperable with industry-standard (System)Verilog and VHDL code.

Amaranth is an open-source toolchain for developing hardware based on synchronous digital logic using Python. It provides a hardware definition language, a standard library, a simulator, and a build system to cover the typical FPGA development workflow.

Key features include:

• Python-based hardware design: Use Python to define complex hardware with reusable components.
• Interoperability: Amaranth can integrate with existing (System)Verilog or VHDL code, and vice versa.
• Ecosystem: Includes evaluation board definitions (amaranth-boards) and a System on Chip toolkit (amaranth-soc).

The amaranth.lib.cdc module provides specialized building blocks designed to safely handle Clock Domain Crossing (CDC). These components prevent metastability and data corruption when signals move between asynchronous clock domains.

Available synchronizer components include:

• FFSynchronizer: Standard flip-flop based synchronizer.
• AsyncFFSynchronizer: Asynchronous flip-flop synchronizer.
• ResetSynchronizer: Synchronizer specifically for reset signals.
• PulseSynchronizer: Synchronizer for transferring single-cycle pulses.

A module is the fundamental unit of an Amaranth design hierarchy. It is the smallest collection of logic that can be independently simulated, synthesized, or processed.

Modules are responsible for:

• Associating signals with control domains.
• Providing control flow syntax.
• Managing clock domains.
• Aggregating submodules.

Every design begins with a fresh module instance.

m = Module()

The Amaranth standard library provides reliable, reusable building blocks for digital design. While optional, it is recommended for:

• Clock Domain Crossing (CDC): Provides primitives that can be specialized by platform integrations to follow vendor recommendations.
• I/O Buffers: Provides a common interface for high-speed designs requiring registered or geared I/O buffers.
• Common Components: Includes synchronous and asynchronous FIFOs and flexible I/O buffer interfaces.

Using the standard library reduces the amount of code required when migrating between different FPGA families.

The Amaranth simulator is an event-driven, pure-Python implementation that requires no system dependencies.

• Test Benches: Written as Python generator functions.
• Capabilities: Supports designs with multiple clocks and asynchronous resets.
• Performance: Compiles the netlist to Python code ahead of time for high performance (especially when running on PyPy).
• Alternative: You can also convert Amaranth designs to Verilog to use with external simulators like Icarus Verilog or Verilator.

For advanced simulation performance or to avoid reimplementing complex algorithms in Amaranth, you can replace an Amaranth circuit with an async Python function called a process.

A process runs simultaneously with the Design Under Test (DUT) and communicates with the design via Signal objects.

Key differences between a process and a testbench:

• Execution Order: Testbenches run in a well-defined order (first to last as added), whereas processes run in an undefined order while the design is converging.
• Observability: Processes cannot use ctx.get() to inspect signal values; this prevents processes from observing inconsistent intermediate states. Instead, they must react to changes or clock edges.

To add a process, use Simulator.add_process(async_function).