wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

update docs to reflect new tutorial example, remove old dummy DCO stuff

Browse Source
This commit is contained in:
Harrison Liew
2021-06-06 21:17:55 -07:00
parent a7214e671c
commit f08b22885a
9 changed files with 60 additions and 756 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/VLSI/Basic-Flow.rst
View File

@@ -63,17 +63,19 @@ 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 MacroCopmiler (:ref:`Tools/Barstools:barstools`) in order to make the generated Verilog more VLSI friendly.
By default, the MacroCopmiler will attempt to map memories into the SRAM options within the Hammer technology plugin. However, if you are wokring with a new process technology are prefer to work with flipflop arrays, you can configure the MacroCompiler using the ``MACROCOMPILER_MODE`` make variable. For example, the ASAP7 process technology does not have associated SRAMs, and therefore the ASAP7 Hammer tutorial (:ref:`tutorial`) uses the ``MACROCOMPILER_MODE='--mode synflops'`` option (Note that synthesizing a design with only flipflops is very slow and will often may not meet constraints).
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.
By default, the MacroCompiler will attempt to map memories into the SRAM options within the Hammer technology plugin. However, if you are wokring with a new process technology are prefer to work with flipflop arrays, you can configure the MacroCompiler using the ``MACROCOMPILER_MODE`` make variable. For example, if your technology plugin does not have an SRAM compiler ready, you can use the ``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``.
Hence, if we want to monolithically place and route the entire SoC, the relevant command would be
.. code-block:: shell
make buildfile CONFIG=<chipyard_config_name> tech_name=<tech_name> INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
In a more typical scenario of working on a single module, for example the Gemmini accelerator within the GemminiRocketConfig Chipyard SoC configuration, the relevant command would be
In a more typical scenario of working on a single module, for example the Gemmini accelerator within the GemminiRocketConfig Chipyard SoC configuration, the relevant command would be:
.. code-block:: shell
make buildfile CONFIG=GemminiRocketConfig VLSI_TOP=Gemmini tech_name=tsmintel3 INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
@@ -89,12 +91,14 @@ Synthesis
In order to run synthesis, we run ``make syn`` with the matching Make variables.
Post-synthesis logs and collateral will be saved in ``build/<config-name>/syn-rundir``. The raw QoR data (area, timing, gate counts, etc.) will be found in ``build/<config-name>/syn-rundir/reports``.
Hence, if we want to monolithically synthesize the entire SoC, the relevant command would be
Hence, if we want to monolithically synthesize the entire SoC, the relevant command would be:
.. code-block:: shell
make syn CONFIG=<chipyard_config_name> tech_name=<tech_name> INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
In a more typical scenario of working on a single module, for example the Gemmini accelerator within the GemminiRocketConfig Chipyard SoC configuration, the relevant command would be
In a more typical scenario of working on a single module, for example the Gemmini accelerator within the GemminiRocketConfig Chipyard SoC configuration, the relevant command would be:
.. code-block:: shell
make syn CONFIG=GemminiRocketConfig VLSI_TOP=Gemmini tech_name=tsmintel3 INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
@@ -108,7 +112,8 @@ In order to run place-and-route, we run ``make par`` with the matching Make vari
Post-PnR logs and collateral will be saved in ``build/<config-name>/par-rundir``. Specifically, the resulting GDSII file will be in that directory with the suffix ``*.gds``. and timing reports can be found in ``build/<config-name>/par-rundir/timingReports``.
Place-and-route is requires more design details in contrast to synthesis. For example, place-and-route requires some basic floorplanning constraints. The default ``example-design.yml`` configuration file template allows the tool (specifically, the Cadence Innovus tool) to use it's automatic floorplanning capability within the top level of the design (``ChipTop``). However, if we choose to place-and-route a specific block which is not the SoC top level, we need to change the top-level path name to match the ``VLSI_TOP`` make parameter we are using.
Hence, if we want to monolitically place-and-route the entire SoC with the default tech plug-in parameters for power-straps and corners, the relevant command would be
Hence, if we want to monolitically place-and-route the entire SoC with the default tech plug-in parameters for power-straps and corners, the relevant command would be:
.. code-block:: shell
make par CONFIG=<chipyard_config_name> tech_name=<tech_name> INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
@@ -130,7 +135,8 @@ In a more typical scenario of working on a single module, for example the Gemmin
top: 0
bottom: 0
The relevant ``make`` command would then be
The relevant ``make`` command would then be:
.. code-block:: shell
make par CONFIG=GemminiRocketConfig VLSI_TOP=Gemmini tech_name=tsmintel3 INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"

