sim: Use Period to represent time.

Author: zyp

amaranth/sim/_async.py

@@ -2,6 +2,7 @@
 # Annoyingly, this means that the `sphinxcontrib.napoleon` style docstrings cannot be used, and
 # the Sphinx style docstrings must be used instead. I'm sorry.
 
+import warnings
 import typing
 import operator
 from contextlib import contextmanager
@@ -72,9 +73,18 @@ def __init__(self, interval):
         # Note: even though it is likely to be a bad idea, ``await ctx.delay(0)`` is accepted.
         # This is because, if disallowed, people are likely to do even worse things, such as
         # `await ctx.delay(1e-15)` instead.
-        if interval < 0:
+
+        if not isinstance(interval, Period):
+            # TODO(amaranth-0.7): remove
+            warnings.warn(
+                f"Per RFC 66, the `interval` argument of `DelayTrigger()` will only accept a `Period`"
+                f" in the future.",
+                DeprecationWarning, stacklevel=1)
+            interval = Period(s=interval)
+
+        if interval < Period():
             raise ValueError(f"Delay cannot be negative")
-        self.interval_fs = round(float(interval) * 1e15)
+        self.interval = interval
 
 
 class TriggerCombination:

amaranth/sim/_pycoro.py

@@ -102,10 +102,10 @@ def src_loc(coroutine):
                     raise TypeError(f"Command {command!r} is not allowed in testbenches")
 
                 elif type(command) is Settle:
-                    await context.delay(0)
+                    await context.delay(Period())
 
                 elif type(command) is Delay:
-                    await context.delay(command.interval or 0)
+                    await context.delay(Period(s=command.interval or 0))
 
                 elif type(command) is Passive:
                     context._process.critical = False

amaranth/sim/core.py

@@ -2,7 +2,7 @@
 import warnings
 
 from .._utils import deprecated
-from ..hdl import Value, ValueLike, MemoryData, ClockDomain, Fragment
+from ..hdl import Value, ValueLike, MemoryData, ClockDomain, Fragment, Period
 from ..hdl._ir import DriverConflict
 from ._base import BaseEngine
 from ._async import DomainReset, BrokenTrigger
@@ -35,8 +35,8 @@ class Simulator:
 
     2. Processes, clocks, and testbenches are added as necessary: ::
 
-        sim.add_clock(1e-6)
-        sim.add_clock(1e-7, domain="fast")
+        sim.add_clock(Period(MHz=1))
+        sim.add_clock(Period(MHz=10), domain="fast")
         sim.add_process(process_instr_decoder)
         sim.add_testbench(testbench_cpu_execute)
 
@@ -118,12 +118,25 @@ def add_clock(self, period, *, phase=None, domain="sync", if_exists=False):
         if domain in self._clocked:
             raise DriverConflict(f"Domain {domain.name!r} already has a clock driving it")
 
-        period_fs = _seconds_to_femtos(period)
+        if not isinstance(period, Period):
+            # TODO(amaranth-0.7): remove
+            warnings.warn(
+                f"Per RFC 66, the `period` argument of `add_clock()` will only accept a `Period`"
+                f" in the future.",
+                DeprecationWarning, stacklevel=1)
+            period = Period(s=period)
+
         if phase is None:
-            phase_fs = _seconds_to_femtos(period / 2)
-        else:
-            phase_fs = _seconds_to_femtos(phase)
-        self._engine.add_clock_process(domain.clk, phase=phase_fs, period=period_fs)
+            phase = period / 2
+        elif not isinstance(phase, Period):
+            # TODO(amaranth-0.7): remove
+            warnings.warn(
+                f"Per RFC 66, the `phase` argument of `add_clock()` will only accept a `Period`"
+                f" (or `None`) in the future.",
+                DeprecationWarning, stacklevel=1)
+            phase = Period(s=phase)
+
+        self._engine.add_clock_process(domain.clk, phase=phase.femtoseconds, period=period.femtoseconds)
         self._clocked.add(domain)
 
     @staticmethod
@@ -315,9 +328,17 @@ def run_until(self, deadline, *, run_passive=None):
                 f"The `run_passive` argument of `run_until()` has been removed as a part of "
                 f"transition to RFC 36.",
                 DeprecationWarning, stacklevel=1)
-        deadline_fs = _seconds_to_femtos(deadline)
-        assert self._engine.now <= deadline_fs
-        while self._engine.now < deadline_fs:
+
+        if not isinstance(deadline, Period):
+            # TODO(amaranth-0.7): remove
+            warnings.warn(
+                f"Per RFC 66, the `deadline` argument of `run_until()` will only accept a `Period`"
+                f" in the future.",
+                DeprecationWarning, stacklevel=1)
+            deadline = Period(s=deadline)
+
+        assert self._engine.now <= deadline.femtoseconds
+        while self._engine.now < deadline.femtoseconds:
             self.advance()
 
     def advance(self):

amaranth/sim/pysim.py

@@ -551,8 +551,8 @@ def waker():
                 return
             self._triggers_hit.add(trigger)
             self.activate()
