xilinx.analyzer - 2022.2 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2023-01-13
Version
2022.2 English

xilinx.analyzer is a MATLAB® class that provides an interface between the Model Composer model and Vivado® timing paths.

The Model Composer timing analysis is supported for all compilation targets. The Perform analysis drop down menu under the Clocking tab of the Model Composer Hub block provides two options for the trade-off between total runtime vs. accuracy of the Vivado timing data. If you select either the Post Synthesis or the Post Implementation option of Perform analysis and click the Generate button, then Vivado timing paths information is collected during the netlist generation. The xilinx.analyzer class is used to access Vivado timing paths information. The xilinx.analyzer class object processes Vivado timing paths to find 50 unique paths with the worst slack value. The unique timing paths are sorted in increasing value of slack and saved in the analyzer object.

The cross-probing between Vivado timing paths and the Model Composer model is made possible using the following API functions in the xilinx.analyzer class.

Table 1. xilinx.analyzer Class Functions
Function Name Description Function Argument
xilinx.analyzer

This is a constructor of the class.

A call to the xilinx.analyzer constructor returns object of the class.

First argument is Model Composer model name.

Second argument is path to already generated netlist directory.

isValid Indicates if timing analysis data is valid or not. Use this API to make sure that the xilinx.analyzer class construction was successful. No argument
getErrorMessage Returns an error message string if the call to the class constructor or other API function had an error. No argument
getStatus Returns ‘FAILED’ if any of the timing paths in the model have a violation, i.e., negative slack. No argument
getVivadoStage Returns either Post Synthesis or Post Implementation. This is the Vivado design stage after which timing analysis was performed. No argument
paths Returns an array of MATLAB structures. Each structure contains data for a timing path. A string that is equal to either ‘setup’ or ‘hold’
violations Returns an array of MATLAB structures. Each member of the array is a path structure with a timing violation. A string that is equal to either ‘setup’ or ‘hold’
print Prints timing path information such as Slack, Path Delay, Levels of Logic, Name of Source and Destination blocks, and Source and Destination clocks. An array of MATLAB structures for timing path data. The array can have one or more structures.
highlight In the Model Composer model, highlights blocks for the timing path passed in the argument. Blocks that are already highlighted in the model will remain highlighted. MATLAB structure for one timing path
highlightOnePath In the Model Composer model, highlights blocks for the timing path passed in the argument. Before highlighting blocks for this path, the blocks that are already highlighted in the model will be unhighlighted. MATLAB® structure for one timing path
unhighlight In the Simulink® model, unhighlights all blocks currently highlighted. No argument
disp Displays a summary of timing analysis results on the MATLAB console, including the worst slack value among all timing paths. No argument
delete This is a destructor of the xilinx.analyzer class No argument
Table 2. Timing Path Data in a MATLAB Structure
Field Name Description
Slack The double value containing timing slack for the path
Delay Total Data Path delay for the path
Levels_of_Logic Number of elements in Vivado design for the timing path. The number of HDL blocks in the timing path may be different from Levels_of_Logic.
Source First HDL block in the timing path
Destination Last HDL block in the timing path
Source_Clock Name of the clock domain for the source block
Destination_Clock Name of the clock domain for the destination block
Path_Constraints Timing constraint used for the path. For a multi-clock design, the path constraint can be a multi-clock timing constraint.
Block_Masks Cell array where each element contains mask information for a HDL block.
Simulink_Names Cell array where each element contains hierarchical name of a block in Model Composer model
Vivado_Names Cell array where each element contains name of HDL block in Vivado database
Type A timing violation type. The value is either ‘setup’ or ‘hold’.

xilinx.analyzer - Construct xilinx.analyzer class object

Syntax

