S-Function Features and Limitations - MATLAB & Simulink (original) (raw)
S-Function Features
The following tables give overviews of the features supported by different types of S-functions. The first table focuses on handwritten S-functions. The second table compares the features of S-functions automatically generated by the S-Function Builder or Legacy Code Tool.
Features of Hand-Written S-Functions
| Feature | Level-2 MATLAB S-Function | Handwritten C MEX S-Function |
|---|---|---|
| Data types | Supports any data type supported by Simulink® software, including fixed-point types. | Supports any data type supported by Simulink software, including fixed-point types. |
| Numeric types | Supports real and complex signals. | Supports real and complex signals. |
| Frame support | Supports framed and unframed signals. | Supports framed and unframed signals. |
| Port dimensions | Supports scalar, 1-D, and multidimensional input and output signals. | Supports scalar, 1-D, and multidimensional input and output signals. |
| S-function API | Supports a larger set of the S-function API. See Level-2 MATLAB S-Function Callback Methods for a list of supported methods. | Supports the entire S-function API. |
| Code generation support | Requires a handwritten TLC file to generate code. | Natively supports code generation. Requires a handwritten TLC file to inline the S-function during code generation. |
| Simulink Accelerator mode | Provides the option to use a TLC file in Accelerator mode, instead of running interpretively. | Provides the option to use a TLC or MEX file in Accelerator mode. |
| Model reference | Supports Normal and Accelerator mode simulations when used in a referenced model. Requires a TLC file for Accelerator mode. | Provides options for sample time inheritance and Normal mode support when used in a referenced model. See Model Reference Requirements and Limitations. |
| Simulink.AliasType andSimulink.NumericType support | Supports Simulink.NumericType andSimulink.AliasType classes (see Configure Custom Data Types). | Supports all of these classes (see Configure Custom Data Types). |
| Bus input and output signals | Does not support bus input or output signals. | Supports nonvirtual bus input or output signals. |
| Tunable and run-time parameters | Supports tunable and run-time parameters. | Supports tunable and run-time parameters. |
| Work vectors | Supports DWork vectors (see Using DWork Vectors in Level-2 MATLAB S-Functions). | Supports all work vector types (see Types of DWork Vectors). |
Features of Automatically Generated S-Functions
| Feature | S-Function Builder | Legacy Code Tool |
|---|---|---|
| Data types | Supports any data type supported by Simulink software, including fixed-point types. | Supports all built-in data types. To use a fixed-point data type, you must specify the data type as a Simulink.NumericType. You cannot use a fixed-point type with unspecified scaling. |
| Numeric types | Supports real and complex signals. | Supports complex signals only for built-in data types. |
| Frame support | Supports framed and unframed signals. | Does not support frame-based signals. |
| Port dimensions | Supports scalar, 1-D, and multidimensional input and output signals. | Supports scalar, 1-D, and multidimensional input and output signals. |
| S-function API | Supports creation of custom mdlInitializeSizes,mdlInitializeSampleTimes, mdlDerivatives,mdlUpdate, and mdlOutputs. Also allows for automatic generation of mdlStart andmdlTerminate. | Supports mdlInitializeSizes,mdlInitializeSampleTimes, mdlStart,mdlInitializeConditions, mdlOutputs, andmdlTerminate. |
| Code generation support | Natively supports code generation. Also, automatically generates a TLC file for inlining the S-function during code generation. | Natively supports code generation optimized for embedded systems. Also, automatically generates a TLC file that supports expression folding for inlining the S-function during code generation. |
| Accelerator mode | Uses a TLC file in Accelerator mode, if the file was generated. Otherwise, uses the MEX file. | Provides the option to use a TLC or MEX file in Accelerator mode. |
| Model reference | Uses default behaviors when used in a referenced model. | Uses default behaviors when used in a referenced model. |
| Simulink.AliasType andSimulink.NumericType | Does not support these classes. | Supports Simulink.AliasType andSimulink.NumericType. |
| Bus input and output signals | Supports bus input and output signals. See sfbuilder_bususage for an example. | Supports bus input and output signals. You must define aSimulink.Bus object in the MATLAB® workspace that is equivalent to the structure of the input or output used in the legacy code. Does not support bus parameters. |
| Tunable and run-time parameters | Supports tunable parameters only during simulation. Supports run-time parameters. | Supports tunable and run-time parameters. |
| Work vectors | Does not provide access to work vectors. | Supports DWork vectors with the usage typeSS_DWORK_USED_AS_DWORK. See Types of DWork Vectors for a discussion on the different DWork vector usage types. |
S-Function Limitations
The following table summarizes the major limitations of the different types of S-functions.
| Implementation | Limitations |
|---|---|
| Level-2 MATLAB S-functions | Does not support bus input and output signals.Cannot incorporate legacy code during simulation, only during code generation through a TLC file. |
| Handwritten C MEX S-function | Supports model reference with some limitations. See S-Functions in Referenced Models. |
| S-Function Builder | Generates S-function code using a wrapper function which incurs additional overhead. Does not support the following S-function features:Work vectorsPort-based sample timesMultiple sample times or a nonzero offset timeDynamically-sized input and output signals for an S-function with multiple input and output ports The initial values of states, the sample time, and the size of input and output ports must be pre-selected value and cannot be passed as parameters to the s-function.The value of sample time cannot be retrieved by any of the callback methods. NoteS-functions with one input and one output port can have dynamically-sized signals. |
| Legacy Code Tool | Generates C MEX S-functions for existing functions written in C or C++ only. The tool does not support transformation of MATLAB or Fortran® functions.Can interface with C++ functions, but not C++ objects.Does not support simulating continuous or discrete states.Does not support use of function pointers as the output of the legacy function being called.Always sets the S-function's flag for direct feedthrough (sizes.DirFeedthrough) totrue.Supports only the continuous, but fixed in minor time step, sample time and offset option.Supports complex numbers, but only with Simulinkbuilt-in data types.Does not support the following S-function features:Work vectors, other than general DWork vectorsFrame-based input and output signalsPort-based sample timesMultiple block-based sample times |