the direction of <> operator in Chisel? - operator-keyword

Question

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) ?

Answer 1

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.

Answer 2

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.