Simulink - Writing S-Functions

Writing Simulink S-Functions

S-Functions are the mechanism for incorporating generic user-defined functionality into Simulink. They may be written in m-code, C, C++, and Fortran. There is also a deprecated API (Application Program Interface) for writing Ada S-Functions.

Irrespective of the language used to write the S-Function, the code must adhere to a specific API. The API uses an object oriented approach to specifying the block functionality, with seperate methods for intitializing signals, defining and initializing states, terminating the code, and many other aspects of its behaviour.

Each of the following sections gives links to relevant example S-Functions and an overview of the appropriate API.

M-Code S-Functions.
C-Mex S-Functions.

Other tutorials discussing Simulink and its applications for model based design are available on the Software Tutorials page.

M-Code S-Functions

The M-code S-Function examples currently available are,

Generic m-code can be incorporated into a Simulink model using an m-code S-Function. Although m-code S-Functions are somewhat more difficult to write than Embedded MATLAB Function blocks, they enable a much finer control over the way the block works.

The code written must adhere to the m-code S-Function API. The API includes a collection of callbacks and macros that define how the S-Function interfaces with Simulink. Information on the macros can be found in several locations,

There is a basic template file which describes the most commonly used API callbacks and macros. The basic template can be opened by typing the following at the MATLAB command line,
```
>> edit([matlabroot,'toolbox\simulink\blocks\msfuntmpl']);
```
The complete list of callback methods can be viewed in the documentation by typing the following at the MATLAB command line,
```
>> docsearch('Level-2 M-File S-Function Callback Methods']);
```

M-code S-Functions are not directly suitable for code generation using the Simulink Coder (formerly Real-Time Workshop). To generate code from a model containing an m-code S-Function a companion TLC (Target Language Compiler) file must be supplied.

C-Mex S-Functions

The C-Mex S-Function examples currently available are,

Replicating the Continuous Time Integrator

Compiled c-code is incorporated into Simulink using c-mex S-Functions. (The term mex stands for MATLAB executable, which is the mechanism for incorporating C and Fortran into MATLAB.) Writing C-mex S-Functions is (almost unarguably) the most difficult aspect of using Simulink. However, with the added complexity comes (almost) unlimited capabilities.

The code written must adhere to the c-mex S-Function API. The API includes a collection of several hundred macros that are used to define how the S-Function interfaces with Simulink. Information on the macros can be found in several locations,

There is a basic template file which describes the most commonly used API functions and macros. The basic template can be opened by typing the following at the MATLAB command line,
```
>> edit([matlabroot,'\simulink\src\sfuntmpl_basic.c']);
```
There is a more detailed template file which describes many more of the API functions and macros in more detail. The advanced template can be opened by typing the following at the MATLAB command line,
```
>> edit([matlabroot,'\simulink\src\sfuntmpl_doc.c']);
```
The complete list of macros, listed in alphabetical order, can be viewed in the documentation by typng the following at the MATLAB command line,
```
>> docsearch('Simstruct Functions Alphabetical List']);
```

To use a c-mex S-Function the c-code must be compiled. This may be done with any c-compiler as long as the appropriate Simulink include and header files are made available to the compiler. It is typically easier to compile the code from within MATLAB. This is done by typing the following at the MATLAB command line

>> mex S_Function_Name.c

Prior to this MATLAB must be made aware of the compiler being used. This is done by typing

>> mex -setup

at the MATLAB command prompt and following the resulting instructions. This setp only needs to be performed once.

C-mex S-Functions can be used directly with Simulink Coder (formerly Real-Time Workshop) to generate embeddable code from a model, or a TLC (Target Language Compiler) file may be supplied.

This tutorial has discussed topics related to using S-Functions to incorporate custom code into a Simulink model. Other Simulink tutorials are available on the Software Tutorials page.