Merge remote-tracking branch 'origin/dev' into dev-asap7-demo

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Advanced-Usage/DTM-Debugging.rst

@@ -3,7 +3,7 @@ Debugging with DTM/JTAG
 
 By default, Chipyard is not setup to use the Debug Test Module (DTM) to bringup the core.
 Instead, Chipyard uses TSI commands to bringup the core (which normally results in a faster simulation).
-TSI simulations use the SimSerial interface to directly write the test binary into memory, while the DTM 
+TSI simulations use the SimSerial interface to directly write the test binary into memory, while the DTM
 executes a small loop of code to write the test binary byte-wise into memory.
 However, if you want to use JTAG, you must do the following steps to setup a DTM enabled system.
 
@@ -13,13 +13,10 @@ Creating a DTM/JTAG Config
 First, a DTM config must be created for the system that you want to create.
 This involves specifying the SoC top-level to add a DTM as well as configuring that DTM to use JTAG.
 
-.. code-block:: scala
-
-    class DTMBoomConfig extends Config(
-      new WithDTMTop ++
-      new WithBootROM ++
-      new WithJtagDTM ++
-      new boom.common.SmallBoomConfig)
+.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
+    :language: scala
+    :start-after: DOC include start: JtagRocket
+    :end-before: DOC include end: JtagRocket
 
 In this example, the ``WithDTMTop`` mixin specifies that the top-level SoC will instantiate a DTM.
 The ``WithJtagDTM`` will configure that instantiated DTM to use JTAG as the bringup method (note: this can be removed if you want a DTM-only bringup).

docs/Advanced-Usage/Resources.rst

@@ -1,8 +1,9 @@
 Accessing Scala Resources
 ===============================
 
-A simple way to copy over a source file to the build directory to be used for a simulation compile or VLSI flow is to use the ``addResource`` functions given by FIRRTL.
-It can be used in the following way:
+A simple way to copy over a source file to the build directory to be used for a simulation compile or VLSI flow is to use the ``addResource`` function given by FIRRTL.
+An example of its use can be seen in `generators/testchipip/src/main/scala/SerialAdapter.scala <https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/SerialAdapter.scala>`_.
+Here is the example inlined:
 
 .. code-block:: scala
 

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -8,12 +8,13 @@ Generators
 
 The Chipyard Framework currently consists of the following RTL generators:
 
+
 Processor Cores
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Rocket**
+**Rocket Core**
   An in-order RISC-V core.
-  See :ref:`Rocket` for more information.
+  See :ref:`Rocket Core` for more information.
 
 **BOOM (Berkeley Out-of-Order Machine)**
   An out-of-order RISC-V core.

docs/Chipyard-Basics/Configs-Parameters-Mixins.rst

@@ -8,8 +8,6 @@ In order to use the parameter system correctly, we will use several terms and co
 Parameters
 --------------------
 
-TODO: Need to explain up, site, field, and other stuff from Henry's thesis.
-
 It is important to note that a significant challenge with the Rocket parameter system is being able to identify the correct parameter to use, and the impact that parameter has on the overall system.
 We are still investigating methods to facilitate parameter exploration and discovery.
 
@@ -82,17 +80,56 @@ This example shows a Rocket Chip based SoC that merges multiple system component
 .. code-block:: scala
 
   class MySoC(implicit p: Parameters) extends RocketSubsystem
-    with CanHaveMisalignedMasterAXI4MemPort
+    with CanHaveMasterAXI4MemPort
     with HasPeripheryBootROM
     with HasNoDebug
     with HasPeripherySerial
     with HasPeripheryUART
     with HasPeripheryIceNIC
   {
-     //Additional top-level specific instantiations or wiring
+     lazy val module = new MySoCModuleImp(this)
   }
 
-Mix-in
+  class MySoCModuleImp(outer: MySoC) extends RocketSubsystemModuleImp(outer)
+    with CanHaveMasterAXI4MemPortModuleImp
+    with HasPeripheryBootROMModuleImp
+    with HasNoDebugModuleImp
+    with HasPeripherySerialModuleImp
+    with HasPeripheryUARTModuleImp
+    with HasPeripheryIceNICModuleImp
+
+There are two "cakes" here. One for the lazy module (ex. ``HasPeripherySerial``) and one for the lazy module
+implementation (ex. ``HasPeripherySerialModuleImp`` where ``Imp`` refers to implementation). The lazy module defines
+all the logical connections between generators and exchanges configuration information among them, while the
+lazy module implementation performs the actual Chisel RTL elaboration.
+
+In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner"
+``MySoCModuleImp`` as a lazy module implementation. This delays immediate elaboration
+of the module until all logical connections are determined and all configuration information is exchanged.
+The ``RocketSubsystem`` outer base class, as well as the
+``HasPeripheryX`` outer traits contain code to perform high-level logical
+connections. For example, the ``HasPeripherySerial`` outer trait contains code
+to lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s
+TileLink node to the Front bus.
+
+The ``ModuleImp`` classes and traits perform elaboration of real RTL.
+For example, the ``HasPeripherySerialModuleImp`` trait physically connects
+the ``SerialAdapter`` module, and instantiates queues.
+
+In the test harness, the SoC is elaborated with
+``val dut = Module(LazyModule(MySoC))``.
+After elaboration, the result will be a MySoC module, which contains a
+SerialAdapter module (among others).
+
+From a high level, classes which extend LazyModule *must* reference
+their module implementation through ``lazy val module``, and they
+*may* optionally reference other lazy modules (which will elaborate
+as child modules in the module hierarchy). The "inner" modules
+contain the implementation for the module, and may instantiate
+other normal modules OR lazy modules (for nested Diplomacy
+graphs, for example).
+
+ Mix-in
 ---------------------------
 
 A mix-in is a Scala trait, which sets parameters for specific system components, as well as enabling instantiation and wiring of the relevant system components to system buses.

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

@@ -1,6 +1,13 @@
 Initial Repository Setup
 ========================================================
 
+Requirements
+-------------------------------------------
+
+Chipyard is developed and tested on Linux-based systems.
+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``.
+Working under Windows is not recommended.
+
 Checking out the sources
 ------------------------
 
@@ -28,6 +35,6 @@ But to get a basic installation, just the following steps are necessary.
 
     ./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
 
-Once the script is run, a ``env.sh`` file is emitted at sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
+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.
 These variables need to be set for the make system to work properly.

docs/Chipyard-Basics/index.rst

