Using --to_step and Launching Vivado Interactively - 2023.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2023-07-17
Version
2023.1 English

The Vitis compiler lets you stop the build process after completing a specified step (--to_step), manually intervene in the design or files in some way, and then continue the build by specifying a step the build should resume from (--from_step). The --from_step directs the Vitis compiler to resume compilation from the step where --to_step left off, or some earlier step in the process. The --to_step and --from_step are described in v++ General Options.

Important: The --to_step and --from_step options are sequential build options that require you to use the same project directory when launching v++ --link --from_step as you specified when using v++ --link --to_step.

The Vitis compiler also provides a --list_steps option to list the available steps for the compilation or linking processes of a specific build target. For example, the list of steps for the link process of the hardware build can be found by:

v++ --list_steps --target hw --link

This command returns a number of steps, both default steps and optional steps that the Vitis compiler goes through during the linking process of the hardware build. Some of the default steps include: system_link, vpl, vpl.create_project, vpl.create_bd, vpl.generate_target, vpl.synth, vpl.impl.opt_design, vpl.impl.place_design, vpl.impl.route_design, and vpl.impl.write_bitstream.

Optional steps include: vpl.impl.power_opt_design, vpl.impl.post_place_power_opt_design, vpl.impl.phys_opt_design, and vpl.impl.post_route_phys_opt_design.
Tip: An optional step must be enabled before specifying it with --from_step or --to_step as previously described in Using the --vivado and --advanced Options.

Launching the Vivado IDE for Interactive Design

For example, with the --to_step command, you can launch the build process to Vivado synthesis and then start the Vivado IDE on the project to manually place and route the design. To perform this you would use the following command syntax:

v++ --target hw --link --to_step vpl.synth --save-temps --platform <PLATFORM_NAME> <XO_FILES>
Tip: As shown in the example above, you must also specify --save-temps when using --to_step to preserve any temporary files created by the build process.

This command specifies the link process of the hardware build, runs the build through the synthesis step, and saves the temporary files produced by the build process.

You can launch the Vivado tool directly on the project built by the Vitis compiler using the --interactive command. This opens the Vivado project found at <temp_dir>/link/vivado/vpl/prj in your build directory, letting you interactively edit the design:

v++ --target hw --link --interactive --save-temps --platform <PLATFORM_NAME> <XO_FILES>

When invoking the Vivado IDE in this mode, you can open the synthesis or implementation runs to manage and modify the project. You can change the run details as needed to close timing and try different approaches to implementation. You can save the results to a design checkpoint (DCP), or generate the project bitstream (.bit) to use in the Vitis environment to generate the device binary.

After saving the DCP from within the Vivado IDE, close the tool and return to the Vitis environment. Use the --reuse_impl option to apply a previously implemented DCP file in the v++ command line to generate the xclbin.

Important: The --reuse_impl option is an incremental build option that requires you to apply the same project directory when resuming the Vitis compiler with --reuse_impl that you specified when using --to_step to start the build.

The following command completes the linking process by using the specified DCP file from the Vivado tool to create the project.xclbin from the input files.

v++ --link --platform <PLATFORM_NAME> -o'project.xclbin' project.xo --reuse_impl ./_x/link/vivado/routed.dcp
You can also use a bitstream file generated by the Vivado tool to create the project.xclbin:
v++ --link --platform <PLATFORM_NAME> -o'project.xclbin' project.xo --reuse_bit ./_x/link/vivado/project.bit
Note: The project.bit used for --reuse_bit is a partial bit and not a full bit.

Additional Vivado Options

Some additional switches that can be used in the v++ command line or config file include the following:

  • --export_script/--custom_script edit and use Tcl scripts to modify the compilation or linking process.
  • --remote_ip_cache specify a remote IP cache directory for Vivado synthesis.
  • --no_ip_cache turn off the IP cache for Vivado synthesis. This causes all IP to be re-synthesized as part of the build process, scrubbing out cached data.