First crack at updating the readme (#1106)

* First crack at updating the readme
Goals
Include up front example
Simplify
Get users to things quicker
Move complicated details to wiki.

* headers were not working,
intellij and github don't use same render for .md files

* Fix verb agreement

* Add a fir filter diagram
Compact the fir-filter code a bit

* More compact filter

* Additional README.md updates

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Don't use chisel-lang.org, drop HCL

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Fix link to fir image, make it relative

* Proposed readme changes

* Resize picture, restyle doc bullets

1 files changed, 99 insertions, 158 deletions

diff --git a/README.md b/README.md
index 9f82a59d..c0000c34 100644
--- a/README.md
+++ b/README.md
@@ -6,215 +6,156 @@
 [![CircleCI](https://circleci.com/gh/freechipsproject/chisel3/tree/master.svg?style=shield)](https://circleci.com/gh/freechipsproject/chisel3/tree/master)
 [![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/freechipsproject/chisel3.svg?label=release)](https://github.com/freechipsproject/chisel3/releases/latest)
 
-Chisel is a new hardware construction language to support advanced hardware design and circuit generation.
-The latest iteration of [Chisel](https://chisel.eecs.berkeley.edu/) is Chisel3,
-which uses Firrtl as an intermediate hardware representation language.
-
-Chisel3 releases are available as jars on Sonatype/Nexus/Maven and as tagged branches on the [releases tab](https://github.com/freechipsproject/chisel3/releases) of this repository.
-
-Please visit the [Wiki](https://github.com/ucb-bar/chisel3/wiki) for documentation!
-
-The ScalaDoc for Chisel3 is available at the [API tab on the Chisel web site.](https://chisel.eecs.berkeley.edu/api/latest/index.html)
-
-## Overview
-The standard Chisel3 compilation pipeline looks like:
-- Chisel3 (Scala) to Firrtl (this is your "Chisel RTL").
-- [Firrtl](https://github.com/ucb-bar/firrtl) to Verilog (which can then be passed into FPGA or ASIC tools).
-- Verilog to C++ for simulation and testing using [Verilator](http://www.veripool.org/wiki/verilator).
-
-## Installation
-This will walk you through installing Chisel and its dependencies:
-- [sbt](http://www.scala-sbt.org/), which is the preferred Scala build system and what Chisel uses.
-- [Firrtl](https://github.com/ucb-bar/firrtl), which compiles Chisel's IR down to Verilog.
-  If you're building from a release branch of Chisel3, separate installation of Firrtl is no longer required: the required jar will be automatically downloaded by sbt.
-  If you're building chisel3 from the master branch, you'll need to follow the directions on the [Firrtl repository](https://github.com/ucb-bar/firrtl) to publish a local copy of the required jar.
-- [Verilator](http://www.veripool.org/wiki/verilator), which compiles Verilog down to C++ for simulation.
-  The included unit testing infrastructure uses this.
-
-### (Ubuntu-like) Linux
-
-1. Install Java
-   ```
-   sudo apt-get install default-jdk
-   ```
-1. [Install sbt](http://www.scala-sbt.org/release/docs/Installing-sbt-on-Linux.html),
-    which isn't available by default in the system package manager:
-    ```
-    echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
-    sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 642AC823
-    sudo apt-get update
-    sudo apt-get install sbt
-    ```
-1. Install Verilator.
-    We currently recommend Verilator version 4.006.
-    Follow these instructions to compile it from source.
-
-    1. Install prerequisites (if not installed already):
-        ```
-        sudo apt-get install git make autoconf g++ flex bison
-        ```
-
-    2. Clone the Verilator repository:
-        ```
-        git clone http://git.veripool.org/git/verilator
-        ```
-
-    3. In the Verilator repository directory, check out a known good version:
-        ```
-        git pull
-        git checkout verilator_4_006
-        ```
-
-    4. In the Verilator repository directory, build and install:
-        ```
-        unset VERILATOR_ROOT # For bash, unsetenv for csh
-        autoconf # Create ./configure script
-        ./configure
-        make
-        sudo make install
-        ```
-
-### Arch Linux
+[**Chisel**](https://chisel.eecs.berkeley.edu) is a hardware design language that facilitates **advanced circuit generation and design reuse for both ASIC and FPGA digital logic designs**.
+Chisel adds hardware construction primitives to the [Scala](https://www.scala-lang.org) programming language, providing designers with the power of a modern programming language to write complex, parameterizable circuit generators that produce synthesizable Verilog.
+This generator methodology enables the creation of re-usable components and libraries, such as the FIFO queue and arbiters in the [Chisel Standard Library](https://chisel.eecs.berkeley.edu/api/latest/chisel3/util/index.html), raising the level of abstraction in design while retaining fine-grained control. 
 
-```
-yaourt -S firrtl-git verilator sbt
-```
+For more information on the benefits of Chisel see: ["What benefits does Chisel offer over classic Hardware Description Languages?"](https://stackoverflow.com/questions/53007782/what-benefits-does-chisel-offer-over-classic-hardware-description-languages)
+
+Chisel is powered by [FIRRTL (Flexible Intermediate Representation for RTL)](https://github.com/freechipsproject/firrtl), a hardware compiler framework that performs optimizations of Chisel-generated circuits and supports custom user-defined circuit transformations. 
 
-### Windows
+## What does Chisel code look like?
 
-[Download and install sbt for Windows](https://www.scala-sbt.org/download.html).
+Consider an FIR filter that implements a convolution operation, as depicted in this block diagram:
 
-#### Simulation on Windows
+<img src="doc/images/fir_filter.svg?sanitize=true" width="512" />
 
-The chisel3 regression tests use Verilator as the simulator, but Verilator does not work well on Windows natively.
-However, Verilator works in [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) or in other Linux-compatible environments like Cygwin.
+While Chisel provides similar base primitives as synthesizable Verilog, and *could* be used as such:
 
-Alternatively, if you're using [PeekPokeTester](https://github.com/freechipsproject/chisel-testers) or the [Testers2 alpha](https://github.com/ucb-bar/chisel-testers2), you can use [treadle](https://github.com/freechipsproject/treadle) as the simulation engine.
-Treadle is a FIRRTL simulator written in Scala, and works on any platform that can run Scala code.
-It can simulate any pure Chisel design, but cannot simulate Verilog code and hence will not work on BlackBoxes / ExtModules which do not have corresponding greybox definitions.
+```scala
+// 3-point moving average implemented in the style of a FIR filter
+class MovingAverage3(bitWidth: Int) extends Module {
+  val io = IO(new Bundle {
+    val in = Input(UInt(bitWidth.W))
+    val out = Output(UInt(bitWidth.W))
+  })
 
-There are no issues with generating Verilog from Chisel, which can be pushed to FPGA or ASIC tools.
+  val z1 = RegNext(io.in)
+  val z2 = RegNext(z0)
 
-### Mac OS X
+  io.out := (io.in * 1.U) + (z1 * 1.U) + (z2 * 1.U)
+}
+```
 
+the power of Chisel comes from the ability to create generators, such as n FIR filter that is defined by the list of coefficients:
+```scala
+// Generalized FIR filter parameterized by the convolution coefficients
+class FirFilter(bitWidth: Int, coeffs: Seq[UInt]) extends Module {
+  val io = IO(new Bundle {
+    val in = Input(UInt(bitWidth.W))
+    val out = Output(UInt(bitWidth.W))
+  })
+  // Create the serial-in, parallel-out shift register
+  val zs = Wire(Vec(coeffs.length, UInt(bitWidth.W)))
+  zs(0) := io.in
+  for (i <- 1 until coeffs.length) {
+    zs(i) := zs(i-1)
+  }
+  
+  // Do the multiplies
+  val products = VecInit.tabulate(coeffs.length)(i => zs(i) * coeffs(i))
+  
+  // Sum up the products
+  io.out := products.reduce(_ + _)
+}
 ```
-brew install sbt verilator
+ 
+and use and re-use them across designs:
+```scala
+val movingAverage3Filter = FirFilter(8.W, Seq(1.U, 1.U, 1.U))  // same 3-point moving average filter as before
+val delayFilter = FirFilter(8.W, Seq(0.U, 1.U))  // 1-cycle delay as a FIR filter
+val triangleFilter = FirFilter(8.W, Seq(1.U, 2.U, 3.U, 2.U, 1.U))  // 5-point FIR filter with a triangle impulse response
 ```
 
-## Getting Started
-If you are migrating to Chisel3 from Chisel2, please visit
-[Chisel3 vs Chisel2](https://github.com/ucb-bar/chisel3/wiki/Chisel3-vs-Chisel2)
 
-### Resources for Learning Chisel
-* [Chisel Bootcamp](https://github.com/freechipsproject/chisel-bootcamp), a collection of interactive Jupyter notebooks that teach Chisel
-* [Chisel Tutorial](https://github.com/ucb-bar/chisel-tutorial), a collection of exercises utlizing `sbt`
+## Getting Started
 
-### Data Types Overview
-These are the base data types for defining circuit wires (abstract types which
-may not be instantiated are greyed out):
+### Bootcamp Interactive Tutorial
+The [**online Chisel Bootcamp**](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master) is the recommended way to get started with and learn Chisel.
+**No setup is required** (it runs in the browser), nor does it assume any prior knowledge of Scala.   
 
-![Image](doc/images/type_hierarchy.png?raw=true)
+### Build Your Own Chisel Projects
 
-## For Hardware Engineers
-This section describes how to get started using Chisel to create a new RTL
-design from scratch.
+See [the setup instructions](SETUP.md) for how to set up your environment to run Chisel locally.
 
-### [Project Setup](https://github.com/ucb-bar/chisel-template)
+When you're ready to build your own circuits in Chisel, **we recommend starting from the [Chisel Template](https://github.com/freechipsproject/chisel-template) repository**, which provides a pre-configured project, example design, and testbench. Follow the [chisel-template readme](https://github.com/freechipsproject/chisel-template) to get started.
 
+If you insist on setting up your own project, the magic SBT lines are:
+```scala
+resolvers ++= Seq(
+  Resolver.sonatypeRepo("snapshots"),
+  Resolver.sonatypeRepo("releases")
+)
+libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
+libraryDependencies += "edu.berkeley.cs" %% "chisel-testers2" % "0.1-SNAPSHOT"
+``` 
 
-### RTL
-*TODO: toy example*
+### Design Verification
 
-### Verification
-*The simulation unit testing infrastructure is still a work in progress.*
+These simulation-based verification tools are available for Chisel:
+- [**iotesters**](https://github.com/freechipsproject/chisel-testers), specifically [PeekPokeTester](https://github.com/freechipsproject/chisel-testers/wiki/Using%20the%20PeekPokeTester), provides constructs (`peek`, `poke`, `expect`) similar to a non-synthesizable Verilog testbench.
+- [**testers2**](https://github.com/ucb-bar/chisel-testers2) is an in-development replacement for PeekPokeTester, providing the same base constructs but with a streamlined interface and concurrency support with `fork` and `join`.
 
-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.
 
-Unit tests are written with the ScalaTest unit testing framework, optionally
-with ScalaCheck generators to sweep the parameter space where desired.
+## Documentation
 
-`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.
+### Useful Resources
+ 
+- [**Cheat Sheet**](https://chisel.eecs.berkeley.edu/doc/chisel-cheatsheet3.pdf), a 2-page reference of the base Chisel syntax and libraries
+- [**Wiki**](https://github.com/freechipsproject/chisel3/wiki), which contains various feature-specific tutorials and frequently-asked questions.
+- [**ScalaDoc**](https://chisel.eecs.berkeley.edu/api/latest/chisel3/index.html), a listing, description, and examples of the functionality exposed by Chisel   
+- [**Gitter**](https://gitter.im/freechipsproject/chisel3), where you can ask questions or discuss anything Chisel
+- [**Website**](https://chisel.eecs.berkeley.edu)
 
-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.
+If you are migrating from Chisel2, see [the migration guide on the wiki](https://github.com/ucb-bar/chisel3/wiki/Chisel3-vs-Chisel2).
 
-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`.
+### Data Types Overview
+These are the base data types for defining circuit wires (abstract types which may not be instantiated are greyed out):
 
-*A more Chisel2-like tester may come in the future.*
+![Image](doc/images/type_hierarchy.png?raw=true)
 
-### Compiling to Simulation
-*TODO: commands to compile project to simulation*
+## Developer Documentation
+This section describes how to get started developing Chisel itself, including how to test your version locally against other projects that pull in Chisel using [sbt's managed dependencies](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html).
 
-*TODO: running testbenches*
+### Compiling and Testing Chisel
 
-## For Chisel Developers
-This section describes how to get started developing Chisel itself, including
-how to test your version locally against other projects that pull in Chisel
-using [sbt's managed dependencies](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html).
+In the chisel3 repository directory compile the Chisel library:
 
-### Compiling and Testing Chisel
-In the Chisel repository directory, run:
 ```
 sbt compile
 ```
-to compile the Chisel library. If the compilation succeeded, you can then run
-the included unit tests by invoking:
+
+If the compilation succeeded, you can then run the included unit tests by invoking:
+
 ```
 sbt test
 ```
 
 ### Running Projects Against Local Chisel
+
 To use the development version of Chisel (`master` branch), you will need to build from source and `publishLocal`.
-The repo version can be found in the build.sbt file.
+The repository version can be found in the build.sbt file.
 As of the time of writing it was:
 
-    version := "3.2-SNAPSHOT",
+```
+version := "3.2-SNAPSHOT"
+```
+
+To publish your version of Chisel to the local Ivy (sbt's dependency manager) repository, run:
 
-To publish your version of Chisel to the local Ivy (sbt's dependency manager)
-repository, run:
 ```
 sbt publishLocal
 ```
 
-*PROTIP*: sbt can automatically run commands on a source change if you prefix
-the command with `~`. For example, the above command to publish Chisel locally
-becomes `sbt ~publishLocal`.
+The compiled version gets placed in `~/.ivy2/local/edu.berkeley.cs/`.
+If you need to un-publish your local copy of Chisel, remove the directory generated in `~/.ivy2/local/edu.berkeley.cs/`.
 
-[sbt's manual](https://www.scala-sbt.org/1.x/docs/Publishing.html#Publishing+Locally)
-recommends that you use a `SNAPSHOT` version suffix to ensure that the local
-repository is checked for updates. Since the current default is a `SNAPSHOT`,
-and the version number is already incremented compared to the currently
-published snapshot, you dont need to change version.
+In order to have your projects use this version of Chisel, you should update the `libraryDependencies` setting in your project's build.sbt file to:
 
-The compiled version gets placed in `~/.ivy2/local/`. You can nuke the relevant
-subfolder to un-publish your local copy of Chisel.
-
-In order to have your projects use this version of Chisel, you should update
-the libraryDependencies setting in your project's build.sbt file to:
 ```
 libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
 ```
 
-The version specifier in libraryDependencies in the project's build.sbt should
-match the version string in your local copy of Chisel's build.sbt.
-
-## Technical Documentation
-
 ### Chisel3 Architecture Overview
 
 The Chisel3 compiler consists of these main parts:
@@ -234,7 +175,7 @@ Also included is:
 - **The standard library** of circuit generators, `chisel3.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).
+  circuit generators (like arbiters and multiplexors).
 - **Driver utilities**, `chisel3.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.