S-Functions and Code Generation
You use S-functions to extend Simulink® support for simulation and code generation. For example, you can use them to:
Represent custom algorithms
Interface existing external code with Simulink model and the generated code
Represent device drivers for interfacing with hardware
Generate highly optimized code for embedded systems
Verify code generated for a subsystem as part of a Simulink simulation
The application program interface (API) for writing S-functions allows you to implement generic algorithms in the Simulink environment with a great deal of flexibility. If you intend to use S-functions in a model for code generation, the level of flexibility can vary. For example, it is not possible to access the MATLAB® workspace from an S-function that you use with the code generator. This topic explains conditions to be aware of for using S-functions. However, using the techniques presented in this topic, you can create S-functions for most applications that work with the generated code.
Although S-functions provide a generic and flexible solution for implementing complex algorithms in a model, the underlying API incurs overhead in terms of memory and computation resources. Most often the additional resources are acceptable for real-time rapid prototyping systems. Often, though, additional resources are unavailable in real-time embedded applications. You can minimize memory and computational requirements by using the Target Language Compiler technology provided with the code generator to inline your S-functions. If you are producing an S-function for existing external code, consider using the Legacy Code Tool to generate your S-function and relevant TLC file.
This topic assumes that you understand the following concepts:
Target Language Compiler (TLC) scripting
How the code generator produces and builds C/C++ code
This information is for code generator users. Even if you do not currently use the code generator, follow these practices when writing S-functions, especially if you are creating general-purpose S-functions.
Types of S-Functions
Examples for which you might choose to implement an S-function for simulation and code generation include:
“I'm not concerned with efficiency. I want to write one version of my algorithm and have it work in the Simulink and code generator products automatically.”
“I want to implement a highly optimized algorithm in the Simulink and code generator products that looks like a built-in block and generates efficient code.”
“I have a lot of hand-written code that I need to interface. I want to call my function from the Simulink and code generator products efficiently.”
Respectively, the preceding situations map to the following MathWorks® terminology:
Auto-generated S-function for external code
A noninlined S-function is a C or C++ MEX S-function that is treated
identically by the Simulink engine and generated code. In general, you implement your
algorithm once according to the S-function API. The Simulink engine and generated code call the S-function routines (for
mdlOutputs) during model execution.
Additional memory and computation resources are required for each instance of a noninlined S-Function block. However, this routine of incorporating algorithms into models and code generation applications is typical during the prototyping phase of a project where efficiency is not important. The advantage gained by forgoing efficiency is the ability to change model parameters and structures rapidly.
Writing a noninlined S-function does not involve TLC coding. Noninlined S-functions are the default case for the build process in the sense that once you build a MEX S-function in your model, there is no additional preparation before pressing Ctrl+B to build your model.
Some restrictions exist concerning the names and locations of noninlined S-function files when generating makefiles. See Write Noninlined S-Function.
For S-functions to work in the Simulink environment, some overhead code is generated. When the code
generator produces code from models that contain S-functions (without
embeds some of this overhead code in the generated code. If you want to optimize
your real-time code and eliminate some of the overhead code, you must
inline (or embed) your S-functions. This involves
writing a TLC (
that eliminates overhead code from the generated code. The Target Language
files to define how to inline your S-function algorithm in the generated
Do not confuse the term inline with the C++
inline keyword. Inline means to specify text in
place of the call to the general S-function API routines (for example,
mdlOutputs). For example, when a TLC file is used
to inline an S-function, the generated code contains the C/ C++ code that
normally appears within the S-function routines and the S-function itself
that has been removed from the build process.
A fully inlined S-function builds your algorithm (block) into generated code in a manner that is indistinguishable from a built-in block. Typically, a fully inlined S-function requires you to implement your algorithm twice: once for the Simulink model (C/C++ MEX S-function) and once for code generation (TLC file). The complexity of the TLC file depends on the complexity of your algorithm and the level of efficiency you try to achieve in the generated code. TLC files vary from simple to complex in structure. See Inlining S-Functions.
Auto-generated S-Functions for Legacy or Custom Code
If you need to invoke hand-written C/C++ code in your model, consider using the Simulink Legacy Code Tool. The Legacy Code Tool can automate the generation of a fully inlined S-function and a corresponding TLC file based on information that you register in a Legacy Code Tool data structure.
For more information, see Integrate C Functions Using Legacy Code Tool and see Import Calls to External Code into Generated Code with Legacy Code Tool.
Files Required for Implementing Noninlined and Inlined S-Functions
This topic briefly describes what files and functions you need to create noninlined and inlined S-functions.
Noninlined S-functions require the C or C++ MEX S-function source code (
Fully inlined S-functions require an
file. Fully inlined S-functions produce the optimal code for a parameterized S-function. This is an S-function that operates in a specific mode dependent upon fixed S-function parameters that do not change during model execution. For a given operating mode, the
file specifies the exact code that is generated to implement the algorithm for that mode. For example, the direct-index lookup table S-function in Write Fully Inlined S-Functions with mdlRTW Routine contains two operating modes — one for evenly spaced
x-dataand one for unevenly spaced
Fully inlined S-functions that are generated to invoke legacy or custom C/C++ code also require an
file, which is generated by Legacy Code Tool.
Fully inlined S-functions might require the placement of the
mdlRTW routine in your S-function MEX-file
mdlRTW routine lets you place information in
is the record file
that specifies a model, and which the code generator invokes the Target Language
Compiler to process before executing
mdlRTW routine is useful when you want to
introduce non-tunable parameters into your TLC file. Such parameters are used to
determine which operating mode is active in a given instance of the S-function.
Based on this information, the TLC file for the S-function can generate highly
efficient, optimal code for that operating mode.
Guidelines for Writing S-Functions that Support Code Generation
You can use C/C++ MEX, MATLAB language, and Fortran MEX S-functions with code generation.
You can inline S-functions for code generation by providing an inlining TLC file. See S-Function Inlining in Target Language Compiler. MATLAB and Fortran MEX S-functions must be inlined. C/C++ MEX S-functions can be inlined for code efficiency, or noninlined.
To automatically generate a fully inlined C MEX S-function for invoking legacy or custom code, use the Legacy Code Tool. For more information, see Integrate C Functions Using Legacy Code Tool and see Import Calls to External Code into Generated Code with Legacy Code Tool.
If code efficiency is not an overriding consideration, for example, if you are rapid prototyping, you can choose not to inline a C/C++ MEX S-function. For more information, see Write Noninlined S-Function.