Skip to content

Commit 5e676e5

Browse files
oharboeoharboe
committed
docs: add bazel-orfs beta test documentation
Add bazel-orfs.md with quick start guide, available targets, build results for 59 designs across 6 platforms, and status of blocked designs.
1 parent da6ce96 commit 5e676e5

1 file changed

Lines changed: 292 additions & 0 deletions

File tree

‎bazel-orfs.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# bazel-orfs Beta Test
2+
3+
This is an early integration of [bazel-orfs](https://github.com/The-OpenROAD-Project/bazel-orfs)
4+
into OpenROAD-flow-scripts. It lets you build ORFS designs with Bazel
5+
using the same `config.mk` files you already have.
6+
7+
**Status**: beta -- 59 designs across 6 public PDK platforms have
8+
`orfs_design()` enabled. 53 pass QoR tests; 6 designs are blocked on
9+
upstream fixes (see below). Platforms without public PDK files (gf12,
10+
gf55, rapidus2hp) are not wired up.
11+
12+
## Quick Start
13+
14+
```bash
15+
# Install bazelisk (one-time) -- see https://github.com/bazelbuild/bazelisk
16+
# Then, from the ORFS root:
17+
18+
# Synthesize gcd on asap7 (downloads Docker image on first run)
19+
bazelisk build //flow/designs/asap7/gcd:gcd_synth
20+
21+
# Run through floorplan
22+
bazelisk build //flow/designs/asap7/gcd:gcd_floorplan
23+
24+
# Full flow through final
25+
bazelisk build //flow/designs/asap7/gcd:gcd_final
26+
27+
# Run the test (includes QoR regression check)
28+
bazelisk test //flow/designs/asap7/gcd:gcd_test
29+
30+
# List all targets for a design
31+
bazelisk query //flow/designs/asap7/gcd:all
32+
```
33+
34+
## Available Targets Per Design
35+
36+
Each enabled design gets these targets automatically from its `config.mk`:
37+
38+
| Target suffix | What it does |
39+
|---|---|
40+
| `_synth` | Yosys synthesis |
41+
| `_floorplan` | Floorplan + I/O placement |
42+
| `_place` | Global + detailed placement |
43+
| `_cts` | Clock tree synthesis |
44+
| `_grt` | Global routing |
45+
| `_route` | Detailed routing |
46+
| `_final` | Final optimization + fill |
47+
| `_generate_abstract` | LEF/LIB abstract for hierarchical use |
48+
| `_generate_metadata` | Flow metadata (logs, reports) |
49+
| `_test` | Full flow + QoR regression check |
50+
51+
Each stage depends on the previous one, so building `_final` runs the
52+
entire flow.
53+
54+
## Working Designs (53 passing tests + 6 blocked)
55+
56+
All designs below have `orfs_design()` enabled. Designs marked
57+
**(blocked)** fail due to upstream issues in bazel-orfs or the
58+
design's verilog sources.
59+
60+
### asap7 (18 designs)
61+
62+
| Design | DESIGN_NAME | Notes |
63+
|--------|-------------|-------|
64+
| `gcd` | gcd | smoketest, ~1 min |
65+
| `gcd-ccs` | gcd | CCS lib model |
66+
| `aes` | aes_cipher_top | medium |
67+
| `aes-block` | aes_cipher_top | block variant |
68+
| `aes-mbff` | aes_cipher_top | MBFF |
69+
| `aes_lvt` | aes_cipher_top | LVT cells |
70+
| `ethmac` | ethmac | Ethernet MAC |
71+
| `ethmac_lvt` | ethmac | LVT cells |
72+
| `ibex` | ibex_core | RISC-V core (slang) |
73+
| `jpeg` | jpeg_encoder | JPEG encoder |
74+
| `jpeg_lvt` | jpeg_encoder | LVT cells |
75+
| `uart` | uart | UART |
76+
| `riscv32i` | riscv_top | RISC-V RV32I |
77+
| `riscv32i-mock-sram` | riscv_top | **(blocked)** PSM-0069 VDD connectivity |
78+
| `mock-cpu` | mock_cpu | mock CPU with FIFO |
79+
| `swerv_wrapper` | swerv_wrapper | SweRV EH1 |
80+
| `cva6` | cva6 | CVA6 RISC-V (~63 min) |
81+
| `mock-alu` | MockAlu | mock ALU |
82+
83+
### sky130hd (7 designs)
84+
85+
| Design | DESIGN_NAME | Notes |
86+
|--------|-------------|-------|
87+
| `gcd` | gcd | smoketest |
88+
| `aes` | aes_cipher_top | medium |
89+
| `ibex` | ibex_core | RISC-V core |
90+
| `jpeg` | jpeg_encoder | JPEG encoder |
91+
| `riscv32i` | riscv | RISC-V RV32I |
92+
| `chameleon` | soc_core | SoC with macros |
93+
| `microwatt` | microwatt | POWER ISA core |
94+
95+
### nangate45 (16 designs)
96+
97+
| Design | DESIGN_NAME | Notes |
98+
|--------|-------------|-------|
99+
| `gcd` | gcd | smoketest |
100+
| `aes` | aes_cipher_top | medium |
101+
| `ibex` | ibex_core | RISC-V core |
102+
| `jpeg` | jpeg_encoder | JPEG encoder |
103+
| `dynamic_node` | dynamic_node_top_wrap | NoC router |
104+
| `swerv` | swerv | SweRV EH1 |
105+
| `tinyRocket` | RocketTile | RISC-V Rocket |
106+
| `ariane133` | ariane | hierarchical |
107+
| `ariane136` | ariane | hierarchical |
108+
| `black_parrot` | black_parrot | **(blocked)** MPL-0020 macro name mismatch |
109+
| `bp_be_top` | bp_be_top | BP back-end |
110+
| `bp_fe_top` | bp_fe_top | BP front-end |
111+
| `bp_multi_top` | bp_multi_top | **(blocked)** OpenROAD crash in CTS |
112+
| `bp_quad` | black_parrot | **(blocked)** yosys check -assert fails |
113+
| `mempool_group` | mempool_group | **(blocked)** SV macro undefined in synth |
114+
| `swerv_wrapper` | swerv_wrapper | SweRV wrapped |
115+
116+
### gf180 (6 designs)
117+
118+
| Design | DESIGN_NAME | Notes |
119+
|--------|-------------|-------|
120+
| `aes` | aes_cipher_top | medium |
121+
| `aes-hybrid` | aes_cipher_top | hybrid variant |
122+
| `ibex` | ibex_core | RISC-V core |
123+
| `jpeg` | jpeg_encoder | JPEG encoder |
124+
| `riscv32i` | riscv | RISC-V RV32I |
125+
| `uart-blocks` | uart | hierarchical with uart_rx block |
126+
127+
### ihp-sg13g2 (7 designs)
128+
129+
| Design | DESIGN_NAME | Notes |
130+
|--------|-------------|-------|
131+
| `gcd` | gcd | smoketest |
132+
| `aes` | aes_cipher_top | medium |
133+
| `ibex` | ibex_core | RISC-V core |
134+
| `jpeg` | jpeg_encoder | JPEG encoder |
135+
| `riscv32i` | riscv | RISC-V RV32I |
136+
| `spi` | spi | SPI controller |
137+
| `i2c-gpio-expander` | I2cGpioExpanderTop | **(blocked)** PAD-0102 IO pad instance not found |
138+
139+
### sky130hs (5 designs)
140+
141+
| Design | DESIGN_NAME | Notes |
142+
|--------|-------------|-------|
143+
| `gcd` | gcd | smoketest |
144+
| `aes` | aes_cipher_top | medium |
145+
| `ibex` | ibex_core | RISC-V core |
146+
| `jpeg` | jpeg_encoder | JPEG encoder |
147+
| `riscv32i` | riscv | RISC-V RV32I |
148+
149+
## Designs Not Supported
150+
151+
### No VERILOG_FILES (minimal)
152+
153+
`asap7/minimal` is a test design with no `VERILOG_FILES` in config.mk
154+
(empty SDC). Not expected to work with `orfs_designs`.
155+
156+
### Platforms without public PDK
157+
158+
gf12, gf55, and rapidus2hp have design directories but no platform
159+
files in the open-source repo. These are skipped entirely.
160+
161+
## How to Add More Designs
162+
163+
1. Create `flow/designs/<platform>/<design>/BUILD.bazel`:
164+
165+
```starlark
166+
load("@bazel-orfs//:openroad.bzl", "orfs_design")
167+
load("@orfs_designs//:designs.bzl", "DESIGNS")
168+
169+
exports_files(glob(["*"]))
170+
171+
orfs_design(designs = DESIGNS)
172+
```
173+
174+
2. If `flow/designs/src/<name>/BUILD.bazel` doesn't exist, create it:
175+
176+
```starlark
177+
exports_files(
178+
glob(["*.v", "*.sv"], allow_empty = True),
179+
visibility = ["//visibility:public"],
180+
)
181+
182+
filegroup(
183+
name = "verilog",
184+
srcs = glob(include = ["*.v", "*.sv"], allow_empty = True),
185+
visibility = ["//visibility:public"],
186+
)
187+
```
188+
189+
3. Run `bazelisk query //flow/designs/<platform>/<design>:all` to verify.
190+
191+
## Using a Local bazel-orfs Checkout
192+
193+
To iterate on bazel-orfs rules locally, replace the `git_override` in
194+
`MODULE.bazel`:
195+
196+
```starlark
197+
# Comment out the git_override block, then add:
198+
local_path_override(
199+
module_name = "bazel-orfs",
200+
path = "/path/to/your/bazel-orfs",
201+
)
202+
```
203+
204+
Also update the `bazel-orfs-verilog` override:
205+
206+
```starlark
207+
local_path_override(
208+
module_name = "bazel-orfs-verilog",
209+
path = "/path/to/your/bazel-orfs/verilog",
210+
)
211+
```
212+
213+
## Key Differences from Make
214+
215+
- **Incremental**: Bazel caches every stage. Changing `PLACE_DENSITY`
216+
in `config.mk` rebuilds only floorplan onward -- synthesis is cached.
217+
- **Hermetic**: Tools come from a Docker image (extracted automatically).
218+
No `make install` or `PATH` setup needed.
219+
- **Parallel**: Independent designs build in parallel automatically.
220+
- **Reproducible**: Same inputs always produce the same outputs.
221+
222+
## Performance Notes
223+
224+
Each OpenROAD invocation uses `-threads <nproc>` (all available cores).
225+
When Bazel runs many designs in parallel, the machine becomes heavily
226+
overcommitted. On a 48-core machine, 50+ OpenROAD instances may run
227+
simultaneously during a full `bazelisk test ...`, each requesting 48
228+
threads.
229+
230+
To limit parallelism:
231+
232+
```bash
233+
# Limit to 4 concurrent OpenROAD invocations
234+
bazelisk test --jobs=4 ...
235+
```
236+
237+
A full test suite run (53 designs, 6 platforms) takes roughly 4-5 hours
238+
on a 48-core machine with default parallelism (overcommitted). Individual
239+
design times vary from ~1 minute (gcd) to ~63 minutes (cva6 on asap7).
240+
241+
## Updating Metric Thresholds
242+
243+
When OpenROAD or flow scripts change, metric thresholds in
244+
`rules-base.json` may go stale. To update them for a specific design:
245+
246+
```bash
247+
# Rebuilds the design and writes updated thresholds back to source
248+
bazelisk run //flow/designs/asap7/aes-block:aes_cipher_top_update
249+
```
250+
251+
The target name follows the pattern `<design_name>_update` where
252+
`<design_name>` comes from `DESIGN_NAME` in `config.mk`.
253+
254+
## Equivalence Checking (eqy)
255+
256+
Some designs (e.g. `aes`) set `EQUIVALENCE_CHECK=1` in their
257+
`config.mk` to enable equivalence checking of repair_timing. The
258+
actual `eqy` tool invocation is gated by a separate `RUN_EQY`
259+
variable (default 0), so builds don't fail when eqy is not installed.
260+
CI sets `RUN_EQY=1` when eqy is available.
261+
262+
## Workflow: Unmerged Commits
263+
264+
This PR serves as a working branch against master. Commits here are
265+
spun off as separate, focused PRs for review. Once a PR merges, this
266+
branch is rebased on master to drop the merged commit. The branch is
267+
force-pushed after each rebase so the PR commit list is always the
268+
source of truth for what's pending.
269+
270+
Filing of PRs is throttled to avoid overwhelming maintainers --
271+
submitting too many at once just causes "maintainer packet dropping"
272+
where reviews stall.
273+
274+
## Known Limitations
275+
276+
- The Docker image is pinned; updating it requires changing
277+
`MODULE.bazel`.
278+
- Platforms without public PDK files (gf12, gf55, rapidus2hp) are not
279+
supported.
280+
- **black_parrot**: macro_placement.tcl references macro names that
281+
don't match the synthesized netlist (MPL-0020).
282+
- **bp_multi_top**: OpenROAD crashes (SIGSEGV) during CTS timing
283+
analysis.
284+
- **bp_quad**: yosys `check -assert` finds 9 problems during synthesis.
285+
- **i2c-gpio-expander**: IO pad instance `sg13g2_IOPad_io_gpio_3` not
286+
found during floorplan (PAD-0102).
287+
- **mempool_group**: SystemVerilog macros (`AXI_TYPEDEF_RESP_T` etc.)
288+
are undefined -- likely a missing include path in the bazel build.
289+
- **riscv32i-mock-sram**: VDD connectivity check fails at final stage
290+
(PSM-0069) -- fakeram macro power pins are unconnected.
291+
- This is a beta -- expect rough edges. File issues at
292+
https://github.com/The-OpenROAD-Project/bazel-orfs/issues

0 commit comments

Comments
 (0)