@@ -20,5 +20,3 @@ Hit next to get started!
    Chipyard-Components
    Configs-Parameters-Mixins
    Initial-Repo-Setup
-   Running-A-Simulation
-   Building-A-Chip

docs/Customization/Boot-Process.rst

@@ -7,11 +7,12 @@ SoC boots a Linux kernel and the changes you can make to customize this process.
 BootROM and RISC-V Frontend Server
 ----------------------------------
 
-The first instructions to run when the SoC is powered on are those stored in
-the BootROM. The assembly for the BootROM code is located in
+The BootROM contains both the first instructions to run when the SoC is powered on as well as the
+Device Tree Binary (dtb) which details the components of the system.
+The assembly for the BootROM code is located in
 `generators/testchipip/src/main/resources/testchipip/bootrom/bootrom.S <https://github.com/ucb-bar/testchipip/blob/master/src/main/resources/testchipip/bootrom/bootrom.S>`_.
-The BootROM address space starts at ``0x10000`` and execution starts at address
-``0x10040``, which is marked by the ``_hang`` label in the BootROM assembly.
+The BootROM address space starts at ``0x10000`` (determined by the ``BootROMParams`` key in the configuration) and execution starts at address
+``0x10040`` (given by the linker script and reset vector in the ``BootROMParams``), which is marked by the ``_hang`` label in the BootROM assembly.
 
 The Chisel generator encodes the assembled instructions into the BootROM
 hardware at elaboration time, so if you want to change the BootROM code, you

docs/Customization/Heterogeneous-SoCs.rst

@@ -8,22 +8,15 @@ Creating a Rocket and BOOM System
 -------------------------------------------
 
 Instantiating an SoC with Rocket and BOOM cores is all done with the configuration system and two specific mixins.
-Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core.
+Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core/tile [1]_.
 When used together you can create a heterogeneous system.
+
 The following example shows a dual core BOOM with a single core Rocket.
 
-.. code-block:: scala
-
-    class DualBoomAndOneRocketConfig extends Config(
-      new WithTop ++
-      new WithBootROM ++
-      new boom.system.WithRenumberHarts ++
-      new boom.common.WithRVC ++
-      new boom.common.LargeBoomConfig ++
-      new boom.system.WithNBoomCores(2) ++
-      new freechips.rocketchip.subsystem.WithoutTLMonitors ++
-      new freechips.rocketchip.subsystem.WithNBigCores(1) ++
-      new freechips.rocketchip.system.BaseConfig)
+.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
+    :language: scala
+    :start-after: DOC include start: DualBoomAndRocket
+    :end-before: DOC include end: DualBoomAndRocket
 
 In this example, the ``WithNBoomCores`` and ``WithNBigCores`` mixins set up the default parameters for the multiple BOOM and Rocket cores, respectively.
 However, for BOOM, an extra mixin called ``LargeBoomConfig`` is added to override the default parameters with a different set of more common default parameters.
@@ -31,7 +24,7 @@ This mixin applies to all BOOM cores in the system and changes the parameters fo
 
 Great! Now you have a heterogeneous setup with BOOMs and Rockets.
 The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId`` (a ``hartId`` is the hardware thread id of the core).
-This is done with ``WithRenumberHarts`` (which can label the Rocket cores first or the BOOM cores first).
+The ``WithRenumberHarts`` mixin solves this by assigning a unique ``hartId`` to all cores in the system (it can label the Rocket cores first or the BOOM cores first).
 The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only BOOM or only Rocket cores in the system.
 Thus, without the ``WithRenumberHarts`` mixin, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``.
 
@@ -75,19 +68,10 @@ Adding Hwachas
 Adding a Hwacha accelerator is as easy as adding the ``DefaultHwachaConfig`` so that it can setup the Hwacha parameters and add itself to the ``BuildRoCC`` parameter.
 An example of adding a Hwacha to all tiles in the system is below.
 
-.. code-block:: scala
-
-    class DualBoomAndRocketWithHwachasConfig extends Config(
-      new WithTop ++
-      new WithBootROM ++
-      new hwacha.DefaultHwachaConfig ++
-      new boom.system.WithRenumberHarts ++
-      new boom.common.WithRVC ++
-      new boom.common.LargeBoomConfig ++
-      new boom.system.WithNBoomCores(2) ++
-      new freechips.rocketchip.subsystem.WithoutTLMonitors ++
-      new freechips.rocketchip.subsystem.WithNBigCores(1) ++
-      new freechips.rocketchip.system.BaseConfig)
+.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
+    :language: scala
+    :start-after: DOC include start: BoomAndRocketWithHwacha
+    :end-before: DOC include end: BoomAndRocketWithHwacha
 
 In this example, Hwachas are added to both BOOM tiles and to the Rocket tile.
 All with the same Hwacha parameters.
@@ -100,27 +84,20 @@ Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on
 For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles.
 An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached.
 
-.. code-block:: scala
-
-    class DualBoomAndOneHwachaRocketConfig extends Config(
-      new WithTop ++
-      new WithBootROM ++
-      new WithMultiRoCC ++
-      new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket
-      new boom.system.WithRenumberHarts(rocketFirst = true) ++
-      new hwacha.DefaultHwachaConfig ++
-      new boom.common.WithRVC ++
-      new boom.common.LargeBoomConfig ++
-      new boom.system.WithNBoomCores(2) ++
-      new freechips.rocketchip.subsystem.WithoutTLMonitors ++
-      new freechips.rocketchip.subsystem.WithNBigCores(1) ++
-      new freechips.rocketchip.system.BaseConfig)
+.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
+    :language: scala
+    :start-after: DOC include start: DualBoomAndRocketOneHwacha
+    :end-before: DOC include end: DualBoomAndRocketOneHwacha
 
 In this example, the ``WithRenumberHarts`` relabels the ``hartId``'s of all the BOOM/Rocket cores.
-Then after that is applied to the parameters, the ``WithMultiRoCCHwacha(0)`` is used to assign to ``hartId`` zero a Hwacha (in this case ``hartId`` zero is Rocket).
+Then after that is applied to the parameters, the ``WithMultiRoCCHwacha`` mixin assigns a Hwacha accelerator to a particular ``hartId`` (in this case, the ``hartId`` of ``2`` corresponds to the Rocket core).
 Finally, the ``WithMultiRoCC`` mixin is called.
 This mixin sets the ``BuildRoCC`` key to use the ``MultiRoCCKey`` instead of the default.
 This must be used after all the RoCC parameters are set because it needs to override the ``BuildRoCC`` parameter.
 If this is used earlier in the configuration sequence, then MultiRoCC does not work.
 
 This mixin can be changed to put more accelerators on more cores by changing the arguments to cover more ``hartId``'s (i.e. ``WithMultiRoCCHwacha(0,1,3,6,...)``).
