add literal references | cleanup firrtl-transform-docs [ci skip]

common.mk

@@ -53,10 +53,12 @@ HARNESS_CONF_FLAGS = -thconf $(HARNESS_SMEMS_CONF)
 TOP_TARGETS = $(TOP_FILE) $(TOP_SMEMS_CONF) $(TOP_ANNO) $(TOP_FIR) $(sim_top_blackboxes)
 HARNESS_TARGETS = $(HARNESS_FILE) $(HARNESS_SMEMS_CONF) $(HARNESS_ANNO) $(HARNESS_FIR) $(sim_harness_blackboxes)
 
+# DOC include start: FirrtlCompiler
 .INTERMEDIATE: firrtl_temp
 $(TOP_TARGETS) $(HARNESS_TARGETS): firrtl_temp
 firrtl_temp: $(FIRRTL_FILE) $(ANNO_FILE)
 	cd $(base_dir) && $(SBT) "project tapeout" "runMain barstools.tapeout.transforms.GenerateTopAndHarness -o $(TOP_FILE) -tho $(HARNESS_FILE) -i $(FIRRTL_FILE) --syn-top $(TOP) --harness-top $(VLOG_MODEL) -faf $(ANNO_FILE) -tsaof $(TOP_ANNO) -tdf $(sim_top_blackboxes) -tsf $(TOP_FIR) -thaof $(HARNESS_ANNO) -hdf $(sim_harness_blackboxes) -thf $(HARNESS_FIR) $(REPL_SEQ_MEM) $(HARNESS_CONF_FLAGS) -td $(build_dir)"
+# DOC include end: FirrtlCompiler
 
 # This file is for simulation only. VLSI flows should replace this file with one containing hard SRAMs
 MACROCOMPILER_MODE ?= --mode synflops

docs/Customization/Firrtl-Transforms.rst

@@ -3,21 +3,24 @@
 Adding a Firrtl Transform
 =========================
 
-After generating a ``.fir`` file from the Chisel generator, this ``.fir`` file is passed to
-FIRRTL. FIRRTL then goes ahead and modifies the ``.fir`` IR with a series of tranforms that can modify
-the circuit and then converts it to Verilog.
+After writing the Chisel RTL, you can make further modifications by adding transforms during the FIRRTL compilation phase.
+As mentioned in Section <>, transforms are modifications that happen on the FIRRTL IR that can modify a circuit.
+Transforms are a powerful tool to take in the FIRRTL IR that is emitted from Chisel and run analysis (https://www.youtube.com/watch?v=FktjrjRVBoY) or convert the circuit into a new form.
 
 Where to add transforms
 -----------------------
 
-The main location to add tranforms is within the ``tools/barstools`` project.
-Inside the ``tranforms`` package, the FIRRTL compiler is called twice,
-first on the top-level circuit, then on the test harness. This is because we want to separate out
-the harness and all the modules associated with it from the top-level design under test.
+In Chipyard, the FIRRTL compiler is called multiple times to create a "Top" file that has the DUT and a "Harness" file that has all harness collateral.
+This done by the ``tapeout`` SBT project (located in ``tools/barstools/tapeout``) which calls ``GenerateTopAndHarness`` (a function that wraps the multiple FIRRTL compiler calls and extra transforms).
 
-If you want to add transforms to just modify the DUT, you can add them to ``topTransforms``.
+.. literalinclude:: ../../common.mk
+    :language: make
+    :start-after: DOC include start: FirrtlCompiler
+    :end-before: DOC include end: FirrtlCompiler
 
-If you want to add transforms to just modify the test harness, you can add them to ``harnessTransforms``.
+If you look inside of the `tools/barstools/tapeout/src/main/scala/transforms/Generate.scala <https://github.com/ucb-bar/barstools/blob/master/tapeout/src/main/scala/transforms/Generate.scala>`__ file,
+you can see that FIRRTL invoked twice, once for the "Top" and once for the "Harness". If you want to add transforms to just modify the DUT, you can add them to ``topTransforms``.
+Otherwise, if you want to add transforms to just modify the test harness, you can add them to ``harnessTransforms``.
 
 Examples of transforms
 ----------------------
@@ -26,11 +29,20 @@ There are multiple examples of transforms that you can apply and are spread acro
 Within FIRRTL there is a default set of supported transforms located in https://github.com/freechipsproject/firrtl/tree/master/src/main/scala/firrtl/transforms.
 This includes transforms that can flatten modules (``Flatten``), group modules together (``GroupAndDedup``), and more.
 
-Transforms can be standalone or can take annotations as input. Annotations are FIRRTL specific ``json`` files that
-are used to pass information into FIRRTL transforms (e.g. what modules to flatten, group, etc). Annotations can be added to the code by
-adding them to your Chisel source (which will generate the ``json`` code for you) or by creating the ``.json`` file and adding it to the FIRRTL compiler.
+Transforms can be standalone or can take annotations as input. Annotations are used to pass information between FIRRTL transforms. This includes information on
+what modules to flatten, group, and more. Annotations can be added to the code by
+adding them to your Chisel source or by creating the ``.json`` file and adding it to the FIRRTL compiler (note: adding to the Chisel source will add the ``json`` snippet into the build system for you).
+**The recommended way to annotate something is to do it in the Chisel source**.
 
-Here is an example of grouping a series of modules by specifying the ``.json`` file:
+Here is an example of adding an annotation within the Chisel source. This example is taken from the
+``firechip`` project and uses an annotation to mark BOOM's register file for optimization:
+
+.. literalinclude:: ../../generators/firechip/src/main/scala/TargetMixins.scala
+    :language: make
+    :start-after: DOC include start: ChiselAnnotation
+    :end-before: DOC include end: ChiselAnnotation
+
+Here is an example of grouping a series of modules by specifying the ``.json`` file.
 
 .. code-block:: json
 
@@ -46,19 +58,16 @@ Here is an example of grouping a series of modules by specifying the ``.json`` f
        }
    ]
 
