[docs] update documentation [ci skip] (#393)

docs/Advanced-Concepts/Chip-Communication.rst

@@ -48,8 +48,8 @@ By default, Chipyard uses the Tethered Serial Interface (TSI) to communicate wit
 TSI protocol is an implementation of HTIF that is used to send commands to the
 RISC-V DUT. These TSI commands are simple R/W commands
 that are able to probe the DUT's memory space. During simulation, the host sends TSI commands to a
-simulation stub called ``SimSerial`` (C++ class) that resides in a ``SimSerial`` verilog module
-(both are located in the ``generators/testchipip`` project). This ``SimSerial`` verilog module then
+simulation stub called ``SimSerial`` (C++ class) that resides in a ``SimSerial`` Verilog module
+(both are located in the ``generators/testchipip`` project). This ``SimSerial`` Verilog module then
 sends the TSI command recieved by the simulation stub into the DUT which then converts the TSI
 command into a TileLink request. This conversion is done by the ``SerialAdapter`` module
 (located in the ``generators/testchipip`` project). In simulation, FESVR
@@ -60,11 +60,19 @@ mechanism to communicate with the DUT in simulation.
 In the case of a chip tapeout bringup, TSI commands can be sent over a custom communication
 medium to communicate with the chip. For example, some Berkeley tapeouts have a FPGA
 with a RISC-V soft-core that runs FESVR. The FESVR on the soft-core sends TSI commands
-to a TSI-to-TileLink converter living on the FPGA (i.e. ``SerialAdapter``). Then this converter
-sends the converted TileLink commands over a serial link to the chip. The following image shows this flow:
+to a TSI-to-TileLink converter living on the FPGA (i.e. ``SerialAdapter``). After the transaction is
+converted to TileLink, the ``TLSerdesser`` (located in ``generators/testchipip``) serializes the
+transaction and sends it to the chip (this ``TLSerdesser`` is sometimes also referred to as a
+serial-link or serdes). Once the serialized transaction is received on the
+chip, it is deserialized and masters a bus on the chip. The following image shows this flow:
 
 .. image:: ../_static/images/chip-bringup.png
 
+.. note::
+    The ``TLSerdesser`` can also be used as a slave (client), so it can sink memory requests from the chip
+    and connect to off-chip backing memory. Or in other words, ``TLSerdesser`` creates a bi-directional TileLink
+    interface.
+
 Using the Debug Module Interface (DMI)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -75,8 +83,8 @@ The DTM is given in the `RISC-V Debug Specification <https://riscv.org/specifica
 and is responsible for managing communication between the DUT and whatever lives on the other side of the DMI (in this case FESVR).
 This is implemented in the Rocket Chip ``Subsystem`` by having the ``HasPeripheryDebug`` and ``HasPeripheryDebugModuleImp`` mixins.
 During simulation, the host sends DMI commands to a
-simulation stub called ``SimDTM`` (C++ class) that resides in a ``SimDTM`` verilog module
-(both are located in the ``generators/rocket-chip`` project). This ``SimDTM`` verilog module then
+simulation stub called ``SimDTM`` (C++ class) that resides in a ``SimDTM`` Verilog module
+(both are located in the ``generators/rocket-chip`` project). This ``SimDTM`` Verilog module then
 sends the DMI command recieved by the simulation stub into the DUT which then converts the DMI
 command into a TileLink request. This conversion is done by the DTM named ``DebugModule`` in the ``generators/rocket-chip`` project.
 When the DTM receives the program to load, it starts to write the binary byte-wise into memory.
@@ -109,7 +117,7 @@ top-level system with the DTM (``TopWithDTM``), a test-harness to connect to the
     :start-after: DOC include start: DmiRocket
     :end-before: DOC include end: DmiRocket
 
-In this example, the ``WithDTMTop`` mixin specifies that the top-level SoC will instantiate a DTM (that by default is setup to use DMI).
+In this example, the ``WithDTM`` mixin specifies that the top-level SoC will instantiate a DTM (that by default is setup to use DMI).
 The rest of the mixins specify the rest of the system (cores, accelerators, etc).
 Then you can run simulations with the new DMI-enabled top-level and test-harness.
 
@@ -119,7 +127,7 @@ Then you can run simulations with the new DMI-enabled top-level and test-harness
     # or
     cd sims/vcs
 
-    make CONFIG=dmiRocketConfig TOP=TopWithDTM MODEL=TestHarnessWithDTM run-asm-tests
+    make CONFIG=dmiRocketConfig run-asm-tests
 
 Using the JTAG Interface
 ------------------------
@@ -132,8 +140,7 @@ Creating a DTM+JTAG Config
 
 First, a DTM config must be created for the system that you want to create.
 This step is similar to the DMI simulation section within the :ref:`Starting the TSI or DMI Simulation` section.
-First, you must make a top-level system (``TopWithDTM``) and test-harness (``TestHarnessWithDTM``) that instantiates
-and connects the DTM correctly. The configuration is very similar to a DMI-based configuration. The main difference
+The configuration is very similar to a DMI-based configuration. The main difference
 is the addition of the ``WithJtagDTM`` mixin that configures the instantiated DTM to use the JTAG protocol as the
 bringup method.
 
@@ -153,7 +160,7 @@ After creating the config, call the ``make`` command like the following to build
     # or
     cd sims/vcs
 
-    make CONFIG=jtagRocketConfig TOP=TopWithDTM MODEL=TestHarnessWithDTM
+    make CONFIG=jtagRocketConfig
 
 In this example, the simulation 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

docs/Advanced-Concepts/Debugging-RTL.rst

@@ -40,14 +40,18 @@ make variable to set additional simulator flags:
 
    make CONFIG=CustomConfig run-binary-debug BINARY=linux.riscv SIM_FLAGS=+vpdfilesize=1024
 
+.. note::
+    In some cases where there is multiple simulator flags, you can write the ``SIM_FLAGS``
+    like the following: ``SIM_FLAGS="+vpdfilesize=XYZ +some_other_flag=ABC"``.
+
 Print Output
 ---------------------------
 
 Both Rocket and BOOM can be configured with varying levels of print output.
-For information see the Rocket core source code, or the BOOM `documentation 
-<https://docs.boom-core.org/en/latest/>`__ .website. In addition, developers
-may insert arbitrary printfs at arbitrary conditions within the Chisel g
-enerators. See the Chisel documentation for information on this.
+For information see the Rocket core source code, or the BOOM `documentation
+<https://docs.boom-core.org/en/latest/>`__ website. In addition, developers
+may insert arbitrary printfs at arbitrary conditions within the Chisel generators.
+See the Chisel documentation for information on this.
 
 Once the cores have been configured with the desired print statements, the
 ``+verbose`` flag will cause the simulator to print the statements. The following
@@ -56,6 +60,7 @@ commands will all generate desired print statements:
 .. code-block:: shell
 
    make CONFIG=CustomConfig run-binary-debug BINARY=helloworld.riscv
+
    # The below command does the same thing
    ./simv-CustomConfig-debug +verbose helloworld.riscv
 

docs/Advanced-Concepts/Top-Testharness.rst

@@ -4,7 +4,7 @@ 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
+The ``TestDriver`` serves as our testbench, and is a Verilog
 file in Rocket Chip.
 
 
@@ -45,22 +45,13 @@ System
 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.
+A SoC Top then extends the ``System`` class with any config-specific components.
+In Chipyard, this includes things like adding a NIC, UART, and GPIO as well as setting up the hardware for the bringup method.
 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
@@ -70,21 +61,9 @@ 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`` 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.
+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.