-        self._engine.state.set_delay_waker(trigger.interval_fs, waker)
-        self._delay_wakers[waker] = trigger.interval_fs
+        self._engine.state.set_delay_waker(trigger.interval.femtoseconds, waker)
+        self._delay_wakers[waker] = trigger.interval.femtoseconds
 
     def activate(self):
         if self._combination._process.waits_on is self:

docs/_code/up_counter.py

@@ -43,7 +43,7 @@ def elaborate(self, platform):
 
         return m
 # --- TEST ---
-from amaranth.sim import Simulator
+from amaranth.sim import Simulator, Period
 
 
 dut = UpCounter(25)
@@ -68,7 +68,7 @@ async def bench(ctx):
 
 
 sim = Simulator(dut)
-sim.add_clock(1e-6) # 1 MHz
+sim.add_clock(Period(MHz=1))
 sim.add_testbench(bench)
 with sim.write_vcd("up_counter.vcd"):
     sim.run()

docs/simulator.rst

@@ -48,7 +48,7 @@ Simulating a design always requires the three basic steps: constructing the :abb
 
 .. testcode::
 
-    from amaranth.sim import Simulator
+    from amaranth.sim import Simulator, Period
 
     dut = Counter()
     sim = Simulator(dut)
@@ -69,9 +69,9 @@ The following code simulates a design and capture the values of all the signals
 
     dut = Counter()
     sim = Simulator(dut)
-    sim.add_clock(1e-6) # 1 µs period, or 1 MHz
+    sim.add_clock(Period(MHz=1)) # 1 µs period, or 1 MHz
     with sim.write_vcd("example1.vcd"):
-        sim.run_until(1e-6 * 15) # 15 periods of the clock
+        sim.run_until(Period(MHz=1) * 15) # 15 periods of the clock
 
 The captured data is saved to a :abbr:`VCD` file :file:`example1.vcd`, which can be displayed with a *waveform viewer* such as Surfer_ or GTKWave_:
 
@@ -122,10 +122,10 @@ The following example simulates a counter and verifies that it can be stopped us
         ctx.set(dut.en, True)          # assert `dut.en`, enabling the counter again
 
     sim = Simulator(dut)
-    sim.add_clock(1e-6)
+    sim.add_clock(Period(MHz=1))
     sim.add_testbench(testbench_example2) # add the testbench; run_until() calls the function
     with sim.write_vcd("example2.vcd"):
-        sim.run_until(1e-6 * 15)
+        sim.run_until(Period(MHz=1) * 15)
 
 Since this circuit is synchronous, and the :meth:`ctx.tick() <SimulatorContext.tick>` method waits until after the circuit has reacted to the clock edge, the change to the :py:`en` input affects the behavior of the circuit on the next clock cycle after the change:
 
@@ -155,17 +155,17 @@ The following example simulates an adder:
     dut = Adder()
 
     async def testbench_example3(ctx):
-        await ctx.delay(1e-6)
+        await ctx.delay(Period(us=1))
         ctx.set(dut.a, 2)
         ctx.set(dut.b, 2)
         assert ctx.get(dut.o) == 4
 
-        await ctx.delay(1e-6)
+        await ctx.delay(Period(us=1))
         ctx.set(dut.a, 1717)
         ctx.set(dut.b, 420)
         assert ctx.get(dut.o) == 2137
 
-        await ctx.delay(2e-6)
+        await ctx.delay(Period(us=2))
 
     sim = Simulator(dut)
     sim.add_testbench(testbench_example3)
@@ -234,7 +234,7 @@ The following code replaces the :py:`Counter` elaboratable with the equivalent P
         ctx.set(en, True)
 
     sim = Simulator(m)
-    sim.add_clock(1e-6)
+    sim.add_clock(Period(MHz=1))
     sim.add_process(process_example4)
     sim.add_testbench(testbench_example4)
     with sim.write_vcd("example4.vcd", traces=(cd_sync.clk, cd_sync.rst, en, count)):
@@ -262,17 +262,17 @@ The following code replaces the :py:`Adder` elaboratable with the equivalent Pyt
             ctx.set(o, a_value + b_value)
 
     async def testbench_example5(ctx):
-        await ctx.delay(1e-6)
+        await ctx.delay(Period(us=1))
         ctx.set(a, 2)
         ctx.set(b, 2)
         assert ctx.get(o) == 4
 
-        await ctx.delay(1e-6)
+        await ctx.delay(Period(us=1))
         ctx.set(a, 1717)
         ctx.set(b, 420)
         assert ctx.get(o) == 2137
 
-        await ctx.delay(2e-6)
+        await ctx.delay(Period(us=2))
 
     sim = Simulator(m)
     sim.add_process(process_example5)

docs/stdlib/io.rst

@@ -60,7 +60,7 @@ All of the following examples assume that one of the built-in FPGA platforms is
 
 .. testcode::
 
-    from amaranth.sim import Simulator
+    from amaranth.sim import Simulator, Period
     from amaranth.lib import io, wiring, stream
     from amaranth.lib.wiring import In, Out
 
