Building the Device Binary

Introduction

In most cases, the Vitis environment completely abstracts away the underlying process of synthesis and implementation of the programmable logic region, as the CUs are linked with the hardware platform and the FPGA binary (xclbin) is generated. This removes the application developer from the typical hardware development process, and the need to manage constraints such as logic placement and routing delays. The Vitis tool automates much of the FPGA implementation process.

However, in some cases you might want to exercise some control over the synthesis and implementation processes deployed by the Vitis compiler, especially when large designs are being implemented. Towards this end, the Vitis tool offers some control through specific options that can be specified in a v++ configuration file, or from the command line. The following are some of the ways you can interact with and control the Vivado synthesis and implementation results.

• Using the --vivado option to manage the Vivado tool.
• Using the -to_step and -from_step options to run the compilation or linking process to a specific step, perform some manual intervention on the design, and resume from that step.
• Interactively editing the Vivado project, and using the results for generating the FPGA binary.

Using the --vivado and --advanced Options

Using the --vivado option, as described in --vivado Options, and the --advanced option as described in --advanced Options, you can perform a number of interventions on the standard Vivado synthesis or implementation.

1. Pass Tcl scripts, with custom design constraints or scripted operations.

   You can create Tcl scripts to assign XDC design constraints to objects in the design, and pass these Tcl scripts to the Vivado tools using the PRE and POST Tcl script properties of the synthesis and implementation steps. For more information on Tcl scripting, refer to the Vivado Design Suite User Guide: Using Tcl Scripting (UG894). While there is only one synthesis step, there are a number of implementation steps as described in the Vivado Design Suite User Guide: Implementation (UG904). You can assign Tcl scripts for the Vivado tool to run before the step (PRE), or after the step (POST). The specific steps you can assign Tcl scripts to include the following: SYNTHESIS, INIT_DESIGN, OPT_DESIGN, PLACE_DESIGN, ROUTE_DESIGN, WRITE_BITSTREAM.

   TIP: There are also some optional steps that can be enabled using the --vivado.prop run.impl_1.steps.phys_opt_design.is_enabled=1 option. When enabled, these steps can also have Tcl PRE and POST scripts.
   An example of the Tcl PRE and POST script assignments follow:

   --vivado.prop run.impl_1.STEPS.PLACE_DESIGN.TCL.PRE=/…/xxx.tcl

   In the preceding example a script has been assigned to run before the PLACE_DESIGN step. The command line is broken down as follows:

   • --vivado is the v++ command-line option to specify directives for the Vivado tools.
   • prop keyword to indicate you are passing a property setting.
   • run. keyword to indicate that you are passing a run property.
   • impl_1. indicates the name of the run.
   • STEPS.PLACE_DESIGN.TCL.PRE indicates the run property you are specifying.
   • /.../xx.tcl indicates the property value.
   TIP: Both the --advanced and --vivado options can be specified on the v++ command line, or in a configuration file specified by the --config option. The example above shows the command line use, and the following example shows the config file usage. Refer to Vitis Compiler Configuration File for more information.
2. Setting properties on run, file, and fileset design objects.
   This is very similar to passing Tcl scripts as described above, but in this case you are passing values to different properties on multiple design objects. For example, to use a specific implementation strategy such as Performance_Explore, you can define the properties as shown below:

   [vivado]
   prop=run.impl_1.STEPS.OPT_DESIGN.ARGS.DIRECTIVE=Explore
   prop=run.impl_1.STEPS.PLACE_DESIGN.ARGS.DIRECTIVE=Explore
   prop=run.impl_1.STEPS.PHYS_OPT_DESIGN.IS_ENABLED=true
   prop=run.impl_1.STEPS.PHYS_OPT_DESIGN.ARGS.DIRECTIVE=Explore
   prop=run.impl_1.STEPS.ROUTE_DESIGN.ARGS.DIRECTIVE=Explore

   In the example above, the Explore value is assigned to the STEPS.XXX.DIRECTIVE property of the implementation run. Note the syntax for defining these properties is:

   <object>.<instance>.property=<value>

   Where:

   • <object> can be a design run, a file, or a fileset object.
   • <instance> indicates a specific instance of the object.
   • <property> specifies the property to assign.
   • <value> defines the value of the property.
