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

Rename Config Mixins to Fragments (#451)

Browse Source 
* [docs] rename config mixins -> fragments [ci skip]

* [docs] cleanup naming | link similar sections [ci skip]

* [boom] bump for mixin rename [ci skip]

* [docs] cleanup capitalization [ci skip]

* [docs] consistent config fragment naming [ci skip]

* [boom] bump boom for documentation changes [ci skip]

* [docs] update source comments [ci skip]

* [docs] fix last config fragment name [ci skip]

Co-Authored-By: alonamid <alonamid@eecs.berkeley.edu>

Co-authored-by: alonamid <alonamid@eecs.berkeley.edu>
This commit is contained in:
Abraham Gonzalez
2020-02-27 09:31:08 -08:00
committed by GitHub
parent b6faed283a
commit 01238c8b7a
22 changed files with 91 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/Advanced-Concepts/CDEs.rst
View File

@@ -28,11 +28,11 @@ Consider the following example using CDEs.
}
When forming a query based on a ``Parameters`` object, like ``p(SomeKeyX)``, the configuration system traverses the "chain" of mixins until it finds a partial function which is defined at the key, and then returns that value.
When forming a query based on a ``Parameters`` object, like ``p(SomeKeyX)``, the configuration system traverses the "chain" of config fragments until it finds a partial function which is defined at the key, and then returns that value.
.. code:: scala
val params = Config(new WithX(true) ++ new WithY(true)) // "chain" together mixins
val params = Config(new WithX(true) ++ new WithY(true)) // "chain" together config fragments
params(SomeKeyX) // evaluates to true
params(SomeKeyY) // evaluates to true
params(SomeKeyZ) // evaluates to false
@@ -68,7 +68,7 @@ In this example, the partial function in ``WithXEqualsYSite`` will look up the v
Here
~~~~
``here`` provides a ``View`` of the locally defined Config, which typically just contains some partial function.
``here`` provides a ``View`` of the locally defined config, which typically just contains some partial function.
.. code:: scala
@@ -103,7 +103,7 @@ Up
params_1(SomeKeyX) // evaluates to true
params_2(SomeKeyX) // evaluates to false
In this example, note how ``up(SomeKeyY, site)`` in ``WithXEqualsYUp`` will refer to *either* the the partial function defining ``SomeKeyY`` in ``WithY(true)`` *or* the default value for ``SomeKeyY`` provided in the original ``case object SomeKeyY`` definition, *depending on the order in which the mixins were used*. Since the order of mixins affects the the order of the ``View`` traversal, ``up`` provides a different ``View`` of the parameterization in ``params_1`` and ``params_2``.
In this example, note how ``up(SomeKeyY, site)`` in ``WithXEqualsYUp`` will refer to *either* the the partial function defining ``SomeKeyY`` in ``WithY(true)`` *or* the default value for ``SomeKeyY`` provided in the original ``case object SomeKeyY`` definition, *depending on the order in which the config fragments were used*. Since the order of config fragments affects the the order of the ``View`` traversal, ``up`` provides a different ``View`` of the parameterization in ``params_1`` and ``params_2``.
Also note that again, ``site`` must be recursively passed through the call to ``up``.

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

@@ -81,7 +81,7 @@ Similar to TSI, the DMI protocol is an implementation of HTIF.
In order to communicate with the DUT with the DMI protocol, the DUT needs to contain a Debug Transfer Module (DTM).
The DTM is given in the `RISC-V Debug Specification <https://riscv.org/specifications/debug-specification/>`__
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.
This is implemented in the Rocket Chip ``Subsystem`` by having the ``HasPeripheryDebug`` and ``HasPeripheryDebugModuleImp`` traits.
During simulation, the host sends DMI commands to a
simulation stub called ``SimDTM`` (C++ class) that resides in a ``SimDTM`` Verilog module
(both are located in the ``generators/rocket-chip`` project). This ``SimDTM`` Verilog module then
@@ -138,7 +138,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.
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
is the addition of the ``WithJtagDTM`` config fragment that configures the instantiated DTM to use the JTAG protocol as the
bringup method.
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala

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

