Document Calyx's signal interface

[nathanielnrn]

The docs should explicitly state that simulating Verilog generated by Calyx requires that the toplevel reset and go signals are asserted in that order.

@rachitnigam Any thoughts on where to put this? Verilator and Icarus are talked about here, but it seems a bit of a weird place to put it. On the other hand, not sure of a better place to put before doing some bigger refactoring (possible a dedicated "Simulation" section?).

---

As seen here:

@nathanielnrn had a synchronous discussion about this and we noticed a couple of problems:

1. The main.go signal isn't asserted in the cocotb harness
2. The main.reset is not asserted which is needed to reset the state inside the control registers

The fix was to add the following to the top of the harness:

    # Assert reset for 5 cycles
    main.reset.value = 1
    await ClockCycles(main.clk, 5)  # wait a bit
    main.reset.value = 0

    # Start the execution
    main.go.value = 1

There is a bigger problem to address here: writing a harness to execute Calyx programs is non-trivial because the user needs to reset control state and then correctly assert the go signal. We should document this somewhere.

Originally posted by @rachitnigam in #1801 (comment)

[rachitnigam]

I think this should go under "Running Calyx Programs" with a new file called "Interfacing with Calyx". Do you want to take a shot at writing this up? Might be a good exercise so that we can figure out which details need to be mentioned!

[sampsyo]

Yes, that sounds like a great location! Thanks for bringing it up. This will in general be very helpful for people who want to generate a thing with Calyx and then incorporate it into a larger RTL design.

(This is slightly tangential, but it occurs to me that this points out a deviation that we will incur when transitioning from the old Verilog AXI interface to a Calyx-generated AXI interface… that is we probably want to have some way to make this interface not be required for the latter! Otherwise, the Xilinx shell will of course not know that it needs to do these things.)

[nathanielnrn]

Happy to take this up