setTflCOperationEntryParameters

Set specified parameters for operator entry in code replacement table

Syntax

setTflCOperationEntryParameters(hEntry,varargin)

Description

setTflCOperationEntryParameters(hEntry,varargin) sets specified parameters for an operator entry in a code replacement table.

Examples

Set Parameters for Addition Operator Entry

This example shows how to use the setTflCOperationEntryParameters function to set parameters for a code replacement operator entry for uint8 addition that matches a cast-after-sum algorithm.

op_entry = RTW.TflCOperationEntry;
op_entry.setTflCOperationEntryParameters( ...
    'Key',                      'RTW_OP_ADD', ...
    'EntryInfoAlgorithm',       'RTW_CAST_AFTER_OP', ...
    'Priority',                 90, ...
    'SaturationMode',           'RTW_SATURATE_UNSPECIFIED', ...
    'RoundingModes',            {'RTW_ROUND_UNSPECIFIED'}, ...
    'ImplementationName',       'u8_add_u8_u8', ...
    'ImplementationHeaderFile', 'u8_add_u8_u8.h', ...
    'ImplementationSourceFile', 'u8_add_u8_u8.c');

Set Parameters for Fixed-Point Division Operator Entry

This example shows how to use the setTflCOperationEntryParameters function to set parameters for a code replacement operator entry for fixed-point int16 division. The table entry specifies a net scaling between the operator inputs and output to map a range of slope and bias values to a replacement operation.

op_entry = RTW.TflCOperationEntryGenerator_NetSlope;
op_entry.setTflCOperationEntryParameters( ...
    'Key',                      'RTW_OP_DIV', ...
    'Priority',                 90, ...
    'SaturationMode',           'RTW_WRAP_ON_OVERFLOW', ...
    'RoundingModes',            {'RTW_ROUND_CEILING'}, ...
    'NetSlopeAdjustmentFactor',   1.0, ...
    'NetFixedExponent',           0.0, ...
    'ImplementationName',       's16_div_s16_s16', ...
    'ImplementationHeaderFile', 's16_div_s16_s16.h', ...
    'ImplementationSourceFile', 's16_div_s16_s16.c' );

Set Parameters for Fixed-Point Addition Operator Entry

This example shows how to use the setTflCOperationEntryParameters function to set parameters for a code replacement operator entry for fixed-point uint16 addition that matches a cast-after-sum algorithm. The parameters 'SlopesMustBeTheSame' and 'MustHaveZeroNetBias' must be set to true to specify equal slope and zero net bias across operator inputs and output. This maps relative slope and bias values (rather than a specific slope and bias combination) to a replacement operation.

op_entry = RTW.TflCOperationEntryGenerator;
op_entry.setTflCOperationEntryParameters( ...
    'Key',                     'RTW_OP_ADD', ...
    'EntryInfoAlgorithm',      'RTW_CAST_AFTER_OP', ...
    'Priority',                 90, ...
    'SaturationMode',           'RTW_WRAP_ON_OVERFLOW', ...
    'RoundingModes',            {'RTW_ROUND_UNSPECIFIED'}, ...
    'SlopesMustBeTheSame',      true, ...
    'MustHaveZeroNetBias',      true, ...
    'ImplementationName',       'u16_add_SameSlopeZeroBias', ...
    'ImplementationHeaderFile', 'u16_add_SameSlopeZeroBias.h', ...
    'ImplementationSourceFile', 'u16_add_SameSlopeZeroBias.c');

Input Arguments

hEntry — Handle to a code replacement table entry

handle

The hEntry is a handle to a code replacement table entry previously returned by one of the class instantiations in the table.

Class Instantiation	Support
hEntry = RTW.TflCOperationEntry;	Supports operator replacement.
hEntry = RTW.TflCOperationEntryGenerator;	Provides parameters for fixed-point addition and subtraction that are not available in RTW.TflCOperationEntry (SlopesMustBeTheSame and MustHaveZeroNetBias).
hEntry = RTW.TflCOperationEntryGenerator_NetSlope;	Provides net slope parameters for fixed-point multiplication and division that are not available in RTW.TflCOperationEntry (NetSlopeAdjustmentFactor and NetFixedExponent).
hEntry = RTW.TflBlasEntryGenerator;	Supports replacement of nonscalar operators with MathWorks BLAS functions.
hEntry = RTW.TflCBlasEntryGenerator;	Supports replacement of nonscalar operators with ANSI®/ISO® C BLAS functions.
hEntry = MyCustomOperationEntry; (where MyCustomOperationEntry is a class derived from RTW.TflCOperationEntry)	Supports operator replacement using custom code replacement table entries.

