wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Jerry Zhao
2020-02-13 11:40:10 -08:00
parent 0f56c4ce44
commit c12819eb52
28 changed files with 247 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/Advanced-Concepts/Chip-Communication.rst
View File

@@ -109,16 +109,13 @@ reminder, to run a software RTL simulation, run:
FireSim FPGA-accelerated simulations use TSI by default as well.
If you would like to build and simulate a Chipyard configuration with a DTM configured for DMI communication, then you must create a
top-level system with the DTM (``TopWithDTM``), a test-harness to connect to the DTM (``TestHarnessWithDTM``), as well as a config to use that top-level system.
If you would like to build and simulate a Chipyard configuration with a DTM configured for DMI communication, then you must tie-off the TSI interface, and instantiate the `SimDTM`. Note that we use `WithTiedOffSerial ++ WithSimDTM` instead of `WithTiedOffDebug ++ WithSimSerial`.
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: DmiRocket
:end-before: DOC include end: DmiRocket
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.
.. code-block:: bash
@@ -144,7 +141,7 @@ The configuration is very similar to a DMI-based configuration. The main differe
is the addition of the ``WithJtagDTM`` mixin that configures the instantiated DTM to use the JTAG protocol as the
bringup method.
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: JtagRocket
:end-before: DOC include end: JtagRocket

10
docs/Advanced-Concepts/Top-Testharness.rst
View File

