coder.replace - Replace current MATLAB function implementation with code replacement library function in generated

  code - MATLAB ([original](https://in.mathworks.com/help/ecoder/ref/coder.replace.html)) ([raw](?raw))

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

Syntax

Description

coder.replace([ifNoReplacement](#d126e17545)) 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.

example

Examples

collapse all

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.

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.

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

collapse all

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

Extended Capabilities

Version History

Introduced in R2012b