use pip within conda, update docs + links

conda-reqs/vlsi.yaml

@@ -1,13 +0,0 @@
-dependencies:
-    # https://conda-forge.org/feedstock-outputs/
-    #   filterable list of all conda-forge packages
-    # https://conda-forge.org/#contribute
-    #   instructions on adding a recipe
-    # https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/pkg-specs.html#package-match-specifications
-    #   documentation on package_spec syntax for constraining versions
-
-
-    - pip:
-        - -e ../vlsi/hammer-cadence-plugins
-        - -e ../vlsi/hammer-synopsys-plugins
-        - -e ../vlsi/hammer-mentor-plugins

docs/VLSI/ASAP7-Tutorial.rst

@@ -49,31 +49,22 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
 Prerequisites
 -------------
 
-* Python 3.4+
+* Python 3.9+
-* numpy and `gdstk <https://github.com/heitzmann/gdstk>`__ or `gdspy <https://github.com/heitzmann/gdspy>`__  packages. Note: gdspy must be version 1.4.
 * Genus, Innovus, Voltus, VCS, and Calibre licenses
-* For ASAP7 specifically (`README <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/technology/asap7>`__ for more details):
+* For ASAP7 specifically (`README <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/asap7>`__ for more details):
 
   * First, download the `ASAP7 v1p7 PDK <https://github.com/The-OpenROAD-Project/asap7>`__ (we recommend shallow-cloning or downloading an archive of the repository). Then, download the `encrypted Calibre decks tarball <http://asap.asu.edu/asap/>`__ tarball to a directory of choice (e.g. the root directory of the PDK) but do not extract it like the instructions say. The tech plugin is configured to extract the tarball into a cache directory for you.
   * If you have additional ASAP7 hard macros, their LEF & GDS need to be 4x upscaled @ 4000 DBU precision.
 
 Initial Setup
 -------------
-In the Chipyard root, run:
+In the Chipyard root, ensure that you have the Chipyard conda environment activated. Then, run:
 
 .. code-block:: shell
 
     ./scripts/init-vlsi.sh asap7
 
-to pull the Hammer & plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
+to pull and install the plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
-
-Pull the Hammer environment into the shell:
-
-.. code-block:: shell
-
-    cd vlsi
-    export HAMMER_HOME=$PWD/hammer
-    source $HAMMER_HOME/sourceme.sh
 
 Building the Design
 --------------------