@@ -27,7 +27,7 @@ We also see this class define several ``ElaborationArtefacts``, files emitted af
Subsystem
^^^^^^^^^^^^^^^^^^^^^^^^^
Looking in `generators/utilities/src/main/scala/Subsystem.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/utilities/src/main/scala/Subsystem.scala>`__, we can see how Chipyard's ``Subsystem``
Looking in `generators/chipyard/src/main/scala/Subsystem.scala <https://github.com/ucb-bar/chipyard/blob/master/generators/chipyard/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.
@@ -35,7 +35,7 @@ We also connect some basic IOs for each tile here, specifically the hartids and
System
^^^^^^^^^^^^^^^^^^^^^^^^^
``generators/utilities/src/main/scala/System.scala`` completes the definition of the ``System``.
``generators/chipyard/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
@@ -45,7 +45,7 @@ System
Tops
^^^^^^^^^^^^^^^^^^^^^^^^^
A SoC Top then extends the ``System`` class with any config-specific components.
A SoC Top then extends the ``System`` class with traits for custom 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.
@@ -55,7 +55,7 @@ TestHarness
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
``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
@@ -66,4 +66,4 @@ 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 file is compiled with the generated Verilog for the ``TestHarness`` and the ``Top`` to produce a simulator.

6
docs/Chipyard-Basics/Chipyard-Components.rst
View File

@@ -29,9 +29,9 @@ Accelerators
Hwacha integrates with a Rocket or BOOM core using the RoCC (Rocket Custom Co-processor) interface.
See :ref:`Hwacha` for more information.
.. Fixed Function Accelerators:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TBD
**Gemmini**
A matrix-multiply accelerator targeting neural-networks
**SHA3**
A fixed-function accelerator for the SHA3 hash function. This simple accelerator is used as a demonstration for some of the
Chipyard integration flows using the RoCC interface.

53
docs/Chipyard-Basics/Configs-Parameters-Mixins.rst
View File

@@ -74,52 +74,37 @@ Cake Pattern
A cake pattern is a Scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes referred to as dependency injection).
It is used in the Rocket Chip SoC library and Chipyard framework in merging multiple system components and IO interfaces into a large system component.
This example shows a Rocket Chip based SoC that merges multiple system components (BootROM, UART, etc) into a single top-level design.
This example shows the Chipyard default top that composes multiple traits together into a fully-featured SoC with many optional components.
.. _cake-example:
.. code-block:: scala
class MySoC(implicit p: Parameters) extends RocketSubsystem
with CanHaveMasterAXI4MemPort
with HasPeripheryBootROM
with HasNoDebug
with HasPeripherySerial
with HasPeripheryUART
with HasPeripheryIceNIC
{
lazy val module = new MySoCModuleImp(this)
}
.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
:language: scala
:start-after: DOC include start: Top
:end-before: DOC include end: Top
class MySoCModuleImp(outer: MySoC) extends RocketSubsystemModuleImp(outer)
with CanHaveMasterAXI4MemPortModuleImp
with HasPeripheryBootROMModuleImp
with HasNoDebugModuleImp
with HasPeripherySerialModuleImp
with HasPeripheryUARTModuleImp
with HasPeripheryIceNICModuleImp
There are two "cakes" here. One for the lazy module (ex. ``HasPeripherySerial``) and one for the lazy module
implementation (ex. ``HasPeripherySerialModuleImp`` where ``Imp`` refers to implementation). The lazy module defines
There are two "cakes" here. One for the lazy module (ex. ``CanHavePeripherySerial``) and one for the lazy module
implementation (ex. ``CanHavePeripherySerialModuleImp`` where ``Imp`` refers to implementation). The lazy module defines
all the logical connections between generators and exchanges configuration information among them, while the
lazy module implementation performs the actual Chisel RTL elaboration.
In the ``MySoC`` example class, the "outer" ``MySoC`` instantiates the "inner"
``MySoCModuleImp`` as a lazy module implementation. This delays immediate elaboration
In the ``Top`` example class, the "outer" ``Top`` instantiates the "inner"
``TopModule`` as a lazy module implementation. This delays immediate elaboration
of the module until all logical connections are determined and all configuration information is exchanged.
The ``RocketSubsystem`` outer base class, as well as the
``HasPeripheryX`` outer traits contain code to perform high-level logical
connections. For example, the ``HasPeripherySerial`` outer trait contains code
to lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s
The ``Syatem`` outer base class, as well as the
``CanHavePeripheryX`` outer traits contain code to perform high-level logical
connections. For example, the ``CanHavePeripherySerial`` outer trait contains code
to optionally lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s
TileLink node to the Front bus.
The ``ModuleImp`` classes and traits perform elaboration of real RTL.
For example, the ``HasPeripherySerialModuleImp`` trait physically connects
For example, the ``CanHavePeripherySerialModuleImp`` trait optionally physically connects
the ``SerialAdapter`` module, and instantiates queues.
In the test harness, the SoC is elaborated with
``val dut = Module(LazyModule(MySoC))``.
After elaboration, the result will be a ``MySoC`` module, which contains a
``SerialAdapter`` module (among others).
``val dut = Module(LazyModule(Top))``.
After elaboration, the result will be a ``Top`` module, which contains a
``SerialAdapter`` module (among others), if the config specified for that block to be instantiated.
From a high level, classes which extend ``LazyModule`` *must* reference
their module implementation through ``lazy val module``, and they
@@ -134,8 +119,8 @@ Mix-in
---------------------------
A mix-in is a Scala trait, which sets parameters for specific system components, as well as enabling instantiation and wiring of the relevant system components to system buses.
The naming convention for an additive mix-in is ``Has<YourMixin>``.
This is shown in the ``MySoC`` class where things such as ``HasPeripherySerial`` connect a RTL component to a bus and expose signals to the top-level.
The naming convention for an additive mix-in is ``CanHave<YourMixin>``.
This is shown in the ``Top`` class where things such as ``CanHavePeripherySerial`` connect a RTL component to a bus and expose signals to the top-level.
Additional References
---------------------------

2
docs/Chipyard-Basics/Development-Ecosystem.rst
View File

@@ -16,7 +16,7 @@ Chisel is an embedded language within Scala that provides a set of libraries to
FIRRTL on the other hand is a compiler for hardware which allows the user to run FIRRTL passes that can do dead code elimination, circuit analysis, connectivity checks, and much more!
These two tools in combination allow quick design space exploration and development of new RTL.
Generators
RTL Generators
-------------------------------------------
Within this repository, all of the Chisel RTL is written as generators.

4
docs/Customization/Custom-Chisel.rst
View File

@@ -52,8 +52,8 @@ Then add ``yourproject`` to the Chipyard top-level build.sbt file.
You can then import the classes defined in the submodule in a new project if
you add it as a dependency. For instance, if you want to use this code in
the ``example`` project, change the final line in build.sbt to the following.
the ``chipyard`` project, change the final line in build.sbt to the following.
.. code-block:: scala
lazy val example = (project in file(".")).settings(commonSettings).dependsOn(testchipip, yourproject)
lazy val chipyard = (project in file(".")).settings(commonSettings).dependsOn(testchipip, yourproject)

8
docs/Customization/DMA-Devices.rst
View File

@@ -12,10 +12,10 @@ having the CPU poll data from the device, we may want to have the device write
directly to the coherent memory system instead. For example, here is a device
that writes zeros to the memory at a configured address.
.. literalinclude:: ../../generators/example/src/main/scala/InitZero.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/InitZero.scala
:language: scala
.. literalinclude:: ../../generators/example/src/main/scala/Top.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
:language: scala
:start-after: DOC include start: Top
:end-before: DOC include end: Top
@@ -26,12 +26,12 @@ For more info on creating TileLink client nodes, take a look at :ref:`Client Nod
Once we've created our top-level module including the DMA widget, we can create a configuration for it as we did before.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/InitZero.scala
:language: scala
:start-after: DOC include start: WithInitZero
:end-before: DOC include end: WithInitZero
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: InitZeroRocketConfig
:end-before: DOC include end: InitZeroRocketConfig

8
docs/Customization/Heterogeneous-SoCs.rst
View File

@@ -13,7 +13,7 @@ When used together you can create a heterogeneous system.
The following example shows a dual core BOOM with a single core Rocket.
.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
:language: scala
:start-after: DOC include start: DualBoomAndRocket
:end-before: DOC include end: DualBoomAndRocket
@@ -72,7 +72,7 @@ Adding Hwachas
Adding a Hwacha accelerator is as easy as adding the ``DefaultHwachaConfig`` so that it can setup the Hwacha parameters and add itself to the ``BuildRoCC`` parameter.
An example of adding a Hwacha to all tiles in the system is below.
.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
:language: scala
:start-after: DOC include start: BoomAndRocketWithHwacha
:end-before: DOC include end: BoomAndRocketWithHwacha
@@ -83,12 +83,12 @@ All with the same Hwacha parameters.
Assigning Accelerators to Specific Tiles with MultiRoCC
-------------------------------------------------------
Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a mixin that provides support for adding RoCC accelerators to specific tiles in your SoC.
Located in ``generators/chipyard/src/main/scala/ConfigMixins.scala`` is a mixin that provides support for adding RoCC accelerators to specific tiles in your SoC.
Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on the ``hartId`` of the tile.
For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles.
An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached.
.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
:language: scala
:start-after: DOC include start: DualBoomAndRocketOneHwacha
:end-before: DOC include end: DualBoomAndRocketOneHwacha

12
docs/Customization/Incorporating-Verilog-Blocks.rst
View File

@@ -48,12 +48,12 @@ Verilog files into the build process, which are part of the
.settings(commonSettings)
For this concrete GCD example, we will be using a ``GCDMMIOBlackBox``
Verilog module that is defined in the ``example`` project. The Scala
Verilog module that is defined in the ``chipyard`` project. The Scala
and Verilog sources follow the prescribed directory layout.
.. code-block:: none
generators/example/
generators/chipyard/
build.sbt
src/main/
scala/
@@ -81,14 +81,14 @@ 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
.. literalinclude:: ../../generators/chipyard/src/main/resources/vsrc/GCDMMIOBlackBox.v
:language: Verilog
:start-after: DOC include start: GCD portlist
:end-before: DOC include end: GCD portlist
**Chisel BlackBox Definition**
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD blackbox
:end-before: DOC include end: GCD blackbox
@@ -103,7 +103,7 @@ peripheral-specific traits into a ``TLRegisterRouter``. The ``params``
member and ``HasRegMap`` base trait should look familiar from the
previous memory-mapped GCD device example.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD instance regmap
:end-before: DOC include end: GCD instance regmap
@@ -115,7 +115,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.
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GCDAXI4BlackBoxRocketConfig
:end-before: DOC include end: GCDAXI4BlackBoxRocketConfig

41
docs/Customization/Keys-Traits-Configs.rst
View File

