renamed Advanced section | move Top-Testharness to Advanced [ci skip]

docs/Advanced-Concepts/Top-Testharness.rst

@@ -0,0 +1,90 @@
+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``.
+The Top and ``TestHarness`` are both emitted by Chisel generators.
+The ``TestDriver`` serves as our testbench, and is a verilog
+file in Rocket Chip.
+
+
+Top/DUT
+-------------------------
+
+The top-level module of a Rocket Chip SoC is composed via cake-pattern.
+Specifically, "Tops" extend a ``System``, which extends a ``Subsystem``, which extends a ``BaseSubsystem``.
+
+
+BaseSubsystem
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``BaseSubsystem`` is defined in ``generators/rocketchip/src/main/scala/subsystem/BaseSubsystem.scala``.
+Looking at the ``BaseSubsystem`` abstract class, we see that this class instantiates the top-level buses
+(frontbus, systembus, peripherybus, etc.), but does not specify a topology.
+We also see this class define several ``ElaborationArtefacts``, files emitted after Chisel elaboration
+(e.g. the device tree string, and the diplomacy graph visualization GraphML file).
+
+Subsystem
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Looking in `generators/utilities/src/main/scala/Subsystem.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/utilities/src/main/scala/Subsystem.scala>`__, we can see how Chipyard's ``Subsystem``
+extends the ``BaseSubsystem`` abstract class. ``Subsystem`` mixes in the ``HasBoomAndRocketTiles`` trait that
+defines and instantiates BOOM or Rocket tiles, depending on the parameters specified.
+We also connect some basic IOs for each tile here, specifically the hartids and the reset vector.
+
+System
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``generators/utilities/src/main/scala/System.scala`` completes the definition of the ``System``.
+
+- ``HasHierarchicalBusTopology`` is defined in Rocket Chip, and specifies connections between the top-level buses
+- ``HasAsyncExtInterrupts`` and ``HasExtInterruptsModuleImp`` adds IOs for external interrupts and wires them appropriately to tiles
+- ``CanHave...AXI4Port`` adds various Master and Slave AXI4 ports, adds TL-to-AXI4 converters, and connects them to the appropriate buses
+- ``HasPeripheryBootROM`` adds a BootROM device
+
+Tops
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A SoC Top then extends the ``System`` class with any config-specific components. There are two "classes" of Tops in Chipyard that enable different bringup methods.
+Please refer to :ref:`Communicating with the DUT` for more information on these bringup methods.
+
+- ``Top`` is the default setup. These top modules instantiate a serial module which interfaces with the ``TestHarness``. In addition, the Debug Transfer Module (DTM) is removed and replaced with a TSI-based bringup flow. All other example "Tops" (except the ``TopWithDTM``) extend this Top as the "base" top-level system.
+- ``TopWithDTM`` does not include the TSI-based bringup flow. Instead it keeps the Debug Transfer Module (DTM) within the design so that you can use a DMI-based or JTAG-based bringup.
+
+For a custom Top a mixed-in trait adds the additional modules or IOs (an example of this is ``TopWithGPIO``).
+
+TestHarness
+-------------------------
+
+There are two variants of ``TestHarness`` generators in Chipyard, both located in
+`generators/example/src/main/scala/TestHarness.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/example/src/main/scala/TestHarness.scala>`__.
+One is designed for TSI-based bringup, while the other performs DTM-based bringup.
+See :ref:`Communicating with the DUT` for more information on these two methodologies.
+
+The wiring between the ``TestHarness`` and the Top are performed in methods defined in mixins added to the Top.
+When these methods are called from the ``TestHarness``, they may instantiate modules within the scope of the harness,
+and then connect them to the DUT. For example, the ``connectSimAXIMem`` method defined in the
+``CanHaveMasterAXI4MemPortModuleImp`` trait, when called from the ``TestHarness``, will instantiate ``SimAXIMem``s
+and connect them to the correct IOs of the top.
+
+While this roundabout way of attaching to the IOs of the top may seem to be unnecessarily complex, it allows the designer to compose
+custom traits together without having to worry about the details of the implementation of any particular trait.
+
+Specifying a Top
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To see why the Top connection method is useful, consider the case where we want to use a custom Top with additional GPIO pins.
+In `generators/example/src/main/scala/Top.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/example/src/main/scala/Top.scala>`__,
+we can see how the ``TopWithGPIO`` class adds the ``HasPeripheryGPIO`` trait. This trait adds IOs to the Top module,
+instantiates a TileLink GPIO node, and connects it to the proper buses.
+
+If we look at the ``WithGPIOTop`` mixin in the ``ConfigMixins.scala`` file, we see that adding this mixin to the top-level Config overrides the
+``BuildTop`` key with a custom function that both instantiates the custom Top, and drives all the GPIO pins.
+When the ``TestHarness`` looksup the ``BuildTop`` key, this function will run and perform this wiring, and then return the Top module.
+
+TestDriver
+-------------------------
+
+The ``TestDriver`` is defined in ``generators/rocketchip/src/main/resources/vsrc/TestDriver.v``.
+This verilog file executes a simulation by instantiating the ``TestHarness``, driving the clock and reset signals, and interpreting the success output.
+This file is compiled with the generated verilog for the ``TestHarness`` and the Top to produce a simulator.

docs/Advanced-Concepts/index.rst

@@ -0,0 +1,13 @@
+Advanced Concepts
+================================
+
+The following sections are advanced topics about how to Chipyard works, 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 Concepts:
+
+   Top-Testharness
+   Chip-Communication
+   Resources