@@ -139,7 +130,7 @@ To run DRC & LVS, and view the results in Calibre:
     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>`__.
+Some DRC errors are expected from this PDK, as explained in the `ASAP7 plugin readme <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/asap7>`__.
 Furthermore, the dummy SRAMs that are provided in this tutorial and PDK do not have any geometry inside, so will certainly cause DRC errors.
 
 Simulation

docs/VLSI/Basic-Flow.rst

@@ -7,31 +7,22 @@ Using Hammer To Place and Route a Custom Block
 
 Initialize the Hammer Plug-ins
 ----------------------------------
-In the Chipyard root, run:
+In the Chipyard root, ensure that you have the Chipyard conda environment activated. Then, run:
 
 .. code-block:: shell
 
     ./scripts/init-vlsi.sh <tech-plugin-name>
 
 This will pull the Hammer & CAD tool plugin submodules, assuming the technology plugins are available on github.
-Currently only the asap7 technology plugin is available on github.
+Currently only the asap7 and sky130 technology plugins are available on github.
-If you have additional private technology plugins (this is a typical use-case for proprietry process technologies with require NDAs and secure servers), you can clone them directly
+If you have additional private technology plugins (this is a typical use-case for proprietry process technologies with require NDAs and secure servers), you can submodule them directly
 into VLSI directory with the name ``hammer-<tech-plugin-name>-plugin``.
 For example, for an imaginary process technology called tsmintel3:
 
 .. code-block:: shell
 
     cd vlsi
-    git clone git@my-secure-server.berkeley.edu:tsmintel3/hammer-tsmintel3-plugin.git
+    git submodule add git@my-secure-server.berkeley.edu:tsmintel3/hammer-tsmintel3-plugin.git
-
-
-Next, we define the Hammer environment into the shell:
-
-.. code-block:: shell
-
-    cd vlsi    # (if you haven't done so yet)
-    export HAMMER_HOME=$PWD/hammer
-    source $HAMMER_HOME/sourceme.sh
 
 
 .. Note:: Some VLSI EDA tools are supported only on RHEL-based operating systems. We recommend using Chipyard on RHEL7 and above. However, many VLSI server still have old operating systems such as RHEL6, which have software packages older than the basic chipyard requirements. In order to build Chipyard on RHEL6, you will likely need to use tool packages such as devtoolset (for example, devtoolset-8) and/or build from source gcc, git, gmake, make, dtc, cc, bison, libexpat and liby.
@@ -42,8 +33,7 @@ Setting up the Hammer Configuration Files
 The first configuration file that needs to be set up is the Hammer environment configuration file ``env.yml``. In this file you need to set the paths to the EDA tools and license servers you will be using. You do not have to fill all the fields in this configuration file, you only need to fill in the paths for the tools that you will be using.
 If you are working within a shared server farm environment with an LSF cluster setup (for example, the Berkeley Wireless Research Center), please note the additional possible environment configuration listed in the :ref:`VLSI/Basic-Flow:Advanced Environment Setup` segment of this documentation page.
 
-Hammer relies on YAML-based configuration files. While these configuration can be consolidated within a single files (as is the case in the ASAP7 tutorial :ref:`tutorial` and the ``sky130``
+Hammer relies on YAML-based configuration files. While these configuration can be consolidated within a single files (as is the case in the :ref:`tutorial` and the :ref:`sky130-openroad-tutorial`), the generally suggested way to work with an arbitrary process technology or tools plugins would be to use three configuration files, matching the three Hammer concerns - tools, tech, and design.
-OpenRoad example), the generally suggested way to work with an arbitrary process technology or tools plugins would be to use three configuration files, matching the three Hammer concerns - tools, tech, and design.
 The ``vlsi`` directory includes three such example configuration files matching the three concerns: ``example-tools.yml``, ``example-tech.yml``, and ``example-design.yml``.
 
 The ``example-tools.yml`` file configures which EDA tools hammer will use. This example file uses Cadence Innovus, Genus and Voltus, Synopsys VCS, and Mentor Calibre (which are likely the tools you will use if you're working in the Berkeley Wireless Research Center). Note that tool versions are highly sensitive to the process-technology in-use. Hence, tool versions that work with one process technology may not work with another.
@@ -52,7 +42,7 @@ The ``example-design.yml`` file contains basic build system information (how man
 
 Finally, the ``example-tech.yml`` file is a template file for a process technology plugin configuration. We will copy this file, and replace its fields with the appropriate process technology details for the tech plugin that we have access to. For example, for the ``asap7`` tech plugin, we will replace the <tech_name> field with "asap7" and the path to the process technology files installation directory. The technology plugin (which for ASAP7 is within Hammer) will define the technology node and other parameters.
 
-We recommend copying these example configuration files and customizing them with a different name, so you can have different configuration files for different process technologies and designs (e.g. create tech-tsmintel3.yml from example-tech.yml)
+We recommend copying these example configuration files and customizing them with a different name, so you can have different configuration files for different process technologies and designs (e.g. create ``tech-tsmintel3.yml`` from ``example-tech.yml``)
 
 
 Building the Design

docs/VLSI/Building-A-Chip.rst

@@ -49,4 +49,5 @@ Running the VLSI tool flow
 --------------------------
 
 For the full documentation on how to use the VLSI tool flow, see the `Hammer Documentation <https://hammer-vlsi.readthedocs.io/>`__.
-For an example of how to use the VLSI in the context of Chipyard, see :ref:`VLSI/ASAP7-Tutorial:ASAP7 Tutorial`.
+For setup  and instructions for a VLSI tool flow in the context of Chipyard, see :ref:`hammer_basic_flow`.
+For specific examples, see :ref:`tutorial`, :ref:`sky130-commercial-tutorial`, and :ref:`sky130-openroad-tutorial`.

docs/VLSI/Hammer.rst

