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 withm.Default()
.Replace uses of
Value.matches()
with no patterns withConst(1)
.Update uses of
amaranth.utils.log2_int(need_pow2=False)
toamaranth.utils.ceil_log2()
.Update uses of
amaranth.utils.log2_int(need_pow2=True)
toamaranth.utils.exact_log2()
.Update uses of
reset=
keyword argument toinit=
.Convert uses of
Simulator.add_sync_process
used as testbenches toSimulator.add_testbench
.Convert other uses of
Simulator.add_sync_process
toSimulator.add_process
.Convert simulator processes and testbenches to use the new async API.
Replace uses of
amaranth.hdl.Memory
withamaranth.lib.memory.Memory
.Replace imports of
amaranth.asserts.Assert
,Assume
, andCover
with imports fromamaranth.hdl
.Remove uses of
name=
keyword argument ofAssert
,Assume
, andCover
; 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 passdir="-"
and useamaranth.lib.io
buffers.Update uses of
Simulator.add_clock
with explicitphase
to take into account simulator no longer adding implicitperiod / 2
. (Previously,Simulator.add_clock
was documented to first toggle the clock at the timephase
, but actually first toggled the clock atperiod / 2 + phase
.)Update uses of
Simulator.run_until
to remove therun_passive=True
argument. If the code usesrun_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=
toinit=
RFC 45: Move
hdl.Memory
tolib.Memory
RFC 46: Change
Shape.cast(range(1))
tounsigned(0)
RFC 50:
Print
statement and string formattingRFC 51: Add
ShapeCastable.from_bits
andamaranth.lib.data.Const
RFC 53: Low-level I/O primitives
RFC 55: New
lib.io
componentsRFC 58: Core support for
ValueCastable
formattingRFC 59: Get rid of upwards propagation of clock domains
RFC 62: The
MemoryData
classRFC 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 inAssert
,Assume
andCover
. (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 isConst(0)
instead ofConst(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 nowunsigned(0)
. (RFC 46)Changed: the
reset=
argument ofSignal
,Signal.like()
,amaranth.lib.wiring.Member
,amaranth.lib.cdc.FFSynchronizer
, andm.FSM()
has been renamed toinit=
. (RFC 43)Changed:
Shape
has been made immutable and hashable.Changed:
Assert
,Assume
,Cover
have been moved toamaranth.hdl
fromamaranth.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
andCover
. (RFC 50)Removed: accepting non-subclasses of
Elaboratable
as elaboratables.
Standard library changes
Added:
amaranth.lib.memory
. (RFC 45)Added:
amaranth.lib.data.Const
class. (RFC 51)Changed:
amaranth.lib.data.Layout.const()
returns aamaranth.lib.data.Const
, not a view (RFC 51)Changed:
amaranth.lib.wiring.Signature.is_compliant()
no longer rejects reset-less signals.Added:
amaranth.lib.io.SingleEndedPort
,amaranth.lib.io.DifferentialPort
. (RFC 55)Added:
amaranth.lib.io.Buffer
,amaranth.lib.io.FFBuffer
,amaranth.lib.io.DDRBuffer
. (RFC 55)Added:
amaranth.lib.meta
,amaranth.lib.wiring.ComponentMetadata
. (RFC 30)Deprecated:
amaranth.lib.coding
. (RFC 63)Removed: (deprecated in 0.4)
amaranth.lib.scheduler
. (RFC 19)Removed: (deprecated in 0.4)
amaranth.lib.fifo.FIFOInterface
withfwft=False
. (RFC 20)Removed: (deprecated in 0.4)
amaranth.lib.fifo.SyncFIFO
withfwft=False
. (RFC 20)
Toolchain changes
Added:
Simulator.add_testbench
. (RFC 27)Added: async function support in
Simulator.add_testbench
andSimulator.add_process
. (RFC 36)Added: support for
amaranth.hdl.Assert
in simulation. (RFC 50)Changed:
Simulator.add_clock
no longer implicitly addsperiod / 2
whenphase
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 toSimulator.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
orAMARANTH_ENV_Diamond
; use upper-case environment variable names, such asAMARANTH_ENV_DIAMOND
.
Platform integration changes
Added:
BuildPlan.execute_local_docker()
.Added:
BuildPlan.extract()
.Added:
build.sh
begins with#!/bin/sh
.Changed:
IntelPlatform
renamed toAlteraPlatform
.Deprecated: argument
run_script=
inBuildPlan.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 ofNMIGEN_*
environment variables.Update shell environment to use
AMARANTH_ENV_<TOOLCHAIN>
(with all-uppercase<TOOLCHAIN>
name) environment variable names instead ofAMARANTH_ENV_<Toolchain>
orNMIGEN_ENV_<Toolchain>
(with mixed-case<Toolchain>
name).Update imports of the form
from amaranth.vendor.some_vendor import SomeVendorPlatform
tofrom amaranth.vendor import SomeVendorPlatform
. This change will reduce future churn.Replace uses of
Const.normalize(value, shape)
withConst(value, shape).value
.Replace uses of
Repl(value, count)
withvalue.replicate(count)
.Replace uses of
Record
withamaranth.lib.data
andamaranth.lib.wiring
. The appropriate replacement depends on the use case. IfRecord
was being used for data storage and accessing the bit-level representation, useamaranth.lib.data
. IfRecord
was being used for connecting design components together, useamaranth.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 byplatform.request
is not cast to value directly, but used for its fields. Replace code likeleds = Cat(platform.request(led, n) for n in range(4))
withleds = 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)
andamaranth.lib.fifo.FIFOInterface(fwft=False)
by converting code to usefwft=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
toValue.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
operatorsRFC 31: Enumeration type safety
RFC 34: Rename
amaranth.lib.wiring.Interface
toPureInterface
RFC 35: Add
ShapeLike
,ValueLike
RFC 37: Make
Signature
immutableRFC 38:
Component.signature
immutability
Language changes
Added:
ShapeCastable
, similar toValueCastable
.Added:
Value.as_signed()
andValue.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()
, supersedingRepl
. (RFC 10)Added:
Memory
supports transparent read ports with read enable.Changed: creating a
Signal
with a shape that is aShapeCastable
implementingShapeCastable.__call__()
wraps the returned object using that method. (RFC 15)Changed:
Value.cast()
castsValueCastable
objects recursively.Changed:
Value.cast()
treats instances of classes derived from bothenum.Enum
andint
(includingenum.IntEnum
) as enumerations rather than integers.Changed:
Value.matches()
with an empty list of patterns returnsConst(1)
rather thanConst(0)
, to match the behavior ofwith 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()
; useConst(value, shape).value
instead ofConst.normalize(value, shape)
. (RFC 5)Deprecated:
Repl
; useValue.replicate()
instead. (RFC 10)Deprecated:
Record
; useamaranth.lib.data
andamaranth.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
Added:
amaranth.lib.enum
. (RFC 3)Added:
amaranth.lib.data
. (RFC 1)Added:
amaranth.lib.wiring
. (RFC 2)Added:
amaranth.lib.crc
. (RFC 6)Deprecated:
amaranth.lib.scheduler
. (RFC 19)Deprecated:
amaranth.lib.fifo.FIFOInterface
withfwft=False
. (RFC 20)Deprecated:
amaranth.lib.fifo.SyncFIFO
withfwft=False
. (RFC 20)
Toolchain changes
Changed: text files are written with LF line endings on Windows, like on other platforms.
Added:
debug_verilog
override inbuild.TemplatedPlatform
.Added:
env=
argument tobuild.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
orAMARANTH_ENV_Diamond
; use upper-case environment variable names, such asAMARANTH_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()
andback.verilog.convert()
without an explicit ports= argument.Removed: (deprecated in 0.3)
test
.
Platform integration changes
Added:
icepack_opts
override invendor.LatticeICE40Platform
.Added:
OSCH
asdefault_clk
clock source invendor.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 fromvendor
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 beimport amaranth as am
, and adjust the code to use theam.*
namespace.Update
import nmigen.*
imports to beimport amaranth.*
.Update
import nmigen_boards.*
imports to beimport amaranth_boards.*
.Update board definitions using
vendor.lattice_machxo2.LatticeMachXO2Platform
to usevendor.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 usevendor.xilinx.XilinxPlatform
.Switch uses of
hdl.ast.UserValue
toValueCastable
; note thatValueCastable
does not inherit fromValue
, and inheriting fromValue
is not supported.Switch uses of
back.pysim
tosim
.Add an explicit
ports=
argument to uses ofback.rtlil.convert()
andback.verilog.convert()
if missing.Remove uses of
test.utils.FHDLTestCase
and vendor the implementation oftest.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.rotate_left()
andValue.rotate_right()
.Added:
Value.shift_left()
andValue.shift_right()
.Added:
ValueCastable
.Deprecated:
ast.UserValue
; useValueCastable
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
Added:
cdc.PulseSynchronizer
.Added:
cdc.AsyncFFSynchronizer
.Changed:
fifo.AsyncFIFO
is reset when the write domain is reset.Added:
fifo.AsyncFIFO.r_rst
is asserted when the write domain is reset.Added:
fifo.FIFOInterface.r_level
andfifo.FIFOInterface.w_level
.
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 asamaranth[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
; usesim
instead.Removed: The
with Simulator(fragment, ...) as sim:
form.Removed:
sim.Simulator.add_process()
with a generator argument.Deprecated:
sim.Simulator.step()
; usesim.Simulator.advance()
instead.Added:
build.BuildPlan.execute_remote_ssh()
.Deprecated:
test.utils.FHDLTestCase
, with no replacement.Deprecated:
back.rtlil.convert()
andback.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; useAMARANTH_*
environment variables instead.
Platform integration changes
Added:
SB_LFOSC
andSB_HFOSC
asdefault_clk
clock sources inlattice_ice40.LatticeICE40Platform
.Added:
lattice_machxo2.LatticeMachXO2Platform
generates binary (.bit
) bitstreams.Added:
lattice_machxo_2_3l.LatticeMachXO3LPlatform
.Deprecated:
lattice_machxo2
; uselattice_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
asdefault_clk
clock source inintel.IntelPlatform
.Added:
add_settings
andadd_constraints
overrides inintel.IntelPlatform
.Added:
xilinx.XilinxPlatform
.Deprecated:
xilinx_spartan_3_6.XilinxSpartan3APlatform
,xilinx_spartan_3_6.XilinxSpartan6Platform
,xilinx_7series.Xilinx7SeriesPlatform
,xilinx_ultrascale.XilinxUltrascalePlatform
; usexilinx.XilinxPlatform
instead.Added: Mistral toolchain support for
intel.IntelPlatform
.Added:
synth_design_opts
override inxilinx.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
.