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:
  • 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:
  • 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:

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.