From 71db99911b8c27461f8d111dd41b06d1ca3d10bf Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 17:54:47 -0700 Subject: [PATCH] extra cleanup [ci skip] --- docs/Customization/Firrtl-Transforms.rst | 65 ++++++++++++------- docs/Tools/FIRRTL.rst | 1 + .../src/main/scala/TargetMixins.scala | 2 - 3 files changed, 41 insertions(+), 27 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 4d947522..64aba247 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -3,14 +3,16 @@ Adding a Firrtl Transform ========================= -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. +Similar to how LLVM IR passes can perform transformations and optimizations on software, FIRRTL transforms can +modify Chisel-elaborated RTL. +As mentioned in Section :ref:`firrtl`, 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 or convert the circuit into a new form. Where to add transforms ----------------------- -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. +In Chipyard, the FIRRTL compiler is called multiple times to create a "Top" file that contains the DUT and a "Harness" file containing the test harness, which instantiates the DUT. +The "Harness" file does not contain the DUT's module definition or any of its submodules. 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). .. literalinclude:: ../../common.mk @@ -19,7 +21,7 @@ This done by the ``tapeout`` SBT project (located in ``tools/barstools/tapeout`` :end-before: DOC include end: FirrtlCompiler If you look inside of the `tools/barstools/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``. +you can see that FIRRTL is 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 @@ -31,38 +33,51 @@ This includes transforms that can flatten modules (``Flatten``), group modules t 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**. +adding them to your Chisel source or by creating a serialized annotation ``json`` file and adding it to the FIRRTL compiler +(note: annotating the Chisel source will automatically serialize the annotation as a ``json`` snippet into the build system for you). +**The recommended way to annotate something is to do it in the Chisel source, but not all annotation types have Chisel APIs**. -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: +Here is an example of adding a ``DontTouchAnnotation`` within the Chisel source. This annotation +makes sure that a particular signal is not removed by the "Dead Code Elimination" pass in FIRRTL: -.. literalinclude:: ../../generators/firechip/src/main/scala/TargetMixins.scala - :language: make - :start-after: DOC include start: ChiselAnnotation - :end-before: DOC include end: ChiselAnnotation +.. code-block:: scala -Here is an example of grouping a series of modules by specifying the ``.json`` file. + class TopModule extends Module { + ... + val submod = Module(new Submodule) + ... + } + + class Submodule extends Module { + ... + val some_signal := ... + annotate(new ChiselAnnotation { + def toFirrtl = DontTouchAnnotation(some_signal.toNamed) + }) + + // or use the wrapper for this + // chisel3.experimental.dontTouch(some_signal) + ... + } + +Here is an example of the ``DontTouchAnnotation`` when it is serialized: .. code-block:: json [ { - "class": "firrtl.transforms.GroupAnnotation", - "components": [ - "BeagleChipTop.BeagleChipTop.instance1", - "BeagleChipTop.BeagleChipTop.instance2", - ], - "newModule": "NewModule", - "newInstance": "newModInst" + "class": "firrtl.transforms.DontTouchAnnotation", + "target": "~TopModule|Submodule>some_signal" } ] -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. +In this case, the specific syntax depends on the type of annotation and its fields. +One of the easier ways to figure out the serialized syntax is to first try and find a Chisel +annotation to add to the code. Then you can look at the collateral that is generated from the +build system, find the ``*.anno.json``, and find the proper syntax for the annotation. -Once ``yourAnnoFile.json`` is created then you can add ``-faf yourAnnoFile.json`` to the FIRRTL compiler invocation in ``common.mk``. +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 diff --git a/docs/Tools/FIRRTL.rst b/docs/Tools/FIRRTL.rst index 23f39f16..b850b39e 100644 --- a/docs/Tools/FIRRTL.rst +++ b/docs/Tools/FIRRTL.rst @@ -1,3 +1,4 @@ +.. _firrtl: FIRRTL ================================ diff --git a/generators/firechip/src/main/scala/TargetMixins.scala b/generators/firechip/src/main/scala/TargetMixins.scala index 9a8dd739..f36cf021 100644 --- a/generators/firechip/src/main/scala/TargetMixins.scala +++ b/generators/firechip/src/main/scala/TargetMixins.scala @@ -108,7 +108,6 @@ 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)) @@ -120,7 +119,6 @@ trait CanHaveMultiCycleRegfileImp { case _ => Nil } }) - // DOC include end: ChiselAnnotation outer.rocketTiles.foreach({ tile => annotate(MemModelAnnotation(tile.module.core.rocketImpl.rf.rf))