Embedded MATLAB™

Calling Functions in the Embedded MATLAB™ Subset

How the Embedded MATLAB™ Subset Resolves Function Calls

From an Embedded MATLAB™ function, you can call subfunctions, Embedded MATLAB library functions, and external MATLAB^® functions. Embedded MATLAB resolves function names as follows:

Key Points About Resolving Function Calls

The diagram illustrates key points about how the Embedded MATLAB subset resolves function calls:

• Searches two paths, the Embedded MATLAB path and the MATLAB path

  See Compile Path Search Order.

• Attempts to compile all functions unless you explicitly declare them to be extrinsic

  An extrinsic function is an M-function on the MATLAB path that Embedded MATLAB dispatches to MATLAB software for execution. Embedded MATLAB does not generate code for extrinsic functions. You declare functions to be extrinsic by using the Embedded MATLAB function eml.extrinsic, as described in Declaring MATLAB^® Functions as Extrinsic Functions.

After Embedded MATLAB resolves a function name, it then resolves the file type based on precedence rules described in How the Embedded MATLAB™ Subset Resolves File Types on the Path.

Compile Path Search Order

The Embedded MATLAB subset searches two paths to resolve function calls:

1. Embedded MATLAB path

   Embedded MATLAB searches this path first. The Embedded MATLAB path contains the Embedded MATLAB library functions.

2. MATLAB path

   If Embedded MATLAB does not find the function on the Embedded MATLAB path, it searches the MATLAB path.

Embedded MATLAB applies MATLAB dispatcher rules when searching each path. For more information, see Determining Which Function Gets Called in the MATLAB Programming Fundamentals documentation.

When to Use the Embedded MATLAB™ Path

Use the Embedded MATLAB path to override a MATLAB function with a customized version. Since the Embedded MATLAB subset searches the Embedded MATLAB path first, an M-file on the Embedded MATLAB path always shadows an M-file of the same name on the MATLAB path.

Back to Top

How the Embedded MATLAB™ Subset Resolves File Types on the Path

After Embedded MATLAB resolves function names on a path, it resolves file types on the path using precedence rules as follows:

Back to Top

Adding the Compilation Directive %#eml

To compile an external function, add the %#eml pragma to the Embedded MATLAB function code. Adding this pragma accomplishes two purposes:

• If compilation succeeds, provides a visual cue that the function complies with the Embedded MATLAB subset

• If compilation fails, produces detailed diagnostic messages to help you correct violations of Embedded MATLAB syntax and semantics

If compilation fails and your function code does not contain the %#eml pragma, Embedded MATLAB prompts you to clarify whether you really want to compile the external function or whether you want to dispatch it to MATLAB for execution, as follows:

A Simple Example

Suppose you have an Embedded MATLAB Function block that contains the function example which, in turn, calls the function foo on the MATLAB path. Here is the code for example.m:

function example(u)

foo(u);

Here is the code for foo.m:

function y = foo(u)
y = 0;
for i = 1:u:u
    y = y+i;
end

When you build example.m, the Embedded MATLAB subset tries to compile foo.m based on the heuristic described in How the Embedded MATLAB™ Subset Resolves Function Calls. During compilation, Embedded MATLAB detects errors and generates the following messages:

• Warning:

  Please add an %#eml pragma to 'D:/Work/foo.m' 
  to indicate that this file is intended to be 
  used for Embedded MATLAB.

• Error:

  The function failed to compile, if you intended 
  to compile the file use %#eml directive in 
  'D:/Work/foo.m', however if you wish to call out 
  to matlab use eml.extrinsic('foo') before calling 
  the function.

To continue with compilation, add %#eml to foo.m, shown highlighted below:

%#eml
function y = foo(u)
y = 0;
for i = 1:u:u
    y = y+i;
end

When you build example.m again, you get a more detailed message, explaining the specific syntax violations, as follows:

Back to Top

Calling Subfunctions

