| Writing S-Functions | |
Implementing S-Functions
You can implement an S-function as either an M-file or a MEX file. The following sections describe these alternative implementations and discuss the advantages of each.
M-File S-Functions
An M-file S-function consists of a MATLAB function of the following form:
where f is the S-function's name, t is the current time, x is the state vector of the corresponding S-function block, u is the block's inputs, flag indicates a task to be performed, and p1, p2, ... are the block's parameters. During simulation of a model, Simulink repeatedly invokes f, using flag to indicate the task to be performed for a particular invocation. Each time the S-function performs the task, it returns the result in a structure having the format shown in the syntax example.
A template implementation of an M-file S-function, sfuntmpl.m, resides in matlabroot/toolbox/simulink/blocks. The template consists of a top-level function and a set of skeleton subfunctions, each of which corresponds to a particular value of flag. The top-level function invokes the subfunction indicated by flag. The subfunctions, called S-function callback methods, perform the tasks required of the S-function during simulation. The following table lists the contents of an M-file S-function that follows this standard format.
We recommend that you follow the structure and naming conventions of the template when creating M-file S-functions. This makes it easier for others to understand and maintain M-file S-functions that you create. See Writing M S-Functions, for information on creating M-file S-functions.
MEX-File S-Functions
Like an M-file S-function, a MEX-file function consists of a set of callback routines that Simulink invokes to perform various block-related tasks during a simulation. Significant differences exist, however. For one, MEX-file functions are implemented in a different programming language: C, C++, Ada, or Fortran. Also, Simulink invokes MEX S-function routines directly instead of via a flag value as with M-file S-functions. Because Simulink invokes the functions directly, MEX-file functions must follow standard naming conventions specified by Simulink.
Other key differences exist. For one, the set of callback functions that MEX functions can implement is much larger than can be implemented by M-file functions. A MEX function also has direct access to the internal data structure, called the SimStruct, that Simulink uses to maintain information about the S-function. MEX-file functions can also use the MATLAB MEX-file API to access the MATLAB workspace directly.
A C MEX-file S-function template, called sfuntmpl_basic.c, resides in the matlabroot/simulink/src directory. The template contains skeleton implementations of all the required and optional callback routines that a C MEX-file S-function can implement. For a more amply commented version of the template, see sfuntmpl_doc.c in the same directory.
MEX-File Versus M-File S-Functions
M-file and MEX-file S-functions each have advantages. The advantage of M-file S-functions is speed of development. Developing M-file S-functions avoids the time-consuming compile-link-execute cycle required by development in a compiled language. M-file S-functions also have easier access to MATLAB and toolbox functions.
The primary advantage of MEX-file functions is versatility. The larger number of callbacks and access to the SimStruct enable MEX-file functions to implement functionality not accessible to M-file S-functions. Such functionality includes the ability to handle data types other than double, complex inputs, matrix inputs, and so on.
| | S-Function Callback Methods | S-Function Concepts | |