[skip ci] address comments, remove bwrc env vars, bump hammer

docs/VLSI/Advanced-Usage.rst

@@ -12,11 +12,36 @@ The Make-based build system provided supports using Hammer without using RTL gen
     export CUSTOM_VLOG=<your verilog files>
     export VLSI_TOP=<your top module>
 
+``CUSTOM_VLOG`` breaks the dependency on the rest of the 
+
+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``.
+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:
 

docs/VLSI/HAMMER.rst

@@ -62,7 +62,7 @@ Technology Plugins
 
 Hammer supports separately managed technology plugins to satisfy NDAs. You may be able to acquire access to certain pre-built technology plugins with permission from the technology vendor. Or, to build your own tech plugin, you need at least a ``<tech_name>.tech.json`` and ``defaults.yml``. An ``__init__.py`` is optional if there are any technology-specific methods or hooks to run.
 
-The `ASAP7 plugin <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/technology/asap7>`__ is a good starting point for setting up a technology plugin. Refer to Hammer's documentation for the schema and setup instructions.
+The `ASAP7 plugin <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/technology/asap7>`__ is a good starting point for setting up a technology plugin because it is an open-source example that is not suitable for taping out a chip. Refer to Hammer's documentation for the schema and detailed setup instructions.
 
 Several configuration variables are needed to configure your technology of choice.
 

docs/VLSI/Tutorial.rst

@@ -18,9 +18,9 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
   * Hammer output directory. Can be changed with the ``OBJ_DIR`` variable.
   * Will contain subdirectories such as ``syn-rundir`` and ``par-rundir`` and the ``inputs.yml`` denoting the top module and input Verilog files.
 
-* bwrc-env.yml
+* env.yml
 
-  * An example of tool environment configuration for BWRC affiliates. Replace as necessary for your environment.
+  * A template file for tool environment configuration. Fill in the install and license server paths for your environment.
 
 * example-vlsi
 
@@ -86,9 +86,13 @@ To elaborate the Sha3RocketConfig (Rocketchip w/ the accelerator) and set up all
     export VLSI_TOP=Sha3AccelwBB
     make buildfile
 
-Note that because the ASAP7 process does not yet have a memory compiler, flip-flop arrays are used instead.
+The ``MACROCOMPILER_MODE='--mode synflops'`` is needed because the ASAP7 process does not yet have a memory compiler. Therefore, flip-flop arrays are used instead.
 
-For the curious, Hammer generates a set of Make targets in ``build/hammer.d``. ``make buildfile`` needs to be re-run if Make variables are changed.
+The ``CONFIG=Sha3RocketConfig`` selects the target generator config in the same manner as the rest of the Chipyard framework.
+
+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.
+
+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.
 
 Running the VLSI Flow
 ---------------------
@@ -101,7 +105,7 @@ 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 where you downloaded the ASAP7 PDK.
+First, set ``technology.asap7.tarball_dir`` to the absolute path of where the downloaded the ASAP7 PDK tarball lives.
 
 Synthesis
 ^^^^^^^^^

vlsi/Makefile

@@ -25,7 +25,7 @@ SMEMS_CACHE        ?= $(tech_dir)/sram-cache.json
 SMEMS_HAMMER       ?= $(build_dir)/$(long_name).mems.hammer.json
 MACROCOMPILER_MODE ?= -l $(SMEMS_CACHE) -hir $(SMEMS_HAMMER)
 OBJ_DIR            ?= $(vlsi_dir)/build
-ENV_YML            ?= $(vlsi_dir)/bwrc-env.yml
+ENV_YML            ?= $(vlsi_dir)/env.yml
 INPUT_CONFS        ?= example.yml
 HAMMER_EXEC        ?= ./example-vlsi
 VLSI_TOP           ?= $(TOP)

vlsi/bwrc-env.yml

@@ -1,7 +0,0 @@
-mentor.mentor_home: "/tools/mentor"
-mentor.MGLS_LICENSE_FILE: "1717@bwrcflex-1.eecs.berkeley.edu:1717@bwrcflex-2.eecs.berkeley.edu"
-cadence.cadence_home: "/tools/cadence"
-cadence.CDS_LIC_FILE: "5280@bwrcflex-1.eecs.berkeley.edu:5280@bwrcflex-2.eecs.berkeley.edu"
-synopsys.synopsys_home: "/tools/synopsys"
-synopsys.SNPSLMD_LICENSE_FILE: "1701@bwrcflex-1.eecs.berkeley.edu:1701@bwrcflex-2.eecs.berkeley.edu"
-synopsys.MGLS_LICENSE_FILE: "1717@bwrcflex-1.eecs.berkeley.edu:1717@bwrcflex-2.eecs.berkeley.edu"

vlsi/env.yml

@@ -0,0 +1,13 @@
+# Base path to where Mentor tools are installed
+mentor.mentor_home: ""
+# Mentor license server/file
+mentor.MGLS_LICENSE_FILE: ""
+# Base path to where Cadence tools are installed
+cadence.cadence_home: ""
+# Cadence license server/file
+cadence.CDS_LIC_FILE: ""
+# Base path to where Synopsys tools are installed
+synopsys.synopsys_home: ""
+# Synopsys license server/files
+synopsys.SNPSLMD_LICENSE_FILE: ""
+synopsys.MGLS_LICENSE_FILE: ""