From d95baee97bba768947e8fe33878dfca3cb41251d Mon Sep 17 00:00:00 2001 From: Wajahat Riaz Date: Tue, 25 Aug 2026 07:09:26 +0000 Subject: [PATCH 1/3] Add --package-only so DCP tarball packaging can skip Vivado. 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 --- docs-rtd/source/hdk/README.rst | 4 +++ hdk/README.md | 1 + .../build/scripts/aws_build_dcp_from_cl.py | 29 +++++++++++++------ 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/docs-rtd/source/hdk/README.rst b/docs-rtd/source/hdk/README.rst index 40bdef752..ccf5b313e 100644 --- a/docs-rtd/source/hdk/README.rst +++ b/docs-rtd/source/hdk/README.rst @@ -186,6 +186,10 @@ A few more notes on source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. +- Use ``--package-only -t `` to skip Vivado and + package an existing post-route DCP. The tag must match the checkpoint + filename (``..post_route.dcp`` in + ``$CL_DIR/build/checkpoints``). - The script also allows developers to pass different Vivado directives as shown below: diff --git a/hdk/README.md b/hdk/README.md index 0a2b79ae5..6f9176ce2 100644 --- a/hdk/README.md +++ b/hdk/README.md @@ -109,6 +109,7 @@ A few more notes on [aws_build_dcp_from_cl.py](https://github.com/aws/aws-fpga/b - Use `--cl ` option to build a different CL design. This is default to `cl_dram_hbm_dma`. - Use `--aws_clk_gen` option to annotate the use of [AWS clock generation block](./docs/AWS_CLK_GEN_spec.md) and [customer clock recipes](./docs/Clock_Recipes_User_Guide.md). - Use `--no-encrypt` option to disable encryption of the design's source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. +- Use `--package-only -t ` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (`..post_route.dcp` in `$CL_DIR/build/checkpoints`). - The script also allows developers to pass different Vivado directives as shown below: - `--place `: Default to `SSI_SpreadLogic_high` placement strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Available-Directives) for supported directives. - `--phy_opt ` : Default to `AggressiveExplore` physical optimization strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Using-Directives?tocId=9xJiGeSV35ApxUsX7pAVDg) for supported directives diff --git a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py index ee85b1109..5a9ef1a13 100755 --- a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py +++ b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py @@ -256,6 +256,14 @@ def main(): default=True, ) + parser.add_option( + "--package-only", + dest="package_only", + action="store_true", + default=False, + help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp.", + ) + (options, args) = parser.parse_args() print("==================================================") @@ -323,18 +331,21 @@ def main(): Custom `clock_recipe` arguments were detected, please add `--aws_clk_gen` to continue.""") - # Run the Vivado job - 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} " - ) - start_time = datetime.datetime.now() print(f"\nAWS FPGA: {start_time.strftime(TIMESTAMP_LOG_FORMAT)} - Build starts\n") - sys.stdout.flush() - os.system(cmd) + + if options.package_only: + if not options.build_tag: + print_error("--package-only requires --tag matching an existing post-route DCP (for example -t YYYY_MM_DD-HHMMSS)") + print(f"AWS FPGA: --package-only set, skipping Vivado and packaging tag {build_tag}\n") + else: + 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} " + ) + os.system(cmd) if options.flow == "BuildAll": generate_dcp_tarball( From 44bad068dfd3943467bfec98f2f39c6ad46b8129 Mon Sep 17 00:00:00 2001 From: Wajahat Riaz Date: Sun, 30 Aug 2026 19:16:10 +0000 Subject: [PATCH 2/3] Require at least one clock recipe when --package-only packages a DCP. 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 --- docs-rtd/source/hdk/README.rst | 11 ++++--- hdk/README.md | 2 +- .../build/scripts/aws_build_dcp_from_cl.py | 30 ++++++++++++++++--- 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/docs-rtd/source/hdk/README.rst b/docs-rtd/source/hdk/README.rst index ccf5b313e..2c24bcb52 100644 --- a/docs-rtd/source/hdk/README.rst +++ b/docs-rtd/source/hdk/README.rst @@ -186,10 +186,13 @@ A few more notes on source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. -- Use ``--package-only -t `` to skip Vivado and - package an existing post-route DCP. The tag must match the checkpoint - filename (``..post_route.dcp`` in - ``$CL_DIR/build/checkpoints``). +- Use ``--package-only -t `` with at least one of + ``--clock_recipe_a``, ``--clock_recipe_b``, ``--clock_recipe_c``, or + ``--clock_recipe_hbm`` to skip Vivado and package an existing post-route + DCP. The tag must match the checkpoint filename + (``..post_route.dcp`` in ``$CL_DIR/build/checkpoints``). + Omitted recipes use documented defaults in the Developer CL tarball + manifest. - The script also allows developers to pass different Vivado directives as shown below: diff --git a/hdk/README.md b/hdk/README.md index 6f9176ce2..58a1e2a74 100644 --- a/hdk/README.md +++ b/hdk/README.md @@ -109,7 +109,7 @@ A few more notes on [aws_build_dcp_from_cl.py](https://github.com/aws/aws-fpga/b - Use `--cl ` option to build a different CL design. This is default to `cl_dram_hbm_dma`. - Use `--aws_clk_gen` option to annotate the use of [AWS clock generation block](./docs/AWS_CLK_GEN_spec.md) and [customer clock recipes](./docs/Clock_Recipes_User_Guide.md). - Use `--no-encrypt` option to disable encryption of the design's source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. -- Use `--package-only -t ` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (`..post_route.dcp` in `$CL_DIR/build/checkpoints`). +- Use `--package-only -t ` with at least one of `--clock_recipe_a`, `--clock_recipe_b`, `--clock_recipe_c`, or `--clock_recipe_hbm` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (`..post_route.dcp` in `$CL_DIR/build/checkpoints`). Omitted recipes use documented defaults in the Developer CL tarball manifest. - The script also allows developers to pass different Vivado directives as shown below: - `--place `: Default to `SSI_SpreadLogic_high` placement strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Available-Directives) for supported directives. - `--phy_opt ` : Default to `AggressiveExplore` physical optimization strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Using-Directives?tocId=9xJiGeSV35ApxUsX7pAVDg) for supported directives diff --git a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py index 5a9ef1a13..cebd91984 100755 --- a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py +++ b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py @@ -28,6 +28,20 @@ TIMESTAMP_LOG_FORMAT = "%Y-%m-%d %H:%M:%S" TIMESTAMP_FILE_FORMAT = "%Y_%m_%d-%H%M%S" +CLOCK_RECIPE_OPTS = ( + "--clock_recipe_a", + "--clock_recipe_b", + "--clock_recipe_c", + "--clock_recipe_hbm", +) + + +def option_on_argv(option_name): + for arg in sys.argv[1:]: + if arg == option_name or arg.startswith(option_name + "="): + return True + return False + ############################################################# # Print error message and exit @@ -261,7 +275,7 @@ def main(): dest="package_only", action="store_true", default=False, - help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp.", + help="Skip Vivado and package an existing post-route DCP. Requires --tag matching the checkpoint timestamp and at least one of --clock_recipe_a/b/c/hbm. Omitted recipes use documented defaults in the tarball manifest.", ) (options, args) = parser.parse_args() @@ -325,8 +339,9 @@ def main(): build_tag = now.strftime(TIMESTAMP_FILE_FORMAT) os.environ["BUILD_TAG"] = build_tag - # Last check before build in case the user sets clock recipes without the aws_clk_gen IP - if not options.aws_clk_gen and "clock_recipe" in str(sys.argv): + # Last check before build in case the user sets clock recipes without the aws_clk_gen IP. + # --package-only only records recipes in the tarball manifest, so --aws_clk_gen is not required. + if not options.package_only and not options.aws_clk_gen and "clock_recipe" in str(sys.argv): print_error("""The aws_clk_gen IP is required for setting custom clock recipes. Custom `clock_recipe` arguments were detected, please add `--aws_clk_gen` to continue.""") @@ -337,7 +352,14 @@ def main(): if options.package_only: if not options.build_tag: - print_error("--package-only requires --tag matching an existing post-route DCP (for example -t YYYY_MM_DD-HHMMSS)") + print_error( + "--package-only requires --tag matching an existing post-route DCP (for example -t YYYY_MM_DD-HHMMSS)" + ) + if not any(option_on_argv(opt) for opt in CLOCK_RECIPE_OPTS): + print_error( + "--package-only requires at least one clock recipe " + "(--clock_recipe_a, --clock_recipe_b, --clock_recipe_c, or --clock_recipe_hbm)" + ) print(f"AWS FPGA: --package-only set, skipping Vivado and packaging tag {build_tag}\n") else: cmd = ( From 19a975031e674abce7c3c5e4a974c900ed9b5af5 Mon Sep 17 00:00:00 2001 From: Wajahat Riaz Date: Tue, 1 Sep 2026 10:55:13 +0000 Subject: [PATCH 3/3] Require all four clock recipes when --package-only packages a DCP. 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 --- docs-rtd/source/hdk/README.rst | 8 ++++---- hdk/README.md | 2 +- .../shell_stable/build/scripts/aws_build_dcp_from_cl.py | 9 +++++---- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs-rtd/source/hdk/README.rst b/docs-rtd/source/hdk/README.rst index 2c24bcb52..1799ddf82 100644 --- a/docs-rtd/source/hdk/README.rst +++ b/docs-rtd/source/hdk/README.rst @@ -186,13 +186,13 @@ A few more notes on source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. -- Use ``--package-only -t `` with at least one of - ``--clock_recipe_a``, ``--clock_recipe_b``, ``--clock_recipe_c``, or +- Use ``--package-only -t `` with + ``--clock_recipe_a``, ``--clock_recipe_b``, ``--clock_recipe_c``, and ``--clock_recipe_hbm`` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (``..post_route.dcp`` in ``$CL_DIR/build/checkpoints``). - Omitted recipes use documented defaults in the Developer CL tarball - manifest. + All four recipes must be passed explicitly; the script does not assume + defaults or derive clock info from the DCP. - The script also allows developers to pass different Vivado directives as shown below: diff --git a/hdk/README.md b/hdk/README.md index 58a1e2a74..3b93013ad 100644 --- a/hdk/README.md +++ b/hdk/README.md @@ -109,7 +109,7 @@ A few more notes on [aws_build_dcp_from_cl.py](https://github.com/aws/aws-fpga/b - Use `--cl ` option to build a different CL design. This is default to `cl_dram_hbm_dma`. - Use `--aws_clk_gen` option to annotate the use of [AWS clock generation block](./docs/AWS_CLK_GEN_spec.md) and [customer clock recipes](./docs/Clock_Recipes_User_Guide.md). - Use `--no-encrypt` option to disable encryption of the design's source code and DCPs. Encryption, enabled by default, may impede debugging as errors from encrypted envelope do not provide meaningful information. -- Use `--package-only -t ` with at least one of `--clock_recipe_a`, `--clock_recipe_b`, `--clock_recipe_c`, or `--clock_recipe_hbm` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (`..post_route.dcp` in `$CL_DIR/build/checkpoints`). Omitted recipes use documented defaults in the Developer CL tarball manifest. +- Use `--package-only -t ` with `--clock_recipe_a`, `--clock_recipe_b`, `--clock_recipe_c`, and `--clock_recipe_hbm` to skip Vivado and package an existing post-route DCP. The tag must match the checkpoint filename (`..post_route.dcp` in `$CL_DIR/build/checkpoints`). All four recipes must be passed explicitly; the script does not assume defaults or derive clock info from the DCP. - The script also allows developers to pass different Vivado directives as shown below: - `--place `: Default to `SSI_SpreadLogic_high` placement strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Available-Directives) for supported directives. - `--phy_opt ` : Default to `AggressiveExplore` physical optimization strategy. Please refer to [Vivado User Guide](https://docs.amd.com/r/en-US/ug904-vivado-implementation/Using-Directives?tocId=9xJiGeSV35ApxUsX7pAVDg) for supported directives diff --git a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py index cebd91984..40a7d268e 100755 --- a/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py +++ b/hdk/common/shell_stable/build/scripts/aws_build_dcp_from_cl.py @@ -275,7 +275,7 @@ def main(): 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 at least one of --clock_recipe_a/b/c/hbm. Omitted recipes use documented defaults in the tarball manifest.", + 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).", ) (options, args) = parser.parse_args() @@ -355,10 +355,11 @@ def main(): print_error( "--package-only requires --tag matching an existing post-route DCP (for example -t YYYY_MM_DD-HHMMSS)" ) - if not any(option_on_argv(opt) for opt in CLOCK_RECIPE_OPTS): + _missing_recipes = [opt for opt in CLOCK_RECIPE_OPTS if not option_on_argv(opt)] + if _missing_recipes: print_error( - "--package-only requires at least one clock recipe " - "(--clock_recipe_a, --clock_recipe_b, --clock_recipe_c, or --clock_recipe_hbm)" + "--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") else: