Documentation Center

  • Trials
  • Product Updates

Contents

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 MATLAB® 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 MATLAB S-functions. 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.

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. (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 Build 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 code. See Integrate C Functions Using 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 Available S-Function Implementations for more information on the features and limitations of each of these approaches to writing a C MEX S-function.

If you have Simulink Coder™, in addition to the previous three approaches, the Simulink Coder product provides a method for generating a C MEX S-function from a graphical subsystem. If you are new to writing C MEX S-functions, you can build portions of your application in a Simulink subsystem and use the S-function target to convert it to an S-function. The generated files provides insight on how particular blocks can be implemented within an S-function. For details and limitations on using the S-function target, see Generated S-Function Block.

Was this topic helpful?