Documentation

coder.ceval

Call external C/C++ function

Syntax

coder.ceval(cfun_name)
coder.ceval(cfun_name,cfun_arguments)
coder.ceval('-global',cfun_name)
coder.ceval('-global',cfun_name,cfun_arguments)
cfun_return = coder.ceval(___)

Description

example

coder.ceval(cfun_name) executes the external C/C++ function specified by cfun_name. Define cfun_name in an external C/C++ source file or library.

example

coder.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.

By default, coder.ceval passes arguments by value to the C/C++ function whenever C/C++ supports passing arguments by value. To make coder.ceval pass arguments by reference, use the constructs coder.ref, coder.rref, and coder.wref. If C/C++ does not support passing arguments by value, for example, if the argument is an array, coder.ceval passes arguments by reference. If you do not use coder.ref, coder.rref or coder.wref, a copy of the argument can appear in the generated code to enforce MATLAB® semantics for arrays.

example

coder.ceval('-global',cfun_name) executes cfun_name and indicates that cfun_name uses one or more MATLAB global variables. The code generator can then produce code that is consistent with this global variable usage.

coder.ceval('-global',cfun_name,cfun_arguments) executes cfun_name with arguments cfun_arguments and indicates that cfun_name uses one or more MATLAB global variables.

example

cfun_return = coder.ceval(___) executes cfun_name and returns a single scalar value, cfun_return, corresponding to the value that the C/C++ function returns in the return statement. To be consistent with C/C++, coder.ceval can return only a scalar value. It cannot return an array. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

collapse all

Call a C function foo(u) from a MATLAB function from which you intend to generate C code.

Create a C header file foo.h for a function foo that takes two input parameters of type double and returns a value of type double.

#ifdef MATLAB_MEX_FILE
#include <tmwtypes.h>
#else
#include "rtwtypes.h"
#endif

double foo(double in1, double in2);

Write the C function foo.c.

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

double foo(double in1, double in2)
{
  return in1 + in2;
}

Write a function callfoo that calls foo by using coder.ceval.

function y = callfoo  %#codegen
y = 0.0;
if coder.target('MATLAB')
    % Executing in MATLAB, call MATLAB equivalent of
    % C function foo
    y = 10 + 20;
else
    % Executing in generated code, call C function foo
    y = coder.ceval('foo', 10, 20);
end
end

Generate C library code for function callfoo. Pass foo.c and foo.h as parameters to include this custom C function in the generated code. codegen generates C code in the codegen\lib\callfoo subfolder.

codegen -config:lib callfoo foo.c foo.h
double callfoo(void)
{
  /*  Executing in generated code, call C function foo */
  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.

Call a C library function from MATLAB code.

Write a MATLAB function absval.

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

Generate the C library for absval.m by using the -args option to specify the size, type, and complexity of the input parameter.

codegen -config:lib absval -args {0.0}
codegen creates the library absval.lib and header file absval.h in the folder /codegen/lib/absval. It generates the functions absval_initialize and absval_terminate in the same folder.

Write a MATLAB function to call the generated C library functions by using coder.ceval.

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

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

Convert the code in callabsval.m to a MEX function so you can call the C library function absval directly from MATLAB.

codegen -config:mex callabsval codegen/lib/absval/absval.lib...
     codegen/lib/absval/absval.h

Call the C library by running the MEX function from MATLAB:

callabsval_mex

Use the '-global' flag when you call a C function that modifies a global variable.

Write a MATLAB function useGlobal that calls a C function addGlobal. Use the '-global' flag to indicate to the code generator that the C function uses a global variable.

function y = useGlobal()
global g;
t = g;
% compare execution with/without '-global' flag
coder.ceval('-global','addGlobal'); 
y = t;
end

Create a C header file addGlobal.h for the function addGlobal.

void addGlobal(void);

Write the C function addGlobal in the file addGlobal.c. This function includes the header file useGlobal_data.h that the code generator creates when you generate code for the function useGlobal. This header file contains the global variable declaration for g.

#include "addGlobal.h"
#include "useGlobal_data.h"
void addGlobal(void) {
    g++;
}

Generate the MEX function for useGlobal. To define the input to the code generator, declare the global variable in the workspace.

global g;
g = 1;
codegen useGlobal -report addGlobal.h addGlobal.c
y = useGlobal_mex();

With the '-global' flag, the MEX function produces the result y = 1. The '-global' flag indicates to the code generator that the C function possibly modifies the global variable. For useGlobal, the code generator produces this code:

real_T useGlobal(const emlrtStack *sp)
{
  real_T y;
  (void)sp;
  y = g;
  addGlobal();
  return y;
}

Without the '-global' flag, the MEX function produces y = 2. Because there is no indication that the C function modifies g, the code generator assumes that y and g are identical. This C code is generated:

real_T useGlobal(const emlrtStack *sp)
{
  (void)sp;
  addGlobal();
  return g;
}

Input Arguments

collapse all

Name of external C/C++ function to call.

Example: coder.ceval('foo')

Data Types: char | string

Comma-separated list of input arguments in the order that cfun_name requires.

Example: coder.ceval('foo', 10, 20);

Example: coder.ceval('myFunction', coder.ref(x));

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct
Complex Number Support: Yes

Limitations

  • You cannot use coder.ceval on functions that you declare extrinsic with coder.extrinsic.

  • When the LCC compiler creates a library, it adds a leading underscore to the library function names. If the compiler for the library was LCC and your code generation compiler is not LCC, you must add the leading underscore to the function name, for example, coder.ceval('_mylibfun'). If the compiler for a library was not LCC, you cannot use LCC to generate code from MATLAB code that calls functions from that library. Those library function names do not have the leading underscore that the LCC compiler requires.

  • If a property has a get method, a set method, or validators, or is a System object™ property with certain attributes, then you cannot pass the property by reference to an external function. See Passing By Reference Not Supported for Some Properties.

Tips

  • For code generation, before calling coder.ceval, you must specify the type, size, and complexity data type of return values and output arguments.

  • Use coder.ceval only in MATLAB for code generation. coder.ceval generates an error in uncompiled MATLAB code. To determine if a MATLAB function is executing in MATLAB, use coder.target. If the function is executing in MATLAB, call the MATLAB version of the C/C++ function.

Introduced in R2011a

Was this topic helpful?