Deploying to main from @ amaranth-lang/amaranth@5a6ceec 🚀

Author: github-merge-queue[bot]

docs/amaranth/latest/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 8a742aa9ed59343fa8ddfc65bff03707
+config: 9d1ff2d69a43f21ccdef9ee0509e3140
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/amaranth/latest/.doctrees/changes.doctree

@@ -1,7 +1,7 @@
 Changelog
 #########
 
-This document describes changes to the public interfaces in the Amaranth language and standard library. It does not include most bug fixes or implementation changes.
+This document describes changes to the public interfaces in the Amaranth language and standard library. It does not include most bug fixes or implementation changes; versions which do not include notable changes are not listed here.
 
 
 Documentation for past releases
@@ -19,8 +19,8 @@ Documentation for past releases of the Amaranth language and toolchain is availa
 * `Amaranth 0.3 <https://amaranth-lang.org/docs/amaranth/v0.3/>`_
 
 
-Version 0.6 (unreleased)
-========================
+Version 0.6.0 (unreleased)
+==========================
 
 
 Language changes
@@ -30,12 +30,12 @@ Language changes
 
 * 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) :class:`Record`.
-* Removed: (deprecated in 0.5) :class:`Memory` (`RFC 45`_)
-* Removed: (deprecated in 0.5) public submodules of :mod:`amaranth.hdl`.
-* Removed: (deprecated in 0.5) :meth:`Value.implies`.
-* Removed: (deprecated in 0.5) :meth:`Const.width`, :meth:`Const.signed`, :meth:`Signal.width`, :meth:`Signal.signed`.
-* Removed: (deprecated in 0.5) upwards propagation of clock domains. (`RFC 59`_)
+* Removed: (deprecated in 0.4.0) :class:`Record`.
+* Removed: (deprecated in 0.5.0) :class:`Memory` (`RFC 45`_)
+* Removed: (deprecated in 0.5.0) public submodules of :mod:`amaranth.hdl`.
+* Removed: (deprecated in 0.5.0) :meth:`Value.implies`.
+* Removed: (deprecated in 0.5.0) :meth:`Const.width`, :meth:`Const.signed`, :meth:`Signal.width`, :meth:`Signal.signed`.
+* Removed: (deprecated in 0.5.0) upwards propagation of clock domains. (`RFC 59`_)
 
 
 Standard library changes
@@ -44,13 +44,22 @@ Standard library changes
 .. currentmodule:: amaranth.lib
 
 * Added: :py:`payload_init=` argument in :class:`amaranth.lib.stream.Signature`.
-* Removed: (deprecated in 0.5) :mod:`amaranth.lib.coding`. (`RFC 63`_)
+* Changed: (deprecated in 0.5.1) providing :meth:`io.PortLike.__add__` is now mandatory. (`RFC 69`_)
+* Removed: (deprecated in 0.5.0) :mod:`amaranth.lib.coding`. (`RFC 63`_)
 
 
 Version 0.5.1
 =============
 
 
+Implemented RFCs
+----------------
+
+.. _RFC 69: https://amaranth-lang.org/rfcs/0069-simulation-port.html
+
+* `RFC 69`_: Add a ``lib.io.PortLike`` object usable in simulation
+
+
 Standard library changes
 ------------------------
 
@@ -59,10 +68,11 @@ Standard library changes
 * Added: views of :class:`amaranth.lib.data.ArrayLayout` can be indexed with negative integers or slices.
 * Added: :py:`len()` works on views of :class:`amaranth.lib.data.ArrayLayout`.
 * Added: views of :class:`amaranth.lib.data.ArrayLayout` are iterable.
+* Added: :class:`io.SimulationPort`. (`RFC 69`_)
 
 
-Version 0.5
-===========
+Version 0.5.0
+=============
 
 The Migen compatibility layer has been removed.
 
@@ -161,9 +171,9 @@ Language changes
 * Deprecated: :class:`amaranth.hdl.Memory`. (`RFC 45`_)
 * Deprecated: upwards propagation of clock domains. (`RFC 59`_)
 * Deprecated: :meth:`Value.implies`.
