%% Replacing Math Functions and Operators
% 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
%% Steps for Using a Code Replacement Library
% 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.
%% Addition and Subtraction Operator Replacement in the MATLAB Coder Product
% 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, open addsub_two_int_16.m.
%% Set MATLAB Coder to Use the Code Replacement Library
% Set up the configuration parameters to build and define the operation input type. To see the table definition file, open crl_table_addsub.m. Because an rtwTargetInfo.m file may already exist on the path, this example creates a new file from a different name.

copyfile myRtwTargetInfoCRL.txt rtwTargetInfo.m 
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 into a C Source File
% 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};

%
%% Inspect the MATLAB Coder Generated Code
% After compiling, you may want to explore the generated source code.

type codegen/lib/addsub_two_int16/addsub_two_int16.c

%% Math Function Replacement
% 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, open replace_math_fcns.m.
%% Set MATLAB Coder to Use the Code Replacement Library
% Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, open crl_table_functions.m.

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 into a C Source File
% 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};

%
%% Inspect the MATLAB Coder Generated Code
% After compiling, you may want to explore the generated source code.

type codegen/lib/replace_math_fcns/replace_math_fcns.c

%% Matrix Operator Replacement
% 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, open replace_matrix_ops.m.
%% Set MATLAB Coder to Use the Code Replacement Library
% Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, open crl_table_matops.m.

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 into a C Source File
% 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};

%
%% Inspect the MATLAB Coder Generated Code
% After compiling, you may want to explore the generated source code.

type codegen/lib/replace_matrix_ops/replace_matrix_ops.c

%% BLAS Support
% 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, open replace_matrix_ops_blas.m.
%% Set MATLAB Coder to Use the Code Replacement Library
% Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, open crl_table_blas.m.

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 into a C Source File
% 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};

%
%% Inspect the MATLAB Coder Generated Code
% After compiling, you may want to explore the generated source code.

type codegen/lib/replace_matrix_ops_blas/replace_matrix_ops_blas.c

%% MATLAB Function Replacement Using Coder.Replace
% 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, open coder_replace_fcn.m.
%% Set MATLAB Coder to Use the Code Replacement Library
% Set up the configuration parameters to build and define the function input type. To see the code replacement table definition file, open crl_table_coder_replace.m.

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 into a C Source File
% 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};

%
%% Inspect the MATLAB Coder Generated Code
% After compiling, you may want to explore the generated source code.

type codegen/lib/coder_replace_fcn/coder_replace_fcn.c

%% Build Support
% 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.
%% Cleanup

delete ./rtwTargetInfo.m
RTW.TargetRegistry.getInstance('reset');

% Copyright 2018 The MathWorks, Inc.
%