@@ -16,7 +16,7 @@ Keys specify some parameter which controls some custom widget. Keys should typic
Keys should be defined and documented in sub-projects, since they generally deal with some specific block, and not system-level integration. (We make an exception for the example GCD widget).
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD key
:end-before: DOC include end: GCD key
@@ -24,7 +24,7 @@ Keys should be defined and documented in sub-projects, since they generally deal
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
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD params
:end-before: DOC include end: GCD params
@@ -42,14 +42,14 @@ Top-level traits should be defined and documented in subprojects, alongside thei
Below we see the traits for the GCD example. The Lazy trait connects the GCD module to the Diplomacy graph, while the Implementation trait causes the ``Top`` to instantiate an additional port and concretely connect it to the GCD module.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD lazy trait
:end-before: DOC include end: GCD imp trait
These traits are added to the default ``Top`` in Chipyard.
.. literalinclude:: ../../generators/example/src/main/scala/Top.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
:language: scala
:start-after: DOC include start: Top
:end-before: DOC include end: Top
@@ -57,49 +57,22 @@ These traits are added to the default ``Top`` in Chipyard.
Mixins
------
Mixins set the keys to a non-default value. Together, the collection of Mixins which define a configuration generate the values for all the keys used by the generator.
Config mixins set the keys to a non-default value. Together, the collection of Mixins which define a configuration generate the values for all the keys used by the generator.
For example, the ``WithGCDMixin`` is parameterized by the type of GCD widget you want to instantiate. When this mixin is added to a config, the ``GCDKey`` is set to a instance of ``GCDParams``, informing the previously mentioned traits to instantiate and connect the GCD widget appropriately.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD mixin
:end-before: DOC include end: GCD mixin
We can use this mixin when composing our configs.
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GCDTLRocketConfig
:end-before: DOC include end: GCDTLRocketConfig
BuildTop
--------
The ``BuildTop`` key is special, because sometimes, we need to instantiate ``TestHarness`` modules to interface with a custom widget. The ``BuildTop`` key provides a function which can call some method of the Top to instantiate these ``TestHarness`` modules. Since the ``BuildTop`` key is called from the ``TestHarness``, these modules will appear in the ``TestHarness``. The config system also lets the ``BuildTop`` key look recursively into previous definitions of itself. This enables composability of the ``Top`` configurations.
For example, conside a config that contains the mixins ``WithGPIO ++ WithTSI``. We need to instantiate the TSI serial adapter, and connect it to the ``success`` signal of our ``TestHarness``. We also need to instantiate the GPIO pins, and tie their inputs to 0 in the ``TestHarness``, since we currently cannot drive the GPIOs in simulation.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
:language: scala
:start-after: DOC include start: tsi mixin
:end-before: DOC include end: tsi mixin
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
:language: scala
:start-after: DOC include start: gpio mixin
:end-before: DOC include end: gpio mixin
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::
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.
.. note::
Readers who want more information on the configuration system may be interested in reading :ref:`cdes`.

24
docs/Customization/MMIO-Peripherals.rst
View File

@@ -3,21 +3,21 @@
MMIO Peripherals
==================
The easiest way to create a MMIO peripheral is to use the ``TLRegisterRouter`` or ``AXI4RegisterRouter`` widgets, which abstracts away the details of handling the interconnect protocols and provides a convenient interface for specifying memory-mapped registers. Since Chipyard and Rocket Chip SoCs primarily use Tilelink as the on-chip interconnect protocol, this section will primarily focus on designing Tilelink-based peripherals. However, see ``generators/example/src/main/scala/GCD.scala`` for how an example AXI4 based peripheral is defined and connected to the Tilelink graph through converters.
The easiest way to create a MMIO peripheral is to use the ``TLRegisterRouter`` or ``AXI4RegisterRouter`` widgets, which abstracts away the details of handling the interconnect protocols and provides a convenient interface for specifying memory-mapped registers. Since Chipyard and Rocket Chip SoCs primarily use Tilelink as the on-chip interconnect protocol, this section will primarily focus on designing Tilelink-based peripherals. However, see ``generators/chipyard/src/main/scala/GCD.scala`` for how an example AXI4 based peripheral is defined and connected to the Tilelink graph through converters.
To create a RegisterRouter-based peripheral, you will need to specify a parameter case class for the configuration settings, a bundle trait with the extra top-level ports, and a module implementation containing the actual RTL.
For this example, we will show how to connect a MMIO peripheral which computes the GCD.
The full code can be found in ``generators/example/src/main/scala/GCD.scala``.
The full code can be found in ``generators/chipyard/src/main/scala/GCD.scala``.
In this case we use a submodule ``GCDMMIOChiselModule`` to actually perform the GCD. The ``GCDModule`` class only creates the registers and hooks them up using ``regmap``.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD chisel
:end-before: DOC include end: GCD chisel
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD instance regmap
:end-before: DOC include end: GCD instance regmap
@@ -51,7 +51,7 @@ The second set of arguments is the IO bundle constructor, which we create by ext
The final set of arguments is the module constructor, which we create by extends ``TLRegModule`` with our module trait.
Notice how we can create an analogous AXI4 version of our peripheral.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD router
:end-before: DOC include end: GCD router
@@ -69,7 +69,7 @@ In the Rocket Chip cake, there are two kinds of traits: a ``LazyModule`` trait a
The ``LazyModule`` trait runs setup code that must execute before all the hardware gets elaborated.
For a simple memory-mapped peripheral, this just involves connecting the peripheral's TileLink node to the MMIO crossbar.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD lazy trait
:end-before: DOC include end: GCD lazy trait
@@ -82,7 +82,7 @@ Also observe how we have to place additional AXI4 buffers and converters for the
For peripherals which instantiate a concrete module, or which need to be connected to concrete IOs or wires, a matching concrete trait is necessary. We will make our GCD example output a ``gcd_busy`` signal as a top-level port to demonstrate. In the concrete module implementation trait, we instantiate the top level IO (a concrete object) and wire it to the IO of our lazy module.
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD imp trait
:end-before: DOC include end: GCD imp trait
@@ -91,9 +91,9 @@ Constructing the Top and Config
-------------------------------
Now we want to mix our traits into the system as a whole.
This code is from ``generators/example/src/main/scala/Top.scala``.
This code is from ``generators/chipyard/src/main/scala/Top.scala``.
.. literalinclude:: ../../generators/example/src/main/scala/Top.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
:language: scala
:start-after: DOC include start: Top
:end-before: DOC include end: Top
@@ -105,14 +105,14 @@ The ``TopModule`` class is the actual RTL that gets synthesized.
And finally, we create a configuration class in ``generators/example/src/main/scala/Configs.scala`` that uses the ``WithGCD`` mixin defined earlier.
And finally, we create a configuration class in ``generators/chipyard/src/main/scala/Configs.scala`` that uses the ``WithGCD`` mixin defined earlier.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD mixin
:end-before: DOC include end: GCD mixin
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GCDTLRocketConfig
:end-before: DOC include end: GCDTLRocketConfig

