Using the --vivado and --advanced Options - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

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. You can specify the strategy to be used by the Vivado tool during synthesis, implementation, or when generating reports during the build process. The strategy specified can be one of the standard tool strategies, or can be a custom-defined strategy that you have previously created in the Vivado tool. Use the --vivado.prop command as shown below.

    The original Tcl command to set the property on a run object looks like the following:
    set_property strategy Flow_AreaOptimized_medium [get_runs synth_1]
    

    The v++ command is rewritten as shown below:

    • Synthesis Strategy:
      --vivado.prop run.synth_1.strategy=Flow_AreaOptimized_medium
    • Implementation Strategy:
      --vivado.prop run.impl_1.strategy=Performance_ExtraTimingOpt 
    • Report Strategy: Can be specified for synthesis or implementation runs.
      --vivado.prop run.synth_1.report_strategy=MyCustom_Reports
      --vivado.prop run.impl_1.report_strategy={Timing Closure Reports}
    The command line is broken down as follows:
    • --vivado.prop is the v++ command-line option to assign properties to objects as described in --vivado Options.
    • run.<run_name>.strategy=<strategy_name> to assign a strategy property (or report_strategy) to the specified synthesis or implementation run. Default run names are synth_1 for synthesis or impl_1 for implementation.
    • Strategy names with spaces in them, such as {Timing Closure Reports} require braces or double-quotes to group the words as shown above.
      Tip: You can also specify multiple implementation strategies to run as described in Running Multiple Implementation Strategies for Timing Closure.
  2. 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: SYNTH_DESIGN, 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.
  3. 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 and disable global buffer insertion during placement, 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.PLACE_DESIGN.ARGS.MORE OPTIONS}={-no_bufg_opt}
    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 various steps 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.

    In this example the object is a run, the instance is the default implementation run, impl_1, and the property is an argument of the different step names, In this case the DIRECTIVE, IS_ENABLED, and {MORE OPTIONS}. Refer to --vivado Options for more information on the command syntax.

  4. Enabling optional steps in the Vivado implementation process.

    The build process runs Vivado synthesis and implementation to generate the device binary. Some of the implementation steps are enable and run as part of the default build process, and some of the implementation steps can be optionally enabled at your discretion.

    Optional steps can be listed using the --list_steps command, and 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.

    An optional step can be enabled using the --vivado.prop option. For example, to enable PHYS_OPT_DESIGN step, use the following config file content:

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

    When an optional step is enabled as shown above, the step can be specified as part of the -from_step/-to_step command as described below in Running --to_step or --from_step, or enable a Tcl script to run before or after the step as described in --linkhook Options.

  5. 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.

    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
  6. 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 to preserve the temporary files created during synthesis and implementation, including any generated reports.

    You might 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.