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