Reconsider simulator interface

[whitequark]

The oMigen simulator had a strange interface where user processes would run after a clock edge, but before synchronous signals assume their new value. Not only it is very hard to use and bug-prone (my simulation testing workflow, for example, involves adding yield until tests pass...), but it also makes certain patterns impossible! For example, let's consider the FIFOInterface.write() simulation function:

def write(self, data):
    """Write method for simulation."""
    assert (yield self.w_rdy)
    yield self.w_data.eq(data)
    yield self.w_en.eq(1)
    yield
    yield self.w_en.eq(0)
    yield

It has to take two clock cycles. This is because, after the first yield, it is not yet possible to read the new value of self.w_rdy; running (yield self.w_rdy) would return the value from the previous cycle. To make sure it's updated, it is necessary to deassert self.w_en, and waste another cycle doing nothing.

Because of this, I've removed these methods from nMigen FIFOInterface in a57b76f.

I think we should look at prior art for cosimulation (cocotb?) and adopt a usage pattern that is easier to use. This is complicated by the fact that it is desirable to run oMigen testbenches unmodified.

[sbourdeauducq]

The oMigen simulator had a strange interface where user processes would run after a clock edge, but before synchronous signals assume their new value.

The reason for this is to ensure determinism when there are multiple processes on the same clock communicating through signals. The result is independent of the order in which those process are run.

[sbourdeauducq]

Was this changed already? This prints 1 0:

from nmigen import *
from nmigen.back.pysim import *

class Dummy(Elaboratable):
     def __init__(self):
        self.x = Signal()
        self.y = Signal()

     def elaborate(self, platform):
        m = Module()
        m.d.sync += self.y.eq(self.x)
        return m

if __name__ == "__main__":
     dummy = Dummy()
     with Simulator(dummy) as sim:
        def process():
            yield dummy.x.eq(1)
            print((yield dummy.x))
            yield dummy.x.eq(0)
            print((yield dummy.x))
        sim.add_clock(1e-6)
        sim.add_sync_process(process)
        sim.run()

[whitequark]

You aren't using dummy.y at all in this code, no?

[sbourdeauducq]

Yes. It is a dummy signal to work around #262.

[whitequark]

Was this changed already?

I didn't intend to change this. I think the reason you see the behavior you do is that I did not understand the design of the oMigen simulator, so I didn't implement it entirely correctly.

The reason for this is to ensure determinism when there are multiple processes on the same clock communicating through signals. The result is independent of the order in which those process are run.

OK, so this works like VHDL. That's good. Unfortunately, the problem I outlined in this issue stands: not being able to write a single-cycle FIFOInterface.read() is a serious defect.

I've been thinking about this problem and came to the conclusion that there should probably be three kinds of simulator processes:

• add_sync_process, working like in oMigen, where the Python code works like synchronous logic;
• add_comb_process, where the Python code works like combinatorial logic (Make it possible for generators to simulate combinatorial logic #11);
• add_toplevel_process (or something like that), only one of which can be present in a design, and where you could implement single-cycle FIFOInterface.read.

[sbourdeauducq]

What about an option to run synchronous processes at twice the clock rate?

For example, a synchronous process could yield a full cycle (default), or a high half-cycle, or a low half-cycle.

At the beginning of a cycle, it could yield either a full cycle (default) or a high half-cycle. At the middle of a cycle it could yield only a low half-cycle. Doing otherwise raises an error, which ensures that processes are always "in phase" with the clock.

This is backward compatible, can be deterministic using the VHDL-style behavior, and supports an arbitrary number of processes.

[whitequark]

The basic idea is sound, thanks. But, what happens if someone uses a negedge clock domain (#185) in the design? There are many valid reasons to do so, and even some FPGA primitives (Xilinx UltraRAM) trigger on both clock edges.

So I think we should change it a bit: rather than use a half cycle, run all "sync" processes at the posedge (or the negedge) as it currently happens, and then run all "testbench" (or whatever they are called) processes simultaneously, a very small amount of time later (however much it takes for combinatorial logic to propagate, and for "comb" processes to run as well).

[jordens]

I would want to differentiate that yield (None). Semantically yield currently means to continue the simulation until before the next clock edge: "update sync signals and settle comb signals again". At that point the values for sync signals for the next cycle are known (and can be altered from the process) and the sync signals are about to update.

What you actually want instead is to be able to differentiate between yielding to update the sync signals and yielding to settle the comb signals.
I don't think mapping this to two half cycles is correct since that will most likely clash with support for multiple clock domains: the settling of comb signals does not take the length of a half cycle. That's arbitrary. In reality you have the sync clock cycle and -- semantically different from it -- a delta cycle that just settles comb.

[whitequark]

In terms of the UI, currently add_process requires submitting explicit wait commands (i.e. Tick("domain"), and add_sync_process(domain=) automatically substitutes yield Tick(domain) for any yield with no arguments. We could split that into yield BeforeTick(domain) (the same as current Tick) and yield AfterTick(domain); in both cases, you can only observe "current" values for all signals and update "next" values for signals, preserving determinism, but all built-in synchronous logic, and any "sync" processes, wait for the BeforeTick event if you do yield with no argument, whereas simulation testbenches wait for AfterTick event in that case.

This solves an important issue where something like FIFOInterface.read cannot just yield because the meaning of yield changes depending on the kind of process it's in. But if it can explicitly do yield AfterTick() (with the domain perhaps substituted by some sort of default), then it would be possible to use it unambiguously.

[jordens]

And this extends to multiple clock domains accordingly (sync cycles executed in the pattern defined by their timing beat and comb/delta cycles in between). A process should be able to specify what kind of cycle it wants to yield for: not just a bare yield but maybe yield None for comb settling vs yield dut.sync or yield "sync" for the next corresponding clock edge update.

[jordens]

I don't think BeforeTick/AfterTick is sufficient: there are good reasons to do multiple delta cycles between sync cycles.

[whitequark]

Can you provide some examples of those reasons?

[jordens]

Otherwise yield x.eq(1) could only ever been a sync update. If your process wants to do the equivalent of comb logic, this is limiting. There would not be a way for a process to react to non-trivial comb signal changes from the simulated gateware within the same cycle.

[jordens]

E.g. if you don't have any synchronous clock domain.
In the simplest case if you want to test whether your module reacts to a signal immediately:

yield stb.eq(1)
yield  # settle comb
assert (yield busy)
yield stb.eq(0)
yield  # settle comb
assert not (yield busy)

[whitequark]

If your process wants to do the equivalent of comb logic, this is limiting.

Comb processes are something I wanted to introduce explicitly (that's the second oldest nMigen issue, #11). In my mind, they would require specifying the exact set of signals they will wait on during creation, and then always wait on exactly those signals; that way, they would have no choice but to be well behaved.

However, that would not work for the snippet you show. And I think you are making a very good point with it. I'm inclined to agree that a separate command for comb settling is desirable.