Naming Plugin and Object Pattern

[seldridge]

I've been using a pattern of wrapping hardware in an object to provide namespacing. This has been useful because it enables a direct conversion of an anonymous bundle pattern like val io = IO(new Bundle { }) to something which is more amenable to adding domain information. However, this pattern doesn't work correctly with the naming plugin.

Consider:

//> using repository https://central.sonatype.com/repository/maven-snapshots
//> using scala 2.13.18
//> using dep org.chipsalliance::chisel:7.13.0+23-b2a0e030-SNAPSHOT
//> using plugin org.chipsalliance:::chisel-plugin:7.13.0+23-b2a0e030-SNAPSHOT
//> using options -unchecked -deprecation -language:reflectiveCalls -feature -Xcheckinit
//> using options -Xfatal-warnings -Ywarn-dead-code -Ywarn-unused -Ymacro-annotations

import chisel3._
import chisel3.experimental.prefix
import circt.stage.ChiselStage

class Foo extends Module {
  val io = IO {
    new Bundle {
      val a = Input(Bool())
      val b = Output(Bool())
    }
  }

  io.b := RegNext(io.a)
}

class Bar extends Module {
  object io {
    val a = IO(Input(Bool()))
    val b = IO(Output(Bool()))
  }
  prefix("io")(io)

  io.b := RegNext(io.a)
}

object Main extends App {
  println(
    ChiselStage.emitSystemVerilog(
      gen = new Foo,
      firtoolOpts = Array("-disable-all-randomization", "-strip-debug-info", "-default-layer-specialization=enable")
    )
  )
  println(
    ChiselStage.emitSystemVerilog(
      gen = new Bar,
      firtoolOpts = Array("-disable-all-randomization", "-strip-debug-info", "-default-layer-specialization=enable")
    )
  )
}

The above produces the following Verilog:

// Generated by CIRCT firtool-1.151.0
module Foo(
  input  clock,
         reset,
         io_a,
  output io_b
);

  reg io_b_REG;
  always @(posedge clock)
    io_b_REG <= io_a;
  assign io_b = io_b_REG;
endmodule


// Generated by CIRCT firtool-1.151.0
module Bar(
  input  clock,
         reset,
         io_a,
  output io_b
);

  reg b_REG;
  always @(posedge clock)
    b_REG <= io_a;
  assign io_b = b_REG;
endmodule

It seems like these should produce the same thing. Given that b has a prefix of io_. However, this doesn't get used when determining the name of the register with the object pattern.

[jackkoenig]

I looked into this a bit (with Open 4.8 help) and this is a really tricky one.

The basic issue comes from the fact that prefixes derived from Data (e.g. the LHS of a connection in this case) are only the local-name of that Data. This makes sense and works because in typical cases the prefix for the Data being used and at the connection point will be the same (just by the structure of how Scala code works with returning values). The object pattern violates this by applying the prefix only to the vals defined within the object, so vals with a different prefix can escape their prefix domain and be used in a different prefix domain that lacks the same "outer" domain if you will.

This is a subtle point that is hard to visualize so I will show how one can get the same behavior with mutation:

class Foo extends Module {
  var io: MyBundle = null
  prefix("fizz") {
    val x = IO(new MyBundle)
    io = x
  }

  io.b := RegNext(io.a)
}

Which results in

module Foo(
  input  clock,
         reset,
         fizz_x_a,
  output fizz_x_b
);

  reg x_b_REG;
  always @(posedge clock)
    x_b_REG <= fizz_x_a;
  assign fizz_x_b = x_b_REG;
endmodule

See how fizz applies to the ports but not the reg.

You can do something similar by "hiding" your values in an unnamable type:

case class Box(a: Bool, b: Bool)

class Foo extends Module {
  val io = prefix("io") {
    val a = IO(Input(Bool()))
    val b = IO(Output(Bool()))
    Box(a, b)
  }

  io.b := RegNext(io.a)
}

Gives:

module Foo(
  input  clock,
         reset,
         io_a,
  output io_b
);

  reg b_REG;
  always @(posedge clock)
    b_REG <= io_a;
  assign io_b = b_REG;
endmodule

[jackkoenig]

Note that if you use the prefix of the Data in generating a later prefix, you will basically get a double prefix. One can make this work by doing some common prefix removal algorithm. That might be the best answer, will think about it.