169
docs/Customization/Memory-Hierarchy.rst
View File

@@ -14,25 +14,43 @@ configure 4 KiB direct-mapped caches for L1I and L1D.
.. code-block:: scala
class SmallRocketConfig 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) ++ // small rocket cores
new freechips.rocketchip.system.BaseConfig)
class SmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithInclusiveCache ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ // small rocket cores
new freechips.rocketchip.system.BaseConfig)
class MediumRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithInclusiveCache ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNMediumCores(1) ++ // Medium rocket cores
new freechips.rocketchip.system.BaseConfig)
class MediumRocketConfig extends Config(
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.
@@ -42,18 +60,11 @@ mixins for those too.
import freechips.rocketchip.subsystem.{WithL1ICacheSets, WithL1DCacheSets, WithL1ICacheWays, WithL1DCacheWays}
class MyL1RocketConfig extends Config(
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)
new freechips.rocketchip.subsystem.WithL1ICacheSets(128) ++ // change rocket I$
new freechips.rocketchip.subsystem.WithL1ICacheWays(2) ++ // change rocket I$
new freechips.rocketchip.subsystem.WithL1DCacheSets(128) ++ // change rocket D$
new freechips.rocketchip.subsystem.WithL1DCacheWays(2) ++ // change rocket D$
new RocketConfig)
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,
@@ -62,22 +73,26 @@ Note that these configurations fully remove the L2 cache and mbus.
.. code-block:: scala
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 ScratchpadSmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++
new freechips.rocketchip.subsystem.WithNBanks(0) ++
new freechips.rocketchip.subsystem.WithScratchpadsOnly ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
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)
This configuration fully removes the L2 cache and memory bus by setting the
number of channels and number of banks to 0.
@@ -92,23 +107,8 @@ set-associativity. However, you can change these parameters to obtain your
desired cache configuration. The main restriction is that the number of ways
and the number of banks must be powers of 2.
.. code-block:: scala
import freechips.rocketchip.subsystem.WithInclusiveCache
class MyCacheRocketConfig extends Config(
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 freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
Refer to the ``CacheParameters`` object defined in sifive-cache for
customization options.
The Broadcast Hub
-----------------
@@ -120,28 +120,29 @@ To make such a configuration, you can just copy the definition of
``RocketConfig`` but omit the ``WithInclusiveCache`` mixin from the
list of included mixims.
.. code-block:: scala
class CachelessRocketConfig extends Config(
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
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.
.. code-block:: scala
import freechips.rocketchip.subsystem.WithBufferlessBroadcastHub
class NoL2SmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithBufferlessBroadcastHub ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
class BufferlessRocketConfig extends Config(
new WithBufferlessBroadcastHub ++
new CachelessRocketConfig)
The Outer Memory System
-----------------------
@@ -158,15 +159,9 @@ number of DRAM channels is restricted to powers of two.
import freechips.rocketchip.subsystem.WithNMemoryChannels
class DualChannelRocketConfig extends Config(
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)
new freechips.rocketchip.subsystem.WithNMemoryChannels(2) ++
new RocketConfig)
In VCS and Verilator simulation, the DRAM is simulated using the
``SimAXIMem`` module, which simply attaches a single-cycle SRAM to each

4
docs/Generators/Gemmini.rst
View File

@@ -9,7 +9,7 @@ To add a Gemmini unit to an SoC, you should add the ``gemmini.DefaultGemminiConf
The example Chipyard config includes the following example SoC configuration which includes Gemmini:
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GemminiRocketConfig
:end-before: DOC include end: GemminiRocketConfig
@@ -42,7 +42,7 @@ Major parameters of interest include:
* DMA parameters (``dma_maxbytes``, ``dma_buswidth``, ``mem_pipeline``): Gemmini implements a DMA to move data from main memory to the Gemmini scratchpad, and from the Gemmini accumulators to main memory. The size of these DMA transactions is determined by the DMA parameters. These DMA parameters are tightly coupled with Rocket Chip SoC system parameters: in particular ``dma_buswidth`` is associated with the ``SystemBusKey`` ``beatBytes`` parameter, and ``dma_maxbytes`` is associated with ``cacheblockbytes`` Rocket Chip parameters.
Software
Gemmini Software
------------------
The Gemmini non-standard ISA extension is specified in the `Gemmini repository <https://github.com/ucb-bar/gemmini/blob/master/README.md>`__.

7
docs/Generators/Rocket-Chip.rst
View File

@@ -58,8 +58,8 @@ The ``PeripheryBus`` attaches additional peripherals like the NIC and Block Devi
It can also optionally expose an external AXI4 port, which can be attached to
vendor-supplied AXI4 IP.
To learn more about adding MMIO peripherals, check out the :ref:`MMIO Peripheral`
section of :ref:`Adding an Accelerator/Device`.
To learn more about adding MMIO peripherals, check out the :ref:`mmio-accelerators`
section.
DMA
---
@@ -68,5 +68,4 @@ You can also add DMA devices that read and write directly from the memory
system. These are attached to the ``FrontendBus``. The ``FrontendBus`` can also
connect vendor-supplied AXI4 DMA devices through an AXI4 to TileLink converter.
To learn more about adding DMA devices, see the :ref:`Adding a DMA port` section
of :ref:`Adding an Accelerator/Device`.
To learn more about adding DMA devices, see the :ref:`dma-devices` section.

2
docs/Generators/SHA3.rst
View File

@@ -72,7 +72,7 @@ it can be mixed into a Rocket or BOOM core by overriding the
generator. An example configuration highlighting the use of
this mixin is shown here:
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: Sha3Rocket
:end-before: DOC include end: Sha3Rocket

6
docs/Generators/SiFive-Generators.rst
View File

@@ -18,7 +18,7 @@ Peripheral Devices
These peripheral devices usually affect the memory map of the SoC, and its top-level IO as well.
To integrate one of these devices in your SoC, you will need to define a custom mixin with the approriate address for the device using the Rocket Chip parameter system. As an example, for a GPIO device you could add the following mixin to set the GPIO address to ``0x10012000``. This address is the start address for the GPIO configuration registers.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/ConfigMixins.scala
:language: scala
:start-after: DOC include start: gpio mixin
:end-before: DOC include end: gpio mixin
@@ -26,12 +26,12 @@ To integrate one of these devices in your SoC, you will need to define a custom
Additionally, if the device requires top-level IOs, you will need to define a mixin to change the top-level configuration of your SoC.
When adding a top-level IO, you should also be aware of whether it interacts with the test-harness.
This example instantiates a top-level module with include GPIO ports (``TopWithGPIO``), and then ties-off the GPIO port inputs to 0 (``false.B``).
This example instantiates a top-level module with include GPIO ports, and then ties-off the GPIO port inputs to 0 (``false.B``).
Finally, you add the relevant config mixin to the SoC config. For example:
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GPIORocketConfig
:end-before: DOC include end: GPIORocketConfig

7
docs/Generators/TestChipIP.rst
View File

@@ -22,9 +22,7 @@ The block device controller provides a generic interface for secondary storage.
This device is primarily used in FireSim to interface with a block device
software simulation model. The default Linux configuration in `firesim-software <https://github.com/firesim/firesim-software>`_
To add a block device to your design, add ``HasPeripheryBlockDevice`` to your
lazy module and ``HasPeripheryBlockDeviceModuleImp`` to the implementation.
Then add the ``WithBlockDevice`` config mixin to your configuration.
To add a block device to your design, add the ``WithBlockDevice`` config mixin to your configuration.
TileLink SERDES
@@ -71,5 +69,4 @@ during Linux boot). In addition to working with ``stdin/stdout`` of the host, it
output a UART log to a particular file using ``+uartlog=<NAME_OF_FILE>`` during simulation.
By default, this UART Adapter is added to all systems within Chipyard by adding the
``CanHavePeripheryUARTWithAdapter`` and ``CanHavePeripheryUARTWithAdapterImp`` traits to the ``Top`` system.
These traits add a SiFive UART to the system as well as add the UART Adapter to the TestHarness.
``WithUART`` and ``WithUARTAdapter`` configs.