@@ -52,7 +52,7 @@ Please refer to :ref:`Communicating with the DUT` for more information on these
TestHarness
-------------------------
The wiring between the ``TestHarness`` and the Top are performed in methods defined in mixins added to the Top.
The wiring between the ``TestHarness`` and the Top are performed in methods defined in traits 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 ``SimAXIMems``

2
docs/Advanced-Concepts/index.rst
View File

@@ -2,7 +2,7 @@ Advanced Concepts
================================
The following sections are advanced topics about how to Chipyard works, how to use Chipyard, and special features of the framework.
They expect you to know about Chisel, Parameters, Configs, etc.
They expect you to know about Chisel, Parameters, configs, etc.
.. toctree::
:maxdepth: 2

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

@@ -1,4 +1,4 @@
Configs, Parameters, Mix-ins, and Everything In Between
Configs, Parameters, Mixins, and Everything In Between
========================================================
A significant portion of generators in the Chipyard framework use the Rocket Chip parameter system.
@@ -14,12 +14,12 @@ We are still investigating methods to facilitate parameter exploration and disco
Configs
---------------------
A *Config* is a collection of multiple generator parameters being set to specific values.
Configs are additive, can override each other, and can be composed of other Configs.
The naming convention for an additive Config is ``With<YourConfigName>``, while the naming convention for a non-additive Config will be ``<YourConfig>``.
A *config* is a collection of multiple generator parameters being set to specific values.
Configs are additive, can override each other, and can be composed of other configs (sometimes referred to as config fragments).
The naming convention for an additive config or config fragment is ``With<YourConfigName>``, while the naming convention for a non-additive config will be ``<YourConfig>``.
Configs can take arguments which will in-turn set parameters in the design or reference other parameters in the design (see :ref:`Parameters`).
This example shows a basic additive Config class that takes in zero arguments and instead uses hardcoded values to set the RTL design parameters.
This example shows a basic config fragment class that takes in zero arguments and instead uses hardcoded values to set the RTL design parameters.
In this example, ``MyAcceleratorConfig`` is a Scala case class that defines a set of variables that the generator can use when referencing the ``MyAcceleratorKey`` in the design.
.. _basic-config-example:
@@ -36,7 +36,7 @@ In this example, ``MyAcceleratorConfig`` is a Scala case class that defines a se
someLength = 256)
})
This next example shows a "higher-level" additive Config that uses prior parameters that were set to derive other parameters.
This next example shows a "higher-level" additive config fragment that uses prior parameters that were set to derive other parameters.
.. _complex-config-example:
.. code-block:: scala
@@ -50,8 +50,8 @@ This next example shows a "higher-level" additive Config that uses prior paramet
hartId = up(RocketTilesKey, site).length)
})
The following example shows a non-additive Config that combines the prior two additive Configs using ``++``.
The additive Configs are applied from the right to left in the list (or bottom to top in the example).
The following example shows a non-additive config that combines or "assembles" the prior two config fragments using ``++``.
The additive config fragments are applied from the right to left in the list (or bottom to top in the example).
Thus, the order of the parameters being set will first start with the ``DefaultExampleConfig``, then ``WithMyAcceleratorParams``, then ``WithMyMoreComplexAcceleratorConfig``.
.. _top-level-config:
@@ -68,10 +68,10 @@ The ``site`` map gives you the definitions as seen from the root of the configur
The ``here`` map gives the definitions as seen at the current level of the hierarchy (i.e. in ``WithMyMoreComplexAcceleratorConfig`` itself).
The ``up`` map gives the definitions as seen from the next level up from the current (i.e. from ``WithMyAcceleratorParams``).
Cake Pattern
Cake Pattern / Mixin
-------------------------
A cake pattern is a Scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes referred to as dependency injection).
A cake pattern or mixin 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 the Chipyard default top that composes multiple traits together into a fully-featured SoC with many optional components.
@@ -83,7 +83,7 @@ This example shows the Chipyard default top that composes multiple traits togeth
:end-before: DOC include end: Top
There are two "cakes" here. One for the lazy module (ex. ``CanHavePeripherySerial``) and one for the lazy module
There are two "cakes" or mixins 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.
@@ -114,15 +114,13 @@ contain the implementation for the module, and may instantiate
other normal modules OR lazy modules (for nested Diplomacy
graphs, for example).
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 ``CanHave<YourMixin>``.
The naming convention for an additive mixin or trait 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
---------------------------
A brief explanation of some of these topics is given in the following video: https://www.youtube.com/watch?v=Eko86PGEoDY.
Another description of traits/mixins and config fragments is given in :ref:`Keys, Traits, and Configs`.
Additionally, a brief explanation of some of these topics (with slightly different naming) is given in the following video: https://www.youtube.com/watch?v=Eko86PGEoDY.
.. Note:: Chipyard uses the name "config fragments" over "config mixins" to avoid confusion between a mixin applying to a config or to the system ``Top`` (even though both are technically Scala mixins).

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

