0cb71f8c57
Before this commit, testbenches (generators added with `add_testbench`) were not only preemptible after any `yield`, but were *guaranteed* to be preempted by another testbench after *every* yield. This is evil: if you have any race condition between testbenches, which is common, this scheduling strategy will maximize the resulting nondeterminism by interleaving your testbench with every other one as much as possible. This behavior is an outcome of the way `add_testbench` is implemented, which is by yielding `Settle()` after every command. One can observe that: - `yield value_like` should never preempt; - `yield assignable.eq()` in `add_process()` should not preempt, since it only sets a `next` signal state, or appends to `write_queue` of a memory state, and never wakes up processes; - `yield assignable.eq()` in `add_testbench()` should only preempt if changing `assignable` wakes up an RTL process. (It could potentially also preempt if that wakes up another testbench, but this has no benefit and requires `sim.set()` from RFC 36 to be awaitable, which is not desirable.) After this commit, `PySimEngine._step()` is implemented with two nested loops instead of one. The outer loop iterates through every testbench and runs it until an explicit wait point (`Settle()`, `Delay()`, or `Tick()`), terminating when no testbenches are runnable. The inner loop is the usual eval/commit loop, running whenever a testbench changes design state. `PySimEngine._processes` is a `set`, which doesn't have a deterministic iteration order. This does not matter for processes, where determinism is guaranteed by the eval/commit loop, but causes racy testbenches to pass or fail nondeterministically (in practice depending on the memory layout of the Python process). While it is best to not have races in the testbenches, this commit makes `PySimEngine._testbenches` a `list`, making the outcome of a race deterministic, and enabling a hacky work- around to make them work: reordering calls to `add_testbench()`. A potential future improvement is a simulation mode that, instead, randomizes the scheduling of testbenches, exposing race conditions early. |
||
|---|---|---|
| .github | ||
| amaranth | ||
| docs | ||
| examples | ||
| tests | ||
| .codecov.yml | ||
| .coveragerc | ||
| .env.toolchain | ||
| .gitattributes | ||
| .gitignore | ||
| CONTRIBUTING.txt | ||
| LICENSE.txt | ||
| pdm_build.py | ||
| pyproject.toml | ||
| README.md | ||
Amaranth HDL (previously nMigen)
The Amaranth project provides an open-source toolchain for developing hardware based on synchronous digital logic using the Python programming language, as well as evaluation board definitions, a System on Chip toolkit, and more. It aims to be easy to learn and use, reduce or eliminate common coding mistakes, and simplify the design of complex hardware with reusable components.
The Amaranth toolchain consists of the Amaranth hardware definition language, the standard library, the simulator, and the build system, covering all steps of a typical FPGA development workflow. At the same time, it does not restrict the designer’s choice of tools: existing industry-standard (System)Verilog or VHDL code can be integrated into an Amaranth-based design flow, or, conversely, Amaranth code can be integrated into an existing Verilog-based design flow.
The development of Amaranth has been supported by LambdaConcept, ChipEleven, and Chipflow.
Introduction
See the Introduction section of the documentation.
Installation
See the Installation section of the documentation.
Usage
See the Language guide section of the documentation.
Platform support
Amaranth can be used to target any FPGA or ASIC process that accepts behavioral Verilog-2001 as input. It also offers extended support for many FPGA families, providing toolchain integration, abstractions for device-specific primitives, and more. Specifically:
- Lattice iCE40 (toolchains: Yosys+nextpnr, LSE-iCECube2, Synplify-iCECube2);
- Lattice MachXO2 (toolchains: Diamond);
- Lattice MachXO3L (toolchains: Diamond);
- Lattice ECP5 (toolchains: Yosys+nextpnr, Diamond);
- Lattice Nexus (toolchains: Yosys+nextpnr, Diamond);
- AMD Virtex, Virtex E, Spartan 2, Spartan 2E (toolchains: ISE);
- AMD Virtex II, Virtex II Pro (toolchains: ISE);
- AMD Spartan 3, Spartan 3E, Spartan 3A, Spartan 3AN, Spartan 3A DSP (toolchains: ISE);
- AMD Virtex 4, Virtex 5, Virtex 6 (toolchains: ISE);
- AMD Spartan 6 (toolchains: ISE);
- AMD 7-series (toolchains: Vivado, ISE);
- AMD UltraScale, UltraScale+ (toolchains: Vivado);
- Altera (toolchains: Quartus);
- Quicklogic EOS S3 (toolchains: Yosys+VPR).
FOSS toolchains are listed in bold.
Community
Amaranth has a dedicated IRC channel, #amaranth-lang at libera.chat, which is bridged1 to Matrix at #amaranth-lang:matrix.org. Feel free to join to ask questions about using Amaranth or discuss ongoing development of Amaranth and its related projects.
License
Amaranth is released under the two-clause BSD license. You are permitted to use Amaranth for open-source and proprietary designs provided that the copyright notice in the license file is reproduced.
-
The same messages appear on IRC and on Matrix, and one can participate in the discussion equally using either communication system. ↩︎