Merge remote-tracking branch 'origin/dev' into HEAD

docs/Advanced-Concepts/Debugging-BOOM.rst

@@ -0,0 +1,30 @@
+Debugging BOOM
+======================
+
+In addition to the default debugging techniques specified in :ref:`Debugging RTL`,
+single-core BOOM designs can utilize the Dromajo co-simulator (see :ref:`Dromajo`)
+to verify functionality.
+
+.. warning:: Dromajo currently only works in single-core BOOM systems without accelerators.
+
+.. warning:: Dromajo currently only works in VCS simulation and FireSim.
+
+Setting up Dromajo Co-simulation
+--------------------------------------
+
+Dromajo co-simulation is setup to work when two config fragments are added to a BOOM config.
+First, a ``chipyard.config.WithTraceIO`` config fragment must be added so that BOOM's traceport is enabled.
+Second, a ``chipyard.iobinders.WithSimDromajoBridge`` config fragment must be added to
+connect the Dromajo co-simulator to the traceport.
+Once both config fragments are added Dromajo should be enabled.
+
+To build/run Dromajo with a BOOM design, run your configuration the following make commands:
+
+.. code-block:: shell
+
+    # build the default Dromajo BOOM config without waveform dumps
+    # replace "DromajoBoomConfig" with your particular config
+    make CONFIG=DromajoBoomConfig ENABLE_DROMAJO=1
+
+    # run a simulation with Dromajo
+    make CONFIG=DromajoBoomConfig ENABLE_DROMAJO=1 BINARY=<YOUR-BIN> run-binary

docs/Advanced-Concepts/Debugging-RTL.rst

@@ -88,7 +88,7 @@ directory.
 
 Firesim Debugging
 ---------------------------
-Chisel printfs, asserts, and waveform generation are also available in FireSim
+Chisel printfs, asserts, Dromajo co-simulation, and waveform generation are also available in FireSim
 FPGA-accelerated simulation. See the FireSim
 `documentation <https://docs.fires.im/en/latest/>`__ for more detail.
 

docs/Advanced-Concepts/index.rst

@@ -11,6 +11,7 @@ They expect you to know about Chisel, Parameters, configs, etc.
    Top-Testharness
    Chip-Communication
    Debugging-RTL
+   Debugging-BOOM
    Resources
    CDEs
 

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -79,6 +79,10 @@ Tools
 **Dsptools**
   A Chisel library for writing custom signal processing hardware, as well as integrating custom signal processing hardware into an SoC (especially a Rocket-based SoC).
 
+**Dromajo**
+  A RV64GC emulator primarily used for co-simulation and was originally developed by Esperanto Technologies.
+  See :ref:`Dromajo` for more information.
+
 Toolchains
 -------------------------------------------
 

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -23,10 +23,10 @@ In Ubuntu/Debian-based platforms (Ubuntu), we recommend installing the following
 
 .. Note:: When running on an Amazon Web Services EC2 FPGA-development instance (for FireSim), FireSim includes a machine setup script that will install all of the aforementioned dependencies (and some additional ones).
 
-Checking out the sources
-------------------------
+Setting up the Chipyard Repo
+-------------------------------------------
 
-After cloning this repo, you will need to initialize all of the submodules.
+Start by fetching Chipyard's sources. Run:
 
 .. code-block:: shell
 
@@ -34,6 +34,8 @@ After cloning this repo, you will need to initialize all of the submodules.
     cd chipyard
     ./scripts/init-submodules-no-riscv-tools.sh
 
+This will initialize and checkout all of the necessary git submodules.
+
 When updating Chipyard to a new version, you will also want to rerun this script to update the submodules.
 Using git directly will try to initialize all submodules; this is not recommended unless you expressly desire this behavior.
 
@@ -46,15 +48,66 @@ The `toolchains` directory contains toolchains that include a cross-compiler too
 Currently there are two toolchains, one for normal RISC-V programs, and another for Hwacha (``esp-tools``).
 For custom installations, Each tool within the toolchains contains individual installation procedures within its README file.
 To get a basic installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary.
+This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
 
 .. code-block:: shell
 
     ./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain
 
-    # OR
-
-    ./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
+.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
+  If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
 
 Once the script is run, a ``env.sh`` file is emitted that sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
-You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables.
+You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables, or directly include it in your current environment:
+
+.. code-block:: shell
+
+    source ./env.sh
+
 These variables need to be set for the ``make`` system to work properly.
