Deploying to main from @ amaranth-lang/amaranth@c609025 🚀

Author: github-merge-queue[bot]

docs/amaranth/latest/_code/led_blinker.py

@@ -7,7 +7,7 @@ def elaborate(self, platform):
 
         led = platform.request("led")
 
-        half_freq = int(platform.default_clk_frequency // 2)
+        half_freq = int(platform.default_clk_period.hertz // 2)
         timer = Signal(range(half_freq + 1))
 
         with m.If(timer == half_freq):

docs/amaranth/latest/_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/amaranth/latest/_downloads/9916e1f0618daa91d3860f1bdac16820/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/amaranth/latest/_sources/changes.rst.txt

@@ -26,8 +26,10 @@ Version 0.6.0 (unreleased)
 Implemented RFCs
 ----------------
 
+.. _RFC 66: https://amaranth-lang.org/rfcs/0066-simulation-time.html
 .. _RFC 71: https://amaranth-lang.org/rfcs/0071-enumview-matches.html
 
+* `RFC 66`_: Simulation time
 * `RFC 71`_: ``EnumView.matches``
 
 
@@ -36,6 +38,7 @@ Language changes
 
 .. currentmodule:: amaranth.hdl
 
+* Added: :class:`Period` for representing time periods. (`RFC 66`_)
 * Changed: overriding :meth:`ValueCastable.from_bits` is now mandatory. (`RFC 51`_)
 * Deprecated: the :py:`local=` argument to :class:`ClockDomain`. (`RFC 59`_)
 * Removed: (deprecated in 0.4.0) :class:`Record`.
@@ -58,6 +61,24 @@ Standard library changes
 * Removed: (deprecated in 0.5.0) :mod:`amaranth.lib.coding`. (`RFC 63`_)
 
 
+Toolchain changes
+-----------------
+
+* Added: :meth:`SimulatorContext.elapsed_time <amaranth.sim._async.SimulatorContext.elapsed_time>` for getting elapsed simulation time. (`RFC 66`_)
+* Added: :meth:`Platform.default_clk_period <amaranth.build.plat.Platform.default_clk_period>`. (`RFC 66`_)
+* Changed: :meth:`Simulator.add_clock <amaranth.sim.Simulator.add_clock>` now accepts a :class:`Period <amaranth.hdl.Period>` for :py:`period` and :py:`phase`. (`RFC 66`_)
+* Changed: :meth:`Simulator.run_until <amaranth.sim.Simulator.run_until>` now accepts a :class:`Period <amaranth.hdl.Period>` for :py:`deadline`. (`RFC 66`_)
+* Changed: :meth:`SimulatorContext.delay <amaranth.sim._async.SimulatorContext.delay>` now accepts a :class:`Period <amaranth.hdl.Period>` for :py:`interval`. (`RFC 66`_)
+* Changed: :meth:`ResourceManager.add_clock_constraint <amaranth.build.res.ResourceManager.add_clock_constraint>` now accepts a :class:`Period <amaranth.hdl.Period>` for :py:`period`. (`RFC 66`_)
+* Changed: :class:`Clock <amaranth.build.dsl.Clock>` now accepts a :class:`Period <amaranth.hdl.Period>` for :py:`period`. (`RFC 66`_)
+* Changed: :attr:`Clock.period <amaranth.build.dsl.Clock.period>` now returns a :class:`Period <amaranth.hdl.Period>`. (`RFC 66`_)
+* Deprecated: Passing a :class:`float` of seconds or hertz to any of the methods/arguments now accepting a :class:`Period <amaranth.hdl.Period>`. (`RFC 66`_)
+* Deprecated: Passing :py:`frequency=` to :meth:`ResourceManager.add_clock_constraint <amaranth.build.res.ResourceManager.add_clock_constraint>`. (`RFC 66`_)
+* Deprecated: Passing :py:`frequency=` to :class:`Clock <amaranth.build.dsl.Clock>`. (`RFC 66`_)
+* Deprecated: :attr:`Clock.frequency <amaranth.build.dsl.Clock.frequency>`. (`RFC 66`_)
+* Deprecated: :meth:`Platform.default_clk_frequency <amaranth.build.plat.Platform.default_clk_frequency>`. (`RFC 66`_)
+
+
 Platform integration changes
 ----------------------------
 

docs/amaranth/latest/_sources/simulator.rst.txt

@@ -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/amaranth/latest/_sources/stdlib/io.rst.txt

@@ -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/amaranth/latest/_sources/stdlib/stream.rst.txt

@@ -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"):

docs/amaranth/latest/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.6.0.dev57',
+    VERSION: '0.6.0.dev64',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',