Writing S-Functions

Example of a Basic C MEX S-Function

This section presents an example of a C MEX S-function that you can use as a model for creating simple C S-functions. The example is the timestwo S-function example that comes with Simulink (see matlabroot/simulink/src/timestwo.c). This S-function outputs twice its input.

The following model uses the timestwo S-function to double the amplitude of a sine wave and plot it in a scope.

The block dialog for the S-function specifies timestwo as the S-function name; the parameters field is empty.

The timestwo S-function contains the S-function callback methods shown in this figure.

The contents of timestwo.c are shown below.

This is example has three parts:

• Defines and includes
• Callback implementations
• Simulink (or Real-Time Workshop) interface

The following sections explains each of these parts.

Defines and Includes

The example starts with the following defines.

#define S_FUNCTION_NAME  timestwo
#define S_FUNCTION_LEVEL 2

The first specifies the name of the S-function (timestwo). The second specifies that the S-function is in the level 2 format (for more information about level 1 and level 2 S-functions, see Converting Level 1 C MEX S-Functions to Level 2).

After defining these two items, the example includes simstruc.h, which is a header file that gives access to the SimStruct data structure and the MATLAB Application Program Interface (API) functions.

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

The simstruc.h file defines a a data structure, called the SimStruct, that Simulink uses to maintain information about the S-function. The simstruc.h file also defines macros that enable your MEX-file to set values in and get values (such as the input and output signal to the block) from the SimStruct (see Chapter 10, SimStruct Functions).

Callback Implementations

The next part of the timestwo S-function contains implementations of callback methods required by Simulink.

mdlInitializeSizes.   Simulink calls mdlInitializeSizes to inquire about the number of input and output ports sizes of the ports and any other objects (such as the number of states) needed by the S-function.

The timestwo implementation of mdlInitializeSizes specifies the following size information:

• Zero parameters

This means that the S-function parameters field of the S-functions's dialog box must be empty. If it contains any parameters, Simulink will report a parameter mismatch.

• One input port and one output port

The widths of the input and output ports are dynamically sized. This tells Simulink to multiply each element of the input signal to the S-function by two and to place the result in the output signal. Note that the default handling for dynamically sized S-functions for this case (one input and one output) is that the input and output widths are equal.

• One sample time

The timestwo example specifies the actual value of the sample time in the mdlInitializeSampleTimes routine.

• The code is exception free.

Specifying exception free code speeds up execution of your S-function. Care must be taken when specifying this option. In general, if your S-function isn't interacting with MATLAB, it is safe to specify this option. For more details, see How Simulink Interacts with C S-Functions.

mdlInitializeSampleTimes.   Simulink calls mdlInitializeSampleTimes to set the sample time(s) of the S-function. A timestwo block executes whenever the driving block executes. Therefore, it has a single inherited sample time, SAMPLE_TIME_INHERITED.

mdlOutputs.   Simulink calls mdlOutputs at each time step to calculate a block's outputs. The timestwo implementation of mdlOutputs takes the input, multiplies it by two, and writes the answer to the output.

The timestwo mdlOutputs method uses a SimStruct macro,

InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

to access the input signal. The macro returns a vector of pointers, which must be accessed using

*uPtrs[i]

For more details, see Data View.

The timestwo mdlOutputs method uses the macro

    real_T *y = ssGetOutputPortRealSignal(S,0);

To access the output signal. This macro returns a pointer to an array containing the block's outputs.

The S-function uses

int_T width = ssGetOutputPortWidth(S,0);

to get the width of the signal passing through the block. Finally the S-function loops over the inputs to compute the outputs.

mdlTerminate.   Perform tasks at end of simulation. This is a mandatory S-function routine. However, the timestwo S-function doesn't need to perform any termination actions, so this routine is empty.

Simulink/Real-Time Workshop Interface

At the end of the S-function, specify code that attaches this example to either Simulink or the Real-Time Workshop.

#ifdef MATLAB_MEX_FILE
#include "simulink.c"
#else
#include "cg_sfun.h"
#endif

Building the Timestwo Example

To incorporate this S-function into Simulink, type

mex timestwo.c

at the command line. The mex command compiles and links the timestwo.c file to create a dynamically loadable executable for Simulink's use.

The resulting executable is referred to as a MEX S-function, where MEX stands for "MATLAB EXecutable." The MEX-file extension varies from platform to platform. For example, in Microsoft Windows, the MEX-file extension is .dll.

Writing S-Functions in C

Templates for C S-Functions