Merge pull request #355 from riscv-boom/migrate-to-chipyard

[general] Migrate BOOM Integration to Chipyard

.circleci/build-riscv-tools.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# create the riscv tools binaries from riscv-boom/boom-template with rocket-chip hash given by riscv-boom
+# create the riscv tools binaries from ucb-bar/chipyard with rocket-chip hash given by riscv-boom
 
 # turn echo on and error on earliest command
 set -ex

.circleci/build-run-csmith-tests.sh

@@ -9,7 +9,7 @@ set -ex
 SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
 source $SCRIPT_DIR/defaults.sh
 
-SIM_BASE=simulator-boom.system-
+SIM_BASE=simulator-example-
 CONFIG=$(echo ${mapping[$1]} | sed -n -e 's/^.*CONFIG=\([a-zA-Z0-9]*\).*/\1/p')
 SIM=${SIM_BASE}${CONFIG}
 AMT_RUNS=$2

.circleci/defaults.sh

@@ -22,20 +22,20 @@ REMOTE_WORK_DIR=$CI_DIR/$CIRCLE_PROJECT_REPONAME-$CIRCLE_BRANCH-$CIRCLE_SHA1-$CI
 REMOTE_RISCV_DIR=$REMOTE_WORK_DIR/riscv-tools-install
 REMOTE_CHIPYARD_DIR=$REMOTE_WORK_DIR/chipyard
 REMOTE_VERILATOR_DIR=$REMOTE_WORK_DIR/verilator
-REMOTE_SIM_DIR=$REMOTE_CHIPYARD_DIR/sims/verisim
+REMOTE_SIM_DIR=$REMOTE_CHIPYARD_DIR/sims/verilator
 
 # local variables (aka within the docker container)
 LOCAL_CHECKOUT_DIR=$HOME/project
 LOCAL_RISCV_DIR=$HOME/riscv-tools-install
 LOCAL_CHIPYARD_DIR=$HOME/chipyard
 LOCAL_VERILATOR_DIR=$HOME/verilator
-LOCAL_SIM_DIR=$LOCAL_CHIPYARD_DIR/sims/verisim
+LOCAL_SIM_DIR=$LOCAL_CHIPYARD_DIR/sims/verilator
 
 # key value store to get the build strings
 declare -A mapping
-mapping["smallboom"]="SUB_PROJECT=boom CONFIG=SmallBoomConfig"
-mapping["mediumboom"]="SUB_PROJECT=boom CONFIG=MediumBoomConfig"
-mapping["largeboom"]="SUB_PROJECT=boom CONFIG=LargeBoomConfig"
-mapping["megaboom"]="SUB_PROJECT=boom CONFIG=MegaBoomConfig"
-mapping["boomandrocket"]="SUB_PROJECT=boom CONFIG=SmallBoomAndRocketConfig"
-mapping["rv32unifiedboom"]="SUB_PROJECT=boom CONFIG=SmallRV32UnifiedBoomConfig"
+mapping["smallboom"]="CONFIG=SmallBoomConfig"
+mapping["mediumboom"]="CONFIG=MediumBoomConfig"
+mapping["largeboom"]="CONFIG=LargeBoomConfig"
+mapping["megaboom"]="CONFIG=MegaBoomConfig"
+mapping["boomandrocket"]="CONFIG=SmallBoomAndRocketConfig"
+mapping["rv32unifiedboom"]="CONFIG=SmallRV32UnifiedBoomConfig"

.circleci/do-rtl-build.sh

@@ -26,7 +26,7 @@ copy $LOCAL_RISCV_DIR/ $SERVER:$REMOTE_RISCV_DIR
 copy $LOCAL_CHIPYARD_DIR/ $SERVER:$REMOTE_CHIPYARD_DIR
 copy $LOCAL_VERILATOR_DIR/ $SERVER:$REMOTE_VERILATOR_DIR
 
-# enter the verisim directory and build the specific config on remote server
+# enter the verilator directory and build the specific config on remote server
 run "make -C $REMOTE_SIM_DIR clean"
 run "export RISCV=\"$REMOTE_RISCV_DIR\"; export VERILATOR_ROOT=$REMOTE_VERILATOR_DIR/install/share/verilator; make -C $REMOTE_SIM_DIR VERILATOR_INSTALL_DIR=$REMOTE_VERILATOR_DIR JAVA_ARGS=\"-Xmx8G -Xss8M\" ${mapping[$1]}"
 run "rm -rf $REMOTE_CHIPYARD_DIR/project"

.circleci/prepare-for-rtl-build.sh