@@ -7,8 +7,8 @@ This discussion will focus on how you combine Rocket, BOOM and Hwacha in particu
Creating a Rocket and BOOM System
-------------------------------------------
Instantiating an SoC with Rocket and BOOM cores is all done with the configuration system and two specific mixins.
Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core/tile [1]_.
Instantiating an SoC with Rocket and BOOM cores is all done with the configuration system and two specific config fragments.
Both BOOM and Rocket have config fragments labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core/tile [1]_.
When used together you can create a heterogeneous system.
The following example shows a dual core BOOM with a single core Rocket.
@@ -18,18 +18,18 @@ The following example shows a dual core BOOM with a single core Rocket.
:start-after: DOC include start: DualBoomAndRocket
: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 ``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.
In this example, the ``WithNBoomCores`` and ``WithNBigCores`` config fragments set up the default parameters for the multiple BOOM and Rocket cores, respectively.
However, for BOOM, an extra config fragment called ``WithLargeBooms`` is added to override the default parameters with a different set of more common default parameters.
This config fragment 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.
The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId`` (a ``hartId`` is the hardware thread id of the core).
The ``WithRenumberHarts`` mixin solves this by assigning a unique ``hartId`` to all cores in the system (it can label the Rocket cores first or the BOOM cores first).
The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only BOOM or only Rocket cores in the system.
Thus, without the ``WithRenumberHarts`` mixin, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``.
The ``WithRenumberHarts`` config fragment solves this by assigning a unique ``hartId`` to all cores in the system (it can label the Rocket cores first or the BOOM cores first).
The reason this is needed is because by default the ``WithN...Cores(X)`` config fragment assumes that there are only BOOM or only Rocket cores in the system.
Thus, without the ``WithRenumberHarts`` config fragment, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``.
Another alternative option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core.
The mixin to add to your system would look something like the following.
The config fragment to add to your system would look something like the following.
.. code-block:: scala
@@ -50,7 +50,7 @@ The mixin to add to your system would look something like the following.
}
})
Then you could use this new mixin like the following.
Then you could use this new config fragment like the following.
.. code-block:: scala
@@ -83,7 +83,7 @@ All with the same Hwacha parameters.
Assigning Accelerators to Specific Tiles with MultiRoCC
-------------------------------------------------------
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.
Located in ``generators/chipyard/src/main/scala/ConfigFragments.scala`` is a config fragment 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.
@@ -94,13 +94,13 @@ An example is shown below with two BOOM cores, and one Rocket tile with a RoCC a
:end-before: DOC include end: DualBoomAndRocketOneHwacha
In this example, the ``WithRenumberHarts`` relabels the ``hartId``'s of all the BOOM/Rocket cores.
Then after that is applied to the parameters, the ``WithMultiRoCCHwacha`` mixin assigns a Hwacha accelerator to a particular ``hartId`` (in this case, the ``hartId`` of ``2`` corresponds to the Rocket core).
Finally, the ``WithMultiRoCC`` mixin is called.
This mixin sets the ``BuildRoCC`` key to use the ``MultiRoCCKey`` instead of the default.
Then after that is applied to the parameters, the ``WithMultiRoCCHwacha`` config fragment assigns a Hwacha accelerator to a particular ``hartId`` (in this case, the ``hartId`` of ``2`` corresponds to the Rocket core).
Finally, the ``WithMultiRoCC`` config fragment is called.
This config fragment sets the ``BuildRoCC`` key to use the ``MultiRoCCKey`` instead of the default.
This must be used after all the RoCC parameters are set because it needs to override the ``BuildRoCC`` parameter.
If this is used earlier in the configuration sequence, then MultiRoCC does not work.
This mixin can be changed to put more accelerators on more cores by changing the arguments to cover more ``hartId``'s (i.e. ``WithMultiRoCCHwacha(0,1,3,6,...)``).
This config fragment can be changed to put more accelerators on more cores by changing the arguments to cover more ``hartId``'s (i.e. ``WithMultiRoCCHwacha(0,1,3,6,...)``).
.. [1] Note, in this section "core" and "tile" are used interchangeably but there is subtle distinction between a "core" and "tile" ("tile" contains a "core", L1D/I$, PTW).

