hdl.ast: deprecate Const.normalize.

Tracking issue #754.

amaranth/hdl/ast.py

@@ -582,7 +582,9 @@ class Const(Value):
     """
     src_loc = None
 
+    # TODO(amaranth-0.5): remove
     @staticmethod
+    @deprecated("instead of `Const.normalize(value, shape)`, use `Const(value, shape).value`")
     def normalize(value, shape):
         mask = (1 << shape.width) - 1
         value &= mask
@@ -601,7 +603,10 @@ class Const(Value):
             shape = Shape.cast(shape, src_loc_at=1 + src_loc_at)
         self.width  = shape.width
         self.signed = shape.signed
-        self.value  = self.normalize(self.value, shape)
+        if self.signed and self.value >> (self.width - 1):
+            self.value |= -(1 << self.width)
+        else:
+            self.value &= (1 << self.width) - 1
 
     def shape(self):
         return Shape(self.width, self.signed)

amaranth/lib/data.py

@@ -100,9 +100,10 @@ class Layout(ShapeCastable, metaclass=ABCMeta):
         """Convert ``value``, which may be a dict or an array of field values, to an integer using
         the representation defined by this layout.
 
-        This method is roughly equivalent to :meth:`Const.normalize`. It is private because
+        This method is private because Amaranth does not currently have a concept of
-        Amaranth does not currently have a concept of a constant initializer; this requires
+        a constant initializer; this requires an RFC. It will be renamed or removed
-        an RFC. It will be renamed or removed in a future version."""
+        in a future version.
+        """
         if isinstance(value, Mapping):
             iterator = value.items()
         elif isinstance(value, Sequence):
@@ -116,7 +117,7 @@ class Layout(ShapeCastable, metaclass=ABCMeta):
             field = self[key]
             if isinstance(field.shape, Layout):
                 key_value = field.shape._convert_to_int(key_value)
-            int_value |= Const.normalize(key_value, Shape.cast(field.shape)) << field.offset
+            int_value |= Const(key_value, Shape.cast(field.shape)).value << field.offset
         return int_value
 
 

amaranth/sim/_pycoro.py

@@ -69,7 +69,7 @@ class PyCoroProcess(BaseProcess):
                 if isinstance(command, Value):
                     exec(_RHSValueCompiler.compile(self.state, command, mode="curr"),
                         self.exec_locals)
-                    response = Const.normalize(self.exec_locals["result"], command.shape())
+                    response = Const(self.exec_locals["result"], command.shape()).value
 
                 elif isinstance(command, Statement):
                     exec(_StatementCompiler.compile(self.state, command),

docs/changes.rst

@@ -33,6 +33,7 @@ Language changes
 * Changed: :meth:`Value.cast` casts :class:`ValueCastable` objects recursively.
 * Changed: :meth:`Value.cast` treats instances of classes derived from both :class:`enum.Enum` and :class:`int` (including :class:`enum.IntEnum`) as enumerations rather than integers.
 * Changed: :class:`Cat` accepts instances of classes derived from both :class:`enum.Enum` and :class:`int` (including :class:`enum.IntEnum`) without warning.
+* Deprecated: :meth:`Const.normalize`.
 * Removed: (deprecated in 0.1) casting of :class:`Shape` to and from a ``(width, signed)`` tuple.
 * Removed: (deprecated in 0.3) :class:`ast.UserValue`.
 * Removed: (deprecated in 0.3) support for ``# nmigen:`` linter instructions at the beginning of file.