From 5f19697618b7f42e4c0df54bfc9a4030c83b4f01 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 31 May 2019 17:51:05 -0700 Subject: [PATCH 1/5] first attempt at explaining heter systems --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 127 +++++++++++++++++++++ docs/Advanced-Usage/index.rst | 11 ++ docs/index.rst | 4 + 3 files changed, 142 insertions(+) create mode 100644 docs/Advanced-Usage/Heterogeneous-SoCs.rst create mode 100644 docs/Advanced-Usage/index.rst diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst new file mode 100644 index 00000000..2ee9cba4 --- /dev/null +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -0,0 +1,127 @@ +Heterogeneous SoCs +=============================== + +The REBAR framework involves multiple cores and accelerators that can be composed in arbitrary ways. +This discussion will focus on how you combine Rocket, BOOM and Hwacha in particular ways to create a unique SoC. + +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. +When used together you can create a heterogeneous system. +The following example shows a dual core BOOM with a single Rocket. + +.. code-block:: scala + + class DualCoreBoomAndRocketConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new boom.system.WithRenumberHarts ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +In this example, the ``WithN...Cores(X)`` mixins set up particular parameters for the duplicated core. +For example, the Rocket tiles will be "BigCores" while BOOM has some generic parameters set in its mixin. +In BOOMs case, we override these base core parameters to create multiple "DefaultBoom"s with calling ``DefaultBoomConfig`` after the multi-core instantiation. +This mixin applies to all the BOOM cores in the system and sets up 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``. +This is done with ``WithRenumberHarts`` (which 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 that type of core in the system. +Thus, without the renumber mixin, each set of cores is labeled starting from zero. + +Another 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. + +.. code-block:: scala + + // create 6 cores (4 boom and 2 rocket) + class WithHeterCoresSetup extends Config((site, here, up) => { + case BoomTilesKey => { + val boomTile0 = BoomTileParams(...) // params for boom core 0 + val boomTile1 = BoomTileParams(...) // params for boom core 1 + val boomTile2 = BoomTileParams(...) // params for boom core 2 + val boomTile3 = BoomTileParams(...) // params for boom core 3 + boomTile0 ++ boomTile1 ++ boomTile2 ++ boomTile3 + } + + case RocketTilesKey => { + val rocketTile0 = RocketTileParams(...) // params for rocket core 0 + val rocketTile1 = RocketTileParams(...) // params for rocket core 1 + rocketTile0 ++ rocketTile1 + } + }) + +Then you could use this new mixin like the following. + +.. code-block:: scala + + class SixCoreConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new WithHeterCoresSetup ++ + new freechips.rocketchip.system.BaseConfig) + +Note, in this setup you most likely dont need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the params yourself. + +Adding Hwachas +------------------------------------------- + +Adding a Hwacha accelerator is as easy as adding the ``DefaultHwachaConfig`` so that it can setup the Hwacha parameters and add itself to the ``BuildRoCC`` parameter. +An example of adding a Hwacha to all tiles in the system is below. + +.. code-block:: scala + + class DualCoreBoomAndRocketWithHwachasConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new hwacha.DefaultHwachaConfig ++ + new boom.system.WithRenumberHarts ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +In this example, Hwachas are added to both BOOM's and to the Rocket tile. +All with the same Hwacha parameters. + +Assigning Accelerators to Specific Tiles with MultiRoCC +------------------------------------------------------- + +Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a Mixin 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 attached to a Hwacha. + +.. code-block:: scala + + class DualCoreBoomAndOneHwachaRocketConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new WithMultiRoCC ++ + new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket + new boom.system.WithRenumberHarts ++ + new hwacha.DefaultHwachaConfig ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +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(0)`` is used to assign to ``hartId`` zero a Hwacha (in this case ``hartId`` zero is Rocket). +Finally, the ``WithMultiRoCC`` mixin is called. +This mixin 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,...)``). diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst new file mode 100644 index 00000000..6aa2a195 --- /dev/null +++ b/docs/Advanced-Usage/index.rst @@ -0,0 +1,11 @@ +Advanced Usage +================================ + +The following sections are advanced topics about how to use REBAR and special features of the framework. +They expect you to know about Chisel, Parameters, Configs, etc. + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started: + + Heterogeneous-SoCs diff --git a/docs/index.rst b/docs/index.rst index ce083f2c..019a6991 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,10 @@ New to Chipyard? Jump to the :ref:`Getting Started` page for more info. :numbered: VLSI/index + :maxdepth: 3 + :caption: Advanced Usage: + :numbered: + Advanced-Usage/index Indices and tables ================== From c61713d807c07d6435210e6a636f2a1cd9851c39 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 21 Jun 2019 11:52:00 -0700 Subject: [PATCH 2/5] removed extra core in names | misc cleanup --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 24 +++++++++---------- docs/Advanced-Usage/index.rst | 2 +- .../example/src/main/scala/Configs.scala | 6 ++--- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 2ee9cba4..596ba59b 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -1,7 +1,7 @@ Heterogeneous SoCs =============================== -The REBAR framework involves multiple cores and accelerators that can be composed in arbitrary ways. +The Chipyard framework involves multiple cores and accelerators that can be composed in arbitrary ways. This discussion will focus on how you combine Rocket, BOOM and Hwacha in particular ways to create a unique SoC. Creating a Rocket and BOOM System @@ -10,11 +10,11 @@ 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. When used together you can create a heterogeneous system. -The following example shows a dual core BOOM with a single Rocket. +The following example shows a dual core BOOM with a single core Rocket. .. code-block:: scala - class DualCoreBoomAndRocketConfig extends Config( + class DualBoomAndOneRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new boom.system.WithRenumberHarts ++ @@ -33,8 +33,8 @@ This mixin applies to all the BOOM cores in the system and sets up the parameter 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``. This is done with ``WithRenumberHarts`` (which 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 that type of core in the system. -Thus, without the renumber mixin, each set of cores is labeled starting from zero. +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``. Another 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. @@ -68,7 +68,7 @@ Then you could use this new mixin like the following. new WithHeterCoresSetup ++ new freechips.rocketchip.system.BaseConfig) -Note, in this setup you most likely dont need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the params yourself. +Note, in this setup you most likely don't need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the tile parameters yourself. Adding Hwachas ------------------------------------------- @@ -78,7 +78,7 @@ An example of adding a Hwacha to all tiles in the system is below. .. code-block:: scala - class DualCoreBoomAndRocketWithHwachasConfig extends Config( + class DualBoomAndRocketWithHwachasConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new hwacha.DefaultHwachaConfig ++ @@ -90,25 +90,25 @@ An example of adding a Hwacha to all tiles in the system is below. new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -In this example, Hwachas are added to both BOOM's and to the Rocket tile. +In this example, Hwachas are added to both BOOM tiles and to the Rocket tile. All with the same Hwacha parameters. Assigning Accelerators to Specific Tiles with MultiRoCC ------------------------------------------------------- -Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a Mixin that provides support for adding RoCC accelerators to specific tiles in your SoC. +Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a mixin 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 attached to a Hwacha. +An example is shown below with two BOOM cores, and one Rocket tile with a Hwacha attached. .. code-block:: scala - class DualCoreBoomAndOneHwachaRocketConfig extends Config( + class DualBoomAndOneHwachaRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new WithMultiRoCC ++ new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket - new boom.system.WithRenumberHarts ++ + new boom.system.WithRenumberHarts(rocketFirst = true) ++ new hwacha.DefaultHwachaConfig ++ new boom.common.WithRVC ++ new boom.common.DefaultBoomConfig ++ diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst index 6aa2a195..62dd11aa 100644 --- a/docs/Advanced-Usage/index.rst +++ b/docs/Advanced-Usage/index.rst @@ -1,7 +1,7 @@ Advanced Usage ================================ -The following sections are advanced topics about how to use REBAR and special features of the framework. +The following sections are advanced topics about how to use Chipyard and special features of the framework. They expect you to know about Chisel, Parameters, Configs, etc. .. toctree:: diff --git a/generators/example/src/main/scala/Configs.scala b/generators/example/src/main/scala/Configs.scala index d6ff3432..4b5352d3 100644 --- a/generators/example/src/main/scala/Configs.scala +++ b/generators/example/src/main/scala/Configs.scala @@ -205,7 +205,7 @@ class GPIOBoomAndRocketConfig extends Config( new WithGPIOBoomRocketTop ++ new BaseBoomAndRocketConfig) -class DualCoreBoomAndOneRocketConfig extends Config( +class DualBoomAndOneRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new boom.system.WithRenumberHarts ++ @@ -216,12 +216,12 @@ class DualCoreBoomAndOneRocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -class DualCoreBoomAndOneHwachaRocketConfig extends Config( +class DualBoomAndOneHwachaRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new WithMultiRoCC ++ new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket - new boom.system.WithRenumberHarts ++ + new boom.system.WithRenumberHarts(rocketFirst = true) ++ new hwacha.DefaultHwachaConfig ++ new boom.common.WithRVC ++ new boom.common.DefaultBoomConfig ++ From b3eeb70045ce08f4d5582cc1feeb5cfcb0cff0bf Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Sun, 23 Jun 2019 22:58:34 -0700 Subject: [PATCH 3/5] clarifications --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 596ba59b..1ac91633 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -25,13 +25,12 @@ The following example shows a dual core BOOM with a single core Rocket. new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -In this example, the ``WithN...Cores(X)`` mixins set up particular parameters for the duplicated core. -For example, the Rocket tiles will be "BigCores" while BOOM has some generic parameters set in its mixin. -In BOOMs case, we override these base core parameters to create multiple "DefaultBoom"s with calling ``DefaultBoomConfig`` after the multi-core instantiation. -This mixin applies to all the BOOM cores in the system and sets up the parameters for each. +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 ``DefaultBoomConfig`` is added to override the default parameters with a "normal" sized out-of-order core. +This mixin 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``. +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). This is done with ``WithRenumberHarts`` (which 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``. @@ -68,7 +67,7 @@ Then you could use this new mixin like the following. new WithHeterCoresSetup ++ new freechips.rocketchip.system.BaseConfig) -Note, in this setup you most likely don't need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the tile parameters yourself. +Note, in this setup you need to specify the ``hartId`` of each core in the "TileParams", where each ``hartId`` is unique. Adding Hwachas ------------------------------------------- From 9fc0b9393cd040a0a2a7c8fb65fa32850c56a3ef Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Mon, 24 Jun 2019 14:32:49 -0700 Subject: [PATCH 4/5] more clarity on defaults --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 1ac91633..4afb6f20 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -26,7 +26,7 @@ The following example shows a dual core BOOM with a single core Rocket. new freechips.rocketchip.system.BaseConfig) 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 ``DefaultBoomConfig`` is added to override the default parameters with a "normal" sized out-of-order core. +However, for BOOM, an extra mixin called ``DefaultBoomConfig`` 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. Great! Now you have a heterogeneous setup with BOOMs and Rockets. From 44b1412c5e840330c92d1a98e5f98c87c3070465 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Tue, 25 Jun 2019 09:22:06 -0700 Subject: [PATCH 5/5] clarify hwacha=rocc | alternative clarification --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 4afb6f20..96a7e40e 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -35,7 +35,7 @@ This is done with ``WithRenumberHarts`` (which can label the Rocket 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``. -Another option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core. +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. .. code-block:: scala @@ -98,7 +98,7 @@ Assigning Accelerators to Specific Tiles with MultiRoCC Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a mixin 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 Hwacha attached. +An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached. .. code-block:: scala