adding RawModule documentation in module.md section

[Martoni]

documentation proposal for RawModule refering to this Chisel3 issue.

Closes chipsalliance/chisel#678

[johnsbrew]

Hi, it's great to get some pieces of documentation for these features =)
Just so you know, they are in the process of getting out of chisel3.experimental to go into the main chisel3:
chipsalliance/chisel#1162

Which would lead to some minor modifications to the doc you have just written.

[Martoni]

Thanks johnsbrew, I deleted lines with «experimental» remarks.

[seldridge]

I'll give this a real review, but the experimental vs. non-experimental is tricky. The website is using submodules (pointing at the latest tagged-version) of Chisel for it's dependencies. Because of that, anything in a tut shed (which is going to be run in a REPL) needs to work. Consequently, stuff like: [...] or use of bleeding edge features will cause the website build to fail.

@johnsbrew brings up an interesting point related to what version should the website documentation be documenting?

Currently, it's documenting the most recent tagged version (3.1.8). My reasoning here is that I don't want to document features that require the use of 3.2-SNAPSHOT. I figure if people are comfortable with that, then they are comfortable with only using the published snapshot Scaladoc and are beyond the need for the gentle documentation. People wanting to use newer features can be fixed with a faster release cadence 🤞.

The current approach of documenting the most recent version implies that it's a (necessary) pain to prepare the website for a new release, e.g., 3.2, as all the documentation needs to get updated. This isn't insurmountable, though.

I'm open to other approaches on how to handle this.

[johnsbrew]

I guess the original "experimental" remark was a good approach then, maybe just add a tag "must be imported from experimental prior X.Y"

However IMHO the website build should be based on the latest snapshot of chisel, so latest features can be advertised very quickly to users. Devs should also come with proper documentation and basic intended use-cases along with their code changes when publishing new features.

As @chick mentioned it in the original issue chipsalliance/chisel#678 the idea of this 'gentle documentation' is to highlight cool features of chisel. I was personally unaware of chisel's RawModule and MultiIOModule until very recently which I think is a shame.

[seldridge]

Interesting perspective @johnsbrew. I think there's a fair point in getting features out to users. (Discoverability is a huge issue.)

I think you're implying this, but do you think purely new features (e.g., those that do not exist in 3.1.8) should be advertised on the website?

[Martoni]

I wrote this document because I needed it for a design and the only documentation about RawModule I'd found is my own blog article (in french).
In my opinion this feature is not a gadget, it's mandatory for FPGA design I think.

[seldridge]

Thanks for diving into documenting Chisel! We need more contributions like this!

Two main points:

• If you are so inclined, this PR would be really complete with documentation of MultiIOModule. I won't hold up this PR if you want to do that in a subsequent request or leave it for someone else.
• I think the example you provide (which is a great start) could be simplified a bit and show usage of RawModule to rename all ports.

[seldridge]

When you put this code in a tut shed, it's executing on the Scala REPL. So, anything here needs to be legal Scala and type safe.

Suggested change

	[...]
	// ...

[Martoni]

Ok, I'm deleting tut shed replacing it with ```scala

[seldridge]

Actually, if you can keep the tut sheds I think that would be better. There's then a guarantee that a user can copy-paste that code block and it will work (with a specific version of the scala compiler).

Going forward, I view tut or mdoc as the approach for keeping the documentation in sync (and guaranteed to work): #4

[Martoni]

Ok

[seldridge]

I would tighten these two paragraphs up. Consider something like:

A `RawModule` is a module that allows you to define as much `IO` as needed (like `MultiIOModule`) but **does not provide an implicit clock and reset.** 
This can be useful when interfacing a Chisel module with a design that expects a specific naming convention for clock or reset.

[edwardcwang]

I agree with Schuyler and would condense these two paragraphs into one. For example, we probably don't need to repeat something like *Module* are used to connect components inside a design

A `RawModule` is a module that allows you to define as much `IO` as needed with fully-custom naming (like `MultiIOModule`) but **does not provide an implicit clock and reset.** 
This can be useful when interfacing a Chisel module with a design that expects a specific naming convention for clock or reset.

[seldridge]

I think this example is a great start, but may be a little verbose. Maybe something abstract and with fewer signals.

I've hit the issue where companies expect _i and _o suffixes on ports. Maybe something like the following which shows naming problems with all io:

class Foo extends Module {
  val io = IO(new Bundle{
    val a = Input(Bool())
    val b = Output(Bool())
  }
  io.b := !io.a
}
class FooWrapper extends RawModule {
  val a_i  = IO(Input(Bool()))
  val b_o  = IO(Output(Bool()))
  val clk  = Input(Clock())
  val rstn = Input(Bool())

  val foo = withClockAndReset(clk, !rstn){ Module(new Foo) }

  foo.io.a := a_i
  b_o := foo.io.b
}

[Martoni]

I discovered the syntax :

  val foo = withClockAndReset(clk, !rstn){ Module(new Foo) }

I usally use this syntax :

withClockAndReset(clk, !rstn){ 
 val foo = Module(new Foo)
}

I still have a lot to learn ;)

[seldridge]

For Scala/Chisel things, the rest of the documentation uses RawModule over RawModule or RawModule.

[seldridge]

I think this documentation should likely be moved into the documentation for MultiIOModule if we introduce Module first, MultiIOModule second, and RawModule third.

[Martoni]

Thanks for all the reviewing. I can do the reviewed modifications myself if you want. But maybe it's easier to let you do it no ?
I wanted to document MultiIOModule but I could not find documentation about it ;). And Scala is not so easy to understand quickly.

[seldridge]

Probably easier, but that would defeat the point! Why don't you make modifications just to raw module and we can leave the MultiIOModule documentation for future work.

[Martoni]

I rewritten text according to the above review.

[seldridge]

Nice. Final round of review. Should be good after this.

Note: once you add in the tut:silent (or other tut options), you can test that all your code examples work (or, in this case, that my example isn't busted) with: sbt ++2.12.6 docs/makeMicrosite.

[Martoni]

Ok, I used the github feature to 'approuve' all your proposal but it flooded a little bit the commit log ;)

[seldridge]

Awesome. Thanks for this! Once this gets through regressions, I'll squash and merge (to get rid of the spurious and broken commits).