S-functions (system-functions) provide a powerful mechanism for extending the
capabilities of the Simulink® environment. An
S-function is a computer language description of a Simulink block written in MATLAB®, C, C++,
or Fortran. C, C++, and Fortran S-functions are compiled as MEX files using the
mex utility (see Build MEX File (MATLAB)). As with other MEX
files, S-functions are dynamically linked subroutines that the MATLAB execution engine can automatically load and execute.
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.
S-functions follow a general form and can accommodate continuous, discrete, and hybrid systems. By following a set of simple rules, 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 (see Create Block Masks).
If you have Simulink Coder™, you can use S-functions with the software. You can also customize the code generated for S-functions by writing a Target Language Compiler (TLC) file. For more information, see S-Functions and Code Generation (Simulink Coder).
To create S-functions, you need to understand how S-functions work. Such knowledge requires an understanding of how the Simulink engine simulates a model, including the mathematics of blocks. This section begins by explaining the mathematical relationships between the inputs, states, and outputs of a block.
A Simulink block consists of a set of inputs, a set of states, and a set of outputs, where the outputs are a function of the simulation time, the inputs, and the states.
The following equations express the mathematical relationships between the inputs, outputs, states, and simulation time
Execution of a Simulink model proceeds in stages. First comes the initialization phase. In this phase, the Simulink engine incorporates library blocks into the model, propagates signal widths, data types, and sample times, evaluates block parameters, determines block execution order, and allocates memory. The engine then enters a simulation loop, where each pass through the loop is referred to as a simulation step. During each simulation step, the engine executes each block in the model in the order determined during initialization. For each block, the engine invokes functions that compute the block states, derivatives, and outputs for the current sample time.
The following figure illustrates the stages of a simulation. The inner integration loop takes place only if the model contains continuous states. The engine executes this loop until the solver reaches the desired accuracy for the state computations. The entire simulation loop then continues until the simulation is complete. See Simulation Phases in Dynamic Systems in Using Simulink for more detailed information on how the engine executes a model. See Simulink Engine Interaction with C S-Functions for a description of how the engine calls the S-function API during initialization and simulation.
How the Simulink Engine Performs Simulation
An S-function comprises a set of S-function callback methods that perform tasks required at each simulation stage. During simulation of a model, at each simulation stage, the Simulink engine calls the appropriate methods for each S-Function block in the model. Tasks performed by S-function callback methods include:
Initialization — Prior to the first simulation loop, the engine initializes the S-function, including:
SimStruct, a simulation
structure that contains information about the S-function
Setting the number and dimensions of input and output ports
Setting the block sample times
Allocating storage areas
Calculation of next sample hit — If you created a variable sample time block, this stage calculates the time of the next sample hit; that is, it calculates the next step size.
Calculation of outputs in the major time step — After this call is complete, all the block output ports are valid for the current time step.
Update of discrete states in the major time step — In this call, the block performs once-per-time-step activities such as updating discrete states.
Integration — This applies to models with continuous states and/or nonsampled zero crossings. If your S-function has continuous states, the engine calls the output and derivative portions of your S-function at minor time steps. This is so the solvers can compute the states for your S-function. If your S-function has nonsampled zero crossings, the engine also calls the output and zero-crossings portions of your S-function at minor time steps so that it can locate the zero crossings.
See Simulation Phases in Dynamic Systems for an explanation of major and minor time steps.