If you want to specify SlopesMustBeTheSame or MustHaveZeroNetBias for your operator entry, instantiate your table entry using hEntry = RTW.TflCOperationEntryGenerator rather than hEntry = RTW.TflCOperationEntry. If you want to use NetSlopeAdjustmentFactor and NetFixedExponent, instantiate your table entry by using hEntry = RTW.TflCOperationEntryGenerator_NetSlope.

Example: op_entry

varargin — Name-value pairs of arguments for operation entry

name-value pairs

Example: 'Key','RTW_OP_ADD'

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Key','RTW_OP_ADD'

AcceptExprInput — Specifies whether implementation operation accepts expression inputs

true | false

The AcceptExprInput value flags the code generator that the implementation function described by this entry accepts expression inputs. The default value is true if ImplType equals FCN_IMPL_FUNCT and false if ImplType equals FCN_IMPL_MACRO.

If the value is true, expression inputs are integrated into the generated code in a form similar to this form:

 rtY.Out1 = myAdd(rtU.In1, rtU.In2 * rtU.In3);

If the value is false, a temporary variable is generated for the expression input:

real_T temp;

temp = rtU.In2 * rtU.In3;
rtY.Out1 = myAdd(rtU.In1, temp);

Example: 'AcceptExprInput',true

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. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB^® workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalHeaderFiles',{}

AdditionalIncludePaths — Specifies additional include paths for table entry

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

The AdditionalIncludePaths value specifies the full path of additional include paths for a code replacement entry. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalIncludePaths',{}

AdditionalLinkObjs — Specifies additional link objects for table entry

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

The AdditionalLinkObjs value specifies additional link objects for a code replacement table entry. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalLinkObjs',{}

AdditionalLinkObjsPaths — Specifies additional link object paths for table entry

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

The AdditionalLinkObjsPaths value specifies the full path of additional link object paths for a code replacement entry. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalLinkObjsPaths',{}

AdditionalSourceFiles — specifies additional source files for table entry

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

The AdditionalSourceFiles value specifies additional source files for a code replacement table entry. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalSourceFiles',{}

AdditionalSourcePaths — Specifies additional source paths for table entry

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

The AdditionalSourcePaths value specifies the full path of additional source paths for a code replacement entry. The character vectors or string array can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'AdditionalSourcePaths',{}

AdditionalCompileFlags — Specifies additional compiler flags for table entry

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

The AdditionalCompileFlags value specifies additional flags required to compile the source files defined for a code replacement table entry.

Example: 'AdditionalCompileFlags',{}

AdditionalLinkFlags — Specifies additional linker flags for table entry

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

The AdditionalLinkFlags value specifies additional flags required to link the compiled files for a code replacement table entry.

Example: 'AdditionalLinkFlags',{}

AllowShapeAgnosticMatch — Enables matrix matches based on the total number of elements rather than specific matrix shape

false (default) | true

The AllowShapeAgnosticMatch value enables code replacement match based on total number of elements rather than specific matrix shape for matrices that are contiguously allocated in memory. For more information, see Allow Shape Agnostic Match.

Example: 'AllowShapeAgnosticMatch', false

ArrayLayout — Specifies layout of array storage for table entry

'COLUMN_MAJOR' (default) | 'ROW_MAJOR' | 'COLUMN_AND_ROW'

The ArrayLayout value specifies the order of array elements in memory supported by the replacement implementation. By default, the replacement implementation supports column-major data layout. For ROW-MAJOR, the replacement implementation supports row-major data layout. For COLUMN_AND_ROW, the replacement implementation supports column-major and row-major data layouts.

Example: 'ArrayLayout','ROW_MAJOR'

EntryInfoAlgorithm — Specifies math algorithm to match for table entry

'RTW_CAST_BEFORE_OP' (default) | 'RTW_CAST_AFTER_OP'

The EntryInfoAlgorithm value specifies the algorithm for the specified math function that must be matched for operator replacement to occur. Code replacement libraries support replacement based on the algorithm for math operations RTW_OP_ADD and RTW_OP_MINUS. Valid arguments for the supported operations are listed in the table. The arguments have the same meaning for both operations.