2
docs/Customization/IOBinders.rst
View File

@@ -22,4 +22,4 @@ For example, the ``WithSimAXIMemTiedOff`` IOBinder specifies that any ``Top`` wh
These classes are all ``Config`` objects, which can be mixed into the configs to specify IO connection behaviors.
There are two macros for generating these ``Configs``. ``OverrideIOBinder`` overrides any existing behaviors set for a particular IO in the ``Config`` object. This macro is frequently used because typically top-level IOs drive or are driven by only one source, so a composition of ``IOBinders`` does not make sense. The ``ComposeIOBinder`` macro provides the functionality of not overriding existing behaviors.
There are two macros for generating these ``Config``s. ``OverrideIOBinder`` overrides any existing behaviors set for a particular IO in the ``Config`` object. This macro is frequently used because typically top-level IOs drive or are driven by only one source, so a composition of ``IOBinders`` does not make sense. The ``ComposeIOBinder`` macro provides the functionality of not overriding existing behaviors.

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

@@ -3,7 +3,7 @@
Keys, Traits, and Configs
=========================
You have probably seen snippets of Chisel referencing Keys, Traits, and Configs by this point.
You have probably seen snippets of Chisel referencing keys, traits, and configs by this point.
This section aims to elucidate the interactions between these Chisel/Scala components, and provide
best practices for how these should be used to create a parameterized design and configure it.
@@ -36,9 +36,9 @@ Traits
Typically, most custom blocks will need to modify the behavior of some pre-existing block. For example, the GCD widget needs the ``Top`` module to instantiate and connect the widget via Tilelink, generate a top-level ``gcd_busy`` port, and connect that to the module as well. Traits let us do this without modifying the existing code for the ``Top``, and enables compartmentalization of code for different custom blocks.
Top-level traits specify that the ``Top`` has been parameterized to read some custom Key and optionally instantiate and connect a widget defined by that Key. Traits **should not** mandate the instantiation of custom logic. In other words, traits should be written with ``CanHave`` semantics, where the default behavior when the Key is unset is a no-op.
Top-level traits specify that the ``Top`` has been parameterized to read some custom key and optionally instantiate and connect a widget defined by that key. Traits **should not** mandate the instantiation of custom logic. In other words, traits should be written with ``CanHave`` semantics, where the default behavior when the key is unset is a no-op.
Top-level traits should be defined and documented in subprojects, alongside their corresponding Keys. The traits should then be added to the ``Top`` being used by Chipyard.
Top-level traits should be defined and documented in subprojects, alongside their corresponding keys. The traits should then be added to the ``Top`` being used by Chipyard.
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.
@@ -54,19 +54,19 @@ These traits are added to the default ``Top`` in Chipyard.
:start-after: DOC include start: Top
:end-before: DOC include end: Top
Mixins
------
Config Fragments
----------------
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.
Config fragments set the keys to a non-default value. Together, the collection of config fragments 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.
For example, the ``WithGCD`` config fragment is parameterized by the type of GCD widget you want to instantiate. When this config fragment 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/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD mixin
:end-before: DOC include end: GCD mixin
:start-after: DOC include start: GCD config fragment
:end-before: DOC include end: GCD config fragment
We can use this mixin when composing our configs.
We can use this config fragment when composing our configs.
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala

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

