diff --git a/docs/Advanced-Usage/Chip-Communication.rst b/docs/Advanced-Concepts/Chip-Communication.rst similarity index 100% rename from docs/Advanced-Usage/Chip-Communication.rst rename to docs/Advanced-Concepts/Chip-Communication.rst diff --git a/docs/Advanced-Usage/Resources.rst b/docs/Advanced-Concepts/Resources.rst similarity index 100% rename from docs/Advanced-Usage/Resources.rst rename to docs/Advanced-Concepts/Resources.rst diff --git a/docs/Advanced-Concepts/Top-Testharness.rst b/docs/Advanced-Concepts/Top-Testharness.rst new file mode 100644 index 00000000..a0f7f775 --- /dev/null +++ b/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 `__, 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 `__. +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 `__, +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`` looks up the ``BuildTop`` key, this function will run and perform the specified 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. diff --git a/docs/Advanced-Concepts/index.rst b/docs/Advanced-Concepts/index.rst new file mode 100644 index 00000000..2994899c --- /dev/null +++ b/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 diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst deleted file mode 100644 index 4864ce7a..00000000 --- a/docs/Advanced-Usage/index.rst +++ /dev/null @@ -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 diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst index 3c05c864..5c97f0ac 100644 --- a/docs/Chipyard-Basics/index.rst +++ b/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:: diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 462c20e2..384838fc 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -24,5 +24,6 @@ so changes to the generators themselves will automatically be used when building Hwacha IceNet TestChipIP - SiFive-Generators + SiFive-Generators SHA3 + diff --git a/docs/index.rst b/docs/index.rst index 75c3714e..667f6ae2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,7 +40,7 @@ Table of Contents Software/index - Advanced-Usage/index + Advanced-Concepts/index TileLink-Diplomacy-Reference/index