Subfunctions are functions defined in the body of an Embedded MATLAB function. They work the same way in Embedded MATLAB functions as they do in MATLAB functions.

The following example illustrates how to define and call a subfunction in an Embedded MATLAB function:

You can include subfunctions for Embedded MATLAB functions just as you would in MATLAB M-file functions. Subfunctions can have multiple arguments and return values, using any types and sizes supported by the Embedded MATLAB subset. See Subfunctions in the MATLAB Programming Fundamentals documentation for more information.

Back to Top

Calling Embedded MATLAB™ Library Functions

You can call Embedded MATLAB library functions directly. The Embedded MATLAB function library is a subset of MATLAB, Fixed-Point Toolbox™, Aerospace Blockset™, and Signal Processing Toolbox™ functions which can be used to generate code. For a list of supported functions appear in Embedded MATLAB™ Function Library Reference.

For more information about fixed-point support, refer to Working with the Fixed-Point Embedded MATLAB™ Subset in the Fixed-Point Toolbox documentation.

Back to Top

Calling MATLAB^® Functions

The Embedded MATLAB subset attempts to compile all MATLAB functions unless you explicitly declare them to be extrinsic (see How the Embedded MATLAB™ Subset Resolves Function Calls). An extrinsic function is a function that is executed by MATLAB software during simulation. Embedded MATLAB does not compile or generate code for extrinsic functions (see How the Embedded MATLAB™ Subset Resolves Extrinsic Functions).

There are two ways to declare a function to be extrinsic:

• Declare the function extrinsic in Embedded MATLAB main functions or subfunctions (see Declaring MATLAB^® Functions as Extrinsic Functions).

• Call the MATLAB function indirectly using feval (see Calling MATLAB^® Functions Using feval).

Declaring MATLAB^® Functions as Extrinsic Functions

To declare a MATLAB function extrinsic, add a declaration at the top of the main Embedded MATLAB function or a subfunction using this syntax:

eml.extrinsic('function_name_1', ... , 'function_name_n');

For example, the following code declares the MATLAB find function extrinsic in the main Embedded MATLAB function foo:

function y = foo

eml.extrinsic('find');

x = ones(4);
y = x;
y = find(x);

When to Use the eml.extrinsic Declaration.   Use the eml.extrinsic declaration to:

• Call MATLAB functions that produce no output — such as plot — for visualizing results during simulation, without generating unnecessary code (see How the Embedded MATLAB™ Subset Resolves Extrinsic Functions).

• Make your code self-documenting and easier to debug. You can scan the source code for eml.extrinsic declarations to isolate calls to MATLAB functions, which can potentially create and propagate mxArrays (see Working with mxArrays).

• Save typing. With one declaration, you ensure that each subsequent function call is extrinsic, as long as the call and the declaration 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).

Rules for Extrinsic Function Declarations.   Observe the following rules when declaring functions extrinsic in the Embedded MATLAB subset:

• You must declare the function extrinsic before you call it.

• You cannot use the extrinsic declaration in conditional statements.

Scope of Extrinsic Function Declarations.   The eml.extrinsic declaration has function scope. For example, consider the following code:

function y = foo 
eml.extrinsic('rat','min');
[N D] = rat(pi);
y = 0;
y = min(N, D);

In this example, the Embedded MATLAB subset interprets the functions rat and min 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 subfunction, as in this example:

  function y = foo 
  eml.extrinsic('rat');
  [N D] = rat(pi);
  y = 0;
  y = mymin(N, D);
   
  function y = mymin(a,b)
  eml.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 subfunction mymin.

• Call the MATLAB function using feval, as described in Calling MATLAB^® Functions Using feval.

Calling MATLAB^® Functions Using feval

The Embedded MATLAB subset automatically interprets the function feval as an extrinsic function. Therefore, you can use feval to conveniently call MATLAB functions from Embedded MATLAB.

Consider the following example:

