UPF Generation + docs, final review ready

common.mk

@@ -20,7 +20,8 @@ HELP_COMPILATION_VARIABLES += \
 "   ENABLE_CUSTOM_FIRRTL_PASS = if set, enable custom firrtl passes (SFC lowers to LowFIRRTL & MFC converts to Verilog)" \
 "   ENABLE_YOSYS_FLOW         = if set, add compilation flags to enable the vlsi flow for yosys(tutorial flow)" \
 "   EXTRA_CHISEL_OPTIONS      = additional options to pass to the Chisel compiler" \
-"   EXTRA_FIRRTL_OPTIONS      = additional options to pass to the FIRRTL compiler"
+"   EXTRA_FIRRTL_OPTIONS      = additional options to pass to the FIRRTL compiler" \
+"   ASPECT_ARGS				  = additional aspect flows that will be run based on inputted pointers (such as UPF gen)"
 
 EXTRA_GENERATOR_REQS ?= $(BOOTROM_TARGETS)
 EXTRA_SIM_CXXFLAGS   ?=
@@ -29,6 +30,11 @@ EXTRA_SIM_SOURCES    ?=
 EXTRA_SIM_REQS       ?=
 ENABLE_CUSTOM_FIRRTL_PASS += $(ENABLE_YOSYS_FLOW)
 
+ifneq ($(ASPECTS), )
+	comma = ,
+	ASPECT_ARGS = $(foreach aspect, $(subst $(comma), , $(ASPECTS)), --with-aspect $(aspect))
+endif
+
 #----------------------------------------------------------------------------
 HELP_SIMULATION_VARIABLES += \
 "   EXTRA_SIM_FLAGS        = additional runtime simulation flags (passed within +permissive)" \
@@ -112,7 +118,7 @@ $(FIRRTL_FILE) $(ANNO_FILE) $(CHISEL_LOG_FILE) &: $(SCALA_SOURCES) $(SCALA_BUILD
 		--name $(long_name) \
 		--top-module $(MODEL_PACKAGE).$(MODEL) \
 		--legacy-configs $(CONFIG_PACKAGE):$(CONFIG) \
-		$(UPF_ASPECT) \
+		$(ASPECT_ARGS) \
 		$(EXTRA_CHISEL_OPTIONS)) | tee $(CHISEL_LOG_FILE))
 
 define mfc_extra_anno_contents

docs/VLSI/Advanced-Usage.rst

@@ -109,15 +109,19 @@ The simulation configuration (e.g. binaries) can be edited for your design. See
 
 UPF Generation Flow
 -------------------------------
-To generate UPF for any design, first modify the UPFInputs in generators/chipyard/src/main/scala/upf/UPFInputs.scala to fit your design power specifications.
+This VLSI flow experimentally supports generating Chisel-based `UPF <https://vlsitutorials.com/upf-low-power-vlsi/>`__ files using `Chisel Aspects <https://javadoc.io/doc/edu.berkeley.cs/chisel3_2.13/latest/chisel3/aop/Aspect.html>`__.
 
-This involves filling in the upfInfo list with PowerDomainInput objects representing all the power domains you want in your design, along with specifying hierarchy and domain attributes.
+To generate UPF for any design, first modify the ``UPFInputs`` object in ``generators/chipyard/src/main/scala/upf/UPFInputs.scala`` to fit your design power specifications.
 
-The given example in UPFInputs corresponds to a dual-core Rocket config with 3 power domains (1 parent and 2 children).
+This involves filling in the ``upfInfo`` list with ``PowerDomainInput`` objects representing all the power domains you want in your design, along with specifying hierarchy and domain attributes.
+
+The given example in ``UPFInputs`` corresponds to a dual-core Rocket config with 3 power domains (1 parent domain with all uncore modules and 2 children corresponding to the Rocket tiles).
 
 To run the flow:
 
 .. code-block:: shell
     
     cd chipyard/vlsi
     make verilog ASPECTS=chipyard.upf.ChipTopUPFAspect
+
+The output UPF files will be dumped in ``vlsi/generated-src/upf``.

generators/chipyard/src/main/scala/upf/ChipTopUPF.scala

@@ -1,14 +1,13 @@
 // See LICENSE for license details
 package chipyard.upf
 
-import chipyard.TestHarness
-import freechips.rocketchip.diplomacy.LazyModule
-
 import scala.collection.mutable.ListBuffer
