Templates for C S-Functions

About the Templates for C S-Functions

Use one of the provided C MEX S-function templates as a starting point for creating your own S-function. The templates contain skeleton implementations of callback methods with comments that explain their use. The template file, sfuntmpl_basic.c, contains commonly used S-function routines. A template containing all available routines (as well as more comments) can be found in sfuntmpl_doc.c in the same folder.

Note

We recommend that you use the C MEX file template when developing MEX S-functions.

S-Function Source File Requirements

This section describes requirements that every S-function source file must meet to compile correctly. The S-function templates meet these requirements.

Statements Required at the Top of S-Functions

For S-functions to operate properly, each source module of your S-function that accesses the SimStruct must contain the following sequence of defines and include

#define S_FUNCTION_NAME your_sfunction_name_here
#define S_FUNCTION_LEVEL 2
#include "simstruc.h"

where your_sfunction_name_here is the name of your S-function (i.e., what you enter in the S-Function Block Parameters dialog box). These statements give you access to the SimStruct data structure that contains pointers to the data used by the simulation. The included code also defines the macros used to store and retrieve data in the SimStruct, described in detail in Convert Level-1 C MEX S-Functions. In addition, the code specifies that you are using the Level-2 S-function format.

Note

All S-functions from Simulink^® version 1.3 through version 2.1 are considered to be Level-1 S-functions. They are compatible with newer versions of the software, but we recommend that you write new S-functions in the Level-2 format.

The following headers are included by simstruc.h when compiling as a MEX file.

Header Files Included by simstruc.h When Compiling as a MEX File

Header File	Description
`matlabroot/extern/include/tmwtypes.h`	General data types, e.g., `real_T`
`matlabroot/simulink/include/simstruc_types.h`	`SimStruct` data types, e.g., `DTypeId`
`matlabroot/extern/include/mex.h`	MATLAB^® MEX file API routines to interface MEX files with the MATLAB environment
`matlabroot/extern/include/matrix.h`	MATLAB External Interface API routines to query and manipulate MATLAB matrices

When compiling your S-function for use with the Simulink Coder™ product, simstruc.h includes the following.

Header Files Included by simstruc.h When Used by the Simulink Coder Product

Header File	Description
`matlabroot/extern/include/tmwtypes.h`	General types, e.g., `real_T`
`matlabroot/simulink/include/simstruc_types.h`	`SimStruct` data types, e.g., `DTypeId`
`matlabroot/rtw/c/src/rt_matrx.h`	Macros for MATLAB API routines

Callback Methods That an S-Function Must Implement

Your S-function must implement the following functions (see Configure C/C++ S-Function Features ):

mdlInitializeSizes specifies the sizes of various parameters in the SimStruct, such as the number of output ports for the block.
mdlInitializeSampleTimes specifies the sample time(s) of the block.
mdlOutputs calculates the output of the block.
mdlTerminate performs any actions required at the termination of the simulation. If no actions are required, this function can be implemented as a stub.

Statements Required at the Bottom of S-Functions

Your S-function must include the following trailer code at the end of the main module only.

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

These statements select the appropriate code for your particular application:

simulink.c is included if the file is being compiled into a MEX- file.
cg_sfun.h is included if the file is being used with the Simulink Coder product to produce a standalone or real-time executable.
Note
This trailer code must not be in the body of any S-function routine.

The SimStruct

The file simstruc.h is a C language header file that defines the SimStruct data structure and its access macros. It encapsulates all the data relating to the model or S-function, including block parameters and outputs.

There is one SimStruct data structure allocated for the Simulink model. Each S-function in the model has its own SimStruct associated with it. The organization of these SimStructs is much like a folder tree. The SimStruct associated with the model is the root SimStruct. Any SimStruct associated with an S-function is a child SimStruct.

The Simulink product provides a set of macros that S-functions can use to access the fields of the SimStruct. See About SimStruct Functions for more information.

Data Types in S-Functions

The file tmwtypes.h is a C language header file that defines a set of data types used in the S-function template and in the SimStruct. These data types, such as real_T, uint32_T, etc., provide a way to switch between different data types for 16, 32, and 64 bit systems, allowing greater platform independence and flexibility.

S-functions are not required to use these data types. For example, you can edit the example csfunc.c and change real_T to double and int_T to int. If you compile and simulate the S-function, the results will be identical to the results using the previous data types.

Compiling C S-Functions

Your S-function can be compiled in one of three modes, defined either by the mex command or by the Simulink Coder product when the S-function is built:

MATLAB_MEX_FILE — Indicates that the S-function is being built as a MEX file for use with the Simulink product.
RT — Indicates that the S-function is being built with the Simulink Coder product for a real-time application using a fixed-step solver.
NRT — Indicates that the S-function is being built with the Simulink Coder product for a non-real-time application using a variable-step solver.

The build process you use automatically defines the mode for your S-function.