report_qor_suggestions - 2024.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
Release Date
2024.1 English

Recommend QoR Suggestions


report_qor_suggestions [‑file <arg>] [‑csv_output_dir <arg>] [‑name <arg>]
    [‑append] [‑return_string] [‑max_strategies <arg>] [‑max_paths <arg>]
    [‑no_split] [‑report_all_suggestions] [‑cells <args>]
    [‑of_objects <args>] [‑quiet] [‑verbose]


Name Description
[-file] Filename to output results to. (send output to console if -file is not used)
[-csv_output_dir] Output Dir
[-name] Output the results to GUI panel with this name
[-append] Append the results to file, don't overwrite the results file
[-return_string] Return report as string
[-max_strategies] Number of strategies to suggest Default: 3
[-max_paths] Number of paths to consider for suggestion analysis Default: 100
[-no_split] Report without spliting the lines in tables
[-report_all_suggestions] Report all suggestions
[-cells] Report QOR suggestions for a given cell
[-of_objects] List of QoR suggestion objects
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution


Report design and tool option recommendations related to improving the quality of results (QoR). The report looks at timing constraints, netlist characteristics, failing timing paths, and congestion information to determine suggestions that can enhance the QoR. The report can be generated after synthesis, or after any implementation step, but requires a design to be open.

The report_qor_suggestions command creates QoR suggestion objects related to the suggestions identified. These suggestion objects can be enabled for use by the Vivado™ tools to improve the quality of synthesis and implementation results. Some of these suggestions can be automatically applied, and some may require more manual intervention to implement design changes, or write Tcl design constraints.

Suggestion objects can be obtained using the get_qor_suggestions command. The QoR objects have properties that define what step they are APPLICABLE_FOR, if they are ENABLED to be used, if they can be automatically applied (AUTO), or what step the suggestions was GENERATED_AT. A suggestion must be ENABLED and the APPLICABLE_FOR synthesis or implementation step run in order for a suggestion to be applied to the design.

You can write the suggestions from the design into an RQS file using the write_qor_suggestions command. After resetting the design flow to the appropriate step, you can read suggestions back into the design using the read_qor_suggestions command, and then run the synthesis or implementation step to apply the enabled suggestions.

The recommended method for working with QoR suggestions is:

  1. Run the report to create recommendations (report_qor_suggestions)
  2. Write the suggestions to an RQS file on disk (write_qor_suggestions).
  3. Reset the design to the appropriate step.
  4. Read the RQS file into the design to restore the suggestions (read_qor_suggestions).
  5. Run the synthesis or implementation step to apply the suggestion (synth_design, opt_design...).

For strategy suggestions, a machine learning based analysis is conducted and the best 3 strategies are reported. This analysis is only conducted on a routed design that has been implemented with

  • the Default or Explore directive for opt_design and
  • place_design, phys_opt_design, and route_design must have the directive set to Default or Explore. Mix and match of directives is not allowed within these commands.

Strategy suggestions do not apply to synthesis. Unlike the non-strategy suggestions, only one strategy suggestion can be applied to each run.

The recommended method for working with QoR strategy suggestions is:

  1. Run the report to create strategies and other recommendations(report_qor_suggestions).
  2. Write the suggestions to a directory disk. There is one RQS file per strategy (write_qor_suggestions -strategy_dir).
  3. Update all the directive settings to -directive RQS for opt_design, place_design, phys_opt_design, and route_design commands.
  4. For each run, read one RQS file into the design. This will contain the strategy suggestion and all exported non-strategy suggestions(read_qor_suggestions).
  5. Run the implementation step from the opt_design command to apply the strategy and all the design suggestions.


-file <arg> - (Optional) Write the QoR report into the specified file. The specified file will be overwritten if one already exists, unless -append is also specified.

Note: If the path is not specified as part of the file name for either -file or -csv, the file will be written into the current working directory that can be identified using the [pwd] Tcl command.

-csv_output_dir - Directory to write supporting CSV files. CSV files contain:

  • Timing path details and show suggestions that are applicable to the timing path.
  • Cells and nets with DONT_TOUCH properties

-name <arg> - (Optional) The name of the view to display in the Vivado IDE when run in GUI mode. Only one QoR suggestion report can be opened in the Vivado tool at one time. This makes it different from most other available reports. If there is already an open report in the Report view, that report will be closed and a new report is opened.

-append - (Optional) Append the output of the command to the specified file rather than overwriting it.

Note: The -append option can only be used with the -file option.

-return_string - (Optional) Direct the output to a Tcl string rather than to the standard output. The Tcl string can be captured by a variable definition and parsed or otherwise processed.

Note: This argument cannot be used with the -file option.

-max_strategies <args> - (Optional) Specify the maximum number of ML strategies returned. The algorithm may generate less than the maximum specified number if not enough suitable strategies are identified. Default is 3.

-max_paths <arg> - (Optional) Specify the number of critical paths to analyze. The default is the 100 worst timing paths per timing group. Timing paths that have a WNS > 0.000 are ignored unless -report_all_suggestions is set.

-no_split - (Optional) Do not split the lines in the table when generating the report.

-report_all_suggestions - (Optional) Relaxes the criteria that suppresses suggestions.

  • Utilization suggestions do not need to save a critical resource
  • Congestion suggestions are offered on designs when timing is closed
  • Timing suggestions on paths that have a WNS < +0.500

-cells <arg> - (Optional) Report QoR suggestions for the specified hierarchical cells and all data paths passing through them.

-of_objects <args> - (Optional) Report existing suggestions defined by the specified list of QoR objects as returned by the get_qor_suggestions command. When -of_objects is specified, the report does not analyze the design to identify new suggestions, it merely reports the specified existing suggestion objects.

-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.
Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.
-verbose - (Optional) Temporarily override any message limits and return all messages from this command.
Note: Message limits can be defined with the set_msg_config command.


Report suggestions after analyzing the worst 10 paths.

report_qor_suggestions -max_paths 10

Report existing suggestions in the design from a prior run of report_qor_suggestions.

report_qor_suggestions -of_objects [get_qor_suggestions]