Add FixedIORawModule, FixedIOBlackBox

[seldridge]

Add a private[chisel3] ability to block further IO creation in a
BaseModule. This is intended for advanced, in-tree APIs that need to
disallow the creation of further IO by a user. This API has mutable state
to track if more IO is allowed to be created, a method to get the
value, and a method to set the module to disallow further IO creation.
This one-way setting (h/t @jackkoenig) tries to keep this as locked down
as possible.

Add a new module hierarchy that promotes the type of the IO of that module
to a type parameter. This module hierarchy includes:

1. PolymorphicIOBaseModule
2. PolymorphicIORawModule
3. PolymorphicIOBlackBox

Both (2) and (3) inherit from (1). These modules are all polymorphic in
their type of IO. It follows that no more IO are allowed to be created
other than what is in the type.

Release Notes

Add FixedIORawModule and FixedIOExtModule that have a type parameter describing what their IO is. This is intended for advanced APIs which want to have guarantees about the IO will be. These share a common trait, FixedIOBaseModule which can be used to allow for substitution of one for the other.

[azidar]

I'm not in love with the PolymorphicIO name. I feel like most Chisel modules could make the claim that they are polymorphic over their IOs. Isn't it more like a "FixedIO" module?

Anyways, no major issues, I approve.

[azidar]

Was going to suggest an abstract class here, but I take it back, I think a trait is better.

[seldridge]

"Fixed" is also a good idea. I think this will much better match what a user thinks about here. "The IO is fixed" vs. "The IO is polymorphic" (???). 👍 Changes to this in the rebase.

[mwachs5]

👍 on the FixedIO name

[mwachs5]

couldn't the order of trait-mixing-in allow a user to get around this?

trait MySneakyIO {
  val sneakyIO = IO(UInt(32.W))
}

class MyThing extends MySneakyIO with FixedIORawModule 

[seldridge]

Fortunately, no because FixedIORawModule/FixedIOExtModule are classes and not traits. Those have to be the first thing you mix-in, i.e., they need to follow extends.

A user will see the following compile-time error if they try the above:

[error] /repos/github.com/chipsalliance/chisel/src/test/scala/chiselTests/FixedIOModuleSpec.scala:55:43: class FixedIORawModule needs to be a trait to be mixed in
[error]     class MyThing extends MySneakyIO with FixedIORawModule[Bool](Bool())
[error]                                           ^

If they change the order to be legal Scala, they'll get a runtime error because the trait constructor body runs after IO creation is disallowed:

[info]   java.lang.IllegalArgumentException: requirement failed: This module cannot have user-created IO
[info]   at ... ()
[info]   at chiselTests.FixedIOModuleSpec$MySneakyIO$1.$anonfun$sneakyIO$2(FixedIOModuleSpec.scala:52)
[info]   at chisel3.experimental.prefix$.apply(prefix.scala:50)
[info]   at chiselTests.FixedIOModuleSpec$MySneakyIO$1.$anonfun$sneakyIO$1(FixedIOModuleSpec.scala:52)
[info]   at chisel3.internal.plugin.package$.autoNameRecursively(package.scala:33)
[info]   at chiselTests.FixedIOModuleSpec$MySneakyIO$1.$init$(FixedIOModuleSpec.scala:52)
[info]   at chiselTests.FixedIOModuleSpec$MyThing$1.<init>(FixedIOModuleSpec.scala:55)
[info]   at chiselTests.FixedIOModuleSpec.$anonfun$new$9(FixedIOModuleSpec.scala:57)
[info]   at ... ()
[info]   at ... (Stack trace trimmed to user code only. Rerun with --full-stacktrace to see the full stack trace)

[mwachs5]

nit: can you change the name of this PR because i think it shows up in the release notes?