xilinx.resource_analyzer - 2023.2 English

Vitis Model Composer User Guide (UG1483)

Document ID
UG1483
Release Date
2023-11-15
Version
2023.2 English

xilinx.resource_analyzer is a MATLAB class that enables cross-probing between the Model Composer model and Vivado resource utilization data.

The Model Composer resource 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 Vivado tools runtime vs. accuracy of the resource utilization data. If you select either the Post Synthesis or the Post Implementation option of Perform analysis and click the Generate button, then Vivado resource utilization information is collected during the netlist generation. Once the netlist generation has completed, the xilinx.resource_analyzer class is used to access this Vivado resource utilization results. The xilinx.resource_analyzer class object processes Vivado resource utilization data to display the number of resources (BRAMs, DSPs, Registers, and LUTs) used in the Simulink model, as well as by the subsystems and low-level blocks in the model.

The cross-probing between Vivado resource utilization results and the Model Composer model is made possible through the following API functions in the xilinx.resource_analyzer class.

Table 1. Functions in xilinx.resource_analyzer Class
Function Name Description Function Argument
xilinx.resource_analyzer This is a constructor of the class. A call to the xilinx.resource_analyzer constructor returns object of the class.

First argument is design model name.

Second argument is path to already generated netlist directory.

getVivadoStage Returns either Post Synthesis or Post Implementation. This is the Vivado design stage after which resource analysis was performed. No argument
getDevicePart Returns a string for device part, package and speed grade for the device in which the design will be implemented. No argument
getDeviceResource Returns a string for the total count of the specified type of resource in the target AMD device. (Optional) Resource type.Resource types are: BRAMs, DSPs, Registers, or LUTs.
printDeviceResources Prints the total number of BRAMs, DSPs, Registers, and LUTs available on the target AMD device. The counts are printed in the MATLAB console. No argument.
getCount Returns a count for the particular resource type used by a block or subsystem.

(Optional) First argument is a Simulink handle or pathname for the block.

(Optional) Second argument is Resource type. Resource types are: BRAMs, DSPs, Registers, or LUTs.

print Returns a count for the particular resource type used by a block or subsystem.

(Optional) First argument is a Simulink handle or pathname for the block or subsystem.

(Optional) Second argument is resource type. Resource types are: BRAMs, DSPs, Registers, or LUTs.

getDistribution

Returns three values:

An array of MATLAB structures. Each element in the array is a structure containing the name of a block or subsystem directly under the subsystem in the argument, with a key-value pair of the resource type and number of resources used by that sub block or subsystem.

A count of the resources used by the self (the block or subsystem specified in the argument).

A count of the resources used by both blocks and subsystems combined.

First argument is a Simulink handle or pathname for the block or subsystem.

Second argument is resource type. Resource types are: BRAMs, DSPs, Registers, or LUTs.

getErrorMessage Returns an error message string if the call to the class constructor or other API function had an error. No argument
highlight In the Simulink model, highlights the specified block or subsystem with yellow color and red border. A Simulink handle or pathname for the block to highlight.
unhighlight In the Simulink model, unhighlights a block which is currently highlighted. (Optional) A Simulink handle or pathname for the block to unhighlight.
delete This is a destructor of the xilinx.resource_analyzer class. No argument
Table 2. Resource Data in a MATLAB Structure
Field Name Description
BRAMs

Count of block RAM resources for a block or subsystem.

BRAMs are counted in this way:
  • RAMB36E: 1 BRAM
  • RAMB36E: 1 BRAM
  • RAMB18E: 0.5 BRAM
  • FIFO18E: 0.5 BRAM

Variations of Primitives (for example, RAM36E1 and RAM36E2) are all counted in the same way.

Total BRAMs = (Number of RAMB36E) + (Number of FIFO36E) + 0.5 (Number of RAMB18E + Number of FIFO18E)

DSPs Count of DSP48 resources utilized by a block or subsystem.
Registers Count of Flip-Flops and Latches used by the design is reported as the number of Registers utilized by the design model, a particular block, or a subsystem.
LUTs Count of all LUT type resources utilized by a block or subsystem.

xilinx.resource_analyzer – Construct xilinx.resource_analyzer class object