Argument	Meaning
RTW_CAST_BEFORE_OP	Before performing the operation, type cast input values to the output data type. If the output type cannot exactly represent the input values, losses can occur as a result of the cast to the output type. Additional loss can occur when the result of the operation is cast to the final output type.
RTW_CAST_AFTER_OP	Compute the ideal result of the operation of inputs. Then, type cast the result to the output data type. Loss occurs during the type cast. This algorithm behaves similarly to the C language except when the signedness of the operands does not match. For example, when you add a signed long operation to an unsigned long operand, standard C language rules convert the signed long operand to an unsigned long operand. The result is a value that is not ideal.

Example: 'EntryInfoAlgorithm','RTW_CAST_AFTER_OP'

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 operation 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 entry to the build folder.

Example: 'GenCallback','RTW.copyFileToBuildDir'

ImplementationHeaderFile — Specifies name of header file that declares implementation operation

'' (default) | character vector | string scalar

The ImplementationHeaderFile value specifies the name of the header file that declares the implementation function. The character vector or string scalar can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'ImplementationHeaderFile','s32_mul.h'

ImplementationHeaderPath — Specifies path to implementation header file

'' (default) | character vector | string scalar

The ImplementationHeaderPath value specifies the full path to the implementation header file. The character vector or string scalar can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'ImplementationHeaderPath', fullfile('$MATLAB_ROOT', 'crl')

ImplementationName — Specifies name of implementation function

'' (default) | character vector | string scalar

The ImplementationName value specifies the name of the implementation function, which can match or differ from the Key name.

Example: 'ImplementationName','s32_mul_s32_s32_sat'

ImplementationSourceFile — specifies name of implementation source file

'' (default) | character vector | string scalar

The ImplementationSourceFile value specifies the name of the implementation source file. The character vector or string scalar can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'ImplementationSourceFile','s32_mul.c'

ImplementationSourcePath — Specifies path to implementation source file

'' (default) | character vector | string scalar

The ImplementationSourcePath value specifies the full path to the implementation source file. The character vector or string scalar can include tokens. For example, in the token $mytoken$, mytoken is a variable defined as a character vector or string scalar in the MATLAB workspace or as a MATLAB function in the search path that returns a character vector.

Example: 'ImplementationSourcePath', fullfile('$MATLAB_ROOT', 'crl')

ImplType — Specifies whether the table entry is for an implementation function or macro

'FCN_IMPL_FUNCT' (default) | 'FCN_IMPL_MACRO'

The ImplType value specifies the type of table entry. Use FCN_IMPL_FUNCT for function or FCN_IMPL_MACRO for macro.

Example: 'ImplType','FCN_IMPL_FUNCT'

Key — Specifies key for operator to replace

character vector | string scalar

The Key value specifies the key for the operator to replace. The key must match an operator key listed in Code You Can Replace from MATLAB Code or Code You Can Replace From Simulink Models.

Example: 'Key','RTW_OP_ADD'

MustHaveZeroNetBias — Specifies net bias requirement for conceptual arguments of Add/Minus entries

false (default) | true

The MustHaveZeroNetBias value specifies whether a replacement match requires that the net bias for conceptual arguments of Add/Minus entries is zero. For the Add/Minus of fixed-point operator inputs and output this parameter must be set to true. Instantiate the entry by using hEntry = RTW.TflCOperationEntryGenerator rather than hEntry = RTW.TflCOperationEntry.

For Mul/Div/MulDiv/Shift/Cast entries:

• The code generator ignores the value of this argument.

• The bias of the conceptual arguments for Mul/Div/MulDiv/Shift/Cast entries must be zero for a replacement match to occur.

Example: 'MustHaveZeroNetBias',true

NetFixedExponent — Specifies fixed exponent part of net slope for fixed-point conceptual arguments of Mul/Div/MulDiv/Shift/Cast entries

0 (default) | numeric scalar

The NetSlopeAdjustmentFactor value specifies the fixed exponent (E) part of the net slope (F2^E, for example, -3.0) for fixed-point conceptual arguments required for a replacement match to occur for Mul/Div/MulDiv/Shift/Cast entries. Instantiate an entry by using hEntry = RTW.TflCOperationEntryGenerator_NetSlope rather than hEntry = RTW.TflCOperationEntry.

For Add/Minus entries:

• The code generator ignores the value of this argument.

• The slope adjustment factor part of the net slope of the conceptual arguments for Add/Minus entries must be zero for a replacement match to occur.

Example: 'NetFixedExponent', -3.0

