Merge pull request #81 from ucb-bar/readmeupdate

Update README with more architecture details and new testing flow

1 files changed, 66 insertions, 30 deletions

diff --git a/README.md b/README.md
index 3fe2130b..279b2299 100644
--- a/README.md
+++ b/README.md
@@ -38,11 +38,21 @@ modifications are:
 Chisel3 is much more modular than Chisel2, and the compilation pipeline looks
 like:
  - Chisel3 (Scala) to FIRRTL (this is your "Chisel RTL").
- - FIRRTL to Verilog (which then be passed into FPGA or ASIC tools). Repository
- with the compiler and installation instructions are
- [here](https://github.com/ucb-bar/firrtl).
- - Optionally, Verilog to C++ (for simulation and testing).  
- *TODO: Verilator support*
+ - [FIRRTL](https://github.com/ucb-bar/firrtl) to Verilog (which then be passed
+ into FPGA or ASIC tools).
+ - Verilog to C++ for simulation and testing using
+ [Verilator](http://www.veripool.org/wiki/verilator).
+
+### Installation
+To compile down to Verilog for either simulation or synthesis, you will need to 
+download and install [FIRRTL](https://github.com/ucb-bar/firrtl). Currently,
+FIRRTL is written in Stanza, which means it only runs on Linux or OS X. A
+future Scala rewrite is planned which should also allow Windows compatibility.
+
+To compile Verilog down to C++ for simulation (like the included unit testing
+infrastructure uses), you will need to have
+[Verilator](http://www.veripool.org/wiki/verilator) installed and in your
+PATH. Verilator is available via the package manager for some operating systems.
 
 ### Data Types Overview
 These are the base data types for defining circuit wires (abstract types which
@@ -51,21 +61,49 @@ may not be instantiated are greyed out):
 ![Image](doc/images/type_hierarchy.png?raw=true)
 
 ### Chisel Tutorial
-*TODO: quick howto for running chisel-tutorial*
+*TODO: quick howto for running chisel-tutorial, once chisel-tutorial exists*
 
 ## For Hardware Engineers
 This section describes how to get started using Chisel to create a new RTL
 design from scratch.
 
 ### Project Setup
-*TODO: tools needed*
-
 *TODO: recommended sbt style, project structure* 
 
-### RTL and Verification
-*TODO: project boilerplate: import statements, main() contents*
+### RTL
+*TODO: toy example*
+
+### Verification
+*The simulation unit testing infrastructure is still a work in progress.*
+
+See `src/test/scala/chiselTests` for example unit tests. Assert.scala is a
+pretty bare-bones unittest which also somewhat verifies the testing system
+itself.
 
-*TODO: recommended test structure*
+Unit tests are written with the ScalaTest unit testing framework, optionally
+with ScalaCheck generators to sweep the parameter space where desired. 
+
+`BasicTester`-based tests run a single circuit in simulation until either the
+test finishes or times out after a set amount of cycles. After compilation,
+there is no communication between the testdriver and simulation (unlike
+Chisel2's Tester, which allowed dynamic peeks and pokes), so all testvectors
+must be determined at compile time.
+
+The circuits run must subclass `BasicTester`, which is a Module with the
+addition of a `stop` function which finishes the testbench and reports success.
+Any `assert`s that trigger (in either the `BasicTester` or a submodule) will
+cause the test to fail. `printf`s will forward to the console.
+
+To write a test using the `BasicTester` that integrates with sbt test, create
+a class that extends either `ChiselFlatSpec` (BDD-style testing) or
+`ChiselPropSpec` (ScalaCheck generators). In the test content, use
+```
+assert(execute{ new MyTestModule })
+``` 
+where `MyTestModule` is your top-level test circuit that extends
+`BasicTester`.
+
+*A more Chisel2-like tester may come in the future.*
 
 ### Compiling to Simulation
 *TODO: commands to compile project to simulation*
@@ -85,11 +123,9 @@ sbt compile
 to compile the Chisel library. If the compilation succeeded, you can then run
 the included unit tests by invoking:
 ```
-sbt *TODO WRITE ME*
+sbt test
 ``` 
 
-*TODO: circuit test cases*
-
 ### Running Projects Against Local Chisel
 To publish your version of Chisel to the local Ivy (sbt's dependency manager)
 repository, run:  
@@ -113,22 +149,22 @@ subfolder to un-publish your local copy of Chisel.
 ### Chisel3 Architecture Overview
 
 The Chisel3 compiler consists of these main parts:
- - **The frontend**, which is the publicly visible "API" of Chisel and what is
- used in Chisel RTL. All these do is build...  
- *TODO: filenames (or package names, once the split is complete*
- - **The intermediate data structures**, which is syntactically very similar
- to FIRRTL. Once the entire circuit has been elaborated, the top-level object
- (a `Circuit`) is then passed to...  
- *TODO: filenames (or package names, once the split is complete*
- - **The FIRRTL emitter**, which turns the intermediate data structures into
- a string that can be written out into a FIRRTL file for further processing.  
- *TODO: filenames (or package names, once the split is complete*
- 
+ - **The frontend**, `chisel.*`, which is the publicly visible "API" of Chisel
+ and what is used in Chisel RTL. These just add data to the...
+ - **The Builder**, `chisel.internal.Builder`, which maintains global state
+ (like the currently open Module) and contains commands, generating...
+ - **The intermediate data structures**, `chisel.firrtl.*`, which are
+ syntactically very similar to FIRRTL. Once the entire circuit has been
+ elaborated, the top-level object (a `Circuit`) is then passed to...
+ - **The FIRRTL emitter**, `chisel.firrtl.Emitter`, which turns the
+ intermediate data structures into a string that can be written out into a
+ FIRRTL file for further processing.
+
 Also included is:
- - **The standard library** of circuit generators, currently Utils.scala. These
+ - **The standard library** of circuit generators, `chisel.util.*`. These
  contain commonly used interfaces and constructors (like `Decoupled`, which
  wraps a signal with a ready-valid pair) as well as fully parameterizable
- circuit generators (like arbiters and muxes).  
- *TODO: update once standard library gets properly broken you* 
- - *TODO: add details on the testing framework*
- - *TODO: add details on simulators*
+ circuit generators (like arbiters and muxes).
+ - **Driver utilities**, `chisel.Driver`, which contains compilation and test
+ functions that are invoked in the standard Verilog generation and simulation
+ testing infrastructure. These can also be used as part of custom flows.