create_qor_check - 2025.1 English - UG835

Vivado Design Suite Tcl Command Reference Guide (UG835)
Document ID
UG835
Release Date
2025-06-16
Version
2025.1 English

Description

Creates a new user-defined QoR (Quality of Results) check for Report QoR Suggestions use. QoR suggestion checks are used to analyze and offer suggestions to improve the results from the synthesis and implementation tools for a given design.

To create a QoR check, a user must first create a Tcl proc to carry out the desired function. It is recommended to start from a template and then use an existing check as a reference. The template includes Tcl structures to leverage data generated inside the engine and prepared Tcl procs to aid development of the check.

Before a check is registered, ensure that the associated check is visible in Vivado which is achieved by sourcing the Tcl script containing the proc. It is then registeration-ready using the create_qor_check command and referenced using the -rule_body <proc name> switch. The create_qor_check associates the check with an ID. Users can select any ID name but each ID should be unique to a particular check and naming should not conflict with existing or potential future (including possible 3rd party suggestion) IDs. In addition, create_qor_check sets properties of the new QoR check. Some property settings are mandatory and must be set at the same time as the check is created using create_qor_check. Property setting is done by provide a "key value" Tcl list to the -property_values <key value> switch. Multiple properties can be set at once.

A quick summary of the flow to create a user check is as follows:

  • Save the template.suggestion file as <your_proc_name>.tcl
  • Write up the Tcl proc to analyze the design and offer a suggestion.
  • Source the Tcl script to set the proc visible in Vivado.
  • Use the create_qor_check command to register the Tcl proc and associate it with an ID and assign required properties to the check.
  • Optionally, add the check to a QoR ruledeck using the add_qor_checks command. Refer to create_qor_ruledeck for information on creating ruledecks.
  • Call the check using report_qor_suggestions. If a suggestion is triggered, a suggestion object is created.
  • Write an RQS (QoR suggestions) file or enable the suggestion in the flow directly.

The following captures the properties associated with QoR checks that are suggestion type.

Property Details Req. Update via Tcl Allowed value
DESCRIPTION Text description of suggestion Yes Yes Any string
CATEGORY Area of impact Yes No Clocking, Congestion, Netlist, Timing, Utilization, or XDC
APPLICABLE_FOR Design stage to execute the suggestion Yes Yes opt_design, place_design, postplace_phys_opt_design, route_design, postroute_phys_opt_design
AUTO Automatically executes No Yes Default: 1 Allowed value: 1 or 0
NEEDS_TIMING_DATA Requires engine timing data No No Default: 1 Allowed value: 1 or 0
PARAMS Tcl dictionary to configure suggestion No No Dictionary of user defined parameters and values

For more information on creating suggestions and accessing the template, refer to Vivado Design Suite: Design Analysis and Closure Techniques (UG906).

Arguments

-name <arg> - (Required) The name of the check. This can take on any string. Recommended format is RQS_<category>_<company>-<number>. For example, RQS_NETLIST_AMD-1.

-rule_body <arg> - (Required) The name of the Tcl proc to execute when a suggestion is called. Ensure that the proc is already sourced and visible in Vivado.

-property_values <arg> - (Required) Specifies the values of the properties applicable for QoR check. Ensure to apply the mandatory property settings mentioned in the Table. The argument takes a list of values which are specified as key-value pairs.

Examples

The following example shows a way of registering a new suggestion called RQS_NETLIST_AMD-1. It takes proc called unroll_srl_to_input which is inside file unroll_srl_to_input.tcl. It sets the applicable for value to opt_design, adds a description and a summary and adds the suggestion to the Netlist category.

source unroll_srl_to_input.tcl
set af [list opt_design]
set cat Netlist
set sum "Unroll SRL inputs"
set desc "Unroll SRL inputs when driving by a LUT"
create_qor_check -name RQS_NETLIST_AMD-1 -rule_body unroll_srl_to_input -property_values [list APPLICABLE_FOR $af CATEGORY $cat DESCRIPTION $desc SUMMARY $sum]

See Also