From 72db3be0a504938829b2071d0989bd333d279874 Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Wed, 25 Sep 2019 15:03:36 -0700 Subject: [PATCH 1/8] [docs][ci skip] Top and Testharness info --- docs/Generators/Top-Testharness.rst | 61 +++++++++++++++++++++++++++++ docs/Generators/index.rst | 4 +- 2 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 docs/Generators/Top-Testharness.rst diff --git a/docs/Generators/Top-Testharness.rst b/docs/Generators/Top-Testharness.rst new file mode 100644 index 00000000..fd8f9690 --- /dev/null +++ b/docs/Generators/Top-Testharness.rst @@ -0,0 +1,61 @@ +Tops, TestHarnesses, and TestDriver +==================================== + +The three highest levels of hierarchy in a Chipyard +SoC are the Top, TestHarness, and the Testbench. The Top and TestHarness are both emitted by Chisel generators. + +Top/DUT +------------------------- +The top-level module of a Rocketchip 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", for example the device tree string, and the diplomacy GraphML. + +Subsystem +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the BaseSubsystem abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect 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 Rocketchip, 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" +- ``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, for example the ``TopWithGPIO``, a mixed-in trait adds the additional modules or IOs. + + +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 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 ``CanHaceMasterAXI4MemPortModuleImp`` 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 see 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 TileLikn 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. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 462c20e2..4e8f8669 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -24,5 +24,7 @@ so changes to the generators themselves will automatically be used when building Hwacha IceNet TestChipIP - SiFive-Generators + SiFive-Generators SHA3 + Top-Testharness + From 63e15f049290a8dc7d06d2dc69715263fe5b93b3 Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Wed, 25 Sep 2019 21:22:34 -0700 Subject: [PATCH 2/8] [docs][ci skip] Address comments --- docs/Generators/Top-Testharness.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/Generators/Top-Testharness.rst b/docs/Generators/Top-Testharness.rst index fd8f9690..39c09c7a 100644 --- a/docs/Generators/Top-Testharness.rst +++ b/docs/Generators/Top-Testharness.rst @@ -1,30 +1,34 @@ -Tops, TestHarnesses, and TestDriver +Tops, Test-Harnesses, and the Test-Driver ==================================== The three highest levels of hierarchy in a Chipyard -SoC are the Top, TestHarness, and the Testbench. The Top and TestHarness are both emitted by Chisel generators. +SoC are the Top, 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 n rocketchip. + Top/DUT ------------------------- -The top-level module of a Rocketchip SoC is composed via cake-pattern. Specifically, "Tops" extend a "System", which extends a "Subsystem", which extends a "BaseSubsystem" +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", for example the device tree string, and the diplomacy GraphML. +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``, for example the device tree string, and the diplomacy GraphML. Subsystem ^^^^^^^^^^^^^^^^^^^^^^^^^ -Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the BaseSubsystem abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect connect some basic IOs for each tile here, specifically the hartids and the reset_vector. +Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the ``BaseSubsystem`` abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect 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 Rocketchip, and specifies connections between the top-level buses. +- ``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 @@ -51,7 +55,7 @@ While this roundabout way of attaching to the IOs of the top may see unnecessari 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 TileLikn GPIO node, and connects it to the proper buses. +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 looksup the BuildTop key, this function will run and perform this wiring, and then return the Top module. From 1e84ab06c6804a7cdcc69a74b3f11dfcf5157496 Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Thu, 26 Sep 2019 17:49:10 -0700 Subject: [PATCH 3/8] [docs][ci skip] More formatting fixes --- docs/Generators/Top-Testharness.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/Generators/Top-Testharness.rst b/docs/Generators/Top-Testharness.rst index 39c09c7a..df6b1a10 100644 --- a/docs/Generators/Top-Testharness.rst +++ b/docs/Generators/Top-Testharness.rst @@ -2,10 +2,10 @@ Tops, Test-Harnesses, and the Test-Driver ==================================== The three highest levels of hierarchy in a Chipyard -SoC are the Top, 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 n rocketchip. +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 @@ -16,12 +16,12 @@ The top-level module of a Rocket Chip SoC is composed via cake-pattern. Specific 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``, for example the device tree string, and the diplomacy GraphML. +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``, for example the device tree string, and the diplomacy GraphML. Subsystem ^^^^^^^^^^^^^^^^^^^^^^^^^ -Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the ``BaseSubsystem`` abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect connect some basic IOs for each tile here, specifically the hartids and the reset_vector. +Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the ``BaseSubsystem`` abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect connect some basic IOs for each tile here, specifically the hartids and the reset vector. System ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -36,9 +36,9 @@ System Tops ^^^^^^^^^^^^^^^^^^^^^^^^^ -A SoC top then extends the System class with any config-specific components. There are two "classes" of Tops in Chipyard. +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`` 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" - ``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, for example the ``TopWithGPIO``, a mixed-in trait adds the additional modules or IOs. @@ -47,9 +47,9 @@ For a custom Top, for example the ``TopWithGPIO``, a mixed-in trait adds the add 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 TODO for more information on these two methodologies. +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 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 ``CanHaceMasterAXI4MemPortModuleImp`` trait, when called from the TestHarness, will instantiate SimAXIMems and connect them to the correct IOs of the top. +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 ``CanHaceMasterAXI4MemPortModuleImp`` 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 see 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. @@ -57,9 +57,9 @@ 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 looksup the BuildTop key, this function will run and perform this wiring, and then return the Top module. +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. +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. From 63a1315f33738013e7149d86ba5d5b4bd43c4d47 Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Thu, 26 Sep 2019 20:55:56 -0700 Subject: [PATCH 4/8] Update docs/Generators/Top-Testharness.rst Co-Authored-By: Abraham Gonzalez --- docs/Generators/Top-Testharness.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Generators/Top-Testharness.rst b/docs/Generators/Top-Testharness.rst index df6b1a10..8138a8a8 100644 --- a/docs/Generators/Top-Testharness.rst +++ b/docs/Generators/Top-Testharness.rst @@ -16,7 +16,7 @@ The top-level module of a Rocket Chip SoC is composed via cake-pattern. Specific 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``, for example the device tree string, and the diplomacy GraphML. +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 ^^^^^^^^^^^^^^^^^^^^^^^^^ From c2547bd04f5f8244174640c7224698b01fe1ce7f Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Thu, 26 Sep 2019 21:06:57 -0700 Subject: [PATCH 5/8] Apply suggestions from code review Co-Authored-By: Abraham Gonzalez --- docs/Generators/Top-Testharness.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/Generators/Top-Testharness.rst b/docs/Generators/Top-Testharness.rst index 8138a8a8..c70be98c 100644 --- a/docs/Generators/Top-Testharness.rst +++ b/docs/Generators/Top-Testharness.rst @@ -21,14 +21,14 @@ The ``BaseSubsystem`` is defined in ``generators/rocketchip/src/main/scala/subsy Subsystem ^^^^^^^^^^^^^^^^^^^^^^^^^ -Looking in ``generators/utilities/src/main/scala/Subsystem.scala``, we can see how Chipyard extends the ``BaseSubsystem`` abstract class. The ``HasBoomAndRocketTiles`` trait defines and instantiates BOOM or Rocket tiles, depending on the parameters specified. We also connect connect some basic IOs for each tile here, specifically the hartids and the reset vector. +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. +``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. +- ``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 @@ -38,24 +38,24 @@ 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`` 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, for example the ``TopWithGPIO``, a mixed-in trait adds the additional modules or IOs. +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 TODO for more information on these two methodologies. +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 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 ``CanHaceMasterAXI4MemPortModuleImp`` trait, when called from the TestHarness, will instantiate SimAXIMems and connect them to the correct IOs of the top. +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 see 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. +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. +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`` looksup the ``BuildTop`` key, this function will run and perform this wiring, and then return the Top module. From f71e65e1af19666d64154c4138a1403ba7a836c3 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Sat, 28 Sep 2019 13:48:43 -0700 Subject: [PATCH 6/8] move into chipyard basics [ci skip] --- docs/{Generators => Chipyard-Basics}/Top-Testharness.rst | 0 docs/Chipyard-Basics/index.rst | 1 + docs/Generators/index.rst | 1 - 3 files changed, 1 insertion(+), 1 deletion(-) rename docs/{Generators => Chipyard-Basics}/Top-Testharness.rst (100%) diff --git a/docs/Generators/Top-Testharness.rst b/docs/Chipyard-Basics/Top-Testharness.rst similarity index 100% rename from docs/Generators/Top-Testharness.rst rename to docs/Chipyard-Basics/Top-Testharness.rst diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst index 3c05c864..0025cbd9 100644 --- a/docs/Chipyard-Basics/index.rst +++ b/docs/Chipyard-Basics/index.rst @@ -20,3 +20,4 @@ Hit next to get started! Chipyard-Components Configs-Parameters-Mixins Initial-Repo-Setup + Top-Testharness diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 4e8f8669..384838fc 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -26,5 +26,4 @@ so changes to the generators themselves will automatically be used when building TestChipIP SiFive-Generators SHA3 - Top-Testharness From 5a825d77c4b948f5620b3f208f0213ad5213bc5e Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Sat, 28 Sep 2019 14:14:41 -0700 Subject: [PATCH 7/8] renamed Advanced section | move Top-Testharness to Advanced [ci skip] --- .../Chip-Communication.rst | 0 .../Resources.rst | 0 docs/Advanced-Concepts/Top-Testharness.rst | 90 +++++++++++++++++++ docs/Advanced-Concepts/index.rst | 13 +++ docs/Advanced-Usage/index.rst | 12 --- docs/Chipyard-Basics/Top-Testharness.rst | 65 -------------- docs/Chipyard-Basics/index.rst | 3 - docs/index.rst | 2 +- 8 files changed, 104 insertions(+), 81 deletions(-) rename docs/{Advanced-Usage => Advanced-Concepts}/Chip-Communication.rst (100%) rename docs/{Advanced-Usage => Advanced-Concepts}/Resources.rst (100%) create mode 100644 docs/Advanced-Concepts/Top-Testharness.rst create mode 100644 docs/Advanced-Concepts/index.rst delete mode 100644 docs/Advanced-Usage/index.rst delete mode 100644 docs/Chipyard-Basics/Top-Testharness.rst 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..c83e99c7 --- /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`` 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. 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/Top-Testharness.rst b/docs/Chipyard-Basics/Top-Testharness.rst deleted file mode 100644 index c70be98c..00000000 --- a/docs/Chipyard-Basics/Top-Testharness.rst +++ /dev/null @@ -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 `__ . 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 `__ , 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. diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst index 0025cbd9..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:: @@ -20,4 +18,3 @@ Hit next to get started! Chipyard-Components Configs-Parameters-Mixins Initial-Repo-Setup - Top-Testharness 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 From 4eca9abba25466f049e84acfef7040793a4298ce Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Sat, 28 Sep 2019 14:28:31 -0700 Subject: [PATCH 8/8] Update docs/Advanced-Concepts/Top-Testharness.rst [ci skip] Co-Authored-By: alonamid --- docs/Advanced-Concepts/Top-Testharness.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Advanced-Concepts/Top-Testharness.rst b/docs/Advanced-Concepts/Top-Testharness.rst index c83e99c7..a0f7f775 100644 --- a/docs/Advanced-Concepts/Top-Testharness.rst +++ b/docs/Advanced-Concepts/Top-Testharness.rst @@ -80,7 +80,7 @@ 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. +When the ``TestHarness`` looks up the ``BuildTop`` key, this function will run and perform the specified wiring, and then return the Top module. TestDriver -------------------------