From 0eaa3fc75233e7adb9e4e6f4f754b02164c8871f Mon Sep 17 00:00:00 2001 From: fusang Date: Tue, 23 Jun 2026 22:38:04 +0800 Subject: [PATCH 1/2] docs: add Docker quickstart for gcd on nangate45 Add a short verified walkthrough for the default ORFS smoke test and fix the GDS output path in index.md to include the base flow variant. Signed-off-by: fusang Co-authored-by: Cursor --- docs/index.md | 5 +- docs/toc.yml | 2 + docs/tutorials/QuickstartGcdNangate45.md | 114 +++++++++++++++++++++++ docs/tutorials/TutorialHome.md | 3 + 4 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/QuickstartGcdNangate45.md diff --git a/docs/index.md b/docs/index.md index 2c78e4310a..65e50d21b8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -120,9 +120,10 @@ make By default, the `gcd` design is selected using the `nangate45` platform. The resulting GDS will be available at -`flow/results/nangate45/gcd/6_final.gds`. The flow should take only a few +`flow/results/nangate45/gcd/base/6_final.gds`. The flow should take only a few minutes to produce a GDS for this design. We recommend implementing this -design first to validate your flow and tool setup. +design first to validate your flow and tool setup. For a minimal Docker-only +walkthrough, see the [gcd quickstart](tutorials/QuickstartGcdNangate45.md). ### Design exploration and automatic parameter tuning diff --git a/docs/toc.yml b/docs/toc.yml index 722c933ca5..f553b41922 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -45,6 +45,8 @@ entries: - file: tutorials/TutorialHome title: Tutorials entries: + - file: tutorials/QuickstartGcdNangate45 + title: "Quickstart: gcd on nangate45 (Docker)" - file: tutorials/FlowTutorial title: Flow Tutorial - file: tutorials/Notebooks diff --git a/docs/tutorials/QuickstartGcdNangate45.md b/docs/tutorials/QuickstartGcdNangate45.md new file mode 100644 index 0000000000..4b133cd7c0 --- /dev/null +++ b/docs/tutorials/QuickstartGcdNangate45.md @@ -0,0 +1,114 @@ +# Quickstart: Run gcd on nangate45 with Docker + +This guide runs the smallest ORFS smoke test ¡ª the `gcd` design on the +`nangate45` platform ¡ª from RTL to GDS using the pre-built Docker image. +No local compilation is required. + +For the full RTL-to-GDS walkthrough with interactive examples, see the +[Flow Tutorial](FlowTutorial.md). + +## Prerequisites + +- Docker installed and running (Docker Desktop with WSL integration on Windows) +- At least 1 CPU core and 8 GB RAM (4 cores recommended) +- A clone of [OpenROAD-flow-scripts](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts) + +## One-time setup: pull the Docker image + +Downloading the image is separate from running the flow. Do this once: + +```shell +docker pull openroad/orfs:latest +``` + +## Run the flow + +From the root of your `OpenROAD-flow-scripts` clone: + +```shell +cd flow +util/docker_shell make +``` + +The `Makefile` defaults to `DESIGN_CONFIG=./designs/nangate45/gcd/config.mk`, +so no extra flags are needed for this quickstart. + +To select the design explicitly: + +```shell +util/docker_shell make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk +``` + +On success, `make` prints a stage summary table at the end. For `gcd`, the +total runtime is typically **under five minutes** on a modern machine. A full +clean run on WSL2 with Docker Desktop completed in about one minute in our +verification (see [Verified environment](#verified-environment) below). + +## Expected output + +Final layout files are written under the `base` flow variant: + +| Artifact | Path | +|----------|------| +| GDSII | `flow/results/nangate45/gcd/base/6_final.gds` | +| DEF | `flow/results/nangate45/gcd/base/6_final.def` | +| Logs | `flow/logs/nangate45/gcd/base/` | + +Confirm the GDS exists: + +```shell +ls -lh results/nangate45/gcd/base/6_final.gds +``` + +## Optional: view the layout in the GUI + +If you have an X11 display available (for example, WSLg on Windows 11): + +```shell +util/docker_shell make gui_final +``` + +This opens the finished layout in the OpenROAD GUI. It is not required to +validate that the flow completed successfully. + +## Troubleshooting + +### `xauth` warnings when running headless + +When no graphical display is available, `util/docker_shell` may print `xauth` +warnings. These can be ignored for `make`; they do not affect RTL-to-GDS +execution. + +### Image not found + +If Docker reports that `openroad/orfs:latest` is missing, run: + +```shell +docker pull openroad/orfs:latest +``` + +### Re-running from scratch + +To remove previous results for this design and run all stages again: + +```shell +util/docker_shell make clean_all +util/docker_shell make +``` + +## Next steps + +- Read the [Flow Tutorial](FlowTutorial.md) for stage-by-stage exploration +- See [Docker Shell](../user/DockerShell.md) for other `docker_shell` options +- See [Adding New Designs](../user/AddingNewDesign.md) to bring your own RTL + +## Verified environment + +This quickstart was verified with: + +- OS: WSL2 (Linux) +- Docker: Docker Desktop 28.4.0 +- Image: `openroad/orfs:latest` +- Command: `util/docker_shell make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk` +- Full clean run (`make clean_all` then `make`): ~61 seconds wall time +- Output: `flow/results/nangate45/gcd/base/6_final.gds` present diff --git a/docs/tutorials/TutorialHome.md b/docs/tutorials/TutorialHome.md index 9f56cb795c..963738439f 100644 --- a/docs/tutorials/TutorialHome.md +++ b/docs/tutorials/TutorialHome.md @@ -1,5 +1,8 @@ # OpenROAD-flow-scripts tutorial +New users can run the smallest smoke test in a few minutes with Docker: +[Quickstart: gcd on nangate45](QuickstartGcdNangate45.md). + The links to the main flow tutorial, where we go through each step of the RTL-GDSII flow are as [follows](FlowTutorial.md). We have also provided Google Colab packaging for ease of experimentation [here](Notebooks.md). From 8ed48e42ce401fa3072004747e30f78fdb1ee9ab Mon Sep 17 00:00:00 2001 From: fusang Date: Tue, 23 Jun 2026 23:02:50 +0800 Subject: [PATCH 2/2] docs: address review feedback on gcd quickstart Use ASCII dashes and paths relative to the flow directory for consistency. Signed-off-by: fusang Co-authored-by: Cursor --- docs/tutorials/QuickstartGcdNangate45.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/QuickstartGcdNangate45.md b/docs/tutorials/QuickstartGcdNangate45.md index 4b133cd7c0..5f04f683de 100644 --- a/docs/tutorials/QuickstartGcdNangate45.md +++ b/docs/tutorials/QuickstartGcdNangate45.md @@ -1,7 +1,7 @@ # Quickstart: Run gcd on nangate45 with Docker -This guide runs the smallest ORFS smoke test ¡ª the `gcd` design on the -`nangate45` platform ¡ª from RTL to GDS using the pre-built Docker image. +This guide runs the smallest ORFS smoke test -- the `gcd` design on the +`nangate45` platform -- from RTL to GDS using the pre-built Docker image. No local compilation is required. For the full RTL-to-GDS walkthrough with interactive examples, see the @@ -50,9 +50,9 @@ Final layout files are written under the `base` flow variant: | Artifact | Path | |----------|------| -| GDSII | `flow/results/nangate45/gcd/base/6_final.gds` | -| DEF | `flow/results/nangate45/gcd/base/6_final.def` | -| Logs | `flow/logs/nangate45/gcd/base/` | +| GDSII | `results/nangate45/gcd/base/6_final.gds` | +| DEF | `results/nangate45/gcd/base/6_final.def` | +| Logs | `logs/nangate45/gcd/base/` | Confirm the GDS exists: @@ -111,4 +111,4 @@ This quickstart was verified with: - Image: `openroad/orfs:latest` - Command: `util/docker_shell make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk` - Full clean run (`make clean_all` then `make`): ~61 seconds wall time -- Output: `flow/results/nangate45/gcd/base/6_final.gds` present +- Output: `results/nangate45/gcd/base/6_final.gds` present