sim: document.

This commit includes additional non-documentation changes, related to
issues found while documenting it:
- `Simulator.run_until()` no longer accepts a `run_passive=` argument.
  Passive no longer exist and in any case defaulting to `False` does not
  make a lot of sense from an API perspective.
- `add_clock()`'s `phase=` argument, when specified, no longer has
  `period/2` added to it. This wasn't the documented behavior in first
  place and it makes no sense to do that.
- `add_clock()` raises a `NameError` if a clock domain does not exist,
  instead of `ValueError`.
- `add_clock()` raises a `DriverConflict` if a clock domain is already
  being driven by a clock, instead of `ValueError`.
- GTKWave is no longer a part of the installation instructions, and both
  Surfer and GTKWave are recommended (in this order).

docs/_code/up_counter.py

@@ -47,29 +47,29 @@ from amaranth.sim import Simulator
 
 
 dut = UpCounter(25)
-def bench():
+async def bench(ctx):
     # Disabled counter should not overflow.
-    yield dut.en.eq(0)
+    ctx.set(dut.en, 0)
     for _ in range(30):
-        yield
-        assert not (yield dut.ovf)
+        await ctx.tick()
+        assert not ctx.get(dut.ovf)
 
     # Once enabled, the counter should overflow in 25 cycles.
-    yield dut.en.eq(1)
-    for _ in range(25):
-        yield
-        assert not (yield dut.ovf)
-    yield
-    assert (yield dut.ovf)
+    ctx.set(dut.en, 1)
+    for _ in range(24):
+        await ctx.tick()
+        assert not ctx.get(dut.ovf)
+    await ctx.tick()
+    assert ctx.get(dut.ovf)
 
     # The overflow should clear in one cycle.
-    yield
-    assert not (yield dut.ovf)
+    await ctx.tick()
+    assert not ctx.get(dut.ovf)
 
 
 sim = Simulator(dut)
 sim.add_clock(1e-6) # 1 MHz
-sim.add_sync_process(bench)
+sim.add_testbench(bench)
 with sim.write_vcd("up_counter.vcd"):
     sim.run()
 # --- CONVERT ---