Writing S-Functions

Chapter 3
Writing S-Functions in C

The following sections explain how to use the C programming language to create S-functions.


Introduction	Overview of writing a C S-function.
Building S-Functions Automatically	How to use the S-Function Builder to generate S-functions automatically from specifications that you supply.
Example of a Basic C MEX S-Function	Illustrates the code needed to create a C S-function.
Templates for C S-Functions	Describes code templates that you can use as startingpoints for writing your own C S-functions.
How Simulink Interacts with C S-Functions	Describes how Simulink interacts with a C S-function. This is information that you need to know in order to create and debug your own C S-functions.
Writing Callback Methods	How to write methods that Simulink calls as it executes your S-function.
Converting Level 1 C MEX S-Functions to Level 2	How to convert S-functions written for earlier releases of Simulink to work with the current version.

Introduction

A C MEX-file that defines an S-Function block must provide information about the model to Simulink during the simulation. As the simulation proceeds, Simulink, the ODE solver, and the MEX-file interact to perform specific tasks. These tasks include defining initial conditions and block characteristics, and computing derivatives, discrete states, and outputs.

As with M-file S-functions, Simulink interacts with a C MEX-file S-function by invoking callback methods that the S-function implements. Each method performs a predefined task, such as computing block outputs, required to simulate the block whose functionality the S-function defines. Simulink defines in a general way the task of each callback. The S-function is free to perform the task according to the functionality it implements. For example, Simulink specifies that the S-function's mdlOutput method must compute that block's outputs at the current simulation time. It does not specify what those outputs must be. This callback-based API allows you to create S-functions, and hence custom blocks, of any desired functionality.

The set of callback methods, hence functionality, that C MEX-files can implement is much larger than that available for M-file S-functions. See S-Function Callback Methods, for descriptions of the callback methods that a C MEX-file S-function can implement. Unlike M-file S-functions, C MEX-files can access and modify the data structure that Simulink uses internally to store information about the S-function. The ability to implement a broader set of callback methods and to access internal data structures allows C-MEX files to implement a wider set of block features, such as the ability to handle matrix signals and multiple data types.

C MEX-file S-functions are required to implement only a small subset of the callback methods that Simulink defines. If your block does not implement a particular feature, such as matrix signals, you are free to omit the callback methods required to implement a feature. This allows you to create simple blocks very quickly.

The general format of a C MEX S-function is shown below.

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

static void mdlInitializeSizes(SimStruct *S)
{
}

<additional S-function routines/code>

static void mdlTerminate(SimStruct *S)
{
}
#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 */
#endif

mdlInitializeSizes is the first routine Simulink calls when interacting with the S-function. Simulink subsequently invokes other S-function methods (all starting with mdl). At the end of a simulation, Simulink calls mdlTerminate.

Note Unlike M-file S-functions, C MEX S-function methods do not each have a flag parameter. This is because Simulink calls each S-function method directly at the appropriate time during the simulation.

Creating C MEX S-Functions

The easiest way to create a C MEX S-function is to use the S-Function Builder (see Building S-Functions Automatically). This tool builds a C MEX S-function from specifications and code fragments that you supply. This eliminates the need for you to build the S-function from scratch. The S-function Builder, however, is limited in the kinds of S-functions that it can build. For example, it cannot build S-functions that have more than one input or output or that must handle data types other than double. You must create such S-functions from scratch.

The following sections provide information on writing C MEX S-functions from scratch:

Example of a Basic C MEX S-Function provides a step-by-step example of how to write a simple S-function from scratch.

Templates for C S-Functions describes a complete skeleton implementation of a C S-function that you can use as a starting point for creating your own S-functions.

Example - Variable Sample Time S-Function Building S-Functions Automatically

Chapter 3Writing S-Functions in C

Chapter 3
Writing S-Functions in C