This example shows how to use code replacement libraries to replace operators and functions in the generated code. The MATLAB code described illustrates the replacement capabilities. With each example MATLAB function, the example provides separate MATLAB® files to illustrate the creation of operator and function replacements using a MATLAB® based API and registration of the replacements with MATLAB Coder®.
Using code replacement libraries enables:
Better integration of generated code with external and legacy code, to reduce code size and verification efforts.
The use of target specific function implementations, to optimize performance of the embedded application.
The code replacement capabilities include:
Replacement of math functions with target-specific function implementations.
Replacement of math operations with target-specific function implementations.
Replacement of MATLAB functions with target-specific function implementations.
Specifying build information for compiling and building the replacements with the generated code.
Additional Requirements:*
Embedded Coder
The following code creates a folder in your current working folder (pwd). The new folder will contain the files that are relevant for this example. If you do not want to affect the current folder (or if you cannot generate files in this folder), you should change your working folder.
coderdemo_setup('coderdemo_crl');
Create a table of replacement function entries.
Register a code replacement library consisting of one or more tables using an rtwTargetInfo.m file.
Select the code replacement library using the Hardware pane in the MATLAB Coder Project Settings dialog box or MATLAB Coder configuration object.
Generate code for the MATLAB function with Embedded Coder™.
For more information on these steps, look here.
This example code replacement library replaces '+' and '-' for two input, scalar operations on integer data types when using the codegen command.
For more information on operator replacement, look here. For more information on embeddable C-code generation using MATLAB Coder, look here.
To see the MATLAB file for this example, look here.
Set up the configuration parameters to build and define the operation input type. To see the table definition file, look here.
RTW.TargetRegistry.getInstance('reset'); cfg = coder.config('lib','ecoder',true); cfg.CodeReplacementLibrary = 'Addition & Subtraction Examples'; cfg.GenerateReport = false; cfg.LaunchReport = false; t = int16(2); %#ok<NASGU>
Compile the MATLAB program using the configuration parameters that point to the desired code replacement library and the example input class defined in the previous step as input parameters to the codegen command.
codegen -config cfg addsub_two_int16 -args {t, t};
After compiling, you may want to explore the generated source code. matlab:edit(fullfile(pwd,'codegen','lib','addsub_two_int16','addsub_two_int16.c'))
Code replacement libraries support the replacement of a variety of functions. For a full list of supported functions look here.
For more information on math function replacement, look here.
To see the MATLAB file for this example, look here.
Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, look here.
RTW.TargetRegistry.getInstance('reset'); cfg = coder.config('lib','ecoder',true); cfg.CodeReplacementLibrary = 'Function Replacement Examples'; cfg.GenerateReport = false; cfg.LaunchReport = false; t = single(2); %#ok<NASGU>
Compile the MATLAB program using the configuration parameters that point to the desired code replacement library and the example input class defined in the previous step as input parameters to the codegen command.
codegen -config cfg replace_math_fcns -args {t, t};
After compiling, you may want to explore the generated source code. matlab:edit(fullfile(pwd,'codegen','lib','replace_math_fcns','replace_math_fcns.c'))
Code replacement libraries support replacement of the following matrix operations:
addition, subtraction, multiplication, transposition, conjugate, Hermitian
Supported types include:
single, double
int8, uint8
int16, uint16
int32, uint32
csingle, cdouble
cint8, cuint8
cint16, cuint16
cint32, cuint32
fixed-point integers
mixed types (different type on each input)
For more information on matrix operator replacement, look here.
To see the MATLAB file for this example, look here.
Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, look here.
RTW.TargetRegistry.getInstance('reset'); cfg = coder.config('lib','ecoder',true); cfg.CodeReplacementLibrary = 'Matrix Op Replacement Examples'; cfg.GenerateReport = false; cfg.LaunchReport = false; t = [1.0 2.0; 3.0, 4.0]; %#ok<NASGU>
Compile the MATLAB program using the configuration parameters that point to the desired code replacement library and the example input class defined in the previous step as input parameters to the codegen command.
codegen -config cfg replace_matrix_ops -args {t, t};
After compiling, you may want to explore the generated source code. matlab:edit(fullfile(pwd,'codegen','lib','replace_matrix_ops','replace_matrix_ops.c'))
In addition, some matrix operations can be mapped to Basic Linear Algebra Subroutines (BLAS). The following operations can be mapped to a BLAS Subroutine:
matrix multiplication
matrix multiplication with transpose on single or both inputs
matrix multiplication with Hermitian operation on single or both inputs
To see the MATLAB file for this example, look here.
Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, look here.
RTW.TargetRegistry.getInstance('reset'); cfg = coder.config('lib','ecoder',true); cfg.CodeReplacementLibrary = 'BLAS Replacement Examples'; cfg.GenerateReport = false; cfg.LaunchReport = false; t = [1.0 2.0 3.0; 4.0 5.0 6.0; 7.0 8.0 9.0]; %#ok<NASGU>
Compile the MATLAB program using the configuration parameters that point to the desired code replacement library and the example input class defined in the previous step as input parameters to the codegen command.
codegen -config cfg replace_matrix_ops_blas -args {t, t};
After compiling, you may want to explore the generated source code. matlab:edit(fullfile(pwd,'codegen','lib','replace_matrix_ops_blas','replace_matrix_ops_blas.c'))
Code replacement libraries support the replacement of MATLAB functions with scalar and matrix inputs/outputs for built-in, complex and fixed point data types.
For more information on MATLAB function replacement, look here.
To see the MATLAB file for this example, look here.
Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, look here.
RTW.TargetRegistry.getInstance('reset'); cfg = coder.config('lib','ecoder',true); cfg.CodeReplacementLibrary = 'Coder Replace Examples'; cfg.GenerateReport = false; cfg.LaunchReport = false; t = [1 2; 3 4];
Compile the MATLAB program using the configuration parameters that point to the desired code replacement library and the example input class defined in the previous step as input parameters to the codegen command.
codegen -config cfg coder_replace_fcn -args {t, t};
After compiling, you may want to explore the generated source code. matlab:edit(fullfile(pwd,'codegen','lib','coder_replace_fcn','coder_replace_fcn.c'))
Each entry in a code replacement library table can specify build information such as:
Header file dependencies
Source file dependencies
Additional include paths
Additional source paths
Additional link flags
Additionally, the method RTW.copyFileToBuildDir can be used to locally copy the source and header files specified by an entry. For more information on specifying compilation information, look here.
Remove files and return to original folder
RTW.TargetRegistry.getInstance('reset');
cleanup