2
docs/Generators/index.rst
View File

@@ -1,6 +1,6 @@
.. _generator-index:
Generators
Included RTL Generators
============================
A Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.

65
docs/Quick-Start.rst
View File

@@ -1,65 +0,0 @@
Quick Start
===============================
Requirements
-------------------------------------------
Chipyard is developed and tested on Linux-based systems.
.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
.. Warning:: Working under Windows is not recommended.
Setting up the Chipyard Repo
-------------------------------------------
Start by fetching Chipyard's sources. Run:
.. code-block:: shell
git clone https://github.com/ucb-bar/chipyard.git
cd chipyard
./scripts/init-submodules-no-riscv-tools.sh
This will initialize and checkout all of the necessary git submodules.
Installing the RISC-V Tools
-------------------------------------------
We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
To build the toolchains, you should run:
.. code-block:: shell
./scripts/build-toolchains.sh
.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
Finally, set up Chipyard's environment variables and put the newly built toolchain on your path:
.. code-block:: shell
source ./env.sh
What's Next?
-------------------------------------------
This depends on what you are planning to do with Chipyard.
* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.

6
docs/Simulation/Software-RTL-Simulation.rst
View File

@@ -49,16 +49,16 @@ Simulating The Default Example
To compile the example design, run ``make`` in the selected verilator or VCS directory.
This will elaborate the ``RocketConfig`` in the example project.
An executable called ``simulator-example-RocketConfig`` will be produced.
An executable called ``simulator-chipyard-RocketConfig`` will be produced.
This executable is a simulator that has been compiled based on the design that was built.
You can then use this executable to run any compatible RV64 code.
For instance, to run one of the riscv-tools assembly tests.
.. code-block:: shell
./simulator-example-RocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
./simulator-chipyard-RocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
.. Note:: In a VCS simulator, the simulator name will be ``simv-example-RocketConfig`` instead of ``simulator-example-RocketConfig``.
.. Note:: In a VCS simulator, the simulator name will be ``simv-chipyard-RocketConfig`` instead of ``simulator-chipyard-RocketConfig``.
Alternatively, we can run a pre-packaged suite of RISC-V assembly or benchmark tests, by adding the make target ``run-asm-tests`` or ``run-bmark-tests``.
For example:

