Merge pull request #268 from ucb-bar/alon-docs-dev

Docs Cleanup

README.md

@@ -1,3 +1,5 @@
+![CHIPYARD](https://raw.githubusercontent.com/ucb-bar/chipyard/dev/docs/_static/images/chipyard_logo.svg?sanitize=true)
+
 # 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

docs/Advanced-Concepts/Chip-Communication.rst

@@ -74,7 +74,7 @@ In order to communicate with the DUT with the DMI protocol, the DUT needs to con
 The DTM is given in the `RISC-V Debug Specification <https://riscv.org/specifications/debug-specification/>`__
 and is responsible for managing communication between the DUT and whatever lives on the other side of the DMI (in this case FESVR).
 This is implemented in the Rocket Chip ``Subsystem`` by having the ``HasPeripheryDebug`` and ``HasPeripheryDebugModuleImp`` mixins.
- During simulation, the host sends DMI commands to a
+During simulation, the host sends DMI commands to a
 simulation stub called ``SimDTM`` (C++ class) that resides in a ``SimDTM`` verilog module
 (both are located in the ``generators/rocket-chip`` project). This ``SimDTM`` verilog module then
 sends the DMI command recieved by the simulation stub into the DUT which then converts the DMI

docs/Advanced-Concepts/Top-Testharness.rst

@@ -1,5 +1,5 @@
 Tops, Test-Harnesses, and the Test-Driver
-====================================
+===========================================
 
 The three highest levels of hierarchy in a Chipyard
 SoC are the Top (DUT), ``TestHarness``, and the ``TestDriver``.

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -29,6 +29,13 @@ Accelerators
   Hwacha integrates with a Rocket or BOOM core using the RoCC (Rocket Custom Co-processor) interface.
   See :ref:`Hwacha` for more information.
 
+.. Fixed Function Accelerators:
+   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   TBD
+**SHA3**
+  A fixed-function accelerator for the SHA3 hash function. This simple accelerator is used as a demonstration for some of the
+  Chipyard integration flows using the RoCC interface.
+
 System Components:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -45,9 +52,6 @@ System Components:
 **testchipip**
   A collection of utilities used for testing chips and interfacing them with larger test environments.
 
-.. Fixed Function Accelerators:
-   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-   TBD
 
 Tools
 -------------------------------------------
@@ -68,6 +72,9 @@ Tools
   A collection of common FIRRTL transformations used to manipulate a digital circuit without changing the generator source RTL.
   See :ref:`Barstools` for more information.
 
+**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).
+
 Toolchains
 -------------------------------------------
 
@@ -81,6 +88,13 @@ Toolchains
   A fork of riscv-tools, designed to work with the Hwacha non-standard RISC-V extension.
   This fork can also be used as an example demonstrating how to add additional RoCC accelerators to the ISA-level simulation (Spike) and the higher-level software toolchain (GNU binutils, riscv-opcodes, etc.)
 
+Software
+-------------------------------------------
+
+**FireMarshal**
+  FireMarshal is the default workload generation tool that Chipyard uses to create software to run on its platforms.
+  See :ref:`fire-marshal` for more information.
+
 Sims
 -------------------------------------------
 
@@ -105,9 +119,9 @@ Sims
 VLSI
 -------------------------------------------
 
-**HAMMER**
-  HAMMER is a VLSI flow designed to provide a layer of abstraction between general physical design concepts to vendor-specific EDA tool commands.
+**Hammer**
+  Hammer is a VLSI flow designed to provide a layer of abstraction between general physical design concepts to vendor-specific EDA tool commands.
   The HAMMER flow provide automated scripts which generate relevant tool commands based on a higher level description of physical design constraints.