Syntax
resource_analyzer_obj = 
xilinx.resource_analyzer('<name_of_the_model>','<path_to_netlist_directory>');
Description

A call to xilinx.resource_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.resource_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.resource_analyzer.<API_function>
Example
//Construct class. Must give the model name and absolute or relative path to the 
//target directory

>> res_obj = xilinx.resource_analyzer('test_decimator', './netlist_for_resource_analysis')

res_obj = 

Resources used by: test_decimator
BRAMs => 0.5
DSPs => 1
Registers => 273
LUTs => 153

getVivadoStage – Get Vivado design stage for resource analysis

Syntax
string = resource_analyzer_obj.getVivadoStage();
Description

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

Example
//Determine Vivado stage when resource data was collected

>> design_stage = res_obj.getVivadoStage()

design_stage =

Post Synthesis

getDevicePart – Get target AMD device part name

Syntax
string = resource_analyzer_obj.getDevicePart();
Description

Gets the name of the AMD device to which your design is targeted.

Example
//Get the AMD part in which you will implement your design

>> part_name = res_obj.getDevicePart()

part_name =

xc7k325tfbg676-3

getDeviceResource – Get number of resources in target device

Syntax
total_resource_count = resource_analyzer_obj.getDeviceResource(<resource_type>);
Description

The returned value is the total number of a particular type of resource contained in the AMD device for which you are targeting your design.

The resource_type may be:

  • BRAMs - Block RAM and FIFO primitives
  • DSPs - DSP48 primitives
  • Registers - Registers and Flip-Flops
  • LUTs - All LUT types combined

If no resource_type is provided, the command returns a MATLAB structure containing all device resources.

Example
//Determine the total number of Block RAMs in the AMD device

>> total_brams = res_obj.getDeviceResource('BRAMs')

total_brams =

445

//Determine the total number of Block RAMs, DSP blocks, Registers, and LUTs in the
//AMD device

>> total_resource_count = res_obj.getDeviceResource

total_resource_count = 

    BRAMs: '445'
     DSPs: '840'
Registers: '407600'
     LUTs: '203800'

printDeviceResources – Print number of resources in target device

Syntax
resource_analyzer_obj.printDeviceResources();
Description

Prints the number of all types of resources in the used AMD device. The output is printed in the MATLAB console.

Example
//Print the number of all types of resources contained in the target AMD device

>> res_obj.printDeviceResources()

BRAMs => 445
DSPs => 840
Registers => 407600
LUTs => 203800

getCount – Get resource utilization for subsystem or block

Syntax
<block_resource_count> = resource_analyzer_obj.getCount(<blockID>,<resource_type>);
Description

The returned value is the total number of a particular type of resource used in the specified subsystem or block.

The blockID can be either a Simulink handle or a pathname (a hierarchical name) for the subsystem or block.

The resource_type may be:

  • BRAMs - Block RAM and FIFO primitives
  • DSPs - DSP48 primitives
  • Registers - Registers and Flip-Flops
  • LUTs - All LUT types combined

If no resource_type is provided, the command returns a MATLAB structure containing all device resources.

Example
// Return register resource utilization for Simulink block with pathname
// test_decimator/addr_gen

>> regs_in_block = res_obj.getCount('test_decimator/addr_gen', 'Registers')

ans =

         105
//Return resource utilization for the entire Simulink model

>> total_resource_count = res_obj.getCount()

Resources used by: test_decimator
BRAMs => 0.5
DSPs => 1
Registers => 273
LUTs => 153

print – Prints all resources used by a subsystem or block

Syntax
resource_analyzer_obj.print(<blockID>);
Description

Prints all resources (for all resource types: BRAMs, Registers, DSPs, and LUTs) used by a subsystem or block, in key-value pair. Resources are printed in the MATLAB console.

If you enter a blockID (which can be either a Simulink handle or a pathname), all resources used by the specified block or subsystem will be printed in the MATLAB console.

If no blockID argument is provided, all resources used by the top-level design will be printed in the MATLAB console.

Example
// Print resource utilization for Simulink subsystem with pathname
// test_decimator/addr_gen

>> res_obj.print('test_decimator/subsystem1')
Resources used by: test_decimator/subsystem1
BRAMs => 0.5
DSPs => 1
Registers => 49
LUTs => 97

