Merge remote-tracking branch 'origin/dev' into filter-c-files

.circleci/build-verilator.sh

@@ -23,7 +23,7 @@ if [ ! -d "$LOCAL_VERILATOR_DIR" ]; then
     run "mkdir -p $REMOTE_CHIPYARD_DIR"
     copy $LOCAL_CHIPYARD_DIR/ $SERVER:$REMOTE_CHIPYARD_DIR
 
-    run "make -C $REMOTE_CHIPYARD_DIR/sims/verisim VERILATOR_INSTALL_DIR=$REMOTE_VERILATOR_DIR verilator_install"
+    run "make -C $REMOTE_SIM_DIR VERILATOR_INSTALL_DIR=$REMOTE_VERILATOR_DIR verilator_install"
 
     # copy so that circleci can cache
     mkdir -p $LOCAL_CHIPYARD_DIR

.circleci/check-commit.sh

@@ -26,7 +26,7 @@ search () {
     done
 }
 
-submodules=("boom" "firechip" "hwacha" "icenet" "rocket-chip" "sifive-blocks" "sifive-cache" "testchipip")
+submodules=("boom" "hwacha" "icenet" "rocket-chip" "sifive-blocks" "sifive-cache" "testchipip")
 dir="generators"
 
 search

.circleci/config.yml

@@ -78,14 +78,14 @@ jobs:
             - checkout
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Build Verilator
                 command: |
                     .circleci/build-verilator.sh
                 no_output_timeout: 120m
             - save_cache:
-                key: verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                key: verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
                 paths:
                     - "/home/riscvuser/verilator"
     prepare-example:
@@ -108,7 +108,7 @@ jobs:
                     - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the example subproject using Verilator
                 command: .circleci/do-rtl-build.sh example
@@ -137,7 +137,7 @@ jobs:
                     - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the boomexample subproject using Verilator
                 command: .circleci/do-rtl-build.sh boomexample
@@ -166,7 +166,7 @@ jobs:
                     - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the boomrocketexample subproject using Verilator
                 command: .circleci/do-rtl-build.sh boomrocketexample
@@ -195,7 +195,7 @@ jobs:
                     - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the boom subproject using Verilator
                 command: .circleci/do-rtl-build.sh boom