@@ -105,12 +105,12 @@ The ``TopModule`` class is the actual RTL that gets synthesized.
And finally, we create a configuration class in ``generators/chipyard/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`` config fragment defined earlier.
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD mixin
:end-before: DOC include end: GCD mixin
:start-after: DOC include start: GCD fragment
:end-before: DOC include end: GCD fragment
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala

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

@@ -12,8 +12,8 @@ uses 16 KiB, 4-way set-associative instruction and data caches. However,
if you use the ``WithNMedCores`` or ``WithNSmallCores`` configurations, you can
configure 4 KiB direct-mapped caches for L1I and L1D.
If you only want to change the size or associativity, there are configuration
mixins for those too. See :ref:`Mixins` for how to add these to a custom ``Config``
If you only want to change the size or associativity, there are config
fragments for those too. See :ref:`Config Fragments` for how to add these to a custom ``Config``.
.. code-block:: scala
@@ -41,7 +41,7 @@ number of channels and number of banks to 0.
The SiFive L2 Cache
-------------------
The default RocketConfig provided in the Chipyard example project uses SiFive's
The default ``RocketConfig`` provided in the Chipyard example project uses SiFive's
InclusiveCache generator to produce a shared L2 cache. In the default
configuration, the L2 uses a single cache bank with 512 KiB capacity and 8-way
set-associativity. However, you can change these parameters to obtain your
@@ -58,11 +58,11 @@ If you do not want to use the L2 cache (say, for a resource-limited embedded
design), you can create a configuration without it. Instead of using the L2
cache, you will instead use RocketChip's TileLink broadcast hub.
To make such a configuration, you can just copy the definition of
``RocketConfig`` but omit the ``WithInclusiveCache`` mixin from the
``RocketConfig`` but omit the ``WithInclusiveCache`` config fragment from the
list of included mixims.
If you want to reduce the resources used even further, you can configure
the Broadcast Hub to use a bufferless design. This mixin is
the Broadcast Hub to use a bufferless design. This config fragment is
``freechips.rocketchip.subsystem.WithBufferlessBroadcastHub``.

2
docs/Customization/index.rst
View File

@@ -11,7 +11,7 @@ These guides will walk you through customization of your system-on-chip:
- Adding custom MMIO widgets to the Chipyard memory system by Tilelink or AXI4, with custom Top-level IOs
- Standard practices for using Keys, Traits, and Configs to parameterize your design
- Standard practices for using keys, traits, and configs to parameterize your design
- Customizing the memory hierarchy

12
docs/Generators/Gemmini.rst
View File

