From c6376e7b4669b313bbdaa936f8f9273f684bfa1a Mon Sep 17 00:00:00 2001 From: Chick Markley Date: Wed, 19 Jun 2019 10:07:58 -0700 Subject: 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 * Don't use chisel-lang.org, drop HCL Signed-off-by: Schuyler Eldridge * Fix link to fir image, make it relative * Proposed readme changes * Resize picture, restyle doc bullets --- README.md | 257 ++++++++++++++++++++++++-------------------------------------- 1 file changed, 99 insertions(+), 158 deletions(-) (limited to 'README.md') 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 + -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. -- cgit v1.2.3