Merge pull request #796 from tymcauley/heterogeneous-doc-patches

Heterogeneous doc patches

docs/Customization/Heterogeneous-SoCs.rst

@@ -17,8 +17,8 @@ The following example shows a dual core BOOM with a single core Rocket.
 
 .. literalinclude:: ../../generators/chipyard/src/main/scala/config/HeteroConfigs.scala
     :language: scala
-    :start-after: DOC include start: DualBoomAndRocket
-    :end-before: DOC include end: DualBoomAndRocket
+    :start-after: DOC include start: DualBoomAndSingleRocket
+    :end-before: DOC include end: DualBoomAndSingleRocket
 
 
 Adding Hwachas
@@ -48,14 +48,37 @@ An example is shown below with two BOOM cores, and one Rocket tile with a RoCC a
     :start-after: DOC include start: DualBoomAndRocketOneHwacha
     :end-before: DOC include end: DualBoomAndRocketOneHwacha
 
-The ``WithMultiRoCCHwacha`` config fragment assigns a Hwacha accelerator to a particular ``hartId`` (in this case, the ``hartId`` of ``2`` corresponds to the Rocket core).
+The ``WithMultiRoCCHwacha`` config fragment assigns a Hwacha accelerator to a particular ``hartId`` (in this case, the ``hartId`` of ``0`` 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 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,...)``).
 
+Since config fragments are applied from right-to-left (or bottom-to-top as they are formatted here), the right-most config fragment specifying a core (which is ``freechips.rocketchip.subsystem.WithNBigCores`` in the example above) gets the first hart ID.
+Consider this config:
+
+.. code-block:: scala
+
+    class RocketThenBoomHartIdTestConfig extends Config(
+      new boom.common.WithNLargeBooms(2) ++
+      new freechips.rocketchip.subsystem.WithNBigCores(3) ++
+      new chipyard.config.AbstractConfig)
+
+This specifies an SoC with three Rocket cores and two BOOM cores.
+The Rocket cores would have hart IDs 0, 1, and 2, while the BOOM cores would have hard IDs 3 and 4.
+On the other hand, consider this config which reverses the order of those two fragments:
+
+.. code-block:: scala
+
+    class BoomThenRocketHartIdTestConfig extends Config(
+      new freechips.rocketchip.subsystem.WithNBigCores(3) ++
+      new boom.common.WithNLargeBooms(2) ++
+      new chipyard.config.AbstractConfig)
+
+This also specifies an SoC with three Rocket cores and two BOOM cores, but because the BOOM config fragment is evaluated before the Rocket config fragment, the hart IDs are reversed.
+The BOOM cores would have hart IDs 0 and 1, while the Rocket cores would have hard IDs 2, 3, and 4.
 
 .. [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).
     For many places in the documentation, we usually use "core" to mean "tile" (doesn't make a large difference but worth the mention).

generators/chipyard/src/main/scala/config/HeteroConfigs.scala

@@ -20,23 +20,35 @@ class HwachaLargeBoomAndHwachaRocketConfig extends Config(
   new chipyard.config.AbstractConfig)
 // DOC include end: BoomAndRocketWithHwacha
 
-// DOC include start: DualBoomAndRocketOneHwacha
 class LargeBoomAndHwachaRocketConfig extends Config(
   new chipyard.config.WithMultiRoCC ++                                  // support heterogeneous rocc
-  new chipyard.config.WithMultiRoCCHwacha(1) ++                         // put hwacha on hart-1 (rocket)
+  new chipyard.config.WithMultiRoCCHwacha(0) ++                         // put hwacha on hart-0 (rocket)
   new hwacha.DefaultHwachaConfig ++                                     // set default hwacha config keys
   new boom.common.WithNLargeBooms(1) ++                                 // add 1 boom core
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++                // add 1 rocket core
   new chipyard.config.AbstractConfig)
-// DOC include end: DualBoomAndRocketOneHwacha
 
+// DOC include start: DualBoomAndRocketOneHwacha
+class DualLargeBoomAndHwachaRocketConfig extends Config(
+  new chipyard.config.WithMultiRoCC ++                                  // support heterogeneous rocc
+  new chipyard.config.WithMultiRoCCHwacha(0) ++                         // put hwacha on hart-0 (rocket)
+  new hwacha.DefaultHwachaConfig ++                                     // set default hwacha config keys
+  new boom.common.WithNLargeBooms(2) ++                                 // add 2 boom cores
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++                // add 1 rocket core
+  new chipyard.config.AbstractConfig)
+// DOC include end: DualBoomAndRocketOneHwacha
 
-// DOC include start: DualBoomAndRocket
 class DualLargeBoomAndDualRocketConfig extends Config(
   new boom.common.WithNLargeBooms(2) ++                   // add 2 boom cores
   new freechips.rocketchip.subsystem.WithNBigCores(2) ++  // add 2 rocket cores
   new chipyard.config.AbstractConfig)
-// DOC include end: DualBoomAndRocket
+
+// DOC include start: DualBoomAndSingleRocket
+class DualLargeBoomAndSingleRocketConfig extends Config(
+  new boom.common.WithNLargeBooms(2) ++                   // add 2 boom cores
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++  // add 1 rocket core
+  new chipyard.config.AbstractConfig)
+// DOC include end: DualBoomAndSingleRocket
 
 class LargeBoomAndRocketWithControlCoreConfig extends Config(
   new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ // Add a small "control" core