Merge branch 'master' into 3.5-release

5 files changed, 726 insertions, 0 deletions

diff --git a/docs/src/appendix/appendix.md b/docs/src/appendix/appendix.md
new file mode 100644
index 00000000..0efedbfe
--- /dev/null
+++ b/docs/src/appendix/appendix.md
@@ -0,0 +1,14 @@
+---
+layout: docs
+title:  "Appendix"
+section: "chisel3"
+---
+
+# Appendix
+
+This section covers some less-common Chisel topics.
+
+* [Differences between Chisel3 and Chisel2](chisel3-vs-chisel2)
+* [Experimental Features](experimental-features)
+* [Upgrading from Scala 2.11](upgrading-from-scala-2-11)
+* [Versioning](versioning)
diff --git a/docs/src/appendix/chisel3-vs-chisel2.md b/docs/src/appendix/chisel3-vs-chisel2.md
new file mode 100644
index 00000000..cafd29e3
--- /dev/null
+++ b/docs/src/appendix/chisel3-vs-chisel2.md
@@ -0,0 +1,217 @@
+---
+layout: docs
+title:  "Chisel3 vs. Chisel2"
+section: "chisel3"
+---
+
+# Chisel3 vs Chisel2
+```scala mdoc:invisible
+import chisel3._
+```
+
+## Chisel2 Migration
+For those moving from Chisel2, there were some backwards incompatible changes
+and your RTL needs to be modified to work with Chisel3. The required
+modifications are:
+
+ - Wire declaration style:
+```scala
+  val wire = UInt(width = 15)
+```
+   becomes (in Chisel3):
+```scala mdoc:compile-only
+  val wire = Wire(UInt(15.W))
+```
+
+ - I/O declaration style:
+```scala
+   val done = Bool(OUTPUT)
+```
+   becomes (in Chisel3):
+```scala mdoc:compile-only
+   val wire = Output(Bool())
+```
+
+ - Sequential memories:
+```scala mdoc:invisible
+import chisel3._
+val enable = Bool()
+```
+
+```scala
+   val addr = Reg(UInt())
+   val mem = Mem(UInt(8.W), 1024, seqRead = true)
+   val dout = when(enable) { mem(addr) }
+```
+   becomes (in Chisel3):
+```scala mdoc:compile-only
+   val addr = UInt()
+   val mem = SyncReadMem(1024, UInt(8.W))
+   val dout = mem.read(addr, enable)
+```
+
+   Notice the address register is now internal to the SyncReadMem(), but the data
+   will still return on the subsequent cycle.
+
+ - Generating Verilog for a module:
+```scala mdoc:invisible
+import chisel3._
+class Hello extends RawModule
+```
+
+```scala
+   object Hello {
+     def main(args: Array[String]): Unit = {
+       chiselMain(Array("--backend", "v"), () => Module(new Hello()))
+     }
+   }
+```
+   becomes (in Chisel3):
+```scala mdoc:compile-only
+   import chisel3.stage.ChiselStage
+   object Hello {
+     def main(args: Array[String]): Unit = {
+       (new ChiselStage).emitVerilog(new Hello())
+     }
+   }
+```
+
+ - Package changes:
+   - Chisel.log2Ceil -> chisel3.util.log2Ceil
+   - BitPat
+   - Decoupled is also in chisel3.util
+
+Please refer to the [Chisel3 compatibility section](https://github.com/ucb-bar/chisel#chisel3)
+for instructions on preparing your Chisel2 designs for Chisel3.
+
+## Deprecated Usage
+*  `Vec(Reg)` should be replaced with `Reg(Vec)`,
+*  type-only vals (no associated data) must be wrapped in a `Wire()` if they will be the destination of a wiring operation (":=" or " < >"),
+*  masked bit patterns ('b??') should be created using BitPat(), not UInt() or Bits(),
+*  the `clone` method required for parameterized Bundles has been renamed `cloneType`,
+*  the con and alt inputs to a Mux must be type-compatible - both signed or both unsigned,
+*  bulk-connection to a node that has been procedurally assigned-to is illegal,
+*  `!=` is deprecated, use `=/=` instead,
+*  use `SyncReadMem(...)` instead of `Mem(..., seqRead)`,
+*  use `SyncReadMem(n:Int, out: => T)` instead of `SyncReadMem(out: => T, n:Int)`,
+*  use `SyncReadMem(...)` instead of `SeqMem(...)`,
+*  use `Mem(n:Int, t:T)` instead of `Mem(out:T, n:Int)`,
+*  use `Vec(n:Int, gen: => T)` instead of `Vec(gen: => T, n:Int)`,
+*  module io's must be wrapped in `IO()`.
+*  The methods `asInput`, `asOutput`, and `flip` should be replaced by the `Input()`, `Output()`, and `Flipped()` object apply methods.
+
+## Unsupported constructs
+*  `Mem(..., orderedWrites)` is no longer supported,
+*  masked writes are only supported for `Mem[Vec[_]]`,
+* Chisel3 Vecs must all have the same type, unlike with Chisel2. Use `MixedVec` (see [Bundles and Vecs](../explanations/bundles-and-vecs)) for Vecs where the elements are of different types.
+*  connections between `UInt` and `SInt` are illegal.
+*  the `Node` class and object no longer exist (the class should have been private in Chisel2)
+*  `printf()` is defined in the Chisel object and produces simulation printf()'s.
+To use the Scala `Predef.printf()`, you need to qualify it with `Predef`.
+*  in Chisel2, bulk-connects `<>` with unconnected source components do not update connections from the unconnected components.
+** In Chisel3, bulk-connects strictly adhere to last connection semantics and unconnected OUTPUTs will be connected to INPUTs resulting in the assignment of random values to those inputs.
+* In Chisel3, adding hardware inside `BlackBox` for simulation is no longer supported. (#289)
+* `ChiselError` is gone
+  * Change `ChiselError.error("error msg")` to `throw new Error("error msg")`
+  * Change `ChiselError.info("info msg")` to `println("info msg")`
+* In Chisel3, subword assignments are not supported. [Alternative constructions exist](https://github.com/freechipsproject/chisel3/wiki/Cookbook#how-do-i-do-subword-assignment-assign-to-some-bits-in-a-uint) in Chisel3.
+
+## Further changes
+* The clock signal was renamed from `clk` to `clock` in Chisel3.
+* Change `getWidth()` to `getWidth`
+
+## Packaging
+Chisel3 is implemented as several packages.
+The core DSL is differentiated from utility or library classes and objects, testers, and interpreters.
+The prime components of the Chisel3 front end (the DSL and library objects) are:
+* coreMacros - source locators provide Chisel line numbers for `firrtl` detected errors,
+* chiselFrontend - main DSL components,
+* chisel3 - compiler driver, interface packages, compatibility layer.
+
+Due to the wonders of `sbt`, you need only declare a dependency on the chisel3 package, and the others will be downloaded as required.
+
+The `firrtl` compiler is distributed as a separate package, and release versions will also be downloaded automatically as required.
+If you choose to integrate the compiler into your own toolchain, or you're working with the development (master) branch of chisel3, you should clone the [firrtl](https://github.com/ucb-bar/firrtl) repo
+and follow the instructions for installing the `firrtl` compiler.
+
+The testers in Chisel3 are distributed as a separate package.
+If you intend to use them in your tests, you will either need to clone the [chisel-testers](https://github.com/ucb-bar/chisel-testers) repo
+or declare a dependency on the published version of the package.
+See the `build.sbt` file in either the [chisel-template](https://github.com/ucb-bar/chisel-template) or [chisel-tutorial](https://github.com/ucb-bar/chisel-tutorial)
+repos for examples of the latter.
+
+## Simulation
+Chisel2 was capable of directly generating a `C++` simulation from the Chisel code, or a harness for use with a `vcs` simulation.
+Chisel3 relies on [verilator](http://www.veripool.org/wiki/verilator) to generate the `C++` simulation from the Verilog output of `firrtl`.
+See the [Chisel3 README](https://github.com/ucb-bar/chisel3) for directions on installing `verilator`.
+
+## Compile Options and Front End Checks (Strict vs. NotStrict)
+Chisel3 introduces a formal specification for hardware circuit graphs: FIRRTL,
+and Chisel3 itself (the Scala library implementing the Chisel DSL), is a relatively thin front end that generates FIRRTL.
+Since the `firrtl` parser needs to validate FIRRTL input, most of the checks that were performed in Chisel2 were eliminated
+from the initial Chisel3 front end (the DRY principle).
+
+However, this does impact the ability to provide detailed messages for error conditions that could be detected in the Chisel3
+front end. The decision was made to optionally enable stricter error checking (for connections and the use of raw types versus
+hardware objects), based on specific imports.
+This allows designs to move from less strict front end checks (largely compatible with Chisel2), to stricter checking,
+on a file by file basis, by adjusting specific import statements.
+
+```scala mdoc:compile-only
+    import chisel3.ExplicitCompileOptions.Strict
+```
+
+enables stricter connection and usage checks, while
+
+```scala mdoc:compile-only
+    import chisel3.ExplicitCompileOptions.NotStrict
+```
+
+defers these checks to the `firrtl` compiler.
+
+By default, the `Chisel` compatibility layer, invoked by:
+
+```scala
+    import Chisel._
+```
+
+implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.NotStrict`
+
+whereas the Chisel3 package, invoked by:
+
+```scala
+    import chisel3._
+```
+
+implicitly defines the compile options as `chisel3.core.ExplicitCompileOptions.Strict`
+
+Again, these implicit compile options definitions may be overridden by explicit imports.
+
+Currently, the specific error checks (found in [CompileOptions.scala](https://github.com/ucb-bar/chisel3/blob/master/chiselFrontend/src/main/scala/chisel3/core/CompileOptions.scala)) are:
+
+```scala
+    trait CompileOptions {
+      // Should Bundle connections require a strict match of fields.
+      // If true and the same fields aren't present in both source and sink, a MissingFieldException,
+      // MissingLeftFieldException, or MissingRightFieldException will be thrown.
+      val connectFieldsMustMatch: Boolean
+      // When creating an object that takes a type argument, the argument must be unbound (a pure type).
+      val declaredTypeMustBeUnbound: Boolean
+      // Module IOs should be wrapped in an IO() to define their bindings before the reset of the module is defined.
+      val requireIOWrap: Boolean
+      // If a connection operator fails, don't try the connection with the operands (source and sink) reversed.
+      val dontTryConnectionsSwapped: Boolean
+      // If connection directionality is not explicit, do not use heuristics to attempt to determine it.
+      val dontAssumeDirectionality: Boolean
+      // Issue a deprecation warning if Data.{flip, asInput,asOutput} is used
+      // instead of Flipped, Input, or Output.
+      val deprecateOldDirectionMethods: Boolean
+      // Check that referenced Data have actually been declared.
+      val checkSynthesizable: Boolean
+    }
+```
+
+`chisel3.core.ExplicitCompileOptions.Strict` sets all CompileOptions fields to true and
+`chisel3.core.ExplicitCompileOptions.NotStrict` sets them all to false.
+Clients are free to define their own settings for these options.
+Examples may be found in the test [CompileOptionsSpec](https://github.com/ucb-bar/chisel3/blob/master/src/test/scala/chiselTests/CompileOptionsTest.scala)
diff --git a/docs/src/appendix/experimental-features.md b/docs/src/appendix/experimental-features.md
new file mode 100644
index 00000000..4b1208aa
--- /dev/null
+++ b/docs/src/appendix/experimental-features.md
@@ -0,0 +1,372 @@
+---
+layout: docs
+title:  "Experimental Features"
+section: "chisel3"
+---
+
+Chisel has a number of new features that are worth checking out.  This page is an informal list of these features and projects.
+
+- [FixedPoint](#fixed-point)
+- [Module Variants](#module-variants)
+- [Module Variants](#bundle-literals)
+- [Interval Type](#interval-type)
+- [Loading Memories for simulation or FPGA initialization](#loading-memories)
+
+### FixedPoint  <a name="fixed-point"></a>
+FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc.  Most common math and logic operations
+are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify
+circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala)
+
+### Module Variants <a name="module-variants"></a>
+The standard Chisel *Module* requires a `val io = IO(...)`, the experimental package introduces several
+new ways of defining Modules
+- BaseModule: no contents, instantiable
+- BlackBox extends BaseModule
+- UserDefinedModule extends BaseModule: this module can contain Chisel RTL. No default clock or reset lines. No default IO. - User should be able to specify non-io ports, ideally multiple of them.
+- ImplicitModule extends UserModule: has clock, reset, and io, essentially current Chisel Module.
+- RawModule: will be the user-facing version of UserDefinedModule
+- Module: type-aliases to ImplicitModule, the user-facing version of ImplicitModule.
+
+### Bundle Literals <a name="bundle-literals"></a>
+
+Bundle literals can be constructed via an experimental import:
+
+```scala mdoc
+import chisel3._
+import chisel3.experimental.BundleLiterals._
+
+class MyBundle extends Bundle {
+  val a = UInt(8.W)
+  val b = Bool()
+}
+
+class Example extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.a -> 8.U, _.b -> true.B)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example)
+```
+
+Partial specification is allowed, defaulting any unconnected fields to 0 (regardless of type).
+
+```scala mdoc
+class Example2 extends RawModule {
+  val out = IO(Output(new MyBundle))
+  out := (new MyBundle).Lit(_.b -> true.B)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example2)
+```
+
+Bundle literals can also be nested arbitrarily.
+
+```scala mdoc
+class ChildBundle extends Bundle {
+  val foo = UInt(8.W)
+}
+
+class ParentBundle extends Bundle {
+  val a = UInt(8.W)
+  val b = new ChildBundle
+}
+
+class Example3 extends RawModule {
+  val out = IO(Output(new ParentBundle))
+  out := (new ParentBundle).Lit(_.a -> 123.U, _.b -> (new ChildBundle).Lit(_.foo -> 42.U))
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new Example3)
+```
+
+### Vec Literals
+
+Vec literals are very similar to Bundle literals and can be constructed via an experimental import.
+They can be constructed in two forms, with type and length inferred as in: 
+
+```scala mdoc
+import chisel3._
+import chisel3.experimental.VecLiterals._
+
+class VecExample1 extends Module {
+  val out = IO(Output(Vec(2, UInt(4.W))))
+  out := Vec.Lit(0xa.U, 0xbb.U)
+}
+```
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new VecExample1)
+```
+
+or explicitly as in:
+
+```scala mdoc
+import chisel3._
+import chisel3.experimental.VecLiterals._
+
+class VecExample1a extends Module {
+  val out = IO(Output(Vec(2, UInt(4.W))))
+  out := Vec(2, UInt(4.W)).Lit(0 -> 1.U, 1 -> 2.U)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new VecExample1a)
+```
+
+The following examples all use the explicit form.
+With the explicit form partial specification is allowed.
+When used with as a `Reg` `reset` value, only specified indices of the `Reg`'s `Vec`
+will be reset
+
+```scala mdoc
+class VecExample2 extends RawModule {
+  val out = IO(Output(Vec(4, UInt(4.W))))
+  out := Vec(4, UInt(4.W)).Lit(0 -> 1.U, 3 -> 7.U)
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new VecExample2)
+```
+
+Registers can be initialized from Vec literals
+
+```scala mdoc
+class VecExample3 extends Module {
+  val out = IO(Output(Vec(4, UInt(8.W))))
+  val y = RegInit(
+    Vec(4, UInt(8.W)).Lit(0 -> 0xAB.U(8.W), 1 -> 0xCD.U(8.W), 2 -> 0xEF.U(8.W), 3 -> 0xFF.U(8.W))
+  )
+  out := y
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new VecExample3)
+```
+
+Vec literals can also be nested arbitrarily.
+
+```scala mdoc
+class VecExample5 extends RawModule {
+  val out = IO(Output(Vec(2, new ChildBundle)))
+  out := Vec(2, new ChildBundle).Lit(
+    0 -> (new ChildBundle).Lit(_.foo -> 42.U),
+    1 -> (new ChildBundle).Lit(_.foo -> 7.U)
+  )
+}
+```
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new VecExample5)
+```
+
+### Interval Type <a name="interval-type"></a>
+
+**Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers.
+It augments these types with range information, i.e. upper and lower numeric bounds.
+This information can be used to exercise tighter programmatic control over the ultimate widths of
+signals in the final circuit.  The **Firrtl** compiler can infer this range information based on
+operations and earlier values in the circuit. Intervals support all the ordinary bit and arithmetic operations
+associated with UInt, SInt, and FixedPoint and adds the following methods for manipulating the range of
+a **source** Interval with the IntervalRange of **target** Interval
+
+#### Clip -- Fit the value **source** into the IntervalRange of **target**, saturate if out of bounds
+The clip method applied to an interval creates a new interval based on the argument to clip,
+and constructs the necessary hardware so that the source Interval's value will be mapped into the new Interval.
+Values that are outside the result range will be pegged to either maximum or minimum of result range as appropriate.
+
+> Generates necessary hardware to clip values, values greater than range are set to range.high, values lower than range are set to range min.
+
+#### Wrap -- Fit the value **source** into the IntervalRange of **target**, wrapping around if out of bounds
+The wrap method applied to an interval creates a new interval based on the argument to wrap,
+and constructs the necessary
+hardware so that the source Interval's value will be mapped into the new Interval.
+Values that are outside the result range will be wrapped until they fall within the result range.
+
+> Generates necessary hardware to wrap values, values greater than range are set to range.high, values lower than range are set to range min.
+
+> Does not handle out of range values that are less than half the minimum or greater than twice maximum
+
+#### Squeeze -- Fit the value **source** into the smallest IntervalRange based on source and target.
+The squeeze method applied to an interval creates a new interval based on the argument to clip, the two ranges must overlap
+behavior of squeeze with inputs outside of the produced range is undefined.
+
+> Generates no hardware, strictly a sizing operation
+
+##### Range combinations
+
+| Condition | A.clip(B) | A.wrap(B) | A.squeeze(B) |
+| --------- | --------------- | --------------- | --------------- |
+| A === B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A contains B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| B contains A   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A min < B min, A max in B  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A min in B, A max > B max  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
+| A strictly less than B   | error               | error               | error               |
+| A strictly greater than B   | error               | error               | error               |
+
+
+#### Applying binary point operators to an Interval
+
+Consider a Interval with a binary point of 3: aaa.bbb
+
+| operation | after operation | binary point | lower | upper | meaning |
+| --------- | --------------- | ------------ | ----- | ----- | ------- |
+| setBinaryPoint(2) | aaa.bb |  2 | X | X  | set the precision |
+| shiftLeftBinaryPoint(2) | a.aabbb |  5 | X | X  | increase the precision |
+| shiftRighBinaryPoint(2) | aaaa.b |  1 | X | X  | reduce the precision |
+
+## Loading Memories for simulation or FPGA initialization <a name="loading-memories"></a>
+
+Chisel supports multiple experimental methods for annotating memories to be loaded from a text file containing hex or binary data. When using verilog simulation it uses the `$readmemh` or `$readmemb` verilog extension. The treadle simulator can also load memories using the same annotation.
+
+### Inline initialization with external file
+
+Memories can be initialized by generating inline `readmemh` or `readmemb` statements in the output Verilog.
+
+The function `loadMemoryFromFileInline` from `chisel3.util.experimental` allows the memory to be initialized by the synthesis software from the specified file. Chisel does not validate the file contents nor its location. Both the memory initialization file and the Verilog source should be accessible for the toolchain.
+
+```scala mdoc:silent
+import chisel3._
+import chisel3.util.experimental.loadMemoryFromFileInline
+
+class InitMemInline(memoryFile: String = "") extends Module {
+  val width: Int = 32
+  val io = IO(new Bundle {
+    val enable = Input(Bool())
+    val write = Input(Bool())
+    val addr = Input(UInt(10.W))
+    val dataIn = Input(UInt(width.W))
+    val dataOut = Output(UInt(width.W))
+  })
+
+  val mem = SyncReadMem(1024, UInt(width.W))
+  // Initialize memory
+  if (memoryFile.trim().nonEmpty) {
+    loadMemoryFromFileInline(mem, memoryFile)
+  }
+  io.dataOut := DontCare
+  when(io.enable) {
+    val rdwrPort = mem(io.addr)
+    when (io.write) { rdwrPort := io.dataIn }
+      .otherwise    { io.dataOut := rdwrPort }
+  }
+}
+```
+
+The default is to use `$readmemh` (which assumes all numbers in the file are in ascii hex),
+but to use ascii binary there is an optional `hexOrBinary` argument which can be set to `MemoryLoadFileType.Hex` or `MemoryLoadFileType.Binary`. You will need to add an additional import.
+
+By default, the inline initialization will generate the memory `readmem` statements inside an `ifndef SYNTHESIS` block, which suits ASIC workflow.
+
+Some synthesis tools (like Synplify and Yosys) define `SYNTHESIS` so the `readmem` statement is not read when inside this block.
+
+To control this, one can use the `MemoryNoSynthInit` and `MemorySynthInit` annotations from `firrtl.annotations`. The former which is the default setting when no annotation is present generates `readmem` inside the block. Using the latter, the statement are generated outside the `ifndef` block so it can be used by FPGA synthesis tools.
+
+Below an example for initialization suited for FPGA workflows:
+
+```scala mdoc:silent
+import chisel3._
+import chisel3.util.experimental.loadMemoryFromFileInline
+import chisel3.experimental.{annotate, ChiselAnnotation}
+import firrtl.annotations.MemorySynthInit
+
+class InitMemInlineFPGA(memoryFile: String = "") extends Module {
+  val width: Int = 32
+  val io = IO(new Bundle {
+    val enable = Input(Bool())
+    val write = Input(Bool())
+    val addr = Input(UInt(10.W))
+    val dataIn = Input(UInt(width.W))
+    val dataOut = Output(UInt(width.W))
+  })
+
+  // Notice the annotation below
+  annotate(new ChiselAnnotation {
+    override def toFirrtl =
+      MemorySynthInit
+  })
+
+  val mem = SyncReadMem(1024, UInt(width.W))
+  if (memoryFile.trim().nonEmpty) {
+    loadMemoryFromFileInline(mem, memoryFile)
+  }
+  io.dataOut := DontCare
+  when(io.enable) {
+    val rdwrPort = mem(io.addr)
+    when (io.write) { rdwrPort := io.dataIn }
+      .otherwise    { io.dataOut := rdwrPort }
+  }
+}
+```
+
+#### SystemVerilog Bind Initialization
+
+Chisel can also initialize memories by generating a SV bind module with `readmemh` or `readmemb` statements by using the function `loadMemoryFromFile` from `chisel3.util.experimental`.
+
+```scala mdoc:silent
+import chisel3._
+import chisel3.util.experimental.loadMemoryFromFile
+
+class InitMemBind(val bits: Int, val size: Int, filename: String) extends Module {
+  val io = IO(new Bundle {
+    val nia = Input(UInt(bits.W))
+    val insn = Output(UInt(32.W))
+  })
+
+  val memory = Mem(size, UInt(32.W))
+  io.insn := memory(io.nia >> 2);
+  loadMemoryFromFile(memory, filename)
+}
+```
+
+Which generates the bind module:
+
+```verilog
+module BindsTo_0_Foo(
+  input         clock,
+  input         reset,
+  input  [31:0] io_nia,
+  output [31:0] io_insn
+);
+
+initial begin
+  $readmemh("test.hex", Foo.memory);
+end
+endmodule
+
+bind Foo BindsTo_0_Foo BindsTo_0_Foo_Inst(.*);
+```
+
+### Notes on files
+
+There is no simple answer to where to put the `hex` or `bin` file with the initial contents. It's probably best to create a resource directory somewhere and reference that through a full path or place the file beside the generated Verilog. Another option is adding the path to the memory file in the synthesis tool path. Because these files may be large, Chisel does not copy them.
+> Don't forget there is no decimal option, so a 10 in an input file will be 16 decimal
+
+See: [ComplexMemoryLoadingSpec.scala](https://github.com/freechipsproject/chisel-testers/blob/master/src/test/scala/examples/ComplexMemoryLoadingSpec.scala) and
+[LoadMemoryFromFileSpec.scala](https://github.com/freechipsproject/chisel-testers/blob/master/src/test/scala/examples/LoadMemoryFromFileSpec.scala)
+for working examples.
+
+
+### Aggregate memories
+
+Aggregate memories are supported but in bit of a clunky way. Since they will be split up into a memory per field, the following convention was adopted.  When specifying the file for such a memory the file name should be regarded as a template. If the memory is a Bundle e.g.
+
+```scala mdoc:compile-only
+class MemDataType extends Bundle {
+  val a = UInt(16.W)
+  val b = UInt(32.W)
+  val c = Bool()
+}
+```
+
+The memory will be split into `memory_a`, `memory_b`, and `memory_c`. Similarly if a load file is specified as `"memory-load.txt"` the simulation will expect that there will be three files, `"memory-load_a.txt"`, `"memory-load_b.txt"`, `"memory-load_c.txt"`
+
+> Note: The use of `_` and that the memory field name is added before any file suffix. The suffix is optional but if present is considered to be the text after the last `.` in the file name.
diff --git a/docs/src/appendix/upgrading-from-scala-2-11.md b/docs/src/appendix/upgrading-from-scala-2-11.md
new file mode 100644
index 00000000..26e2d252
--- /dev/null
+++ b/docs/src/appendix/upgrading-from-scala-2-11.md
@@ -0,0 +1,88 @@
+---
+layout: docs
+title:  "Upgrading From Scala 2.11"
+section: "chisel3"
+redirect_from:
+  - /chisel3/upgrading-from-scala-2-11.html
+---
+
+<!-- Prelude -->
+```scala mdoc:invisible
+import chisel3._
+```
+<!-- End Prelude -->
+
+## Upgrading From Scala 2.11 to 2.12
+
+As the latest (and probably last) release of Scala 2.11 (2.11.12) was released on 2 November 2017, the time has come to deprecate support for Scala 2.11.
+Chisel 3.4 is the last version of Chisel that will support Scala 2.11, so users should upgrade to Scala 2.12
+This document is intended to help guide Chisel users through this process; both the "Why?" and the "How?".
+
+### Scala Versioning
+
+<!-- TODO, this should be discussed in a different document about "Building Chisel" or something-->
+
+Scala versions have the following structure: `2.X.Y` where `X` is the _major version_ and `Y` is the _minor version_.
+Note that while we keep the leading `2` constant, there is a project, [Dotty](https://dotty.epfl.ch/), that is slated to become Scala 3.
+
+Scala maintains both source and binary compatiblity between minor versions, but not between major versions.
+Binary compatibility is defined at the level of the Java Byte Code (the `.class` or `.jar` files compiled from `.scala`).
+This means that Scala projects that support multiple major versions of Scala must be compiled and published for each supported version.
+When publishing artifacts to Maven repositories, this manifests as an appendix on the _Artifact ID_.
+Taking Chisel v3.3.2 as an example, the "Artifact ID" is ["chisel3_2.12"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.12)
+for Scala 2.12, and ["chisel3_2.11"](https://search.maven.org/artifact/edu.berkeley.cs/chisel3_2.11) for Scala 2.11.
+
+For more information, see the documentation on the Scala website:
+* [Binary Compatibility of Scala Releases](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html)
+* [Binary Compatibility for Library Authoers](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html)
+
+
+### How to Upgrade
+
+For most users, this is as simple as changing the `scalaVersion` field in your `build.sbt`:
+```scala
+scalaVersion := "2.11.12"
+```
+Becomes
+```scala
+scalaVersion := "2.12.12"
+```
+Now, the next time you run SBT, it will be using the Scala 2.12 version of Chisel 3 (as well as any other dependencies you have).
+
+### Common Issues
+
+As mentioned in the [previous section](#scala-versioning), Scala does *not* maintain source compatibilty between major versions.
+Put another way, sometimes they break things in backwards incompatible ways.
+This section includes some common issues that Chisel users run into and how to fix them.
+
+For complete information about changes, please see the [release notes for Scala 2.12.0](https://www.scala-lang.org/news/2.12.0/).
+
+#### Value is not a member of chisel3.Bundle
+
+The most common problem for Chisel users upgrading from Scala 2.11 to 2.12 is a change in Scala type inference.
+This usually occurs in the context of `io` `Bundles` in `Modules`, given:
+```scala mdoc:silent
+class Foo extends Module {
+  val io = IO(new Bundle {
+    val in = Input(Bool())
+    val out = Output(Bool())
+  })
+
+  io.out := ~io.in
+}
+```
+You may see an error that says somethign like "value out is not a member of chisel3.Bundle":
+```
+[error] /workspace/src/main/scala/gcd/Foo.scala:9:6: value out is not a member of chisel3.Bundle
+[error]   io.out := ~io.in
+[error]      ^
+[error] /workspace/src/main/scala/gcd/Foo.scala:9:17: value in is not a member of chisel3.Bundle
+[error]   io.out := ~io.in
+[error]                 ^
+[error] two errors found
+```
+This can be worked around by adding `-Xsource:2.11` to your `scalacOptions`.
+This is most commonly set in your `build.sbt`.
+For an example, see the [chisel-template's build.sbt](https://github.com/freechipsproject/chisel-template/blob/11f6ca470120908d167cb8dc3241953eb31d0acb/build.sbt#L10).
+
+
diff --git a/docs/src/appendix/versioning.md b/docs/src/appendix/versioning.md
new file mode 100644
index 00000000..8c5ef91c
--- /dev/null
+++ b/docs/src/appendix/versioning.md
@@ -0,0 +1,35 @@
+---
+layout: docs
+title:  "Versioning"
+section: "chisel3"
+---
+
+# Chisel Project Versioning
+
+Chisel and related projects follow a versioning scheme similar to [PVP](https://pvp.haskell.org/).
+Project versions are of the form `A.B.C` where `A.B` specifies the _Major_ version and `C` specifies the _Minor_ version.
+Projects maintain _binary compatibility_ between minor versions of the same major version.
+For example, a project compiled against Chisel3 version 3.4.0 can be used with Chisel3 version 3.4.2 or 3.4.15 without recompilation.
+
+# Compatible Versions
+
+Historically, due to a mistake in versioning with chisel-iotesters as well as some projects originating later than others,
+the compatible versions of Chisel-related projects has not been obvious.
+We are taking steps to improve the situation by bringing the major versions more in line (the `B` part in `A.B.C`),
+but the inconsistencies remain in previously published versions.
+
+Please use the following table to determine which versions of the related projects are compatible.
+In particular, versions of projects in this table were compiled against the version of any dependencies listed in the same row.
+For example, `chisel-iotesters` version 1.4 was compiled against `chisel3` version 3.3.
+
+| chisel3 | chiseltest | chisel-iotesters | firrtl | treadle | diagrammer | firrtl-interpreter<sup>2</sup> |
+| ------- | ---------- | ---------------- | ------ | ------- | ---------- | ----- |
+| 3.4     | 0.3        | 1.5              | 1.4    | 1.3     | 1.3        | 1.4 |
+| 3.3     | 0.2        | 1.4              | 1.3    | 1.2     | 1.2        | 1.3 |
+| 3.2     | 0.1<sup>1</sup>  | 1.3        | 1.2    | 1.1     | 1.1        | 1.2 |
+| 3.1     | -          | 1.2              | 1.1    | 1.0     | 1.0        | 1.1 |
+| 3.0     | -          | 1.1              | 1.0    | -<sup>3</sup> | -    | 1.0 |
+
+<sup>1</sup> chiseltest 0.1 was published under artifact name [chisel-testers2](https://search.maven.org/search?q=a:chisel-testers2_2.12) (0.2 was published under both artifact names)    
+<sup>2</sup> Replaced by Treadle, in maintenance mode only since version 1.1    
+<sup>3</sup> Treadle was preceded by the firrtl-interpreter