@@ -6,7 +6,7 @@ Core Hammer
 `Hammer <https://github.com/ucb-bar/hammer>`__ is a physical design flow which encourages reusability by partitioning physical design specifications into three distinct concerns: design, CAD tool, and process technology. Hammer wraps around vendor specific technologies and tools to provide a single API to address ASIC design concerns.
 Hammer allows for reusability in ASIC design while still providing the designers leeway to make their own modifications.
 
-For more information, read the `Hammer paper <https://people.eecs.berkeley.edu/~edwardw/pubs/hammer-woset-2018.pdf>`__ and see the `GitHub repository <https://github.com/ucb-bar/hammer>`__ and associated documentation.
+For more information, read the `Hammer paper <https://dl.acm.org/doi/abs/10.1145/3489517.3530672>`__ and see the `GitHub repository <https://github.com/ucb-bar/hammer>`__ and associated documentation.
 
 Hammer implements a VLSI flow using the following high-level constructs:
 
@@ -30,7 +30,7 @@ VLSI Flow Control
 -----------------
 Sometimes we want more fine-grained control of the VLSI flow than at the action level.
 The Hammer flow supports being able to start/stop before/after any of the steps in a particular action.
-See the `Hammer documentation on Flow Control <https://docs.hammer-eda.org/en/latest/Hammer-Use/Flow-Control.html>`__ for a full list and description of the options.
+See the `Hammer documentation on Flow Control <https://hammer-vlsi.readthedocs.io/en/latest/Hammer-Use/Flow-Control.html>`__ for a full list and description of the options.
 The ``Makefile`` in the ``vlsi`` directory passes this extra information via the ``HAMMER_EXTRA_ARGS`` variable.
 This variable can also be used to specify additional YAML configurations that may have
 changed or been omitted from the inital build.
@@ -41,7 +41,7 @@ Configuration (Hammer IR)
 
 To configure a Hammer flow, supply a set ``yaml`` or ``json`` configuration files that chooses the tool and technology plugins and versions as well as any design specific configuration options. Collectively, this configuration API is referred to as Hammer IR and can be generated from higher-level abstractions.
 
-The current set of all available Hammer APIs is codified `here <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/defaults.yml>`__.
+The current set of all available Hammer APIs is codified `here <https://github.com/ucb-bar/hammer/blob/master/hammer/config/defaults.yml>`__.
 
 Tool Plugins
 ============
@@ -60,10 +60,9 @@ The types of tools (by Hammer names) supported currently include:
 
 Several configuration variables are needed to configure your tool plugin of choice.
 
-First, select which tool to use for each action by setting ``vlsi.core.<tool_type>_tool`` to the name of your tool, e.g. ``vlsi.core.par_tool: "innovus"``.
+First, select which tool to use for each action by setting ``vlsi.core.<tool_type>_tool`` to the package name of your tool, e.g. ``vlsi.core.par_tool: "hammer.par.innovus"``.
 
-Then, point Hammer to the folder that contains your tool plugin by setting ``vlsi.core.<tool_type>_tool_path``.
+This package directory should include a folder with the name of the tool, which itself includes a python file ``__init__.py`` and a yaml file ``defaults.yml``. Customize the version of the tool by setting ``<tool_type>.<tool_name>.version`` to a tool specific string.
-This directory should include a folder with the name of the tool, which itself includes a python file ``__init__.py`` and a yaml file ``defaults.yml``. Customize the version of the tool by setting ``<tool_type>.<tool_name>.version`` to a tool specific string.
 
 The ``__init__.py`` file should contain a variable, ``tool``, that points to the class implementing this tool.
 This class should be a subclass of ``Hammer<tool_type>Tool``, which will be a subclass of ``HammerTool``. The class should implement methods for all the tool's steps.
