Implement RFC 43: Rename reset= to init=.

Author: wanda-phi

amaranth/hdl/_ast.py

@@ -173,15 +173,15 @@ class ShapeCastable:
 
     .. code::
 
-        value_like = Signal(shape_castable, reset=initializer)
+        value_like = Signal(shape_castable, init=initializer)
 
     The code above is equivalent to:
 
     .. code::
 
         value_like = shape_castable(Signal(
             shape_castable.as_shape(),
-            reset=shape_castable.const(initializer)
+            init=shape_castable.const(initializer)
         ))
 
     Note that the :py:`shape_castable(x)` syntax performs :py:`shape_castable.__call__(x)`.
@@ -1731,15 +1731,15 @@ class Signal(Value, DUID, metaclass=_SignalMeta):
     name : str
         Name hint for this signal. If ``None`` (default) the name is inferred from the variable
         name this ``Signal`` is assigned to.
-    reset : int or integral Enum
+    init : int or integral Enum
         Reset (synchronous) or default (combinatorial) value.
         When this ``Signal`` is assigned to in synchronous context and the corresponding clock
         domain is reset, the ``Signal`` assumes the given value. When this ``Signal`` is unassigned
         in combinatorial context (due to conditional assignments not being taken), the ``Signal``
-        assumes its ``reset`` value. Defaults to 0.
+        assumes its ``init`` value. Defaults to 0.
     reset_less : bool
         If ``True``, do not generate reset logic for this ``Signal`` in synchronous statements.
-        The ``reset`` value is only used as a combinatorial default or as the initial value.
+        The ``init`` value is only used as a combinatorial default or as the initial value.
         Defaults to ``False``.
     attrs : dict
         Dictionary of synthesis attributes.
@@ -1754,13 +1754,13 @@ class Signal(Value, DUID, metaclass=_SignalMeta):
     width : int
     signed : bool
     name : str
