Merge remote-tracking branch 'origin/dev' into abe-docs-dev

docs/Advanced-Usage/DTM-Debugging.rst

@@ -0,0 +1,50 @@
+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 
+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.
+
+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 WithDTMBoomRocketTop ++
+      new WithBootROM ++
+      new WithJtagDTM ++
+      new boom.common.SmallBoomConfig)
+
+In this example, the ``WithDTMBoomRocketTop`` 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).
+The rest of the mixins specify the rest of the system (cores, accelerators, etc).
+
+Starting the DTM Simulation
+-------------------------------------------
+
+After creating the config, call the ``make`` command like the following:
+
+.. code-block:: bash
+
+    cd sims/verilator
+    # or
+    cd sims/vcs
+
+    make CONFIG=DTMBoomConfig TOP=BoomRocketTopWithDTM MODEL=TestHarnessWithDTM
+
+In this example, this will use the config that you previously specified, as well as set the other parameters that are needed to satisfy the build system.
+After that point, you should have a JTAG enabled simulation that you can attach to using OpenOCD and GDB!
+
+Debugging with JTAG
+-------------------------------------------------------
+
+Please refer to the following resources on how to debug with JTAG.
+
+* https://github.com/chipsalliance/rocket-chip#-debugging-with-gdb
+* https://github.com/riscv/riscv-isa-sim#debugging-with-gdb

docs/Advanced-Usage/Resources.rst

@@ -0,0 +1,38 @@
+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 ``setResource`` or ``addResource`` functions given by FIRRTL.
+They can be used in the following way:
+
+.. code-block:: scala
+
+    class SimSerial(w: Int) extends BlackBox with HasBlackBoxResource {
+      val io = IO(new Bundle {
+        val clock = Input(Clock())
+        val reset = Input(Bool())
+        val serial = Flipped(new SerialIO(w))
+        val exit = Output(Bool())
+      })
+
+      setResource("/testchipip/vsrc/SimSerial.v")
+      setResource("/testchipip/csrc/SimSerial.cc")
+    }
+
+In this example, the ``SimSerial`` files will be copied from a specific folder (in this case the ``path/to/testchipip/src/main/resources/testchipip/...``) to the build folder.
+The ``set/addResource`` path retrieves resources from the ``src/main/resources`` directory.
+So to get an item at ``src/main/resources/fileA.v`` you can use ``setResource("/fileA.v")``.
+However, one caveat of this approach is that to retrieve the file during the FIRRTL compile, you must have that project in the FIRRTL compiler's classpath.
+Thus, you need to add the SBT project as a dependency to the FIRRTL compiler in the Chipyard ``build.sbt``, which in Chipyards case is the ``tapeout`` project.
+For example, you added a new project called ``myAwesomeAccel`` in the Chipyard ``build.sbt``.
+Then you can add it as a ``dependsOn`` dependency to the ``tapeout`` project.
+For example:
+
+.. code-block:: scala
+
+    lazy val myAwesomeAccel = (project in file("generators/myAwesomeAccelFolder"))
+      .dependsOn(rocketchip)
+      .settings(commonSettings)
+
+    lazy val tapeout = conditionalDependsOn(project in file("./tools/barstools/tapeout/"))
+      .dependsOn(myAwesomeAccel)
+      .settings(commonSettings)

docs/Advanced-Usage/index.rst

@@ -4,3 +4,9 @@ Advanced Usage
 The following sections are advanced topics about how to use Chipyard and special features of the framework.
 They expect you to know about Chisel, Parameters, Configs, etc.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced Usage:
+
+   DTM-Debugging
+   Resources

docs/Chipyard-Basics/Building-A-Chip.rst

@@ -1,3 +1,5 @@
+.. _build-a-chip:
+
 Building A Chip
 ==============================
 TODO

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -1,3 +1,5 @@
+.. _chipyard-components:
+
 Chipyard Components
 ===============================
 

docs/Customization/Adding-An-Accelerator.rst

@@ -1,3 +1,5 @@
+.. _adding-an-accelerator:
+
 Adding An Accelerator/Device
 ===============================
 
@@ -63,9 +65,9 @@ Finally, add ``yourproject`` to the ``PACKAGES`` variable in the ``common.mk`` f
 This will allow make to detect that your source files have changed when building the Verilog/FIRRTL files.
 
 .. code-block:: shell
-   
+
      PACKAGES=$(addprefix generators/, rocket-chip testchipip boom hwacha sifive-blocks sifive-cache example yourproject) \
-		 $(addprefix sims/firesim/sim/, . firesim-lib midas midas/targetutils) 
+		 $(addprefix sims/firesim/sim/, . firesim-lib midas midas/targetutils)
 
 
 MMIO Peripheral

docs/Quick-Start.rst

@@ -12,15 +12,14 @@ Start by fetching Chipyard's sources. Run:
     cd chipyard
     ./scripts/init-submodules-no-riscv-tools.sh
 
-This will have initialized submodules and installed the RISC-V tools and
-other dependencies.
+This will have initialized the git submodules.
 
 Installing the RISC-V Tools
 -------------------------------------------
 
 We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
 This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
-TO build the toolchains, you should run: 
+To build the toolchains, you should run:
 
 ::
 
@@ -34,10 +33,10 @@ 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 <>.
-- If you intend to build one of the vanilla Chipyard examples, go to <> and follow the instructions.
-- If you intend to add a new accelerator, go to <> and follow the instructions.
+- 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 full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.  
-- 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 full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
+- If you intend to run a VLSI flow using one of the vanilla Chipyard examples, go to <> and follow the instructions.

docs/index.rst

@@ -46,6 +46,13 @@ New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.
    :numbered:
    Customization/index
 
+   :maxdepth: 3
+   :caption: Advanced Usage:
+   :numbered:
+   Advanced-Usage/index
+
+
+
 Indices and tables
 ==================