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 example has three parts:

The following sections explain each of these parts.

Defines and Includes

The example starts with the following defines.

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.

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 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:

mdlInitializeSampleTimes

Simulink calls mdlInitializeSampleTimes to set the sample times 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 2, and writes the answer to the output.

The timestwo mdlOutputs method uses a SimStruct macro,

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

For more details, see Data View.

The timestwo mdlOutputs method uses the macro

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

The S-function uses

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 the end of the 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.

Building the Timestwo Example

To incorporate this S-function into Simulink, enter

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.


  Setting the Include Path Templates for C S-Functions