-  The HAMMER flow also allows for re-use of process technology knowledge by enabling the construction of process-technology-specific plug-ins, which describe particular constraints relating to that process technology (obsolete standard cells, metal layer routing constraints, etc.).
-  The HAMMER flow requires access to proprietary EDA tools and process technology libraries.
+  The Hammer flow also allows for re-use of process technology knowledge by enabling the construction of process-technology-specific plug-ins, which describe particular constraints relating to that process technology (obsolete standard cells, metal layer routing constraints, etc.).
+  The Hammer flow requires access to proprietary EDA tools and process technology libraries.
   See :ref:`Core HAMMER` for more information.

docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst

@@ -1,133 +0,0 @@
-SoC Generator Config Mix-ins:
-==============================
-
-Rocket Chip
------------------------
-
-+ System-on-Chip
-    - HasTiles
-    - HasClockDomainCrossing
-    - HasResetVectorWire
-    - HasNoiseMakerIO
-
-
-+ Basic Core
-    - HasRocketTiles
-    - HasRocketCoreParameters
-    - HasCoreIO
-
-
-+ Branch Prediction
-    - HasBtbParameters
-
-
-+ Additional Compute
-    - HasFPUCtrlSigs
-    - HasFPUParameters
-    - HasLazyRoCC
-    - HasFpuOpt
-
-
-+ Memory System
-    - HasRegMap
-    - HasCoreMemOp
-    - HasHellaCache
-    - HasL1ICacheParameters
-    - HasICacheFrontendModule
-    - HasAXI4ControlRegMap
-    - HasTLControlRegMap
-    - HasTLBusParams
-    - HasTLXbarPhy
-
-
-+ Interrupts
-    - HasInterruptSources
-    - HasExtInterrupts
-    - HasAsyncExtInterrupts
-    - HasSyncExtInterrupts
-
-
-+ Periphery
-    - HasPeripheryDebug
-    - HasPeripheryBootROM
-    - HasBuiltInDeviceParams
-
-
-BOOM
------------------------
-+ Basic Core
-    - HasBoomTiles
-    - HasBoomCoreParameters
-    - HasBoomCoreIO
-    - HasBoomUOP
-    - HasRegisterFileIO
-
-
-+ Branch Prediction
-    - HasGShareParameters
-    - HasBoomBTBParameters
-
-
-+ Memory System
-    - HasL1ICacheBankedParameters
-    - HasBoomICacheFrontend
-    - HasBoomHellaCache
-
-
-SiFive Blocks
------------------------
-
-+ Peripherals
-    - HasPeripheryGPIO
-    - HasPeripheryI2C
-    - HasPeripheryMockAON
-    - HasPeripheryPWM
-    - HasPeripherySPI
-    - HasSPIProtocol
-        - HasSPIEndian
-        - HasSPILength
-        - HasSPICSMode
-    - HasPeripherySPIFlash
-    - HasPeripheryUART
-
-
-testchipip
------------------------
-
-+ Peripherals
-    - HasPeripheryBlockDevice
-    - HasPeripherySerial
-    - HasNoDebug
-
-
-Icenet
------------------------
-
-+ Periphery Network Interface Controller
-    - HasPeripheryIceNIC
-
-
-AWL
------------------------
-
-+ IO
-    - HasEncoding8b10b
-    - HasTLBidirectionalPacketizer
-    - HasTLController
-    - HasGenericTransceiverSubsystem
-
-+ Debug/Testing
-    - HasBertDebug
-    - HasPatternMemDebug
-    - HasBitStufferDebug4Modes
-    - HasBitReversalDebug
-
-
-
-
-
-
-
-
-
-

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

@@ -103,7 +103,7 @@ implementation (ex. ``HasPeripherySerialModuleImp`` where ``Imp`` refers to impl
 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"
+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
@@ -118,10 +118,10 @@ 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).
+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
+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
@@ -129,12 +129,13 @@ contain the implementation for the module, and may instantiate
 other normal modules OR lazy modules (for nested Diplomacy
 graphs, for example).
 
- Mix-in
+
+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.
 The naming convention for an additive mix-in is ``Has<YourMixin>``.