analyzer_object = xilinx.analyzer(<name_of_the_model>', '<path_to_netlist_directory>')
Description

A call to xilinx.analyzer constructor returns object of the class.

The first argument is the name of the Model Composer model. The model must be open before the class constructor is called.

The second argument is an absolute or relative path to the netlist directory. You must have read permission to the netlist directory.

To access API functions of the xilinx.analyzer class use the object of the class as described below. To get more details for a specific API function type the following at the MATLAB command prompt:

help xilinx.analyzer.<API_function>
Example
//Construct class. Must give the model name and absolute or relative path to the 
//target directory

>> timing_object = xilinx.analyzer('fixed_point_IIR', './netlist_for_timing_analysis')

timing_object = 

Number of setup paths = 9
Worst case setup slack = -1.6430

isValid – Check validity of Vivado timing paths

Syntax
result = analyzer_object.isValid();
Description

If timing analysis data is valid then the result equals '1', otherwise it is '0'. Use this API to make sure that the xilinx.analyzer class construction was successful and the timing data was valid.

Example
//Determine if timing analysis data is valid

>> valid_status = timing_object.isValid()

valid_status =

     1

getErrorMessage - Get an error message

Syntax
result = analyzer_object.getErrorMessage();
Description

Returns an error message string if the call to the class constructor or other API function had an error.

Example
//Determine if there was an error in the xilinx.analyzer constructor
//or in any of the API functions

>> err_msg = timing_object.getErrorMessage()

err_msg =

     ''

getStatus - Timing analysis status

Syntax
string = analyzer_object.getStatus();
Description

The returned string is either 'PASSED' or 'FAILED'. If any of the timing paths have a violation, i.e. negative slack, then the timing analysis status is considered failed.

Example
//Determine if there were timing path violations in Simulink model

>> analysis_status = timing_object.getStatus()

analysis_status =

FAILED

getVivadoStage - Get Vivado design stage for timing analysis

Syntax
string = analyzer_object.getVivadoStage();
Description

The returned string is the Vivado design stage after which timing analysis was performed and data collected in Vivado. The value is either 'Post Synthesis' or 'Post Implementation'.

Example
//Determine Vivado stage when timing data was collected

>> design_stage = timing_object.getVivadoStage()

design_stage =

Post Synthesis

paths - Access all timing paths

Syntax
<array_of_timing_paths_structure> = analyzer_object.paths('<violation_type>');
Description

The returned value is an array of MATLAB structures. Each structure contains data for a timing path, sorted in decreasing order of timing violation, i.e., in increasing order of slack value.

The argument violation_type is either 'setup' or 'hold' string.

Example
//Return an array of the timing path structures

>> all_timing_paths = timing_object.paths('setup')

all_timing_paths = 

1x9 struct array with fields:

    Slack
    Delay
    Levels_of_Logic
    Source
    Destination
    Source_Clock
    Destination_Clock
    Path_Constraints
    Block_Masks
    Simulink_Names
    Vivado_Names
    Type
Note:

There are a total of nine timing paths in this timing analysis.

You can find the data fields in each timing path as shown in Example 1 in Additional Information.

violations - Access paths with timing violations

Syntax
<array_of_timing_paths_structure> = analyzer_object.violations('<violation_type>');
Description

The returned value is an array of MATLAB structures. Each member of the array is data for a path with a timing violation. The array elements are sorted in decreasing order of timing violation. If there are no timing violations in the design then the API function returns an empty array.

The argument violation_type is either 'setup' or 'hold'.

Example
//Return an array of timing paths with setup violations

>> violating_paths = timing_object.violations('setup')

violating_paths = 

1x2 struct array with fields:

    Slack
    Delay
    Levels_of_Logic
    Source
    Destination
    Source_Clock
    Destination_Clock
    Path_Constraints
    Block_Masks
    Simulink_Names
    Vivado_Names
    Type

There are a total of two paths with violations in this timing analysis.

You can find the data fields in each timing path as shown in Example 3 in Additional Information.

print - Print timing path information

Syntax
analyzer_object.print(<timing_path_structures>);
Description

Prints timing data such as Slack, Path Delay, Levels of Logic, Name of Source and Destination blocks, Source and Destination clocks, Path Constraints, etc. for the input timing path structure.

The argument is an array of MATLAB structures with one or more elements.

Examples
//Print timing path information for path #1

>> timing_object.print(all_timing_paths(1))
Path Num            Slack (ns)             Delay (ns)            Levels of Logic   
Source/Destination Blocks            Source Clock      Destination Clock              Path 
Constraints
   1                            -1.6430                 11.5690                     6                           
fixed_point_IIR/Delay1                                 clk                           clk                           
create_clock -name clk -period 2 [get_ports clk]
                                                                                                                                  
fixed_point_IIR/IIR Filter Subsystem/Delay4

ans =

     1

//Print timing path information for path #3

>> timing_object.print(all_timing_paths(3))
Path Num            Slack (ns)             Delay (ns)            Levels of Logic   
Source/Destination Blocks            Source Clock      Destination Clock              Path 
Constraints
   1                            1.1320                   0.5270                      0                           
fixed_point_IIR/Delay1                            clk                              clk                             
create_clock -name clk -period 2 [get_ports clk]
                                                                                                                                  
fixed_point_IIR/Delay1

ans =

     1

//Print timing path information for path #2 from violating_paths array

>> timing_obj.print(violating_paths(2))
Path Num            Slack (ns)             Delay (ns)            Levels of Logic   
Source/Destination Blocks            Source Clock      Destination Clock              Path 
Constraints
   1                            -1.3260                 11.2520                    6                            
fixed_point_IIR/Delay1                                 clk                           clk                           
create_clock -name clk -period 2 [get_ports clk]
                                                                                                                                  
fixed_point_IIR/Delay2

ans =

     1

highlight - Highlight design blocks for a timing path

Syntax
analyzer_object.highlight(<timing_path_structure>);
Description

This API highlights HDL blocks for the timing path passed in the argument. It doesn't change the highlighting of a block from other paths, so more than one timing path can be highlighted if you use this function repeatedly.

The argument is the MATLAB structure for one timing path.

Example
//Highlight Simulink model blocks in the selected path
//Don't change highlighting of currently highlighted blocks in the model

>> [result, err_msg] = timing_object.highlight(all_timing_paths(1));

Highlighted Model Composer model blocks appear as shown below.

Figure 2. HDL Model Blocks Generated by Your Tool
 

highlightOnePath - Highlight design blocks for one timing path

Syntax
analyzer_object.highlightOnePath(<timing_path_structure>);
Description

This API highlights HDL blocks for the timing path passed in the argument. If a block from other paths is already highlighted then it will be unhighlighted first, so only one path is highlighted at a time.

The argument is the MATLAB structure for one timing path.

Example
//Highlight a single path in Model Composer model, and unhighlight currently
//highlighted paths

>> [result, err_msg] = timing_object.highlightOnePath(violating_paths(2));

unhighlight - Unhighlight design blocks

Syntax
analyzer_object.unhighlight();
Description

This API unhighlights blocks that are already highlighted. The blocks in Model Composer model are displayed in their original colors.

Example
//Unhighlight any Simulink block that is currenly highlighted

>> [result, err_msg] = timing_object.unhighlight();

disp - Display summary of timing analysis

Syntax
analyzer_object.disp();
Description

This API displays the summary of timing paths on the MATLAB console, including the worst slack value.

Example
//Display a summary of timing analysis

>> timing_object.disp()
Number of setup paths = 9
Worst case setup slack = -1.6430

delete - Delete xilinx.analyzer class object

Syntax
analyzer_object.delete();
Description

This is a destructor for the xilinx.analyzer class.

Example
//Delete xilinx.analyzer object, i.e., timing_object

>> timing_object.delete();

Additional Information

Accessing data fields of timing path structures:

Example 1: Data for timing path #1
//Return the data fields for the timing path with the worst slack

>> all_timing_paths(1)

ans = 

                Slack: -1.6430
                Delay: 11.5690
      Levels_of_Logic: 6
               Source: 'fixed_point_IIR/Delay1'
          Destination: 'fixed_point_IIR/IIR Filter Subsystem/Delay4'
         Source_Clock: 'clk'
    Destination_Clock: 'clk'
     Path_Constraints: 'create_clock -name clk -period 2 [get_ports ...'
          Block_Masks: {1x5 cell}
       Simulink_Names: {1x5 cell}
         Vivado_Names: {1x5 cell}
                 Type: 'setup'
Example 2: Data for timing path #3
//Return the data fields for a timing path

>> all_timing_paths(3)

ans = 

                Slack: 1.1320
                Delay: 0.5270
      Levels_of_Logic: 0
               Source: 'fixed_point_IIR/Delay1'
          Destination: 'fixed_point_IIR/Delay1'
         Source_Clock: 'clk'
    Destination_Clock: 'clk'
     Path_Constraints: 'create_clock -name clk -period 2 [get_ports ...'
          Block_Masks: {'fprintf('','COMMENT: begin icon graphics')...'}
       Simulink_Names: {'fixed_point_IIR/Delay1'}
         Vivado_Names: {'fixed_point_iir.fixed_point_iir_struct.delay1'}

Type: 'setup'

Example 3: Data for path #1 in violating_paths array

//Return the data fields in a timing path with timing violations

>> violating_paths(1)

ans = 

                Slack: -1.6430
                Delay: 11.5690
      Levels_of_Logic: 6
               Source: 'fixed_point_IIR/Delay1'
          Destination: 'fixed_point_IIR/IIR Filter Subsystem/Delay4'
         Source_Clock: 'clk'
    Destination_Clock: 'clk'
     Path_Constraints: 'create_clock -name clk -period 2 [get_ports ...'
          Block_Masks: {1x5 cell}
       Simulink_Names: {1x5 cell}
         Vivado_Names: {1x5 cell}
                 Type: 'setup'