Main Content

coder.replace

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

collapse all in page

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 the 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 may 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 a MATLAB function, calculate, that you want to replace with a custom implementation, replacement_calculate_impl.c, in the generated code.

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)
  p = calculate(in);
  out = exp(p);
end

Create a file named crl_table_calculate.m that 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.

function hLib = crl_table_calculate()

hLib = RTW.TflTable;

%---------- entry: calculate ----------- 
hEnt = RTW.TflCFunctionEntry;
setTflCFunctionEntryParameters(hEnt, ...
  'Key', 'calculate', ...
  'Priority', 100, ...
  'ArrayLayout', 'COLUMN_MAJOR', ...
  'ImplementationName', ...
  'replacement_calculate_impl', ...
  'ImplementationHeaderFile', ...
  'replacement_calculate_impl.h', ...
  'ImplementationSourceFile', ...
  'replacement_calculate_impl.c')
% Conceptual Args

arg = getTflArgFromString(hEnt, 'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEnt, arg);

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

% Implementation Args 

arg = getTflArgFromString(hEnt, 'y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEnt.Implementation.setReturn(arg); 

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

addEntry(hLib, hEnt);

end

Create an rtwTargetInfo file:

function rtwTargetInfo(tr)
% rtwTargetInfo function to register a code 
% replacement library (CRL) 
% for use with codegen

  % Register the CRL defined in local function locCrlRegFcn
  tr.registerTargetInfo(@locCrlRegFcn);

end % End of RTWTARGETINFO

function thisCrl = locCrlRegFcn

  % Instantiate a CRL registry entry
  thisCrl = RTW.TflRegistry;

  % Define the CRL properties
  thisCrl.Name = 'My calculate Example'; 
  thisCrl.Description = 'Demonstration of function replacement';
  thisCrl.TableList = {'crl_table_calculate'};
  thisCrl.BaseTfl = 'C89/C90 (ANSI)';
  thisCrl.TargetHWDeviceType = {'*'};

end % End of LOCCRLREGFCN

Refresh registration information. At the MATLAB command line, enter:

RTW.TargetRegistry.getInstance('reset');

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 the following code:

real_T top_function(real_T in)
{
  real_T p;
  p = replacement_calculate_impl(in);
  return exp(p);
}

In the generated code, the replacement function replacement_calculate_impl replaces the MATLAB function calculate.

Input Arguments

collapse all

The ifNoReplacement argument selects whether the code generator issues an error or warning when no match is found. If this argument is omitted, 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()

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

See Also

Topics