Update docs

docs/Customization/Keys-Traits-Configs.rst

@@ -16,7 +16,7 @@ Keys specify some parameter which controls some custom widget. Keys should typic
 
 Keys should be defined and documented in sub-projects, since they generally deal with some specific block, and not system-level integration. (We make an exception for the example GCD widget).
 
-.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
     :language: scala
     :start-after: DOC include start: GCD key
     :end-before: DOC include end: GCD key
@@ -24,7 +24,7 @@ Keys should be defined and documented in sub-projects, since they generally deal
 The object within a key is typically a ``case class XXXParams``, which defines a set of parameters which some block accepts. For example, the GCD widget's ``GCDParams`` parameterizes its address, operand widths, whether the widget should be connected by Tilelink or AXI4, and whether the widget should use the blackbox-Verilog implementation, or the Chisel implementation.
 
 
-.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
     :language: scala
     :start-after: DOC include start: GCD params
     :end-before: DOC include end: GCD params
@@ -42,14 +42,14 @@ Top-level traits should be defined and documented in subprojects, alongside thei
 
 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.
 
-.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
     :language: scala
     :start-after: DOC include start: GCD lazy trait
     :end-before: DOC include end: GCD imp trait
 
 These traits are added to the default ``Top`` in Chipyard.
 
-.. literalinclude:: ../../generators/example/src/main/scala/Top.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
     :language: scala
     :start-after: DOC include start: Top
     :end-before: DOC include end: Top
@@ -57,49 +57,22 @@ These traits are added to the default ``Top`` in Chipyard.
 Mixins
 ------
 
-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 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.
 
 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.
 
-.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
     :language: scala
     :start-after: DOC include start: GCD mixin
     :end-before: DOC include end: GCD mixin
 
 We can use this mixin when composing our configs.
 
-.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
     :language: scala
     :start-after: DOC include start: GCDTLRocketConfig
     :end-before: DOC include end: GCDTLRocketConfig
 
-
-BuildTop
---------
-
-The ``BuildTop`` key is special, because sometimes, we need to instantiate ``TestHarness`` modules to interface with a custom widget. The ``BuildTop`` key provides a function which can call some method of the Top to instantiate these ``TestHarness`` modules. Since the ``BuildTop`` key is called from the ``TestHarness``, these modules will appear in the ``TestHarness``. The config system also lets the ``BuildTop`` key look recursively into previous definitions of itself. This enables composability of the ``Top`` configurations.
-
-For example, conside a config that contains the mixins ``WithGPIO ++ WithTSI``. We need to instantiate the TSI serial adapter, and connect it to the ``success`` signal of our ``TestHarness``. We also need to instantiate the GPIO pins, and tie their inputs to 0 in the ``TestHarness``, since we currently cannot drive the GPIOs in simulation.
-
-.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
-    :language: scala
-    :start-after: DOC include start: tsi mixin
-    :end-before: DOC include end: tsi mixin
-
-
-.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
-    :language: scala
-    :start-after: DOC include start: gpio mixin
-    :end-before: DOC include end: gpio mixin
-
-When ``WithGPIO ++ WithTSI`` is evaluated right to left, the call to ``up(BuildTop, site)`` in ``WithGPIO`` will reference the function defined in the ``BuildTop`` key of ``WithTSI``. Thus, at elaboration time, when the ``BuildTop`` function is called by the ``TestHarness``, first the ``BuildTop`` function in ``WithTSI`` will be evaluated. This connects the ``success`` signal of the ``TestHarness`` to the ``SerialAdapter`` enabled by ``WithTSI``. Then, the rest of the code in the ``BuildTop`` function of ``WithGPIO`` will execute, tieing off the top-level GPIO input pins. Thus the evaluation of the ``BuildTop`` functions in a completed config is "right-to-left", matching how the evaluation of the mixins at compile-time is also "right-to-left".
-
-.. warning::
-   In some cases, the ordering and duplication of mixins which extend ``BuildTop`` will have unintended consequences.
-   For example, ``WithTSI ++ WithTSI`` will attempt to generate and connect two ``SimSerial`` widgets in the ``TestHarness``,
-   which will likely break the simulation.
-   In general, you should avoid attaching multiple mixins which interface to the same top-level ports.
-
 .. note::
    Readers who want more information on the configuration system may be interested in reading :ref:`cdes`.