1
docs/Software/FireMarshal.rst
View File

@@ -1,4 +1,5 @@
.. _fire-marshal:
FireMarshal
=================

12
docs/TileLink-Diplomacy-Reference/NodeTypes.rst
View File

@@ -17,7 +17,7 @@ The L1 caches and DMA devices in RocketChip/Chipyard have client nodes.
You can add a TileLink client node to your LazyModule using the TLHelper
object from testchipip like so:
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyClient
:end-before: DOC include end: MyClient
@@ -66,7 +66,7 @@ TileLink managers take requests from clients on the A channel and send
responses back on the D channel. You can create a manager node using the
TLHelper like so:
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyManager
:end-before: DOC include end: MyManager
@@ -146,7 +146,7 @@ to the outputs unchanged. This node is mainly used to combine multiple
nodes into a single node with multiple edges. For instance, say we have two
client lazy modules, each with their own client node.
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyClient1+MyClient2
:end-before: DOC include end: MyClient1+MyClient2
@@ -154,21 +154,21 @@ client lazy modules, each with their own client node.
Now we instantiate these two clients in another lazy module and expose their
nodes as a single node.
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyClientGroup
:end-before: DOC include end: MyClientGroup
We can also do the same for managers.
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyManagerGroup
:end-before: DOC include end: MyManagerGroup
If we want to connect the client and manager groups together, we can now do this.
.. literalinclude:: ../../generators/example/src/main/scala/NodeTypes.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
:language: scala
:start-after: DOC include start: MyClientManagerComplex
:end-before: DOC include end: MyClientManagerComplex

14
docs/TileLink-Diplomacy-Reference/Register-Router.rst
View File