+In this case, the specific syntax depends on the type of annotation. The best way to figure out
+what the ``json`` file should contain is to first try to annotate in the Chisel
+source and then see what the ``json`` output gives and copy that format.
 
-Once created then you can add this to the FIRRTL compiler by modifying ``common.mk`` and adding the particu
-
-.. code-block:: none
-
-	-faf yourAnnoFile.json
-
+Once ``yourAnnoFile.json`` is created then you can add ``-faf yourAnnoFile.json`` to the FIRRTL compiler invocation in ``common.mk``.
 
+.. literalinclude:: ../../common.mk
+    :language: make
+    :start-after: DOC include start: FirrtlCompiler
+    :end-before: DOC include end: FirrtlCompiler
 
 If you are interested in writing FIRRTL transforms please refer to the FIRRTL documentation located here:
 https://github.com/freechipsproject/firrtl/wiki.
-
-The main Chipyard tranforms that are applied to the top and are located in the ``tools/barstools``.
-
-- Talk about .json annotations
-

generators/firechip/src/main/scala/TargetMixins.scala

@@ -108,6 +108,7 @@ trait ExcludeInvalidBoomAssertions extends LazyModuleImp {
 trait CanHaveMultiCycleRegfileImp {
   val outer: utilities.HasBoomAndRocketTiles
   val boomCores = outer.boomTiles.map(tile => tile.module.core)
+  // DOC include start: ChiselAnnotation
   boomCores.foreach({ core =>
     core.iregfile match {
       case irf: boom.exu.RegisterFileSynthesizable => annotate(MemModelAnnotation(irf.regfile))
@@ -119,6 +120,7 @@ trait CanHaveMultiCycleRegfileImp {
       case _ => Nil
     }
   })
+  // DOC include end: ChiselAnnotation
 
   outer.rocketTiles.foreach({ tile =>
     annotate(MemModelAnnotation(tile.module.core.rocketImpl.rf.rf))