-    reset : int
+    init : int
     reset_less : bool
     attrs : dict
     decoder : function
     """
 
-    def __init__(self, shape=None, *, name=None, reset=None, reset_less=False,
+    def __init__(self, shape=None, *, name=None, init=None, reset=None, reset_less=False,
                  attrs=None, decoder=None, src_loc_at=0):
         super().__init__(src_loc_at=src_loc_at)
 
@@ -1776,53 +1776,61 @@ def __init__(self, shape=None, *, name=None, reset=None, reset_less=False,
         self.width  = shape.width
         self.signed = shape.signed
 
-        orig_reset = reset
+        # TODO(amaranth-0.7): remove
+        if reset is not None:
+            if init is not None:
+                raise ValueError("Cannot specify both `reset` and `init`")
+            warnings.warn("`reset=` is deprecated, use `init=` instead",
+                          DeprecationWarning, stacklevel=2)
+            init = reset
+
+        orig_init = init
         if isinstance(orig_shape, ShapeCastable):
             try:
-                reset = Const.cast(orig_shape.const(reset))
+                init = Const.cast(orig_shape.const(init))
             except Exception:
-                raise TypeError("Reset value must be a constant initializer of {!r}"
+                raise TypeError("Initial value must be a constant initializer of {!r}"
                                 .format(orig_shape))
-            if reset.shape() != Shape.cast(orig_shape):
+            if init.shape() != Shape.cast(orig_shape):
                 raise ValueError("Constant returned by {!r}.const() must have the shape that "
                                  "it casts to, {!r}, and not {!r}"
                                  .format(orig_shape, Shape.cast(orig_shape),
-                                         reset.shape()))
+                                         init.shape()))
         else:
-            if reset is None:
-                reset = 0
+            if init is None:
+                init = 0
             try:
-                reset = Const.cast(reset)
+                init = Const.cast(init)
             except TypeError:
-                raise TypeError("Reset value must be a constant-castable expression, not {!r}"
-                                .format(orig_reset))
+                raise TypeError("Initial value must be a constant-castable expression, not {!r}"
+                                .format(orig_init))
         # Avoid false positives for all-zeroes and all-ones
-        if orig_reset is not None and not (isinstance(orig_reset, int) and orig_reset in (0, -1)):
-            if reset.shape().signed and not self.signed:
+        if orig_init is not None and not (isinstance(orig_init, int) and orig_init in (0, -1)):
+            if init.shape().signed and not self.signed:
                 warnings.warn(
-                    message="Reset value {!r} is signed, but the signal shape is {!r}"
-                            .format(orig_reset, shape),
+                    message="Initial value {!r} is signed, but the signal shape is {!r}"
+                            .format(orig_init, shape),
                     category=SyntaxWarning,
                     stacklevel=2)
-            elif (reset.shape().width > self.width or
-                  reset.shape().width == self.width and
-                    self.signed and not reset.shape().signed):
+            elif (init.shape().width > self.width or
+                  init.shape().width == self.width and
+                    self.signed and not init.shape().signed):
                 warnings.warn(
-                    message="Reset value {!r} will be truncated to the signal shape {!r}"
-                            .format(orig_reset, shape),
+                    message="Initial value {!r} will be truncated to the signal shape {!r}"
+                            .format(orig_init, shape),
                     category=SyntaxWarning,
                     stacklevel=2)
-        self.reset = reset.value
+        self.init = init.value
         self.reset_less = bool(reset_less)
 
-        if isinstance(orig_shape, range) and orig_reset is not None and orig_reset not in orig_shape:
-            if orig_reset == orig_shape.stop:
+        if isinstance(orig_shape, range) and orig_init is not None and orig_init not in orig_shape:
+            if orig_init == orig_shape.stop:
                 raise SyntaxError(
-                    f"Reset value {orig_reset!r} equals the non-inclusive end of the signal "
+                    f"Initial value {orig_init!r} equals the non-inclusive end of the signal "
                     f"shape {orig_shape!r}; this is likely an off-by-one error")
             else:
                 raise SyntaxError(
-                    f"Reset value {orig_reset!r} is not within the signal shape {orig_shape!r}")
+                    f"Initial value {orig_init!r} is not within the signal shape {orig_shape!r}")
 
         self.attrs = OrderedDict(() if attrs is None else attrs)
 
@@ -1850,6 +1858,18 @@ def __init__(self, shape=None, *, name=None, reset=None, reset_less=False,
                 # Any other case is formatted as a plain integer.
                 self._value_repr = (Repr(FormatInt(), self),)
 
+    @property
+    def reset(self):
+        warnings.warn("`Signal.reset` is deprecated, use `Signal.init` instead",
+                      DeprecationWarning, stacklevel=2)
+        return self.init
+
+    @reset.setter
+    def reset(self, value):
+        warnings.warn("`Signal.reset` is deprecated, use `Signal.init` instead",
+                      DeprecationWarning, stacklevel=2)
+        self.init = value
+
     @property
     def decoder(self):
         return self._decoder
@@ -1873,7 +1893,7 @@ def enum_decoder(value):
             self._decoder = enum_decoder
 
     @classmethod
-    def like(cls, other, *, name=None, name_suffix=None, src_loc_at=0, **kwargs):
+    def like(cls, other, *, name=None, name_suffix=None, init=None, reset=None, src_loc_at=0, **kwargs):
         """Create Signal based on another.
 
         Parameters
@@ -1887,15 +1907,24 @@ def like(cls, other, *, name=None, name_suffix=None, src_loc_at=0, **kwargs):
             new_name = other.name + str(name_suffix)
         else:
             new_name = tracer.get_var_name(depth=2 + src_loc_at, default="$like")
+        # TODO(amaranth-0.7): remove
+        if reset is not None:
+            if init is not None:
+                raise ValueError("Cannot specify both `reset` and `init`")
+            warnings.warn("`reset=` is deprecated, use `init=` instead",
+                          DeprecationWarning, stacklevel=2)
+            init = reset
         if isinstance(other, ValueCastable):
             shape = other.shape()
         else:
             shape = Value.cast(other).shape()
         kw = dict(shape=shape, name=new_name)
         if isinstance(other, Signal):
