全文 - 第01 部分- openroad-flow-scripts UserGuide

原文

01. 用户指南

OpenROAD 项目使用三个工具来执行自动化的 RTL 到 GDS 版图生成：

1. yosys：逻辑综合
2. OpenROAD：
   从布图规划到详细布线
3. KLayout：GDS 合并、DRC 和 LVS（针对公共
   PDK）

为了实现 RTL 到 GDS 的自动化，我们提供了
OpenROAD Flow，
其中包含集成上述三个工具的脚本。

代码组织

OpenROAD Flow
仓库是一个使用 OpenROAD 工具的 RTL 到 GDS 示例流程。仓库中的
build_openroad.sh 脚本会自动构建 OpenROAD 工具链。

两个主要目录是：

1. tools/：包含完整的 yosys 和
   OpenROAD App
   的源代码（两者均通过子模块引入），以及流程所需的其他工具。
2. flow/：包含用于运行设计流程的参考配方和脚本。它还包含公共平台
   和测试设计。

环境搭建

请参阅快速上手指南。

使用 OpenROAD Flow

有关流程的详细信息以及如何通过流程运行设计，请参阅
这里的文档。

使用 OpenROAD App

有关该应用程序及其可用功能和命令的详细信息，请参阅
这里
的文档。

02. 使用预编译二进制文件

安装 KLayout 和 Yosys

请确保 KLayout 的版本（以 klayoutVersion 变量表示）与
DependencyInstaller 脚本
中使用的版本一致。

安装说明：

• Klayout>=0.28.8
• Yosys>=0.58

安装 OpenROAD

从 Precision Innovations 的 GitHub releases 页面下载包含
自足依赖项的预编译二进制文件，地址在
这里。

感谢 Precision Innovations 托管并
维护这些二进制文件。

目前支持以下平台：

• Ubuntu 20.04/22.04
• Debian 11

按以下步骤下载：

第 1 步：点击 Precision Innovations 的 GitHub releases 链接。

第 2 步：下载适用于您发行版的构建产物。

第 3 步：根据平台使用软件包安装器运行安装命令。
例如 Ubuntu 20.04 使用：

sudo apt install ./openroad_2.0_amd64-ubuntu20.04.deb

验证安装

您可以以非递归方式克隆 OpenROAD-flow-scripts 仓库。

git clone https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git

相应地导出路径变量。

# 这些变量在 flow/Makefile 中使用。请务必确保 yosys 路径已生效。
export OPENROAD_EXE=$(command -v openroad)
export YOSYS_EXE=$(command -v yosys)

# 仅当 KLayout 是从源码构建时才需要
export LD_LIBRARY_PATH="<klayout_location>/bin:$PATH"

yosys -help
yosys -m slang -p "slang_version"
openroad -help
cd flow
make
make gui_final

03. 使用 Docker 从源码构建

:::{Note}
本文档介绍如何构建您自己的 Docker 镜像。
如果您的目标是使用最新版本的 OpenROAD-Flow-Scripts，
请参阅 Docker Shell 文档。
:::

前提条件

• 使用此方法，您只需在机器上安装
  Docker。
• 确保按照我们的系统要求，
  为虚拟机（VM）分配了足够的内存。有关设置 CPU 核心数和内存限制，
  请参阅这份 Docker 指南。

:::{Warning}
build_openroad.sh 将使用主机的 CPU 数量来编译 openroad。

请检查您的 Docker 守护进程设置，确保所有主机 CPU 都可用。如果不
确定，可以使用下面的命令检查。如果输出的数字与您机器的 CPU 数量
不同，建议您限制脚本使用的 CPU 数量（见下文说明）。
:::

docker run --rm ubuntu:22.04 nproc

基于预编译二进制文件使用 Docker 构建

感谢 Precision Innovations，
他们定期发布适用于 Ubuntu 和 Debian 的 OpenROAD .deb 安装包。
这大大减少了所需的编译时间。

我们建议使用受支持操作系统的 Docker 镜像，并使用来自
Precision Innovations 的预编译二进制文件安装 OpenROAD。
您可以使用下面的命令以交互模式启动容器。

docker run -it ubuntu:22.04