NetSlopeAdjustmentFactor — Specifies slope adjustment part of net slope requirement for fixed-point conceptual arguments of Mul/Div/MulDiv/Shift/Cast entries

1 (default) | numeric scalar

The NetSlopeAdjustmentFactor value specifies the slope adjustment part of the net slope (F2^E, for example, 1.0) for fixed-point conceptual arguments required for a replacement match to occur for Mul/Div/MulDiv/Shift/Cast entries. Instantiate an entry by using hEntry = RTW.TflCOperationEntryGenerator_NetSlope rather than hEntry = RTW.TflCOperationEntry.

For Add/Minus entries:

• The code generator ignores the value of this argument.

• The slope adjustment factor part of the net slope of the conceptual arguments for Add/Minus entries must be zero for a replacement match to occur.

Example: 'NetSlopeAdjustmentFactor',1.5

Priority — Specifies the search priority of operator entry

100 (default) | integer value 0..100

The Priority value specifies the search priority of the operation entry, relative to other entries of the same operation name and conceptual argument list within this table. Highest priority is 0, and lowest priority is 100. If the table provides two implementations for an operation, the implementation with the higher priority shadows the one with the lower priority.

Example: 'Priority',100

RoundingModes — Specifies rounding modes supported by implementation function

'RTW_ROUND_UNSPECIFIED' (default) | 'RTW_ROUND_FLOOR' | 'RTW_ROUND_CEILING' | 'RTW_ROUND_ZERO' | 'RTW_ROUND_NEAREST' | 'RTW_ROUND_NEAREST_ML' | 'RTW_ROUND_CONV' | 'RTW_ROUND_SIMPLEST' | array of character vectors | string array

The RoundingModes value specifies one or more rounding modes supported by the implementation function.

Example: 'RoundingModes',{'RTW_ROUND_UNSPECIFIED'}

SaturationMode — specifies saturation mode supported by implementation function

'RTW_SATURATE_UNSPECIFIED' (default) | 'RTW_SATURATE_ON_OVERFLOW' | 'RTW_WRAP_ON_OVERFLOW' | character vector | string scalar

The SaturationMode value specifies the saturation mode supported by the implementation function.

Example: 'SaturationMode','RTW_SATURATE_UNSPECIFIED'

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

SlopesMustBeTheSame — Specifies slope requirement for conceptual arguments of Mul/Div/MulDiv/Shift/Cast entries

false (default) | true

The SlopesMustBeTheSame value specifies whether a replacement match requires that the slope is the same for conceptual arguments of Mul/Div/MulDiv/Shift/Cast entries. Instantiate the entry by using hEntry = RTW.TflCOperationEntryGenerator rather than hEntry = RTW.TflCOperationEntry.

For Add/Minus entries:

• The code generator ignores the value of this argument.

• This parameter must be set to true. When set to true, the slopes of the conceptual arguments are equal for a replacement match to occur.

Example: 'SlopesMustBeTheSame',true

StoreFcnReturnInLocalVar — Specifies whether to store the implementation function regardless expression folding settings

false (default) | true

The StoreFcnReturnInLocalVar value flags the code generator that the return value of the implementation function described by this entry must be stored in a local variable regardless of other expression folding settings. If the value is false, other expression folding settings determine whether the return value is folded. Storing function returns in a local variable can increase the clarity of generated code. This example shows code generated with expression folding:

void sw_step(void)
{
    if (ssub(sadd(sw_U.In1, sw_U.In2), sw_U.In3) <= 
        smul(ssub(sw_U.In4, sw_U.In5),sw_U.In6)) {  
      sw_Y.Out1 = sw_U.In7;  
    } else {
       sw_Y.Out1 = sw_U.In8;  
    }
}

With StoreFcnReturnInLocalVar set to true, the generated code is potentially easier to understand and debug:

void sw_step(void)
{  
    real32_T rtb_Switch;  
    real32_T hoistedExpr;
    ......  
    rtb_Switch = sadd(sw_U.In1, sw_U.In2);
    rtb_Switch = ssub(rtb_Switch, sw_U.In3);
    hoistedExpr = ssub(sw_U.In4, sw_U.In5); 
    hoistedExpr = smul(hoistedExpr, sw_U.In6);  
    if (rtb_Switch <= hoistedExpr) {
       sw_Y.Out1 = sw_U.In7;  
    } else { 
       sw_Y.Out1 = sw_U.In8;  
    }
}

Example: 'StoreFcnReturnInLocalVar',false

Version History

Introduced in R2007b