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.
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:
timestwo
example specifies the actual value of the sample time in the mdlInitializeSampleTimes
routine.
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.
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 | ![]() |