现在您已准备好安装预编译二进制文件。
安装预编译二进制文件的说明请参阅
这里。

基于源码使用 Docker 构建

另外，如果您希望使用 OpenROAD 仓库的最新提交，
请按照下面的说明操作。

克隆并构建

以下说明以 Ubuntu 22.04 作为基础操作系统构建 Docker 镜像：

git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
cd OpenROAD-flow-scripts
./build_openroad.sh

您可以使用 -t|--threads N 参数限制 CPU 数量：

./build_openroad.sh --threads N

验证安装

二进制文件只能在 Docker 容器内部使用。下面是一个从已创建的
Docker 镜像启动容器的示例。

docker run --rm -it -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/flow:/OpenROAD-flow-scripts/flow openroad/orfs

然后，在 docker 内部：

source ./env.sh
yosys -help
yosys -m slang -p "slang_version"
openroad -help
cd flow
make
exit

另外，您也可以按如下方式使用 docker_shell 实用工具。
请务必确保您位于 flow 目录中。

cd flow
util/docker_shell make

启用 GUI 支持

要使用 GUI 功能，您需要使用以下命令启动 docker，

适用于 Ubuntu/Debian 操作系统用户：

docker run --rm -it \
           -u $(id -u ${USER}):$(id -g ${USER}) \
           -v $(pwd)/flow:/OpenROAD-flow-scripts/flow \
           -e DISPLAY=${DISPLAY} \
           -v /tmp/.X11-unix:/tmp/.X11-unix \
           -v ${HOME}/.Xauthority:/.Xauthority \
           --network host \
           --security-opt seccomp=unconfined \
           openroad/orfs

在 Mac OS X 上使用 Docker 运行 GUI 的用户，请参阅
这里。

然后使用：

docker run --rm -it -e DISPLAY=<IP_LIKE_FROM_TUTORIAL>:0 --network host --privileged <IMAGE_NAME>

另外，您也可以按如下方式使用 docker_shell 实用工具来运行 GUI。
请务必确保您位于 flow 目录中。

cd flow
util/docker_shell gui_final

`docker_shell` 是一个实用的工具，它使用用户的参数来自动化执行
上述 Docker 命令。请参阅[这里](./DockerShell.md)的文档。

为不同操作系统构建 Docker 镜像

以下说明以参数化的操作系统分两个阶段构建 Docker 镜像。这些说明
面向 CI 以及希望使用 Ubuntu 22.04 以外操作系统的开发者；普通用户
应使用前面章节中的步骤。dev 阶段安装运行 OpenROAD 和
OpenROAD Flow Scripts 所需的所有依赖项和软件包。builder 阶段生成
运行流程所需的全部二进制文件（即 openroad 和 yosys）。

git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
cd OpenROAD-flow-scripts
./etc/DockerHelper.sh create -target=dev -os=$OS_NAME
./etc/DockerHelper.sh create -target=builder -os=$OS_NAME

04. 使用 Docker 镜像构建示例设计

==============================

docker_shell 脚本用于通过 OpenROAD-flow-scripts 的 Docker 镜像
启动命令。

此外，当前工作目录会以当前用户的凭据映射到 Docker 镜像中。

构建 Docker 镜像

如果您想使用 master 分支的最新版本，可以跳过此步骤。如果您正在
开发 ORFS/OR，则应当构建自己的镜像。

cd OpenROAD-flow-scripts
./build_openroad.sh

使用 docker_shell 运行 ORFS

构建一个示例设计并运行 GUI：

cd flow
util/docker_shell make
util/docker_shell make gui_final

您也可以启动一个交互式 bash 会话：

util/docker_shell bash

如果您需要使用与默认不同的 Docker 镜像，可以通过 docker_shell_IMAGE
环境变量进行覆盖：

OR_IMAGE=openroad/orfs:v1234 util/docker_shell make

如果您的 OpenROAD Docker 镜像是使用预编译二进制文件构建的，
您可能需要按如下方式为模块指定自定义路径。

OR_IMAGE=openroad_prebuilt_image YOSYS_EXE=/oss-cad-suite/bin/yosys util/docker_shell make

在 OpenROAD-flow-scripts/flow 文件夹之外使用 docker_shell

