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.

Documentation for past releases

Documentation for past releases of the Amaranth language and toolchain is available online:

Version 0.5 (unreleased)

The Migen compatibility layer has been removed.

Migrating from version 0.4

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

  • Replace uses of m.Case() with no patterns with m.Default().

  • Replace uses of Value.matches() with no patterns with Const(1).

  • Update uses of amaranth.utils.log2_int(need_pow2=False) to amaranth.utils.ceil_log2().

  • Update uses of amaranth.utils.log2_int(need_pow2=True) to amaranth.utils.exact_log2().

  • Update uses of reset= keyword argument to init=.

  • Convert uses of Simulator.add_sync_process used as testbenches to Simulator.add_testbench.

  • Convert other uses of Simulator.add_sync_process to Simulator.add_process.

  • Convert simulator processes and testbenches to use the new async API.

  • Replace uses of amaranth.hdl.Memory with amaranth.lib.memory.Memory.

  • Replace imports of amaranth.asserts.Assert, Assume, and Cover with imports from amaranth.hdl.

  • Remove uses of name= keyword argument of Assert, Assume, and Cover; a message can be used instead.

  • Ensure all elaboratables are subclasses of Elaboratable.

  • Ensure clock domains aren’t used outside the module that defines them, or its submodules; move clock domain definitions upwards in the hierarchy as necessary

  • Remove uses of amaranth.lib.coding.* by inlining or copying the implementation of the modules.

  • Update uses of platform.request to pass dir="-" and use amaranth.lib.io buffers.

  • Update uses of Simulator.add_clock with explicit phase to take into account simulator no longer adding implicit period / 2. (Previously, Simulator.add_clock was documented to first toggle the clock at the time phase, but actually first toggled the clock at period / 2 + phase.)

  • Update uses of Simulator.run_until to remove the run_passive=True argument. If the code uses run_passive=False, ensure it still works with the new behavior.

Implemented RFCs

  • RFC 17: Remove log2_int

  • RFC 27: Testbench processes for the simulator

  • RFC 30: Component metadata

  • RFC 36: Async testbench functions

  • RFC 39: Change semantics of no-argument m.Case()

  • RFC 43: Rename reset= to init=

  • RFC 45: Move hdl.Memory to lib.Memory

  • RFC 46: Change Shape.cast(range(1)) to unsigned(0)

  • RFC 50: Print statement and string formatting

  • RFC 51: Add ShapeCastable.from_bits and amaranth.lib.data.Const

  • RFC 53: Low-level I/O primitives

  • RFC 55: New lib.io components

  • RFC 58: Core support for ValueCastable formatting

  • RFC 59: Get rid of upwards propagation of clock domains

  • RFC 62: The MemoryData class

  • RFC 63: Remove amaranth.lib.coding

  • RFC 65: Special formatting for structures and enums

Language changes

  • Added: Slice objects have been made const-castable.

  • Added: amaranth.utils.ceil_log2(), amaranth.utils.exact_log2(). (RFC 17)

  • Added: Format objects, Print statements, messages in Assert, Assume and Cover. (RFC 50)

  • Added: ShapeCastable.from_bits() method. (RFC 51)

  • Added: IO values, IOPort objects, IOBufferInstance objects. (RFC 53)

  • Added: MemoryData objects. (RFC 62)

  • Changed: m.Case() with no patterns is never active instead of always active. (RFC 39)

  • Changed: Value.matches() with no patterns is Const(0) instead of Const(1). (RFC 39)

  • Changed: Signal(range(stop), init=stop) warning has been changed into a hard error and made to trigger on any out-of range value.

  • Changed: Signal(range(0)) is now valid without a warning.

  • Changed: Shape.cast(range(1)) is now unsigned(0). (RFC 46)

  • Changed: the reset= argument of Signal, Signal.like(), amaranth.lib.wiring.Member, amaranth.lib.cdc.FFSynchronizer, and m.FSM() has been renamed to init=. (RFC 43)

  • Changed: Shape has been made immutable and hashable.

  • Changed: Assert, Assume, Cover have been moved to amaranth.hdl from amaranth.asserts. (RFC 50)

  • Changed: Instance IO ports now accept only IO values, not plain values. (RFC 53)

  • Deprecated: amaranth.utils.log2_int(). (RFC 17)

  • Deprecated: amaranth.hdl.Memory. (RFC 45)

  • Deprecated: upwards propagation of clock domains. (RFC 59)

  • Removed: (deprecated in 0.4) Const.normalize(). (RFC 5)

  • Removed: (deprecated in 0.4) Repl. (RFC 10)

  • Removed: (deprecated in 0.4) ast.Sample, ast.Past, ast.Stable, ast.Rose, ast.Fell.

  • Removed: assertion names in Assert, Assume and Cover. (RFC 50)

  • Removed: accepting non-subclasses of Elaboratable as elaboratables.

