Add an RFC for async testbench functions.

Author: zyp

text/0000-async-testbench-functions.md

@@ -0,0 +1,167 @@
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- RFC PR: [amaranth-lang/rfcs#0000](https://github.com/amaranth-lang/rfcs/pull/0000)
+- Amaranth Issue: [amaranth-lang/amaranth#0000](https://github.com/amaranth-lang/amaranth/issues/0000)
+
+Note: This draft makes references to additions from RFC #27 and assumes it is merged first.
+
+# Async testbench functions
+
+## Summary
+[summary]: #summary
+
+Introduce an improved simulator testbench interface using `async`/`await` style coroutines.
+
+## Motivation
+[motivation]: #motivation
+
+For the purpose of writing a testbench, an `async` function will read more naturally than a generator function, especially when calling subfunctions/methods.
+
+A more expressive way to specify trigger/wait conditions allows the condition checking to be offloaded to the simulator engine, only returning control to the testbench process when it has work to do.
+
+Passing a simulator context to the testbench function provides a convenient place to gather all simulator operations.
+
+Having `.get()` and `.set()` methods provides a convenient way for value castables to implement these in a type-specific manner.
+
+## Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+As an example, let's consider a simple stream interface with `valid`, `ready` and `data` members.
+On the interface class, we can then implement `.send()` and `.recv()` methods like this:
+
+```python
+class StreamInterface(PureInterface):
+    async def recv(self, sim):
+        await self.ready.set(1)
+        await sim.tick().until(self.valid)
+
+        value = await self.data.get()
+
+        await sim.tick()
+        await self.ready.set(0)
+
+        return value
+
+    async def send(self, sim, value):
+        await self.data.set(value)
+
+        await self.valid.set(1)
+        await sim.tick().until(self.ready)
+
+        await sim.tick()
+        await self.valid.set(0)
+```
+
+`sim.tick()` replaces the existing `Tick()`. It returns a trigger object that either can be awaited directly, or made conditional through `.until()`.
+
+Using this stream interface, let's consider a colorspace converter accepting a stream of RGB values and outputting a stream of YUV values:
+
+```python
+class RGBToYUVConverter(Component):
+    input: In(StreamSignature(RGB888))
+    output: Out(StreamSignature(YUV888))
+```
+
+A testbench could then look like this:
+
+```python
+async def test_rgb(sim, r, g, b):
+    rgb = {'r': r, 'g': g, 'b': b}
+    await dut.input.send(sim, rgb)
+    yuv = await dut.output.recv(sim)
+
+    print(rgb, yuv)
+
+async def testbench(sim):
+    await test_rgb(sim, 0, 0, 0)
+    await test_rgb(sim, 255, 0, 0)
+    await test_rgb(sim, 0, 255, 0)
+    await test_rgb(sim, 0, 0, 255)
+    await test_rgb(sim, 255, 255, 255)
+```
+
+Since `.send()` and `.recv()` invokes `.get()` and `.set()` that a value castable (here `data.View`) can implement in a suitable manner, it is general enough to work for streams with arbitrary shapes.
+
+`Tick()` and `Delay()` are replaced by `sim.tick()` and `sim.delay()` respectively.
+In addition, `sim.changed()` is introduced that allows creating triggers from arbitrary signals.
+These all return a trigger object that can be made conditional through `.until()`.
+
+`Active()` and `Passive()` are replaced by an `passive=False` keyword argument to `.add_process()`, `.add_sync_process()` and `.add_testbench()`.
+To mark a passive testbench temporarily active, `sim.active()` is introduced, which is used as a context manager:
+
+```python
+async def packet_reader(sim, stream):
+    while True
+        # Wait until stream has valid data.
+        await sim.tick().until(stream.valid)
+
+        # Go active to ensure simulation doesn't end in the middle of a packet.
+        with sim.active():
+            packet = await stream.read_packet()
+            print('Received packet:', packet.hex(' '))
+```
+
+TBD: Does this need to be an async context manager?
+
+## Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+The following `Simulator` methods have their signatures updated:
+
+* `add_process(process, *, passive=False)`
+* `add_sync_process(process, *, domain="sync", passive=False)`
+* `add_testbench(process, *, domain="sync", passive=False)` (TBD: RFC #27: Does `domain` default to `None` or `"sync"` here?)
+
+The new optional named argument `passive` registers the testbench as passive when true.
+
+All three methods are updated to accept an async function passed as `process`. When the function passed to `process` accepts an argument named `sim`, it will be passed a simulator context.
+
+The simulator context have the following methods:
+- `delay(interval=None)`
+  - Return a trigger object for advancing simulation by `interval` seconds.
+- `tick(domain=None)`
+  - Return a trigger object for advancing simulation by one tick of `domain`. `domain` defaults to the argument given to `add_sync_process()` or `add_testbench()` if not specified.
+- `changed(signal, value=None)`
+  - Return a trigger object for advancing simulation until `signal` is changed to `value`. `None` is a wildcard and will trigger on any change.
+- `active()`
+  - Return a context manager that temporarily marks the testbench as active for the duration.
+- `time()`
+  - Return the current simulation time.
+
+A trigger object has the following methods:
+- `until(condition)`
+  - Repeat the trigger until `condition` is true. If `condition` is initially true, `await` will return immediately without advancing simulation.
+
+`Value`, `data.View` and `enum.EnumView` have `.get()` and `.set()` methods added.
+
+`Tick()`, `Delay()`, `Active()` and `Passive()` as well as the ability to pass generator coroutines as `process` are deprecated and removed in a future version.
+
+## Drawbacks
+[drawbacks]: #drawbacks
+
+Reserves two new names on `Value` and value castables. Increase in API surface area and complexity. Churn.
+
+## Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+- Do nothing. Keep the existing interface, add `Changed()` alongside `Delay()` and `Tick()`, use `yield from` when calling functions.
+
+- Don't introduce `.get()` and `.set()`. Instead require a value castable and the return value of its `.eq()` to be awaitable so `await value` and `await value.eq(foo)` is possible.
+
+
+## Prior art
+[prior-art]: #prior-art
+
+Other python libraries like [cocotb](https://docs.cocotb.org/en/stable/coroutines.html) that originally used generator based coroutines have also moved to `async`/`await` style coroutines.
+
+## Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+- Is there any other functionality that's natural to have on the simulator context?
+- Is there any other functionality that's natural to have on the trigger object?
+  - Maybe a way to skip a given number of triggers? We still lack a way to say «advance by n cycles».
+- Bikeshed all the names.
+
+## Future possibilities
+[future-possibilities]: #future-possibilities
+
+Add simulation helpers in the manner of `.send()` and `.recv()` to standard interfaces where it makes sense.