3. Passing parameters to the tool to control processing.
   The --vivado option also allows you to pass parameters to the Vivado tools. The parameters are used to configure the tool features or behavior prior to launching the tool. The syntax for specifying a parameter uses the following form:

   --vivado.param <object><parameter>=<value>

   The keyword param indicates that you are passing a parameter for the Vivado tools, rather than a property for a design object. You must also define the <object> it applies to, the <parameter> that you are specifying, and the <value> to assign it.

   In the following example project indicates the current Vivado project, writeIntermedateCheckpoints is the parameter being passed, and the value is 1, which enables this boolean parameter.

   --vivado.param project.writeIntermediateCheckpoints=1

4. Managing the reports generated during synthesis and implementation.
   IMPORTANT: You must also specify --save-temps on the v++ command line when customizing the reports generated by the Vivado tool in order to preserve the temporary files created during synthesis and implementation, including any generated reports.
   You may also want to generate or save more than the standard reports provided by the Vivado tools when run as part of the Vitis tools build process. You can customize the reports generated using the --advanced.misc option as follows:

   [advanced]
   misc=report=type report_utilization name synth_report_utilization_summary steps {synth_design} runs {__KERNEL__} options {}
   misc=report=type report_timing_summary name impl_report_timing_summary_init_design_summary steps {init_design} runs {impl_1} options {-max_paths 10} 
   misc=report=type report_utilization name impl_report_utilization_init_design_summary steps {init_design} runs {impl_1} options {} 
   misc=report=type report_control_sets name impl_report_control_sets_place_design_summary steps {place_design} runs {impl_1} options {-verbose} 
   misc=report=type report_utilization name impl_report_utilization_place_design_summary steps {place_design} runs {impl_1} options {} 
   misc=report=type report_io name impl_report_io_place_design_summary steps {place_design} runs {impl_1} options {} 
   misc=report=type report_bus_skew name impl_report_bus_skew_route_design_summary steps {route_design} runs {impl_1} options {-warn_on_violation} 
   misc=report=type report_clock_utilization name impl_report_clock_utilization_route_design_summary steps {route_design} runs {impl_1} options {} 
   

   The syntax of the command line is explained using the following example:

   misc=report=type report_bus_skew name impl_report_bus_skew_route_design_summary steps {route_design} runs {impl_1} options {-warn_on_violation} 
   

   • misc=report=: Specifies the --advanced.misc option as described in --advanced Options, and defines the report configuration for the Vivado tool. The rest of the command line is specified in name/value pairs, reflecting the options of the create_report_config Tcl command as described in Vivado Design Suite Tcl Command Reference Guide (UG835).
   • type report_bus_skew: Relates to the -report_type argument, and specifies the type of the report as the report_bus_skew. Most of the report_* Tcl commands can be specified as the report type.
   • name impl_report_bus_skew_route_design_summary: Relates to the -report_name argument, and specifies the name of the report. Note this is not the file name of the report, and generally this option can be skipped as the report names will be auto-generated by the tool.
   • steps {route_design}: Relates to the -steps option, and specifies the synthesis and implementation steps that the report applies to. The report can be specified for use with multiple steps to have the report regenerated at each step, in which case the name of the report will be automatically defined.
   • runs {impl_1}: Relates to the -runs option, and specifies the name of the design runs to apply the report to.
   • options {-warn_on_violation}: Specifies various options of the report_* Tcl command to be used when generating the report. In this example, the -warn_on_violation option is a feature of the report_bus_skew command.
     IMPORTANT: There is no error checking to ensure the specified options are correct and applicable to the report type specified. If you indicate options that are incorrect the report will return an error when it is run.

Running --to_step or --from_step

The Vitis compiler lets you specify a step to run to that lets you stop the build process after completing the specified step, manually intervene in the design or files in some way, and then rerun the build specifying a step the build should start from. The commands to do this are the --to_step, to run the build process through that step, and --from_step to resume the build from the specified step of the Vitis compiler, as described in Vitis Compiler General Options.

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.

[vivado]
prop=run.impl_1.steps.phys_opt_design.is_enabled=1

Launching the Vivado IDE for Interactive Design

v++ --target hw --link --to_step vpl.synth --save-temps --platform <PLATFORM_NAME> <XO_FILES>

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, which you can find at _x/link/vivado/vpl/prj in your build directory. When invoking the Vivado IDE in this mode, you can open the synthesis or implementation run 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) to use in the Vitis environment to generate the FPGA binary.

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

v++ --link --platform <PLATFORM_NAME> -o'project.xclbin' project.xo --reuse_impl ./_x/link/vivado/routed.dcp

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 an HLS Tcl script to modify the compilation process.
• --interactive allows the Vivado IDE to be launched from within the v++ environment, with the project loaded.
• --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 resynthesized as part of the build process, scrubbing out cached data.