@@ -25,10 +25,10 @@ if [ ! -d "$LOCAL_VERILATOR_DIR" ] && [ ! -d "$LOCAL_CHIPYARD_DIR" ]; then
     git fetch
     git checkout $(cat $LOCAL_CHECKOUT_DIR/CHIPYARD.hash)
 
-    # init all submodules (according to what boom-template wants)
+    # init all submodules (according to what chipyard wants)
     ./scripts/init-submodules-no-riscv-tools.sh
 
-    # move the pull request riscv-boom repo into boom-template
+    # move the pull request riscv-boom repo into chipyard
     rm -rf $LOCAL_CHIPYARD_DIR/generators/boom
     cp -r $LOCAL_CHECKOUT_DIR $LOCAL_CHIPYARD_DIR/generators/boom/
 

.github/ISSUE_TEMPLATE.md

@@ -22,7 +22,7 @@
 <!--    (examples)
     - version: `git commit hash`
     - os: `Linux knight 4.4.0-92-generic #115-Ubuntu SMP Thu Aug 10 09:04:33 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux`
-    - build environment: `riscv-boom/boom-template` `git commit hash`
+    - build environment: `ucb-bar/chipyard` `git commit hash`
 -->
 
 **What is the use case for changing the behavior?**

CHIPYARD.hash

@@ -1 +1 @@
-b4dddd21cd4fc0b4c0c4858323f9b431d95d60b8
+89b312a8891a4df855d82d4accdfb0db20613d65

README.md

