Write Noninlined S-Function

A noninlined S-function is a C or C++ MEX S-function that is treated identically by the Simulink® engine and by the generated code. You implement your algorithm once according to the S-function API. The Simulink engine and generated code call the S-function routines (for example, mdlOutputs) during model execution.

Noninlined S-functions are identified by the absence of an sfunction.tlc file for your S-function. The file name varies depending on your platform. For example, on a 64-bit Microsoft® Windows® system, the file name is sfunction.mexw64. In the MATLAB® Command Window, type mexext to see which extension your system uses.

Guidelines for Writing Noninlined S-Functions

  • The MEX-file cannot call MATLAB functions.

  • If the MEX-file uses functions in the MATLAB External Interface libraries, include the header file cg_sfun.h instead of mex.h or simulink.c. For the header file cg_sfun.h, at the end of your S-function, include these lines:

    #ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */
#include "simulink.c"  /* MEX-file interface mechanism */
#else
#include "cg_sfun.h"   /* Code generation registration function */
#endif

  • Use only the MATLAB API function that the code generator supports. The supported API functions are:

    • mxGetDoubles

    • mxGetEps

    • mxGetInf

    • mxGetM

    • mxGetN

    • mxGetNaN

    • mxGetPr (Not recommended. Use mxGetDoubles instead.)

    • mxGetScalar

    • mxGetString

    • mxIsEmpty

    • mxIsFinite

    • mxIsInf

  • MEX library calls are not supported in generated code. To use such calls in the MEX-file and not in the generated code, add the following condition:

    #ifdef MATLAB_MEX_FILE
#endif

  • Use only full matrices that contain only real data.

  • Do not specify a return value for calls to mxGetString. If you do specify a return value, the MEX-file does not compile. Instead, use the second input argument of the function, which returns a pointer to a character vector.

  • Use the correct #define s-function_name statement. The S-function name that you specify must match the S-function file name.

  • If possible, use the data types real_T and int_T instead of double and int. The data types real_T and int_T are more generic and can be used in multiple environments.

  • Provide the build process with the names of the modules used to build the S-function. Use a template make file, the set_param function, or the S-function modules field of the S-Function block parameters dialog box. For example, suppose that you build your S-function with this command:

    mex sfun_main.c sfun_module1.c sfun_module2.c

    You can then use the following call to set_param to include the required modules:

    set_param(sfun_block, "SFunctionModules","sfun_module1 sfun_module2")

    When you are ready to generate code, force the code generator to rebuild the top model. For more information, see Control Regeneration of Top Model Code.

Noninlined S-Function Parameter Type Limitations

Parameters to noninlined S-functions can be of the following types only:

  • Double precision

  • Characters in scalars, vectors, or 2-D matrices

For more flexibility in the type of parameters that you can supply to S-functions or the operations in the S-function, inline your S-function and consider using an mdlRTW S-function routine.

Use of other functions from the MATLAB matrix.h API or other MATLAB APIs, such as mex.h and mat.h, are not supported. If you call unsupported APIs from an S-function source file, compiler errors occur. For details on supported MATLAB API functions, see the files matlabroot/rtw/c/src/rt_matrx.h and matlabroot/rtw/c/src/rt_matrx.c

If you use mxGetPr on an empty matrix, the function does not return NULL. It returns a random value. Therefore, you must protect calls to mxGetPr by using mxIsEmpty.

See Also

Topics