-This is shown in the MySoC class where things such as ``HasPeripherySerial`` connect a RTL component to a bus and expose signals to the top-level.
+This is shown in the ``MySoC`` class where things such as ``HasPeripherySerial`` connect a RTL component to a bus and expose signals to the top-level.
 
 Additional References
 ---------------------------

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

@@ -5,8 +5,10 @@ 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.
+
+.. 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.
 
 Checking out the sources
 ------------------------
@@ -24,12 +26,12 @@ Building a Toolchain
 
 The `toolchains` directory contains toolchains that include a cross-compiler toolchain, frontend server, and proxy kernel, which you will need in order to compile code to RISC-V instructions and run them on your design.
 Currently there are two toolchains, one for normal RISC-V programs, and another for Hwacha (``esp-tools``).
-There are detailed instructions at https://github.com/riscv/riscv-tools to install the ``riscv-tools`` toolchain, however, the instructions are similar for the Hwacha ``esp-tools`` toolchain.
-But to get a basic installation, just the following steps are necessary.
+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.
 
 .. code-block:: shell
 
-    ./scripts/build-toolchains.sh riscv # for a normal risc-v toolchain
+    ./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain
 
     # OR
 
@@ -37,4 +39,4 @@ But to get a basic installation, just the following steps are necessary.
 
 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.
+These variables need to be set for the ``make`` system to work properly.

docs/Chipyard-Basics/index.rst

@@ -1,11 +1,11 @@
 Chipyard Basics
 ================================
 
-These guides will walk you through the basics of the Chipyard framework:
+These sections will walk you through the basics of the Chipyard framework:
 
 - First, we will go over the components of the framework.
 
-- Next, we will go over the different configurations available.
+- Next, we will go over how to understand how Chipyard configures its designs.
 
 - Then, we will go over initial framework setup.
 

docs/Generators/Rocket-Chip.rst

@@ -2,7 +2,7 @@ Rocket Chip
 ===========
 
 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.
+`SiFive <https://www.sifive.com>`__. Chipyard uses the Rocket Chip generator as the basis for producing a RISC-V SoC.
 
 `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

docs/Generators/SHA3.rst

@@ -68,7 +68,7 @@ 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
+``BuildRoCC`` key. The configuration mixin is defined in the SHA3
 generator. An example configuration highlighting the use of
 this mixin is shown here:
 

docs/Generators/index.rst

@@ -9,7 +9,7 @@ A standard RTL design is essentially just a single instance of a design coming f
 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.
+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.
 

docs/Quick-Start.rst

@@ -21,7 +21,7 @@ Start by fetching Chipyard's sources. Run:
     cd chipyard
     ./scripts/init-submodules-no-riscv-tools.sh
 
-This will have initialized the git submodules.
+This will initialize and checkout all of the necessary git submodules.
 
 Installing the RISC-V Tools
 -------------------------------------------
@@ -34,7 +34,7 @@ To build the toolchains, you should run:
 
     ./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 toolchains by adding the ``esp-tools`` argument to the script above.
+.. 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:
@@ -60,6 +60,6 @@ This depends on what you are planning to do with Chipyard.
 
 * 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 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.

docs/Simulation/FPGA-Accelerated-Simulation.rst

@@ -1,6 +1,6 @@
 .. _firesim-sim-intro:
 
-FPGA-Accelerated Simulators
+FPGA-Accelerated Simulation
 ==============================
 
 FireSim
@@ -17,7 +17,7 @@ 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:
+Next, initalize FireSim as a library in Chipyard by running:
 
 .. code-block:: shell
 
@@ -37,7 +37,7 @@ Finally, source the following environment at the root of the firesim directory:
     # (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`
+.. Note:: Every time you want to use FireSim with a fresh shell, you must source this ``sourceme-f1-manager.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
@@ -63,7 +63,7 @@ config looks as following:
     new DefaultRocketConfig
   )
 
-Then the equivalent FireChip config (in `generators/firechip/src/main/scala/TargetConfigs.scala`) based on `FireSimRocketChipConfig`
+Then the equivalent FireChip config (in ``generators/firechip/src/main/scala/TargetConfigs.scala``) based on ``FireSimRocketChipConfig``
 will look as follows:
 
 .. code-block:: scala

