Syntax

Description

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.

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.

cfun_return = coder.ceval('cfun_name') 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.

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

coder.ceval('-global','cfun_name',cfun_arguments)

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

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

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. In this case, if you do not use the coder.ref, coder.rref, and coder.wref constructs, a copy of the argument might appear in the generated code to enforce MATLAB^® semantics for arrays.

If you pass a global variable by reference using coder.ref, coder.rref or coder.wref, and the custom C code saves the address of this global variable, use the -global flag to synchronize for the variables passed to the custom C code. Synchronization occurs before and after calls to the custom code. If you do not synchronize global variables under these circumstances and the custom C code saves the address and accesses it again later, the value of the variable might be out of date.

Note:   The -global flag does not apply for MATLAB Function blocks.

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

Use coder.ceval only in MATLAB for code generation. coder.ceval generates an error in uncompiled MATLAB code. Use coder.target to determine if the MATLAB function is executing in MATLAB. If it is, do not use coder.ceval to call the C/C++ function. Instead, call the MATLAB version of the C/C++ function.

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 in a coder.ceval call. 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.

Examples

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

1. 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);
   

2. Write the C function foo.c.

   #include <stdio.h>
   #include <stdlib.h>
   #include "foo.h"
   
   double foo(double in1, double in2)
   {
     return in1 + in2;
   }
   

3. Write a function callfoo that calls foo 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

4. Generate C library code for function callfoo, passing foo.c and foo.h as parameters to include this custom C function in the generated code.

   codegen -config:lib callfoo foo.c foo.h

   codegen generates C code in the codegen\lib\callfoo subfolder.

   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:

1. Write a MATLAB function absval.

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

2. Generate the C library for absval.m, 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 also generates the functions absval_initialize and absval_terminate in the same folder.

3. Write a MATLAB function to call the generated C library functions 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
   

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

5. Call the C library by running the MEX function from MATLAB.

   callabsval_mex

Related Examples

• Return Multiple Values from C Functions

See Also

codegen | coder.extrinsic | coder.opaque | coder.ref | coder.rref | coder.target | coder.wref