Changelog

This document describes changes to the public interfaces in the Amaranth language and standard library. It does not include most bug fixes or implementation changes.

Version 0.3

The project has been renamed from nMigen to Amaranth.

Features deprecated in version 0.2 have been removed.

Migrating from version 0.2

Apply the following changes to code written against nMigen 0.2 to migrate it to Amaranth 0.3:

  • Update import nmigen as nm explicit prelude imports to be import amaranth as am, and adjust the code to use the am.* namespace.

  • Update import nmigen.* imports to be import amaranth.*.

  • Update import nmigen_boards.* imports to be import amaranth_boards.*.

  • Update board definitions using vendor.lattice_machxo2.LatticeMachXO2Platform to use vendor.lattice_machxo_2_3l.LatticeMachXO2Platform.

  • Update board definitions using vendor.xilinx_spartan_3_6.XilinxSpartan3APlatform, vendor.xilinx_spartan_3_6.XilinxSpartan6Platform, vendor.xilinx_7series.Xilinx7SeriesPlatform, vendor.xilinx_ultrascale.XilinxUltrascalePlatform to use vendor.xilinx.XilinxPlatform.

  • Switch uses of hdl.ast.UserValue to ValueCastable; note that ValueCastable does not inherit from Value, and inheriting from Value is not supported.

  • Switch uses of back.pysim to sim.

  • Add an explicit ports= argument to uses of back.rtlil.convert() and back.verilog.convert() if missing.

  • Remove uses of test.utils.FHDLTestCase and vendor the implementation of test.utils.FHDLTestCase.assertFormal if necessary.

While code that uses the features listed as deprecated below will work in Amaranth 0.3, they will be removed in the next version.

Language changes

  • Added: Value can be used with abs().

  • Added: Value.rotate_left() and Value.rotate_right().

  • Added: Value.shift_left() and Value.shift_right().

  • Added: ValueCastable.

  • Deprecated: ast.UserValue; use ValueCastable instead.

  • Added: Divison and modulo operators can be used with a negative divisor.

Standard library changes

Toolchain changes

  • Changed: Backend and simulator reject wires larger than 65536 bits.

  • Added: Backend emits Yosys enumeration attributes for enumeration-shaped signals.

  • Added: If a compatible Yosys version is not installed, back.verilog will fall back to the amaranth-yosys PyPI package. The package can be installed as amaranth[builtin-yosys] to ensure this dependency is available.

  • Added: back.cxxrtl.

  • Added: sim, a simulator interface with support for multiple simulation backends.

  • Deprecated: back.pysim; use sim instead.

  • Removed: The with Simulator(fragment, ...) as sim: form.

  • Removed: sim.Simulator.add_process() with a generator argument.

  • Deprecated: sim.Simulator.step(); use sim.Simulator.advance() instead.

  • Added: build.BuildPlan.execute_remote_ssh().

  • Deprecated: test.utils.FHDLTestCase, with no replacement.

  • Deprecated: back.rtlil.convert() and back.verilog.convert() without an explicit ports= argument.

  • Changed: VCD output now uses a top-level “bench” module that contains testbench only signals.

Platform integration changes

Versions 0.1, 0.2

No changelog is provided for these versions.

The PyPI packages were published under the nmigen namespace, rather than amaranth.