From 1859054f73a91d53c9301bd8a2976b8d888b7056 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Thu, 23 Jan 2020 13:36:21 -0800 Subject: [PATCH] [docs] update documentation [ci skip] (#393) --- docs/Advanced-Concepts/Chip-Communication.rst | 29 +++-- docs/Advanced-Concepts/Debugging-RTL.rst | 13 ++- docs/Advanced-Concepts/Top-Testharness.rst | 31 +----- docs/Customization/Boot-Process.rst | 2 +- docs/Customization/Heterogeneous-SoCs.rst | 8 +- .../Incorporating-Verilog-Blocks.rst | 8 +- docs/Customization/Keys-Traits-Configs.rst | 4 +- docs/Customization/MMIO-Peripherals.rst | 2 +- docs/Customization/Memory-Hierarchy.rst | 102 ++++++++++++------ docs/Customization/index.rst | 2 +- docs/VLSI/Advanced-Usage.rst | 6 +- docs/_static/images/chip-bringup.png | Bin 18259 -> 18536 bytes 12 files changed, 117 insertions(+), 90 deletions(-) diff --git a/docs/Advanced-Concepts/Chip-Communication.rst b/docs/Advanced-Concepts/Chip-Communication.rst index 92efd17c..29979900 100644 --- a/docs/Advanced-Concepts/Chip-Communication.rst +++ b/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 `__ .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 +`__ 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 diff --git a/docs/Advanced-Concepts/Top-Testharness.rst b/docs/Advanced-Concepts/Top-Testharness.rst index 1256ea59..3d22e54a 100644 --- a/docs/Advanced-Concepts/Top-Testharness.rst +++ b/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 `__. -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 `__, -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. diff --git a/docs/Customization/Boot-Process.rst b/docs/Customization/Boot-Process.rst index d23fae85..b6b5e8a3 100644 --- a/docs/Customization/Boot-Process.rst +++ b/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. diff --git a/docs/Customization/Heterogeneous-SoCs.rst b/docs/Customization/Heterogeneous-SoCs.rst index 116d4ae9..e1d58c6a 100644 --- a/docs/Customization/Heterogeneous-SoCs.rst +++ b/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) diff --git a/docs/Customization/Incorporating-Verilog-Blocks.rst b/docs/Customization/Incorporating-Verilog-Blocks.rst index 48f0c6e3..fc1b8d7d 100644 --- a/docs/Customization/Incorporating-Verilog-Blocks.rst +++ b/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 diff --git a/docs/Customization/Keys-Traits-Configs.rst b/docs/Customization/Keys-Traits-Configs.rst index 8184975f..e7705f44 100644 --- a/docs/Customization/Keys-Traits-Configs.rst +++ b/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. diff --git a/docs/Customization/MMIO-Peripherals.rst b/docs/Customization/MMIO-Peripherals.rst index 0e01edb5..23fddca4 100644 --- a/docs/Customization/MMIO-Peripherals.rst +++ b/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. diff --git a/docs/Customization/Memory-Hierarchy.rst b/docs/Customization/Memory-Hierarchy.rst index 65724483..6266e435 100644 --- a/docs/Customization/Memory-Hierarchy.rst +++ b/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 WithBootROM ++ // use default bootrom - new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ + new WithTSI ++ + new WithNoGPIO ++ + 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 RocketConfig) + new WithTSI ++ + 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 WithL1ICacheWays(2) ++ - new WithL1DCacheSets(128) ++ - new WithL1DCacheWays(2) ++ - new RocketConfig) + new WithTSI ++ + new WithNoGPIO ++ + new WithBootROM ++ + new WithUART ++ + 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, @@ -49,18 +62,22 @@ Note that these configurations fully remove the L2 cache and mbus. .. code-block:: scala - class SmallRocketConfigNoL2 extends Config( - new WithTop ++ // use default top - new WithBootROM ++ // use default bootrom - new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ - new freechips.rocketchip.system.BaseConfig) - + class SmallRocketConfigNoL2 extends Config( + new WithTSI ++ + 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) + class ScratchpadRocketConfig extends Config( - new freechips.rocketchip.subsystem.WithNoMemPort ++ - new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++ - new freechips.rocketchip.subsystem.WithNBanks(0) ++ - new freechips.rocketchip.subsystem.WithScratchpadsOnly ++ - new SmallRocketConfigNoL2) + new freechips.rocketchip.subsystem.WithNoMemPort ++ + new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++ + new freechips.rocketchip.subsystem.WithNBanks(0) ++ + new freechips.rocketchip.subsystem.WithScratchpadsOnly ++ + new SmallRocketConfigNoL2) This configuration fully removes the L2 cache and memory bus by setting the number of channels and number of banks to 0. @@ -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 BaseConfig) + new WithUART ++ + 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 RocketConfig) + new WithTSI ++ + 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 diff --git a/docs/Customization/index.rst b/docs/Customization/index.rst index c76c1f3f..c5ec5778 100644 --- a/docs/Customization/index.rst +++ b/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: diff --git a/docs/VLSI/Advanced-Usage.rst b/docs/VLSI/Advanced-Usage.rst index c7e1bae2..6ab44c02 100644 --- a/docs/VLSI/Advanced-Usage.rst +++ b/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= + CUSTOM_VLOG= VLSI_TOP= ``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. @@ -32,7 +32,7 @@ For ``make par``: ./example-vlsi -e /path/to/env.yml -p /path/to/syn-output-full.json -o /path/to/par-input.json --obj_dir /path/to/build syn-to-par ./example-vlsi -e /path/to/env.yml -p /path/to/par-input.json --obj_dir /path/to/build par - + A ``syn-to-par`` action translates the synthesis output configuration into an input configuration given by ``-o``. Then, this is passed to the ``par`` action. For more information about all the options that can be passed to the Hammer command-line driver, please see the Hammer documentation. diff --git a/docs/_static/images/chip-bringup.png b/docs/_static/images/chip-bringup.png index b7ed022648969b8749a642e1d2f5c66a377a1823..4e8d060271ceb46cd26c61a3d6dacd901fcf43f2 100644 GIT binary patch literal 18536 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 MRAuuYJq!H506YynlmGw#