-* Removed: (deprecated in 0.4) :meth:`Const.normalize`. (`RFC 5`_)
-* Removed: (deprecated in 0.4) :class:`Repl`. (`RFC 10`_)
-* Removed: (deprecated in 0.4) :class:`ast.Sample`, :class:`ast.Past`, :class:`ast.Stable`, :class:`ast.Rose`, :class:`ast.Fell`.
+* Removed: (deprecated in 0.4.0) :meth:`Const.normalize`. (`RFC 5`_)
+* Removed: (deprecated in 0.4.0) :class:`Repl`. (`RFC 10`_)
+* Removed: (deprecated in 0.4.0) :class:`ast.Sample`, :class:`ast.Past`, :class:`ast.Stable`, :class:`ast.Rose`, :class:`ast.Fell`.
 * Removed: assertion names in :class:`Assert`, :class:`Assume` and :class:`Cover`. (`RFC 50`_)
 * Removed: accepting non-subclasses of :class:`Elaboratable` as elaboratables.
 
@@ -182,9 +192,9 @@ Standard library changes
 * Added: :mod:`amaranth.lib.meta`, :class:`amaranth.lib.wiring.ComponentMetadata`. (`RFC 30`_)
 * Added: :mod:`amaranth.lib.stream`. (`RFC 61`_)
 * Deprecated: :mod:`amaranth.lib.coding`. (`RFC 63`_)
-* Removed: (deprecated in 0.4) :mod:`amaranth.lib.scheduler`. (`RFC 19`_)
-* Removed: (deprecated in 0.4) :class:`amaranth.lib.fifo.FIFOInterface` with :py:`fwft=False`. (`RFC 20`_)
-* Removed: (deprecated in 0.4) :class:`amaranth.lib.fifo.SyncFIFO` with :py:`fwft=False`. (`RFC 20`_)
+* Removed: (deprecated in 0.4.0) :mod:`amaranth.lib.scheduler`. (`RFC 19`_)
+* Removed: (deprecated in 0.4.0) :class:`amaranth.lib.fifo.FIFOInterface` with :py:`fwft=False`. (`RFC 20`_)
+* Removed: (deprecated in 0.4.0) :class:`amaranth.lib.fifo.SyncFIFO` with :py:`fwft=False`. (`RFC 20`_)
 
 
 Toolchain changes
@@ -199,7 +209,7 @@ Toolchain changes
 * Deprecated: :py:`Simulator.add_sync_process`. (`RFC 27`_)
 * Deprecated: generator-based simulation processes and testbenches. (`RFC 36`_)
 * Deprecated: the :py:`run_passive` argument to :meth:`Simulator.run_until <amaranth.sim.Simulator.run_until>` has been deprecated, and does nothing.
-* Removed: (deprecated in 0.4) use of mixed-case toolchain environment variable names, such as ``NMIGEN_ENV_Diamond`` or ``AMARANTH_ENV_Diamond``; use upper-case environment variable names, such as ``AMARANTH_ENV_DIAMOND``.
+* Removed: (deprecated in 0.4.0) use of mixed-case toolchain environment variable names, such as ``NMIGEN_ENV_Diamond`` or ``AMARANTH_ENV_Diamond``; use upper-case environment variable names, such as ``AMARANTH_ENV_DIAMOND``.
 
 
 Platform integration changes
@@ -212,11 +222,11 @@ Platform integration changes
 * Added: ``build.sh``  begins with ``#!/bin/sh``.
 * Changed: ``IntelPlatform`` renamed to ``AlteraPlatform``.
 * Deprecated: argument :py:`run_script=` in :meth:`BuildPlan.execute_local`.
-* Removed: (deprecated in 0.4) :mod:`vendor.intel`, :mod:`vendor.lattice_ecp5`, :mod:`vendor.lattice_ice40`, :mod:`vendor.lattice_machxo2_3l`, :mod:`vendor.quicklogic`, :mod:`vendor.xilinx`. (`RFC 18`_)
+* Removed: (deprecated in 0.4.0) :mod:`vendor.intel`, :mod:`vendor.lattice_ecp5`, :mod:`vendor.lattice_ice40`, :mod:`vendor.lattice_machxo2_3l`, :mod:`vendor.quicklogic`, :mod:`vendor.xilinx`. (`RFC 18`_)
 
 
-Version 0.4
-===========
+Version 0.4.0
+=============
 
 Support has been added for a new and improved way of defining data structures in :mod:`amaranth.lib.data` and component interfaces in :mod:`amaranth.lib.wiring`, as defined in `RFC 1`_ and `RFC 2`_. :class:`Record` has been deprecated. In a departure from the usual policy, to give designers additional time to migrate, :class:`Record` will be removed in Amaranth 0.6 (one release later than normal).
 

