Add an annotation for specifying module port conventions (#3030)

This annotation is being handled in mfc via:
  llvm/circt#4665

The convention lets users define how ports with aggregate types are
lowered to verilog.

Author: rwy7

src/main/scala/circt/Convention.scala

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package circt
+
+import chisel3.experimental.{annotate, BaseModule, ChiselAnnotation}
+import firrtl.annotations.{ModuleTarget, SingleTargetAnnotation}
+import firrtl.FirrtlUserException
+
+/** Annotation to specify a module's port convention.
+  * The port convention defines how the ports of a module are transformed while
+  * lowering to verilog.
+  */
+case class ConventionAnnotation(target: ModuleTarget, convention: String) extends SingleTargetAnnotation[ModuleTarget] {
+  override def duplicate(target: ModuleTarget): ConventionAnnotation =
+    ConventionAnnotation(target, convention)
+}
+
+/** Utilities for annotating modules with a port convention.
+  * The port convention defines how the ports of a module are transformed while
+  * lowering to verilog.
+  *
+  * @example {{{
+  * class Inner extends Module {
+  *   val io = IO(new Bundle{})
+  * }
+  *
+  * class Top extends Module {
+  *   val inner = Module(new Inner)
+  *   convention.scalarized(inner)
+  * }
+  * }}}
+  */
+object convention {
+  private def apply[T <: BaseModule](data: T, convention: String): Unit =
+    annotate(new ChiselAnnotation {
+      def toFirrtl = ConventionAnnotation(data.toTarget, convention)
+    })
+
+  /** Annotate a module as having the "scalarized" port convention.
+    * With this port convention, the aggregate ports of the module will be
+    * fully scalarized.
+    */
+  def scalarized[T <: BaseModule](data: T): Unit =
+    apply(data, "scalarized")
+}

src/test/scala/circtTests/ConventionSpec.scala

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package circtTests
+
+import chisel3._
+import circt.convention
+import circt.stage.ChiselStage
+import org.scalatest.funspec.AnyFunSpec
+import org.scalatest.matchers.should.Matchers
+
+class ConventionSpec extends AnyFunSpec with Matchers {
+  describe("convention.scalarized") {
+    it("should scalarize the ports of a module") {
+      class PassThrough extends RawModule {
+        val i = IO(Input(new Bundle {
+          val x = UInt(16.W)
+          val y = UInt(16.W)
+        }))
+        val o = IO(Output(new Bundle {
+          val x = UInt(16.W)
+          val y = UInt(16.W)
+        }))
+        o := i
+      }
+
+      def makePassThrough() = {
+        val p = new PassThrough
+        convention.scalarized(p)
+        p
+      }
+
+      val expected = Array(
+        "input  [15:0] i_x,",
+        "input  [15:0] i_y,",
+        "output [15:0] o_x,",
+        "output [15:0] o_y",
+        "assign o_x = i_x;",
+        "assign o_y = i_y;"
+      )
+
+      val options = Array(
+        "--preserve-aggregate=all",
+        "--strip-debug-info",
+        "--scalarize-top-module=false",
+        "--lowering-options=disallowPortDeclSharing"
+      )
+
+      val actual = ChiselStage.emitSystemVerilog(makePassThrough(), Array(), options).split("\n").map(_.trim)
+      expected.foreach { e => actual should contain(e) }
+    }
+  }
+}