Setting Guidance Thresholds - 2021.2 English

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

Document ID
UG1393
Release Date
2022-03-29
Version
2021.2 English

Guidance messages reported in the Run Guidance report are triggered by specific rules and value thresholds that are defined within the tool. Some of these rules and value thresholds are user-modifiable within Vitis™ analyzer. When the Run Guidance report is opened, the modifiable values will appear as links in the Threshold column of the report, as shown in the following figure.

Figure 1. Run Guidance Threshold

Clicking a link in the Threshold column will display the Edit Guidance Threshold dialog box, as shown below. The top part of the dialog box displays the current operator and threshold for the selected rule, and the lower part lets you edit the value.

Figure 2. Edit Guidance Threshold

The figure above shows the Threshold value being redefined with a user-specified value. In some cases, a range of accepted values is displayed and the tool checks that the provided value falls within that range. In the example above, the specified value must be greater than or equal to 0.

The Edit Guidance Threshold dialog box also provides a Reset threshold command that allows you to reset the user-defined value to the hard-coded value provided by the tool. This is the seen in the figure above.

Tip: The menu bar for the Run Guidance report also has a Reset Guidance Thresholds command to let you clear all user-modified thresholds from the report.

The Update guidance report check box lets you specify if the guidance report will be rerun after the value is updated. If you deselect this check box, the threshold value will be changed as specified, and the report will be marked out-of-date due to the new user-specified threshold. You will need to manuallyReload the report to see the impact of the user values.

Click OK to change the value, or Cancel to close the dialog box without change.

Import/Export Rule Thresholds

The rules as to which threshold values can be modified, and the default values of all rules, are stored within the tool installation. You can override these rules with a custom rule file, which you can export and import into different projects in Vitis analyzer.

When you have customized one or more rules in the Run Guidance report, an Export User Guidance Thresholds command becomes active in the toolbar menu of the report. You can see this command displayed in the top figure above. This lets you export the customized value thresholds to reuse them in other designs.

A sample file is shown below:

profile_rules =
(
  {
    id = "HOST_MIGRATE_MEM";
    value = "1";
  },
  {
    id = "DEVICE_UTIL";
    value = "3";
  }
);
version = "1";	

The user threshold file does not need to contain all guidance rules, only the rules where the value has changed, and only the rule id and value fields are needed:

  • id is the name of the rule as displayed in the Name column of the Run Guidance report.
  • value is the user-specified value, displayed in the Threshold column.

The Vitis analyzer IDE also lets you Import User Guidance Thresholds to reuse the custom thresholds in other projects. You can export a user-thresholds.cfg file, edit the values, and import the file as needed. Importing a user-thresholds file regenerates the Run Guidance report to use the imported values.

Important: Importing a user-guidance threshold file will overwrite any existing user-modified thresholds.