From 4c443d20776c8ec944ccd7780785279313e98266 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 10:26:40 -0700 Subject: [PATCH 1/7] start firrtl transform docs [skip ci] --- docs/Customization/Firrtl-Transforms.rst | 64 ++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/Customization/Firrtl-Transforms.rst diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst new file mode 100644 index 00000000..0cc396ad --- /dev/null +++ b/docs/Customization/Firrtl-Transforms.rst @@ -0,0 +1,64 @@ +.. _firrtl-transforms: + +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. + +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. + +If you want to add transforms to just modify the DUT, you can add them to ``topTransforms``. + +If you want to add transforms to just modify the test harness, you can add them to ``harnessTransforms``. + +Examples of transforms +---------------------- + +There are multiple examples of transforms that you can apply and are spread across the FIRRTL ecosystem. +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. + +Here is an example of grouping a series of modules by specifying the ``.json`` file: + +.. code-block:: json + + [ + { + "class": "firrtl.transforms.GroupAnnotation", + "components": [ + "BeagleChipTop.BeagleChipTop.instance1", + "BeagleChipTop.BeagleChipTop.instance2", + ], + "newModule": "NewModule", + "newInstance": "newModInst" + } + ] + + +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 + + + +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 + From 9199a02e1e8a9517336e1c425d3f5e92fb23bcc6 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 11:18:25 -0700 Subject: [PATCH 2/7] add literal references | cleanup firrtl-transform-docs [ci skip] --- common.mk | 2 + docs/Customization/Firrtl-Transforms.rst | 59 +++++++++++-------- .../src/main/scala/TargetMixins.scala | 2 + 3 files changed, 38 insertions(+), 25 deletions(-) diff --git a/common.mk b/common.mk index 442c62f9..112285c2 100644 --- a/common.mk +++ b/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 diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 0cc396ad..4d947522 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/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 `__ 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 @@ -44,21 +56,18 @@ Here is an example of grouping a series of modules by specifying the ``.json`` f "newModule": "NewModule", "newInstance": "newModInst" } - ] + ] +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 - diff --git a/generators/firechip/src/main/scala/TargetMixins.scala b/generators/firechip/src/main/scala/TargetMixins.scala index f36cf021..9a8dd739 100644 --- a/generators/firechip/src/main/scala/TargetMixins.scala +++ b/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)) From e90d53e31eef6437f6d8d3e1340f02587f575ec6 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 13:20:16 -0700 Subject: [PATCH 3/7] add tranforms to index [ci skip] --- docs/Customization/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Customization/index.rst b/docs/Customization/index.rst index c0432e73..7592ff83 100644 --- a/docs/Customization/index.rst +++ b/docs/Customization/index.rst @@ -17,3 +17,4 @@ Hit next to get started! Adding-An-Accelerator Memory-Hierarchy Boot-Process + Firrtl-Transforms From 71db99911b8c27461f8d111dd41b06d1ca3d10bf Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 17:54:47 -0700 Subject: [PATCH 4/7] 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)) From c6bdeda9ed3be61cd225de5520cfa19766f8d492 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Thu, 26 Sep 2019 23:10:51 -0700 Subject: [PATCH 5/7] small fixes + cleaner example explanation [ci skip] --- docs/Customization/Firrtl-Transforms.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 64aba247..4e689192 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -13,7 +13,7 @@ Where to add transforms 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). +This is 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 :language: make @@ -24,6 +24,8 @@ If you look inside of the `tools/barstools/tapeout/src/main/scala/transforms/Gen 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``. +For more information on Barstools, please visit the :ref:`Barstools` section. + Examples of transforms ---------------------- @@ -38,7 +40,9 @@ adding them to your Chisel source or by creating a serialized annotation ``json` **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 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: +makes sure that a particular signal is not removed by the "Dead Code Elimination" pass in FIRRTL. +The example below shows both how to directly annotate the signal with the ``annotate`` function and the ``DontTouchAnnotation`` +class as well as the Chisel wrapper function called ``dontTouch`` that does this automatically for you (more `dontTouch `__ information): .. code-block:: scala @@ -55,8 +59,9 @@ makes sure that a particular signal is not removed by the "Dead Code Elimination def toFirrtl = DontTouchAnnotation(some_signal.toNamed) }) - // or use the wrapper for this - // chisel3.experimental.dontTouch(some_signal) + // or use the Chisel wrapper for this + + chisel3.dontTouch(some_signal) ... } From 802c11dbefd254fc02f592c6e52175c2e3057e94 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Thu, 26 Sep 2019 23:16:57 -0700 Subject: [PATCH 6/7] add some extra clarity [ci skip] --- docs/Customization/Firrtl-Transforms.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 4e689192..f25bd43f 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -41,8 +41,10 @@ adding them to your Chisel source or by creating a serialized annotation ``json` 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. -The example below shows both how to directly annotate the signal with the ``annotate`` function and the ``DontTouchAnnotation`` -class as well as the Chisel wrapper function called ``dontTouch`` that does this automatically for you (more `dontTouch `__ information): +The example below shows two ways to annotate the signal: + +* directly annotate the signal with the ``annotate`` function and the ``DontTouchAnnotation`` class if there is no Chisel API for it (note: most FIRRTL annotations have Chisel APIs for them) +* use the Chisel API/wrapper function called ``dontTouch`` that does this automatically for you (more `dontTouch `__ information): .. code-block:: scala @@ -55,13 +57,15 @@ class as well as the Chisel wrapper function called ``dontTouch`` that does this class Submodule extends Module { ... val some_signal := ... + + // how to annotate WITHOUT a Chisel API/wrapper annotate(new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(some_signal.toNamed) }) - // or use the Chisel wrapper for this - + // how to annotate if there is a Chisel API/wrapper chisel3.dontTouch(some_signal) + ... } From f24eba30f674ffba6f42142a59bad1e58d7f8e79 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 27 Sep 2019 00:32:47 -0700 Subject: [PATCH 7/7] change order of dontTouch | make more concise [ci skip] --- docs/Customization/Firrtl-Transforms.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index f25bd43f..808082e0 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -39,12 +39,11 @@ adding them to your Chisel source or by creating a serialized annotation ``json` (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 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. -The example below shows two ways to annotate the signal: +The example below shows two ways to annotate the signal using the ``DontTouchAnnotation`` +(makes sure that a particular signal is not removed by the "Dead Code Elimination" pass in FIRRTL): -* directly annotate the signal with the ``annotate`` function and the ``DontTouchAnnotation`` class if there is no Chisel API for it (note: most FIRRTL annotations have Chisel APIs for them) * use the Chisel API/wrapper function called ``dontTouch`` that does this automatically for you (more `dontTouch `__ information): +* directly annotate the signal with the ``annotate`` function and the ``DontTouchAnnotation`` class if there is no Chisel API for it (note: most FIRRTL annotations have Chisel APIs for them) .. code-block:: scala @@ -58,14 +57,15 @@ The example below shows two ways to annotate the signal: ... val some_signal := ... + // MAIN WAY TO USE `dontTouch` + // how to annotate if there is a Chisel API/wrapper + chisel3.dontTouch(some_signal) + // how to annotate WITHOUT a Chisel API/wrapper annotate(new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(some_signal.toNamed) }) - // how to annotate if there is a Chisel API/wrapper - chisel3.dontTouch(some_signal) - ... }