Write Noninlined S-Function - MATLAB & Simulink (original) (raw)
Main Content
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.hinstead ofmex.horsimulink.c. For the header filecg_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:
mxGetDoublesmxGetEpsmxGetInfmxGetMmxGetNmxGetNaNmxGetPr(Not recommended. UsemxGetDoublesinstead.)mxGetScalarmxGetStringmxIsEmptymxIsFinitemxIsInf
- 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-functionname`_statement. The S-function name that you specify must match the S-function file name. - If possible, use the data types
real_Tandint_Tinstead ofdoubleandint. The data typesreal_Tandint_Tare 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_paramfunction, or theS-function modulesfield of theS-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 toset_paramto 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 anmdlRTW S-function routine.
Use of other functions from the MATLABmatrix.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](https://mdsite.deno.dev/matlab:edit%28fullfile%28matlabroot,'/rtw/c/src/rt%5Fmatrx.h'%29%29) and_`matlabroot`_/rtw/c/src/[rt_matrx.c](https://mdsite.deno.dev/matlab:edit%28fullfile%28matlabroot,'/rtw/c/src/rt%5Fmatrx.c'%29%29)
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 usingmxIsEmpty.