Merge pull request #400 from riscv-boom/cleanup-docs

[docs] MICRO 2019 Documentation Cleanup

docs/index.rst

@@ -1,12 +1,66 @@
 Welcome to RISCV-BOOM's documentation!
 ======================================
 
+The Berkeley Out-of-Order Machine (BOOM) is a synthesizable and parameterizable open-source `RISC-V <riscv.org>`__ out-of-order core written in the `Chisel <chisel-lang.org>`__ hardware construction language.
+The goal of this document is to describe the design and implementation of the core as well as provide other helpful information to use the core.
+
+Useful Links
+------------
+
+The BOOM source code can be found here: https://github.com/riscv-boom/riscv-boom.
+
+The main supported mechanism to use the core is to use the Chipyard framework: https://github.com/ucb-bar/chipyard.
+
+The BOOM website can be found here: https://boom-core.org.
+
+The BOOM mailing list can be found here: https://groups.google.com/forum/#!forum/riscv-boom.
+
+Quick-start
+-----------
+
+The best way to get started with the BOOM core is to use the `Chipyard project template <https://github.com/ucb-bar/chipyard>`__.
+There you will find the main steps to setup your environment, build, and run the BOOM core on a C++ emulator.
+Chipyard also provides supported flows for pushing a BOOM-based SoC through both the FireSim FPGA simulation flow and the HAMMER ASIC flow.
+Here is a selected set of steps from `Chipyard's documentation <https://chipyard.readthedocs.io/en/latest/>`__:
+
+.. _quick-start-code:
+.. code-block:: bash
+    :caption: Quick-Start Code
+
+    # Download the template and setup environment
+    git clone https://github.com/ucb-bar/chipyard.git
+    cd chipyard
+    ./scripts/init-submodules-no-riscv-tools.sh
+
+    # build the toolchain
+    ./scripts/build-toolchains.sh riscv-tools
+
+    # add RISCV to env, update PATH and LD_LIBRARY_PATH env vars
+    # note: env.sh generated by build-toolchains.sh
+    source env.sh
+
+    cd sims/verilator
+    make CONFIG=LargeBoomConfig
+
+.. Note:: :numref:`quick-start-code` assumes you don't have riscv-tools toolchain installed. It will pull and build the toolchain for you.
+
+Table of Contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction:
+
+   sections/intro-overview/boom
+   sections/intro-overview/boom-pipeline
+   sections/intro-overview/chisel
+   sections/intro-overview/riscv-isa
+   sections/intro-overview/rocket-chip
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-   :numbered:
+   :caption: Core Overview:
 
-   sections/intro-overview/index
    sections/instruction-fetch-stage
    sections/branch-prediction/index
    sections/decode-stage
@@ -17,17 +71,25 @@ Welcome to RISCV-BOOM's documentation!
    sections/execution-stages
    sections/load-store-unit
    sections/memory-system
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Usage:
+
+   sections/parameterization
+   sections/boom-ecosystem
+   sections/debugging
    sections/uarch-counters
    sections/verification
-   sections/debugging
    sections/physical-realization
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Other:
+
    sections/future-work
-   sections/parameterization
    sections/faq
-   sections/boom-ecosystem
    sections/terminology
-   sections/bibliography/bibliography
-
 
 Indices and tables
 ==================

docs/sections/boom-ecosystem.rst

@@ -1,14 +1,34 @@
-The BOOM Ecosystem
-==================
+The BOOM Development Ecosystem
+==============================
+
+The BOOM Repository
+------------------------------------
+
+The BOOM repository holds the source code to the BOOM core; it is not a full processor and thus is **NOT A SELF-RUNNING** repository.
+To instantiate a BOOM core, you must use a top-level project to integrate the core into an SoC. For this purpose you can use
+the `Chipyard Template <https://github.com/ucb-bar/chipyard>`__.
+
+The BOOM core source code can be found in ``src/main/scala``.
+
+The core code structure is shown below:
+
+* ``src/main/scala/``
+
+  * ``bpu/`` - branch predictor unit
+  * ``common/`` - configs mixins, constants, bundles, tile definitions
+  * ``exu/`` - execute/core unit
+  * ``ifu/`` - instruction fetch unit
+  * ``lsu/`` - load/store/memory unit
+  * ``util/`` - utilities
 
 Scala, Chisel, Generators, Configs, Oh My!
 ------------------------------------------
 
 Working with BOOM has a large learning curve for those people new to *Chisel* and the BOOM ecosystem.
