Add --package-only to aws_build_dcp_from_cl.py to package an existing DCP by WajahatRiaz · Pull Request #805 · aws/aws-fpga

WajahatRiaz · 2026-08-25T07:53:20Z

Summary

aws_build_dcp_from_cl.py always starts Vivado, then packages the post-route DCP into a Developer CL tarball. If packaging fails after a successful implementation (for example AWS_FPGA_REPO_DIR is unset or points at the wrong tree, so release_version.txt cannot be read), the DCP is already on disk but the only supported recovery is to re-run the full build.

This PR adds --package-only so the same script can skip Vivado and package an existing checkpoint. The tag (-t) must match $CL_DIR/build/checkpoints/<cl>.<tag>.post_route.dcp. Without --package-only, BuildAll is unchanged.

The flag is documented in hdk/README.md and docs-rtd/source/hdk/README.rst.

Usage

export CL_DIR=<path-to-cl>
cd $CL_DIR/build/scripts
./aws_build_dcp_from_cl.py -c <cl_name> --package-only -t YYYY_MM_DD-HHMMSS

Test plan

Verified on cl_axil_reg_access (tag 2026_08_25-071852).

`--package-only` with a valid `-t` skips Vivado and writes the tarball

About 1 second; Vivado is not started.

$ ./aws_build_dcp_from_cl.py -c cl_axil_reg_access --package-only -t 2026_08_25-071852
==================================================
Running CL builds
==================================================
cl               : cl_axil_reg_access
mode             : small_shell
flow             : BuildAll
aws_clk_gen      : None
clock_recipe_a   : A1
clock_recipe_b   : B2
clock_recipe_c   : C0
clock_recipe_hbm : H2
place_direct     : SSI_SpreadLogic_high
phy_opt_direct   : AggressiveExplore
route_direct     : AggressiveExplore
build_tag        : 2026_08_25-071852
encrypt          : True
package_only     : True
==================================================

AWS FPGA: 2026-08-25 07:39:05 - Build starts

AWS FPGA: --package-only set, skipping Vivado and packaging tag 2026_08_25-071852

34f3cce82c79d3bd441a2f8ec0406cb0753d9d4f6c7e792b96d9b93561888800  .../cl_axil_reg_access.2026_08_25-071852.post_route.dcp

AWS FPGA: 2026-08-25 07:39:06 - Build completes

AWS FPGA: Build Time = 0:00:01.084498.

`--help` lists the flag

$ ./aws_build_dcp_from_cl.py --help
  --package-only        Skip Vivado and package an existing post-route DCP.
                        Requires --tag matching the checkpoint timestamp.

`--package-only` without `-t` errors and does not start Vivado

$ ./aws_build_dcp_from_cl.py -c cl_axil_reg_access --package-only
ERROR: --package-only requires --tag matching an existing post-route DCP (for example -t YYYY_MM_DD-HHMMSS)

$ ./aws_build_dcp_from_cl.py -c cl_axil_reg_access --package-only -t
Usage: aws_build_dcp_from_cl.py [options]
aws_build_dcp_from_cl.py: error: -t option requires 1 argument

Default build (no `--package-only`) still runs Vivado, then packages

About 18 minutes.

INFO: [Common 17-1381] The checkpoint '.../cl_axil_reg_access.2026_08_25-071852.post_route.dcp' has been generated.
AWS FPGA: (07:36:30): Finished building design checkpoints for customer design cl_axil_reg_access
INFO: [Common 17-206] Exiting Vivado at Tue Aug 25 07:36:31 2026...
34f3cce82c79d3bd441a2f8ec0406cb0753d9d4f6c7e792b96d9b93561888800  .../cl_axil_reg_access.2026_08_25-071852.post_route.dcp

AWS FPGA: 2026-08-25 07:36:33 - Build completes

AWS FPGA: Build Time = 0:17:41.177251.

Reuse an existing post-route checkpoint with --tag instead of re-running implementation, and document the flag next to the other aws_build_dcp_from_cl.py options. Co-authored-by: Cursor <cursoragent@cursor.com>

DavidLiuAmzn · 2026-08-25T20:36:48Z

Hi @WajahatRiaz! Thanks for your contribution! It looks well-scoped and can be genuinely useful for all users of this devkit. We'll review this internally.

Clock recipes are written into the Developer CL tarball, so --package-only now requires --tag and at least one of --clock_recipe_a/b/c/hbm. Omitted recipes keep the documented defaults. --aws_clk_gen is not required in this mode because packaging only records the recipes in the manifest. Co-authored-by: Cursor <cursoragent@cursor.com>

Do not fall back to documented defaults for omitted recipes, so the tarball manifest cannot silently disagree with the clocks used during implementation. Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

This PR adds a --package-only mode to aws_build_dcp_from_cl.py so developers can package an already-generated post-route DCP into a Developer CL tarball without re-running Vivado, and documents the new workflow in the HDK docs.

Changes:

Added --package-only CLI flag, plus argument validation around required --tag and explicitly-specified clock recipe options.
Adjusted the existing --aws_clk_gen/clock-recipe guard so it does not block packaging-only usage.
Documented --package-only usage in both Markdown and RTD documentation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py	Adds `--package-only` mode and related validation/logic changes for packaging existing post-route DCPs.
hdk/README.md	Documents the new `--package-only` workflow and its required arguments.
docs-rtd/source/hdk/README.rst	Mirrors the documentation update for RTD/Sphinx output.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

