What the purpose of `initSource`, `initSink` or `setSinkClock` in chiseltest test harness?

Question

In chisel-template test example there are some init calls method for decoupled value:

class GCDSpec extends FreeSpec with ChiselScalatestTester {

  "Gcd should calculate proper greatest common denominator" in {
    test(new DecoupledGcd(16)) { dut =>
      dut.input.initSource()
      dut.input.setSourceClock(dut.clock)
      dut.output.initSink()
      dut.output.setSinkClock(dut.clock)

//...

I can't find documentation explained the purpose of these methods. Why do we have to «init source or sink» of decoupled input ?

The api documentation is not filled with documentation for it.

Answer 1

The two init methods do the following dut.input.initSource() sets input decoupled's valid signal to false.B dut.output.initSink() sets output decoupled's ready signal to false.B I think you could do these on your own manually. The clock setting calls do a bit more complicated stuff in order to coordinate clock handling across fork calls which are typically used with the enqueue and dequeue family of functions. It might be that this could be inferred from DUTs but detecting the decoupled interfaces is currently a bit hard to do.

The boilerplate calls to these function can be more succinctly specified as

  dut.input.initSource().setSourceClock(dut.clock)
  dut.output.initSink().setSinkClock(dut.clock)

since the initSource and initSync return the port decoupled port

As to documentation, this should definitely be improved for the decoupled helpers. I have added a note to do this to an existing documentation issue