@@ -3,9 +3,9 @@ Gemmini
The Gemmini project is developing a systolic-array based matrix multiplication unit generator for the investigation of software/hardware implications of such integrated SoC accelerators. It is inspired by recent trends in machine learning accelerators for edge and mobile SoCs.
Gemmini is implemented as a RoCC accelerator with non-standard RISC-V custom instructions. The Gemmini unit uses the RoCC port of a Rocket or BOOM `tile`, and by default connects to the memory system through the System Bus (i.e., directly to the L2 cache).
Gemmini is implemented as a RoCC accelerator with non-standard RISC-V custom instructions. The Gemmini unit uses the RoCC port of a Rocket or BOOM `tile`, and by default connects to the memory system through the System Bus (i.e., directly to the L2 cache).
To add a Gemmini unit to an SoC, you should add the ``gemmini.DefaultGemminiConfig`` config mixin to the SoC configurations. To change the configuration of the Gemmini accelerator unit, you can write a custom configuration to replace the ``DefaultGemminiConfig``, which you can view under `generators/gemmini/src/main/scala/configs.scala <https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/configs.scala>`__ to see the possible configuration parameters.
To add a Gemmini unit to an SoC, you should add the ``gemmini.DefaultGemminiConfig`` config fragment to the SoC configurations. To change the configuration of the Gemmini accelerator unit, you can write a custom configuration to replace the ``DefaultGemminiConfig``, which you can view under `generators/gemmini/src/main/scala/configs.scala <https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/configs.scala>`__ to see the possible configuration parameters.
The example Chipyard config includes the following example SoC configuration which includes Gemmini:
@@ -46,12 +46,12 @@ Gemmini Software
------------------
The Gemmini non-standard ISA extension is specified in the `Gemmini repository <https://github.com/ucb-bar/gemmini/blob/master/README.md>`__.
The ISA includes configuration instructions, data movement instructions (from main memory to the Gemmini scratchpad, and from the Gemmini accumulators to main memory), and matrix multiplication execution instructions.
The ISA includes configuration instructions, data movement instructions (from main memory to the Gemmini scratchpad, and from the Gemmini accumulators to main memory), and matrix multiplication execution instructions.
Since Gemmini instructions are not exposed through the GNU binutils assembler, several C macros are provided in order to construct the instruction encodings to call these instructions.
The Gemmini generator includes a C matrix multiplication library which wraps the calls to the custom Gemmini instructions.
The ``software`` directory of the generator includes the aforementioned library and macros, as well as bare-metal tests, and some FireMarshal workloads to run the tests in a Linux environment. In particular, the matrix multiplication C library can be found in the ``software/gemmini-rocc-tests/include/gemmini.h`` file.
The ``software`` directory of the generator includes the aforementioned library and macros, as well as bare-metal tests, and some FireMarshal workloads to run the tests in a Linux environment. In particular, the matrix multiplication C library can be found in the ``software/gemmini-rocc-tests/include/gemmini.h`` file.
The Gemmini generator generates a C header file based on the generator parameters. This header files gets compiled together with the matrix multiplication library to tune library performance. The generated header file can be found under ``software/gemmini-rocc-tests/include/gemmini_params.h``
@@ -64,7 +64,7 @@ To build Gemmini tests:
cd generators/gemmini/software/gemmini-rocc-tests/
./build.sh
Afterwards, the test binaries will be found in ``generators/gemmini/software/gemmini-rocc-tests/build``. Binaries whose names end in ``-baremetal`` are meant to be run in a bare-metal environment, while binaries whose names end in ``-linux`` are meant to run in a Linux environment. You can run the tests either on a cycle-accurate RTL simulator, or on a (much faster) functional ISA simulator called Spike.
The Gemmini generator implements a custom non-standard version of Spike. This implementation is found within the ``esp-tools`` Spike implementation, together with the Hwacha vector accelerator non-standard ISA-extension. In order to use this version of Spike, please make sure to build the ``esp-tools`` software toolchain, as described in :ref:`build-toolchains`.
@@ -80,7 +80,7 @@ Spike is built by default without a commit log. However, if you would like to ad
Alternative SoC Configs
--------------------------
The Gemmini generator includes additional alternative SoC configs (configs that are not in the Chipyard example project).
The Gemmini generator includes additional alternative SoC configs (configs that are not in the Chipyard example project).
If you would like to build one of these alternative SoC configurations which are defined in within the Gemmini project repository, you can run the following commands. These commands are similar to the one required when building a simulation from the example project, but they specify that the location of the configs are in the Gemmini subproject, as opposed to the Chipyard example project:
.. code-block:: shell

