Learn more about Real-Time Workshop

Introduction to S-Functions for Code Generation

On this page…
About S-Functions Additional Information Classes of Problems Solved by S-Functions Types of S-Functions Basic Files Required for Implementation Guidelines for Writing S-Functions for Use with Real-Time Workshop Software

About S-Functions

This chapter describes how to create S-functions that work seamlessly with Real-Time Workshop code generation. It begins with basic concepts and concludes with an example of how to create a highly optimized direct-index lookup table S-Function block.

This chapter assumes that you understand the following concepts:

• Level 2 S-functions

• Target Language Compiler (TLC) scripting

• How the Real-Time Workshop software generates and builds C/C++ code

Note   When this chapter refers to actions performed by the Target Language Compiler, including parsing, caching, creating buffers, and so on, the name Target Language Compiler is spelled out fully. When referring to code written in the Target Language Compiler syntax, this chapter uses the abbreviation TLC.

Note   The guidelines presented in this chapter are for Real-Time Workshop users. Even if you do not currently use the Real-Time Workshop code generator, you should follow the practices presented in this chapter when writing S-functions, especially if you are creating general-purpose S-functions.

Back to Top

Additional Information

See the Target Language Compiler documentation and other Real-Time Workshop documentation for more information on the code generation process.

See Inlining S-Functions in the Target Language Compiler documentation for additional information on inlining S-functions.

Back to Top

Classes of Problems Solved by S-Functions

S-functions help solve various kinds of problems you might face when working with the Simulink and Real-Time Workshop products. These problems include

• Extending the set of algorithms (blocks) provided by the Simulink and Real-Time Workshop products

• Interfacing legacy (hand-written) code with the Simulink and Real-Time Workshop products

• Interfacing to hardware through device driver S-functions

• Generating highly optimized code for embedded systems

• Verifying code generated for a subsystem as part of a Simulink simulation

S-functions are written using an application program interface (API) that allows you to implement generic algorithms in the Simulink environment with a great deal of flexibility. This flexibility cannot always be maintained when you use S-functions with the Real-Time Workshop code generator. For example, it is not possible to access the MATLAB workspace from an S-function that is used with the code generator. However, using the techniques presented in this chapter, you can create S-functions for most applications that work with the Real-Time Workshop generated code.

Although S-functions provide a generic and flexible solution for implementing complex algorithms in a Simulink 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. In many cases, 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 Real-Time Workshop product to inline your S-functions. If you are producing an S-function for existing code, consider using the Simulink Legacy Code Tool.

Back to Top

Types of S-Functions

The implementation of S-functions changes based on your requirements. This chapter discusses the typical problems that you may face and how to create S-functions for applications that need to work with the Simulink and Real-Time Workshop products. These are some (informally defined) common situations:

1. "I'm not concerned with efficiency. I just want to write one version of my algorithm and have it work in the Simulink and Real-Time Workshop products automatically."

2. "I have a lot of hand-written code that I need to interface. I want to call my function from the Simulink and Real-Time Workshop products in an efficient manner."

   or said another way:

   "I want to create a block for my blockset that will be distributed throughout my organization. I'd like it to be very maintainable with efficient code. I'd like my algorithm to exist in one place but work with both the Simulink and Real-Time Workshop products."

3. "I want to implement a highly optimized algorithm in the Simulink and Real-Time Workshop products that looks like a built-in block and generates very efficient code."

The MathWorks products have adopted terminology for these different requirements. Respectively, the situations described above map to this terminology:

1. Noninlined S-function

2. Wrapper S-function

3. Fully inlined S-function

Noninlined S-Functions

A noninlined S-function is a C or C++ MEX S-function that is treated identically by the Simulink engine and Real-Time Workshop generated code. In general, you implement your algorithm once according to the S-function API. The Simulink engine and Real-Time Workshop generated code call the S-function routines (for example, mdlOutputs) at the appropriate points 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 Simulink models and Real-Time Workshop 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 any TLC coding. Noninlined S-functions are the default case for the Real-Time Workshop build process in the sense that once you build a MEX S-function in your model, there is no additional preparation prior to clicking Build in the Real-Time Workshop pane of the Configuration Parameters dialog box for your model.

Some restrictions exist concerning the names and locations of noninlined S-function files when generating makefiles. See Writing Noninlined S-Functions.

Wrapper S-Functions

A wrapper S-function is ideal for interfacing hand-written code or a large algorithm that is encapsulated within a few procedures. In this situation, usually the procedures reside in modules that are separate from the MEX S-function. The S-function module typically contains a few calls to your procedures. Because the S-function module does not contain any parts of your algorithm, but only calls your code, it is referred to as a wrapper S-function.

In addition to the MEX S-function wrapper, you need to create a TLC wrapper that complements your S-function. The TLC wrapper is similar to the S-function wrapper in that it contains calls to your algorithm.

Fully Inlined S-Functions

For S-functions to work correctly in the Simulink environment, a certain amount of overhead code is necessary. When the Real-Time Workshop software generates 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 all 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   The term inline should not be confused with the C++ inline keyword. In Real-Time Workshop terminology, inline means to specify a text string 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 appropriate C/ C++ code that would normally appear within the S-function routines and the S-function itself has been removed from the build process.

A fully inlined S-function builds your algorithm (block) into Real-Time Workshop 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 Real-Time Workshop code generation (TLC file). The complexity of the TLC file depends on the complexity of your algorithm and the level of efficiency you're trying to achieve in the generated code. TLC files vary from simple to complex in structure.

The Simulink 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 Integrating Existing C Functions into Simulink Models with the Legacy Code Tool in the Simulink Writing S-Functions documentation and Automating the Generation of Files for Fully Inlined S-Functions Using Legacy Code Tool.

Back to Top

Basic Files Required for Implementation

This section briefly describes what files and functions you need to create noninlined, wrapper, and fully inlined S-functions.

• Noninlined S-functions require the C or C++ MEX S-function source code (sfunction.c or sfunction.cpp).

• Wrapper S-functions that inline a call to your algorithm (your C/C++ function) require an sfunction.tlc file.

• Fully inlined S-functions also 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 at the end of this chapter contains two operating modes — one for evenly spaced x-data and one for unevenly spaced x-data.

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, the record file that specifies a model, and which the Real-Time Workshop code generator invokes the Target Language Compiler to process prior to executing sfunction.tlc when generating code.

Including a mdlRTW routine is useful when you want to introduce nontunable parameters into your TLC file. Such parameters are generally 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.

Back to Top

Guidelines for Writing S-Functions for Use with Real-Time Workshop Software

• Use only C MEX S-functions with the Real-Time Workshop code generator. You cannot use Level-1 M-file S-functions with Real-Time Workshop software.

• To inline an S-function, use the Legacy Code Tool. The Legacy Code Tool automatically generates fully inlined C MEX S-functions for legacy or custom code. In addition, the tool generates other files needed to compile and build the S-function for simulation and generate a masked S-function block configured to call existing external code. For more information, see Integrating Existing C Functions into Simulink Models with the Legacy Code Tool in the Simulink documentation and Automating the Generation of Files for Fully Inlined S-Functions Using Legacy Code Tool.

• If you are rapid prototyping, inlining an S-function might not be necessary. If you choose not to inline the C MEX S-function, write the S-function, include it directly in the model, and let the Real-Time Workshop software generate the code. For more information, see Writing Noninlined S-Functions.

Back to Top

Integrating External Code Using S-Functions

Writing Noninlined S-Functions

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS