Define Code Replacement Library Optimizations - MATLAB & Simulink (original) (raw)

A code replacement library contains one or more code replacement tables. Each table contains one or more code replacement entries. Each entry contains a mapping and entry parameters. The entry maps the conceptual representation of an automatically generated MATLAB or Simulink function to an implementation representation of an optimized C or C++ function. The entry parameters describe additional properties for the code generator to honor during code replacement.

Diagram showing a library that contains tables and each table contains entries. Each entry contains a conceptual representation, implementation representation, and priority.

To define a code replacement library, first define code replacement tables in a customization file. Then, during the registration step, create a code replacement library by selecting tables to include in your library. You can define your code replacement tables both interactively or programmatically using the same work flow.

The interactive and programmatic approaches both follow these 8 steps:

Open the environment.
Create a table.
Create an entry.
Create entry parameters.
Create the conceptual representation.
Create the implementation representation.
Specify build information.
Validate and save.

Interactively Develop a Code Replacement Library

Open the environment.
To interactively create a code replacement library, open the Code Replacement Tool (crtool) from the MATLAB command line with the command:
Create a table.
A code replacement table organizes code replacement entries into groupings that are easier to manage.
To create a code replacement table:
1. From the toolstrip of the Code Replacement tool, click > .
2. In the right pane, name the table and clickApply.
Create an entry.
A code replacement table entry contains entry parameters and a mapping of a conceptual representation that describes a generated function to an implementation representation that describes an optimized implementation of that function.
To create a code replacement entry:
- Click > and click the type of entry that you want to create.
  The new entry appears without a name in the middle pane.
Create entry parameters.
Entry parameters specify optimization and build requirements for the code generator to honor during code replacement. These parameters vary and automatically appear in various sections of the crtool interface depending on the type of function replacement.
To create entry parameters:
- On the right pane, from the Function orOperation drop-down list, select the name of the function you want to replace.
  This selection determines the entry parameters that appear in the crtool.
Create the conceptual representation.
The conceptual representation describes the signature of the function you want to replace. The conceptual representation consists of the function name, return arguments, and parameters. The return arguments are referred to as output arguments, and the parameters are referred to as input arguments. Specify each conceptual argument with a name, I/O type, and, depending on the type of replacement, other properties that appear in the crtool.
To define your conceptual representation:
- In the Conceptual Function orConceptual Operation section, specify the input and output arguments of the function you want the code generator to replace.
Create the implementation representation.
The implementation representation describes the signature of the replacement function defined in the code replacement library. The implementation representation consists of a function name, return arguments, and parameters. Specify each implementation argument with a type, type qualifier, and complexity.
To define your implementation representation:
- In the Implementation Function orOperation Function section of the, specify the input and output arguments for the optimized function defined in the code replacement library.

Specify build information.
Build information provides the code generator with the files to perform function replacement.
To specify build information:

Click the Build Information tab. Specify build information in these fields:

Parameter	Description
Implementation header file	Name of header file required for code replacement.
Implementation source file	Name of source file required for code replacement.
Additional header files/include paths	Name and path of additional header files required for code replacement.
Additional source files/paths	Name and path of additional source files required for code replacement.
Additional object files/paths	Name and path of additional object files required for code replacement.
Additional link flags	Flags the linker needs to generate an executable file for the replacement code.
Additional compile flags	Flags the compiler needs to generate object code for the replacement code.
Copy files to build folder	Flags whether to copy header, source, or object files, which are required to generate replacement code, to the build folder before code generation. If you specify files with Additional header files/include paths or Additional source files/ paths and you copy files, the compiler and utilities such as packNGo might find duplicate instances of files.

Validate and save.
Save your code replacement library with the same name as your code replacement table on your MATLAB path. Saving your library automatically validates unvalidated content.
To validate and save your library:
- From the Code Replacement tool toolstrip, clickSave. Specify a name for the file and save it.

Programmatically Develop a Code Replacement Library

Open the environment.
To programmatically create a code replacement library, open a MATLAB function file. From the MATLAB menu select New >Function.
Create a table.
A code replacement table organizes code replacement entries into groupings that are easier to manage.
To create a code replacement table:
1. Create a function you can use to call your code replacement library table. The function should not have arguments and return a table object.
2. Create a table object with a call to RTW.TflTable.
  function hTable = code_replacement_library_table()
  % Create a function to call code replacement library table
  %% Create a code replacement library table object
  hTable = RTW.TflTable;

end 3. Create an entry.
A code replacement table entry contains entry parameters and a mapping of a conceptual representation of a generated function to the implementation representation of an optimized implementation of that function.
To create a code replacement table:

Identify the type of function you want to replace.
Call the corresponding Entry Function to create an entry in your table.
function hTable = code_replacement_library_table()
% Create a function to call code replacement library table
%% Create a code replacement library table object
hTable = RTW.TflTable;
%% Create a code replacement library entry
% Pick one from list below
hEntry = RTW.TFLCOperationEntry;
hEntry = RTW.TflCFunctionEntry;
hEntry = RTW.TflBlasEntryGenerator;
hEntry = RTW.TflCBlasEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator_NetSlope;
hEntry = RTW.TflCSemaphoreEntry;
hEntry = RTW.TflCFunctionEntryML;
hEntry = RTW.TflCOperationEntryML;
end
Create entry parameters.
Entry parameters specify optimization and build requirements for the code generator to honor during code replacement. These parameters vary depending on the type of function replacement.
To create your entry parameters:
- Call the Set Parameters function that corresponds with the type of function you want to replace identified in the previous step (step 3).
  Each Set Parameter function is shown with the available properties set to their default values. The exact properties and values you need to specify depends on the function you replace. See examples for specific replacement details.
  function hTable = code_replacement_library_table()
  % Create a function to call code replacement library table
  %% Create a code replacement library table object
  hTable = RTW.TflTable;
  %% Create a code replacement library entry
  % Pick one from list below
  hEntry = RTW.TFLCOperationEntry;
  hEntry = RTW.TflCFunctionEntry;
  hEntry = RTW.TflBlasEntryGenerator;
  hEntry = RTW.TflCBlasEntryGenerator;
  hEntry = RTW.TflCOperationEntryGenerator;
  hEntry = RTW.TflCOperationEntryGenerator_NetSlope;
  hEntry = RTW.TflCSemaphoreEntry;
  hEntry = RTW.TflCFunctionEntryML;
  hEntry = RTW.TflCOperationEntryML;
  %% Create entry parameters
  % Pick one from list below
  hEntry.setTflCOperationEntryParameters(...
  'Key', ' ', ...
  'Priority', 100, ...
  'AcceptExprInput', true, ...
  'AdditionalHeaderFiles', {}, ...
  'AdditionalIncludePaths', {}, ...
  'AdditionalLinkObjs', {}, ...
  'AdditionalLinkObjsPaths', {}, ...
  'AdditionalSourceFiles', {}, ...
  'AdditionalSourcePaths', {}, ...
  'AdditionalCompileFlags', {}, ...
  'AdditionalLinkFlags', {}, ...
  'AllowShapeAgnostic', false, ...
  'ArrayLayout', 'COLUMN_MAJOR', ...
  'EntryInfoAlgorithm', 'RTW_CAST_BEFORE_OP', ...
  'GenCallback', ' ', ...
  'ImplementationHeaderFile', ' ', ...
  'ImplementationHeaderPath', ' ', ...
  'ImplementationName', ' ', ...
  'ImplementationSourceFile', ' ', ...
  'ImplementationSourcePath', ' ', ...
  'ImplType', 'FCN_IMPL_FUNCT', ...
  'MustHaveZeroNetBias', false, ...
  'NetFixedExponet', 0, ...
  'NetAdjustmentFactor', 1, ...
  'RoundingModes', 'RTW_ROUND_UNSPECIFIED', ...
  'SaturationMode', 'RTW_SATURATE_UNSPECIFIED', ...
  'SideEffects', false, ...
  'SlopesMustBeTheSame', false, ...
  'StoreFcnReturnInLocalVar', false);
hEntry.setTflCFunctionEntryParameters(...
'Key', ' ', ...
'Priority', 100, ...
'AcceptExprInput', true, ...
'AdditionalHeaderFiles', {}, ...
'AdditionalIncludePaths', {}, ...
'AdditionalLinkObjs', {}, ...
'AdditionalLinkObjsPaths', {}, ...
'AdditionalSourceFiles', {}, ...
'AdditionalSourcePaths', {}, ...
'AdditionalCompileFlags', {}, ...
'AdditionalLinkFlags', {}, ...
'ArrayLayout', 'COLUMN_MAJOR', ...
'EntryInfoAlgorithm', 'RTW_DEFAULT', ...
'GenCallback', ' ', ...
'ImplementationHeaderFile', ' ', ...
'ImplementationHeaderPath', ' ', ...
'ImplementationName', ' ', ...
'ImplementationSourceFile', ' ', ...
'ImplementationSourcePath', ' ', ...
'ImplType', 'FCN_IMPL_FUNCT', ...
'RoundingModes', 'RTW_ROUND_UNSPECIFIED', ...
'SaturationMode', 'RTW_SATURATE_UNSPECIFIED', ...
'SideEffects', false, ...
'StoreFcnReturnInLocalVar', false);

hEntry.setTflCSemaphoreEntryParameters(...
'Key', ' ', ...
'Priority', 100, ...
'AcceptExprInput', true, ...
'AdditionalHeaderFiles', {}, ...
'AdditionalIncludePaths', {}, ...
'AdditionalLinkObjs', {}, ...
'AdditionalLinkObjsPaths', {}, ...
'AdditionalSourceFiles', {}, ...
'AdditionalSourcePaths', {}, ...
'AdditionalCompileFlags', {}, ...
'AdditionalLinkFlags', {}, ....
'GenCallback', ' ', ...
'ImplementationHeaderFile', ' ', ...
'ImplementationHeaderPath', ' ', ...
'ImplementationName', ' ', ...
'ImplementationSourceFile', ' ', ...
'ImplementationSourcePath', ' ', ...
'ImplType', 'FCN_IMPL_FUNCT', ...
'RoundingModes', 'RTW_ROUND_UNSPECIFIED', ...
'SaturationMode', 'RTW_SATURATE_UNSPECIFIED', ...
'SideEffects', false, ...
'StoreFcnReturnInLocalVar', false);

end
Create the conceptual representation.
The conceptual representation describes the signature of the function you want to replace. It consists of the function name, return arguments, and parameters. The return arguments are referred to as output arguments, and the parameters are referred to as input arguments. Specify each conceptual argument with the required properties, and, depending on the type of replacement, other optional properties.
Required properties:
- Name- Defined as y1..yn for output arguments and u1..un for input arguments
- I/O type- Defined asRTW_IO_OUTPUT orRTW_IO_INPUT
  To define your conceptual representation, use one of these approaches:
  
  Approach Function Goal
  
  1 createAndAddConceptualArg Customization and control.If you want to explicitly specify arguments as scalar or matrix and other properties.

Approach	Function	Goal
1	createAndAddConceptualArg	Customization and control.If you want to explicitly specify arguments as scalar or matrix and other properties.

| 2 | getTflArgFromString | Rapid prototyping.If you want to quickly specify arguments with built-in data types. |
Programming approaches are shown with the available properties set to default values. The exact properties and values you need to specify depends on the function you replace. See examples for specific replacement details.
function hTable = code_replacement_library_table()
% Create a function to call code replacement library table
%% Create a code replacement library table object
hTable = RTW.TflTable;
%% Create a code replacement library entry
% Pick one from list below
hEntry = RTW.TFLCOperationEntry;
hEntry = RTW.TflCFunctionEntry;
hEntry = RTW.TflBlasEntryGenerator;
hEntry = RTW.TflCBlasEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator_NetSlope;
hEntry = RTW.TflCSemaphoreEntry;
hEntry = RTW.TflCFunctionEntryML;
hEntry = RTW.TflCOperationEntryML;
%% Create entry parameters
% Pick one from list below
% To view properties, see step 4
hEntry.setTflCOperationEntryParameters( );
hEntry.setTflCFunctionEntryParameters( );
hEntry.setTflCSemaphoreEntryParameters( );
%% Create the conceptual representation
% Approach 1: createAndAddConceptualArg
% arg = createAndAddConceptualArg(hEntry, argType, varargin)
% argType - 'RTW.TflArgNumeric' | 'RTW.TflArgMatrix'
% varargin - 'name', 'value' pairs shown below set to default values,
% includes name and I/O type
% Define Output Arguments
hEntry.createAndAddConceptualArg(...
'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'IsSigned', true, ...
'WordLength', 32, ...
'CheckSlope', true, ...
'CheckBias', true, ...
'DataTypeMode', 'Fixed-point:binary point scaling', ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'Slope', 1, ...
'SlopeAdjustmentFactor', 1.0, ...
'FixedExponent', -15, ...
'Bias', 0.0, ...
'FractionLength', 15, ...
'BaseType', 'double', ...
'DimRange', [2,2]);
% Define Input Arguments
hEntry.createAndAddConceptualArg(...
'RTW.TflArgNumeric', ...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 32, ...
'CheckSlope', true, ...
'CheckBias', true, ...
'DataTypeMode', 'Fixed-point:binary point scaling', ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'Slope', 1, ...
'SlopeAdjustmentFactor', 1.0, ...
'FixedExponent', -15, ...
'Bias', 0.0, ...
'FractionLength', 15, ...
'BaseType', 'double', ...
'DimRange', [2,2]);
% Approach 2: getTflArgFromString
% arg = getTflArgFromString(hEntry, name, I/O type)
% name- y1..yn | u1..un
% I/O type- RTW_IO_OUTPUT | RTW_IO_INPUT
% Define Output Arguments
arg = getTflArgFromString('y1', 'double');
arg.IOType = 'RTW_IO_OUTPUT';
hEntry.addConceptualArg(arg);
% Define Input Arguments
arg = getTflArgFromString('u1', 'double');
arg.IOType = 'RTW_IO_INPUT';
hEntry.addConceptualArg(arg);
end 6. Create the implementation representation.
The implementation representation describes the signature of the replacement function defined by the code replacement library. It consists of the function name, return arguments, and parameters. Specify the implementation arguments with a type, type qualifier, and complexity. After you define your implementation representation, add your completed entry to the code replacement table with a call to the function addEntry.
To define your implementation representation, use one of these approaches:
Programming approaches are shown with the available properties set to their default values. The exact properties and values you need to specify depends on the function you replace. See examples for specific replacement details.
function hTable = code_replacement_library_table()
% Create a function to call code replacement library table
%% Create a code replacement library table object
hTable = RTW.TflTable;
%% Create a code replacement library entry
% Pick one from list below
hEntry = RTW.TFLCOperationEntry;
hEntry = RTW.TflCFunctionEntry;
hEntry = RTW.TflBlasEntryGenerator;
hEntry = RTW.TflCBlasEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator;
hEntry = RTW.TflCOperationEntryGenerator_NetSlope;
hEntry = RTW.TflCSemaphoreEntry;
hEntry = RTW.TflCFunctionEntryML;
hEntry = RTW.TflCOperationEntryML;
%% Create entry parameters
% Pick one from list below
% To view properties, see step 4
hEntry.setTflCOperationEntryParameters( );
hEntry.setTflCFunctionEntryParameters( );
hEntry.setTflCSemaphoreEntryParameters( );
%% Create the conceptual representation
% Approach 1: createAndAddConceptualArg
% arg = createAndAddConceptualArg(hEntry, argType, varargin)
% argType - 'RTW.TflArgNumeric' | 'RTW.TflArgMatrix'
% varargin - 'name', 'value' pairs shown below set to default values,
% includes name and I/O type, to view properties, see step 5
% Define Output Arguments
hEntry.createAndAddConceptualArg( );
% Define Input Arguments
hEntry.createAndAddConceptualArg( );
% Approach 2: getTflArgFromString
% arg = getTflArgFromString(hEntry, name, I/O type)
% name- y1..yn | u1..un
% I/O type- RTW_IO_OUTPUT | RTW_IO_INPUT
% Define Output Arguments
arg = getTflArgFromString('y1', 'double');
arg.IOType = 'RTW_IO_OUTPUT';
hEntry.addConceptualArg(arg);
% Define Input Arguments
arg = getTflArgFromString('u1', 'double');
arg.IOType = 'RTW_IO_INPUT';
hEntry.addConceptualArg(arg);
%% Create the implementation representation
% Approach 1: copyConceptualArgsToImplementation
copyConceptualArgsToImplementation(hEntry);
% Approach 2: createAndSetCImplementation, createAndSetCImplementationArg
% arg = createAndAddImplementation(hEntry, argType,varargin),
% arg = createAndSetCImplementationReturn(hEntry, argType,varargin)
% argType - 'RTW.TflArgNumeric' | 'RTW.TflArgMatrix'
% varargin - 'name', 'value' pairs shown below set to default values,
% includes name and I/O type
% Define Output Arguments
hEntry.createAndSetCImplementationReturn(...
'RTW.TflArgNumeric', ...
'Name', 'y1', ...
'IOType', 'RTW_IO_OUTPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'DataTypeMode', 'Fixed-point:binary point scaling', ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'Slope', 1.0, ...
'SlopeAdjustmentFactor', 1.0, ...
'FixedExponent', -15, ...
'Bias', 0.0, ...
'FractionLength', 15, ...
'Value', 0);

% Define Input Arguments
hEntry.createAndAddImplementationArg(...
'RTW.TflArgNumeric', ...
'Name', 'u1', ...
'IOType', 'RTW_IO_INPUT', ...
'IsSigned', true, ...
'WordLength', 16, ...
'DataTypeMode', 'Fixed-point:binary point scaling', ...
'DataType', 'Fixed', ...
'Scaling', 'BinaryPoint', ...
'Slope', 1.0, ...
'SlopeAdjustmentFactor', 1.0, ...
'FixedExponent', -15, ...
'Bias', 0.0, ...
'FractionLength', 15, ...
'Value', 0);

% Approach 3: getTflArgFromString
% arg = getTflArgFromString(hEntry, name, datatype)
% name- y1..yn | u1..un, datatype - built-in data type
% Define Output arguments
arg = getTflArgFromString(hEntry, 'y1', 'double');
arg.IOType = 'RTW_IO_OUTPUT';
hEntry.Implementation.setReturn(arg);
% Define Input arguments
arg = getTflArgFromString(hEntry, 'u1', 'double', 0);
hEntry.Implementation.addArgument(arg);
% Approach 4: getTflDWorkFromString
% arg = getTflDWorkFromString(hEntry, name, datatype)
% Define arguments
arg = getTflDWorkFromString('d1', 'void*');
hEntry.addDWorkArg(arg);
% Approach 5: createCRLEntry
% tableEntry = createCRLEntry(crTable,conceptualSpecification,implementationSpecification)
% Define code replacement conceptual and implementation arguments
hEntry = createCRLEntry(...
hTable, ...
'conceptualSpecification', ...
'implementationSpecification');
%% Add code replacement library entry to table
hTable.addEntry(hEntry);
end 7. Specify build information.
Specify build information for your code replacement library. Build information provides the code generator with the files required to perform function replacement.
To specify build information:

Specify your build parameters in the Entry Parameters function you defined in step 4 or with the specified functions. Specify build information with the following properties:

Parameter	Description
Implementation header fileSet propertiesImplementationHeaderFile andImplementationHeaderPath.	Name of header file required for code replacement.
Implementation source fileSet propertiesImplementationSourceFile andImplementationSourcePath.	Name of source file required for code replacement.
Additional header files/include pathsFor each file, specify the file name and path in calls to the functions addAdditionalHeaderFile and addAdditionalIncludePath.	Name and path of additional header files required for code replacement.
Additional source files/pathsFor each file, specify the file name and path in calls to the functions addAdditionalSourceFile and addAdditionalSourcePath.	Name and path of additional source files required for code replacement.
Additional object files/pathsFor each file, specify the file name and path in calls to the functions addAdditionalLinkObj and addAdditionalLinkObjPath.	Name and path of additional object files required for code replacement.
Additional link flagsSet the entry property AdditionalLinkFlags to a cell array of character vectors or string array representing the required compile flags.	Flags the linker needs to generate an executable file for the replacement code.
Additional compile flagsSet the entry property AdditionalCompileFlags to a cell array of character vectors or string array representing the required link flags.	Flags the compiler needs to generate object code for the replacement code.
Copy files to build folder.Set propertyGenCallback to'RTW.copyFileToBuildDir'.	Flags whether to copy header, source, or object files, which are required to generate replacement code, to the build folder before code generation.If a match occurs for a table entry, a call to the functionRTW.copyFileToBuildDir copies required files to the build folder.If the configuration parameterDataTypeReplacement is set to'CDataTypesFixedWidth', the function replaces Simulink® Coder™ data types in the copied files with data types from the C99 language standard.If you specify files with Additional header files/include paths or Additional source files/ paths and you copy files, the compiler and utilities such aspackNGo might find duplicate instances of files.

If an entry uses header, source, or object files, consider whether to make the files accessible to the code generator. You can copy files to the build folder or you can specify individual file names and paths explicitly.
If you specify additional header files/include paths or source files/paths and you copy files, the compiler and utilities such as packNGo might find duplicate instances of files (an instance in the build folder and an instance in the original folder).
If you choose to copy files to the build folder and you are using thepackNGo function to relocate static and generated code files to another development environment:
* In the call to packNGo, specify the property-value pair 'minimalHeaders' true (the default). That setting instructs the function to include the minimal header files required to build the code in the zip file.
* Do not collocate files that you copy with files that you do not copy. If the packNGo function finds multiple instances of the same file, the function returns an error.
If you use the programming interface, paths that you specify can include tokens. A token is a variable defined as a character vector, cell array of character vectors, or string array in the MATLAB® workspace that you enclose with dollar signs ($variable$). The code generator evaluates and replaces a token with the defined value. For example, consider the path $myfolder$\folder1, wheremyfolder is a character vector or string scalar variable defined in the MATLAB workspace as 'd:\work\source\module1'. The code generator generates the custom path asd:\work\source\module1\folder1.

Validate and save.
Save your code replacement library customization file with the same name as your code replacement library table on your MATLAB path.
To save and validate your library:
1. Save your file. From the MATLAB menu, select File > Save.
2. Validate your library by calling it from the MATLAB command line. For example:
  
  hTable = code_replacement_library_table()

Define Code Replacement Library Optimizations - MATLAB & Simulink (original) (raw)

Interactively Develop a Code Replacement Library

Programmatically Develop a Code Replacement Library

See Also

Topics