What is the purpose of TransitName in Chisel3?

Question

In the implementation of the Queue in chisel3,

Object Queue returns TransitName:

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(enq.bits))
      deq.valid := enq.valid
      deq.bits := enq.bits
      enq.ready := deq.ready
      deq
    } else {
      require(entries > 0)
      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)
    }
}

I couldn't grasp what's inside TransitName, because I couldn't understand its meaning of source code.

At the line located at TransitName(q.io.deq, q), I think that just returning q.io.deq(instead of TransitName), it works correctly. But why do we need TransitName??

seldridge seldridge · Accepted Answer · 2018-04-16T18:19:30

TransitName is helping to name the created Queue module based on what the user specifies. The Queue factory creates a new Queue object internally, but only returns a portion of its IO. Chisel knows what to name the IO based on the name of the user's val (or via some name override). However, Chisel does not know what to name the Queue. For improved readability of the queue in downstream representations (FIRRTL, Verilog), this will "transit" the name of the q.io.deq to the Queue as opposed to giving it a generated/temporary name (e.g., _T_42) that loses the connection to the user's name.

From the perspective of functionality, however, all that TransitName is doing is returning q.io.deq.

Take a look at the TransitName object definition for some more details (and a nice comment).

What is the purpose of TransitName in Chisel3?

1 Answers