Merge branch 'master' into 3.5-release

8 files changed, 54 insertions, 78 deletions

diff --git a/docs/src/explanations/blackboxes.md b/docs/src/explanations/blackboxes.md
index 4ecd1ea0..a2a041a7 100644
--- a/docs/src/explanations/blackboxes.md
+++ b/docs/src/explanations/blackboxes.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Blackboxes"
 section: "chisel3"
 ---
+
+# BlackBoxes
+
 Chisel *BlackBoxes* are used to instantiate externally defined modules. This construct is useful
 for hardware constructs that cannot be described in Chisel and for connecting to FPGA or other IP not defined in Chisel.
 
diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md
index 78626c42..75230c41 100644
--- a/docs/src/explanations/bundles-and-vecs.md
+++ b/docs/src/explanations/bundles-and-vecs.md
@@ -4,6 +4,8 @@ title:  "Bundles and Vecs"
 section: "chisel3"
 ---
 
+# Bundles and Vecs
+
 `Bundle` and `Vec` are classes that allow the user to expand the set of Chisel datatypes with aggregates of other types.
 
 Bundles group together several named fields of potentially different types into a coherent unit, much like a `struct` in
@@ -128,48 +130,19 @@ class ModuleProgrammaticMixedVec(x: Int, y: Int) extends Module {
 }
 ```
 
-### A note on `cloneType`
-
-Since Chisel is built on top of Scala and the JVM, it needs to know how to construct copies of bundles for various
-purposes (creating wires, IOs, etc). If you have a parametrized bundle and Chisel can't automatically figure out how to
-clone your bundle, you will need to create a custom `cloneType` method in your bundle. Most of the time, this is as
-simple as `override def cloneType = (new YourBundleHere(...)).asInstanceOf[this.type]`.
-
-Note that in the vast majority of cases, **this is not required** as Chisel can figure out how to clone most bundles
-automatically.
-
-Here is an example of a parametrized bundle (`ExampleBundle`) that features a custom `cloneType`.
-
-```scala mdoc:silent
-class ExampleBundle(a: Int, b: Int) extends Bundle {
-    val foo = UInt(a.W)
-    val bar = UInt(b.W)
-    override def cloneType = (new ExampleBundle(a, b)).asInstanceOf[this.type]
-}
-
-class ExampleBundleModule(btype: ExampleBundle) extends Module {
-    val io = IO(new Bundle {
-        val out = Output(UInt(32.W))
-        val b = Input(chiselTypeOf(btype))
-    })
-    io.out := io.b.foo + io.b.bar
-}
+### A note on `cloneType` (For Chisel < 3.5)
 
