RTW.TflBlockEntry Class

Namespace: RTW

Create code replacement table entry for a block

Since R2024a

Description

Use the RTW.TflBlockEntry class to finely control the specification of a code replacement entry for a block. For block replacement entries, you can specify match criteria such as block parameter settings that the entry must match for code replacement. You can specify implementation functions for each model system function that the block generates, such as initialize, update, and terminate functions.

The RTW.TflBlockEntry class is a handle class.

Creation

Description

entry = RTW.TflBlockEntry creates an RTW.TflBlockEntry object.

Properties

Key — Type of block to replace

'DiscreteFIR' | 'Biquad Filter' | 'FFT' | 'IFFT' | 'FIR Decimation' | 'FIR Interpolation'

Type of block to replace, specified as a character array.

Example: 'DiscreteFir'

AdditionalHeaderFiles — Specifies additional header files for table entry

{} (default) | array of character vectors | string array

The AdditionalHeaderFiles value specifies additional header files for a code replacement table entry.

Example: 'AdditionalHeaderFiles',{}

BlockParams — Block dialog properties to match

[] (default) | array of block property handles

Block dialog properties for the block replacement entry to match, specified as an array of block property handles, such as the handle created by the RTW.BlockProperty function. Each block property handle specifies the name and value of a block property that the block entry matches during code replacement. You can add a block property by using the addBlockProperty method.

Example: RTW.BlockProperty('FilterStructure','Direct form')

BlockParamArgs — Numeric block parameters used by implementations

[] (default) | array of argument handles

Numeric block parameters whose values are used by the implementation functions, specified as an array of argument handles. These parameters are called block parameter arguments. Implementation functions can use block parameter argument data directly (by referencing the parameter) or indirectly (by referencing a derived parameter that uses the block parameter argument).

To use a block parameter value in an implementation function, you must specify the data type information of the parameter by adding a block parameter argument as an argument handle in BlockParamArgs. Create an argument handle that specifies the data type by using the getTflArgFromString function or the RTW.TflArgMatrix and RTW.TflArgNumeric classes. Add the argument by using the addBlockParamArg method.

During replacement, the code generator uses the data type information to:

• Match blocks that use the corresponding data type for the parameter.

• Construct the arguments for calling the implementation code that uses the block parameter argument.

Example: [RTW.TflArgMatrix('Coefficient','RTW_IO_INPUT','int16')]

DerivedBlockParams — Derived parameters used for implementation function arguments

[] (default) | cell array of string MATLAB^® expressions

Derived parameters that one or more implementation functions use for arguments, specified as a cell array of string MATLAB expressions. The expressions must follow the format 'derivedParameter = expression' where:

• The right side of the expression is a constant, conceptual argument, block parameter, or a MATLAB function that is on the path and supports code generation.

• If the right side of the expression uses variables such as block parameters, conceptual arguments, or other derived block parameters, each variable follows the format <%VarName>.

• The left side of the expression is the derived parameter that an implementation function of the block entry uses.

Depending on the expression, the derived parameter is generated as a variable in the generated code or is evaluated and inlined as a constant in the code. Derived parameters that use the functions size, length, and numel are evaluated during code generation and inlined as constants. A derived parameter does not appear in the generated code if none of the block entry implementation functions use the parameter.

Example: [{'coeffDim = size(<%Coefficients>)'} {'dim1 = <%coeffDim>(1)'} {'dim2 = <%coeffDim>(2)'}]

Example: [{'InputDim = size(<%u1>)'}]

Example: 'tempBuffer = <%u1>'

GenCallback — Specifies callback that follows code generation

'' (default) | 'RTW.copyFileToBuildDir'

The GenCallback specifies a callback that follows code generation. If you specify 'RTW.copyFileToBuildDir', and if this function entry is matched and used, the code generator calls function RTW.copyFileToBuildDir after code generation. This callback function copies additional header, source, or object files that you have specified for this function entry to the build folder.

Example: 'GenCallback',''

ImplementationVector — Implementation functions

[] (default) | cell array

Implementation functions that replace the generated code for the block, specified as an Nx2 cell array in which the first column contains the string name of a model system function and the second column contains an RTW.CImplementation object that represents the implementation function.

Model system functions include:

• 'initialize'

• 'update'

• 'output'

• 'terminate'

You can add an implementation function by using the addImplementation method.

Example: [{'initialize'};{initImplementationObj}]

Priority — Search priority for block entry

100 (default) | integer from 0 to 100

Search priority for the block entry relative to other entries for the block, specified as an integer from 0 to 100. The highest priority is 0 and the lowest priority is 100. If the code replacement table provides two entries of the same block key and conceptual argument list, the entry with the higher priority is used for replacement.

Example: 100

SideEffects — Specifies whether to attempt to optimize away the implementation function

false (default) | true

The SideEffects value flags the code generator not to optimize away the implementation function described by this entry. This parameter applies to implementation functions that return void but are not to be optimized away, such as a memcpy implementation or an implementation function that accesses global memory values. For those implementation functions only, you must include this parameter and specify the value true.

Example: 'SideEffects',false

Methods

Public Methods

addBlockProperty	Add block property to a block replacement entry
addBlockParamArg	Add block property data type information
addImplementation	Add implementation function to block replacement entry
createDWorkArg	Create DWork argument for a block replacement entry

Examples

Create Block Replacement Entry

This example shows how to create a block replacement entry for the Discrete FIR Filter block.

Create the block entry by using the key DiscreteFir for the Discrete FIR Filter block. Set the priority of the entry to 1.

hLib = RTW.TflTable;

entry = RTW.TflBlockEntry;
entry.Key = 'DiscreteFir';
entry.Priority = 1;

Specify the block properties to match by using the RTW.BlockProperty function. For this example, specify that the block entry matches Discrete FIR Filter blocks that have FilterStructure set to Direct form and InputProcessing set to Columns as channels (frame based).

prop1 = RTW.BlockProperty('FilterStructure', 'Direct form');
addBlockProperty(entry, prop1);
prop2 = RTW.BlockProperty('InputProcessing', 'Columns as channels (frame based)'); 
addBlockProperty(entry, prop2);

Create the conceptual representation of the block by specifying block inputs and outputs. For this example, add the first output with the type single to the entry.

arg = getTflArgFromString(hLib, 'y1', 'single');
addConceptualArg(entry, arg);

Add the specifications for the implementation functions to the entry. For this example, add the initialization function init_impl, which uses the derived block parameter numTaps as an input argument. Because the derived parameter uses the block parameter Coefficients, specify the data type for Coefficients by adding a block parameter argument.

impl = RTW.CImplementation;
impl.Name = 'init_impl';

blockParamArg = RTW.TflArgMatrix('Coefficients','RTW_IO_INTPUT','int16');
addBlockParamArg(entry,blockParamArg);

entry.DerivedBlockParams{1} = 'numTaps = length(<%Coefficients>)';
arg = getTflArgFromString(hLib, 'numTaps', 'uint16');
addArgument(impl, arg);

addImplementation(entry, 'initialize', impl);

Add the block replacement entry to the code replacement table.

addEntry(hLib, entry);

Version History

Introduced in R2024a