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

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