-class Top extends Module {
-    val io = IO(new Bundle {
-        val out = Output(UInt(32.W))
-        val in = Input(UInt(17.W))
-    })
-    val x = Wire(new ExampleBundle(31, 17))
-    x := DontCare
-    val m = Module(new ExampleBundleModule(x))
-    m.io.b.foo := io.in
-    m.io.b.bar := io.in
-    io.out := m.io.out
-}
-```
+NOTE: This section **only applies to Chisel before Chisel 3.5**.
+As of Chisel 3.5, `Bundle`s should **not** `override def cloneType`,
+as this is a compiler error when using the chisel3 compiler plugin for inferring `cloneType`.
 
-Generally cloneType can be automatically defined if all arguments to the Bundle are vals e.g.
+Since Chisel is built on top of Scala and the JVM,
+it needs to know how to construct copies of `Bundle`s for various
+purposes (creating wires, IOs, etc).
+If you have a parametrized `Bundle` and Chisel can't automatically figure out how to
+clone it, you will need to create a custom `cloneType` method in your bundle. 
+In the vast majority of cases, **this is not required**
+as Chisel can figure out how to clone most `Bundle`s automatically:
 
 ```scala mdoc:silent
 class MyCloneTypeBundle(val bitwidth: Int) extends Bundle {
@@ -178,13 +151,15 @@ class MyCloneTypeBundle(val bitwidth: Int) extends Bundle {
 }
 ```
 
-The only caveat is if you are passing something of type Data as a "generator" parameter, in which case you should make
-it a `private val`.
+The only caveat is if you are passing something of type `Data` as a "generator" parameter,
+in which case you should make it a `private val`, and define a `cloneType` method with
+`override def cloneType = (new YourBundleHere(...)).asInstanceOf[this.type]`.
 
-For example, consider the following Bundle. Because its `gen` variable is not a `private val`, the user has to
-explicitly define the `cloneType` method.
+For example, consider the following `Bundle`. Because its `gen` variable is not a `private val`, the user has to
+explicitly define the `cloneType` method:
 
-```scala mdoc:silent
+<!-- Cannot compile this because the cloneType is now an error -->
+```scala
 import chisel3.util.{Decoupled, Irrevocable}
 class RegisterWriteIOExplicitCloneType[T <: Data](gen: T) extends Bundle {
   val request  = Flipped(Decoupled(gen))
@@ -196,8 +171,10 @@ class RegisterWriteIOExplicitCloneType[T <: Data](gen: T) extends Bundle {
 We can make this this infer cloneType by making `gen` private since it is a "type parameter":
 
 ```scala mdoc:silent
+import chisel3.util.{Decoupled, Irrevocable}
 class RegisterWriteIO[T <: Data](private val gen: T) extends Bundle {
   val request  = Flipped(Decoupled(gen))
   val response = Irrevocable(Bool())
 }
 ```
+
diff --git a/docs/src/explanations/dataview.md b/docs/src/explanations/dataview.md
index 2f229bfc..bb8dbdd1 100644
--- a/docs/src/explanations/dataview.md
+++ b/docs/src/explanations/dataview.md
@@ -10,7 +10,6 @@ _New in Chisel 3.5_
 
 ```scala mdoc:invisible
 import chisel3._
-import chisel3.stage.ChiselStage.emitVerilog
 ```
 
 ## Introduction
@@ -91,7 +90,7 @@ class MyModule extends RawModule {
 Of course, this would result in very different looking Verilog:
 
 ```scala mdoc:verilog
-emitVerilog(new MyModule {
+getVerilogString(new MyModule {
   override def desiredName = "MyModule"
   axi := DontCare // Just to generate Verilog in this stub
 })
@@ -147,7 +146,7 @@ class AXIStub extends RawModule {
 This will generate Verilog that matches the standard naming convention:
 
 ```scala mdoc:verilog
-emitVerilog(new AXIStub)
+getVerilogString(new AXIStub)
 ```
 
 Note that if both the _Target_ and the _View_ types are subtypes of `Data` (as they are in this example),
@@ -175,7 +174,7 @@ class ConnectionExample extends RawModule {
 This results in the corresponding fields being connected in the emitted Verilog:
 
 ```scala mdoc:verilog
-emitVerilog(new ConnectionExample)
+getVerilogString(new ConnectionExample)
 ```
 
 ## Other Use Cases
@@ -206,17 +205,6 @@ The issue, is that Chisel primitives like `Mux` and `:=` only operate on subtype
 Tuples (as members of the Scala standard library), are not subclasses of `Data`.
 `DataView` provides a mechanism to _view_ a `Tuple` as if it were a `Data`:
 
-<!-- TODO replace this with stdlib import -->
-
-```scala mdoc:invisible
-// ProductDataProduct
-implicit val productDataProduct: DataProduct[Product] = new DataProduct[Product] {
-  def dataIterator(a: Product, path: String): Iterator[(Data, String)] = {
-    a.productIterator.zipWithIndex.collect { case (d: Data, i) => d -> s"$path._$i" }
-  }
-}
-```
-
 ```scala mdoc
 // We need a type to represent the Tuple
 class HWTuple2[A <: Data, B <: Data](val _1: A, val _2: B) extends Bundle
@@ -259,16 +247,24 @@ class TupleExample extends RawModule {
 
 ```scala mdoc:invisible
 // Always emit Verilog to make sure it actually works
-emitVerilog(new TupleExample)
+getVerilogString(new TupleExample)
 ```
 
 Note that this example ignored `DataProduct` which is another required piece (see [the documentation
 about it below](#dataproduct)).
 
-All of this is slated to be included the Chisel standard library.
+All of this is available to users via a single import:
+```scala mdoc:reset
+import chisel3.experimental.conversions._
+```
 
 ## Totality and PartialDataView
 
+```scala mdoc:reset:invisible
+import chisel3._
+import chisel3.experimental.dataview._
+```
+
 A `DataView` is _total_ if all fields of the _Target_ type and all fields of the _View_ type are 
 included in the mapping.
 Chisel will error if a field is accidentally left out from a `DataView`.
@@ -285,7 +281,6 @@ class BundleB extends Bundle {
 ```
 
 ```scala mdoc:crash
-{ // Using an extra scope here to avoid a bug in mdoc (documentation generation)
 // We forgot BundleA.foo in the mapping!
 implicit val myView = DataView[BundleA, BundleB](_ => new BundleB, _.bar -> _.fizz)
 class BadMapping extends Module {
@@ -294,8 +289,7 @@ class BadMapping extends Module {
    out := in.viewAs[BundleB]
 }
 // We must run Chisel to see the error
-emitVerilog(new BadMapping)
-}
+getVerilogString(new BadMapping)
 ```
 
 As that error suggests, if we *want* the view to be non-total, we can use a `PartialDataView`:
@@ -311,7 +305,7 @@ class PartialDataViewModule extends Module {
 ```
 
 ```scala mdoc:verilog
-emitVerilog(new PartialDataViewModule)
+getVerilogString(new PartialDataViewModule)
 ```
 
 While `PartialDataViews` need not be total for the _Target_, both `PartialDataViews` and `DataViews`
@@ -321,7 +315,6 @@ This has the consequence that `PartialDataViews` are **not** invertible in the s
 For example:
 
 ```scala mdoc:crash
-{ // Using an extra scope here to avoid a bug in mdoc (documentation generation)
 implicit val myView2 = myView.invert(_ => new BundleA)
 class PartialDataViewModule2 extends Module {
    val in = IO(Input(new BundleA))
@@ -330,8 +323,7 @@ class PartialDataViewModule2 extends Module {
    out.viewAs[BundleA] := in
 }
 // We must run Chisel to see the error
-emitVerilog(new PartialDataViewModule2)
-}
+getVerilogString(new PartialDataViewModule2)
 ```
 
 As noted, the mapping must **always** be total for the `View`.
@@ -394,7 +386,7 @@ resolution error.
 
 
 This section draws heavily from [[1]](https://stackoverflow.com/a/5598107/2483329) and
-[[2]](https://stackoverflow.com/a/5598107/2483329).
+[[2]](https://stackoverflow.com/a/8694558/2483329).
 In particular, see [1] for examples.
 
 #### Implicit Resolution Example
@@ -444,7 +436,7 @@ class FooToBar extends Module {
 ```
 
 ```scala mdoc:verilog
-emitVerilog(new FooToBar)
+getVerilogString(new FooToBar)
 ```
 
 However, it's possible that some user of `Foo` and `Bar` wants different behavior,
@@ -464,7 +456,7 @@ class FooToBarSwizzled extends Module {
 ```
 
 ```scala mdoc:verilog
-emitVerilog(new FooToBarSwizzled)
+getVerilogString(new FooToBarSwizzled)
 ```
 
 ### DataProduct
diff --git a/docs/src/explanations/explanations.md b/docs/src/explanations/explanations.md
index 01894ad7..595bb48c 100644
--- a/docs/src/explanations/explanations.md
+++ b/docs/src/explanations/explanations.md
@@ -16,6 +16,7 @@ read these documents in the following order:
 * [Motivation](motivation)
 * [Supported Hardware](supported-hardware)
 * [Data Types](data-types)
+* [DataView](dataview)
 * [Bundles and Vecs](bundles-and-vecs)
 * [Combinational Circuits](combinational-circuits)
 * [Operators](operators)
diff --git a/docs/src/explanations/functional-abstraction.md b/docs/src/explanations/functional-abstraction.md
index 4e3900b6..596d869a 100644
--- a/docs/src/explanations/functional-abstraction.md
+++ b/docs/src/explanations/functional-abstraction.md
@@ -23,10 +23,10 @@ def clb(a: UInt, b: UInt, c: UInt, d: UInt): UInt =
 where ```clb``` is the function which takes ```a```, ```b```,
 ```c```, ```d``` as arguments and returns a wire to the output of a
 boolean circuit.  The ```def``` keyword is part of Scala and
-introduces a function definition, with each argument followed by a colon then its type,
-and the function return type given after the colon following the
-argument list.  The equals (```=})```sign separates the function argument list from the function
-definition.
+introduces a function definition, with each argument followed by a colon then
+its type, and the function return type given after the colon following the
+argument list.  The equals (`=`) sign separates the function argument list
+from the function definition.
 
 We can then use the block in another circuit as follows:
 ```scala mdoc:silent
diff --git a/docs/src/explanations/modules.md b/docs/src/explanations/modules.md
index f82a14d6..fcdc6020 100644
--- a/docs/src/explanations/modules.md
+++ b/docs/src/explanations/modules.md
@@ -132,7 +132,7 @@ class FooWrapper extends RawModule {
 In the example above, the `RawModule` is used to change the reset polarity
 of module `SlaveSpi`. Indeed, the reset is active high by default in Chisel
 modules, then using `withClockAndReset(clock, !rstn)` we can use an active low
-reset in entire design.
+reset in the entire design.
 
-The clock is just wired as it, but if needed, `RawModule` can be used in
+The clock is just wired as is, but if needed, `RawModule` can be used in
 conjunction with `BlackBox` to connect a differential clock input for example.
diff --git a/docs/src/explanations/multi-clock.md b/docs/src/explanations/multi-clock.md
index 6e9afd5a..eafb5372 100644
--- a/docs/src/explanations/multi-clock.md
+++ b/docs/src/explanations/multi-clock.md
@@ -3,6 +3,8 @@ layout: docs
 title:  "Multiple Clock Domains"
 section: "chisel3"
 ---
+# Multiple Clock Domains
+
 Chisel 3 supports multiple clock domains as follows.
 
 Note that in order to cross clock domains safely, you will need appropriate synchronization logic (such as an asynchronous FIFO). You can use the [AsyncQueue library](https://github.com/ucb-bar/asyncqueue) to do this easily.
diff --git a/docs/src/explanations/naming.md b/docs/src/explanations/naming.md
index 60c653aa..a9f21936 100644
--- a/docs/src/explanations/naming.md
+++ b/docs/src/explanations/naming.md
@@ -3,6 +3,7 @@ layout: docs
 title:  "Naming"
 section: "chisel3"
 ---
+# Naming
 
 Historically, Chisel has had trouble reliably capturing the names of signals. The reasons for this are due to (1)
 primarily relying on reflection to find names, (2) using `@chiselName` macro which had unreliable behavior.