@@ -75,10 +74,10 @@ 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 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.
+The `ASAP7 plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/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.
 
-First, choose the technology, e.g. ``vlsi.core.technology: asap7``, then point to the location with the PDK tarball with ``technology.<tech_name>.tarball_dir`` or pre-installed directory with ``technology.<tech_name>.install_dir`` and (if applicable) the plugin repository with ``vlsi.core.technology_path``.
+First, choose the technology package, e.g. ``vlsi.core.technology: hammer.technology.asap7``, then point to the location with the PDK tarball with ``technology.<tech_name>.tarball_dir`` or pre-installed directory with ``technology.<tech_name>.install_dir``.
 
 Technology-specific options such as supplies, MMMC corners, etc. are defined in their respective ``vlsi.inputs...`` configurations. Options for the most common use case are already defined in the technology's ``defaults.yml`` and can be overridden by the user.

docs/VLSI/Sky130-Commercial-Tutorial.rst

@@ -45,28 +45,19 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
 Prerequisites
 -------------
 
-* Python 3.6+
+* Python 3.9+
-* numpy package
 * Genus, Innovus, Voltus, VCS, and Calibre licenses
-* Sky130 PDK, install using `these directions  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+* Sky130 PDK, install using `these directions  <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__
 
 Initial Setup
 -------------
-In the Chipyard root, run:
+In the Chipyard root, ensure that you have the Chipyard conda environment activated. Then, run:
 
 .. code-block:: shell
 
     ./scripts/init-vlsi.sh sky130
 
-to pull the Hammer & plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
+to pull and install the plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
-
-Pull the Hammer environment into the shell:
-
-.. code-block:: shell
-
-    cd vlsi
-    export HAMMER_HOME=$PWD/hammer
-    source $HAMMER_HOME/sourceme.sh
 
 Building the Design
 --------------------
@@ -103,7 +94,7 @@ example-sky130.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.sky130.sky130A/sky130_nda/openram_lib`` to the absolute path of the respective directories containing the Sky130 PDK and SRAM files. See the
-`Sky130 Hammer plugin README <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+`Sky130 Hammer plugin README <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__
 for details about the PDK setup.
 
 example-tools.yml
@@ -143,7 +134,7 @@ To run DRC & LVS, and view the results in Calibre:
     ./build/chipyard.TestHarness.TinyRocketConfig-ChipTop/lvs-rundir/generated-scripts/view_lvs
 
 Some DRC errors are expected from this PDK, especially with regards to the SRAMs, as explained in the
-`Sky130 Hammer plugin README  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__.
+`Sky130 Hammer plugin README  <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__.
 For this reason, the ``example-vlsi-sky130`` script black-boxes the SRAMs for DRC/LVS analysis.
 
 Simulation

docs/VLSI/Sky130-OpenROAD-Tutorial.rst

@@ -41,8 +41,7 @@ This example gives a suggested file structure and build system. The ``vlsi/`` fo
 Prerequisites
 -------------
 
-* Python 3.6+
+* Python 3.9+
-* numpy package
 * OpenROAD flow tools:
 
   * Yosys (synthesis), install `from source <https://yosyshq.net/yosys/download.html>`__ or `using conda <https://anaconda.org/TimVideos/yosys>`__
@@ -50,27 +49,19 @@ Prerequisites
   * Magic (DRC), install `from source <http://www.opencircuitdesign.com/magic/install.html>`__
   * NetGen (LVS), install `from source <http://www.opencircuitdesign.com/netgen/install.html>`__ or `using conda <https://anaconda.org/conda-forge/netgen>`__
 
-* Sky130 PDK, install using `these directions  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+* Sky130 PDK, install using `these directions  <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__
 
 Initial Setup
 -------------
-In the Chipyard root, run:
+In the Chipyard root, ensure that you have the Chipyard conda environment activated. Then, run:
 
 .. code-block:: shell
 
     ./scripts/init-vlsi.sh sky130 openroad
 
-to pull the Hammer submodule. Note that for technologies other than ``sky130`` or ``asap7``, the tech plugin submodule is cloned into the ``vlsi`` folder,
+to pull and install the plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule is cloned in the ``vlsi`` folder, 
 and for the commercial tool flow (set up by omitting the ``openroad`` argument), the tool plugin submodules are cloned into the ``vlsi`` folder.
 
-Pull the Hammer environment into the shell:
-
-.. code-block:: shell
-
-    cd vlsi
-    export HAMMER_HOME=$PWD/hammer
-    source $HAMMER_HOME/sourceme.sh
-
 Building the Design
 --------------------
 To elaborate the ``TinyRocketConfig`` and set up all prerequisites for the build system to push the design and SRAM macros through the flow:
