From 1c1b0effa34e06bd73a816edcc5a0d79e7990318 Mon Sep 17 00:00:00 2001 From: joey0320 Date: Sat, 11 Mar 2023 16:52:35 -0800 Subject: [PATCH 1/3] update docs for release --- docs/Customization/Firrtl-Transforms.rst | 7 ++++--- docs/Tools/FIRRTL.rst | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 4a467207..c089357b 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -12,13 +12,14 @@ The Scala FIRRTL Compiler and the MLIR FIRRTL Compiler ------------------------------------------------------ In Chipyard, two FIRRTL compilers work together to compile Chisel into Verilog. The Scala FIRRTL compiler(SFC) and the MLIR FIRRTL compiler(MFC). They are basically doing the same thing, except that MFC is written in C++ which makes compilation much faster. In the default setting, the SFC will compile Chisel into CHIRRTL and MFC will -compile CHIRRTL into Verilog(as of now, we are using SFC as a backup for cases when MFC doesn't work, e.g., when the design is using Fixed types). By setting the ``ENABLE_CUSTOM_FIRRTL_PASS`` env variable to a non-zero value, we can make the SFC compile Chisel into LowFIRRTL so that our custom FIRRTL passes are applied. +compile CHIRRTL into Verilog(as of now, we are using SFC as a backup for cases when MFC doesn't work, e.g., when the design is using Fixed types). By setting the ``ENABLE_CUSTOM_FIRRTL_PASS`` env variable to a non-zero value, +we can make the SFC compile Chisel into LowFIRRTL so that our custom FIRRTL passes are applied. 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. +In Chipyard, the FIRRTL compiler is called multiple times to create a "Top" file that contains the DUT and a "Model" file containing the test harness, which instantiates the DUT. +The "Model" file does not contain the DUT's module definition or any of its submodules. This is done by the ``tapeout`` SBT project (located in ``tools/barstools/tapeout``) which calls ``GenerateModelStageMain`` (a function that wraps the multiple FIRRTL compiler calls and extra transforms). .. literalinclude:: ../../common.mk diff --git a/docs/Tools/FIRRTL.rst b/docs/Tools/FIRRTL.rst index e9e6425a..268d7728 100644 --- a/docs/Tools/FIRRTL.rst +++ b/docs/Tools/FIRRTL.rst @@ -3,7 +3,7 @@ FIRRTL `FIRRTL `__ is an intermediate representation of your circuit. It is emitted by the Chisel compiler and is used to translate Chisel source files into another representation such as Verilog. -Without going into too much detail, FIRRTL is consumed by a FIRRTL compiler (another Scala program) which passes the circuit through a series of circuit-level transformations. +Without going into too much detail, FIRRTL is consumed by FIRRTL compilers which passes the circuit through a series of circuit-level transformations. An example of a FIRRTL pass (transformation) is one that optimizes out unused signals. Once the transformations are done, a Verilog file is emitted and the build process is done. From d7574084c19220a10b97a4c054d7f8488c529367 Mon Sep 17 00:00:00 2001 From: joey0320 Date: Sat, 11 Mar 2023 18:56:36 -0800 Subject: [PATCH 2/3] Update docs related to circt --- docs/Customization/Firrtl-Transforms.rst | 8 +++++--- docs/Tools/FIRRTL.rst | 4 +++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index c089357b..1113bde6 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -10,11 +10,13 @@ Transforms are a powerful tool to take in the FIRRTL IR that is emitted from Chi The Scala FIRRTL Compiler and the MLIR FIRRTL Compiler ------------------------------------------------------ -In Chipyard, two FIRRTL compilers work together to compile Chisel into Verilog. The Scala FIRRTL compiler(SFC) and the MLIR FIRRTL compiler(MFC). -They are basically doing the same thing, except that MFC is written in C++ which makes compilation much faster. In the default setting, the SFC will compile Chisel into CHIRRTL and MFC will -compile CHIRRTL into Verilog(as of now, we are using SFC as a backup for cases when MFC doesn't work, e.g., when the design is using Fixed types). By setting the ``ENABLE_CUSTOM_FIRRTL_PASS`` env variable to a non-zero value, +In Chipyard, two FIRRTL compilers work together to compile Chisel into Verilog. The Scala FIRRTL compiler (SFC) and the MLIR FIRRTL compiler (MFC). +They are basically doing the same thing, except that MFC is written in C++ which makes compilation much faster (the generated Verilog will be different). In the default setting, the SFC will compile Chisel into CHIRRTL and MFC will +compile CHIRRTL into Verilog (as of now, we are using SFC as a backup for cases when MFC doesn't work, e.g., when the design is using Fixed types). By setting the ``ENABLE_CUSTOM_FIRRTL_PASS`` env variable to a non-zero value, we can make the SFC compile Chisel into LowFIRRTL so that our custom FIRRTL passes are applied. +For more information on MLIR FIRRTL Compiler, please visit https://mlir.llvm.org/ and https://circt.llvm.org/. + Where to add transforms ----------------------- diff --git a/docs/Tools/FIRRTL.rst b/docs/Tools/FIRRTL.rst index 268d7728..67adde2d 100644 --- a/docs/Tools/FIRRTL.rst +++ b/docs/Tools/FIRRTL.rst @@ -7,4 +7,6 @@ Without going into too much detail, FIRRTL is consumed by FIRRTL compilers which An example of a FIRRTL pass (transformation) is one that optimizes out unused signals. Once the transformations are done, a Verilog file is emitted and the build process is done. -For more information on please visit their `website `__. +To see how FIRRTL is transformed to Verilog in Chipyard, please visit the :ref:`Customization/Firrtl-Transforms` section. + +For more information on FIRRTL, please visit their `website `__. From 3b79de660f38118b1c52d18c45d1c88fa17e8b9d Mon Sep 17 00:00:00 2001 From: joey0320 Date: Sat, 11 Mar 2023 20:02:53 -0800 Subject: [PATCH 3/3] fix --- docs/Tools/FIRRTL.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Tools/FIRRTL.rst b/docs/Tools/FIRRTL.rst index 67adde2d..2e88218f 100644 --- a/docs/Tools/FIRRTL.rst +++ b/docs/Tools/FIRRTL.rst @@ -7,6 +7,6 @@ Without going into too much detail, FIRRTL is consumed by FIRRTL compilers which An example of a FIRRTL pass (transformation) is one that optimizes out unused signals. Once the transformations are done, a Verilog file is emitted and the build process is done. -To see how FIRRTL is transformed to Verilog in Chipyard, please visit the :ref:`Customization/Firrtl-Transforms` section. +To see how FIRRTL is transformed to Verilog in Chipyard, please visit the :ref:`firrtl-transforms` section. For more information on FIRRTL, please visit their `website `__.