docs/amaranth/latest/.doctrees/environment.pickle

@@ -60,7 +60,8 @@ All of the following examples assume that one of the built-in FPGA platforms is
 
 .. testcode::
 
-    from amaranth.lib import io, wiring
+    from amaranth.sim import Simulator
+    from amaranth.lib import io, wiring, stream
     from amaranth.lib.wiring import In, Out
 
 
@@ -191,6 +192,74 @@ In this example of a `source-synchronous interface <https://en.wikipedia.org/wik
 This component transmits :py:`dout` on each cycle as two halves: the low 8 bits on the rising edge of the data clock, and the high 8 bits on the falling edge of the data clock. The transmission is *edge-aligned*, meaning that the data edges exactly coincide with the clock edges.
 
 
+Simulation
+----------
+
+The Amaranth simulator, :mod:`amaranth.sim`, cannot simulate :ref:`core I/O values <lang-iovalues>` or :ref:`I/O buffer instances <lang-iobufferinstance>` as it only operates on unidirectionally driven two-state wires. This module provides a simulation-only library I/O port, :class:`SimulationPort`, so that components that use library I/O buffers can be tested.
+
+A component that is designed for testing should accept the library I/O ports it will drive as constructor parameters rather than requesting them from the platform directly. Synthesizable designs will instantiate the component with a :class:`SingleEndedPort`, :class:`DifferentialPort`, or a platform-specific library I/O port, while tests will instantiate the component with a :class:`SimulationPort`. Tests are able to inject inputs into the component using :py:`sim_port.i`, capture the outputs of the component via :py:`sim_port.o`, and ensure that the component is driving the outputs at the appropriate times using :py:`sim_port.oe`.
+
+For example, consider a simple serializer that accepts a stream of multi-bit data words and outputs them bit by bit. It can be tested as follows:
+
+.. testcode::
+
+    class OutputSerializer(wiring.Component):
+        data: In(stream.Signature(8))
+
+        def __init__(self, dclk_port, dout_port):
+            self.dclk_port = dclk_port
+            self.dout_port = dout_port
+
+            super().__init__()
+
+        def elaborate(self, platform):
+            m = Module()
+
+            m.submodules.dclk = dclk = io.Buffer("o", self.dclk_port)
+            m.submodules.dout = dout = io.Buffer("o", self.dout_port)
+
+            index = Signal(range(8))
+            m.d.comb += dout.o.eq(self.data.payload.bit_select(index, 1))
+
+            with m.If(self.data.valid):
+                m.d.sync += dclk.o.eq(~dclk.o)
+                with m.If(dclk.o):
+                    m.d.sync += index.eq(index + 1)
+                    with m.If(index == 7):
+                        m.d.comb += self.data.ready.eq(1)
+
+            return m
+
+    def test_output_serializer():
+        dclk_port = io.SimulationPort("o", 1)
+        dout_port = io.SimulationPort("o", 1)
+
+        dut = OutputSerializer(dclk_port, dout_port)
+
+        async def testbench_write_data(ctx):
+            ctx.set(dut.data.payload, 0xA1)
+            ctx.set(dut.data.valid, 1)
+            await ctx.tick().until(dut.data.ready)
+            ctx.set(dut.data.valid, 0)
+
+        async def testbench_sample_output(ctx):
+            for bit in [1,0,0,0,0,1,0,1]:
+                _, dout_value = await ctx.posedge(dut.dclk_port.o).sample(dut.dout_port.o)
+                assert ctx.get(dut.dout_port.oe) == 1, "DUT is not driving the data output"
+                assert dout_value == bit, "DUT drives the wrong value on data output"
+
+        sim = Simulator(dut)
+        sim.add_clock(1e-6)
+        sim.add_testbench(testbench_write_data)
+        sim.add_testbench(testbench_sample_output)
+        sim.run()
+
+.. testcode::
+    :hide:
+
+    test_output_serializer()
+
+
 Ports
 -----
 
@@ -199,6 +268,7 @@ Ports
 .. autoclass:: PortLike
 .. autoclass:: SingleEndedPort
 .. autoclass:: DifferentialPort
+.. autoclass:: SimulationPort
 
 
 Buffers

docs/amaranth/latest/.doctrees/stdlib/io.doctree

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