@@ -106,7 +97,7 @@ example-sky130.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.sky130.<sky130A, openram_lib>`` to the absolute path of the respective directories containing the Sky130 PDK and SRAM files. See the
-`Sky130 Hammer plugin README <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__
+`Sky130 Hammer plugin README <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__
 for details about the PDK setup.
 
 
@@ -163,7 +154,7 @@ To run DRC & LVS:
     make lvs tutorial=sky130-openroad
 
 Some DRC errors are expected from this PDK, especially with regards to the SRAMs, as explained in the
-`Sky130 Hammer plugin README  <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/technology/sky130/README.md>`__.
+`Sky130 Hammer plugin README  <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__.
 
 
 VLSI Flow Control
@@ -180,11 +171,11 @@ Firt, refer to the :ref:`VLSI/Hammer:VLSI Flow Control` documentation. The below
       # example of re-running only floorplanning to test out a new floorplan configuration
       make redo-par HAMMER_EXTRA_ARGS="--only_step floorplan_design -p example-sky130.yml"
 
-See the `OpenROAD tool plugin <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/par/openroad>`__ for the full list of OpenROAD tool steps and their implementations.
+See the `OpenROAD tool plugin <https://github.com/ucb-bar/hammer/blob/master/hammer/par/openroad>`__ for the full list of OpenROAD tool steps and their implementations.
 
 Documentation
 -------------
-For more information about Hammer's underlying implementation, visit the `Hammer documentation website <https://docs.hammer-eda.org/en/latest/index.html>`__.
+For more information about Hammer's underlying implementation, visit the `Hammer documentation website <https://hammer-vlsi.readthedocs.io/en/latest/index.html>`__.
 
-For details about the plugins used in this tutorial, check out the `OpenROAD tool plugin repo + README <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/par/openroad>`__
+For details about the plugins used in this tutorial, check out the `OpenROAD tool plugin repo + README <https://github.com/ucb-bar/hammer/blob/master/hammer/par/openroad>`__
-and `Sky130 tech plugin repo + README <https://github.com/ucb-bar/hammer/tree/master/src/hammer-vlsi/technology/sky130>`__.
+and `Sky130 tech plugin repo + README <https://github.com/ucb-bar/hammer/blob/master/hammer/technology/sky130>`__.

scripts/init-vlsi.sh

@@ -4,24 +4,25 @@
 set -e
 set -o pipefail
 
-# Initialize HAMMER and CAD-plugins
+# exit script if not in Chipyard conda env
-git submodule update --init --recursive vlsi/hammer
+if [[ `basename $CONDA_PREFIX` != .conda-env ]]; then
+    echo 'ERROR: Chipyard conda env not activated. Please source env.sh and run this script again.'
+    exit
+fi
+
+# Initialize HAMMER CAD-plugins
 if [[ $1 != *openroad* ]] && [[ $2 != *openroad* ]]; then
     git submodule update --init --recursive vlsi/hammer-cadence-plugins
+    pip install -e vlsi/hammer-cadence-plugins
     git submodule update --init --recursive vlsi/hammer-synopsys-plugins
+    pip install -e vlsi/hammer-synopsys-plugins
     git submodule update --init --recursive vlsi/hammer-mentor-plugins
+    pip install -e vlsi/hammer-mentor-plugins
 fi
 
 # Initialize HAMMER tech plugin
 # And add tech plugin to conda dependencies
 if [[ $1 != *asap7* ]] && [[ $1 != *sky130* ]]; then
     git submodule update --init --recursive vlsi/hammer-$1-plugin
-    echo '        '- -e ../vlsi/hammer-$1-plugin >> conda-reqs/vlsi.yaml
+    pip install -e vlsi/hammer-$1-plugin
 fi
-
-# Update the conda-env with the plugins
-if [[ `basename $CONDA_PREFIX` != .conda-env ]]; then
-    echo 'Activating Chipyard conda environment...'
-    source env.sh
-fi
-conda env update -f conda-reqs/vlsi.yaml