efabless/mpw_precheck

MPW Precheck

镜像概述和主要用途

MPW Precheck Docker镜像是efabless提供的自动化检查工具，用于在MPW（多项目晶圆）项目提交前验证设计是否符合规范。该工具通过一系列标准化检查确保项目在许可、网表结构、GDS布局、设计规则等方面满足提交要求，是MPW项目开发流程中的关键验证环节。

前提条件

• Docker环境

核心功能和特性

• 全面的合规性检查：涵盖许可验证、网表结构检查、GDS布局验证等多维度检查
• 自动化流程：按预设顺序执行检查，失败时提供明确错误信息
• 兼容性验证：确保设计与Caravel用户项目模板的一致性
• 设计规则检查：集成Magic和Klayout工具进行DRC验证
• 灵活配置：支持私有项目模式，可跳过开源相关检查

安装与设置

Docker镜像获取

可通过本地构建或从Dockerhub拉取两种方式获取镜像。

本地构建Docker镜像

bash
cd dependencies
sh build-docker.sh

从Dockerhub拉取镜像

从https://hub.docker.com/repository/docker/efabless/mpw_precheck/tags?page=1&ordering=last_updated%E6%8B%89%E5%8F%96%E6%9C%80%E6%96%B0%E9%95%9C%E5%83%8F%EF%BC%9A

bash
docker pull docker.xuanyuan.run/efabless/mpw_precheck:latest

PDK安装

如未安装PDK，请参考https://github.com/efabless/caravel.git%E9%A1%B9%E7%9B%AE%E7%9A%84Makefile%E8%BF%9B%E8%A1%8C%E5%AE%89%E8%A3%85%E3%80%82

使用前准备

• 确保已阅读并满足开源项目发布准备要求
• 用包含电源信息的综合网表覆盖verilog/gl/user_project_wrapper.v
• 将顶层GDS-II文件放在gds/目录下（路径：gds/user_project_wrapper.gds），该目录应压缩并通过Makefile解压
• 创建./third_party/used_external_repos.csv文件，记录所有使用的外部GitHub仓库信息（格式：仓库名称,提交哈希）
• 在./signoff/<macro-name>/final_summary_report.csv中包含设计统计信息（如单元数量、核心利用率等）。使用OpenLANE时，该文件会自动生成在<run path>/reports/final_summary_report.csv

脚本功能详解

该工具按顺序执行以下检查，任何检查失败都会中止并显示相应错误信息：

许可检查

• 项目根目录、子模块和第三方库包含至少一个批准的许可，不含任何禁止的许可
• 所有源文件包含批准的SPDX许可和版权头

Makefile检查

• Makefile包含至少GDS文件的压缩和解压目标

默认内容检查

• 项目内容与https://github.com/efabless/caravel_user_project.git%EF%BC%88%E6%95%B0%E5%AD%97%E9%A1%B9%E7%9B%AE%EF%BC%89%E6%88%96https://github.com/efabless/caravel_user_project_analog.git%EF%BC%88%E6%A8%A1%E6%8B%9F%E9%A1%B9%E7%9B%AE%EF%BC%89%E7%9A%84%E9%BB%98%E8%AE%A4%E5%86%85%E5%AE%B9%E4%B8%8D%E5%90%8C
• user_project_wrapper.gds与上述默认项目中的对应文件不同

文档检查

• 存在README.md文档，且不包含非包容性语言

一致性检查

对用户网表（user_project_wrapper/user_analog_project_wrapper）和顶层网表（caravel/caravan）执行一系列检查，确保符合黄金封装约束：

• 通用检查：
  • 建模检查：验证网表为结构化，不含行为级构造
  • 复杂度检查：验证网表非空且至少包含8个实例
• 顶层网表额外检查：
  • 子模块钩子：检查用户封装子模块端口连接与黄金封装端口匹配
  • 电源检查：检查网表中所有子模块均连接电源
• 用户网表额外检查：
  • 端口检查：检查网表端口名称与黄金封装端口匹配
  • 布局检查：检查网表与提供的用户封装布局在实例数量和名称上匹配