@@ -1,11 +1,11 @@
 The Berkeley Out-of-Order RISC-V Processor [![CircleCI](https://circleci.com/gh/riscv-boom/riscv-boom.svg?style=svg)](https://circleci.com/gh/riscv-boom/riscv-boom)
-================================================
+====================================================================================================================================================================
 
-The Berkeley Out-of-Order Machine (BOOM) is a synthesizable and parameterizable open source RV64GC RISC-V core written in the 
-[Chisel](https://chisel.eecs.berkeley.edu/) hardware construction language. While BOOM is primarily ASIC optimized, it is also usable on FPGAs. 
+The Berkeley Out-of-Order Machine (BOOM) is a synthesizable and parameterizable open source RV64GC RISC-V core written in the
+[Chisel](https://chisel.eecs.berkeley.edu/) hardware construction language. While BOOM is primarily ASIC optimized, it is also usable on FPGAs.
 We support the FireSim flow to run BOOM at 90+ MHz on FPGAs on Amazon EC2 F1. Created at the University of California,
-Berkeley in the [Berkeley Architecture Research](https://bar.eecs.berkeley.edu/) group, its focus is to create a high 
-performance, synthesizable, and parameterizable core for architecture research. 
+Berkeley in the [Berkeley Architecture Research](https://bar.eecs.berkeley.edu/) group, its focus is to create a high
+performance, synthesizable, and parameterizable core for architecture research.
 
 Feature | BOOM
 --- | ---
@@ -16,158 +16,38 @@ Parameterized |√
 Floating Point (IEEE 754-2008) |√
 Atomic Memory Op Support |√
 Caches |√
-Viritual Memory |√
+Virtual Memory |√
 Boots Linux |√
+Boots Fedora |√
 Privileged Arch v1.11 |√
 External Debug |√
 
-**Google group:** (https://groups.google.com/forum/#!forum/riscv-boom)
+## Documentation and Information
 
-For documentation and publications on BOOM visit the BOOM website (www.boom-core.org/).
+Please check out the BOOM website @ https://boom-core.org for the most up-to-date information.
+It contains links to the mailing lists, documentation, design spec., publications and more!
 
-### Important!
+**Website:** (www.boom-core.org)
 
-This repository is **NOT A SELF-RUNNING** repository. To instantiate a BOOM core, please use the
-boom-template SoC generator found in the git repository (https://github.com/riscv-boom/boom-template).
-
-The current hash of rocket-chip that works with this repository is located in the `ROCKETCHIP_VERSION`
-file in the top level directory of this repository. This file is mainly used for CI purposes, since 
-boom-template should follow the correct version of rocket-chip.
-
-Note: you **MUST** build the riscv-tools as described to build the correct version. A copy of
-riscv-tools you have built yourself previously may be out of date! Likewise, the `master` branch of
-risv-tools may be running ahead and may also not work!
-
-### Requirements
-
-You must set the $RISCV environment variable to where you would like the RISC-V toolchain to be
-installed. You must also add $RISCV/bin to your $PATH.
-
-The instructions below will walk you through installing the RISC-V toolchain. If you run into
-problems, go to the README in [riscv-tools](https://github.com/riscv/riscv-tools) for additional
-information.
-
-### Code Organization
-
-The Chisel source code is found in `src/main/scala`:
-
- * bpu - branch predictor unit
- * exu - execute/core unit
- * ifu - instruction fetch unit
- * lsu - load/store/memory unit
- * common - configs, bundle, and tile definitions
- * system - Non-core system-level infrastructure
- * util - utilities
-
-### Directions
-
-To build a BOOM Verilator emulator and its corresponding RISC-V toolchain, and run BOOM through a
-couple of simple tests:
-
-````
-   $ git clone https://github.com/riscv-boom/boom-template.git
-   $ cd boom-template
-   $ ./scripts/init-submodules.sh
-   $ ./scripts/build-tools.sh 
-   $ cd verisim
-   $ make CONFIG=BoomConfig
-   $ make run CONFIG=BoomConfig
-````
-
-There are many BOOM configurations to choose from (and modify!). In fact, the `CONFIG` variable
-defaults to `BoomConfig`, so it is not necessary to pass a `CONFIG` option.
-
-### Installing the RISC-V Toolchain
-
-First, set the $RISCV environment variable (to where you want the toolchain to be installed). You 
-will also need to add $RISCV/bin to your $PATH.
-
-````
-   $ git clone https://github.com/riscv-boom/boom-template.git
-   $ cd boom-template
-   $ git submodule update --init --recursive
-   $ ./scripts/build-tools.sh
-
-````
-
-That's it.
+**Mailing List** (https://groups.google.com/forum/#!forum/riscv-boom)
 
-For more detailed information on the toolchain, visit 
-[the riscv-tools repository](https://github.com/riscv/riscv-tools).
+## Important!
 
+This repository is **NOT A SELF-RUNNING** repository. To instantiate a BOOM core, please use the
+[Chipyard](https://github.com/ucb-bar/chipyard) SoC generator.
 
-## Using the gem5 O3 Pipeline Viewer with BOOM
-
-The O3 Pipeline Viewer is an out-of-order pipeline viewer included in the
-gem5 suite. BOOM is capable of generating traces compatible with the
-pipeline viewer, which is useful for understanding what causes
-pipeline stalls and flushes.
-
-To generate gem5 compatible traces, first set O3PIPEVIEW_PRINTF in
-`boom/src/main/scala/common/consts.scala` to true:
-
-````
-val O3PIPEVIEW_PRINTF = true  // dump trace for O3PipeView from gem5
-````
-
-Rebuild and rerun BOOM. You should find the traces (*.out) in 
-emulator/output/. To generate the visualization run:
-
-````
-   $ boom/util/pipeview-helper.py -f <TRACE_FILE> > cleaned_trace.out
-   $ path_to_gem5/util/o3-pipeview.py --color --store_completions -o pipeview.out cleaned_trace.out
-````
-
-You can view the visualization by running:
-````
-   $ less -r pipeview.out
-````
-For more details (and to download o3-pipeview.py), visit the [gem5 wiki](http://www.m5sim.org/Visualization).
-
-
-## More Info
-
-Check out the BOOM website @ https://boom-core.org!
-
-* **The Design Spec** - https://docs.boom-core.org
-* **Google group:** - https://groups.google.com/forum/#!forum/riscv-boom
-* **Chisel Learning Journey** - https://github.com/librecores/riscv-sodor/wiki/Chisel-Learning-Journey
-* **Tech Report** - The Berkeley Out-of-Order Machine (BOOM): An Industry-Competitive, Synthesizable, Parameterized RISC-V Processor (https://www.eecs.berkeley.edu/Pubs/TechRpts/2015/EECS-2015-167.html)
-* **CARRV Workshop Report** - BOOM v2: an open-source out-of-order RISC-V core (https://www2.eecs.berkeley.edu/Pubs/TechRpts/2017/EECS-2017-157.html)
-* **Slides** - RISC_V Workshop #3 (https://riscv.org/wp-content/uploads/2016/01/Wed1345-RISCV-Workshop-3-BOOM.pdf)
-* **Video** - RISC-V Workshop #3 (https://www.youtube.com/watch?v=JuJDPbzWpR0)
-* **Slides** - RISC-V Workshop #2 (https://riscv.org/wp-content/uploads/2015/06/riscv-boom-workshop-june2015.pdf)
-* **Video** - RISC-V Workshop #2 (https://www.youtube.com/watch?v=z8UInbiQbdA)
+The current hash of Chipyard that works with this repository is located in the `CHIPYARD.hash`
+file in the top level directory of this repository. This file is mainly used for CI purposes, since
+Chipyard should follow the correct version of rocket-chip. For most users, you should be able to
+clone Chipyard separately and follow the default Chipyard instructions (without having to use the `.hash` file).
 
-### Disclaimer!
+## Disclaimer!
 
-The RISC-V privileged ISA, platform, and Debug specs are still in flux. BOOM will do its best to
+The RISC-V Privileged ISA, Platform, and Debug specs are still in flux. BOOM will do its best to
 stay up-to-date with it!
 
 BOOM is a work-in-progress and remains in active development.
 
-## FAQ
-
-*Help! BOOM isn't working.*
-
-First verify the software is not an issue. Run spike first:
-
-````
-# Verify it works on spike.
-spike my_program
-
-# Then we can run on BOOM.
-./emulator-freechips.rocketchip.system-SmallBoomConfig my_program 
-````
-
-Also verify the riscv-tools you built is the one pointed to within 
-the boom-template/rocket-chip/riscv-tools repository. Otherwise a version mismatch can easily occur!
-
-*Master branch is broken! How do I get a working BOOM?*
+## Contributing
 
-The [boom-template](https://github.com/riscv-boom/boom-template) super-repo should
-always be pointing to a working boom/rocket-chip/riscv-tools combination. The
-`master` branch of riscv-boom may run ahead though. Ideally, `master` should never be
-broken, but it may be somewhat unstable as development continues. For more
-stability, I recommend using one of the tagged
-[releases](https://github.com/riscv-boom/riscv-boom/releases).
+Please see [CONTRIB\_AND\_STYLE.md](/CONTRIB_AND_STYLE.md)

docs/sections/boom-ecosystem.rst

@@ -40,10 +40,10 @@ Generating a BOOM System
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The word "generator" used in many *Chisel* projects refers to a program that takes in a *Chisel Module* and a *Configuration* and returns a circuit based on those parameters.
-The generator for BOOM can be found in ``src/main/scala/system/Generator.scala``.
+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 ExampleBoomSystem found in ``src/main/scala/system/ExampleBoomSystem.scala`` and a *Configuration* like MediumBoomConfig found in ``src/main/scala/system/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``. [3]_
 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*.
 
@@ -86,6 +86,6 @@ Now that the flow of ecosystem has been briefly explained here is a quick recap.
 
 .. [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.
 
-.. [2] This section describes the current build process that is used in `boom-template <https://github.com/riscv-boom/boom-template>`__.
+.. [2] 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 ExampleBoomSystem in a TestHarness found in ``src/main/scala/system/TestHarness.scala``.
+.. [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.

docs/sections/debugging.rst

@@ -72,7 +72,7 @@ To enable pipeline visualization, first set :code:`O3PIPEVIEW_PRINTF` in
     val O3PIPEVIEW_PRINTF = true // dump trace for O3PipeView from gem5
 
 Rebuild and rerun BOOM. You should find the traces (:code:`*.out`) in
-the :code:`verisim/output/` or :code:`vsim/output/` directories if you are using :code:`boom-template` to
+the :code:`verilator/output/` or :code:`vcs/output/` directories if you are using :code:`chipyard` to
 run the core. To generate the visualization, first download and install gem5, and then run:
 
 .. code-block:: bash

docs/sections/faq.rst

@@ -3,3 +3,28 @@ Frequently Asked Questions
 
 For questions regarding the BOOM core, please refer to our GitHub page issues section
 located at https://github.com/riscv-boom/riscv-boom/issues.
+
+Help! BOOM isn't working
+------------------------
+
+First verify the software is not an issue. Run spike first:
+
+.. _verify-spike-first:
+.. code-block:: bash
+    # Verify it works on spike.
+    spike my_program
+
+    # Then we can run on BOOM.
+    ./simulator-...-LargeBoomConfig my_program
+
+Also verify the riscv-tools you built is the one pointed to by Chipyard.
+Otherwise a version mismatch can easily occur!
+
+Master branch is broken! How do I get a working BOOM?
+-------------------------------------------------------
+
+The `Chipyard <https://github.com/ucb-bar/chipyard>`__ SoC super-repo should
+always be pointing to a working BOOM/rocket-chip/riscv-tools combination. The
+`master` branch of riscv-boom may run ahead though. Ideally, `master` should never be
+broken, but it may be somewhat unstable as development continues. For more
+stability, please use one of the tagged `releases <https://github.com/riscv-boom/riscv-boom/releases>`__.