diff --git a/docs/Advanced-Concepts/CDEs.rst b/docs/Advanced-Concepts/CDEs.rst index b8e130e6..6904106e 100644 --- a/docs/Advanced-Concepts/CDEs.rst +++ b/docs/Advanced-Concepts/CDEs.rst @@ -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``. diff --git a/docs/Advanced-Concepts/Chip-Communication.rst b/docs/Advanced-Concepts/Chip-Communication.rst index 596ccd6d..eff08670 100644 --- a/docs/Advanced-Concepts/Chip-Communication.rst +++ b/docs/Advanced-Concepts/Chip-Communication.rst @@ -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 `__ 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 diff --git a/docs/Advanced-Concepts/Top-Testharness.rst b/docs/Advanced-Concepts/Top-Testharness.rst index 43b0be51..8df37769 100644 --- a/docs/Advanced-Concepts/Top-Testharness.rst +++ b/docs/Advanced-Concepts/Top-Testharness.rst @@ -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`` diff --git a/docs/Advanced-Concepts/index.rst b/docs/Advanced-Concepts/index.rst index af23525a..c13e569b 100644 --- a/docs/Advanced-Concepts/index.rst +++ b/docs/Advanced-Concepts/index.rst @@ -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 diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index f490d2a1..9d7d86d0 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -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``, while the naming convention for a non-additive Config will be ````. +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``, while the naming convention for a non-additive config will be ````. 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``. +The naming convention for an additive mixin or trait is ``CanHave``. 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). diff --git a/docs/Customization/Heterogeneous-SoCs.rst b/docs/Customization/Heterogeneous-SoCs.rst index 8087fd35..6385f3b3 100644 --- a/docs/Customization/Heterogeneous-SoCs.rst +++ b/docs/Customization/Heterogeneous-SoCs.rst @@ -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). diff --git a/docs/Customization/IOBinders.rst b/docs/Customization/IOBinders.rst index 798987b1..59924a0f 100644 --- a/docs/Customization/IOBinders.rst +++ b/docs/Customization/IOBinders.rst @@ -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. diff --git a/docs/Customization/Keys-Traits-Configs.rst b/docs/Customization/Keys-Traits-Configs.rst index bac311c5..0dd20a65 100644 --- a/docs/Customization/Keys-Traits-Configs.rst +++ b/docs/Customization/Keys-Traits-Configs.rst @@ -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 diff --git a/docs/Customization/MMIO-Peripherals.rst b/docs/Customization/MMIO-Peripherals.rst index c1c1a424..4801d4d4 100644 --- a/docs/Customization/MMIO-Peripherals.rst +++ b/docs/Customization/MMIO-Peripherals.rst @@ -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 diff --git a/docs/Customization/Memory-Hierarchy.rst b/docs/Customization/Memory-Hierarchy.rst index 99cc9f77..436a0ea9 100644 --- a/docs/Customization/Memory-Hierarchy.rst +++ b/docs/Customization/Memory-Hierarchy.rst @@ -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``. diff --git a/docs/Customization/index.rst b/docs/Customization/index.rst index 496f4c0a..90d36fda 100644 --- a/docs/Customization/index.rst +++ b/docs/Customization/index.rst @@ -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 diff --git a/docs/Generators/Gemmini.rst b/docs/Generators/Gemmini.rst index fe126f02..80767ce0 100644 --- a/docs/Generators/Gemmini.rst +++ b/docs/Generators/Gemmini.rst @@ -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 `__ 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 `__ 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 `__. -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 diff --git a/docs/Generators/Hwacha.rst b/docs/Generators/Hwacha.rst index ac4f4fdf..1980cddf 100644 --- a/docs/Generators/Hwacha.rst +++ b/docs/Generators/Hwacha.rst @@ -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 `__. -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 `__ 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. diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index b520eb6c..a8595038 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -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. diff --git a/docs/Generators/SHA3.rst b/docs/Generators/SHA3.rst index c8969c3a..92173995 100644 --- a/docs/Generators/SHA3.rst +++ b/docs/Generators/SHA3.rst @@ -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 diff --git a/docs/Generators/SiFive-Generators.rst b/docs/Generators/SiFive-Generators.rst index 35b160f8..68c239c7 100644 --- a/docs/Generators/SiFive-Generators.rst +++ b/docs/Generators/SiFive-Generators.rst @@ -1,13 +1,13 @@ SiFive Generators ================== -Chipyard includes several open-source generators developed and maintained by `SiFive `__. +Chipyard includes several open-source generators developed and maintained by `SiFive `__. 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. diff --git a/docs/Generators/TestChipIP.rst b/docs/Generators/TestChipIP.rst index 0e02c077..f85636b1 100644 --- a/docs/Generators/TestChipIP.rst +++ b/docs/Generators/TestChipIP.rst @@ -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 `_ -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 diff --git a/docs/Simulation/FPGA-Accelerated-Simulation.rst b/docs/Simulation/FPGA-Accelerated-Simulation.rst index ea4f3297..82692643 100644 --- a/docs/Simulation/FPGA-Accelerated-Simulation.rst +++ b/docs/Simulation/FPGA-Accelerated-Simulation.rst @@ -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. diff --git a/docs/Simulation/Software-RTL-Simulation.rst b/docs/Simulation/Software-RTL-Simulation.rst index 9bc236ac..957913e9 100644 --- a/docs/Simulation/Software-RTL-Simulation.rst +++ b/docs/Simulation/Software-RTL-Simulation.rst @@ -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. diff --git a/generators/boom b/generators/boom index 779c62c5..28003f77 160000 --- a/generators/boom +++ b/generators/boom @@ -1 +1 @@ -Subproject commit 779c62c5634847b517be64c554af66829de40067 +Subproject commit 28003f7799fa9ea6cc89b56494dc77a3b427f6c9 diff --git a/generators/chipyard/src/main/scala/ConfigMixins.scala b/generators/chipyard/src/main/scala/ConfigFragments.scala similarity index 92% rename from generators/chipyard/src/main/scala/ConfigMixins.scala rename to generators/chipyard/src/main/scala/ConfigFragments.scala index 8234f0e3..d13f468a 100644 --- a/generators/chipyard/src/main/scala/ConfigMixins.scala +++ b/generators/chipyard/src/main/scala/ConfigFragments.scala @@ -32,7 +32,7 @@ object ConfigValName { import ConfigValName._ // ----------------------- -// Common Parameter Mixins +// Common Config Fragments // ----------------------- class WithBootROM extends Config((site, here, up) => { @@ -40,12 +40,12 @@ class WithBootROM extends Config((site, here, up) => { contentFileName = s"./bootrom/bootrom.rv${site(XLen)}.img") }) -// DOC include start: gpio mixin +// DOC include start: gpio config fragment class WithGPIO extends Config((site, here, up) => { case PeripheryGPIOKey => Seq( GPIOParams(address = 0x10012000, width = 4, includeIOF = false)) }) -// DOC include end: gpio mixin +// DOC include end: gpio config fragment class WithUART extends Config((site, here, up) => { case PeripheryUARTKey => Seq( @@ -80,14 +80,14 @@ class WithTracegenTop extends Config((site, here, up) => { case object MultiRoCCKey extends Field[Map[Int, Seq[Parameters => LazyRoCC]]](Map.empty[Int, Seq[Parameters => LazyRoCC]]) /** - * Mixin to enable different RoCCs based on the hartId + * Config fragment to enable different RoCCs based on the hartId */ class WithMultiRoCC extends Config((site, here, up) => { case BuildRoCC => site(MultiRoCCKey).getOrElse(site(TileKey).hartId, Nil) }) /** - * Mixin to add Hwachas to cores based on hart + * Config fragment to add Hwachas to cores based on hart * * For ex: * Core 0, 1, 2, 3 have been defined earlier @@ -110,7 +110,7 @@ class WithMultiRoCCHwacha(harts: Int*) extends Config((site, here, up) => { /** - * Mixin to add a small Rocket core to the system as a "control" core. + * Config fragment to add a small Rocket core to the system as a "control" core. * Used as an example of a PMU core. */ class WithControlCore extends Config((site, here, up) => { diff --git a/generators/chipyard/src/main/scala/GCD.scala b/generators/chipyard/src/main/scala/GCD.scala index 802520f0..049fa876 100644 --- a/generators/chipyard/src/main/scala/GCD.scala +++ b/generators/chipyard/src/main/scala/GCD.scala @@ -200,8 +200,8 @@ trait CanHavePeripheryGCDModuleImp extends LazyModuleImp { // DOC include end: GCD imp trait -// DOC include start: GCD mixin +// DOC include start: GCD config fragment class WithGCD(useAXI4: Boolean, useBlackBox: Boolean) extends Config((site, here, up) => { case GCDKey => Some(GCDParams(useAXI4 = useAXI4, useBlackBox = useBlackBox)) }) -// DOC include end: GCD mixin +// DOC include end: GCD config fragment