[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.

docs/Customization/Boot-Process.rst

@@ -17,7 +17,7 @@ The BootROM address space starts at ``0x10000`` (determined by the ``BootROMPara
 The Chisel generator encodes the assembled instructions into the BootROM
 hardware at elaboration time, so if you want to change the BootROM code, you
 will need to run ``make`` in the bootrom directory and then regenerate the
-verilog. If you don't want to overwrite the existing ``bootrom.S``, you can
+Verilog. If you don't want to overwrite the existing ``bootrom.S``, you can
 also point the generator to a different bootrom image by overriding the
 ``BootROMParams`` key in the configuration.
 

docs/Customization/Heterogeneous-SoCs.rst

@@ -19,7 +19,7 @@ The following example shows a dual core BOOM with a single core Rocket.
     :end-before: DOC include end: DualBoomAndRocket
 
 In this example, the ``WithNBoomCores`` and ``WithNBigCores`` mixins set up the default parameters for the multiple BOOM and Rocket cores, respectively.
-However, for BOOM, an extra mixin called ``LargeBoomConfig`` is added to override the default parameters with a different set of more common default parameters.
+However, for BOOM, an extra mixin called ``WithLargeBooms`` is added to override the default parameters with a different set of more common default parameters.
 This mixin applies to all BOOM cores in the system and changes the parameters for each.
 
 Great! Now you have a heterogeneous setup with BOOMs and Rockets.
@@ -55,8 +55,12 @@ Then you could use this new mixin like the following.
 .. code-block:: scala
 
     class SixCoreConfig extends Config(
-      new WithTop ++
+      new WithTSI ++
+      new WithNoGPIO ++
       new WithBootROM ++
+      new WithUART ++
+      new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+      new freechips.rocketchip.subsystem.WithNoSlavePort ++
       new WithHeterCoresSetup ++
       new freechips.rocketchip.system.BaseConfig)
 

docs/Customization/Incorporating-Verilog-Blocks.rst

@@ -61,7 +61,7 @@ and Verilog sources follow the prescribed directory layout.
             resources/
                 vsrc/
                     GCDMMIOBlackBox.v
-      
+
 Defining a Chisel BlackBox
 --------------------------
 
@@ -78,11 +78,11 @@ Of particular interest is the fact that parameterized Verilog modules
 can be passed the full space of possible parameter values. These
 values may depend on elaboration-time values in the Chisel generator,
 as the bitwidth of the GCD calculation does in this example.
-  
+
 **Verilog GCD port list and parameters**
 
 .. literalinclude:: ../../generators/example/src/main/resources/vsrc/GCDMMIOBlackBox.v
-    :language: verilog
+    :language: Verilog
     :start-after: DOC include start: GCD portlist
     :end-before: DOC include end: GCD portlist
 
@@ -113,7 +113,7 @@ Defining a Chip with a BlackBox
 ---------------------------------------
 
 Since we've parameterized the GCD instantiation to choose between the
-Chisel and the verilog module, creating a config is easy.
+Chisel and the Verilog module, creating a config is easy.
 
 .. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
     :language: scala

docs/Customization/Keys-Traits-Configs.rst

@@ -21,7 +21,7 @@ Keys should be defined and documented in sub-projects, since they generally deal
     :start-after: DOC include start: GCD key
     :end-before: DOC include end: GCD key
 
-The object within a key is typically a ``case class XXXParams``, which defines a set of parameters which some block accepts. For example, the GCD widget's ``GCDParams`` parameterizes its address, operand widths, whether the widget should be connected by Tilelink or AXI4, and whether the widget should use the blackbox-verilog implementation, or the Chisel implementation.
+The object within a key is typically a ``case class XXXParams``, which defines a set of parameters which some block accepts. For example, the GCD widget's ``GCDParams`` parameterizes its address, operand widths, whether the widget should be connected by Tilelink or AXI4, and whether the widget should use the blackbox-Verilog implementation, or the Chisel implementation.
 
 
 .. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
@@ -95,7 +95,7 @@ For example, conside a config that contains the mixins ``WithGPIO ++ WithTSI``.
 When ``WithGPIO ++ WithTSI`` is evaluated right to left, the call to ``up(BuildTop, site)`` in ``WithGPIO`` will reference the function defined in the ``BuildTop`` key of ``WithTSI``. Thus, at elaboration time, when the ``BuildTop`` function is called by the ``TestHarness``, first the ``BuildTop`` function in ``WithTSI`` will be evaluated. This connects the ``success`` signal of the ``TestHarness`` to the ``SerialAdapter`` enabled by ``WithTSI``. Then, the rest of the code in the ``BuildTop`` function of ``WithGPIO`` will execute, tieing off the top-level GPIO input pins. Thus the evaluation of the ``BuildTop`` functions in a completed config is "right-to-left", matching how the evaluation of the mixins at compile-time is also "right-to-left".
 
 .. warning::
-   Note that in some cases, the ordering and duplication of mixins which extend ``BuildTop`` will have unintended consequences.
+   In some cases, the ordering and duplication of mixins which extend ``BuildTop`` will have unintended consequences.
    For example, ``WithTSI ++ WithTSI`` will attempt to generate and connect two ``SimSerial`` widgets in the ``TestHarness``,
    which will likely break the simulation.
    In general, you should avoid attaching multiple mixins which interface to the same top-level ports.

docs/Customization/MMIO-Peripherals.rst

@@ -127,7 +127,7 @@ Now we can test that the GCD is working. The test program is in ``tests/gcd.c``.
 
 This just writes out to the registers we defined earlier.
 The base of the module's MMIO region is at 0x2000 by default.
-This will be printed out in the address map portion when you generate the verilog code.
+This will be printed out in the address map portion when you generate the Verilog code.
 You can also see how this changes the emitted ``.json`` addressmap files in ``generated-src``.
 
 Compiling this program with ``make`` produces a ``gcd.riscv`` executable.