2
docs/VLSI/Hammer.rst
View File

@@ -43,6 +43,8 @@ The types of tools (by Hammer names) supported currently include:
* drc
* lvs
* sram_generator
* sim
* power
* pcb
Several configuration variables are needed to configure your tool plugin of choice.

65
docs/VLSI/Tutorial.rst
View File

@@ -9,7 +9,7 @@ Project Structure
This example gives a suggested file structure and build system. The ``vlsi/`` folder will eventually contain the following files and folders:
* Makefile
* Makefile, sim.mk, power.mk
* Integration of Hammer's build system into Chipyard and abstracts away some Hammer commands.
@@ -26,17 +26,13 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
* Entry point to Hammer. Contains example placeholders for hooks.
* example.v
* Verilog wrapper around the accelerator and dummy hard macro.
* example-asap7.yml
* example-asap7.yml, example-tools.yml
* Hammer IR for this tutorial.
* extra_libraries
* example-design.yml, example-nangate45.yml, example-tech.yml
* Contains collateral for the dummy hard macro.
* Hammer IR not used for this tutorial but provided as templates.
* generated-src
@@ -46,6 +42,10 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
* Core, tool, tech repositories.
* view_gds.py
* A convenience script to view a layout using gdspy. Note that this will be very slow for large layouts (e.g. a Rocket core)!
Prerequisites
-------------
@@ -54,7 +54,7 @@ Prerequisites
* Genus, Innovus, and Calibre licenses
* For ASAP7 specifically:
* Download the `ASAP7 PDK v1p5 <http://asap.asu.edu/asap/>`__ tarball to a directory of choice but do not extract it. The tech plugin is configured to extract the PDK into a cache directory for you.
* Download the `ASAP7 PDK v1p5 <http://asap.asu.edu/asap/>`__ tarball to a directory of choice but do not extract it. The tech plugin is configured to extract the PDK into a cache directory for you. Note: v1p5 of the PDK is not publicly available, and you will need to contact the developers for it. The v1p7 version currently has too many bugs.
* If you have additional ASAP7 hard macros, their LEF & GDS need to be 4x upscaled @ 4000 DBU precision. They may live outside ``extra_libraries`` at your discretion.
* Innovus version must be >= 15.2 or <= 18.1 (ISRs excluded).
@@ -78,17 +78,13 @@ Pull the Hammer environment into the shell:
Building the Design
--------------------
To elaborate the ``Sha3RocketConfig`` (Rocket Chip w/ the accelerator) and set up all prerequisites for the build system to push just the accelerator + hard macro through the flow:
To elaborate the ``TinyRocketConfig`` and set up all prerequisites for the build system to push just the accelerator + hard macro through the flow:
.. code-block:: shell
make buildfile MACROCOMPILER_MODE='--mode synflops' CONFIG=Sha3RocketConfig VLSI_TOP=Sha3AccelwBB
make buildfile CONFIG=TinyRocketConfig
The ``MACROCOMPILER_MODE='--mode synflops'`` is needed because the ASAP7 process does not yet have a memory compiler, so flip-flop arrays are used instead. This will dramatically increase the synthesis runtime if your design has a lot of memory state (e.g. large caches). This change is automatically inferred by the makefile but is included here for completeness.
The ``CONFIG=Sha3RocketConfig`` selects the target generator config in the same manner as the rest of the Chipyard framework. This elaborates a Rocket Chip with the Sha3Accel module.
The ``VLSI_TOP=Sha3AccelwBB`` indicates that we are only interested in physical design of the accelerator block. If this variable is not set, the entire SoC will be pushed through physical design. Note that you should not set the ``TOP`` variable because it is used during Chisel elaboration.
The ``CONFIG=TinyRocketConfig`` selects the target generator config in the same manner as the rest of the Chipyard framework. This elaborates a stripped-down Rocket Chip in the interest of minimizing tool runtime.
For the curious, ``make buildfile`` generates a set of Make targets in ``build/hammer.d``. It needs to be re-run if environment variables are changed. It is recommended that you edit these variables directly in the Makefile rather than exporting them to your shell environment.
@@ -105,13 +101,13 @@ example.yml
^^^^^^^^^^^
This contains the Hammer configuration for this example project. Example clock constraints, power straps definitions, placement constraints, and pin constraints are given. Additional configuration for the extra libraries and tools are at the bottom.
First, set ``technology.asap7.tarball_dir`` to the absolute path of where the downloaded the ASAP7 PDK tarball lives.
First, set ``technology.asap7.tarball_dir`` to the absolute path to the directory where the downloaded the ASAP7 PDK tarball lives.
Synthesis
^^^^^^^^^
.. code-block:: shell
make syn
make syn CONFIG=TinyRocketConfig
Post-synthesis logs and collateral are in ``build/syn-rundir``. The raw QoR data is available at ``build/syn-rundir/reports``, and methods to extract this information for design space exploration are a WIP.
@@ -119,7 +115,7 @@ Place-and-Route
^^^^^^^^^^^^^^^
.. code-block:: shell
make par
make par CONFIG=TinyRocketConfig
After completion, the final database can be opened in an interactive Innovus session via ``./build/par-rundir/generated-scripts/open_chip``.
@@ -131,7 +127,7 @@ Timing reports are found in ``build/par-rundir/timingReports``. They are gzipped
.. code-block:: shell
python3 view_gds.py build/par-rundir/Sha3AccelwBB.gds
python3 view_gds.py build/chipyard.TestHarness.TinyRocketConfig/par-rundir/ChipTop.gds
By default, this script only shows the M2 thru M4 routing. Layers can be toggled in the layout viewer's side pane and ``view_gds.py`` has a mapping of layer numbers to layer names.
@@ -141,9 +137,34 @@ To run DRC & LVS, and view the results in Calibre:
.. code-block:: shell
make drc
make drc CONFIG=TinyRocketConfig
./build/drc-rundir/generated-scripts/view-drc
make lvs
make lvs CONFIG=TinyRocketConfig
./build/lvs-rundir/generated-scripts/view-lvs
Some DRC errors are expected from this PDK, as explained in the `ASAP7 plugin readme <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/technology/asap7>`__.
Furthermore, the dummy SRAMs that are provided do not have any geometry inside, so will certainly cause DRC and LVS errors.
Simulation
^^^^^^^^^^
Simulation with VCS is supported, and can be run at the RTL- or gate-level (post-synthesis and P&R). The simulation infrastructure as included here is intended for running RISC-V binaries on a Chipyard config. For example, for an RTL-level simulation:
.. code-block:: shell
make sim-rtl CONFIG=TinyRocketConfig BINARY=$RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple
Post-synthesis and post-P&R simulations use the ``sim-syn`` and ``sim-par`` targets, respectively.
There are also ``-debug`` and ``-debug-timing``, which will instruct VCS to write a SAIF + VPD and do timing-annotated simulations, respectively. See the ``sim.mk`` file for all available targets.
Note that for the ASAP7 example, gate-level simulations will timeout (the cause is being investigated).
Power/Rail Analysis
^^^^^^^^^^^^^^^^^^^
Post-P&R power and rail (IR drop) analysis is supported with Voltus:
.. code-block:: shell
make power-par CONFIG=TinyRocketConfig
If you append the ``BINARY`` variable to the command, it will use the activity file generated from a ``sim-<syn/par>-debug`` run and report dynamic power & IR drop from the toggles encoded in the waveform.
Note that for ASAP7, to bypass gate-level simulation, you will need to run the power tool manually (see the generated commands in the generated ``hammer.d`` buildfile). Static and active (vectorless) power & IR drop will be reported.