-To be productive, it takes time to learn about the micro-architecture, *Rocket-chip* components, *Chisel* (maybe *Firrtl*), *Scala*, and the build system.
-Luckily, the micro-architecture is detailed in this documentation and some of the other topics (*Chisel*, *Firrtl*, *Scala*) are discussed in their respective websites. [1]_
+To be productive, it takes time to learn about the micro-architecture, *Rocket chip* components, *Chisel* (maybe *Firrtl*), *Scala*, and the build system.
+Luckily, the micro-architecture is detailed in this documentation and some of the other topics (*Chisel*, *Firrtl*, *Scala*) are discussed in their respective websites.
 Instead of focusing solely on those topics, this section hopes to show how they all fit together by giving a high level of the entire build process.
-Put in more specific terms: How do you get from *Scala*/*Chisel* to Verilog? [2]_
+Put in more specific terms: How do you get from *Scala*/*Chisel* to Verilog? [1]_
 
 Recap on Coding in Scala/Chisel
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,7 +63,7 @@ The word "generator" used in many *Chisel* projects refers to a program that tak
 The generator for BOOM and Rocket SoC's can be found in Chipyard under the ``Generator.scala`` file.
 The *Chisel Module* used in the generator is normally the top-level *Chisel Module* class that you (the developer) want to make a circuit of.
 The *Configuration* is just a set of *Scala* variables used to configure the parameters of the passed in *Chisel Module*.
-In BOOM's case, the top-level *Module* would be something like the BoomRocketSystem found in ``src/main/scala/system/BoomRocketSystem.scala`` and a *Configuration* like MediumBoomConfig found in ``src/main/scala/common/configs.scala``. [3]_
+In BOOM's case, the top-level *Module* would be something like the BoomRocketSystem found in ``src/main/scala/system/BoomRocketSystem.scala`` and a *Configuration* like MediumBoomConfig found in ``src/main/scala/common/configs.scala``. [2]_
 In this case, the parameters specified in MediumBoomConfig would set the necessary *Scala* variables needed throughout the ExampleBoomSystem *Module*.
 Once the *Module* and *Configuration* is passed into the generator, they will be combined to form a piece of RTL representing the circuit given by the *Module* parameterized by the *Configuration*.
 
@@ -84,8 +104,13 @@ Now that the flow of ecosystem has been briefly explained here is a quick recap.
 7. Deal with runtime errors (*Firrtl* compile errors, which occur from compiler passes that perform checks e.g. for uninitialized wires)
 8. Done. A Verilog file was created!!!
 
-.. [1] Unfortunately, one of the big components of the BOOM system, Rocket-Chip, lacks alot of meaningful documentation. This is a known issue that the Rocket-Chip maintainers hope to fix one day.
+More Resources
+--------------
+
+If you would like more detail on top-level integration, how accelerators work in the Rocket Chip system, and much more please visit the
+`Chipyard Documentation <https://chipyard.readthedocs.io/en/latest/>`__.
+
 
-.. [2] This section describes the current build process that is used in `Chipyard <https://github.com/ucb-bar/chipyard>`__.
+.. [1] This section describes the current build process that is used in `Chipyard <https://github.com/ucb-bar/chipyard>`__.
 
-.. [3] This is not exactly true since to be able to run BOOM in simulations we wrap the BoomRocketSystem in a TestHarness found in Chipyard.
+.. [2] This is not exactly true since to be able to run BOOM in simulations we wrap the BoomRocketSystem in a TestHarness found in Chipyard.