diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 4a467207..1113bde6 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -10,15 +10,18 @@ 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, we can make the SFC compile Chisel into LowFIRRTL so that our custom FIRRTL passes are applied. +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 ----------------------- -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..2e88218f 100644 --- a/docs/Tools/FIRRTL.rst +++ b/docs/Tools/FIRRTL.rst @@ -3,8 +3,10 @@ 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. -For more information on please visit their `website `__. +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 `__.