@@ -224,7 +224,7 @@ jobs:
                     - riscv-tools-installed-v1-{{ checksum "../riscv-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the rocketchip subproject using Verilator
                 command: .circleci/do-rtl-build.sh rocketchip
@@ -282,7 +282,7 @@ jobs:
                     - esp-tools-installed-v1-{{ checksum "../esp-tools.hash" }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Building the hwacha subproject using Verilator
                 command: .circleci/do-rtl-build.sh hwacha
@@ -311,7 +311,7 @@ jobs:
                     - example-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run example tests
                 command: .circleci/run-tests.sh example
@@ -335,7 +335,7 @@ jobs:
                     - boomexample-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run boomexample tests
                 command: .circleci/run-tests.sh boomexample
@@ -359,7 +359,7 @@ jobs:
                     - boomrocketexample-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run boomrocketexample tests
                 command: .circleci/run-tests.sh boomrocketexample
@@ -383,7 +383,7 @@ jobs:
                     - boom-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run boom tests
                 command: .circleci/run-tests.sh boom
@@ -407,7 +407,7 @@ jobs:
                     - rocketchip-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run rocketchip tests
                 command: .circleci/run-tests.sh rocketchip
@@ -431,7 +431,7 @@ jobs:
                     - hwacha-{{ .Branch }}-{{ .Revision }}
             - restore_cache:
                 keys:
-                    - verilator-installed-v3-{{ checksum "sims/verisim/verilator.mk" }}
+                    - verilator-installed-v3-{{ checksum "sims/verilator/verilator.mk" }}
             - run:
                 name: Run hwacha tests
                 command: .circleci/run-tests.sh hwacha

.circleci/defaults.sh

@@ -23,7 +23,7 @@ REMOTE_RISCV_DIR=$REMOTE_WORK_DIR/riscv-tools-install
 REMOTE_ESP_DIR=$REMOTE_WORK_DIR/esp-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
@@ -31,7 +31,7 @@ LOCAL_RISCV_DIR=$HOME/riscv-tools-install
 LOCAL_ESP_DIR=$HOME/esp-tools-install
 LOCAL_CHIPYARD_DIR=$LOCAL_CHECKOUT_DIR
 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

README.md

@@ -1,8 +1,8 @@
-# Chipyard Framework [![CircleCI](https://circleci.com/gh/ucb-bar/project-template/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/chipyard/tree/master)
+# Chipyard Framework [![CircleCI](https://circleci.com/gh/ucb-bar/chipyard/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/chipyard/tree/master)
 
 ## Using Chipyard
 
-To get started using Chipyard, see the documentation on the Chipyard documentation site: https://bar-project-template.readthedocs.io/en/latest/
+To get started using Chipyard, see the documentation on the Chipyard documentation site: https://chipyard.readthedocs.io/en/latest/
 
 ## What is Chipyard
 
@@ -14,7 +14,7 @@ Chipyard is actively developed in the [Berkeley Architecture Research Group][ucb
 ## Resources
 
 * Chipyard Website: ...TBD at a later date...
-* Chipyard Documentation: https://bar-project-template.readthedocs.io/
+* Chipyard Documentation: https://chipyard.readthedocs.io/
 
 [hwacha]:http://hwacha.org
 [hammer]:https://github.com/ucb-bar/hammer

common.mk

@@ -80,8 +80,9 @@ $(sim_files): $(sim_top_blackboxes) $(sim_harness_blackboxes) $(sim_dotf)
 verilog: $(sim_vsrcs)
 
 #########################################################################################
-# helper rules to run simulator
+# helper rules to run simulations
 #########################################################################################
+.PHONY: run-binary run-fast
 run-binary: $(sim)
 	(set -o pipefail && $(sim) $(PERMISSIVE_ON) +max-cycles=$(timeout_cycles) $(SIM_FLAGS) $(VERBOSE_FLAGS) $(PERMISSIVE_OFF) $(BINARY) 3>&1 1>&2 2>&3 | spike-dasm > $(sim_out_name).out)
 
@@ -97,6 +98,8 @@ run-binary-fast: $(sim)
 run-binary-debug: $(sim_debug)
 	(set -o pipefail && $(sim_debug) $(PERMISSIVE_ON) +max-cycles=$(timeout_cycles) $(SIM_FLAGS) $(VERBOSE_FLAG) $(WAVEFORM_FLAG) $(PERMISSIVE_OFF) $(BINARY) 3>&1 1>&2 2>&3 | spike-dasm > $(sim_out_name).out)
 
+run-fast: run-asm-tests-fast run-bmark-tests-fast
+
 #########################################################################################
 # run assembly/benchmarks rules
 #########################################################################################

docs/Simulation/FPGA-Accelerated-Simulators.rst

@@ -0,0 +1,57 @@
+FPGA-Accelerated Simulators
+==============================
+
+FireSim
+-----------------------
+
+`FireSim <https://fires.im/>`__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1).
+FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators.
+FireSim also provides additional device models to allow full-system simulation, including memory models and network models.
+
+FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances.
+In order to simulate your Chipyard design using FireSim, if you have not
+already, follow the initial EC2 setup instructions as detailed in the `FireSim
+documentation  <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__.
+Then clone Chipyard onto your FireSim manager
+instance, and setup your Chipyard repository as you would normally.
+
+Next, initalize FireSim as library in Chipyard by running:
+
+.. code-block:: shell
+
+    # At the root of your chipyard repo
+    ./scripts/firesim-setup.sh --fast
+
+``firesim-setup.sh`` initializes additional submodules and then invokes
+firesim's ``build-setup.sh`` script adding ``--library`` to properly
+initialize FireSim as a library submodule in chipyard. You may run
+``./sims/firesim/build-setup.sh --help`` to see more options.
+
+Finally, source the following environment at the root of the firesim directory:
+
+.. code-block:: shell
+
+    cd sims/firesim
+    # (Recommended) The default manager environment (includes env.sh)
+    source sourceme-f1-manager.sh
+
+`Every time you want to use FireSim with a fresh shell, you must source this sourceme.sh`
+
+At this point you're ready to use FireSim with Chipyard. If you're not already
+familiar with FireSim, please return to the `FireSim Docs
+<https://docs.fires.im/en/latest/Initial-Setup/Setting-up-your-Manager-Instance.html#completing-setup-using-the-manager>`__,
+and proceed with the rest of the tutorial.
+
+Current Limitations:
+++++++++++++++++++++
+
+FireSim integration in Chipyard is still a work in progress. Presently, you
+cannot build a FireSim simulator from any generator project in Chipyard except ``firechip``, 
+which properly invokes MIDAS on the target RTL.
+
+In the interim, workaround this limitation by importing Config and Module
+classes from other generator projects into FireChip. You should then be able to
+refer to those classes or an alias of them in  your ``DESIGN`` or ``TARGET_CONFIG``
+variables. Note that if your target machine has I/O not provided in the default
+FireChip targets (see ``generators/firechip/src/main/scala/Targets.scala``) you may need
+to write a custom endpoint.

docs/Simulation/FPGA-Based-Simulators.rst

@@ -1,17 +0,0 @@
-FPGA-Based Simulators
-==============================
-
-FireSim
------------------------
-
-`FireSim <https://fires.im/>`__ is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1).
-FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators.
-FireSim also provides additional device models to allow full-system simulation, including memory models and network models.
-
-FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances on the public cloud.
-In order to simulate your Chipyard design using FireSim, you should follow the following steps:
-
-Follow the initial EC2 setup instructions as detailed in the `FireSim documentation  <http://docs.fires.im/en/latest/Initial-Setup/index.html>`__.
-Then clone your full Chipyard repository onto your Amazon EC2 FireSim manager instance.
-
-Enter the ``sims/FireSim`` directory, and follow the FireSim instructions for `running a simulation <http://docs.fires.im/en/latest/Running-Simulations-Tutorial/index.html>`__.

docs/Simulation/Open-Source-Simulators.rst

@@ -1,35 +0,0 @@
-Open Source Software RTL Simulators
-==============================
-
-Verilator
------------------------
-
-`Verilator <https://www.veripool.org/wiki/verilator>`__ is an open-source LGPL-Licensed simulator maintained by `Veripool <https://www.veripool.org/>`__.
-The Chipyard framework can download, build, and execute simulations using Verilator.
-
-To run a simulation using Verilator, perform the following steps:
-
-To compile the example design, run ``make`` in the ``sims/verisim`` directory.
-This will elaborate the ``DefaultRocketConfig`` in the example project.
-
-An executable called ``simulator-example-DefaultRocketConfig`` will be produced.
-This executable is a simulator that has been compiled based on the design that was built.
-You can then use this executable to run any compatible RV64 code.
-For instance, to run one of the riscv-tools assembly tests.
-
-.. code-block:: shell
-
-    ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
-
-If you later create your own project, you can use environment variables to build an alternate configuration.
-
-.. code-block:: shell
-
-    make SUB_PROJECT=yourproject
-    ./simulator-<yourproject>-<yourconfig> ...
-
-If you would like to extract waveforms from the simulation, run the command ``make debug`` instead of just ``make``.
-This will generate a vcd file (vcd is a standard waveform representation file format) that can be loaded to any common waveform viewer.
-An open-source vcd-capable waveform viewer is `GTKWave <http://gtkwave.sourceforge.net/>`__.
-
-Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running.

docs/Simulation/Software-RTL-Simulators.rst

@@ -1,9 +1,43 @@
-Commercial Software RTL Simulators
+Software RTL Simulators
-==============================
+===================================
 
-VCS
+Verilator (Open-Source)
 -----------------------
 
+`Verilator <https://www.veripool.org/wiki/verilator>`__ is an open-source LGPL-Licensed simulator maintained by `Veripool <https://www.veripool.org/>`__.
+The Chipyard framework can download, build, and execute simulations using Verilator.
+
+To run a simulation using Verilator, perform the following steps:
+
+To compile the example design, run ``make`` in the ``sims/verisim`` directory.
+This will elaborate the ``DefaultRocketConfig`` in the example project.
+
+An executable called ``simulator-example-DefaultRocketConfig`` will be produced.
+This executable is a simulator that has been compiled based on the design that was built.
+You can then use this executable to run any compatible RV64 code.
+For instance, to run one of the riscv-tools assembly tests.
+
+.. code-block:: shell
+
+    ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
+
+If you later create your own project, you can use environment variables to build an alternate configuration.
+
+.. code-block:: shell
+
+    make SUB_PROJECT=yourproject
+    ./simulator-<yourproject>-<yourconfig> ...
+
+If you would like to extract waveforms from the simulation, run the command ``make debug`` instead of just ``make``.
+This will generate a vcd file (vcd is a standard waveform representation file format) that can be loaded to any common waveform viewer.
+An open-source vcd-capable waveform viewer is `GTKWave <http://gtkwave.sourceforge.net/>`__.
+
+Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running.
+Commercial Software RTL Simulators
+
+Synopsys VCS (License Required)
+--------------------------------
+
 `VCS <https://www.synopsys.com/verification/simulation/vcs.html>`__ is a commercial RTL simulator developed by Synopsys.
 It requires commercial licenses.
 The Chipyard framework can compile and execute simulations using VCS.

docs/Simulation/index.rst

@@ -1,15 +1,20 @@
 Simulators
 =======================
 
-Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements.
+Chipyard supports two classes of simulation:
-In the majority of cases during a digital design development process, a simple software RTL simulation will do.
+
-When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution.
+#. Software RTL simulation using commercial or open-source (Verilator) RTL simulators 
-The following pages provide detailed information about the simulation possibilities within the Chipyard framework.
+#. FPGA-accelerated full-system simulation using FireSim
+
+Software RTL simulators of Chipyard designs run at O(1 KHz), but compile
+quickly and provide full waveforms. Conversly, FPGA-accelerated simulators run
+at O(100 MHz), making them appropriate for booting an operating system and
+running a complete workload, but have multi-hour compile times and poorer debug
+visability.
 
 .. toctree::
    :maxdepth: 2
    :caption: Simulators:
 
-   Open-Source-Simulators
+   Software-RTL-Simulators
-   Commercial-Simulators
+   FPGA-Accelerated-Simulators
-   FPGA-Based-Simulators

docs/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to Chipyard's documentation!
-=================================
+====================================
 
 Chipyard is a a framework for designing and evaluating full-system hardware using agile teams.
 It is composed of a collection of tools and libraries designed to provide an intergration between open-source and commercial tools for the development of systems-on-chip.

sims/vcs/Makefile

@@ -56,6 +56,7 @@ VCS_NONCC_OPTS = \
 	-error=PCWM-L \
 	-timescale=1ns/10ps \
 	-quiet \
+	-q \
 	+rad \
 	+v2k \
 	+vcs+lic+wait \