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.4 (unreleased)

Support for Python 3.6 has been removed, and support for Python 3.11 has been added.

Features deprecated in version 0.3 have been removed. In particular, the nmigen.* namespace is not provided, # nmigen: annotations are not recognized, and NMIGEN_* envronment variables are not used.

Migrating from version 0.3

Apply the following changes to code written against Amaranth 0.3 to migrate it to version 0.4:

  • Update shell environment to use AMARANTH_* environment variables instead of NMIGEN_* environment variables.

  • Update shell environment to use AMARANTH_ENV_<TOOLCHAIN> (with all-uppercase <TOOLCHAIN> name) environment variable names instead of AMARANTH_ENV_<Toolchain> or NMIGEN_ENV_<Toolchain> (with mixed-case <Toolchain> name).

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

Implemented RFCs

  • RFC 1: Aggregate data structure library

  • RFC 3: Enumeration shapes

  • RFC 4: Constant-castable expressions

  • RFC 5: Remove Const.normalize

Language changes

  • Added: ShapeCastable, similar to ValueCastable.

  • Added: Value.as_signed() and Value.as_unsigned() can be used on left-hand side of assignment (with no difference in behavior).

  • Added: Const.cast(). (RFC 4)

  • Added: Value.matches() and with m.Case(): accept any constant-castable objects. (RFC 4)

  • Changed: Value.cast() casts ValueCastable objects recursively.

  • Changed: Value.cast() treats instances of classes derived from both enum.Enum and int (including enum.IntEnum) as enumerations rather than integers.

  • Changed: Value.matches() with an empty list of patterns returns Const(1) rather than Const(0), to match the behavior of with m.Case():.

  • Changed: Cat warns if an enumeration without an explicitly specified shape is used. (RFC 3)

  • Deprecated: Const.normalize(). (RFC 5)

  • Removed: (deprecated in 0.1) casting of Shape to and from a (width, signed) tuple.

  • Removed: (deprecated in 0.3) ast.UserValue.

  • Removed: (deprecated in 0.3) support for # nmigen: linter instructions at the beginning of file.

Standard library changes

Toolchain changes

  • Changed: text files are written with LF line endings on Windows, like on other platforms.

  • Added: debug_verilog override in build.TemplatedPlatform.

  • Deprecated: use of mixed-case toolchain environment variable names, such as NMIGEN_ENV_Diamond or AMARANTH_ENV_Diamond; use upper-case environment variable names, such as AMARANTH_ENV_DIAMOND.

  • Removed: (deprecated in 0.3) sim.Simulator.step().

  • Removed: (deprecated in 0.3) back.pysim.

  • Removed: (deprecated in 0.3) support for invoking back.rtlil.convert() and back.verilog.convert() without an explicit ports= argument.

  • Removed: (deprecated in 0.3) test.

Platform integration changes

  • Added: OSCH as default_clk clock source in vendor.lattice_machxo_2_3l.LatticeMachXO2Or3LPlatform.

  • Added: Xray toolchain support in vendor.xilinx.XilinxPlatform.

  • Removed: (deprecated in 0.3) lattice_machxo2

  • Removed: (deprecated in 0.3) lattice_machxo_2_3l.LatticeMachXO2Or3LPlatform SVF programming vector {{name}}.svf.

  • Removed: (deprecated in 0.3) xilinx_spartan_3_6.XilinxSpartan3APlatform, xilinx_spartan_3_6.XilinxSpartan6Platform, xilinx_7series.Xilinx7SeriesPlatform, xilinx_ultrascale.XilinxUltrascalePlatform.

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: Division and modulo operators can be used with a negative divisor.

  • Deprecated: # nmigen: linter instructions at the beginning of file; use # amaranth: instead.

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.

  • Deprecated: NMIGEN_* environment variables; use AMARANTH_* environment variables instead.

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.