GPIO定义检查

验证项目verilog/rtl/user_defines.v网表中的Verilog指令

XOR检查

确保user_project_wrapper（数字项目对应https://github.com/efabless/caravel_user_project.git%EF%BC%8C%E6%A8%A1%E6%8B%9F%E9%A1%B9%E7%9B%AE%E5%AF%B9%E5%BA%94https://github.com/efabless/caravel_user_project_analog.git%EF%BC%89%E7%9A%84%E4%BF%AE%E6%94%B9%E4%BB%85%E5%9C%A8%E7%94%A8%E6%88%B7%E5%AE%9A%E4%B9%89%E5%8C%BA%E5%9F%9F%E5%86%85%EF%BC%88%E5%B7%A6%E4%B8%8B%E8%A7%92(0,0)%E8%87%B3%E5%8F%B3%E4%B8%8A%E8%A7%92(2920, 3520)）

设计规则检查

• MagicDRC：使用Magic工具检查user_project_wrapper.gds无DRC违规
• KlayoutBEOLDRC：使用Klayout检查user_project_wrapper.gds在https://skywater-pdk.readthedocs.io/en/main/rules/summary.html%E6%97%A0DRC%E8%BF%9D%E8%A7%84
• KlayoutFEOLDRC：使用Klayout检查user_project_wrapper.gds在https://skywater-pdk.readthedocs.io/en/main/rules/summary.html%E6%97%A0DRC%E8%BF%9D%E8%A7%84
• KlayoutOffgrid：检查user_project_wrapper.gds无网格违规（规则https://skywater-pdk.readthedocs.io/en/main/rules/periphery.html%EF%BC%89
• KlayoutMetalMinimumClearAreaDensity：检查user_project_wrapper.gds的5个金属层密度均低于https://skywater-pdk.readthedocs.io/en/main/rules/periphery.html%E8%A7%84%E5%AE%9A%E7%9A%84%E6%9C%80%E5%A4%A7%E5%AF%86%E5%BA%A6

LVS检查

平台默认禁用LVS，仅在本地运行时启用

• 对用户项目执行层次检查、软检查、LVS检查和ERC检查。详情参见相关文档

OEB检查

运行OEB检查，确保用户连接所有必要的OEB信号。详情参见相关文档

当前假设

• 用户模块名称为user_project_wrapper（模拟项目为user_analog_project_wrapper）
• mpw precheck在Docker容器内执行，其中存在Caravel的黄金副本，由环境变量GOLDEN_CARAVEL指定

LVS配置

为使LVS和OEB检查成功运行，用户必须提供LVS配置文件，描述设计层次结构并提供必要检查信息。配置文件编写方法参见相关文档

注意：如果从用户项目Makefile运行precheck，可通过DISABLE_LVS环境变量禁用LVS

使用方法

挂载Docker容器

bash
export PDK_PATH=<PDK"variant specific"的绝对路径>
export INPUT_DIRECTORY=<用户项目的绝对路径>
sh docker-mount.sh

运行命令

usage: mpw_precheck.py [-h] --input_directory $INPUT_DIRECTORY --pdk_path $PDK_PATH [--output_directory OUTPUT_DIRECTORY] [--private] [check [check ...]]

按顺序调用各种检查运行precheck工具。

位置参数:
  check                 要运行的检查（默认：无）

可选参数:
  -h, --help               显示此帮助消息并退出
  -i, --input_directory    $INPUT_DIRECTORY
                           项目的绝对路径（默认：无）
  -p, --pdk_path           $PDK_PATH
                           PDK"variant specific"的安装路径（默认：无）
  -o, --output_directory   OUTPUT_DIRECTORY
                           输出目录，默认=<input_directory>/precheck_results（默认：无）
  --private                如果提供，precheck将跳过用于验证项目是否符合开源项目要求的[许可、默认内容、文档]检查（默认：False）

故障排除

有关precheck问题的排查指南，请参见调试文档