Standard library changes

Toolchain changes

  • Added: Simulator.add_testbench. (RFC 27)

  • Added: async function support in Simulator.add_testbench and Simulator.add_process. (RFC 36)

  • Added: support for amaranth.hdl.Assert in simulation. (RFC 50)

  • Changed: Simulator.add_clock no longer implicitly adds period / 2 when phase is specified, actually matching the documentation.

  • Changed: Simulator.run_until always runs the simulation until the given deadline, even when no critical processes or testbenches are present.

  • Deprecated: Settle simulation command. (RFC 27)

  • Deprecated: Simulator.add_sync_process. (RFC 27)

  • Deprecated: the run_passive argument to Simulator.run_until has been deprecated, and does nothing.

  • Removed: (deprecated in 0.4) 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.

Platform integration changes

  • Added: BuildPlan.execute_local_docker().

  • Added: BuildPlan.extract().

  • Added: build.sh begins with #!/bin/sh.

  • Changed: IntelPlatform renamed to AlteraPlatform.

  • Deprecated: argument run_script= in BuildPlan.execute_local().

  • Removed: (deprecated in 0.4) vendor.intel, vendor.lattice_ecp5, vendor.lattice_ice40, vendor.lattice_machxo2_3l, vendor.quicklogic, vendor.xilinx. (RFC 18)

Version 0.4

Support has been added for a new and improved way of defining data structures in amaranth.lib.data and component interfaces in amaranth.lib.wiring, as defined in RFC 1 and RFC 2. Record has been deprecated. In a departure from the usual policy, to give designers additional time to migrate, Record will be removed in Amaranth 0.6 (one release later than normal).

Support for enumerations has been extended. A shape for enumeration members can be provided for an enumeration class, as defined in RFC 3.

The language includes several new extension points for integration with Value based data structures defined outside of the core language. In particular, Signal(shape) may now return a Signal object wrapped in another if shape implements the call protocol, as defined in RFC 15.

Several issues with shape inference have been resolved. Notably, a - b where both a and b are unsigned now returns a signed value.

Support for Python 3.6 and 3.7 has been removed, and support for Python 3.11 and 3.12 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.

The Migen compatibility layer remains deprecated (as it had been since Amaranth 0.1), and is now scheduled to be removed in version 0.5.

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).

  • Update imports of the form from amaranth.vendor.some_vendor import SomeVendorPlatform to from amaranth.vendor import SomeVendorPlatform. This change will reduce future churn.

  • Replace uses of Const.normalize(value, shape) with Const(value, shape).value.

  • Replace uses of Repl(value, count) with value.replicate(count).

  • Replace uses of Record with amaranth.lib.data and amaranth.lib.wiring. The appropriate replacement depends on the use case. If Record was being used for data storage and accessing the bit-level representation, use amaranth.lib.data. If Record was being used for connecting design components together, use amaranth.lib.wiring.

  • Replace uses of Sample, Past, Stable, Rose, Fell with a manually instantiated register, e.g. past_x = Signal.like(x); m.d.sync += past_x.eq(x).

  • Remove uses of amaranth.compat by migrating to native Amaranth syntax.

  • Ensure the Pin instance returned by platform.request is not cast to value directly, but used for its fields. Replace code like leds = Cat(platform.request(led, n) for n in range(4)) with leds = Cat(platform.request(led, n).o for n in range(4)) (note the .o).

  • Remove uses of amaranth.lib.scheduler.RoundRobin by inlining or copying the implementation of that class.

  • Remove uses of amaranth.lib.fifo.SyncFIFO(fwft=False) and amaranth.lib.fifo.FIFOInterface(fwft=False) by converting code to use fwft=True FIFOs or copying the implementation of those classes.

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 2: Interface definition library

  • RFC 3: Enumeration shapes

  • RFC 4: Constant-castable expressions

  • RFC 5: Remove Const.normalize

  • RFC 6: CRC generator

  • RFC 8: Aggregate extensibility

  • RFC 9: Constant initialization for shape-castable objects

  • RFC 10: Move Repl to Value.replicate

  • RFC 18: Reorganize vendor platforms

  • RFC 19: Remove amaranth.lib.scheduler

  • RFC 15: Lifting shape-castable objects

  • RFC 20: Deprecate non-FWFT FIFOs

  • RFC 22: Define ValueCastable.shape()

  • RFC 28: Allow overriding Value operators

  • RFC 31: Enumeration type safety

  • RFC 34: Rename amaranth.lib.wiring.Interface to PureInterface

  • RFC 35: Add ShapeLike, ValueLike

  • RFC 37: Make Signature immutable

  • RFC 38: Component.signature immutability

