Introduction

About Writing C S-Functions

A C MEX S-function must provide information about the function to the Simulink engine during the simulation. As the simulation proceeds, the engine, the ODE solver, and the C MEX S-function 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, the Simulink engine interacts with a C MEX 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. However, the S-function is free to perform the task in each method according to the functionality the S-function implements. For example, the mdlOutputs method must compute the block outputs at the current simulation time. However, the S-function can calculate these outputs in any way that is appropriate for the function. This callback-based API allows you to create S-functions, and hence custom blocks, of any desired functionality.

The set of callback methods that C MEX S-functions can implement is larger than that available for M-file S-functions. See S-Function Callback Methods — Alphabetical List for descriptions of the callback methods that a C MEX S-function can implement. C MEX S-functions are required to implement only a small subset of the callback methods in the S-function API. If your block does not implement a particular feature, such as matrix signals, you are free to omit the callback methods needed 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 the Simulink engine calls when interacting with the S-function. The engine subsequently invokes other S-function methods (all starting with mdl). At the end of a simulation, the engine calls mdlTerminate.

Back to Top

Creating C MEX S-Functions

You can create C MEX S-functions using any of the following approaches:

• Handwritten S-function — You can write a C MEX S-function from scratch. (Example of a Basic C MEX S-Function provides a step-by-step example.) See Templates for C S-Functions for a complete skeleton implementation of a C MEX S-function that you can use as a starting point for creating your own S-functions.

• S-Function Builder — This block builds a C MEX S-function from specifications and code fragments that you supply using a graphical user interface. This eliminates the need for you to write S-functions from scratch. See Building S-Functions Automatically for more information about the S-Function Builder.

• Legacy Code Tool — This utility builds a C MEX S-function from existing C code and specifications that you supply using MATLAB M-code. See Integrating Existing C Functions into Simulink Models with the Legacy Code Tool for more information about integrating legacy C code into Simulink models.

Each of these approaches involves a tradeoff between the ease of writing an S-function and the features supported by the S-function. Although handwritten S-functions support the widest range of features, they can be difficult to write. The S-Function Builder block simplifies the task of writing C MEX S-functions but supports fewer features. The Legacy Code Tool provides the easiest approach to creating C MEX S-functions from existing C code but supports the fewest features. See Selecting an S-Function Implementation for more information on the features and limitations of each of these approaches to writing a C MEX S-function.

Back to Top

Writing S-Functions in C

Building S-Functions Automatically

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit