.. _advanced-usage:

Advanced Usage
==============

Alternative RTL Flows
---------------------
The Make-based build system provided supports using Hammer without using RTL generated by Chipyard. To push a custom Verilog module through, one only needs to append the following environment variables to the ``make buildfile`` command (or edit them directly in the Makefile).

.. code-block:: shell

    CUSTOM_VLOG=<your Verilog files>
    VLSI_TOP=<your top module>

``CUSTOM_VLOG`` breaks the dependency on the rest of the Chipyard infrastructure and does not start any Chisel/FIRRTL elaboration. ``VLSI_TOP`` selects the top module from your custom Verilog files.

Under the Hood
--------------
To uncover what is happening under the hood, here are the commands that are executed:

For ``make syn``:

.. code-block:: shell

    ./example-vlsi -e /path/to/env.yml -p /path/to/example.yml -p /path/to/inputs.yml --obj_dir /path/to/build syn

``example-vlsi`` is the entry script as explained before, ``-e`` provides the environment yml, ``-p`` points to configuration yml/jsons, ``--obj_dir`` speficies the destination directory,  and ``syn`` is the action.

For ``make par``:

.. code-block:: shell

    ./example-vlsi -e /path/to/env.yml -p /path/to/syn-output-full.json -o /path/to/par-input.json --obj_dir /path/to/build syn-to-par
    ./example-vlsi -e /path/to/env.yml -p /path/to/par-input.json --obj_dir /path/to/build par

A ``syn-to-par`` action translates the synthesis output configuration into an input configuration given by ``-o``. Then, this is passed to the ``par`` action.

For more information about all the options that can be passed to the Hammer command-line driver, please see the Hammer documentation.

Manual Step Execution & Dependency Tracking
-------------------------------------------
It is invariably necessary to debug certain steps of the flow, e.g. if the power strap settings need to be updated. The underlying Hammer commands support options such as ``--to_step``, ``--from_step``, and ``--only_step``. These allow you to control which steps of a particular action are executed.

Make's dependency tracking can sometimes result in re-starting the entire flow when the user only wants to re-run a certain action. Hammer's build system has "redo" targets such as ``redo-syn`` and ``redo-par`` to run certain actions without typing out the entire Hammer command.

Say you need to update some power straps settings in ``example.yml`` and want to try out the new settings:

.. code-block:: shell

   make redo-par HAMMER_REDO_ARGS='-p example.yml --only_step power_straps'

RTL/Gate-level Simulation, Power Estimation
-------------------------------------------
With the Synopsys plugin, RTL and gate-level simulation is supported using VCS at the chip-level. Also, post-par power estimation with Voltus in the Cadence plugin is also supported. While the provided example does not implement any simulation, some Make targets are provided in the ``vlsi/`` directory. Here is a brief description:

* ``sim-rtl``: RTL-level simulation

  * ``sim-rtl-debug``: Also write a VPD waveform

* ``sim-syn``: Post-synthesis gate-level simulation

  * ``sim-syn-debug``: Also write a VPD waveform
  * ``sim-syn-timing-debug``: Timing-annotated with VPD waveform

* ``sim-par``: Post-par gate-level simulation

  * ``sim-par-debug``: Also write a VPD waveform
  * ``sim-par-timing-debug``: Timing-annotated with VPD waveform

* ``power-par``: Post-par power estimation

  * Note: this will run ``sim-par`` first

* ``redo-`` can be appended to all above targets to break dependency tracking, like described above.

The simulation configuration (e.g. binaries) can be edited for your design. See the Makefile and refer to Hammer's documentation for how to set up simulation parameters for your design.