如果您的设计保存在一个并非 OpenROAD-flow-scripts git 仓库分叉
（fork）的 git 源码仓库中，您仍然可以使用 docker_shell 脚本。

使用 docker_shell 的两种方式：

1. 直接从 ORFS 所在位置调用它。
2. 将该脚本复制到您的源码文件夹中。这样您就可以构建 Docker 镜像并
   发布到私有 Docker 仓库，并将 ORFS 版本锁定为与您源码相对应的
   版本。这为您提供了一种轻松部署 ORFS 更新的方式：发布新的
   Docker 镜像、修改 docker_shell 的副本，并创建拉取请求
   （pull request），以便在您的私有构建服务器上测试升级。

05. 在 Docker 中运行 Claude Code

claude.sh 脚本在 Docker 容器内运行
Claude Code，
并带有 --dangerously-skip-permissions 参数。该容器提供了一个
沙箱环境，Claude Code 在其中拥有完整的 shell 访问权限，但除挂载的
仓库之外无法影响主机系统。

该容器支持：

• 使用 CMake 和 Bazel 构建和测试 OpenROAD
• 运行 ORFS 流程（基于 Makefile 的 RTL-GDSII）
• 通过卷挂载将所有文件更改同步反映到主机上

前提条件

• 在您的机器上安装 Docker
• Claude Code 凭据（在主机上运行一次 claude 进行身份验证，
  或在您的环境中设置 ANTHROPIC_API_KEY）

快速上手

./claude.sh

首次运行时会自动构建 Docker 镜像。来自 ~/.claude/ 的凭据会被
挂载到容器中。ORFS 环境（env.sh）会自动加载，因此工具无需任何
手动设置即可在 PATH 中使用。

用法

./claude.sh [OPTIONS] [-- CLAUDE_ARGS...]

选项

-- 之后的参数会直接传递给 claude。

示例

# 交互式 Claude Code 会话
./claude.sh

# 向 Claude Code 传递提示词
./claude.sh -- -p "fix the failing test in src/drt"

# 交互式 bash shell（用于手动构建）
./claude.sh --shell

# 更新后强制重新构建镜像
./claude.sh --build

# 运行并行会话
CONTAINER_NAME=claude-2 ./claude.sh

在容器内构建和测试

使用 --shell 时，工具已经在 PATH 中：

# CMake 构建
./build_openroad.sh --local --no_init -t $(nproc)

# Bazel 构建
cd tools/OpenROAD && bazel build //...

# 运行 ORFS 流程
cd flow && make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk

Claude Code 可以在交互式会话中自主运行这些相同的命令。

跨运行持久化的内容

容器在退出时会被删除（--rm），但以下主机目录会被挂载，
因此其内容会保留：

环境变量

所有环境变量都是可选的。当在主机上设置时，它们会被传入容器。

工作原理

该配置由三个文件组成：

docker/Dockerfile.claude

在 openroad/flow-ubuntu22.04-dev 基础镜像（已包含所有
OpenROAD 构建依赖项）之上扩展了：

• Java 21 和 Bazelisk（用于 Bazel 8.x 构建）
• Node.js 22 LTS 和 Claude Code CLI
• VS Code CLI、sudo 及其他便利工具

镜像中没有复制任何源代码。所有内容都来自卷挂载。

docker/claude-entrypoint.sh

处理 UID/GID 映射，使容器内创建的文件在主机上具有正确的
所有权。该入口点脚本会：

1. 创建与主机 UID/GID 匹配的用户
2. 加载 env.sh 以设置工具路径
3. 在运行命令之前通过 setpriv 降低权限

这遵循了与 tools/OpenROAD/etc/docker-entrypoint.sh 以及
flow/util/docker_shell 中 --user 模式相同的模式。

claude.sh

封装脚本，使用正确的卷挂载、环境变量和入口点参数来组装
docker run 命令。

安全模型

Claude Code 在容器内部以 --dangerously-skip-permissions
运行，这意味着它无需确认即可执行任何 shell 命令。Docker 容器
提供了隔离：

• 文件访问仅限于挂载的仓库
• 无法访问主机系统的软件包、服务或其他项目
• 无法访问绑定到 localhost 的主机网络服务
• docker kill claude-orfs 可立即停止一切