+
+What's Next?
+-------------------------------------------
+
+This depends on what you are planning to do with Chipyard.
+
+* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
+
+* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
+
+* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
+
+* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
+
+* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
+
+* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
+
+* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
+
+* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
+
+Upgrading Chipyard Release Versions
+-------------------------------------------
+
+In order to upgrade between Chipyard versions, we recommend using a fresh clone of the repository (or your fork, with the new release merged into it).
+
+
+Chipyard is a complex framework that depends on a mix of build systems and scripts. Specifically, it relies on git submodules, on sbt build files, and on custom written bash scripts and generated files.
+For this reason, upgrading between Chipyard versions is **not** as trivial as just running ``git submodule update -recursive``. This will result in recursive cloning of large submodules that are not necessarily used within your specific Chipyard environments. Furthermore, it will not resolve the status of stale state generated files which may not be compatible between release versions.
+
+
+If you are an advanced git user, an alternative approach to a fresh repository clone may be to run ``git clean -dfx``, and then run the standard Chipyard setup sequence. This approach is dangerous, and **not-recommended** for users who are not deeply familiar with git, since it "blows up" the repository state and removes all untracked and modified files without warning. Hence, if you were working on custom un-committed changes, you would lose them.
+
+If you would still like to try to perform an in-place manual version upgrade (**not-recommended**), we recommend at least trying to resolve stale state in the following areas:
+
+* Delete stale ``target`` directories generated by sbt.
+
+* Delete jar collateral generated by FIRRTL (``lib/firrtl.jar``)
+
+* Re-generate generated scripts and source files (for example, ``env.sh``)
+
+* Re-generating/deleting target software state (Linux kernel binaries, Linux images) within FireMarshal
+
+
+This is by no means a comprehensive list of potential stale state within Chipyard. Hence, as mentioned earlier, the recommended method for a Chipyard version upgrade is a fresh clone (or a merge, and then a fresh clone).

docs/Customization/Heterogeneous-SoCs.rst

@@ -40,13 +40,13 @@ The config fragment to add to your system would look something like the followin
         val boomTile1 = BoomTileParams(...) // params for boom core 1
         val boomTile2 = BoomTileParams(...) // params for boom core 2
         val boomTile3 = BoomTileParams(...) // params for boom core 3
-        boomTile0 ++ boomTile1 ++ boomTile2 ++ boomTile3
+        Seq(boomTile0, boomTile1, boomTile2, boomTile3)
       }
 
       case RocketTilesKey => {
         val rocketTile0 = RocketTileParams(...) // params for rocket core 0
         val rocketTile1 = RocketTileParams(...) // params for rocket core 1
-        rocketTile0 ++ rocketTile1
+        Seq(rocketTile0, rocketTile1)
       }
     })
 
