Eliminate outdated parts of readme, add skeleton for new format

1 files changed, 57 insertions, 53 deletions

diff --git a/README.md b/README.md
index d4a8bacf..9f83f7ba 100644
--- a/README.md
+++ b/README.md
@@ -1,64 +1,68 @@
 # Chisel3
-chisel3 is a new FIRRTL based chisel
-
-the current backward incompatiabilities with chisel 2.x are:
-
-```scala
-val wire = Bits(width = 15)
-```
-is
-
-```scala
-val wire = Wire(Bits(width = 15))
-```
-
-## Chisel3 Infrastructure.
-
-Chisel3 is much more modular than Chisel2. What was once provided by a
-monolithic Scala program, is provided by separate components.
-
-Currently, those components are:
- - Chisel3 (Scala)
- - firrtl (Stanza)
-
-and for the C++ simulator
- - flo-llvm (C++)
- - clang
-
-firrtl can generate Verilog output directly, so fewer components are
-required for Verilog testing.
-
-### Stanza
+Chisel3 is a new FIRRTL based chisel
+
+*TODO: A better description, perhaps lifted off Chisel2's README*
+
+## 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:  
+   ```
+   val wire = Bits(width = 15)
+   ```  
+   becomes (in Chisel3):  
+   ```
+   val wire = Wire(Bits(width = 15))
+   ```
+
+## Getting Started
+
+### Overview
+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)
+ - Optionally, Verilog to C++ (for simulation and testing)
+
+#### Stanza
 In order to build firrtl, you need a (currently patched) copy of
 Stanza. (We should add this to the firrtl repo in utils/bin.)
 
-### firrtl
-We assume that copies (or links to) firrtl are in
-chisel3/bin. flo-llvm and clang should be found in your $PATH.
+### Hello, World
+
+*TODO: quick "Hello, World" tutorial*
 
-Follow the instructions on the firrtl repo for building firrtl and put
-the resulting binary (utils/bin/firrtl) in chisel3/bin.
+## For Developers
 
-### flo-llvm
-flo-llvm is Palmer's flo to (.o,.v) converter. It's hosted at:
-	 https://github.com/ucb-bar/flo
-and
-	 https://github.com/palmer-dabbelt/flo-llvm
+### Environment Setup
 
+*TODO: tools needed*
 
-Installation instructions can be found at:
-	 https://wiki.eecs.berkeley.edu/dreamer/Main/DistroSetup
+*TODO: running Scala unit tests locally*
 
-### clang
-clang is available for Linux and Mac OS X and usually comes installed
-with development tools. You need to ensure that the version you're
-using is compatible with flo-llvm (currently, clang/llvm 3.6). There
-are instructions on the web for managing multiple versions of
-clang/llvm.
+*TODO: running circuit regression tests locally*
 
-Once you have all the components in place, build and publish Chisel3:
+### Chisel3 Architecture Overview
 
-```shell
-% cd chisel3
-% sbt clean publish-local
-```
+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*
+ 
+Also included is:
+ - **The standard library** of circuit generators, currently Utils.scala. 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*