Language changes

  • Added: ShapeCastable, similar to ValueCastable.

  • Added: ShapeLike and ValueLike. (RFC 35)

  • 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: Signal(reset=), Value.matches(), with m.Case(): accept any constant-castable objects. (RFC 4)

  • Added: Value.replicate(), superseding Repl. (RFC 10)

  • Added: Memory supports transparent read ports with read enable.

  • Changed: creating a Signal with a shape that is a ShapeCastable implementing ShapeCastable.__call__() wraps the returned object using that method. (RFC 15)

  • 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)

  • Changed: signed(0) is no longer constructible. (The semantics of this shape were never defined.)

  • Changed: Value.__abs__() returns an unsigned value.

  • Deprecated: ast.Sample, ast.Past, ast.Stable, ast.Rose, ast.Fell. (Predating the RFC process.)

  • Deprecated: Const.normalize(); use Const(value, shape).value instead of Const.normalize(value, shape). (RFC 5)

  • Deprecated: Repl; use Value.replicate() instead. (RFC 10)

  • Deprecated: Record; use amaranth.lib.data and amaranth.lib.wiring instead. (RFC 1, RFC 2)

  • 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.

  • Added: env= argument to build.run.BuildPlan.execute_local().

  • Changed: build.run.BuildPlan.add_file() rejects absolute paths.

  • 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: icepack_opts override in vendor.LatticeICE40Platform.

  • Added: OSCH as default_clk clock source in vendor.LatticeMachXO2Platform, vendor.LatticeMachXO3LPlatform.

  • Added: Xray toolchain support in vendor.XilinxPlatform.

  • Added: Artix UltraScale+ part support in vendor.XilinxPlatform.

  • Added: vendor.GowinPlatform.

  • Deprecated: vendor.intel, vendor.lattice_ecp5, vendor.lattice_ice40, vendor.lattice_machxo2_3l, vendor.quicklogic, vendor.xilinx; import platforms directly from vendor instead. (RFC 18)

  • 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

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

  • Added: SB_LFOSC and SB_HFOSC as default_clk clock sources in lattice_ice40.LatticeICE40Platform.

  • Added: lattice_machxo2.LatticeMachXO2Platform generates binary (.bit) bitstreams.

  • Added: lattice_machxo_2_3l.LatticeMachXO3LPlatform.

  • Deprecated: lattice_machxo2; use lattice_machxo_2_3l.LatticeMachXO2Platform instead.

  • Removed: xilinx_7series.Xilinx7SeriesPlatform.grade; this family has no temperature grades.

  • Removed: xilinx_ultrascale.XilinxUltrascalePlatform.grade; this family has temperature grade as part of speed grade.

  • Added: Symbiflow toolchain support for xilinx_7series.Xilinx7SeriesPlatform.

  • Added: lattice_machxo_2_3l.LatticeMachXO2Or3LPlatform generates separate Flash and SRAM SVF programming vectors, {{name}}_flash.svf and {{name}}_sram.svf.

  • Deprecated: lattice_machxo_2_3l.LatticeMachXO2Or3LPlatform SVF programming vector {{name}}.svf; use {{name}}_flash.svf instead.

  • Added: quicklogic.QuicklogicPlatform.

  • Added: cyclonev_oscillator as default_clk clock source in intel.IntelPlatform.

  • Added: add_settings and add_constraints overrides in intel.IntelPlatform.

  • Added: xilinx.XilinxPlatform.

  • Deprecated: xilinx_spartan_3_6.XilinxSpartan3APlatform, xilinx_spartan_3_6.XilinxSpartan6Platform, xilinx_7series.Xilinx7SeriesPlatform, xilinx_ultrascale.XilinxUltrascalePlatform; use xilinx.XilinxPlatform instead.

  • Added: Mistral toolchain support for intel.IntelPlatform.

  • Added: synth_design_opts override in xilinx.XilinxPlatform.

Versions 0.1, 0.2

No changelog is provided for these versions.

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