//Print resource utilization for the entire Simulink model

>> res_obj.print()
Resources used by: test_decimator
BRAMs => 0.5
DSPs => 1
Registers => 273
LUTs => 153

getDistribution – Get count of each resource type used by each block and subsystem under a specified subsystem

Syntax
[<distribution_array>, <self_count>, <total_count>] = 
resource_analyzer_obj.getDistribution(<blockId>, <resource_type>)
Description

Returns count for the specified type of resource used by each block and subsystem directly under the subsystem passed as the argument.

The three returned values are:

  • An array of MATLAB structures. Each element in the array is a structure containing the name of a block or subsystem directly under the subsystem in the argument, with a key-value pair of the resource type and number of resources used by that sub block or subsystem.
  • A count of the resources used by the self (the block or subsystem specified in the argument).
  • A count of the resources used by both blocks and subsystems combined.

The blockID can be either a Simulink handle or a pathname (a hierarchical name) for the subsystem or block. If no blockID is provided, then the command assumes the top-level module.

The resource_type may be:

  • BRAMs - Block RAM and FIFO primitives
  • DSPs - DSP48 primitives
  • Registers - Registers and Flip-Flops
  • LUTs - All LUT types combined
Example
// Return Register resource distribution for Simulink block with pathname
// test_decimator. This is top level of the design

>> [res_dist, self, total] = res_obj.getDistribution ('test_decimator','Registers')

res_dist = 

1x8 struct array with fields:

    Name
    Hier_Name
    Count


self =

         119


total =

         273
//Return resource utilization for the entire Simulink model

>> total_resource_count = res_obj.getCount()

Resources used by: test_decimator
BRAMs => 0.5
DSPs => 1
Registers => 273
LUTs => 153

getErrorMessage – Get an error message

Syntax
result = resource_analyzer_obj.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.resource_analyzer constructor
//or in any of the API functions

>> err_msg = res_obj.getErrorMessage()

err_msg =

     ''

highlight – Highlight design subsystems and blocks

Syntax
resource_analyzer_obj.highlight(<blockId>)
Description

This API highlights blocks in the Simulink model. Highlighted blocks in the Model Composer model are displayed in yellow and outlined in red. Highlighting blocks using this command does not change the highlighting of other blocks currently highlighted, so more than one block can be highlighted if you use this function repeatedly.

When you enter a blockID (which can be either a Simulink handle or a pathname) for a block or subsystem, the specified block or subsystem will be highlighted in the Simulink model. When the block/subsystem is highlighted then all parent subsystems up to the top level are also highlighted. When the top level module handle is provided as the highlight function argument no block is highlighted, but the Simulink model display changes to the top level, showing all blocks and subsystems at the top level.

Example
//Highlight Simulink block with pathname fixed_point_IIR/IIR Filter Subsystem/Mult1

>> res_obj.highlight('test_decimator/addr_gen/AddSub1')

Highlighted Model Composer model blocks appear as shown below.

Figure 1. HDL Model Blocks

unhighlight – Unhighlight design subsystems and blocks

Syntax
resource_analyzer_obj.unhighlight(<blockId>)
Description

This API unhighlights blocks that are currently highlighted in the Simulink model. When they are unhighlighted, the blocks in the Model Composer model are displayed in their original colors.

If you enter a blockID (which can be either a Simulink handle or a pathname) for a block or subsystem, the specified block or subsystem will be unhighlighted in the Simulink model. When the block/subsystem is unhighlighted, all parent subsystems up to the top level are also unhighlighted.

If no blockID argument is provided, all currently highlighted blocks and subsystems will be unhighlighted.

Example
//Unhighlight Simulink block with pathname test_decimator/addr_gen/Register4

>> res_obj.unhighlight('test_decimator/addr_gen/Register4')


//Unhighlight all Simulink blocks that are currenly highlighted

>> res_obj.unhighlight();

delete – Delete xilinx.resource_analyzer class object

Syntax
resource_analyzer_obj.delete();
Description

This is a destructor for the xilinx.resource_analyzer class.

Example
//Delete xilinx.resource_analyzer object, i.e., res_obj

>> delete(res_obj);

OR

>> res_obj.delete();