MPW Precheck

Prerequisites

• Docker

Setup

Docker

You can either build the docker locally or fetch it from dockerhub.

Build Docker Locally

To build the necessary docker locally, run:

    cd dependencies
    sh build-docker.sh

Pull Docker from Dockerhub

To pull the necessary docker from dockerhub, run:

    docker pull efabless/mpw_precheck:latest

Install the PDK

If you don't have the skywater-pdk installed, run:

    export PDK_ROOT=<absolute path to where skywater-pdk and open_pdks will reside>
    cd dependencies
    sh build-pdk.sh

Before Using

• Before you run the precheck tool, make sure you go through https://opensource.google/docs/releasing/preparing/ and cover the requirements.

• Overwrite verilog/gl/user_project_wrapper.v with your synthesized netlist make sure the netlist includes power information. Otherwise, point to it properly in your info.yaml. You can alternatively use spice files for both caravel and user_project_wrapper. Keep on reading for this point to make more sense.

• Make sure you have the top level GDS-II under a directory called gds/; thus containing gds/user_project_wrapper.gds, this directory should be compressed and the script will use your Makefile to uncompress it.

• Please create a file ./third_party/used_external_repos.csv and add to it all repository name,commit hash for any external github repository that you are using to build this project.

• Please include any useful statistics about your design, i.e. cell count, core utilization, etc. in a .csv file under ./signoff/<macro-name>/final_summary_report.csv. If you're using OpenLANE then, this file should be created automatically in <run path>/reports/final_summary_report.csv.

What Does the Script Do?

It runs a sequence of checks and aborts with the appropriate error message(s) if any of them fails.

The steps are as follows:

• License:
  • The root directory of the project, submodules and third party libraries contain at least one approved license and does not contain any prohibitted license
  • All source files contain an approved SPDX License and Copyright Headers
• Manifest:
  • Caravel version used in development is the latest
• Makefile:
  • Makefile targets contain at least compression and uncompression for the user_project_wrapper.gds file
• Defaults:
  • Contents of the project are different from the default content in caravel_user_project for digital projects and caravel_user_project_analog
  • The info.yaml must contain fields that different from the default fields
  • The user_project_wrapper.gds must be different from the default one found in caravel_user_project for digital projects and caravel_user_project_analog for analog projects
• Documentation:
  • Documentation file README.md exists and does not use any non-inclusive language
• Consistency:
  • Runs a series of checks on the user netlist (user_project_wrapper/user_analog_project_wrapper), and the top netlist (caravel/caravan) to make sure that both conform to the constraints put by the golden wrapper.
    • Both Netlists share the following checks:
      • Modeling check: check netlist is structural and doesn't contain behavioral constructs
      • Complexity check: check netlist isn't empty and contains at least eight instances
    • Remaining Top Netlist checks:
      • Sub-module hooks: check the user wrapper submodule port connections match the golden wrapper ports
      • Power check: check all submodules in the netlist are connected to power
    • Remaining User Netlist checks:
      • Ports check: check netlist port names match the golden wrapper ports
      • Layout check: check netlist matches the provided user wrapper layout in terms of the number of instances, and the instance names
• XOR:
  • No modification in the user_project_wrapper(versus default user_project_wrapper.gds in caravel_user_project for digital projects and caravel_user_project_analog for analog projects) outside the user defined area lower left corner (0,0) and upper right corner (2920, 3520)
• MagicDRC:
  • The user_project_wrapper.gds does not have any DRC violations(using magic vlsi tool)
• KlayoutFEOLDRC:
  • The user_project_wrapper.gds does not have any DRC violations(using klayout) in the Front End Of Line layers
• KlayoutOffgrid:
  • The user_project_wrapper.gds does not contain any shapes that have offgrid violations(rules x.1b, x.3a, x.2, x.2c)
• KlayoutMetalMinimumClearAreaDensity:
  • The user_project_wrapper.gds has metal density (for each of the 5 metal layers) that is the lower than the maximum metal density specified by the li1.pd.ld, m1.pd.ld, m2.pd.ld, m3.pd.ld, m4.pd.ld, m5.pd.ld rules

Current Assumptions

• The user module name is user_project_wrapper (or `user_analog_project_wrapper' for caravel_user_project_analog)
• Caravel is submoduled inside the user project or installed at a different path specified by CARAVEL_ROOT.

How To Run

Mount the docker file:

export PDK_ROOT=<Absolute path to parent of sky130A. Installed PDK root.>
export INPUT_DIRECTORY=<Absolute path to the user project path>
# if caravel is submoduled under the user project, run "export CARAVEL_ROOT=$INPUT_DIRECTORY/caravel"
export CARAVEL_ROOT=<Absolute path to caravel>
sh docker-mount.sh

Run the following command:

usage: mpw_precheck.py [-h] --input_directory INPUT_DIRECTORY --caravel_root CARAVEL_ROOT --pdk_root PDK_ROOT 
                       [--output_directory OUTPUT_DIRECTORY] [--private] [check [check ...]]

Runs the precheck tool by calling the various checks in order.

positional arguments:

  check                 Checks to be ran by the precheck (default: None)

optional arguments:

  -h, --help            show this help message and exit
  
  --input_directory INPUT_DIRECTORY, -i INPUT_DIRECTORY
                        INPUT_DIRECTORY Absolute Path to the project. (default: None)
  
  --caravel_root CARAVEL_ROOT, -cr CARAVEL_ROOT
                        CARAVEL_ROOT Absolute Path to caravel. (default: None)
  
  --pdk_root PDK_ROOT, -p PDK_ROOT
                        PDK_ROOT, points to pdk installation path (default: None)
  
  --output_directory OUTPUT_DIRECTORY, -o OUTPUT_DIRECTORY
                        Output Directory,
                        default=<input_directory>/precheck_results. (default:None)
  
  --private             If provided, precheck skips [License, Defaults, Documentation] 
                        checks used to qualify the project to as an Open Source Project (default: False)

How to Troubleshoot Issues with Precheck

See the following document for guidance on troubleshooting issues with precheck.