@@ -249,7 +249,7 @@ For example, consider a simple serializer that accepts a stream of multi-bit dat
                 assert dout_value == bit, "DUT drives the wrong value on data output"
 
         sim = Simulator(dut)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         sim.add_testbench(testbench_write_data)
         sim.add_testbench(testbench_sample_output)
         sim.run()

docs/stdlib/stream.rst

@@ -59,7 +59,7 @@ The pipeline is tested using the :doc:`built-in simulator </simulator>` and the
 
 .. testcode::
 
-    from amaranth.sim import Simulator
+    from amaranth.sim import Simulator, Period
 
     async def stream_get(ctx, stream):
         ctx.set(stream.ready, 1)
@@ -150,7 +150,7 @@ In this example, the external device does not provide a way to pause data transm
                 f"{payload & 0xff:08b} != {expected_word & 0xff:08b} (expected)"
 
         sim = Simulator(dut)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         sim.add_testbench(testbench_input)
         sim.add_testbench(testbench_output)
         with sim.write_vcd("stream_serial_receiver.vcd"):
@@ -244,7 +244,7 @@ The serial transmitter accepts a stream of words and provides it to the serial i
             await ctx.tick()
 
         sim = Simulator(dut)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         sim.add_testbench(testbench_input)
         sim.add_testbench(testbench_output)
         with sim.write_vcd("stream_serial_transmitter.vcd"):
@@ -293,7 +293,7 @@ The value negator accepts a stream of words, negates the 2's complement value of
             assert await stream_get(ctx, dut.o_stream) == -17
 
         sim = Simulator(dut)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         sim.add_testbench(testbench_input)
         sim.add_testbench(testbench_output)
         with sim.write_vcd("stream_value_negator.vcd"):
@@ -388,7 +388,7 @@ The complete pipeline consists of a serial receiver, a value negator, a FIFO que
             ctx.set(dut.o_ssel, 0)
 
         sim = Simulator(dut)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         sim.add_testbench(testbench_input)
         sim.add_testbench(testbench_output)
         with sim.write_vcd("stream_example_pipeline.vcd"):

examples/basic/ctr_en.py

@@ -25,7 +25,7 @@ def elaborate(self, platform):
 print(verilog.convert(ctr))
 
 sim = Simulator(ctr)
-sim.add_clock(1e-6)
+sim.add_clock(Period(MHz=1))
 async def testbench_ce(ctx):
     await ctx.tick().repeat(3)
     ctx.set(ctr.en, 1)
@@ -35,4 +35,4 @@ async def testbench_ce(ctx):
     ctx.set(ctr.en,1)
 sim.add_testbench(testbench_ce)
 with sim.write_vcd("ctrl.vcd", "ctrl.gtkw", traces=[ctr.en, ctr.v, ctr.o]):
-    sim.run_until(100e-6)
+    sim.run_until(Period(us=100))

examples/basic/uart.py

@@ -104,10 +104,10 @@ def elaborate(self, platform):
 
     args = parser.parse_args()
     if args.action == "simulate":
-        from amaranth.sim import Simulator, Passive
+        from amaranth.sim import Simulator, Passive, Period
 
         sim = Simulator(uart)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
 
         async def testbench_loopback(ctx):
             async for val in ctx.changed(uart.tx_o):

tests/test_lib_cdc.py

@@ -22,7 +22,7 @@ def test_basic(self):
         frag = FFSynchronizer(i, o)
 
         sim = Simulator(frag)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             self.assertEqual(ctx.get(o), 0)
             ctx.set(i, 1)
@@ -39,7 +39,7 @@ def test_init_value(self):
         frag = FFSynchronizer(i, o, init=1)
 
         sim = Simulator(frag)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             self.assertEqual(ctx.get(o), 1)
             ctx.set(i, 0)
@@ -58,7 +58,7 @@ def test_reset_value(self):
             frag = FFSynchronizer(i, o, reset=1)
 
         sim = Simulator(frag)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             self.assertEqual(ctx.get(o), 1)
             ctx.set(i, 0)
@@ -107,7 +107,7 @@ def test_pos_edge(self):
         m.submodules += AsyncFFSynchronizer(i, o)
 
         sim = Simulator(m)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             # initial reset
             self.assertEqual(ctx.get(i), 0)
@@ -144,7 +144,7 @@ def test_neg_edge(self):
         m.submodules += AsyncFFSynchronizer(i, o, async_edge="neg")
 
         sim = Simulator(m)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             # initial reset
             self.assertEqual(ctx.get(i), 1)
@@ -192,7 +192,7 @@ def test_basic(self):
         m.d.sync += s.eq(0)
 
         sim = Simulator(m)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             # initial reset
             self.assertEqual(ctx.get(s), 1)
@@ -237,7 +237,7 @@ def test_smoke(self):
         ps = m.submodules.dut = PulseSynchronizer("sync", "sync")
 
         sim = Simulator(m)
-        sim.add_clock(1e-6)
+        sim.add_clock(Period(MHz=1))
         async def testbench(ctx):
             ctx.set(ps.i, 0)
             # TODO: think about reset