:::{Warning}
容器具有网络访问权限（Anthropic API 和 Bazel 依赖项获取需要）。
原则上 Claude Code 可以发起出站网络请求。如果担心这一点，请使用
Docker 网络策略将出站流量限制为仅允许访问 Anthropic API 端点。
:::

06. 从源码本地构建

克隆并安装依赖项

setup.sh 脚本会安装所有依赖项，包括 OpenROAD 的依赖项（如果
尚未安装的话）。

支持的配置为：Ubuntu 20.04、Ubuntu 22.04、Ubuntu 22.04（aarch64）、
RHEL 8、RockyLinux 9 和 Debian 11。

git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
cd OpenROAD-flow-scripts
sudo ./setup.sh

使用 Bazel 构建 OpenROAD 并运行 ORFS 流程（不受支持）

面向 ORFS/OpenROAD 开发者。当使用 Bazel 构建 OpenROAD 时，
./setup.sh 中的大部分内容并不需要——这里提供的是构建
OpenROAD 并测试 ORFS 流程的最低限度配置。无需 sudo。
请先安装 Bazelisk。

git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
cd OpenROAD-flow-scripts
bazelisk run //:install_for_bazel
cd flow && make

构建

./build_openroad.sh --local

:::{Note}
每次构建都会在主目录中生成一个 build_openroad.log 文件。
如需提交 issue，可以将它上传到 OpenROAD-flow-scripts 仓库
issue 表单
的「Relevant log output」（相关日志输出）部分。
:::

验证安装

设置好环境后，二进制文件应该可以在您的 $PATH 中使用。
make 命令会使用 nangate45 PDK 为默认设计 gcd 运行从
RTL 到 GDSII 的生成流程。

source ./env.sh
yosys -help
yosys -m slang -p "slang_version"
openroad -help
cd flow
make

您可以使用以下命令在 OpenROAD GUI 中查看最终版图图像。

make gui_final

在 Visual Studio Code 中编译和调试

使用 dev_env.sh 设置环境变量，然后启动 Visual Studio Code。
请确保已安装 CMake 插件。

. ./dev_env.sh
code tools/OpenROAD/

使用 Bazel 构建 OpenROAD 并运行一些 ORFS 流程

本地使用场景：

• 仅安装 Bazelisk，无需其他依赖项，也不需要运行 sudo ./setup.sh
• 修改并构建 OpenROAD
• 用几个 ORFS 流程测试构建好的 OpenROAD

OpenROAD 和 ORFS 中的 Bazel 支持仍在开发中，在深入探索 Bazel
构建之前，建议先积累一些 Bazel 使用经验。

欢迎贡献代码！

要构建 designs/asap7/gcd:gcd_floorplan：

cd flow
(cd ../tools/OpenROAD && bazel build :openroad -c opt) && bazelisk build designs/asap7/gcd:gcd_floorplan

或者运行当前 Bazel 中可用的所有流程：

cd flow
(cd ../tools/OpenROAD && bazel build :openroad -c opt) && bazelisk build ...

注意！在 OpenROAD 切换到 bzlmod 之前，ORFS 以临时过渡的方式使用
OpenROAD 的 Bazel 构建产物；切换之后，构建所有流程会变得更简单，
因为 ORFS 将直接构建所需的 OpenROAD：

cd flow
bazelisk build ...

ORFS 使用 bazel-orfs
来实现流程，并从 Docker 镜像中获取部分依赖项（如 yosys）。随着
时间推移，所有依赖项都将使用 Bazel 构建，对 ORFS Docker 镜像的
依赖将逐步淘汰。

使用最新的 bazel-orfs 和 ORFS Docker 镜像升级 MODULE.bazel

运行：

bazelisk run @bazel-orfs//:bump

然后提交 MODULE.bazel 和 MODULE.bazel.lock。

07. 使用 WSL 构建

Windows Subsystem for Linux（简称 WSL）可以让您在 Windows 机器上
挂载一个基于 Linux 的操作系统，从而使您既能在本地也能通过 Docker
构建 OpenROAD-flow-scripts。

安装 WSL

