Wiki proposal: explain and demonstrate parametrizable BlackBox in-line implementation

[tdb-alcorn]

Type of issue: documentation

Impact: no functional change

Development Phase: proposal

Other information

This is a proposal to add some content to the BlackBoxes github wiki page explaining how to write a Verilog BlackBox with an inline implementation that can be parametrized in simple ways. The example I have in mind (relevant to my work) is writing a block RAM generator aimed at Vivado which can handle any bus width and memory depth. Below is my proposed addition to the wiki, to be appended to section BlackBoxes with in-line Verilog. It might also be interesting to add a page to the wiki containing a complete example of a Chisel -> Vivado block RAM generator, since several people I talked to at the Chisel conference expressed a need for that. I'm happy to write such a page if it's desired.

---

The in-line implementation can be dynamically parametrized at compile time by using Scala string interpolation. However, if you use the BlackBox more than once with differing parameters, the generated Verilog files will conflict. To avoid this, you must specify a new unique desiredName for the BlackBox module, which must exactly match the Verilog filename and Verilog module name generated. For example, within the BlackBox module definition, this might look like:

class MyBlackBox(busWidth: int) extends BlackBox with HasBlackBoxInline {
  override def desiredName = s"my_blackbox_$busWidth"

  val io = IO(new Bundle {
    val in = Input(UInt(busWidth.W))
    ...
  })

  setInline(s"${desiredName}.v",
    s"""module ${desiredName}(
         |  input [${busWidth-1}:0] in,
         |  ...
         |endmodule""".stripMargin)

  println(s"Generated BlackBox ${desiredName}.v")
}

This will result in a new generated Verilog file for each instance of MyBlackBox with different parameters. For example, if you somewhere instantiate Module(new MyBlackBox(32)) then the file my_blackbox_32.v will be generated containing a Verilog definition for the module my_blackbox_32.

[chick]

This looks pretty straightforward to me. @albert-magyar do you have any comments

[seldridge]

If possible, is prefer to have this as a website update.

[mwachs5]

can you guys add instructions to the readme how to make updates to the website...? And if Wiki is not the right thing to point to website instead...?

[albert-magyar]

I think it might be good to come up with a canonical phrase to describe this. Using the term "parameter" and "blackbox" together might just make some people miss what you're actually doing and assume it's just Verilog module-level parameters.

[chick]

@ucbjrl I feel like you might have documented the wiki update process at some point in the past.

[ucbjrl]

I agree with @seldridge, that this would be better as website update (I think you just submit a pull request to https://github.com/freechipsproject/www.chisel-lang.org). If you think it's a good idea to update the wiki as well, submit a pull request to https://github.com/ucb-bar/chisel3-wiki.