coder.replace

Replace current MATLAB function implementation with code replacement library function in generated code

Syntax

coder.replace(ifNoReplacement)

Description

coder.replace(ifNoReplacement) replaces the current function implementation with a code replacement library function.

During code generation, when you call coder.replace in a MATLAB^® function, the code generator performs a code replacement library lookup for this function signature:

[y1_type,y2_type,...,yn_type]=fcn(x1_type,x2_type,...,xn_type)

The input data types are x1_type, x2_type,...,xn_type and the output types, derived from the implementation, are y1_type, y2_type,..., yn_type. If a match for the MATLAB function is found in a registered code replacement library, the contents of the MATLAB function are discarded and replaced with a call to the code replacement library function. If a match is not found, the code generates without replacement.

coder.replace only affects code generation and does not alter MATLAB code or MEX function generation. coder.replace is intended to replace a MATLAB function that has behavior equivalent to its replacement function implementation. If the MATLAB function body is empty or not equivalent to the replacement function implementation, it might be eliminated from the generated code. The MATLAB function prior to replacement is used for simulation. You are responsible for verifying the numeric result of simulation and code generation after replacement.

Examples

Replace a MATLAB Function with Custom C Code

Replace a MATLAB function with a custom implementation that is registered in the code replacement library.

Write MATLAB Function

Write a MATLAB function that you want to replace with a custom implementation, repalcement_calculate_impl.c. In the MATLAB function, call coder.replace. For example, use the function calculate.

type calculate.m

function y = calculate(x)
% Search in the code replacement library for replacement
% and use replacement function if available
% Error if not found
  coder.replace('-errorifnoreplacement');
  y = sqrt(x);
end

Write a MATLAB function, top_function, that calls calculate.

type top_function.m

function out = top_function(in)
arguments
    in (1,1) double
end
  p = calculate(in);
  out = exp(p);
end

Create and Register Code Replacement Library

The code replacement library file crl_matlab_fcn_coder_replace.m describes the function entries for a code replacement table. The replacement function replacement_calculate_impl.c and header file replacement_calculate_impl.h must be on the path.

type crl_matlab_fcn_coder_replace.m

function hTable = crl_matlab_fcn_coder_replace
% Create a function to call the code replacement library table 

%% Create a table object
hTable = RTW.TflTable;

%% Create an entry
hEntry = RTW.TflCFunctionEntry;

%% Create entry parameters
setTflCFunctionEntryParameters(hEntry, ...
  'Key','calculate', ...
  'Priority',100, ...
  'ArrayLayout','COLUMN_MAJOR', ...
  'ImplementationName', ...
  'replacement_calculate_impl', ...
  'ImplementationHeaderFile', ...
  'replacement_calculate_impl.h', ...
  'ImplementationSourceFile', ...
  'replacement_calculate_impl.c');

%% Create the conceptual representation
arg = getTflArgFromString(hEntry,'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEntry,arg);

arg = getTflArgFromString(hEntry,'u1','double');
addConceptualArg(hEntry,arg);

%% Create the implementation representation
arg = getTflArgFromString(hEntry,'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEntry.Implementation.setReturn(arg); 

arg = getTflArgFromString(hEntry,'u1','double');
hEntry.Implementation.addArgument(arg);

%% Add the entry to the table
hTable.addEntry(hEntry);

An rtwTargetInfo file registers the code replacement table. For example, use the content from the file RTWTargetInfo-coder-replace.txt. To refresh the registration information, call sl_refresh_customizations.

copyfile RTWTargetInfo-coder-replace.txt rtwTargetInfo.m
sl_refresh_customizations

Apply Code Replacement Library and Generate Code

Create a library code generation configuration and use it to specify the code replacement library that you created.

configObj = coder.config('lib');
configObj.CodeReplacementLibrary = "CRL for matlab function with custom code using coder.replace";

Generate the code by using the code generation configuration.

codegen top_function.m -config configObj -c

Code generation successful.

Because the data type of x and y is double, coder.replace searches for double = calculate(double) in the Code Replacement Library. If it finds a match, codegen generates code in which the replacement function replacement_calculate_impl replaces the MATLAB function calculate.

file = fullfile("codegen/lib/top_function","top_function.c");
coder.example.extractLines(file,"double top_function(double in)","}",1,1);

double top_function(double in)
{
  return exp(replacement_calculate_impl(in));
}

Input Arguments

ifNoReplacement — Option to produce a warning or error when no match is found

'-errorifnoreplacement' | '-warnifnoreplacement'

Option to produce an error or warning when no match is found, specified as '-errorifnoreplacement' or '-warnifnoreplacement'. If you do not specify this argument, the code generator does not issue an error or warning.

coder.replace('-errorifnoreplacement') replaces the current function implementation with a code replacement library function. If a match is not found, code generation stops. An error message describing the code replacement library lookup failure is generated.

coder.replace('-warnifnoreplacement') replaces the current function implementation with a code replacement library function. If match is not found, code is generated for the current function. A warning describing the code replacement library lookup failure is generated during code generation.

Example: coder.replace('-errorifnoreplacement')

Tips

• coder.replace requires an Embedded Coder^® license.

• coder.replace is a code generation function and does not alter MATLAB code or MEX function generation.

• coder.replace is not intended to be called multiple times within a function.

• coder.replace is not intended to be used within conditional expressions and loops.

• coder.replace does not support saturation and rounding modes during code replacement library lookups.

• coder.replace does not support varargout.

• coder.replace does not support function replacement that requires data alignment.

• coder.replace does not support function replacement of MATLAB functions with variable-size inputs.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2012b