4
docs/Generators/Hwacha.rst
View File

@@ -7,9 +7,9 @@ The Hwacha project includes the Hwacha microarchitecture generator, as well as t
For more information on the Hwacha project, please visit the `Hwacha website <http://hwacha.org/>`__.
To add the Hwacha vector unit to an SoC, you should add the ``hwacha.DefaultHwachaConfig`` config mixin to the SoC configurations. The Hwacha vector unit uses the RoCC port of a Rocket or BOOM `tile`, and by default connects to the memory system through the `System Bus` (i.e., directly to the L2 cache).
To add the Hwacha vector unit to an SoC, you should add the ``hwacha.DefaultHwachaConfig`` config fragment to the SoC configurations. The Hwacha vector unit uses the RoCC port of a Rocket or BOOM `tile`, and by default connects to the memory system through the `System Bus` (i.e., directly to the L2 cache).
To change the configuration of the Hwacha vector unit, you can write a custom configuration to replace the ``DefaultHwachaConfig``. You can view the ``DefaultHwachaConfig`` under `generators/hwacha/src/main/scala/configs.scala <https://github.com/ucb-bar/hwacha/blob/master/src/main/scala/configs.scala>`__ to see the possible configuration parameters.
Since Hwacha implements a non-standard RISC-V extension, it requires a unique software toolchain to be able to compile and assemble its vector instructions.
To install the Hwacha toolchain, run the ``./scripts/build-toolchains.sh esp-tools`` command within the root Chipyard directory. This may take a while, and it will install the ``esp-tools-install`` directory within your Chipyard root directory. ``esp-tools`` is a fork of ``riscv-tools`` (formerly a collection of relevant software RISC-V tools) that was enhanced with additional non-standard vector instructions. However, due to the upstreaming of the equivalent RISC-V toolchains, ``esp-tools`` may not be up-to-date with the latest mainline version of the tools included in it.

6
docs/Generators/IceNet.rst
View File

@@ -8,7 +8,7 @@ A diagram of IceNet's microarchitecture is shown below.
.. image:: ../_static/images/nic-design.png
There are four basic parts of the NIC: the :ref:`Controller`, which takes requests
There are four basic parts of the NIC: the :ref:`Controller`, which takes requests
from and sends responses to the CPU; the :ref:`Send Path`, which reads data from
memory and sends it out to the network; the :ref:`Receive Path`, which receives
data from the network and writes it to memory; and, optionally,
@@ -80,8 +80,8 @@ and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you
are confused about the distinction between lazy module and module
implementation, refer to :ref:`Cake Pattern`.
Then add the ``WithIceNIC`` config mixin to your configuration. This will
define ``NICKey``, which IceNIC uses to determine its parameters. The mixin
Then add the ``WithIceNIC`` config fragment to your configuration. This will
define ``NICKey``, which IceNIC uses to determine its parameters. The config fragment
takes two arguments. The ``inBufFlits`` argument is the number of 64-bit flits
that the input packet buffer can hold and the ``usePauser`` argument determines
whether or not the NIC will have a pause handler.

4
docs/Generators/SHA3.rst
View File

@@ -68,9 +68,9 @@ Using a SHA3 Accelerator
------------------------
Since the SHA3 accelerator is designed as a RoCC accelerator,
it can be mixed into a Rocket or BOOM core by overriding the
``BuildRoCC`` key. The configuration mixin is defined in the SHA3
``BuildRoCC`` key. The config fragment is defined in the SHA3
generator. An example configuration highlighting the use of
this mixin is shown here:
this config fragment is shown here:
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala

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

