the direction of <> operator in Chisel?

user_12843495 0
Viewed 128

In 2.6 chiseltest of chisel-bootcamp tutorials, there is a example about create a Queue using Decoupled interface:

case class QueueModule[T <: Data](ioType: T, entries: Int) extends MultiIOModule {
  val in = IO(Flipped(Decoupled(ioType)))
  val out = IO(Decoupled(ioType))
  out <> Queue(in, entries)
}

the <> operator's direction in the last line out <> Queue(in, entries) is really confusing to me as I check <> operator of class DecoupledIO in chisel-api and got the definition is "Connect this data to that data bi-directionally and element-wise." which means out and Queue(in, entries)'s return must be bi-directionally. However, I found the Queue source code:

object Queue
{
  /** Create a queue and supply a DecoupledIO containing the product. */
  @chiselName
  def apply[T <: Data](
      enq: ReadyValidIO[T],
      entries: Int = 2,
      pipe: Boolean = false,
      flow: Boolean = false): DecoupledIO[T] = {
    if (entries == 0) {
      val deq = Wire(new DecoupledIO(chiselTypeOf(enq.bits)))
      deq.valid := enq.valid
      deq.bits := enq.bits
      enq.ready := deq.ready
      deq
    } else {
      val q = Module(new Queue(chiselTypeOf(enq.bits), entries, pipe, flow))
      q.io.enq.valid := enq.valid // not using <> so that override is allowed
      q.io.enq.bits := enq.bits
      enq.ready := q.io.enq.ready
      TransitName(q.io.deq, q)
    }
  }

which return q.io.deq by TransitName method, and q.io.deq are defined as follows:

object DeqIO {
  def apply[T<:Data](gen: T): DecoupledIO[T] = Flipped(Decoupled(gen))
}

/** An I/O Bundle for Queues
  * @param gen The type of data to queue
  * @param entries The max number of entries in the queue.
  */
class QueueIO[T <: Data](private val gen: T, val entries: Int) extends Bundle
{ // See github.com/freechipsproject/chisel3/issues/765 for why gen is a private val and proposed replacement APIs.

  /* These may look inverted, because the names (enq/deq) are from the perspective of the client,
   *  but internally, the queue implementation itself sits on the other side
   *  of the interface so uses the flipped instance.
   */
  /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. */
  val enq = Flipped(EnqIO(gen))
  /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]]*/
  val deq = Flipped(DeqIO(gen))
  /** The current amount of data in the queue */
  val count = Output(UInt(log2Ceil(entries + 1).W))
}

that means q.io.deq is No-Flipped DecoupledIO and has the same interface direction of out. So I really want to know that how <> works in out <> Queue(in, entries) ?

chisel operator-keyword direction
2 Answers

Decoupled(data) add handshaking protocol to data bundle given in parameters. If you declare this signal for example :

val dec_data = IO(Decoupled(chiselTypeOf(data)))

dec_data object will have 2 handshake values (ready, valid) with different directions and one data value.

myvalue := dec_data.bits
value_is_valid := dec_data.valid  //boolean value in the same direction as data
dec_data.ready := sink_ready_to_receive //boolean value in the oposite data direction

If you want to connect dec_data to another DecoupledIO bundle, you can't use := operator on the whole bundle because it's unidirectional operator. You have to do connection value by value :

val dec_data_sink = IO(Flipped(Decoupled(chiselTypeOf(data))))

dec_data_sink.bits := dec_data.bits
dec_data_sink.valid := dec_data.valid
dec_data.ready := dec_data_sink.ready

With bulk connector <> you can avoid this painful connexions with :

dec_data_sink <> dec_data

Chisel will automatically connect right signals together.

For more documentation about bulks connections and decoupled interface, see the documentation here.

user_44229570

OK, I check the Verilog generated by this example:

module Queue(
  input        clock,
  input        reset,
  output       io_enq_ready,
  input        io_enq_valid,
  input  [8:0] io_enq_bits,
  input        io_deq_ready,
  output       io_deq_valid,
  output [8:0] io_deq_bits
);
......
......
module QueueModule(
  input        clock,
  input        reset,
  output       in_ready,
  input        in_valid,
  input  [8:0] in_bits,
  input        out_ready,
  output       out_valid,
  output [8:0] out_bits
);
  wire  q_clock; // @[Decoupled.scala 296:21]
  wire  q_reset; // @[Decoupled.scala 296:21]
  wire  q_io_enq_ready; // @[Decoupled.scala 296:21]
  wire  q_io_enq_valid; // @[Decoupled.scala 296:21]
  wire [8:0] q_io_enq_bits; // @[Decoupled.scala 296:21]
  wire  q_io_deq_ready; // @[Decoupled.scala 296:21]
  wire  q_io_deq_valid; // @[Decoupled.scala 296:21]
  wire [8:0] q_io_deq_bits; // @[Decoupled.scala 296:21]
  Queue q ( // @[Decoupled.scala 296:21]
    .clock(q_clock),
    .reset(q_reset),
    .io_enq_ready(q_io_enq_ready),
    .io_enq_valid(q_io_enq_valid),
    .io_enq_bits(q_io_enq_bits),
    .io_deq_ready(q_io_deq_ready),
    .io_deq_valid(q_io_deq_valid),
    .io_deq_bits(q_io_deq_bits)
  );
  assign in_ready = q_io_enq_ready; // @[Decoupled.scala 299:17]
  assign out_valid = q_io_deq_valid; // @[cmd2.sc 4:7]
  assign out_bits = q_io_deq_bits; // @[cmd2.sc 4:7]
  assign q_clock = clock;
  assign q_reset = reset;
  assign q_io_enq_valid = in_valid; // @[Decoupled.scala 297:22]
  assign q_io_enq_bits = in_bits; // @[Decoupled.scala 298:21]
  assign q_io_deq_ready = out_ready; // @[cmd2.sc 4:7]
endmodule

I found that there is simply inputs connect inputs and outputs connect outputs between Queue and QueueModule. As far as I understand it, there is a instantiation of Queue module in QueueModule, so QueueModule and Queue match the parent/child modules and <> bulk-connect operator connects interfaces of the same gender as the documentation
So I understand that I ignored the Queue itself is also a module and the format of the example:

case class QueueModule[T <: Data](ioType: T, entries: Int) extends MultiIOModule {
  val in = IO(Flipped(Decoupled(ioType)))
  val out = IO(Decoupled(ioType))
  out <> Queue(in, entries)
}

will match QueueModule/Queue to parent/child modules.

user_128434950
Related