+
+
+.. [1] Note, in this section "core" and "tile" are used interchangeably but there is subtle distinction between a "core" and "tile" ("tile" contains a "core", L1D/I$, PTW).
+    For many places in the documentation, we usually use "core" to mean "tile" (doesn't make a large difference but worth the mention).

docs/Customization/Memory-Hierarchy.rst

@@ -1,3 +1,5 @@
+.. _memory-hierarchy:
+
 Memory Hierarchy
 ===============================
 
@@ -105,7 +107,7 @@ the Broadcast Hub to use a bufferless design.
 The Outer Memory System
 -----------------------
 
-The L2 coherence agent (either L2 cache of Broadcast Hub) makes requests to
+The L2 coherence agent (either L2 cache or Broadcast Hub) makes requests to
 an outer memory system consisting of an AXI4-compatible DRAM controller.
 
 The default configuration uses a single memory channel, but you can configure

docs/Generators/BOOM.rst

@@ -1,8 +1,10 @@
 Berkeley Out-of-Order Machine (BOOM)
 ==============================================
 
+.. image:: ../_static/images/boom-pipeline-detailed.png
+
 The `Berkeley Out-of-Order Machine (BOOM) <https://boom-core.org/>`__ is a synthesizable and parameterizable open source RV64GC RISC-V core written in the Chisel hardware construction language.
-It serves as a drop-in replacement to the Rocket core given by Rocket Chip.
+It serves as a drop-in replacement to the Rocket core given by Rocket Chip (replaces the RocketTile with a BoomTile).
 BOOM is heavily inspired by the MIPS R10k and the Alpha 21264 out-of-order processors.
 Like the R10k and the 21264, BOOM is a unified physical register file design (also known as “explicit register renaming”).
 Conceptually, BOOM is broken up into 10 stages: Fetch, Decode, Register Rename, Dispatch, Issue, Register Read, Execute, Memory, Writeback and Commit.

docs/Generators/Hwacha.rst

@@ -2,7 +2,14 @@ Hwacha
 ====================================
 
 The Hwacha project is developing a new vector architecture for future computer systems that are constrained in their power and energy consumption.
-Inspired by traditional vector machines from the 70s and 80s, and lessons learned from our previous vector-thread architectures Scale and Maven, we are bringing back elegant, performant, and energy-efficient aspects of vector processing to modern data-parallel architectures.
-We propose a new vector-fetch architectural paradigm, which focuses on the following aspects for higher performance, better energy efficiency, and lower complexity.
+The Hwacha project is inspired by traditional vector machines from the 70s and 80s, and lessons learned from our previous vector-thread architectures such as Scale and Maven
+The Hwacha project includes the Hwacha microarchitecture generator, as well as the ``XHwacha`` non-standard RISC-V extension. Hwacha does not implement the RISC-V standard vector extension proposal.
 
-For more information, please visit the `Hwacha website <http://hwacha.org/>`__.
+For more information on the Hwacha project, please visit the `Hwacha website <http://hwacha.org/>`__.
+
+To add the Hwacha vector unit to an SoC, you should add the ``hwacha.DefaultHwachaConfig`` config mixin to the SoC configurations. The Hwacha vector unit uses the RoCC port of a Rocket or BOOM `tile`, and by default connects to the memory system through the `System Bus` (i.e., directly to the L2 cache). 
+
+To change the configuration of the Hwacha vector unit, you can write a custom configuration to replace the ``DefaultHwachaConfig``. You can view the ``DefaultHwachaConfig`` under `generators/hwacha/src/main/scala/configs.scala <https://github.com/ucb-bar/hwacha/blob/master/src/main/scala/configs.scala>`__ to see the possible configuration parameters.
+ 
+Since Hwacha implements a non-standard RISC-V extension, it requires a unique software toolchain to be able to compile and asseble its vector instructions.
+To install the Hwacha toolchain, run the ``./scripts/build-toolchains.sh esp-tools`` command within the root Chipyard directory. This may take a while, and it will install the ``esp-tools-install`` directory within your Chipyard root directory. ``esp-tools`` is a fork of ``riscv-tools`` (formerly a collection of relevant software RISC-V tools) that was enhanced with additional non-standard vector instructions. However, due to the upstreaming of the equivalent RISC-V toolchains, ``esp-tools`` may not be up-to-date with the latest mainline version of the tools included in it.

docs/Generators/IceNet.rst

@@ -0,0 +1,87 @@
+IceNet
+======
+
+IceNet is a library of Chisel designs related to networking. The main component
+of IceNet is IceNIC, a network interface controller that is used primarily
+in `FireSim <https://fires.im/>`_ for multi-node networked simulation.
+A diagram of IceNet's microarchitecture is shown below.
+
+.. image:: ../_static/images/nic-design.png
+
+There are four basic parts of the NIC: the :ref:`Controller`, which takes requests 
+from and sends responses to the CPU; the :ref:`Send Path`, which reads data from
+memory and sends it out to the network; the :ref:`Receive Path`, which receives
+data from the network and writes it to memory; and, optionally,
+the :ref:`Pause Handler`, which generates Ethernet pause frames for the purpose
+of flow control.
+
+Controller
+----------
+
+The controller exposes a set of MMIO registers to the CPU. The device driver
+writes to registers to request that packets be sent or to provide memory
+locations to write received data to. Upon the completion of a send request or
+packet receive, the controller sends an interrupt to the CPU, which clears
+the completion by reading from another register.
+
+Send Path
+---------
+
+The send path begins at the reader, which takes requests from the controller
+and reads the data from memory.
+
+Since TileLink responses can come back out-of-order, we use a reservation
+queue to reorder responses so that the packet data can be sent out in the
+proper order.
+
+The packet data then goes to an arbiter, which can arbitrate access to the
+outbound network interface between the NIC and one or more "tap in" interfaces,
+which come from other hardware modules that may want to send Ethernet packets.
+By default, there are no tap in interfaces, so the arbiter simply passes
+the output of the reservation buffer through.
+
+Receive Path
+------------
+
+The receive path begins with the packet buffer, which buffers data coming
+in from the network. If there is insufficient space in the buffer, it will
+drop data at packet granularity to ensure that the NIC does not deliver
+incomplete packets.
+
+From the packet buffer, the data can optionally go to a network tap, which
+examines the Ethernet header and select packets to be redirected from the NIC
+to external modules through one or more "tap out" interfaces. By default, there
+are no tap out interfaces, so the data will instead go directly to the writer,
+which writes the data to memory and then sends a completion to the controller.
+
+Pause Handler
+-------------
+
+IceNIC can be configured to have pause handler, which sits between the
+send and receive paths and the Ethernet interface. This module tracks the
+occupancy of the receive packet buffer. If it sees the buffer filling up, it
+will send an `Ethernet pause frame <https://en.wikipedia.org/wiki/Ethernet_flow_control#Pause_frame>`_
+out to the network to block further packets from being sent. If the NIC receives
+an Ethernet pause frame, the pause handler will block sending from the NIC.
+
+Linux Driver
+------------
+
+The default Linux configuration provided by `firesim-software <https://github.com/firesim/firesim-software>`_
+contains an IceNet driver. If you launch a FireSim image that has IceNIC on it,
+the driver will automatically detect the device, and you will be able to use
+the full Linux networking stack in userspace.
+
+Configuration
+-------------
+
+To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module
+and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you
+are confused about the distinction between lazy module and module
+implementation, refer to :ref:`Cake Pattern`.
+
+Then add the ``WithIceNIC`` config mixin to your configuration. This will
+define ``NICKey``, which IceNIC uses to determine its parameters. The mixin
+takes two arguments. The ``inBufFlits`` argument is the number of 64-bit flits
+that the input packet buffer can hold and the ``usePauser`` argument determines
+whether or not the NIC will have a pause handler.

docs/Generators/Rocket-Chip.rst

@@ -1,15 +1,15 @@
-RocketChip
-==========
+Rocket Chip
+===========
 
-RocketChip is an SoC generator developed at Berkeley and now supported by
-SiFive. Chipyard uses RocketChip as the basis for producing a RISC-V SoC.
+Rocket Chip generator is an SoC generator developed at Berkeley and now supported by
+SiFive. Chipyard uses the Rocket Chip generator as the basis for producing a RISC-V SoC.
 
-RocketChip is distinct from Rocket, the in-order RISC-V CPU generator.
-RocketChip includes many parts of the SoC besides the CPU. Though RocketChip
-uses Rocket CPUs by default, it can also be configured to use the BOOM
+`Rocket Chip` is distinct from `Rocket core`, the in-order RISC-V CPU generator.
+Rocket Chip includes many parts of the SoC besides the CPU. Though Rocket Chip
+uses Rocket core CPUs by default, it can also be configured to use the BOOM
 out-of-order core generator or some other custom CPU generator instead.
 
-A detailed diagram of a typical RocketChip system is shown below.
+A detailed diagram of a typical Rocket Chip system is shown below.
 
 .. image:: ../_static/images/rocketchip-diagram.png
 

docs/Generators/Rocket.rst

@@ -1,8 +1,9 @@
-Rocket
+Rocket Core
 ====================================
 
-`Rocket <https://github.com/freechipsproject/rocket-chip>`__ is a 5-stage in-order scalar core generator that is supported by `SiFive <https://www.sifive.com/>`__.
-It supports the open source RV64GC RISC-V instruction set and is written in the Chisel hardware construction language.
+`Rocket <https://github.com/freechipsproject/rocket-chip>`__ is a 5-stage in-order scalar processor core generator, originally developed at UC Berkeley and currently supported by `SiFive <https://www.sifive.com/>`__. The `Rocket core` is used as a component within the `Rocket Chip SoC generator`. A Rocket core combined with L1 caches (data and instruction caches) form a `Rocket tile`. The `Rocket tile` is the replicable component of the `Rocket Chip SoC generator`.
+
+The Rocket core supports the open-source RV64GC RISC-V instruction set and is written in the Chisel hardware construction language.
 It has an MMU that supports page-based virtual memory, a non-blocking data cache, and a front-end with branch prediction.
 Branch prediction is configurable and provided by a branch target buffer (BTB), branch history table (BHT), and a return address stack (RAS).
 For floating-point,  Rocket  makes  use  of  Berkeley’s  Chisel  implementations  of  floating-point  units.

docs/Generators/SHA3.rst

@@ -0,0 +1,80 @@
+SHA3 RoCC Accelerator
+===================================
+The SHA3 accelerator is a basic RoCC accelerator for the SHA3 hashing algorithm.
+We like using SHA3 in Chipyard tutorial content because it is a self-contained, simple
+example of integrating a custom accelerator into Chipyard.
+
+
+Introduction
+-----------------------------------
+Secure hashing algorithms represent a class of hashing functions that provide four attributes: ease
+of hash computation, inability to generate the message from the hash (one-way property), inability
+to change the message and not the hash (weakly collision free property), and inability to find
+two messages with the same hash (strongly collision free property). The National Institute of
+Standards and Technology (NIST) recently held a competition for a new algorithm to be added to
+its set of Secure Hashing Algorithms (SHA). In 2012 the winner was determined to be the Keccak
+hashing function and a rough specification for SHA3 was established. The algorithm operates on
+variable length messages with a sponge function, and thus alternates between absorbing chunks of
+the message into a set of state bits and permuting the state. The absorbing is a simple bitwise
+XOR while the permutation is a more complex function composed of several operations, χ, θ, ρ,
+π, ι, that all perform various bitwise operations, including rotations, parity calculations, XORs,
+etc. The Keccak hashing function is parameterized for different sizes of state and message chunks
+but for this accelerator we will only support the Keccak-256 variant with 1600 bits of state and
+1088 bit message chunks. A diagram of the SHA3 accelerator is shown below.
+
+.. image:: ../_static/images/sha3.png
+
+Technical Details
+------------------------------------
+The accelerator is designed around three sub-systems, an
+interface with the processor, an interface with memory, and
+the actual hashing computation system. The interface
+with the processor is designed using the ROCC interface for
+coprocessors integrating with the RISC-V Rocket/BOOM
+processor. It includes the ability to transfer two 64 bit
+words to the co-processor, the request for a return value,
+and a small field for the function requested. The accelerator
+receives these requests using a ready/valid interface. The
+ROCC instruction is parsed and the needed information is
+stored into a execution context. The execution context contains
+the memory address of the message being hashed, the memory address
+to store the resulting hash in, the length of the message, and
+several other control fields.
+
+Once the execution context is valid the memory subsystem
+then begins to fetch chunks of the message. The memory
+subsystem is fully decoupled from the other subsystems
+and maintains a single full round memory buffers.
+The accelerators memory interface can provide a
+maximum of one 64 bit word per cycle which corresponds
+to 17 requests needed to fill a buffer (the size is dictated by
+the SHA3 algorithm). Memory requests to fill these buffers
+are sent out as rapidly as the memory interface can handle,
+with a tag field set to allow the different memory buffers
+requests to be distinguished, as they may be returned out of
+order. Once the memory subsystem has filled a buffer the
+control unit absorbs the buffer into the execution
+context, at which point the execution context is free to
+begin permutation, and the memory buffer is free to send
+more memory requests.
+
+After the buffer is absorbed, the hashing computation
+subsystem begins the permutation operations. Once
+the message is fully hashed, the hash is written to memory
+with a simple state machine.
+
+
+Using a SHA3 Accelerator
+------------------------
+Since the SHA3 accelerator is designed as a RoCC accelerator,
+it can be mixed into a Rocket or BOOM core by overriding the
+BuildRoCC key. The configuration mixin is defined in the SHA3
+generator. An example configuration highlighting the use of
+this mixin is shown here:
+
+.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
+   :language: scala
+   :start-after: DOC include start: Sha3Rocket
+   :end-before: DOC include end: Sha3Rocket
+
+

docs/Generators/SiFive-Generators.rst

@@ -0,0 +1,45 @@
+SiFive Generators
+==================
+
+Chipyard includes several open-source generators developed and maintained by `SiFive <https://www.sifive.com/>`__. 
+These are currently organized within two submodules named ``sifive-blocks`` and ``sifive-cache``.
+
+Last-Level Cache Generator
+-----------------------------
+
+``sifive-cache`` includes last-level cache geneator. The Chipyard framework uses this last-level cache as an L2 cache. To use this L2 cache, you should add the ``freechips.rocketchip.subsystem.WithInclusiveCache`` mixin to your SoC configuration.
+To learn more about configuring this L2 cache, please refer to the :ref:`memory-hierarchy` section.
+
+
+Peripheral Devices
+-------------------
+``sifive-blocks`` includes multiple peripheral device generators, such as UART, SPI, PWM, JTAG, GPIO and more.
+
+These peripheral devices usually affect the memory map of the SoC, and its top-level IO as well.
+To integrate one of these devices in your SoC, you will need to define a custom mixin with the approriate address for the device using the Rocket Chip parameter system. As an example, for a GPIO device you could add the following mixin to set the GPIO address to ``0x10012000``. This address is the start address for the GPIO configuration registers. 
+
+.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
+    :language: scala
+    :start-after: DOC include start: WithGPIO
+    :end-before: DOC include end: WithGPIO
+
+Additionally, if the device requires top-level IOs, you will need to define a mixin to change the top-level configuration of your SoC.
+When adding a top-level IO, you should also be aware of whether it interacts with the test-harness.
+For example, a GPIO device would require a GPIO pin, and therefore we would write a mixin to augment the top level as follows:
+
+.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
+    :language: scala
+    :start-after: DOC include start: WithGPIOTop
+    :end-before: DOC include end: WithGPIOTop
+
+This example instantiates a top-level module with include GPIO ports (``TopWithGPIO``), and then ties-off the GPIO port inputs to 0 (``false.B``).
+
+
+Finally, you add the relevant config mixin to the SoC config. For example:
+
+.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
+    :language: scala
+    :start-after: DOC include start: GPIORocketConfig
+    :end-before: DOC include end: GPIORocketConfig
+
+Some of the devices in ``sifive-blocks`` (such as GPIO) may already have pre-defined mixins within the Chipyard example project. You may be able to use these config mixins directly, but you should be aware of their addresses within the SoC address map. 

docs/Generators/TestChipIP.rst

@@ -0,0 +1,63 @@
+Test Chip IP
+============
+
+Chipyard includes a Test Chip IP library which provides various hardware
+widgets that may be useful when designing SoCs. This includes a :ref:`Serial Adapter`,
+:ref:`Block Device Controller`, :ref:`TileLink SERDES`, and :ref:`TileLink Switcher`.
+
+Serial Adapter
+--------------
+
+The serial adapter is used by tethered test chips to communicate with the host
+processor. An instance of RISC-V frontend server running on the host CPU 
+can send commands to the serial adapter to read and write data from the memory
+system. The frontend server uses this functionality to load the test program
+into memory and to poll for completion of the program. More information on
+this can be found in :ref:`Chipyard Boot Process`.
+
+Block Device Controller
+-----------------------
+
+The block device controller provides a generic interface for secondary storage.
+This device is primarily used in FireSim to interface with a block device
+software simulation model. The default Linux configuration in `firesim-software <https://github.com/firesim/firesim-software>`_
+
+To add a block device to your design, add ``HasPeripheryBlockDevice`` to your
+lazy module and ``HasPeripheryBlockDeviceModuleImp`` to the implementation.
+Then add the ``WithBlockDevice`` config mixin to your configuration.
+
+
+TileLink SERDES
+---------------
+
+The TileLink SERDES in the Test Chip IP library allow TileLink memory requests
+to be serialized so that they can be carried off chip through a serial link.
+The five TileLink channels are multiplexed over two SERDES channels, one in
+each direction.
+
+There are three different variants provided by the library, ``TLSerdes``
+exposes a manager interface to the chip, tunnels A, C, and E channels on
+its outbound link, and tunnels B and D channels on its inbound link. ``TLDesser``
+exposes a client interface to the chip, tunnels A, C, and E on its inbound link,
+and tunnels B and D on its outbound link. Finally, ``TLSerdesser`` exposes
+both client and manager interface to the chip and can tunnel all channels in
+both directions.
+
+For an example of how to use the SERDES classes, take a look at the
+``SerdesTest`` unit test in `the Test Chip IP unit test suite
+<https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/Unittests.scala>`_.
+
+TileLink Switcher
+-----------------
+
+The TileLink switcher is used when the chip has multiple possible memory
+interfaces and you would like to select which channels to map your memory
+requests to at boot time. It exposes a client node, multiple manager nodes,
+and a select signal. Depending on the setting of the select signal, requests
+from the client node will be directed to one of the manager nodes.
+The select signal must be set before any TileLink messages are sent and be
+kept stable throughout the remainder of operation. It is not safe to change
+the select signal once TileLink messages have begun sending.
+
+For an example of how to use the switcher, take a look at the ``SwitcherTest``
+unit test in the `Test Chip IP unit tests <https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/Unittests.scala>`_.

docs/Generators/index.rst

@@ -1,17 +1,28 @@
+.. _generator-index:
+
 Generators
 ============================
 
-Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.
+A Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.
 This type of meta-programming is enabled by the Chisel hardware description language (see :ref:`Chisel`).
 A standard RTL design is essentially just a single instance of a design coming from a generator.
 However, by using meta-programming and parameter systems, generators can allow for integration of complex hardware designs in automated ways.
 The following pages introduce the generators integrated with the Chipyard framework.
 
+Chipyard bundles the source code for the generators, under the ``generators`` directory.
+It builds them from source each time (although the build system will cache results if they have not changed),
+so changes to the generators themselves will automatically be used when building with Chipyard and propagate to software simulation, FPGA-accelerated simulation, and VLSI flows.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Generators:
 
+   Rocket-Chip
    Rocket
    BOOM
    Hwacha
-   RocketChip
+   IceNet
+   TestChipIP
+   SiFive-Generators   
+   SHA3

docs/Quick-Start.rst

@@ -1,6 +1,13 @@
 Quick Start
 ===============================
 
+Requirements
+-------------------------------------------
+
+Chipyard is developed and tested on Linux-based systems.
+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``.
+Working under Windows is not recommended.
+
 Setting up the Chipyard Repo
 -------------------------------------------
 
@@ -28,22 +35,29 @@ To build the toolchains, you should run:
 .. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchains 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 want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
-
-* If you intend to build one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
-
-* If you intend to add a new accelerator, go to :ref:`adding-an-accelerator` and follow the instructions.
-
 * 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 <> 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:`adding-an-accelerator` 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 VLSI flow using one of the vanilla Chipyard examples, go to <> 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.

docs/Simulation/Running-A-Simulation.rst

@@ -39,13 +39,21 @@ In order to construct the simulator with our custom design, we run the following
     make SBT_PROJECT=... MODEL=... VLOG_MODEL=... MODEL_PACKAGE=... CONFIG=... CONFIG_PACKAGE=... GENERATOR_PACKAGE=... TB=... TOP=...
 
 Each of these make variables correspond to a particular part of the design/codebase and are needed so that the make system can correctly build and make a RTL simulation.
+
 The ``SBT_PROJECT`` is the ``build.sbt`` project that holds all of the source files and that will be run during the RTL build.
+
 The ``MODEL`` and ``VLOG_MODEL`` are the top-level class names of the design.
+
 Normally, these are the same, but in some cases these can differ (if the Chisel class differs than what is emitted in the Verilog).
+
 The ``MODEL_PACKAGE`` is the Scala package (in the Scala code that says ``package ...``) that holds the ``MODEL`` class.
+
 The ``CONFIG`` is the name of the class used for the parameter Config while the ``CONFIG_PACKAGE`` is the Scala package it resides in.
+
 The ``GENERATOR_PACKAGE`` is the Scala package that holds the Generator class that elaborates the design.
+
 The ``TB`` is the name of the Verilog wrapper that connects the ``TestHarness`` to VCS/Verilator for simulation.
+
 Finally, the ``TOP`` variable is used to distinguish between the top-level of the design and the ``TestHarness`` in our system.
 For example, in the normal case, the ``MODEL`` variable specifies the ``TestHarness`` as the top-level of the design.
 However, the true top-level design, the SoC being simulated, is pointed to by the ``TOP`` variable.

docs/Simulation/Software-RTL-Simulation.rst

@@ -0,0 +1,140 @@
+.. _sw-rtl-sim-intro:
+
+Software RTL Simulation
+===================================
+
+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.
+
+
+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.
+VCS simulation will generally compile faster than Verilator simulations.
+
+To run a VCS simulation, make sure that the VCS simulator is on your ``PATH``.
+
+
+Choice of Simulator
+-------------------------------
+
+First, we will start by entering the Verilator or VCS directory:
+
+For an open-source Verilator simulation, enter the ``sims/verilator`` directory
+
+.. code-block:: shell
+
+    # Enter Verilator directory
+    cd sims/verilator
+
+For a proprietry VCS simulation, enter the ``sims/vcs`` directory
+
+.. code-block:: shell
+
+    # Enter VCS directory
+    cd sims/vcs
+
+
+.. _sim-default:
+
+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.
+
+An executable called ``simulator-example-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.
+For instance, to run one of the riscv-tools assembly tests.
+
+.. code-block:: shell
+
+    ./simulator-example-RocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
+
+.. Note:: in a VCS simulator, the simulator name will be ``simv-example-RocketConfig`` ``instead of simulator-example-RocketConfig``.
+
+Alternatively, we can run a pre-packaged suite of RISC-V assembly or benchmark tests, by adding the make target ``run-asm-tests`` or ``run-bmark-tests``.
+For example:
+
+.. code-block:: shell
+
+    make run-asm-tests
+    make run-bmark-tests
+
+
+.. Note:: Before running the pre-packaged suites, you must run the plain ``make`` command, since the elaboration command generates a Makefile fragment that contains the target for the pre-packaged test suites. Otherwise, you will likely encounter a Makefile target error.
+
+
+.. _sw-sim-custom:
+
+Simulating A Custom Project
+-------------------------------
+
+If you later create your own project, you can use environment variables to build an alternate configuration.
+
+In order to construct the simulator with our custom design, we run the following command within the simulator directory:
+
+.. code-block:: shell
+
+    make SBT_PROJECT=... MODEL=... VLOG_MODEL=... MODEL_PACKAGE=... CONFIG=... CONFIG_PACKAGE=... GENERATOR_PACKAGE=... TB=... TOP=...
+
+Each of these make variables correspond to a particular part of the design/codebase and are needed so that the make system can correctly build and make a RTL simulation.
+
+The ``SBT_PROJECT`` is the ``build.sbt`` project that holds all of the source files and that will be run during the RTL build.
+
+The ``MODEL`` and ``VLOG_MODEL`` are the top-level class names of the design. Normally, these are the same, but in some cases these can differ (if the Chisel class differs than what is emitted in the Verilog).
+
+The ``MODEL_PACKAGE`` is the Scala package (in the Scala code that says ``package ...``) that holds the ``MODEL`` class.
+
+The ``CONFIG`` is the name of the class used for the parameter Config while the ``CONFIG_PACKAGE`` is the Scala package it resides in.
+
+The ``GENERATOR_PACKAGE`` is the Scala package that holds the Generator class that elaborates the design.
+
+The ``TB`` is the name of the Verilog wrapper that connects the ``TestHarness`` to VCS/Verilator for simulation.
+
+Finally, the ``TOP`` variable is used to distinguish between the top-level of the design and the ``TestHarness`` in our system.
+For example, in the normal case, the ``MODEL`` variable specifies the ``TestHarness`` as the top-level of the design.
+However, the true top-level design, the SoC being simulated, is pointed to by the ``TOP`` variable.
+This separation allows the infrastructure to separate files based on the harness or the SoC top level.
+
+Common configurations of all these variables are packaged using a ``SUB_PROJECT`` make variable.
+Therefore, in order to simulate a simple Rocket-based example system we can use:
+
+
+.. code-block:: shell
+
+    make SUB_PROJECT=yourproject
+    ./simulator-<yourproject>-<yourconfig> ...
+
+
+All `Make` targets that can be applied to the default example, can also be applied to custom project using the custom environment variables. For example, the following code example will run the RISC-V assembly benchmark suite on the Hwacha subproject:
+
+.. code-block:: shell
+
+    make SUB_PROJECT=hwacha run-asm-tests
+
+
+Finally, in the ``generated-src/<...>-<package>-<config>/`` directory resides all of the collateral and Verilog source files for the build/simulation.
+Specifically, the SoC top-level (``TOP``) Verilog file is denoted with ``*.top.v`` while the ``TestHarness`` file is denoted with ``*.harness.v``.
+
+
+Generating Waveforms
+-----------------------
+
+If you would like to extract waveforms from the simulation, run the command ``make debug`` instead of just ``make``.
+
+
+For a Verilator simulation, 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/>`__.
+
+
+For a VCS simulation, this will generate a vpd file (this is a proprietary waveform representation format used by Synopsys) that can be loaded to vpd-supported waveform viewers.
+If you have Synopsys licenses, we recommend using the DVE waveform viewer.
+

docs/Simulation/Software-RTL-Simulators.rst

@@ -1,75 +0,0 @@
-.. _sw-rtl-sim-intro:
-
-Software RTL Simulators
-===================================
-
-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/verilator`` directory.
-This will elaborate the ``RocketConfig`` in the example project.
-
-An executable called ``simulator-example-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.
-For instance, to run one of the riscv-tools assembly tests.
-
-.. code-block:: shell
-
-    ./simulator-example-RocketConfig $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.
-VCS simulation will generally compile faster than Verilator simulations.
-
-To run a simulation using VCS, perform the following steps:
-
-Make sure that the VCS simulator is on your ``PATH``.
-
-To compile the example design, run make in the ``sims/vcs`` directory.
-This will elaborate the ``RocketConfig`` in the example project.
-
-An executable called ``simulator-example-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.
-For instance, to run one of the riscv-tools assembly tests.
-
-.. code-block:: shell
-
-    ./simulator-example-RocketConfig $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 vpd file (this is a proprietary waveform representation format used by Synopsys) that can be loaded to vpd-supported waveform viewers.
-If you have Synopsys licenses, we recommend using the DVE waveform viewer.
-
-Please refer to :ref:`Running A Simulation` for a step by step tutorial on how to get a simulator up and running.

docs/Simulation/index.rst

@@ -1,4 +1,4 @@
-Simulators
+Simulation
 =======================
 
 Chipyard supports two classes of simulation:
@@ -12,9 +12,11 @@ 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.
 
+Click next to see how to run a simulation.
+
 .. toctree::
    :maxdepth: 2
-   :caption: Simulators:
+   :caption: Simulation:
 
-   Software-RTL-Simulators
+   Software-RTL-Simulation
    FPGA-Accelerated-Simulators

docs/Software/FireMarshal.rst

@@ -0,0 +1,23 @@
+FireMarshal
+=================
+
+FireMarshal is a workload generation tool for RISC-V based systems. It
+currently only supports the FireSim FPGA-accelerated simulation platform.
+
+**Workloads** in FireMarshal consist of a series of **Jobs** that are assigned
+to logical nodes in the target system. If no jobs are specified, then the
+workload is considered ``uniform`` and only a single image will be produced for
+all nodes in the system. Workloads are described by a ``json`` file and a
+corresponding workload directory and can inherit their definitions from
+existing workloads. Typically, workload configurations are kept in
+``workloads/`` although you can use any directory you like. We provide a few
+basic workloads to start with including buildroot or Fedora-based linux
+distributions and bare-metal.
+
+Once you define a workload, the ``marshal`` command will produce a
+corresponding boot-binary and rootfs for each job in the workload. This binary
+and rootfs can then be launched on qemu or spike (for functional simulation), or
+installed to a platform for running on real RTL (currently only FireSim is
+automated).
+
+To get started, checkout the full `FireMarshal documentation <https://firemarshal.readthedocs.io/en/latest/index.html>`_.

docs/Software/Spike.rst

@@ -0,0 +1,4 @@
+The RISC-V ISA Simulator (Spike)
+=================================
+
+.. attention:: This article is a stub. Fill it out!

docs/Software/index.rst

@@ -0,0 +1,21 @@
+Target Software
+==================================
+
+Chipyard includes tools for developing target software workloads. The primary
+tool is FireMarshal, which manages workload descriptions and generates binaries
+and disk images to run on your target designs. Workloads can be bare-metal, or
+be based on standard Linux distributions. Users can customize every part of the
+build process, including providing custom kernels (if needed by the hardware).
+
+FireMarshal can also run your workloads on high-performance functional
+simulators like Spike and Qemu. Spike is easily customized and serves as the
+official RISC-V ISA reference implementation. Qemu is a high-performance
+functional simulator that can run nearly as fast as native code, but can be
+challenging to modify.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   FireMarshal
+   Spike

docs/Tools/Treadle.rst

@@ -1,5 +1,9 @@
-Treadle
+Treadle and FIRRTL Interpreter
 ==============================
 
-`Treadle <https://github.com/freechipsproject/treadle>`__ is a circuit simulator that directly executes FIRRTL.
-It is especially useful for interactive debugging and small unit tests that benefit from a low-overhead simulator.
+`Treadle <https://github.com/freechipsproject/treadle>`__ and
+`FIRRTL Interpreter <https://github.com/freechipsproject/firrtl-interpreter>`__
+are circuit simulators that directly execute FIRRTL (specifically low-firrtl IR).
+Treadle is the replacement for FIRRTL Interpreter but FIRRTL Interpreter is still used within some
+projects. Treadle is useful for simulating modules in a larger SoC design. Many projects
+use Treadle for interactive debugging and a low-overhead simulator.

docs/VLSI/index.rst

@@ -8,4 +8,5 @@ In particular, we aim to support the HAMMER physical design generator flow.
    :maxdepth: 2
    :caption: VLSI Flow:
 
+   Building-A-Chip
    HAMMER

docs/index.rst

@@ -38,6 +38,8 @@ Table of Contents
 
    Customization/index
 
+   Software/index
+
    Advanced-Usage/index
 
    TileLink-Diplomacy-Reference/index

generators/example/src/main/scala/BoomConfigs.scala

@@ -48,12 +48,12 @@ class DualSmallBoomConfig extends Config(
   new boom.common.WithNBoomCores(2) ++                      // dual-core
   new freechips.rocketchip.system.BaseConfig)
 
-class SmallRV32UnifiedBoomConfig extends Config(
+class SmallRV32BoomConfig extends Config(
   new WithTop ++
   new WithBootROM ++
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
-  new boom.common.WithoutBoomFPU ++                       // no floating point
-  new boom.common.WithUnifiedMemIntIQs ++                 // use unified mem+int issue queues
+  new boom.common.WithoutBoomFPU ++                        // no fp
+  new boom.common.WithBoomRV32 ++                          // rv32 (32bit)
   new boom.common.WithSmallBooms ++
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.system.BaseConfig)

generators/example/src/main/scala/ConfigMixins.scala

@@ -37,6 +37,7 @@ class WithBootROM extends Config((site, here, up) => {
     contentFileName = s"./bootrom/bootrom.rv${site(XLen)}.img")
 })
 
+// DOC include start: WithGPIO
 /**
  * Class to add in GPIO
  */
@@ -44,6 +45,7 @@ class WithGPIO extends Config((site, here, up) => {
   case PeripheryGPIOKey => List(
     GPIOParams(address = 0x10012000, width = 4, includeIOF = false))
 })
+// DOC include end: WithGPIO
 
 // -----------------------------------------------
 // BOOM and/or Rocket Top Level System Parameter Mixins
@@ -107,6 +109,7 @@ class WithSimBlockDeviceTop extends Config((site, here, up) => {
   }
 })
 
