| Writing S-Functions | |
Writing Level-2 M-File S-Functions
The Level-2 M-file S-function application programming interface (API) allows you to use the MATLAB M language to create full-fledged custom blocks having multiple inputs and outputs and capable of handling any type of signal produced by a Simulink model, including matrix and frame signals of any datatype. The Level-2 M-File S-Function API corresponds closely to the API for creating C MEX-file S-functions. Much of the documentation for creating C MEX-file S-functions (see Writing S-Functions in C and Implementing Block Features) applies also to Level-2 M-file S-functions. To avoid duplication, this section focuses on providing information that is specific to writing Level-2 M-file S-functions.
About Level-2 M-File S-Functions
First, a word about Level-2 M-File S-functions themselves. A Level-2 M-file S-function is an M-file that defines the properties and behavior of an instance of a Level-2 M-File S-Function block that references the M-file in a Simulink model. The M-file itself comprises a set of callback methods (see Callback Methods) that Simulink invokes when updating or simulating the model. The callback methods perform the actual work of initializing and computing the outputs of the block defined by the S-function.
To facilitate these tasks, Simulink passes a runtime object to the callback methods as an argument. The runtime object effectively serves as an M proxy for the S-function block, allowing the callback method to set and access the block's properties during simulation or model updating (see Runtime Object for more information).
The Level-2 M-File S-Function API
The Level-2 M-File S-function API defines the signatures and general purpose of the callback methods that constitute a Level-2 M-file S-function. The S-function itself provides the implementations of these callback methods. The implementations in turn determine the block's attributes (e.g., ports, parameters, and states) and behavior (e.g., the block's outputs as a function of time and the block's inputs, states, and parameters). By creating an S-function with an appropriate set of callback implementations, you can define a block type that meets the specific requirements of your application.
M-file S-Function Demos
Simulink provides a set of self-documenting demo models that illustrate creation and usage of Level-2 M-file S-functions. To view the demos,
S-Function Template
To give you a head start on creating Level-2 M-file S-functions, Simulink provides an annotated M-file template containing skeleton implementation of the callbacks defined by the Level-2 M-File S-function API. The template resides at
To create an M-file S-function, make a copy of the template and edit the copy as necessary to reflect the desired behavior of the S-function you are creating. The comments in the template explain how to do this.
Instantiating a Level-2 M-File S-Function
To create an instance of the S-function in a model, first create an instance of the Level-2 M-File S-Function block in the model. Then open the block's parameter dialog box and enter the name of the M-file that implements your S-function in the dialog box's M-file name field. If your function uses any additional parameters, enter their values as a comma-separated list in the dialog box's Parameters field.
Generating Code from a Level-2 M-File S-Function
Generating code from a model containing a Level-2 M-file S-function requires that you provide a corresponding TLC file. You do not need a TLC file to run a model in accelerated mode as the Simulink Accelerator runs Level-2 M-file S-functions in interpreted mode.
| | Introduction | Callback Methods | |
© 1994-2005 The MathWorks, Inc.