@@ -11,14 +11,14 @@ for exposing registers themselves, it's much easier to use RocketChip's
``regmap`` interface, which can generate most of the glue logic.
For TileLink devices, you can use the ``regmap`` interface by extending
the ``TLRegisterRouter`` class, as shown in :ref:`Adding An Accelerator/Device`,
the ``TLRegisterRouter`` class, as shown in :ref:`mmio-accelerators`,
or you can create a regular LazyModule and instantiate a ``TLRegisterNode``.
This section will focus on the second method.
Basic Usage
-----------
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MyDeviceController
:end-before: DOC include end: MyDeviceController
@@ -56,7 +56,7 @@ register. The ``RegField`` interface also provides support for reading
and writing ``DecoupledIO`` interfaces. For instance, you can implement a
hardware FIFO like so.
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MyQueueRegisters
:end-before: DOC include end: MyQueueRegisters
@@ -71,7 +71,7 @@ You need not specify both read and write for a register. You can also create
read-only or write-only registers. So for the previous example, if you wanted
enqueue and dequeue to use different addresses, you could write the following.
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MySeparateQueueRegisters
:end-before: DOC include end: MySeparateQueueRegisters
@@ -93,7 +93,7 @@ You can also create registers using functions. Say, for instance, that you
want to create a counter that gets incremented on a write and decremented on
a read.
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MyCounterRegisters
:end-before: DOC include end: MyCounterRegisters
@@ -107,7 +107,7 @@ You can also pass functions that decouple the read/write request and response.
The request will appear as a decoupled input and the response as a decoupled
output. So for instance, if we wanted to do this for the previous example.
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MyCounterReqRespRegisters
:end-before: DOC include end: MyCounterReqRespRegisters
@@ -131,7 +131,7 @@ change the protocol being used. For instance, in the first example in
:ref:`Basic Usage`, you could simply change the ``TLRegisterNode`` to
and ``AXI4RegisterNode``.
.. literalinclude:: ../../generators/example/src/main/scala/RegisterNodeExample.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
:language: scala
:start-after: DOC include start: MyAXI4DeviceController
:end-before: DOC include end: MyAXI4DeviceController

2
docs/TileLink-Diplomacy-Reference/index.rst
View File

@@ -11,7 +11,7 @@ elaboration scheme. For a detailed explanation of Diplomacy, see `the paper
by Cook, Terpstra, and Lee <https://carrv.github.io/2017/papers/cook-diplomacy-carrv2017.pdf>`_.
A brief overview of how to connect simple TileLink widgets can be found
in the :ref:`Adding-an-Accelerator` section. This section will provide a
in the :ref:`mmio-accelerators` section. This section will provide a
detailed reference for the TileLink and Diplomacy functionality provided by
RocketChip.

1
docs/Tools/FIRRTL.rst
View File

@@ -1,4 +1,3 @@
.. _firrtl:
FIRRTL
================================

2
docs/Tools/index.rst
View File

@@ -1,4 +1,4 @@
Tools
Development Tools
==============================
The Chipyard framework relays heavily on a set of Scala-based tools.

4
docs/VLSI/Advanced-Usage.rst
View File

@@ -49,6 +49,6 @@ Say you need to update some power straps settings in ``example.yml`` and want to
make redo-par HAMMER_REDO_ARGS='-p example.yml --only_step power_straps'
Simulation
----------
RTL and Gate-level Simulation
-----------------------------
With the Synopsys plugin, RTL and gate-level simulation is supported using VCS. While this example does not implement any simulation, refer to Hammer's documentation for how to set it up for your design.

67
docs/index.rst
View File

@@ -12,7 +12,72 @@ Chipyard is a a framework for designing and evaluating full-system hardware usin
It is composed of a collection of tools and libraries designed to provide an intergration between open-source and commercial tools for the development of systems-on-chip.
New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info.
.. include:: Quick-Start.rst
Quick Start
===============================
System Requirements
-------------------------------------------
Chipyard is developed and tested on Linux-based systems.
.. Warning:: It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
.. Warning:: Working under Windows is not recommended.
Setting up the Chipyard Repo
-------------------------------------------
Start by fetching Chipyard's sources. Run:
.. code-block:: shell
git clone https://github.com/ucb-bar/chipyard.git
cd chipyard
./scripts/init-submodules-no-riscv-tools.sh
This will initialize and checkout all of the necessary git submodules.
Installing the RISC-V Tools
-------------------------------------------
We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure.
This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``.
To build the toolchains, you should run:
.. code-block:: shell
./scripts/build-toolchains.sh
.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchain by adding the ``esp-tools`` argument to the script above.
If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expedited installation of a pre-compiled toolchain.
Finally, set up Chipyard's environment variables and put the newly built toolchain on your path:
.. code-block:: shell
source ./env.sh
What's Next?
-------------------------------------------
This depends on what you are planning to do with Chipyard.
* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.
* If you intend to add a new accelerator, go to :ref:`customization` and follow the instructions.
* If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
* If you intend to run a tutorial VLSI flow using one of the Chipyard examples, go to :ref:`tutorial` and follow the instructions.
* If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
Getting Help
------------