[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
+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
+(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
+to a TSI-to-TileLink converter living on the FPGA (i.e. ``SerialAdapter``). After the transaction is
-sends the converted TileLink commands over a serial link to the chip. The following image shows this flow:
+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
+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
+(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
+The configuration is very similar to a DMI-based configuration. The main difference
-and connects the DTM correctly. 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
+<https://docs.boom-core.org/en/latest/>`__ website. In addition, developers
-may insert arbitrary printfs at arbitrary conditions within the Chisel g
+may insert arbitrary printfs at arbitrary conditions within the Chisel generators.
-enerators. See the Chisel documentation for information on this.
+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 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 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

@@ -82,7 +82,7 @@ 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.

docs/Customization/Memory-Hierarchy.rst

@@ -15,18 +15,24 @@ configure 4 KiB direct-mapped caches for L1I and L1D.
 .. code-block:: scala
 
     class SmallRocketConfig extends Config(
-        new WithTop ++                                       // use default top
+        new WithTSI ++
-        new WithBootROM ++                                   // use default bootrom
+        new WithNoGPIO ++
-        new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
+        new WithBootROM ++
+        new WithUART ++
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ // small rocket cores
         new freechips.rocketchip.system.BaseConfig)
 
-    class SmallRocketConfig extends Config(
-        new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
-        new RocketConfig)
-
     class MediumRocketConfig extends Config(
-        new freechips.rocketchip.subsystem.WithNMedCores(1) ++
+        new WithTSI ++
-        new RocketConfig)
+        new WithNoGPIO ++
+        new WithBootROM ++
+        new WithUART ++
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new freechips.rocketchip.subsystem.WithNMedCores(1) ++ // medium rocket cores
+        new freechips.rocketchip.system.BaseConfig)
 
 If you only want to change the size or associativity, there are configuration
 mixins for those too.
@@ -36,11 +42,18 @@ mixins for those too.
     import freechips.rocketchip.subsystem.{WithL1ICacheSets, WithL1DCacheSets, WithL1ICacheWays, WithL1DCacheWays}
 
     class MyL1RocketConfig extends Config(
-        new WithL1ICacheSets(128) ++
+        new WithTSI ++
-        new WithL1ICacheWays(2) ++
+        new WithNoGPIO ++
-        new WithL1DCacheSets(128) ++
+        new WithBootROM ++
-        new WithL1DCacheWays(2) ++
+        new WithUART ++
-        new RocketConfig)
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new WithL1ICacheSets(128) ++                              // change rocket I$
+        new WithL1ICacheWays(2) ++                                // change rocket I$
+        new WithL1DCacheSets(128) ++                              // change rocket D$
+        new WithL1DCacheWays(2) ++                                // change rocket D$
+        new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
+        new freechips.rocketchip.system.BaseConfig)
 
 You can also configure the L1 data cache as an data scratchpad instead.
 However, there are some limitations on this. If you are using a data scratchpad,
@@ -50,8 +63,12 @@ Note that these configurations fully remove the L2 cache and mbus.
 .. code-block:: scala
 
     class SmallRocketConfigNoL2 extends Config(
-        new WithTop ++                              // use default top 
+        new WithTSI ++
-        new WithBootROM ++                          // use default bootrom 
+        new WithNoGPIO ++
+        new WithBootROM ++
+        new WithUART ++
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
         new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
         new freechips.rocketchip.system.BaseConfig)
 
@@ -79,13 +96,19 @@ and the number of banks must be powers of 2.
 
     import freechips.rocketchip.subsystem.WithInclusiveCache
 
-    # Create an SoC with 1 MB, 4-way, 4-bank cache
     class MyCacheRocketConfig extends Config(
-        new WithInclusiveCache(
+        new WithTSI ++
+        new WithNoGPIO ++
+        new WithBootROM ++
+        new WithUART ++
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new WithInclusiveCache(                                // add 1MB, 4-way, 4-bank cache
             capacityKB = 1024,
             nWays = 4,
             nBanks = 4) ++
-        new RocketConfig)
+        new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
+        new freechips.rocketchip.system.BaseConfig)
 
 The Broadcast Hub
 -----------------
@@ -99,13 +122,15 @@ list of included mixims.
 
 .. code-block:: scala
 
-    import freechips.rocketchip.subsystem.{WithNBigCores, BaseConfig}
-
     class CachelessRocketConfig extends Config(
-        new WithTop ++
+        new WithTSI ++
+        new WithNoGPIO ++
         new WithBootROM ++
-        new WithNBigCores(1) ++
+        new WithUART ++
-        new BaseConfig)
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+        new freechips.rocketchip.system.BaseConfig)
 
 If you want to reduce the resources used even further, you can configure
 the Broadcast Hub to use a bufferless design.
@@ -133,8 +158,15 @@ number of DRAM channels is restricted to powers of two.
     import freechips.rocketchip.subsystem.WithNMemoryChannels
 
     class DualChannelRocketConfig extends Config(
-        new WithNMemoryChannels(2) ++
+        new WithTSI ++
-        new RocketConfig)
+        new WithNoGPIO ++
+        new WithBootROM ++
+        new WithUART ++
+        new freechips.rocketchip.subsystem.WithNoMMIOPort ++
+        new freechips.rocketchip.subsystem.WithNoSlavePort ++
+        new WithNMemoryChannels(2) ++                          // multi-channel outer mem
+        new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+        new freechips.rocketchip.system.BaseConfig)
 
 In VCS and Verilator simulation, the DRAM is simulated using the
 ``SimAXIMem`` module, which simply attaches a single-cycle SRAM to each

docs/Customization/index.rst

@@ -17,7 +17,7 @@ These guides will walk you through customization of your system-on-chip:
 
 - Connect widgets which act as TileLink masters
 
-- Adding custom blackboxed verilog to a Chipyard design
+- Adding custom blackboxed Verilog to a Chipyard design
 
 We also provide information on:
 

docs/VLSI/Advanced-Usage.rst

@@ -5,11 +5,11 @@ Advanced Usage
 
 Alternative RTL Flows
 ---------------------
-The Make-based build system provided supports using Hammer without using RTL generated by Chipyard. To push a custom verilog module through, one only needs to append the following environment variables to the ``make buildfile`` command (or edit them directly in the Makefile).
+The Make-based build system provided supports using Hammer without using RTL generated by Chipyard. To push a custom Verilog module through, one only needs to append the following environment variables to the ``make buildfile`` command (or edit them directly in the Makefile).
 
 .. code-block:: shell
 
-    CUSTOM_VLOG=<your verilog files>
+    CUSTOM_VLOG=<your Verilog files>
     VLSI_TOP=<your top module>
 
 ``CUSTOM_VLOG`` breaks the dependency on the rest of the Chipyard infrastructure and does not start any Chisel/FIRRTL elaboration. ``VLSI_TOP`` selects the top module from your custom Verilog files.