Documentation |
The code generation software attempts to generate code for functions, even if they are not supported for C code generation. The software detects calls to many common visualization functions, such as plot, disp, and figure. The software treats these functions like extrinsic functions but you do not have to declare them extrinsic using coder.extrinsic. During simulation, the code generation software generates code for these functions, but does not generate their internal code. During standalone code generation, MATLAB^{®} attempts to determine whether the visualization function affects the output of the function in which it is called. Provided that the output does not change, MATLAB proceeds with code generation, but excludes the visualization function from the generated code. Otherwise, compilation errors occur.
For example, you might want to call plot to visualize your results in the MATLAB environment. If you generate a MEX function from a function that calls plot and then run the generated MEX function, the code generation software dispatches calls to the plot function to MATLAB. If you generate a library or executable, the generated code does not contain calls to the plot function. The code generation report highlights calls from your MATLAB code to extrinsic functions so that it is easy to determine which functions are supported only in the MATLAB environment.
For unsupported functions other than common visualization functions, you must declare the functions (like pause) to be extrinsic (see Resolution of Function Calls for Code Generation). Extrinsic functions are not compiled, but instead executed in MATLAB during simulation (see How MATLAB Resolves Extrinsic Functions During Simulation).
There are two ways to declare a function to be extrinsic:
Use the coder.extrinsic construct in main functions or local functions (see Declaring MATLAB Functions as Extrinsic Functions).
Call the function indirectly using feval (see Calling MATLAB Functions Using feval).
To declare a MATLAB function to be extrinsic, add the coder.extrinsic construct at the top of the main function or a local function:
coder.extrinsic('function_name_1', ... , 'function_name_n');
The following code declares the MATLAB patch function extrinsic in the local function create_plot:
function c = pythagoras(a,b,color) %#codegen % Calculates the hypotenuse of a right triangle % and displays the triangle. c = sqrt(a^2 + b^2); create_plot(a, b, color); function create_plot(a, b, color) %Declare patch and axis as extrinsic coder.extrinsic('patch'); x = [0;a;a]; y = [0;0;b]; patch(x, y, color); axis('equal');
The code generation software detects that axis is not supported for code generation and automatically treats it as an extrinsic function. The compiler does not generate code for patch and axis, but instead dispatches them to MATLAB for execution.
To test the function, follow these steps:
Convert pythagoras to a MEX function by executing this command at the MATLAB prompt:
codegen -report pythagoras -args {1, 1, [.3 .3 .3]}
Click the link to the code generation report and then, in the report, view the MATLAB code for create_plot.
The report highlights the patch and axis functions to indicate that they are supported only within the MATLAB environment.
Run the MEX function by executing this command:
pythagoras_mex(3, 4, [1.0 0.0 0.0]);
MATLAB displays a plot of the right triangle as a red patch object:
Use the coder.extrinsic construct to:
Call MATLAB functions that do not produce output — such as pause — during simulation, without generating unnecessary code (see How MATLAB Resolves Extrinsic Functions During Simulation).
Make your code self-documenting and easier to debug. You can scan the source code for coder.extrinsic statements to isolate calls to MATLAB functions, which can potentially create and propagate mxArrays (see Working with mxArrays).
Save typing. With one coder.extrinsic statement, each subsequent function call is extrinsic, as long as the call and the statement are in the same scope (see Scope of Extrinsic Function Declarations).
Declare the MATLAB function(s) extrinsic throughout the calling function scope (see Scope of Extrinsic Function Declarations). To narrow the scope, use feval (see Calling MATLAB Functions Using feval).
Observe the following rules when declaring functions extrinsic for code generation:
Declare the function extrinsic before you call it.
Do not use the extrinsic declaration in conditional statements.
The coder.extrinsic construct has function scope. For example, consider the following code:
function y = foo %#codegen coder.extrinsic('rat','min'); [N D] = rat(pi); y = 0; y = min(N, D);
In this example, rat and min as treated as extrinsic every time they are called in the main function foo. There are two ways to narrow the scope of an extrinsic declaration inside the main function:
Declare the MATLAB function extrinsic in a local function, as in this example:
function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = 0; y = mymin(N, D); function y = mymin(a,b) coder.extrinsic('min'); y = min(a,b);
Here, the function rat is extrinsic every time it is called inside the main function foo, but the function min is extrinsic only when called inside the local function mymin.
Call the MATLAB function using feval, as described in Calling MATLAB Functions Using feval.
The function feval is automatically interpreted as an extrinsic function during code generation. Therefore, you can use feval to conveniently call functions that you want to execute in the MATLAB environment, rather than compiled to generated code.
Consider the following example:
function y = foo coder.extrinsic('rat'); [N D] = rat(pi); y = 0; y = feval('min', N, D);
Because feval is extrinsic, the statement feval('min', N, D) is evaluated by MATLAB — not compiled — which has the same result as declaring the function min extrinsic for just this one call. By contrast, the function rat is extrinsic throughout the function foo.
MATLAB resolves calls to extrinsic functions — functions that do not support code generation — as follows:
During simulation, MATLAB generates code for the call to an extrinsic function, but does not generate the function's internal code. Therefore, you can run the simulation only on platforms where you install MATLAB software.
During code generation, MATLAB attempts to determine whether the extrinsic function affects the output of the function in which it is called — for example by returning mxArrays to an output variable (see Working with mxArrays). Provided that the output does not change, MATLAB proceeds with code generation, but excludes the extrinsic function from the generated code. Otherwise, MATLAB issues a compiler error.
The output of an extrinsic function is an mxArray — also called a MATLAB array. The only valid operations for mxArrays are:
Storing mxArrays in variables
Passing mxArrays to functions and returning them from functions
Converting mxArrays to known types at run time
To use mxArrays returned by extrinsic functions in other operations, you must first convert them to known types, as described in Converting mxArrays to Known Types.
To convert an mxArray to a known type, assign the mxArray to a variable whose type is defined. At run time, the mxArray is converted to the type of the variable assigned to it. However, if the data in the mxArray is not consistent with the type of the variable, you get a run-time error.
For example, consider this code:
function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = min(N, D);
Here, the top-level function foo calls the extrinsic MATLAB function rat, which returns two mxArrays representing the numerator N and denominator D of the rational fraction approximation of pi. Although you can pass these mxArrays to another MATLAB function — in this case, min — you cannot assign the mxArray returned by min to the output y.
If you run this function foo in a MATLAB Function block in a Simulink^{®} model, the code generates the following error during simulation:
Function output 'y' cannot be of MATLAB type.
To fix this problem, define y to be the type and size of the value that you expect min to return — in this case, a scalar double — as follows:
function y = foo %#codegen coder.extrinsic('rat'); [N D] = rat(pi); y = 0; % Define y as a scalar of type double y = min(N,D);
The full MATLAB run-time environment is not supported during code generation. Therefore, the following restrictions apply when calling MATLAB functions extrinsically:
MATLAB functions that inspect the caller, or read or write to the caller's workspace do not work during code generation. Such functions include:
The MATLAB debugger cannot inspect variables defined in extrinsic functions.
Functions in generated code may produce unpredictable results if your extrinsic function performs the following actions at run time:
Change folders
Change the MATLAB path
Delete or add MATLAB files
Change warning states
Change MATLAB preferences
Change Simulink parameters