docs/Simulation/Running-A-Simulation.rst

@@ -1,108 +0,0 @@
-Running A Simulation
-========================================================
-
-Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements.
-In the majority of cases during a digital design development process, simple software RTL simulation is needed.
-When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution.
-
-Software RTL Simulation
-------------------------
-The Chipyard framework provides wrappers for two common software RTL simulators:
-the open-source Verilator simulator and the proprietary VCS simulator.
-For more information on either of these simulators, please refer to :ref:`Verilator (Open-Source)` or :ref:`Synopsys VCS (License Required)`.
-The following instructions assume at least one of these simulators is installed.
-
-Verilator/VCS Flows
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Verilator is an open-source RTL simulator.
-We run Verilator simulations from within the ``sims/verilator`` directory which provides the necessary ``Makefile`` to both install and run Verilator simulations.
-On the other hand, VCS is a proprietary RTL simulator.
-We run VCS simulations from within the ``sims/vcs`` directory.
-Assuming VCS is already installed on the machine running simulations (and is found on our ``PATH``), then this guide is the same for both Verilator and VCS.
-
-First, we will start by entering the Verilator or VCS directory:
-
-.. code-block:: shell
-
-    # Enter Verilator directory
-    cd sims/verilator
-
-    # OR
-
-    # Enter VCS directory
-    cd sims/vcs
-
-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=example
-
-Once the simulator has been constructed, we would like to run RISC-V programs on it.
-In the simulation directory, we will find an executable file called ``<...>-<package>-<config>``.
-We run this executable with our target RISC-V program as a command line argument in one of two ways.
-One, we can directly call the simulator binary or use make to run the binary for us with extra simulation flags.
-For example:
-
-.. code-block:: shell
-
-    # directly calling the simulation binary
-    ./<...>-<package>-<config> my_program_binary
-
-    # using make to do it
-    make SUB_PROJECT=example BINARY=my_program_binary run-binary
-
-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 SUB_PROJECT=example run-asm-tests
-    make SUB_PROJECT=example run-bmark-tests
-
-Note: You need to specify all the make variables once again to match what the build gave to run the assembly tests or the benchmarks or the binaries if you are using the make option.
-
-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``.
-
-FPGA Accelerated Simulation
----------------------------
-FireSim enables simulations at 1000x-100000x the speed of standard software simulation.
-This is enabled using FPGA-acceleration on F1 instances of the AWS (Amazon Web Services) public cloud.
-Therefore FireSim simulation requires to be set-up on the AWS public cloud rather than on our local development machine.
-
-To run an FPGA-accelerated simulation using FireSim, a we need to clone the Chipyard repository (or our fork of the Chipyard repository) to an AWS EC2, and follow the setup instructions specified in the FireSim Initial Setup documentation page.
-
-After setting up the FireSim environment, we now need to generate a FireSim simulation around our selected digital design.
-We will work from within the ``sims/firesim`` directory.
-
-TODO: Continue from here
-

docs/Simulation/Software-RTL-Simulation.rst

@@ -58,7 +58,7 @@ For instance, to run one of the riscv-tools assembly tests.
 
     ./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``.
+.. 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:
@@ -69,7 +69,7 @@ For example:
     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.
+.. 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:
@@ -114,7 +114,7 @@ Therefore, in order to simulate a simple Rocket-based example system we can use:
     ./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:
+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
 
@@ -130,11 +130,9 @@ 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/index.rst

@@ -19,5 +19,5 @@ Click next to see how to run a simulation.
    :caption: Simulation:
 
    Software-RTL-Simulation
-   FPGA-Accelerated-Simulators
+   FPGA-Accelerated-Simulation
 

docs/Software/FireMarshal.rst

@@ -1,6 +1,6 @@
+.. _fire-marshal:
 FireMarshal
 =================