+// DOC include start: WithGPIOTop
 /**
  * Class to specify a top level BOOM and/or Rocket system with GPIO
  */
@@ -121,6 +124,7 @@ class WithGPIOTop extends Config((site, here, up) => {
     top
   }
 })
+// DOC include end: WithGPIOTop
 
 // ------------------
 // Multi-RoCC Support

generators/example/src/main/scala/HeteroConfigs.scala

@@ -28,6 +28,7 @@ class SmallBoomAndRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: BoomAndRocketWithHwacha
 class HwachaLargeBoomAndHwachaRocketConfig extends Config(
   new WithTop ++
   new WithBootROM ++
@@ -38,6 +39,7 @@ class HwachaLargeBoomAndHwachaRocketConfig extends Config(
   new boom.common.WithNBoomCores(1) ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: BoomAndRocketWithHwacha
 
 class RoccLargeBoomAndRoccRocketConfig extends Config(
   new WithTop ++
@@ -60,6 +62,7 @@ class DualLargeBoomAndRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: DualBoomAndRocketOneHwacha
 class DualLargeBoomAndHwachaRocketConfig extends Config(
   new WithTop ++
   new WithBootROM ++
@@ -71,6 +74,7 @@ class DualLargeBoomAndHwachaRocketConfig extends Config(
   new boom.common.WithNBoomCores(2) ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: DualBoomAndRocketOneHwacha
 
 class LargeBoomAndRV32RocketConfig extends Config(
   new WithTop ++
@@ -83,6 +87,7 @@ class LargeBoomAndRV32RocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: DualBoomAndRocket
 class DualLargeBoomAndDualRocketConfig extends Config(
   new WithTop ++
   new WithBootROM ++
@@ -92,3 +97,4 @@ class DualLargeBoomAndDualRocketConfig extends Config(
   new boom.common.WithNBoomCores(2) ++                   // 2 boom cores
   new freechips.rocketchip.subsystem.WithNBigCores(2) ++ // 2 rocket cores
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: DualBoomAndRocket

generators/example/src/main/scala/RocketConfigs.scala

@@ -31,6 +31,7 @@ class RoccRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: JtagRocket
 class jtagRocketConfig extends Config(
   new WithDTMTop ++                                        // use top with dtm
   new freechips.rocketchip.subsystem.WithJtagDTM ++        // add jtag/DTM module to coreplex
@@ -38,6 +39,7 @@ class jtagRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: JtagRocket
 
 // DOC include start: PWMRocketConfig
 class PWMRocketConfig extends Config(
@@ -48,7 +50,7 @@ class PWMRocketConfig extends Config(
   new freechips.rocketchip.system.BaseConfig)
 // DOC include end: PWMRocketConfig
 
-class PWMRAXI4ocketConfig extends Config(
+class PWMAXI4RocketConfig extends Config(
   new WithPWMAXI4Top ++                                    // use top with axi4-controlled PWM
   new WithBootROM ++
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
@@ -71,6 +73,7 @@ class BlockDeviceModelRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: GPIORocketConfig
 class GPIORocketConfig extends Config(
   new WithGPIO ++                                          // add GPIOs to the peripherybus
   new WithGPIOTop ++                                       // use top with GPIOs
@@ -78,6 +81,7 @@ class GPIORocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: GPIORocketConfig
 
 class DualCoreRocketConfig extends Config(
   new WithTop ++
@@ -102,6 +106,7 @@ class GB1MemoryRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: Sha3Rocket
 class Sha3RocketConfig extends Config(
   new WithTop ++
   new WithBootROM ++
@@ -109,6 +114,7 @@ class Sha3RocketConfig extends Config(
   new sha3.WithSha3Accel ++                                // add SHA3 rocc accelerator
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: Sha3Rocket
 
 // DOC include start: InitZeroRocketConfig
 class InitZeroRocketConfig extends Config(