xlAddTerms - 2022.2 English

Vitis Model Composer User Guide (UG1483)
Document ID
UG1483
Release Date
2023-01-13
Version
2022.2 English

xlAddTerms is similar to the addterms command in Simulink, in that it adds blocks to terminate or drive unconnected ports in a model. With xlAddTerms, output ports are terminated with a Simulink terminator block, and input ports are correctly driven with either a Simulink or HDL constant block. Additionally HDL gateway blocks can also be conditionally added.

The optionStruct argument can be configured to instruct xlAddTerms to set a block's property (e.g. set a constant block's value to 5) or to use different source or terminator blocks.

Syntax

xlAddTerms(arg1,optionStruct)

Description

In the following description, 'source block' refers to the block that is used to drive an unconnected port. And 'term block' refers to the block that is used to terminate an unconnected port.

xlAddTerms(arg1,optionStruct)

xlAddTerms takes either 1 or 2 arguments. The second argument, optionStruct argument is optional. The first argument can be the name of a system, or a block list.

Table 1. xlAddTerms Arguments
arg1 Description
gcs A string-handle of the current system
'top/test1' A string-handle of a system called test1. In this case, xlAddTerms is passed a handle to a system. This will run xlAddTerms on all the blocks under test1, including all children blocks of Subsystems.
{'top/test1'} A block list of string handles. In this case, xlAddTerms is passed a handle to a block. This will run xlAddTerms only on the block called test1, and will not process child blocks.
{'t/b1';'t/b2';'t/b3'} A block list of string handles.
[1;2;3] A block list of numeric handles.

The optionStruct argument is optional, but when included, should be a MATLAB structure. The following table describes the possible values in the structure. The structure field names (as is true with all MATLAB structure field names) are case sensitive.

Table 2. optionStruct Arguments
optionStruct Description
Source

xlAddTerms can terminate in-ports using any source block (refer to SourceWith field). The parameters of the source block can be specified using the Source field of the optionStruct by passing the parameters as sub-fields of the Source field. The Source field prompts xlAddTerms to do a series of set_params on the source block. Since it is possible to change the type of the source block, it is left to the user to ensure that the parameters here are relevant to the source block in use.

E.g. when a Simulink constant block is used as a Source Block, setting the block's value to 10 can be done with: 

Source.value = '10'

And when a HDL Constant block is used as a Source Block, setting the constant block to have a value of 10 and of type UFIX_32_0 can be done with:

Source.const = '10'; 
Source.arith_type='Unsigned'; 
Source.bin_pt=0; 
Source.n_bits=32;
SourceWith

The SourceWith field allows the source block to be specified. Default is to use a constant block. SourceWith has two sub-fields which must be specified.

SourceWithBlock: A string specifying the full path and name of the block to be used. e.g. 'built-in/Constant' or 'xbsIndex_r3/AddSub'.

SourceWithPort: A string specifying the port number used to connect. E.g. '1' or '3' Specifying '1' instructs xlAddTerms to connect using port 1, etc.
TermWith

The TermWith field allows the term block to be specified. Default is to use a Simulink terminator block. TermWith has two sub-fields which must be specified.

TermWithBlock: A string specifying the full path and name of the block to be used. e.g. 'built-in/Terminator' or 'xbsIndex_r3/AddSub'.

TermWithPort:

A string specifying the port number used to connect. E.g. '1' or '3'

Specifying '1' instructs xlAddTerms to connect using port 1, etc.
UseGatewayIns Instructs xlAddTerms to insert HDL gateway ins when required. The existence of the field is used to denote insertion of gateway ins. This field must not be present if gateway ins are not to be used.
GatewayIn

If gateway ins are inserted, their parameters can be set using this field, in a similar way as for Source and Term.

For example:

GatewayIn.arith_type='Unsigned'; 
GatewayIn.n_bits='32' 
GatewayIn.bin_pt='0'

will set the gateway in to output a ufix_32_0.
UseGatewayOuts Instructs xlAddTerms to insert HDL gateway outs when required. The existence of the field is used to denote insertion of gateway outs. This field must not be present if gateway outs are not to be used.
GatewayOut

If gateway outs are inserted, their parameters can be set using this field, in a similar way as for Source and Term.

For example:

GatewayOut.arith_type='Unsigned'; 
GatewayOut.n_bits='32' 
Gatewayout.bin_pt='0'

This sets the gateway out to take an input of ufix_32_0.
RecurseSubsystems Instructs xlAddTerm to recursively run xlAddTerm under all child Subsystems. Expects a scalar number, 1 or 0.

Examples

Example 1: Runs xlAddTerms on the current system, with the default parameters: constant source blocks are used, and gateways are not added. Subsystems are recursively terminated.

xlAddTerms(gcs);

Example 2: Runs xlAddTerms on all the blocks in the Subsystem tt./mySubsystem.

xlAddTerms(find_system('tt/mySubsystem','SearchDepth',1));

Example 3: Runs xlAddTerms on the current system, setting the source block's constant value to 1, using gateway outs and changing the term block to use a Simulink display block.

s.Source.const = '10';
s.UseGatewayOuts = 1;
s.TermWith.Block = 'built-in/Display';
s.TermWith.Port = '1';
s.RecurseSubsystem = 1;
xlAddTerms(gcs,s);

Remarks

Note that field names are case sensitive. When using the fields 'Source', 'GatewayIn' and 'GatewayOut', users have to ensure that the parameter names to be set are valid.

See Also

xlTBUtils