-            kw.update(reset=other.reset, reset_less=other.reset_less,
+            kw.update(init=other.init, reset_less=other.reset_less,
                       attrs=other.attrs, decoder=other.decoder)
         kw.update(kwargs)
+        if init is not None:
+            kw["init"] = init
         return cls(**kw, src_loc_at=1 + src_loc_at)
 
     def shape(self):

amaranth/hdl/_dsl.py

@@ -374,14 +374,21 @@ def Default(self):
             self._statements = _outer_case
 
     @contextmanager
-    def FSM(self, reset=None, domain="sync", name="fsm"):
+    def FSM(self, init=None, domain="sync", name="fsm", *, reset=None):
         self._check_context("FSM", context=None)
         if domain == "comb":
             raise ValueError(f"FSM may not be driven by the '{domain}' domain")
+        # TODO(amaranth-0.7): remove
+        if reset is not None:
+            if init is not None:
+                raise ValueError("Cannot specify both `reset` and `init`")
+            warnings.warn("`reset=` is deprecated, use `init=` instead",
+                          DeprecationWarning, stacklevel=2)
+            init = reset
         fsm_data = self._set_ctrl("FSM", {
             "name":     name,
             "signal":   Signal(name=f"{name}_state", src_loc_at=2),
-            "reset":    reset,
+            "init":     init,
             "domain":   domain,
             "encoding": OrderedDict(),
             "decoding": OrderedDict(),
@@ -489,17 +496,17 @@ def _pop_ctrl(self):
                     src_loc=src_loc, case_src_locs=switch_case_src_locs))
 
         if name == "FSM":
-            fsm_signal, fsm_reset, fsm_encoding, fsm_decoding, fsm_states = \
-                data["signal"], data["reset"], data["encoding"], data["decoding"], data["states"]
+            fsm_signal, fsm_init, fsm_encoding, fsm_decoding, fsm_states = \
+                data["signal"], data["init"], data["encoding"], data["decoding"], data["states"]
             fsm_state_src_locs = data["state_src_locs"]
             if not fsm_states:
                 return
             fsm_signal.width = bits_for(len(fsm_encoding) - 1)
-            if fsm_reset is None:
-                fsm_signal.reset = fsm_encoding[next(iter(fsm_states))]
+            if fsm_init is None:
+                fsm_signal.init = fsm_encoding[next(iter(fsm_states))]
             else:
-                fsm_signal.reset = fsm_encoding[fsm_reset]
-            # The FSM is encoded such that the state with encoding 0 is always the reset state.
+                fsm_signal.init = fsm_encoding[fsm_init]
+            # The FSM is encoded such that the state with encoding 0 is always the init state.
             fsm_decoding.update((n, s) for s, n in fsm_encoding.items())
             fsm_signal.decoder = lambda n: f"{fsm_decoding[n]}/{n}"
 

amaranth/hdl/_ir.py

@@ -691,8 +691,8 @@ def __init__(self, module_idx: int, signal: _ast.Signal,
 
     def emit_value(self, builder):
         if self.domain is None:
-            reset = _ast.Const(self.signal.reset, self.signal.width)
-            default, _signed = builder.emit_rhs(self.module_idx, reset)
+            init = _ast.Const(self.signal.init, self.signal.width)
+            default, _signed = builder.emit_rhs(self.module_idx, init)
         else:
             default = builder.emit_signal(self.signal)
         if len(self.assignments) == 1:
@@ -1184,7 +1184,7 @@ def emit_drivers(self):
                     arst = _nir.Net.from_const(0)
                 cell = _nir.FlipFlop(driver.module_idx,
                     data=value,
-                    init=driver.signal.reset,
+                    init=driver.signal.init,
                     clk=clk,
                     clk_edge=driver.domain.clk_edge,
                     arst=arst,
@@ -1198,12 +1198,12 @@ def emit_drivers(self):
                 src_loc = driver.signal.src_loc
             self.connect(self.emit_signal(driver.signal), value, src_loc=src_loc)
 
-        # Connect all undriven signal bits to their reset values. This can only happen for entirely
+        # Connect all undriven signal bits to their initial values. This can only happen for entirely
         # undriven signals, or signals that are partially driven by instances.
         for signal, value in self.netlist.signals.items():
             for bit, net in enumerate(value):
                 if net.is_late and net not in self.netlist.connections:
-                    self.netlist.connections[net] = _nir.Net.from_const((signal.reset >> bit) & 1)
+                    self.netlist.connections[net] = _nir.Net.from_const((signal.init >> bit) & 1)
 
     def emit_fragment(self, fragment: _ir.Fragment, parent_module_idx: 'int | None'):
         from . import _mem

amaranth/hdl/_mem.py

@@ -262,7 +262,7 @@ def __init__(self, memory, *, domain="sync", transparent=True, src_loc_at=0):
         self.data = Signal(memory.width,
                            name=f"{memory.name}_r_data", src_loc_at=1 + src_loc_at)
         if self.domain != "comb":
-            self.en = Signal(name=f"{memory.name}_r_en", reset=1,
+            self.en = Signal(name=f"{memory.name}_r_en", init=1,
                              src_loc_at=1 + src_loc_at)
         else:
             self.en = Const(1)

amaranth/hdl/_xfrm.py

@@ -521,7 +521,7 @@ def _insert_resets(self, fragment):
             domain = fragment.domains[domain_name]
             if domain.rst is None:
                 continue
-            stmts = [signal.eq(Const(signal.reset, signal.width))
+            stmts = [signal.eq(Const(signal.init, signal.width))
                      for signal in signals if not signal.reset_less]
             fragment.add_statements(domain_name, Switch(domain.rst, {1: stmts}))
 
@@ -559,7 +559,7 @@ def __call__(self, value, *, src_loc_at=0):
 
 class ResetInserter(_ControlInserter):
     def _insert_control(self, fragment, domain, signals):
-        stmts = [s.eq(Const(s.reset, s.width)) for s in signals if not s.reset_less]
+        stmts = [s.eq(Const(s.init, s.width)) for s in signals if not s.reset_less]
         fragment.add_statements(domain, Switch(self.controls[domain], {1: stmts}, src_loc=self.src_loc))
 
 

amaranth/lib/cdc.py

@@ -1,3 +1,5 @@
+import warnings
+
 from .. import *
 
 
@@ -26,8 +28,8 @@ class FFSynchronizer(Elaboratable):
         Signal connected to synchroniser output.
     o_domain : str
         Name of output clock domain.
-    reset : int
-        Reset value of the flip-flops. On FPGAs, even if ``reset_less`` is ``True``,
+    init : int
+        Initial and reset value of the flip-flops. On FPGAs, even if ``reset_less`` is ``True``,
         the :class:`FFSynchronizer` is still set to this value during initialization.
     reset_less : bool
         If ``True`` (the default), this :class:`FFSynchronizer` is unaffected by ``o_domain``
@@ -62,14 +64,24 @@ class FFSynchronizer(Elaboratable):
     Define the ``get_ff_sync`` platform method to override the implementation of
     :class:`FFSynchronizer`, e.g. to instantiate library cells directly.
     """
-    def __init__(self, i, o, *, o_domain="sync", reset=0, reset_less=True, stages=2,
+    def __init__(self, i, o, *, o_domain="sync", init=None, reset=None, reset_less=True, stages=2,
                  max_input_delay=None):
         _check_stages(stages)
 
         self.i = i
         self.o = o
 
-        self._reset      = reset
+        # TODO(amaranth-0.7): remove
+        if reset is not None:
+            if init is not None:
+                raise ValueError("Cannot specify both `reset` and `init`")
+            warnings.warn("`reset=` is deprecated, use `init=` instead",
+                          DeprecationWarning, stacklevel=2)
+            init = reset
+        if init is None:
+            init = 0
+
+        self._init       = init
         self._reset_less = reset_less
         self._o_domain   = o_domain
         self._stages     = stages
@@ -87,7 +99,7 @@ def elaborate(self, platform):
 
         m = Module()
         flops = [Signal(self.i.shape(), name=f"stage{index}",
-                        reset=self._reset, reset_less=self._reset_less)
+                        init=self._init, reset_less=self._reset_less)
                  for index in range(self._stages)]
         for i, o in zip((self.i, *flops), flops):
             m.d[self._o_domain] += o.eq(i)
@@ -161,7 +173,7 @@ def elaborate(self, platform):
 
         m = Module()
         m.domains += ClockDomain("async_ff", async_reset=True, local=True)
-        flops = [Signal(1, name=f"stage{index}", reset=1)
+        flops = [Signal(1, name=f"stage{index}", init=1)
                  for index in range(self._stages)]
         for i, o in zip((0, *flops), flops):
             m.d.async_ff += o.eq(i)

amaranth/lib/crc/__init__.py

@@ -383,7 +383,7 @@ def __init__(self, parameters):
     def elaborate(self, platform):
         m = Module()
 
-        crc_reg = Signal(self._crc_width, reset=self._initial_crc.value)
+        crc_reg = Signal(self._crc_width, init=self._initial_crc.value)
         data_in = Signal(self._data_width)
 
         # Optionally bit-reflect input words.