-``software/firemarshal``
 
 FireMarshal is a workload generation tool for RISC-V based systems. It
 currently only supports the FireSim FPGA-accelerated simulation platform.

docs/Tools/Barstools.rst

@@ -1,5 +1,5 @@
 Barstools
 ===============================
 
-Barstools is a collection of useful FIRRTL transformations and Compilers to help the build process.
+Barstools is a collection of useful FIRRTL transformations and compilers to help the build process.
 Included in the tools are a MacroCompiler (used to map Chisel memory constructs to vendor SRAMs), FIRRTL transforms (to separate harness and top-level SoC files), and more.

docs/Tools/Chisel-Testers.rst

@@ -1,6 +1,7 @@
 Chisel Testers
 ==============================
 
-`Chisel testers <https://github.com/freechipsproject/chisel-testers>`__ is a library for writing tests for Chisel designs.
+`Chisel Testers <https://github.com/freechipsproject/chisel-testers>`__ is a library for writing tests for Chisel designs.
 It provides a Scala API for interacting with a DUT.
-It can use multiple backends, including :ref:`Treadle` and Verilator.
+It can use multiple backends, including things such as Treadle and Verilator.
+See :ref:`Treadle and FIRRTL Interpreter` and :ref:`sw-rtl-sim-intro` for more information on these simulation methods.

docs/VLSI/Building-A-Chip.rst

@@ -3,4 +3,4 @@
 Building A Chip
 ==============================
 
-TODO
+.. Note:: Please refer to the other sections in VLSI for tools/flows on how to build a chip. This section will be filled in ASAP.

docs/VLSI/Hammer.rst

@@ -3,7 +3,7 @@
 Core Hammer
 ================================
 
-`Hammer <https://github.com/ucb-bar/hammer>`__ is a physical design generator that wraps around vendor specific technologies and tools to provide a single API to create ASICs.
+`Hammer <https://github.com/ucb-bar/hammer>`__ is a physical design flow which encourages reusability by partitioning physical design specifications into three distinct concerns: design, CAD tool, and process technology. Hammer wraps around vendor specific technologies and tools to provide a single API to address ASIC design concerns.
 Hammer allows for reusability in ASIC design while still providing the designers leeway to make their own modifications.
 
 For more information, read the `Hammer paper <https://people.eecs.berkeley.edu/~edwardw/pubs/hammer-woset-2018.pdf>`__ and see the `GitHub repository <https://github.com/ucb-bar/hammer>`__ and associated documentation.

docs/conf.py

@@ -97,6 +97,7 @@ html_theme = 'sphinx_rtd_theme'
 #
 html_theme_options = {
     'collapse_navigation': False,
+    'logo_only': True,
 #    'display_version': True,
 #    'navigation_depth': 4,
 }
@@ -121,6 +122,7 @@ html_sidebars = {
     ]
 }
 
+html_logo = '_static/images/chipyard-logo.png'
 
 # -- Options for HTMLHelp output ------------------------------------------
 

docs/index.rst

@@ -6,6 +6,8 @@
 Welcome to Chipyard's documentation!
 ====================================
 
+.. image:: ./_static/images/chipyard-logo.svg
+
 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.
 New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.

scripts/build-toolchains.sh

@@ -11,8 +11,8 @@ CHIPYARD_DIR="${CHIPYARD_DIR:-$(git rev-parse --show-toplevel)}"
 
 usage() {
     echo "usage: ${0} [riscv-tools | esp-tools | ec2fast]"
-    echo "   riscv: if set, builds the riscv toolchain (this is also the default)"
-    echo "   hwacha: if set, builds esp-tools toolchain"
+    echo "   riscv-tools: if set, builds the riscv toolchain (this is also the default)"
+    echo "   esp-tools: if set, builds esp-tools toolchain used for the hwacha vector accelerator"
     echo "   ec2fast: if set, pulls in a pre-compiled RISC-V toolchain for an EC2 manager instance"
     exit "$1"
 }