Rename Config Mixins to Fragments (#451)

* [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>

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).

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.

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

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

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``.
 
 

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