function y = foo 
eml.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 Embedded MATLAB — which has the same effect as declaring the function min extrinsic for just this one call. By contrast, the function rat is extrinsic throughout the function foo.

How the Embedded MATLAB™ Subset Resolves Extrinsic Functions

The Embedded MATLAB subset resolves extrinsic functions as follows:

For simulation targets, Embedded MATLAB generates code for the call to a MATLAB function, but does not generate the function's internal code. Embedded MATLAB sends the extrinsic function to MATLAB for execution. Therefore, you can run the simulation only on platforms where you install MATLAB software.

For Real-Time Workshop^® and custom targets, Embedded MATLAB attempts to determine whether the extrinsic function affects the output of the Embedded MATLAB function in which it is called — for example by returning mxArrays to an output variable (see Working with mxArrays). If Embedded MATLAB can determine that there is no effect on output, it proceeds with code generation, but excludes the extrinsic function from the generated code. Otherwise, Embedded MATLAB issues a compiler error.

Working with mxArrays

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.

Converting mxArrays to Known Types.   To convert anmxArray to a known type, assign the mxArray to a variable whose type is defined. At run time, the Embedded MATLAB subset converts the mxArray 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, Embedded MATLAB generates an error.

For example, consider this code:

function y = foo 
eml.extrinsic('rat','min');
[N D] = rat(pi);
y = min(N, D);

Here, the top-level Embedded MATLAB 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 extrinsic 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 an Embedded MATLAB Function block in a Simulink^® model, the code generates the following error during simulation:

To correct this problem, declare 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  
eml.extrinsic('rat','min');
[N D] = rat(pi);
y = 0; % y is a scalar of type double
y = min(N,D);

In the next example, an Embedded MATLAB function attempts to use an mxArray in an arithmetic expression:

function z = foo
eml.extrinsic('find');
x = ones(1); % x is a 1-by-1 array of type double 
y = find(x); % y is a 1-by-1 array of type mxArray 
z = x + y;

If you run this function foo in an Embedded MATLAB Function block in a Simulink model, the code generates a compiler error during simulation because it attempts to add the mxArray y to a double array x:

The value y is an mxArray because the code assigns it the mxArray value returned by the extrinsic MATLAB function find. To prevent this error, you must declare y to be the same type and size as x — a 1-by-1 matrix of type double — before assigning y to the return value of find(x), as in this example:

function z = foo
eml.extrinsic('find');
x = ones(1); % x is a 1-by-1 array of type double 
y = ones(1); % y is a 1-by-1 array of type double 
y = find(x); % y returned from find converted to
             % 1-by-1 array of type double  
z = x + y;

Here, the Embedded MATLAB function ones(1) returns a 1-by-1 matrix of type double, thereby converting y to the same type and size as x at run time. Now that y is defined, Embedded MATLAB can convert the mxArray returned by find(x) to a known type — an array of type double — at run time for assignment to y. As a result, the expression z = x + y adds variables of the same type and does not generate an error.

Restrictions on Extrinsic Functions in the Embedded MATLAB™ Subset

As a subset of MATLAB, Embedded MATLAB does not support the full MATLAB run-time environment. Therefore, the Embedded MATLAB subset imposes the following restrictions when calling MATLAB functions extrinsically:

• MATLAB functions that inspect the caller or write to the caller's workspace do not work when the caller is an Embedded MATLAB function, including:

  • dbstack

  • evalin

  • assignin

• The MATLAB debugger cannot inspect variables in Embedded MATLAB functions.

• Embedded MATLAB functions may produce unpredictable results if your extrinsic function performs any of the following actions at run time:

  • Change directories

  • Change the MATLAB path

  • Delete or add M-files

  • Change warning states

  • Change MATLAB preferences

  • Change Simulink parameters

Back to Top

Limit on Function Arguments

You can call functions with up to 64 inputs and 64 outputs.

Back to Top

Embedded MATLAB™ Function Library Reference

Using Structures