eml.ceval - Package: eml

Call external C function

Syntax

eml.ceval('cfun_name') eml.ceval('cfun_name', cfun_arguments) cfun_return = eml.ceval('cfun_name') cfun_return = eml.ceval('cfun_name', cfun_arguments)

Description

eml.ceval('cfun_name') executes the external C function specified by the quoted string cfun_name. Define cfun_name in an external C source file or library.

eml.ceval('cfun_name', cfun_arguments) executes cfun_name with arguments cfun_arguments. cfun_arguments is a comma-separated list of input arguments in the order that cfun_name requires.

cfun_return = eml.ceval('cfun_name') executes cfun_name and returns a single scalar value, cfun_return, corresponding to the value that the C function returns in the return statement. To be consistent with C, eml.ceval can return only a scalar value.

cfun_return = eml.ceval('cfun_name', cfun_arguments) executes cfun_name with arguments cfun_arguments and returns cfun_return.

To allow the Embedded MATLAB subset to infer the data type of return values and output arguments, specify their type, size, and complexity before calling eml.ceval.

By default, eml.ceval passes arguments by value to the C function whenever C supports passing arguments by value. To make eml.ceval pass arguments by reference, use the constructs eml.ref, eml.rref, and eml.wref. If C does not support passing arguments by value, for example, if the argument is an array, eml.ceval passes arguments by reference. In this case, if you do not use the eml.ref, eml.rref, and eml.wref constructs, Embedded MATLAB might introduce a copy of the argument in the generated code to enforce MATLAB semantics for arrays.

Use eml.ceval only in Embedded MATLAB code that you have compiled with emlmex or emlc. eml.ceval generates an error in uncompiled M-code. Use eml.target to determine if the MATLAB function is executing in MATLAB. If it is, do not use eml.ceval to call the C function. Instead, call the MATLAB version of the C function.

Examples

Call a C function foo(u) from an Embedded MATLAB function:

Create a C header file foo.h for a function foo that takes two input parameters of type real_T and returns a value of type int32_T.
```
#include <tmwtypes.h>

int32_T foo(real_T in1, real_T in2);
```

Write the C function foo.c.

#include <stdio.h>
#include <stdlib.h>
#include "foo.h"

int32_T foo(real_T in1, real_T in2)
{
  return in1 + in2;
}

Write an M-function callfoo that calls foo using eml.ceval.

function y = callfoo   %#eml
% The directive %#eml declares the function
% to be Embedded MATLAB compliant
y = int32(0); % Constrain the return type to int32_T
if isempty(eml.target)
  % Executing in MATLAB, call MATLAB equivalent of 
  % C function foo
  y = 10 + 20;
else
  % Executing in Embedded MATLAB, call C function foo
  y = eml.ceval('foo', 10, 20);
end

Generate C library code for M-function callfoo, passing foo.c and foo.h as parameters to include this custom C function in the generated code.
```
emlc -T rtw:lib callfoo foo.c foo.h
```
emlc generates C code in the emcprj\rtwlib\callmfoo subfolder.
```
int32_T callfoo(void)
{
    return foo(10.0, 20.0);
}
```
In this case, you have not specified the type of the input arguments, that is, the type of the constants 10 and 20. Therefore, the arguments are implicitly of double-precision, floating-point type by default, because the default type for constants in MATLAB is double.

Cast the input arguments to specify their type explicitly.

y = eml.ceval('foo', int32(10), int32(20));

The generated code is:

int32_T callfoo(void)
{
   return foo(10, 20);
}

Call a C library function from M-code:

Write an M-function absval.

function y = absval(u)   %#eml
y = abs(u);

Generate the C library for absval.m, using the -eg option to specify the size, type, and complexity of the input parameter. emlc creates the library absval.lib and header file absval.h in the folder /emcprj/rtwlib/absval. It also generates the functions absval_initialize and absval_terminate in the same folder.
```
emlc -T rtw:lib absval -eg {0.0}
```

Write an M-function to call the generated C library functions using eml.ceval.

function y = callabsval  %#eml
y = -2.75;
% Check the target. Do not use eml.ceval if callabsval is
% executing in MATLAB
if isempty(eml.target)
  % Executing in MATLAB, call M-function absval
  y = absval(y);
else
  % Executing in Embedded MATLAB. 
  % Call the initialize function before calling the 
  % C function for the first time
  eml.ceval('absval_initialize');

  % Call the generated C library function absval
  y = eml.ceval('absval',y);
  
  % Call the terminate function after
  % calling the C function for the last time
  eml.ceval('absval_terminate');
end

Convert the M-code in callabsval.m to a C MEX function so you can call the C library function absval directly from MATLAB.
```
emlc -T mex callabsval emcprj/rtwlib/absval/absval.lib...
     emcprj/rtwlib/absval/absval.h
```
Call the C library by running the C MEX function from MATLAB.
```
callabsval
```