diff --git a/docs/Advanced-Usage/DTM-Debugging.rst b/docs/Advanced-Usage/DTM-Debugging.rst index 839e36a..787a73a 100644 --- a/docs/Advanced-Usage/DTM-Debugging.rst +++ b/docs/Advanced-Usage/DTM-Debugging.rst @@ -3,7 +3,7 @@ Debugging with DTM/JTAG By default, Chipyard is not setup to use the Debug Test Module (DTM) to bringup the core. Instead, Chipyard uses TSI commands to bringup the core (which normally results in a faster simulation). -TSI simulations use the SimSerial interface to directly write the test binary into memory, while the DTM +TSI simulations use the SimSerial interface to directly write the test binary into memory, while the DTM executes a small loop of code to write the test binary byte-wise into memory. However, if you want to use JTAG, you must do the following steps to setup a DTM enabled system. @@ -13,13 +13,10 @@ Creating a DTM/JTAG Config First, a DTM config must be created for the system that you want to create. This involves specifying the SoC top-level to add a DTM as well as configuring that DTM to use JTAG. -.. code-block:: scala - - class DTMBoomConfig extends Config( - new WithDTMTop ++ - new WithBootROM ++ - new WithJtagDTM ++ - new boom.common.SmallBoomConfig) +.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala + :language: scala + :start-after: DOC include start: JtagRocket + :end-before: DOC include end: JtagRocket In this example, the ``WithDTMTop`` mixin specifies that the top-level SoC will instantiate a DTM. The ``WithJtagDTM`` will configure that instantiated DTM to use JTAG as the bringup method (note: this can be removed if you want a DTM-only bringup). diff --git a/docs/Advanced-Usage/Resources.rst b/docs/Advanced-Usage/Resources.rst index 788e43b..6af7283 100644 --- a/docs/Advanced-Usage/Resources.rst +++ b/docs/Advanced-Usage/Resources.rst @@ -1,8 +1,9 @@ Accessing Scala Resources =============================== -A simple way to copy over a source file to the build directory to be used for a simulation compile or VLSI flow is to use the ``addResource`` functions given by FIRRTL. -It can be used in the following way: +A simple way to copy over a source file to the build directory to be used for a simulation compile or VLSI flow is to use the ``addResource`` function given by FIRRTL. +An example of its use can be seen in `generators/testchipip/src/main/scala/SerialAdapter.scala `_. +Here is the example inlined: .. code-block:: scala diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 1d0aa81..2d93f2b 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -8,8 +8,6 @@ In order to use the parameter system correctly, we will use several terms and co Parameters -------------------- -TODO: Need to explain up, site, field, and other stuff from Henry's thesis. - It is important to note that a significant challenge with the Rocket parameter system is being able to identify the correct parameter to use, and the impact that parameter has on the overall system. We are still investigating methods to facilitate parameter exploration and discovery. diff --git a/docs/Customization/Boot-Process.rst b/docs/Customization/Boot-Process.rst index 0557b8b..d23fae8 100644 --- a/docs/Customization/Boot-Process.rst +++ b/docs/Customization/Boot-Process.rst @@ -7,11 +7,12 @@ SoC boots a Linux kernel and the changes you can make to customize this process. BootROM and RISC-V Frontend Server ---------------------------------- -The first instructions to run when the SoC is powered on are those stored in -the BootROM. The assembly for the BootROM code is located in +The BootROM contains both the first instructions to run when the SoC is powered on as well as the +Device Tree Binary (dtb) which details the components of the system. +The assembly for the BootROM code is located in `generators/testchipip/src/main/resources/testchipip/bootrom/bootrom.S `_. -The BootROM address space starts at ``0x10000`` and execution starts at address -``0x10040``, which is marked by the ``_hang`` label in the BootROM assembly. +The BootROM address space starts at ``0x10000`` (determined by the ``BootROMParams`` key in the configuration) and execution starts at address +``0x10040`` (given by the linker script and reset vector in the ``BootROMParams``), which is marked by the ``_hang`` label in the BootROM assembly. The Chisel generator encodes the assembled instructions into the BootROM hardware at elaboration time, so if you want to change the BootROM code, you diff --git a/docs/Customization/Heterogeneous-SoCs.rst b/docs/Customization/Heterogeneous-SoCs.rst index c1a6a00..88454c6 100644 --- a/docs/Customization/Heterogeneous-SoCs.rst +++ b/docs/Customization/Heterogeneous-SoCs.rst @@ -12,18 +12,10 @@ Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCo When used together you can create a heterogeneous system. The following example shows a dual core BOOM with a single core Rocket. -.. code-block:: scala - - class DualBoomAndOneRocketConfig extends Config( - new WithTop ++ - new WithBootROM ++ - new boom.system.WithRenumberHarts ++ - new boom.common.WithRVC ++ - new boom.common.LargeBoomConfig ++ - new boom.system.WithNBoomCores(2) ++ - new freechips.rocketchip.subsystem.WithoutTLMonitors ++ - new freechips.rocketchip.subsystem.WithNBigCores(1) ++ - new freechips.rocketchip.system.BaseConfig) +.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala + :language: scala + :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 ``LargeBoomConfig`` is added to override the default parameters with a different set of more common default parameters. @@ -75,19 +67,10 @@ 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 DualBoomAndRocketWithHwachasConfig extends Config( - new WithTop ++ - new WithBootROM ++ - new hwacha.DefaultHwachaConfig ++ - new boom.system.WithRenumberHarts ++ - new boom.common.WithRVC ++ - new boom.common.LargeBoomConfig ++ - new boom.system.WithNBoomCores(2) ++ - new freechips.rocketchip.subsystem.WithoutTLMonitors ++ - new freechips.rocketchip.subsystem.WithNBigCores(1) ++ - new freechips.rocketchip.system.BaseConfig) +.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala + :language: scala + :start-after: DOC include start: BoomAndRocketWithHwacha + :end-before: DOC include end: BoomAndRocketWithHwacha In this example, Hwachas are added to both BOOM tiles and to the Rocket tile. All with the same Hwacha parameters. @@ -100,24 +83,13 @@ Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on 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. -.. code-block:: scala - - class DualBoomAndOneHwachaRocketConfig extends Config( - new WithTop ++ - new WithBootROM ++ - new WithMultiRoCC ++ - new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket - new boom.system.WithRenumberHarts(rocketFirst = true) ++ - new hwacha.DefaultHwachaConfig ++ - new boom.common.WithRVC ++ - new boom.common.LargeBoomConfig ++ - new boom.system.WithNBoomCores(2) ++ - new freechips.rocketchip.subsystem.WithoutTLMonitors ++ - new freechips.rocketchip.subsystem.WithNBigCores(1) ++ - new freechips.rocketchip.system.BaseConfig) +.. literalinclude:: ../../generators/example/src/main/scala/HeteroConfigs.scala + :language: scala + :start-after: DOC include start: DualBoomAndRocketOneHwacha + :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(0)`` is used to assign to ``hartId`` zero a Hwacha (in this case ``hartId`` zero is Rocket). +Then after that is applied to the parameters, the ``WithMultiRoCCHwacha`` is used to assign to a Hwacha accelerator to a particular ``hartId`` (in this case the ``hartId`` corresponding to 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. diff --git a/docs/Customization/Memory-Hierarchy.rst b/docs/Customization/Memory-Hierarchy.rst index 7864ddc..3995531 100644 --- a/docs/Customization/Memory-Hierarchy.rst +++ b/docs/Customization/Memory-Hierarchy.rst @@ -105,7 +105,7 @@ the Broadcast Hub to use a bufferless design. The Outer Memory System ----------------------- -The L2 coherence agent (either L2 cache of Broadcast Hub) makes requests to +The L2 coherence agent (either L2 cache or Broadcast Hub) makes requests to an outer memory system consisting of an AXI4-compatible DRAM controller. The default configuration uses a single memory channel, but you can configure diff --git a/docs/Generators/BOOM.rst b/docs/Generators/BOOM.rst index 6dcdb41..79cc0a5 100644 --- a/docs/Generators/BOOM.rst +++ b/docs/Generators/BOOM.rst @@ -2,7 +2,7 @@ Berkeley Out-of-Order Machine (BOOM) ============================================== The `Berkeley Out-of-Order Machine (BOOM) `__ is a synthesizable and parameterizable open source RV64GC RISC-V core written in the Chisel hardware construction language. -It serves as a drop-in replacement to the Rocket core given by Rocket Chip. +It serves as a drop-in replacement to the Rocket core given by Rocket Chip (replaces the RocketTile with a BoomTile). BOOM is heavily inspired by the MIPS R10k and the Alpha 21264 out-of-order processors. Like the R10k and the 21264, BOOM is a unified physical register file design (also known as “explicit register renaming”). Conceptually, BOOM is broken up into 10 stages: Fetch, Decode, Register Rename, Dispatch, Issue, Register Read, Execute, Memory, Writeback and Commit. diff --git a/generators/example/src/main/scala/HeteroConfigs.scala b/generators/example/src/main/scala/HeteroConfigs.scala index 6f7cf8b..a9443c2 100644 --- a/generators/example/src/main/scala/HeteroConfigs.scala +++ b/generators/example/src/main/scala/HeteroConfigs.scala @@ -28,6 +28,7 @@ class SmallBoomAndRocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include start: BoomAndRocketWithHwacha class HwachaLargeBoomAndHwachaRocketConfig extends Config( new WithTop ++ new WithBootROM ++ @@ -38,6 +39,7 @@ class HwachaLargeBoomAndHwachaRocketConfig extends Config( new boom.common.WithNBoomCores(1) ++ new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include end: BoomAndRocketWithHwacha class RoccLargeBoomAndRoccRocketConfig extends Config( new WithTop ++ @@ -60,6 +62,7 @@ class DualLargeBoomAndRocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include start: DualBoomAndRocketOneHwacha class DualLargeBoomAndHwachaRocketConfig extends Config( new WithTop ++ new WithBootROM ++ @@ -71,6 +74,7 @@ class DualLargeBoomAndHwachaRocketConfig extends Config( new boom.common.WithNBoomCores(2) ++ new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include end: DualBoomAndRocketOneHwacha class LargeBoomAndRV32RocketConfig extends Config( new WithTop ++ @@ -83,6 +87,7 @@ class LargeBoomAndRV32RocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include start: DualBoomAndRocket class DualLargeBoomAndDualRocketConfig extends Config( new WithTop ++ new WithBootROM ++ @@ -92,3 +97,4 @@ class DualLargeBoomAndDualRocketConfig extends Config( new boom.common.WithNBoomCores(2) ++ // 2 boom cores new freechips.rocketchip.subsystem.WithNBigCores(2) ++ // 2 rocket cores new freechips.rocketchip.system.BaseConfig) +// DOC include end: DualBoomAndRocket diff --git a/generators/example/src/main/scala/RocketConfigs.scala b/generators/example/src/main/scala/RocketConfigs.scala index 5f3164c..2275549 100644 --- a/generators/example/src/main/scala/RocketConfigs.scala +++ b/generators/example/src/main/scala/RocketConfigs.scala @@ -31,6 +31,7 @@ class RoccRocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include start: JtagRocket class jtagRocketConfig extends Config( new WithDTMTop ++ // use top with dtm new freechips.rocketchip.subsystem.WithJtagDTM ++ // add jtag/DTM module to coreplex @@ -38,6 +39,7 @@ class jtagRocketConfig extends Config( new freechips.rocketchip.subsystem.WithInclusiveCache ++ new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) +// DOC include end: JtagRocket // DOC include start: PWMRocketConfig class PWMRocketConfig extends Config(