WSL 的安装说明见
这里。
您可以使用任何受支持的内核发行版，例如：Ubuntu 20.04、Ubuntu 22.04、
RHEL 8、RockyLinux 9、Debian 11。

我们建议用户继续按照下面的 Docker 构建指南操作。不过，如果您希望
在本地安装，可以按照这里的本地构建说明操作。

提示：您可以使用这份指南
删除您的 WSL 内核发行版。

Docker 配置

本节假设您已经在 Windows 上设置好了 Docker。如果没有，请参阅
Docker 官方网站的说明，地址在
这里。

您需要启用以下选项，以允许 WSL 使用 Docker。

General（常规）> Use the WSL 2 Based engine（使用基于 WSL 2 的引擎，
应为默认选项）

Resources（资源）> WSL integration（WSL 集成）> Enable integration
with my default WSL distro（启用与我的默认 WSL 发行版的集成），并
选择 “Ubuntu-22.04”，或您所安装的发行版。

访问 WSL

您可以通过名为 “Ubuntu 22.04 LTS” 的应用程序访问 WSL。运行以下命令：

sudo apt-get update; sudo apt-get upgrade; sudo apt install -y build-essential python3 python3-venv python3-pip make

验证 Docker 是否正在运行：

docker run hello-world

您应该看到：

Hello from Docker!
This message shows that your installation appears to be working correctly.

如果到这里一切顺利，恭喜！您已经配置好了一个带有必要依赖项的
Linux 系统，现在可以按照 Docker 指南
继续操作了。

08. 向 ORFS 添加新设计

本节介绍如何向 ORFS 仓库添加 Verilog 设计，以执行完整的
RTL-GDS 流程。

下面的设计示例基于 spm 设计，它使用 gf180 平台实现了一个
单端口存储器（Single-port memory）。此流程适用于您所选平台上的
任何设计。

注意： 以下命令以 OpenROAD-flow-scripts/flow 目录作为流程的
起始基准目录。

第 1 步： 根据顶层模块名创建 Verilog 源文件目录。

cd designs/src
mkdir spm
cd spm
vi spm.v

将这个
Verilog 代码复制到 spm.v 中。

第 2 步： 创建 config.mk 以定义设计配置。

cd designs/gf180
mkdir spm
cd spm
vi config.mk

第 3 步： 在 config.mk 中定义关键设计参数。

export PLATFORM         = gf180

export DESIGN_NAME      = spm

export VERILOG_FILES    = $(sort $(wildcard ./designs/src/$(DESIGN_NICKNAME)/*.v))
export SDC_FILE         = ./designs/$(PLATFORM)/$(DESIGN_NICKNAME)/constraint.sdc

export CORE_UTILIZATION = 40
export PLACE_DENSITY    = 0.60

export TNS_END_PERCENT  = 100

要为 config.mk 定制或添加新变量，请参阅其他内置设计示例或
这里的流程变量列表。

第 4 步： 定义 SDC 约束。

cd designs/gf180/spm
vi constraint.sdc

根据需要编辑以定义设计约束。

current_design spm

set clk_name  core_clock
set clk_port_name clk
set clk_period 10
set clk_io_pct 0.2

set clk_port [get_ports $clk_port_name]

create_clock -name $clk_name -period $clk_period  $clk_port

set non_clock_inputs [lsearch -inline -all -not -exact [all_inputs] $clk_port]

set_input_delay  [expr $clk_period * $clk_io_pct] -clock $clk_name $non_clock_inputs
set_output_delay [expr $clk_period * $clk_io_pct] -clock $clk_name [all_outputs]

只需根据设计要求更新 current_design、clk_port_name 和
clk_period。默认模板中的其余值请勿修改。

第 5 步： 将设计名称添加到 Makefile，以便使用 make
命令运行流程。

vi Makefile

如果已有启用的 DESIGN_CONFIG，请将其注释（#）掉。

将以下行添加到 Makefile 中并保存更改。

DESIGN_CONFIG=./designs/gf180/spm/config.mk

运行 make 命令以执行从 RTL 到 GDSII 生成的流程。

make

如果您不想修改 Makefile，也可以直接运行：

make DESIGN_CONFIG=./designs/gf180/spm/config.mk