DavidLiuAmzn · 2026-09-02T15:59:44Z

+        _missing_recipes = [opt for opt in CLOCK_RECIPE_OPTS if not option_on_argv(opt)]
+        if _missing_recipes:
+            print_error(
+                "--package-only requires all four clock recipes to be passed explicitly "
+                "(--clock_recipe_a, --clock_recipe_b, --clock_recipe_c, and --clock_recipe_hbm)"
+            )
+        print(f"AWS FPGA: --package-only set, skipping Vivado and packaging tag {build_tag}\n")


This would be a nice-to-have.

+        cmd = (
+            f"vivado -mode batch -source build_all.tcl -log {build_tag}.vivado.log "
+            + f"-tclargs {options.place_direct} {options.phy_opt_direct} {options.route_direct} "
+            + f"{options.clock_recipe_a} {options.clock_recipe_b} {options.clock_recipe_c} {options.clock_recipe_hbm} "
+        )


DavidLiuAmzn · 2026-09-02T15:55:58Z

Hi @WajahatRiaz. Thanks for the quick follow-ups on the suggested changes! We always appreciate contributions, and we want to make sure you git the credit for these changes.

We have a few more housekeeping items. Can you please run the following, from the repo root:

pip install ruff   # formatter tool
ruff check --select E,W,F,I,N,UP,B,C4,SIM,PIE --line-length 140 --fix --unsafe-fixes hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py
ruff format --line-length 140 hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py

DavidLiuAmzn · 2026-09-02T15:51:33Z

    sys.stdout.flush()
-    os.system(cmd)
+
+    if options.package_only:


nit: this validation (missing --tag, missing clock-recipe flags) runs after the "Build starts" banner is printed right above, so a failed --package-only invocation logs a start message immediately followed by an error/exit.

Let's move this whole block above the start banner print, before the start banner print.

DavidLiuAmzn · 2026-09-02T15:55:22Z

+        dest="package_only",
+        action="store_true",
+        default=False,
+        help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp and all four of --clock_recipe_a/b/c/hbm passed explicitly (recipes are not defaulted or derived from the DCP).",


This line is too long. ruff format won't break string literals. Let's apply the following:

Suggested change

help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp and all four of --clock_recipe_a/b/c/hbm passed explicitly (recipes are not defaulted or derived from the DCP).",

help=(

"Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint "

"timestamp and all four of --clock_recipe_a/b/c/hbm passed explicitly (recipes are not defaulted "

"or derived from the DCP)."

),

Add --package-only so DCP tarball packaging can skip Vivado.

d95baee

Reuse an existing post-route checkpoint with --tag instead of re-running implementation, and document the flag next to the other aws_build_dcp_from_cl.py options. Co-authored-by: Cursor <cursoragent@cursor.com>

czfpga requested changes Aug 28, 2026

View reviewed changes

Comment thread hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py Outdated

WajahatRiaz and others added 2 commits August 30, 2026 19:16

Require all four clock recipes when --package-only packages a DCP.

19a9750

Do not fall back to documented defaults for omitted recipes, so the tarball manifest cannot silently disagree with the clocks used during implementation. Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot AI lite review requested due to automatic review settings September 1, 2026 10:55

Copilot started reviewing on behalf of WajahatRiaz September 1, 2026 10:56 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

DavidLiuAmzn requested changes Sep 2, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add --package-only to aws_build_dcp_from_cl.py to package an existing DCP - #805

Add --package-only to aws_build_dcp_from_cl.py to package an existing DCP#805
WajahatRiaz wants to merge 3 commits into
aws:f2from
SilverLining-EDA:f2

WajahatRiaz commented Aug 25, 2026

Uh oh!

DavidLiuAmzn commented Aug 25, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

DavidLiuAmzn Sep 2, 2026

Uh oh!

DavidLiuAmzn commented Sep 2, 2026

Uh oh!

DavidLiuAmzn Sep 2, 2026

Uh oh!

DavidLiuAmzn Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

-        help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp and all four of --clock_recipe_a/b/c/hbm passed explicitly (recipes are not defaulted or derived from the DCP).",
+        help=(
+            "Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint "
+            "timestamp and all four of --clock_recipe_a/b/c/hbm passed explicitly (recipes are not defaulted "
+            "or derived from the DCP)."
+        ),

Uh oh!

Conversation

WajahatRiaz commented Aug 25, 2026

Summary

Usage

Test plan

--package-only with a valid -t skips Vivado and writes the tarball

--help lists the flag

--package-only without -t errors and does not start Vivado

Default build (no --package-only) still runs Vivado, then packages

Uh oh!

DavidLiuAmzn commented Aug 25, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

DavidLiuAmzn Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

DavidLiuAmzn commented Sep 2, 2026

Uh oh!

DavidLiuAmzn Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

DavidLiuAmzn Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

`--package-only` with a valid `-t` skips Vivado and writes the tarball

`--help` lists the flag

`--package-only` without `-t` errors and does not start Vivado

Default build (no `--package-only`) still runs Vivado, then packages