@@ -1,13 +1,13 @@
SiFive Generators
==================
Chipyard includes several open-source generators developed and maintained by `SiFive <https://www.sifive.com/>`__.
Chipyard includes several open-source generators developed and maintained by `SiFive <https://www.sifive.com/>`__.
These are currently organized within two submodules named ``sifive-blocks`` and ``sifive-cache``.
Last-Level Cache Generator
-----------------------------
``sifive-cache`` includes last-level cache geneator. The Chipyard framework uses this last-level cache as an L2 cache. To use this L2 cache, you should add the ``freechips.rocketchip.subsystem.WithInclusiveCache`` mixin to your SoC configuration.
``sifive-cache`` includes last-level cache geneator. The Chipyard framework uses this last-level cache as an L2 cache. To use this L2 cache, you should add the ``freechips.rocketchip.subsystem.WithInclusiveCache`` config fragment to your SoC configuration.
To learn more about configuring this L2 cache, please refer to the :ref:`memory-hierarchy` section.
@@ -16,24 +16,24 @@ Peripheral Devices
``sifive-blocks`` includes multiple peripheral device generators, such as UART, SPI, PWM, JTAG, GPIO and more.
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.
To integrate one of these devices in your SoC, you will need to define a custom config fragment 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 config fragment to set the GPIO address to ``0x10012000``. This address is the start address for the GPIO configuration registers.
.. literalinclude:: ../../generators/chipyard/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/ConfigFragments.scala
:language: scala
:start-after: DOC include start: gpio mixin
:end-before: DOC include end: gpio mixin
Additionally, if the device requires top-level IOs, you will need to define a mixin to change the top-level configuration of your SoC.
Additionally, if the device requires top-level IOs, you will need to define a config fragment 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, 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:
Finally, you add the relevant config fragment to the SoC config. For example:
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GPIORocketConfig
:end-before: DOC include end: GPIORocketConfig
Some of the devices in ``sifive-blocks`` (such as GPIO) may already have pre-defined mixins within the Chipyard example project. You may be able to use these config mixins directly, but you should be aware of their addresses within the SoC address map.
Some of the devices in ``sifive-blocks`` (such as GPIO) may already have pre-defined config fragments within the Chipyard example project. You may be able to use these config fragments directly, but you should be aware of their addresses within the SoC address map.

2
docs/Generators/TestChipIP.rst
View File

@@ -22,7 +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 the ``WithBlockDevice`` config mixin to your configuration.
To add a block device to your design, add the ``WithBlockDevice`` config fragment to your configuration.
TileLink SERDES

2
docs/Simulation/FPGA-Accelerated-Simulation.rst
View File

@@ -55,7 +55,7 @@ Converting a Chipyard config (one in ``chipyard/src/main/scala`` to run in FireS
:end-before: DOC include end: firesimconfig
Only 3 additional config-mixins are needed.
Only 3 additional config fragments are needed.
* ``WithFireSimConfigTweaks`` modifies your design to better fit the FireSim usage model. For example, FireSim designs typically include a UART. Technically, adding this in is optional, but *strongly* recommended.
* ``WithDefaultMemModel`` sets the external memory model in the FireSim simulation. See the FireSim documentation for details.

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

@@ -93,7 +93,7 @@ The ``MODEL`` and ``VLOG_MODEL`` are the top-level class names of the design. No
The ``MODEL_PACKAGE`` is the Scala package (in the Scala code that says ``package ...``) that holds the ``MODEL`` class.
The ``CONFIG`` is the name of the class used for the parameter Config while the ``CONFIG_PACKAGE`` is the Scala package it resides in.
The ``CONFIG`` is the name of the class used for the parameter config while the ``CONFIG_PACKAGE`` is the Scala package it resides in.
The ``GENERATOR_PACKAGE`` is the Scala package that holds the Generator class that elaborates the design.