-
 import scalax.collection.mutable.Graph
 import scalax.collection.GraphPredef._, scalax.collection.GraphEdge._
 
+import chipyard.TestHarness
+import freechips.rocketchip.diplomacy.LazyModule
+
 object ChipTopUPF {
 
   def default: UPFFunc.UPFFunction = {

generators/chipyard/src/main/scala/upf/UPFAspect.scala

@@ -5,7 +5,6 @@ import chisel3.aop.Aspect
 import firrtl.{AnnotationSeq}
 import chipyard.TestHarness
 import freechips.rocketchip.stage.phases.TargetDirKey
-
 import freechips.rocketchip.diplomacy.LazyModule
 
 abstract class UPFAspect[T <: TestHarness](upf: UPFFunc.UPFFunction) extends Aspect[T] {

generators/chipyard/src/main/scala/upf/UPFGen.scala

@@ -1,13 +1,14 @@
+// See LICENSE for license details
 package chipyard.upf
 
-import freechips.rocketchip.diplomacy.LazyModule
-
 import java.io.FileWriter
 import java.nio.file.{Paths, Files}
 import scala.collection.mutable.ListBuffer
 import scalax.collection.mutable.Graph
 import scalax.collection.GraphPredef._, scalax.collection.GraphEdge._
 
+import freechips.rocketchip.diplomacy.LazyModule
+
 case class PowerDomain (val name: String, val modules: ListBuffer[LazyModule], 
                         val isTop: Boolean, val isGated: Boolean,
                         val highVoltage: Double, val lowVoltage: Double) {

generators/chipyard/src/main/scala/upf/UPFInputs.scala

@@ -1,8 +1,14 @@
+// See LICENSE for license details
 package chipyard.upf
 
-
+/** outputs are dumped in vlsi/generated-src/upf */
 object UPFInputs {
 
+    /**
+     * UPF info
+     * each PowerDomainInput represents a desired power domain
+     * each input will contain all the necessary info to describe a power domain in UPF, including hierarchy
+     */
     val upfInfo = List(
         PowerDomainInput(name="PD_top", isTop=true, moduleList=List("DigitalTop"),
                          parentPD="", childrenPDs=List("PD_RocketTile1", "PD_RocketTile2"),
@@ -15,7 +21,14 @@ object UPFInputs {
                          isGated=false, highVoltage=3.9, lowVoltage=3.2),
     )
 
-    // PST info
+
+    /**
+      * PST info
+      * experimental Power State Table input, used to gate power domains based on specified power states
+      * place names of all power domains to be gated in the domains list
+      * states will map different keywords (arbitrary strings) to a binary on or off (1 or 0) to form a power state
+      * order of domains in list corresponds to order of values in each states mapping
+      */
     val domains = List("PD_top", "PD_RocketTile1", "PD_RocketTile2")
     val states = Map(
         "ON" -> "1, 1, 1",
@@ -24,6 +37,18 @@ object UPFInputs {
 
 }
 
+/**
+  * Representation of a power domain used to generate UPF.
+  *
+  * @param name name of the power domain.
+  * @param isTop if the power domain is the top level or not.
+  * @param moduleList names of all the Verilog modules belonging to this power domain.
+  * @param parentPD the name of the parent power domain to this one.
+  * @param childrenPDs names of all the children power domains to this one.
+  * @param isGated if the power domain is gated or not.
+  * @param highVoltage voltage value of the high voltage rail (currently, gated nets have access to high voltage since they are optimized to save power).
+  * @param lowVoltage voltage value of the low voltage rail (currently, non-gated nets default to the low voltage rail).
+  */
 case class PowerDomainInput(name: String, isTop: Boolean, moduleList: List[String], 
                             parentPD: String, childrenPDs: List[String], 
                             isGated: Boolean, highVoltage: Double, lowVoltage: Double)

vlsi/Makefile

@@ -51,11 +51,6 @@ else
 	OBJ_DIR          ?= $(vlsi_dir)/$(VLSI_OBJ_DIR)/$(long_name)-$(TOP)
 endif
 
-ifneq ($(ASPECTS), )
-	comma = ,
-	UPF_ASPECT = $(foreach aspect, $(subst $(comma), , $(ASPECTS)), --with-aspect $(aspect))
-endif
-
 #########################################################################################
 # general rules
 #########################################################################################