@@ -56,7 +56,6 @@ Then you could use this new config fragment like the following.
 
     class SixCoreConfig extends Config(
       new WithTSI ++
-      new WithNoGPIO ++
       new WithBootROM ++
       new WithUART ++
       new freechips.rocketchip.subsystem.WithNoMMIOPort ++

docs/Generators/NVDLA.rst

@@ -0,0 +1,16 @@
+NVDLA
+====================================
+
+`NVDLA <http://nvdla.org/>`_ is an open-source deep learning accelerator developed by NVIDIA.
+The `NVDLA` is attached as a TileLink peripheral so it can be used as a component within the `Rocket Chip SoC generator`.
+The accelerator by itself exposes an AXI memory interface (or two if you use the "Large" configuration), a control interface, and an interrupt line.
+The main way to use the accelerator in Chipyard is to use the `NVDLA SW repository <https://github.com/ucb-bar/nvdla-sw>`_ that was ported to work on FireSim Linux.
+However, you can also use the accelerator in baremetal simulations (refer to ``tests/nvdla.c``).
+
+For more information on both the HW architecture and the SW, please visit their `website <http://nvdla.org/>`_.
+
+NVDLA Software with FireMarshal
+-------------------------------
+
+Located at ``software/nvdla-workload`` is a FireMarshal-based workload to boot Linux with the proper NVDLA drivers.
+Refer to that ``README.md`` for more information on how to run a simulation.

docs/Generators/TestChipIP.rst

@@ -84,3 +84,11 @@ output a UART log to a particular file using ``+uartlog=<NAME_OF_FILE>`` during
 
 By default, this UART Adapter is added to all systems within Chipyard by adding the
 ``WithUART`` and ``WithUARTAdapter`` configs.
+
+SPI Flash Model
+---------------
+
+The SPI flash model is a device that models a simple SPI flash device. It currently
+only supports single read, quad read, single write, and quad write instructions. The
+memory is backed by a file which is provided using ``+spiflash#=<NAME_OF_FILE>``,
+where ``#`` is the SPI flash ID (usually ``0``).

docs/Generators/index.rst

@@ -28,4 +28,5 @@ so changes to the generators themselves will automatically be used when building
    SiFive-Generators
    SHA3
    Ariane
+   NVDLA
 

docs/Simulation/Software-RTL-Simulation.rst

@@ -49,6 +49,8 @@ Simulating The Default Example
 To compile the example design, run ``make`` in the selected verilator or VCS directory.
 This will elaborate the ``RocketConfig`` in the example project.
 
+.. Note:: The elaboration of ``RocketConfig`` requires about 6.5 GB of main memory. Otherwise the process will fail with ``make: *** [firrtl_temp] Error 137`` which is most likely related to limited resources. Other configurations might require even more main memory.
+
 An executable called ``simulator-chipyard-RocketConfig`` 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.

docs/Software/Baremetal.rst

@@ -0,0 +1,27 @@
+.. _baremetal-programs:
+
+Baremetal RISC-V Programs
+==========================
+
+To build baremetal RISC-V programs to run in simulation, we use the riscv64-unknown-elf cross-compiler and a fork of the libgloss board support package. To build such a program yourself, simply invoke the cross-compiler with the flags "-fno-common -fno-builtin-printf -specs=htif_nano.specs" and the link with the arguments "-static -specs=htif_nano.specs". For instance, if we want to run a "Hello, World" program in baremetal, we could do the following.
+
+.. code:: c
+
+    #include <stdio.h>
+
+    int main(void)
+    {
+        printf("Hello, World!\n");
+        return 0;
+    }
+
+.. code:: bash
+
+    $ riscv64-unknown-elf-gcc -fno-common -fno-builtin-printf -specs=htif_nano.specs -c hello.c
+    $ riscv64-unknown-elf-gcc -static -specs=htif_nano.specs hello.o -o hello.riscv
+    $ spike hello.riscv
+    Hello, World!
+
+For more examples, look at the `tests/ directory <https://github.com/ucb-bar/chipyard/tree/master/tests>`_ in the chipyard repository.
+
+For more information about the libgloss port, take a look at `its README <https://github.com/ucb-bar/libgloss-htif/blob/master/README.md>`_.

docs/Software/index.rst

@@ -19,3 +19,4 @@ challenging to modify.
 
    FireMarshal
    Spike
+   Baremetal

docs/Tools/Dromajo.rst

@@ -0,0 +1,22 @@
+Dromajo
+===============================
+
+`Dromajo <https://github.com/chipsalliance/dromajo/>`__ is a RV64GC functional simulator designed for co-simulation.
+To use it as a co-simulator, it requires you to pass the committed trace of instructions coming from the core into the tool.
+Within Chipyard, this is done by connecting to the `TracePort`` signals that are piped to the top level of the DUT.
+While the Rocket core does have a `TracePort`, it does not provide the committed write data that Dromajo requires.
+Thus, Dromajo uses the `ExtendedTracePort` only probided by BOOM (BOOM is the only core that supports Dromajo co-simulation).
+An example of a divergence and Dromajo's printout is shown below.
+
+.. code-block:: shell
+
+    [error] EMU PC ffffffe001055d84, DUT PC ffffffe001055d84
+    [error] EMU INSN 14102973, DUT INSN 14102973
+    [error] EMU WDATA 00000000000220d6, DUT WDATA 00000000000220d4
+    [error] EMU MSTATUS a000000a0, DUT MSTATUS 00000000
+    [error] DUT pending exception -1 pending interrupt -1
+
+Dromajo shows the divergence compared to simulation (PC, inst, inst-bits, write data, etc) and also provides the register state on failure.
+It is useful to catch bugs that affect architectural state before a simulation hangs or crashes.
+
+To use Dromajo with BOOM, refer to :ref:`Debugging RTL` section on Dromajo.

docs/Tools/index.rst

@@ -14,4 +14,4 @@ The following pages will introduce them, and how we can use them in order to gen
    Chisel-Testers
    Dsptools
    Barstools
-
+   Dromajo

docs/_static/css/custom.css

@@ -0,0 +1,6 @@
+.important {
+  font-size: 175%;
+}
+.important p{
+  font-size: 100%;
+}

docs/conf.py

@@ -106,6 +106,9 @@ html_theme_options = {
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = [
+        'css/custom.css',
+]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/index.rst

@@ -10,75 +10,9 @@ Welcome to Chipyard's documentation!
 
 Chipyard is 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 integration between open-source and commercial tools for the development of systems-on-chip.
-New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.
 
-Quick Start
-===============================
+.. IMPORTANT:: **New to Chipyard?** Jump to the :ref:`Initial Repository Setup` page for setup instructions.
 
-System Requirements
--------------------------------------------
-
-Chipyard is developed and tested on Linux-based systems.
-
-.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
-
-.. Warning:: Working under Windows is not recommended.
-
-Setting up the Chipyard Repo
--------------------------------------------
-
-Start by fetching Chipyard's sources. Run:
-
-.. code-block:: shell
-
-    git clone https://github.com/ucb-bar/chipyard.git
-    cd chipyard
-    ./scripts/init-submodules-no-riscv-tools.sh
-
-This will initialize and checkout all of the necessary git submodules.
-
-Installing the RISC-V Tools
--------------------------------------------
-
-We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
-This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
-To build the toolchains, you should run:
-
-.. code-block:: shell
-
-    ./scripts/build-toolchains.sh
-
-.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
-  If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
-
-Finally, set up Chipyard's environment variables and put the newly built toolchain on your path:
-
-.. code-block:: shell
-
-    source ./env.sh
-
-What's Next?
--------------------------------------------
-
-This depends on what you are planning to do with Chipyard.
-
-* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
-
-* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
-
-* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
-
-* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
-
-* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
-
-* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
-
-* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
-
-* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
-
-  
 Getting Help
 ------------
 

docs/requirements.txt

@@ -1,4 +1,4 @@
-Sphinx==1.7.4
+Sphinx==1.8.5
 Pygments==2.2.0
 sphinx-autobuild
 sphinx_rtd_theme==0.2.5b1