From eae76451594a8d7aca9f4079ace11a9ae87ac8ca Mon Sep 17 00:00:00 2001
From: alonamid <alonamid@eecs.berkeley.edu>
Date: Wed, 25 Sep 2019 11:56:26 -0700
Subject: [PATCH] sifive generators

---
 docs/Customization/Memory-Hierarchy.rst       |  2 +
 docs/Generators/SiFive-Generators.rst         | 43 +++++++++++++++++++
 .../example/src/main/scala/ConfigMixins.scala |  4 ++
 .../src/main/scala/RocketConfigs.scala        |  2 +
 4 files changed, 51 insertions(+)
 create mode 100644 docs/Generators/SiFive-Generators.rst

diff --git a/docs/Customization/Memory-Hierarchy.rst b/docs/Customization/Memory-Hierarchy.rst
index 39955310..207e0775 100644
--- a/docs/Customization/Memory-Hierarchy.rst
+++ b/docs/Customization/Memory-Hierarchy.rst
@@ -1,3 +1,5 @@
+.. _memory-hierarchy:
+
 Memory Hierarchy
 ===============================
 
diff --git a/docs/Generators/SiFive-Generators.rst b/docs/Generators/SiFive-Generators.rst
new file mode 100644
index 00000000..1ddab4f2
--- /dev/null
+++ b/docs/Generators/SiFive-Generators.rst
@@ -0,0 +1,43 @@
+SiFive Generators
+==================
+
+Chipyard includes several open-source generators developed and maintained by `SiFive <https://www.sifive.com/>`__. 
+These are currently organized within two submodules named ``sifive-blocks`` and ``sifive-cache``.
+
+L2 Cache
+---------
+
+``sifive-cache`` includes an L2 cache geneator. To use this L2 cache, you should add the ``freechips.rocketchip.subsystem.WithInclusiveCache`` mixin to your SoC configuration.
+To learn more about configuring this L2, please refer to the :ref:`memory-hierarchy` section.
+
+
+Perihperal Devices
+-------------------
+``sifive-blocks`` includes multiple peripheral device generators. These include UART, SPI, PWM, JTAG, GPIO and more.
+
+These peripheral devices usually affect the memory map of the SoC, and its top-level IO as well.
+To integrate one of these devices in your SoC, you will need to define a custom mixin with the approriate address for the device using the Rocket Chip parameter system. As an example, for a GPIO device you could add the following mixin to set the GPIO address to ``0x10012000``. 
+
+.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
+    :language: scala
+    :start-after: DOC include start: WithGPIO
+    :end-before: DOC include end: WithGPIO
+
+Additionally, if the device requires top-level IOs, you will need to define a mixin to change the top-level configuration of your SoC.
+When adding a top-level IO, you should also be aware of whether it interacts with the test-harness.
+For example, a GPIO device would require a GPIO pin, and therefore we would write a mixin to augment the top level as follows:
+
+.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
+    :language: scala
+    :start-after: DOC include start: WithGPIOTop
+    :end-before: DOC include end: WithGPIOTop
+
+
+Finally, you add the relevant config mixin to the SoC config. For example:
+
+.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
+    :language: scala
+    :start-after: DOC include start: GPIORocketConfig
+    :end-before: DOC include end: GPIORocketConfig
+
+Some of the devices in ``sifive-blocks`` (such as GPIO) may already have pre-defined mixins within the Chipyard example project. You may be able to use these config mixin directly, but you should be aware of their addresses within the SoC address map. 
diff --git a/generators/example/src/main/scala/ConfigMixins.scala b/generators/example/src/main/scala/ConfigMixins.scala
index a829db22..9d92d896 100644
--- a/generators/example/src/main/scala/ConfigMixins.scala
+++ b/generators/example/src/main/scala/ConfigMixins.scala
@@ -37,6 +37,7 @@ class WithBootROM extends Config((site, here, up) => {
     contentFileName = s"./bootrom/bootrom.rv${site(XLen)}.img")
 })
 
+// DOC include start: WithGPIO
 /**
  * Class to add in GPIO
  */
@@ -44,6 +45,7 @@ class WithGPIO extends Config((site, here, up) => {
   case PeripheryGPIOKey => List(
     GPIOParams(address = 0x10012000, width = 4, includeIOF = false))
 })
+// DOC include end: WithGPIO
 
 // -----------------------------------------------
 // BOOM and/or Rocket Top Level System Parameter Mixins
@@ -107,6 +109,7 @@ class WithSimBlockDeviceTop extends Config((site, here, up) => {
   }
 })
 
+// DOC include start: WithGPIOTop
 /**
  * Class to specify a top level BOOM and/or Rocket system with GPIO
  */
@@ -121,6 +124,7 @@ class WithGPIOTop extends Config((site, here, up) => {
     top
   }
 })
+// DOC include end: WithGPIOTop
 
 // ------------------
 // Multi-RoCC Support
diff --git a/generators/example/src/main/scala/RocketConfigs.scala b/generators/example/src/main/scala/RocketConfigs.scala
index 2275549f..a50ad4a7 100644
--- a/generators/example/src/main/scala/RocketConfigs.scala
+++ b/generators/example/src/main/scala/RocketConfigs.scala
@@ -73,6 +73,7 @@ class BlockDeviceModelRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: GPIORocketConfig
 class GPIORocketConfig extends Config(
   new WithGPIO ++                                          // add GPIOs to the peripherybus
   new WithGPIOTop ++                                       // use top with GPIOs
@@ -80,6 +81,7 @@ class GPIORocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: GPIORocketConfig
 
 class DualCoreRocketConfig extends Config(
   new WithTop ++