S-Function
Include S-function in model
Libraries:
Simulink /
User-Defined Functions
Description
The S-Function block allows you to integrate your S-function or system function algorithms written in C, C++, or Fortran®, known as C MEX S-functions, into Simulink models. You can use the block to implement Level-1 or Level-2 C MEX S-functions. To incorporate your S-function in a model, after you compile your C MEX S-function:
Drag an S-function block from the Simulink Library Browser to your model.
Open up the Block Parameters dialog box and specify the S-function name at the S-function name field to provide functionality for the S-function block. For example, type
timestwoand select Apply.
An S-function is a computer language description of a Simulink® block written in MATLAB®, C, C++, or Fortran. If you have C, C++, or Fortran S-functions, they need to be compiled as MEX files using the
mex utility (see Build C MEX Function). S-functions
define how a block works during different parts of simulation, such as initialization,
update, derivatives, outputs and termination. S-functions use a special calling syntax
called the S-function API that enables you to interact with the Simulink engine. This interaction is very similar to the interaction that takes
place between the engine and built-in Simulink blocks. In every step of a simulation, a method is invoked by the
simulation engine to fulfill a specific task.
For example, below is an example of a simple C MEX S-function called
timestwo.c that outputs twice its input.
#define S_FUNCTION_NAME timestwo /* Specifies the name of the S-function (timestwo) */
#define S_FUNCTION_LEVEL 2 /* Specifies that the S-function is in the Level 2 format */
#include "simstruc.h" /* Defines the data structure */
static void mdlInitializeSizes(SimStruct *S) /* Initialize the input and output ports and their size */
{
ssSetNumSFcnParams(S, 0);
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
return; /* Parameter mismatch reported by the Simulink engine*/
}
if (!ssSetNumInputPorts(S, 1)) return;
ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED);
ssSetInputPortDirectFeedThrough(S, 0, 1);
if (!ssSetNumOutputPorts(S,1)) return;
ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED);
ssSetNumSampleTimes(S, 1);
/* Take care when specifying exception free code - see sfuntmpl.doc */
ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
}
static void mdlInitializeSampleTimes(SimStruct *S) /* Set the sample time of the S-function as inherited */
{
ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}
static void mdlOutputs(SimStruct *S, int_T tid) /* Calculate the block output for each time step */
{
int_T i;
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
real_T *y = ssGetOutputPortRealSignal(S,0);
int_T width = ssGetOutputPortWidth(S,0);
for (i=0; i<width; i++) {
*y++ = 5.0 *(*uPtrs[i]);
}
}
static void mdlTerminate(SimStruct *S){} /* Perform tasks at the end of the simulation */
#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 */
#endifS-functions follow a general form and can accommodate continuous, discrete, and hybrid
systems. You can implement an algorithm in an S-function and use the S-Function block to
add it to a Simulink model. After you write your S-function and place its name in an S-Function
block (available in the User-Defined Functions block library), you can customize the
user interface using masking. In this example, the timestwo.c
function is compiled using mex timestwo.c, and it is implemented
using the S-Function block.
The S-Function block displays the name of the specified S-function and the number of input and output ports specified by the S-function. Signals connected to the inputs must have the dimensions specified by the S-function for the inputs.
Note
Use the Level-2 MATLAB S-Function block to include a Level-2 MATLAB S-function in a block diagram.
Examples
Inverted Pendulum with Animation
Use Simulink® to model and animate an inverted pendulum system. An inverted pendulum has its center of mass above its pivot point. To stably maintain this position, the system implements control logic to move the pivot point below the center-of mass as the pendulum starts to fall. The inverted pendulum is a classic dynamics problem used to test control strategies.
Custom Code and Hand Coded Blocks Using the S-Function API
This library launches examples of different types of Simulink® S-functions. Simulink S-functions allow you to extend Simulink with new hand coded blocks, interface to custom external code, and create live interfaces to other programs. Use this example to access models containing S-functions in C, C++, M, and Fortran®.
Ports
Input
Output
Parameters
Block Characteristics
Extended Capabilities
Version History
Introduced before R2006a
