From c478d056e7532e00190b6eff49029749cac360ba Mon Sep 17 00:00:00 2001
From: "-T.K.-" <t_k_233@outlook.com>
Date: Tue, 13 Jun 2023 18:40:14 -0700
Subject: [PATCH] ADD: add documentation

---
 .../fragments/PeripheralFragments.scala       | 61 ++++++++++++++++---
 1 file changed, 53 insertions(+), 8 deletions(-)

diff --git a/generators/chipyard/src/main/scala/config/fragments/PeripheralFragments.scala b/generators/chipyard/src/main/scala/config/fragments/PeripheralFragments.scala
index 3c9cc670..6cfb49ce 100644
--- a/generators/chipyard/src/main/scala/config/fragments/PeripheralFragments.scala
+++ b/generators/chipyard/src/main/scala/config/fragments/PeripheralFragments.scala
@@ -21,28 +21,48 @@ import testchipip._
 
 import chipyard.{ExtTLMem}
 
-// Set the bootrom to the Chipyard bootrom
-class WithBootROM extends Config((site, here, up) => {
+/**
+  * Config fragment for adding a BootROM to the SoC
+  * 
+  * @param address the address of the BootROM device
+  * @param size the size of the BootROM
+  * @param hang the power-on reset vector, i.e. the program counter will be set to this value on reset
+  * @param contentFileName the path to the BootROM image
+  */
+class WithBootROM(address: BigInt = 0x10000, size: Int = 0x10000, hang: BigInt = 0x10040, contentFileName: String = s"${site(TargetDirKey)}/bootrom.rv${site(XLen)}.img") extends Config((site, here, up) => {
   case BootROMLocated(x) => up(BootROMLocated(x), site)
       .map(_.copy(
-        address = 0x10000,
-        size = 0x10000,
-        hang = 0x10040,
-        contentFileName = s"${site(TargetDirKey)}/bootrom.rv${site(XLen)}.img"
+        address = address,
+        size = size,
+        hang = hand,
+        contentFileName = contentFileName
       ))
 })
 
-// DOC include start: gpio config fragment
+/**
+ * Config fragment for adding a GPIO peripheral device to the SoC
+ * 
+ * @param address the address of the GPIO device
+ * @param width the number of pins of the GPIO device
+ */
 class WithGPIO(address: BigInt = 0x10010000, width: Int = 4) extends Config ((site, here, up) => {
   case PeripheryGPIOKey => up(PeripheryGPIOKey) ++ Seq(
     GPIOParams(address = address, width = width, includeIOF = false))
 })
-// DOC include end: gpio config fragment
 
+/**
+ * Config fragment for removing all UART peripheral devices from the SoC
+ */
 class WithNoUART extends Config((site, here, up) => {
   case PeripheryUARTKey => Nil
 })
 
+/**
+  * Config fragment for adding a UART peripheral device to the SoC
+  *
+  * @param address the address of the UART device
+  * @param baudrate the baudrate of the UART device
+  */
 class WithUART(address: BigInt = 0x10020000, baudrate: BigInt = 115200) extends Config ((site, here, up) => {
   case PeripheryUARTKey => up(PeripheryUARTKey) ++ Seq(
     UARTParams(address = address, nTxEntries = 256, nRxEntries = 256, initBaudRate = baudrate))
@@ -52,17 +72,34 @@ class WithUARTFIFOEntries(txEntries: Int, rxEntries: Int) extends Config((site,
   case PeripheryUARTKey => up(PeripheryUARTKey).map(_.copy(nTxEntries = txEntries, nRxEntries = rxEntries))
 })
 
+/**
+  * Config fragment for adding a SPI peripheral device with Execute-in-Place capability to the SoC
+  *
+  * @param address the address of the SPI controller
+  * @param fAddress the address of the Execute-in-Place (XIP) region of the SPI flash memory
+  * @param size the size of the Execute-in-Place (XIP) region of the SPI flash memory
+  */
 class WithSPIFlash(address: BigInt = 0x10030000, fAddress: BigInt = 0x20000000, size: BigInt = 0x10000000) extends Config((site, here, up) => {
   // Note: the default size matches freedom with the addresses below
   case PeripherySPIFlashKey => up(PeripherySPIFlashKey) ++ Seq(
     SPIFlashParams(rAddress = address, fAddress = fAddress, fSize = size))
 })
 
+/**
+  * Config fragment for adding a SPI peripheral device to the SoC
+  *
+  * @param address the address of the SPI controller
+  */
 class WithSPI(address: BigInt = 0x10031000) extends Config((site, here, up) => {
   case PeripherySPIKey => up(PeripherySPIKey) ++ Seq(
     SPIParams(rAddress = address))
 })
 
+/**
+  * Config fragment for adding a I2C peripheral device to the SoC
+  *
+  * @param address the address of the I2C controller
+  */
 class WithI2C(address: BigInt = 0x10040000) extends Config((site, here, up) => {
   case PeripheryI2CKey => up(PeripheryI2CKey) ++ Seq(
     I2CParams(address = address, controlXType = AsynchronousCrossing(), intXType = AsynchronousCrossing())
@@ -77,6 +114,14 @@ class WithDMIDTM extends Config((site, here, up) => {
   case ExportDebug => up(ExportDebug, site).copy(protocols = Set(DMI))
 })
 
+/**
+  * Config fragment for adding a JTAG Debug Module to the SoC
+  *
+  * @param idcodeVersion the version of the JTAG protocol the Debug Module supports
+  * @param partNum the part number of the Debug Module
+  * @param manufId the 11-bit JEDEC Designer ID of the chip manufacturer
+  * @param debugIdleCycles the number of cycles the Debug Module waits before responding to a request
+  */
 class WithJTAGDTMKey(idcodeVersion: Int = 2, partNum: Int = 0x000, manufId: Int = 0x489, debugIdleCycles: Int = 5) extends Config((site, here, up) => {
   case JtagDTMKey => new JtagDTMConfig (
     idcodeVersion = idcodeVersion,