diff --git a/docs/Advanced-Concepts/Resources.rst b/docs/Advanced-Concepts/Resources.rst index fbfaad60..99125194 100644 --- a/docs/Advanced-Concepts/Resources.rst +++ b/docs/Advanced-Concepts/Resources.rst @@ -33,7 +33,3 @@ For example: lazy val myAwesomeAccel = (project in file("generators/myAwesomeAccelFolder")) .dependsOn(rocketchip) .settings(commonSettings) - - lazy val tapeout = conditionalDependsOn(project in file("./tools/barstools/tapeout/")) - .dependsOn(myAwesomeAccel) - .settings(commonSettings) diff --git a/docs/Chipyard-Basics/Chipyard-Components.rst b/docs/Chipyard-Basics/Chipyard-Components.rst index 669bfdfc..7fdbe26d 100644 --- a/docs/Chipyard-Basics/Chipyard-Components.rst +++ b/docs/Chipyard-Basics/Chipyard-Components.rst @@ -79,9 +79,9 @@ Tools FIRRTL enables digital circuits manipulation between Chisel elaboration and Verilog generation. See :ref:`Tools/FIRRTL:FIRRTL` for more information. -**Barstools** +**Tapeout-Tools (Formerly Barstools)** A collection of common FIRRTL transformations used to manipulate a digital circuit without changing the generator source RTL. - See :ref:`Tools/Barstools:Barstools` for more information. + See :ref:`Tools/Tapeout-Tools:Tapeout-Tools` for more information. **Dsptools** A Chisel library for writing custom signal processing hardware, as well as integrating custom signal processing hardware into an SoC (especially a Rocket-based SoC). diff --git a/docs/Customization/Firrtl-Transforms.rst b/docs/Customization/Firrtl-Transforms.rst index 1113bde6..7de7aadb 100644 --- a/docs/Customization/Firrtl-Transforms.rst +++ b/docs/Customization/Firrtl-Transforms.rst @@ -22,18 +22,18 @@ Where to add transforms 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). +This is done by the ``tapeout`` SBT project (located in ``tools/tapeout``) which calls ``GenerateModelStageMain`` (a function that wraps the multiple FIRRTL compiler calls and extra transforms). .. literalinclude:: ../../common.mk :language: make :start-after: DOC include start: FirrtlCompiler :end-before: DOC include end: FirrtlCompiler -If you look inside of the `tools/barstools/tapeout/src/main/scala/transforms/GenerateModelStageMain.scala `__ file, +If you look inside of the ``tools/tapeout/src/main/scala/transforms/GenerateModelStageMain.scala`` file, you can see that FIRRTL is invoked for "Model". Currently, the FIRRTL compiler is agnostic to the ``TOP`` and ``MODEL`` differentiation, and the user is responsible for providing annotations that will inform the compiler where(``TOP`` vs ``MODEL``) to perform the custom FIRRTL transformations. -For more information on Barstools, please visit the :ref:`Tools/Barstools:Barstools` section. +For more information on the Tapeout sub-project, please visit the :ref:`Tools/Tapeout-Tools:Tapeout-Tools` section. Examples of transforms ---------------------- diff --git a/docs/Customization/Incorporating-Verilog-Blocks.rst b/docs/Customization/Incorporating-Verilog-Blocks.rst index fde44411..9d7ceb81 100644 --- a/docs/Customization/Incorporating-Verilog-Blocks.rst +++ b/docs/Customization/Incorporating-Verilog-Blocks.rst @@ -33,19 +33,6 @@ different directory from Chisel (Scala) sources. vsrc/ YourFile.v -In addition to the steps outlined in the previous section on adding a -project to the ``build.sbt`` at the top level, it is also necessary to -add any projects that contain Verilog IP as dependencies to the -``tapeout`` project. This ensures that the Verilog sources are visible -to the downstream FIRRTL passes that provide utilities for integrating -Verilog files into the build process, which are part of the -``tapeout`` package in ``barstools/tapeout``. - -.. code-block:: scala - - lazy val tapeout = conditionalDependsOn(project in file("./tools/barstools/tapeout/")) - .dependsOn(chisel_testers, example, yourproject) - .settings(commonSettings) For this concrete GCD example, we will be using a ``GCDMMIOBlackBox`` Verilog module that is defined in the ``chipyard`` project. The Scala diff --git a/docs/Tools/Barstools.rst b/docs/Tools/Tapeout-Tools.rst similarity index 95% rename from docs/Tools/Barstools.rst rename to docs/Tools/Tapeout-Tools.rst index fa4176c4..b522c46d 100644 --- a/docs/Tools/Barstools.rst +++ b/docs/Tools/Tapeout-Tools.rst @@ -1,7 +1,7 @@ -Barstools +Tapeout-Tools =============================== -Barstools is a collection of useful FIRRTL transformations and compilers to help the build process. +Tapeout-Tools is a collection of useful FIRRTL transformations and compilers to help the build process. Included in the tools are a MacroCompiler (used to map Chisel memory constructs to vendor SRAMs), FIRRTL transforms (to separate harness and top-level SoC files), and more. Mapping technology SRAMs (MacroCompiler) @@ -23,16 +23,16 @@ An external module reference is a FIRRTL construct that enables a design to refe A list of unique SRAM configurations is output to a ``.conf`` file by FIRRTL, which is used to map technology SRAMs. Without this transform, FIRRTL will map all ``SeqMem`` s to flip-flop arrays with equivalent behavior, which may lead to a design that is difficult to route. -The ``.conf`` file is consumed by a tool called MacroCompiler, which is part of the :ref:`Tools/Barstools:Barstools` scala package. +The ``.conf`` file is consumed by a tool called MacroCompiler, which is part of the :ref:`Tools/Tapeout-Tools:Tapeout-Tools` scala package. MacroCompiler is also passed an ``.mdf`` file that describes the available list of technology SRAMs or the capabilities of the SRAM compiler, if one is provided by the foundry. -Typically a foundry SRAM compiler will be able to generate a set of different SRAMs collateral based on some requirements on size, aspect ratio, etc. (see :ref:`Tools/Barstools:SRAM MDF Fields`). +Typically a foundry SRAM compiler will be able to generate a set of different SRAMs collateral based on some requirements on size, aspect ratio, etc. (see :ref:`Tools/Tapeout-Tools:SRAM MDF Fields`). Using a user-customizable cost function, MacroCompiler will select the SRAMs that are the best fit for each dimensionality in the ``.conf`` file. This may include over provisioning (e.g. using a 64x1024 SRAM for a requested 60x1024, if the latter is not available) or arraying. Arraying can be done in both width and depth, as well as to solve masking constraints. For example, a 128x2048 array could be composed of four 64x1024 arrays, with two macros in parallel to create two 128x1024 virtual SRAMs which are combinationally muxed to add depth. If this macro requires byte-granularity write masking, but no technology SRAMs support masking, then the tool may choose to use thirty-two 8x1024 arrays in a similar configuration. You may wish to create a cache of your available SRAM macros either manually, or via a script. A reference script for creating a JSON of your SRAM macros is in the `asap7 technology library folder `__. -For information on writing ``.mdf`` files, look at `MDF on github `__ and a brief description in :ref:`Tools/Barstools:SRAM MDF Fields` section. +For information on writing ``.mdf`` files, look at `MDF on github `__ and a brief description in :ref:`Tools/Tapeout-Tools:SRAM MDF Fields` section. The output of MacroCompiler is a Verilog file containing modules that wrap the technology SRAMs into the specified interface names from the ``.conf``. If the technology supports an SRAM compiler, then MacroCompiler will also emit HammerIR that can be passed to Hammer to run the compiler itself and generate design collateral. @@ -105,7 +105,7 @@ This is necessary to facilitate post-synthesis and post-place-and-route simulati Simulations, after your design goes through a VLSI flow, will use the verilog netlist generated from the flow and will need an untouched test harness to drive it. Separating these components into separate files makes this straightforward. Without the separation the file that included the test harness would also redefine the DUT which is often disallowed in simulation tools. -To do this, there is a FIRRTL ``App`` in :ref:`Tools/Barstools:Barstools` called ``GenerateTopAndHarness``, which runs the appropriate transforms to elaborate the modules separately. +To do this, there is a FIRRTL ``App`` in :ref:`Tools/Tapeout-Tools:Tapeout-Tools` called ``GenerateTopAndHarness``, which runs the appropriate transforms to elaborate the modules separately. This also renames modules in the test harness so that any modules that are instantiated in both the test harness and the chip are uniquified. .. Note:: For VLSI projects, this ``App`` is run instead of the normal FIRRTL ``App`` to elaborate Verilog. @@ -133,5 +133,5 @@ This, unfortunately, breaks the process-agnostic RTL abstraction, so it is recom The simplest way to do this is to have a config fragment that when included updates instantiates the IO cells and connects them in the test harness. When simulating chip-specific designs, it is important to include the IO cells. The IO cell behavioral models will often assert if they are connected incorrectly, which is a useful runtime check. -They also keep the IO interface at the chip and test harness boundary (see :ref:`Tools/Barstools:Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route, +They also keep the IO interface at the chip and test harness boundary (see :ref:`Tools/Tapeout-Tools:Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route, which allows the RTL simulation test harness to be reused. diff --git a/docs/Tools/index.rst b/docs/Tools/index.rst index f8d0be95..491bd60c 100644 --- a/docs/Tools/index.rst +++ b/docs/Tools/index.rst @@ -12,4 +12,4 @@ The following pages will introduce them, and how we can use them in order to gen FIRRTL Treadle Dsptools - Barstools + Tapeout-Tools diff --git a/docs/VLSI/Basic-Flow.rst b/docs/VLSI/Basic-Flow.rst index 10a7af2f..de1acc74 100644 --- a/docs/VLSI/Basic-Flow.rst +++ b/docs/VLSI/Basic-Flow.rst @@ -56,7 +56,7 @@ We will do so by calling ``make buildfile`` with appropriate Chipyard configurat As in the rest of the Chipyard flows, we specify our SoC configuration using the ``CONFIG`` make variable. However, unlike the rest of the Chipyard flows, in the case of physical design we might be interested in working in a hierarchical fashion and therefore we would like to work on a single module. Therefore, we can also specify a ``VLSI_TOP`` make variable with the same of a specific Verilog module (which should also match the name of the equivalent Chisel module) which we would like to work on. -The makefile will automatically call tools such as Barstools and the MacroCompiler (:ref:`Tools/Barstools:barstools`) in order to make the generated Verilog more VLSI friendly. +The makefile will automatically call tools such as Tapeout-Tools and the MacroCompiler (:ref:`Tools/Tapeout-Tools:Tapeout-Tools`) in order to make the generated Verilog more VLSI friendly. By default, the MacroCompiler will attempt to map memories into the SRAM options within the Hammer technology plugin. However, if you are working with a new process technology and prefer to work with flip-flop arrays, you can configure the MacroCompiler using the ``TOP_MACROCOMPILER_MODE`` make variable. For example, if your technology plugin does not have an SRAM compiler ready, you can use the ``TOP_MACROCOMPILER_MODE='--mode synflops'`` option (Note that synthesizing a design with only flipflops is very slow and will often may not meet constraints). We call the ``make buildfile`` command while also specifying the name of the process technology we are working with (same ``tech_name`` for the configuration files and plugin name) and the configuration files we created. Note, in the ASAP7 tutorial ((:ref:`tutorial`)) these configuration files are merged into a single file called ``example-asap7.yml``. diff --git a/docs/VLSI/Building-A-Chip.rst b/docs/VLSI/Building-A-Chip.rst index adc79802..c635bc5f 100644 --- a/docs/VLSI/Building-A-Chip.rst +++ b/docs/VLSI/Building-A-Chip.rst @@ -10,7 +10,7 @@ Transforming the RTL -------------------- Building a chip requires specializing the generic verilog emitted by FIRRTL to adhere to the constraints imposed by the technology used for fabrication. -This includes mapping Chisel memories to available technology macros such as SRAMs, mapping the input and output of your chip to connect to technology IO cells, see :ref:`Tools/Barstools:Barstools`. +This includes mapping Chisel memories to available technology macros such as SRAMs, mapping the input and output of your chip to connect to technology IO cells, see :ref:`Tools/Tapeout-Tools:Tapeout-tools`. In addition to these required transformations, it may also be beneficial to transform the RTL to make it more amenable to hierarchical physical design easier. This often includes modifying the logical hierarchy to match the physical hierarchy through grouping components together or flattening components into a single larger module.