docs/Advanced-Usage/index.rst

@@ -1,12 +0,0 @@
-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:
-
-   Chip-Communication
-   Resources

docs/Chipyard-Basics/Top-Testharness.rst

@@ -1,65 +0,0 @@
-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``.
-The Top and ``TestHarness`` are both emitted by Chisel generators.
-The ``TestDriver`` serves as our testbench, and is a verilog
-file in Rocket Chip.
-
-
-Top/DUT
--------------------------
-The top-level module of a Rocket Chip SoC is composed via cake-pattern. Specifically, "Tops" extend a ``System``, which extends a ``Subsystem``, which extends a ``BaseSubsystem``
-
-
-BaseSubsystem
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``BaseSubsystem`` is defined in ``generators/rocketchip/src/main/scala/subsystem/BaseSubsystem.scala``. Looking at the ``BaseSubsystem`` abstract class, we see that this class instantiates the top-level buses (frontbus, systembus, peripherybus, etc.), but does not specify a topology. We also see this class define several ``ElaborationArtefacts``, files emitted after Chisel elaboration (e.g. the device tree string, and the diplomacy GraphML).
-
-Subsystem
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard's ``Subsystem`` extends the ``BaseSubsystem`` abstract class. ``Subsystem`` mixes in the ``HasBoomAndRocketTiles`` trait that defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect some basic IOs for each tile here, specifically the hartids and the reset vector.
-
-System
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``generators/utilities/src/main/scala/System.scala`` completes the definition of the ``System``.
-
-- ``HasHierarchicalBusTopology`` is defined in Rocket Chip, and specifies connections between the top-level buses
-- ``HasAsyncExtInterrupts`` and ``HasExtInterruptsModuleImp`` adds IOs for external interrupts and wires them appropriately to tiles
-- ``CanHave...AXI4Port`` adds various Master and Slave AXI4 ports, adds TL-to-AXI4 converters, and connects them to the appropriate buses
-- ``HasPeripheryBootROM`` adds a BootROM device
-
-Tops
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A SoC Top then extends the ``System`` class with any config-specific components. There are two "classes" of Tops in Chipyard.
-
-- ``Top`` is the default setup. These top modules instantiate a serial module which interfaces with the ``TestHarness``. In addition, the debug module interface is tied off. All other example "Tops" (except the ``TopWithDTM``) extend this Top as the "base" top-level system.
-- ``TopWithDTM`` does not include the serial module, and the debug module interface (DMI) is left available. This Top is used for DTM-based bringup.
-
-For a custom Top a mixed-in trait adds the additional modules or IOs (an example of this is ``TopWithGPIO``).
-
-
-TestHarness
--------------------------
-
-There are two variants of ``TestHarness`` generators in Chipyard, both located in `generators/example/src/main/scala/TestHarness.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/example/src/main/scala/TestHarness.scala>`__ . One is designed for TSI-based bringup, while the other performs DTM-based bringup. See TODO for more information on these two methodologies.
-
-The wiring between the ``TestHarness`` and the Top are performed in methods defined in mixins added to the Top. When these methods are called from the TestHarness, they may instantiate modules within the scope of the harness, and then connect them to the dut. For example, the ``connectSimAXIMem`` method defined in the ``CanHaveMasterAXI4MemPortModuleImp`` trait, when called from the TestHarness, will instantiate SimAXIMems and connect them to the correct IOs of the top.
-
-While this roundabout way of attaching to the IOs of the top may seem to be unnecessarily complex, it allows the designer to compose custom traits together without having to worry about the details of the implementation of any particular trait.
-
-Specifying a Top
-^^^^^^^^^^^^^^^^^^^^^^^^^
-To see why the Top connection method is useful, consider the case where we want to use a custom Top with additional GPIO pins. In `generators/example/src/main/scala/Top.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/example/src/main/scala/Top.scala>`__ , we can see how the ``TopWithGPIO`` class adds the ``HasPeripheryGPIO`` trait. This trait adds IOs to the Top module, instantiates a TileLink GPIO node, and connects it to the proper buses.
-
-If we look at the ``WithGPIOTop`` mixin in the ``ConfigMixins.scala`` file, we see that adding this mixin to the top-level Config overrides the ``BuildTop`` key with a custom function that both instantiates the custom Top, and drives all the GPIO pins. When the ``TestHarness`` looksup the ``BuildTop`` key, this function will run and perform this wiring, and then return the Top module.
-
-TestDriver
--------------------------
-
-The ``TestDriver`` is defined in ``generators/rocketchip/src/main/resources/vsrc/TestDriver.v``. This verilog file executes a simulation by instantiating the ``TestHarness``, driving the clock and reset signals, and interpreting the success output. This file is compiled with the generated verilog for the ``TestHarness`` and the Top to produce a simulator.

docs/Chipyard-Basics/index.rst

@@ -9,8 +9,6 @@ These guides will walk you through the basics of the Chipyard framework:
 
 - Then, we will go over initial framework setup.
 
-- Finally, we will briefly walk through what you can do with the Chipyard tools.
-
 Hit next to get started!
 
 .. toctree::
@@ -20,4 +18,3 @@ Hit next to get started!
    Chipyard-Components
    Configs-Parameters-Mixins
    Initial-Repo-Setup
-   Top-Testharness

docs/index.rst

@@ -40,7 +40,7 @@ Table of Contents
 
    Software/index
 
-   Advanced-Usage/index
+   Advanced-Concepts/index
 
    TileLink-Diplomacy-Reference/index