add more to docs | 1st spelling pass | more links | proper formatting
This commit is contained in:
abejgonzalez
@@ -1,55 +1,62 @@
|
||||
Configs, Parameters, Mix-ins, and Everything In Between
|
||||
========================================================
|
||||
|
||||
A significant portion of generators in the ReBAR framework use the Rocket chip parameter system.
|
||||
A significant portion of generators in the REBAR framework use the Rocket Chip parameter system.
|
||||
This parameter system enables for the flexible configuration of the SoC without invasive RTL changes.
|
||||
In order to use the parameter system correctly, we will use several terms and conventions:
|
||||
|
||||
Parameter
|
||||
Parameters
|
||||
--------------------
|
||||
|
||||
TODO: Need to explain up, site, field, and other stuff from Henry's thesis.
|
||||
|
||||
It is important to note that a significant challenge with the Rocket parameter system is being able to identify the correct parameter to use, and the impact that parameter has on the overall system. We are still investigating methods to facilitate parameter exploration and discovery.
|
||||
It is important to note that a significant challenge with the Rocket parameter system is being able to identify the correct parameter to use, and the impact that parameter has on the overall system.
|
||||
We are still investigating methods to facilitate parameter exploration and discovery.
|
||||
|
||||
|
||||
Config
|
||||
Configs
|
||||
---------------------
|
||||
A `Config` is a collection of multiple parameters being set to specific values.
|
||||
Configs are additive, and can override each other.
|
||||
A Config can be composed of other configs.
|
||||
The naming convetion for an additive config is ``With<YourConfig>``, while the naming convention for a non-additive config will be ``<YourConfig>``.
|
||||
Configs can take arguments which will in-turn set parameters in the specific configs.
|
||||
|
||||
Example config:
|
||||
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>``.
|
||||
Configs can take arguments which will in-turn set parameters in the design or reference other parameters in the design (see :ref:`Parameters`).
|
||||
|
||||
:numref:`basic-config-example` shows a basic additive Config 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:
|
||||
.. code-block:: scala
|
||||
|
||||
class WithMyAcceleratorParams extends Config((site, here, up) => {
|
||||
case BusWidthBits => 128
|
||||
case MyAcceleratorKey =>
|
||||
MyAcceleratorConfig(
|
||||
Rows = 2,
|
||||
rows = 2,
|
||||
rowBits = 64,
|
||||
Columns = 16,
|
||||
columns = 16,
|
||||
hartId = 1,
|
||||
some_length = 256,
|
||||
)
|
||||
someLength = 256)
|
||||
})
|
||||
|
||||
Example config which uses a higher level config:
|
||||
This next example (:numref:`complex-config-example`) shows a "higher-level" additive Config that uses prior parameters that were set to derive other parameters.
|
||||
|
||||
.. _complex-config-example:
|
||||
.. code-block:: scala
|
||||
|
||||
class WithMyMoreComplexAcceleratorConfig extends Config((site, here, up) => {
|
||||
case BusWidthBits => 128
|
||||
case MyAcceleratorKey =>
|
||||
MyAcceleratorConfig(
|
||||
Rows = 2,
|
||||
rowBits = site(SystemBusKey).beatBits,
|
||||
hartId = up(RocketTilesKey, site).length,
|
||||
)
|
||||
hartId = up(RocketTilesKey, site).length)
|
||||
})
|
||||
|
||||
Example of additive configs:
|
||||
:numref:`top-level-config` 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).
|
||||
Thus, the order of the parameters being set will first start with the ``DefaultExampleConfig``, then ``WithMyAcceleratorParams``, then ``WithMyMoreComplexAcceleratorConfig``.
|
||||
|
||||
.. _top-level-config:
|
||||
.. code-block:: scala
|
||||
|
||||
class SomeAdditiveConfig extends Config(
|
||||
@@ -58,13 +65,15 @@ Example of additive configs:
|
||||
new DefaultExampleConfig
|
||||
)
|
||||
|
||||
|
||||
Cake Pattern
|
||||
-------------------------
|
||||
The cake pattern is a scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes refered to as dependancy injection). It is used in the Rocket chip SoC library and ReBAR framework in merging multiple system components and IO interfaces into a large system component.
|
||||
|
||||
Example of using the cake pattern to merge multiple system components into a single top-level design, extending a basic Rocket SoC:
|
||||
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 REBAR framework in merging multiple system components and IO interfaces into a large system component.
|
||||
|
||||
:numref:`cake-example` shows a Rocket Chip based SoC that merges multiple system components (BootROM, UART, etc) into a single top-level design.
|
||||
|
||||
.. _cake-example:
|
||||
.. code-block:: scala
|
||||
|
||||
class MySoC(implicit p: Parameters) extends RocketSubsystem
|
||||
@@ -78,9 +87,14 @@ Example of using the cake pattern to merge multiple system components into a sin
|
||||
//Additional top-level specific instantiations or wiring
|
||||
}
|
||||
|
||||
|
||||
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 convetion for an additive mix-in is ``Has<YourMixin>``.
|
||||
|
||||
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 show in :numref:`cake-example` where things such as ``HasPeripherySerial`` 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.
|
||||
|
||||
Reference in New Issue
Block a user