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:

Level-2 S-functions
Target Language Compiler (TLC) scripting
How the code generator produces and builds C/C++ code

Notes

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:

Noninlined S-function
Inlined S-function
Auto-generated S-function for external code

Noninlined S-Functions

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 example, 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.

Inlined S-Functions

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 sfunction.tlc files), it 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 (sfunction.tlc) file that eliminates overhead code from the generated code. The Target Language Compiler processes sfunction.tlc files to define how to inline your S-function algorithm in the generated code.

Note

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 typically require the C or C++ MEX S-function source code (sfunction.c or sfunction.cpp). To implement noninlined S-functions without providing the C or C++ MEX S-function source code files, you must include libraries or object files as S-Function modules. For more information, see Specify Additional Source Files for an S-Function and Use rtwmakecfg.m API to Customize Generated Makefiles.
Fully inlined S-functions require an sfunction.tlc 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 sfunction.tlc 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-data and one for unevenly spaced x-data.
Note
Fully inlined S-functions that are generated to invoke legacy or custom C/C++ code also require an sfunction.tlc 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 sfunction.c or sfunction.cpp. The mdlRTW routine lets you place information in model.rtw. model.rtw is the record file that specifies a model, and which the code generator invokes the Target Language Compiler to process before executing sfunction.tlc when generating code.

Including a 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.