Implement RFC 66: Simulation time.

amaranth/build/dsl.py

@@ -1,8 +1,11 @@
+import warnings
+
 from collections import OrderedDict
+from ..hdl import Period
 
 
 __all__ = ["Pins", "PinsN", "DiffPairs", "DiffPairsN",
-           "Attrs", "Clock", "Subsignal", "Resource", "Connector"]
+           "Attrs", "Clock", "Subsignal", "Resource", "Connector", "Period"]
 
 
 class Pins:
@@ -107,18 +110,39 @@ def __repr__(self):
 
 
 class Clock:
-    def __init__(self, frequency):
-        if not isinstance(frequency, (float, int)):
-            raise TypeError("Clock frequency must be a number")
-
-        self.frequency = float(frequency)
+    def __init__(self, period=None, frequency=None):
+        # TODO(amaranth-0.7): remove
+        if (period is None) == (frequency is None):
+            raise TypeError("Exactly one of the `period` or `frequency` arguments must be specified.")
+
+        if frequency is not None:
+            warnings.warn(
+                f"`frequency=` is deprecated, use `period=` instead",
+                DeprecationWarning, stacklevel=1)
+            period = Period(Hz=frequency)
+
+        if not isinstance(period, Period):
+            warnings.warn(
+                f"Per RFC 66, `Clock()` will only accept a `Period` in the future.",
+                DeprecationWarning, stacklevel=1)
+            period = Period(Hz=period)
+
+        self._period = period
 
     @property
     def period(self):
-        return 1 / self.frequency
+        return self._period
+
+    # TODO(amaranth-0.7): remove
+    @property
+    def frequency(self):
+        warnings.warn(
+            f"Per RFC 66, `Clock.frequency` is deprecated.  Use `Clock.period` instead.",
+            DeprecationWarning, stacklevel=1)
+        return self._period.hertz
 
     def __repr__(self):
-        return f"(clock {self.frequency})"
+        return f"(clock {self._period.hertz})"
 
 
 class Subsignal:

amaranth/build/plat.py

@@ -5,6 +5,7 @@
 import textwrap
 import re
 import jinja2
+import warnings
 
 from .. import __version__
 from .._toolchain import *
@@ -45,11 +46,25 @@ def default_clk_constraint(self):
 
     @property
     def default_clk_frequency(self):
+        # TODO(amaranth-0.7): remove
+        warnings.warn(
+            f"Per RFC 66, `default_clk_frequency` is deprecated. Use `default_clk_period` instead."
+            f" instead.",
+            DeprecationWarning, stacklevel=1)
+
+        constraint = self.default_clk_constraint
+        if constraint is None:
+            raise AttributeError("Platform '{}' does not constrain its default clock"
+                                 .format(type(self).__qualname__))
+        return constraint.period.hertz
+
+    @property
+    def default_clk_period(self):
         constraint = self.default_clk_constraint
         if constraint is None:
             raise AttributeError("Platform '{}' does not constrain its default clock"
                                  .format(type(self).__qualname__))
-        return constraint.frequency
+        return constraint.period
 
     def add_file(self, filename, content):
         if not isinstance(filename, str):

amaranth/build/res.py

@@ -222,7 +222,7 @@ def resolve(resource, dir, xdr, path, attrs):
                     ])
                     port = io.SingleEndedPort(iop, invert=phys.invert, direction=direction)
                     if resource.clock is not None:
-                        self.add_clock_constraint(iop, resource.clock.frequency)
+                        self.add_clock_constraint(iop, resource.clock.period)
                 if isinstance(phys, DiffPairs):
                     phys_names_p = phys.p.map_names(self._conn_pins, resource)
                     phys_names_n = phys.n.map_names(self._conn_pins, resource)
@@ -237,7 +237,7 @@ def resolve(resource, dir, xdr, path, attrs):
                     ])
                     port = io.DifferentialPort(p, n, invert=phys.invert, direction=direction)
                     if resource.clock is not None:
-                        self.add_clock_constraint(p, resource.clock.frequency)
+                        self.add_clock_constraint(p, resource.clock.period)
                 for phys_name in phys_names:
                     if phys_name in self._phys_reqd:
                         raise ResourceError("Resource component {} uses physical pin {}, but it "
@@ -273,22 +273,36 @@ def resolve(resource, dir, xdr, path, attrs):
     def iter_pins(self):
         yield from self._pins
 
-    def add_clock_constraint(self, clock, frequency):
+    def add_clock_constraint(self, clock, period=None, frequency=None):
+        # TODO(amaranth-0.7): remove
+        if (period is None) == (frequency is None):
+            raise TypeError("Exactly one of the `period` or `frequency` arguments must be specified.")
+
+        if frequency is not None:
+            warnings.warn(
+                f"`frequency=` is deprecated, use `period=` instead",
+                DeprecationWarning, stacklevel=1)
+            period = Period(Hz=frequency)
+
+        if not isinstance(period, Period):
+            warnings.warn(
+                f"Per RFC 66, `add_clock_constraint()` will only accept a `Period` in the future.",
+                DeprecationWarning, stacklevel=1)
+            period = Period(Hz=period)
+
         if isinstance(clock, ClockSignal):
             raise TypeError(f"A clock constraint can only be applied to a Signal, but a "
                             f"ClockSignal is provided; assign the ClockSignal to an "
                             f"intermediate signal and constrain the latter instead.")
         elif not isinstance(clock, (Signal, IOPort)):
             raise TypeError(f"Object {clock!r} is not a Signal or IOPort")
-        if not isinstance(frequency, (int, float)):
-            raise TypeError(f"Frequency must be a number, not {frequency!r}")
 
         if isinstance(clock, IOPort):
             clocks = self._io_clocks
         else:
             clocks = self._clocks
 
-        frequency = float(frequency)
+        frequency = period.hertz
         if clock in clocks and clocks[clock] != frequency:
             raise ValueError("Cannot add clock constraint on {!r}, which is already constrained "
                              "to {} Hz"

amaranth/hdl/__init__.py

@@ -10,6 +10,7 @@
 from ._ir import Instance, IOBufferInstance
 from ._mem import MemoryData, MemoryInstance
 from ._nir import CombinationalCycle
+from ._time import Period
 from ._xfrm import DomainRenamer, ResetInserter, EnableInserter
 
 
@@ -32,6 +33,8 @@
     "CombinationalCycle",
     # _mem
     "MemoryData", "MemoryInstance",
+    # _time
+    "Period",
     # _xfrm
     "DomainRenamer", "ResetInserter", "EnableInserter",
 ]