Generated S-Function Block :: Desktops (Simulink® Coder™)

S-functions are an important class of target for which the Simulink Coder product can generate code. The ability to encapsulate a subsystem into an S-function allows you to increase its execution efficiency and facilitate code reuse.

The following sections describe the properties of S-function targets and demonstrate how to generate them. For more details on the structure of S-functions, see the Simulink Developing S-Functions documentation.

About Object Libraries

About the S-Function Target

Using the S-function target, you can build an S-function component and use it as an S-Function block in another model. The S-function code format used by the S-function target generates code that conforms to the Simulink C MEX S-function application programming interface (API). Applications of this format include

Conversion of a model to a component. You can generate an S-Function block for a model, m1. Then, you can place the generated S-Function block in another model, m2. Regenerating code for m2 does not require regenerating code for m1.
Conversion of a subsystem to a component. By extracting a subsystem to a separate model and generating an S-Function block from that model, you can create a reusable component from the subsystem. See Create an S-Function Block from a Subsystem for an example of this procedure.
Speeding up simulation. In many cases, an S-function generated from a model performs more efficiently than the original model.
Code reuse. You can incorporate multiple instances of one model inside another without replicating the code for each instance. Each instance will continue to maintain its own unique data.

The S-function target generates noninlined S-functions. Within the same release, you can generate an executable from a model that contains generated S-functions by using the generic real-time or real-time malloc targets. This is not supported when incorporating a generated S-function from one release into a model that you build with a different release.

You can place a generated S-Function block into another model from which you can generate another S-function. This allows any level of nested S-functions. For limitations related to nesting, see Limitations on Nesting S-Functions.

Note While the S-function target provides a means to deploy an application component for reuse while shielding its internal logic from inspection and modification, the preferred solutions for protecting intellectual property in distributed components are:

The protected model, a referenced model from which all block and line information has been eliminated using the Model Protection facility. For more information, see Protecting Referenced Models in the Simulink documentation.
The Embedded Coder shared library system target file, used to generate a shared library for a model or subsystem for use in a system simulation external to Simulink. For more information see Shared Object Libraries in the Embedded Coder documentation.

Required Files for S-Function Deployment

To deploy your generated S-Function block for inclusion in other models for simulation, you need only provide the binary MEX-file object that was generated in the current working folder when the S-Function block was created:

subsys_sf.mexext

where subsys is the subsystem name and mexext is a platform-dependent MEX-file extension (see mexext). For example, SourceSubsys_sf.mexw32.

To deploy your generated S-Function block for inclusion in other models for code generation, you must provide all of the files that were generated in the current working folder when the S-Function block was created:

subsys_sf.c or .cpp, where subsys is the subsystem name (for example, SourceSubsys_sf.c)
subsys_sf.h
subsys_sf.mexext, where mexext is a platform-dependent MEX-file extension (see mexext)
Subfolder subsys_sfcn_rtw and its contents

Sample Time Propagation in Generated S-Functions

A generated S-Function block can inherit its sample time from the model in which it is placed if certain criteria are met. Conditions that govern sample time propagation for both Model blocks and generated S-Function blocks are described in Inheriting Sample Times in the Simulink documentation and Inherited Sample Time for Referenced Models in the Simulink Coder documentation.

To generate an S-Function block that meets the criteria for inheriting sample time, you must constrain the solver for the model from which the S-Function block is generated. On the Solver configuration parameters dialog pane, set Type to Fixed-step and Periodic sample time constraint to Ensure sample time independent. If the model is unable to inherit sample times, this setting causes the Simulink software to display an error message when building the model. See Periodic sample time constraint in the Simulink documentation for more information about this option.

Choose a Solver Type

If the model containing the subsystem from which you generate an S-function uses a variable-step solver, the generated S-function contains zero-crossing functions and will work properly only in models that use variable-step solvers.

If the model containing the subsystem from which you generate an S-function uses a fixed-step solver, the generated S-function contains no zero-crossing functions and the generated S-function will work properly in models that use variable-step or fixed-step solvers.

Create an S-Function Block from a Subsystem

This section demonstrates how to extract a subsystem from a model and generate a reusable S-function component from it.

The next figure shows SourceModel, a simple model that inputs signals to a subsystem. The subsequent figure shows the subsystem, SourceSubsys. The signals, which have different widths and sample times, are

A Step block with sample time 1
A Sine Wave block with sample time 0.5
A Constant block whose value is the vector [-2 3]
SourceModel

SourceSubsys

The objective is to extract SourceSubsys from the model and build an S-Function block from it, using the S-function target. The S-Function block must perform identically to the subsystem from which it was generated.

In this model, SourceSubsys inherits sample times and signal widths from its input signals. However, S-Function blocks created from a model using the S-function target will have all signal attributes (such as signal widths or sample times) hard-wired. (The sole exception to this rule concerns sample times, as described in Sample Time Propagation in Generated S-Functions.)

In this example, you want the S-Function block to retain the properties of SourceSubsys as it exists in SourceModel. Therefore, before you build the subsystem as a separate S-function component, you must set the inport sample times and widths explicitly. In addition, the solver parameters of the S-function component must be the same as those of the original model. The generated S-function component will operate identically to the original subsystem (see Choose a Solver Type for an exception to this rule).

To build SourceSubsys as an S-function component,

Create a new model and copy/paste the SourceSubsys block into the empty window.
Set the signal widths and sample times of inports inside SourceSubsys such that they match those of the signals in the original model. Inport 1, Filter, has a width of 1 and a sample time of 1. Inport 2, Xferfcn, has a width of 1 and a sample time of 0.5. Inport 3, offsets, has a width of 2 and a sample time of 0.5.
The generated S-Function block should have three inports and one outport. Connect inports and an outport to SourceSubsys, as shown in the next figure.

The signal widths and sample times are propagated to these ports.
Set the solver type, mode, and other solver parameters such that they are identical to those of the source model. This is easiest to do if you use Model Explorer.
In Model Explorer or the Configuration Parameters dialog box, click the Code Generation tab.
Click Browse to open the System Target File Browser.
In the System Target File Browser, select the S-function target, rtwsfcn.tlc, and click OK. The Code Generation pane appears as follows.
Select the S-Function Target pane. Make sure that Create new model is selected, as shown in the next figure:

When this option is selected, the build process creates a new model after it builds the S-function component. The new model contains an S-Function block, linked to the S-function component.
Click Apply.
Save the new model containing your subsystem, for example as SourceSubsys.mdl.
Build the model.
The Simulink Coder build process builds the S-function component in the working folder. After the build, a new model window is displayed.

Optionally you can save the generated model, for example as SourceSubsys_Sfunction.mdl.
You can now copy the Simulink Coder S-Function block from the new model and use it in other models or in a library.
The next figure shows the S-Function block plugged into the original model. Given identical input signals, the S-Function block will perform identically to the original subsystem.
Generated S-Function Configured Like SourceModel

The speed at which the S-Function block executes is typically faster than the original model. This difference in speed is more pronounced for larger and more complicated models. By using generated S-functions, you can increase the efficiency of your modeling process.

Tunable Parameters in Generated S-Functions

You can use tunable parameters in generated S-functions in two ways:

Use the Generate S-function feature (see Automate S-Function Generation).
or
Use the Model Parameter Configuration dialog box (see Parameters) to declare desired block parameters tunable.

Block parameters that are declared tunable with the auto storage class in the source model become tunable parameters of the generated S-function. These parameters do not become part of a generated model_P (formerly rtP) parameter data structure, as they would in code generated from other targets. Instead, the generated code accesses these parameters by using MEX API calls such as mxGetPr or mxGetData. Your code should access these parameters in the same way.

For more information on MEX API calls, see Writing S-Functions in C in the Simulink documentation and External Interfaces in the MATLAB online documentation.

S-Function blocks created by using the S-function target are automatically masked. The mask displays each tunable parameter in an edit field. By default, the edit field displays the parameter by variable name, as in the following example.

You can choose to display the value of the parameter rather than its variable name by selecting Use value for tunable parameters on the Code Generation > S-Function Target pane of the Configuration Parameters dialog box.

When this option is chosen, the value of the variable (at code generation time) is displayed in the edit field, as in the following example.

System Target File and Template Makefiles

About System Target File and Template Makefiles

This section lists the target file and template makefiles that are provided for use with the S-function target.

System Target File

rtwsfcn.tlc

Template Makefiles

rtwsfcn_lcc.tmf — Lcc compiler
rtwsfcn_unix.tmf — The Open Group UNIX host
rtwsfcn_vc.tmf — Microsoft Visual C++ compiler
rtwsfcn_watc.tmf — Watcom C compiler

Checksums and the S-Function Target

The Simulink Coder software creates a checksum for a Simulink model and uses the checksum during the build process for code reuse, model reference, and external mode features.

The Simulink Coder software calculates a model's checksum by

Calculating a checksum for each subsystem in the model. A subsystem's checksum is the combination of properties (data type, complexity, sample time, port dimensions, and so forth) of the subsystem's blocks.
Combining the subsystem checksums and other model-level information.

An S-function can add additional information, not captured during the block property analysis, to a checksum by calling the function ssSetChecksumVal. For the S-Function target, the value that gets added to the checksum is the checksum of the model or subsystem from which the S-function is generated.

The Simulink Coder software applies the subsystem and model checksums as follows:

Code reuse — If two subsystems in a model have the same checksum, the Simulink Coder build process generates code for one function only.
Model reference — If the current model checksum matches the checksum when the model was built, the Simulink Coder build process does not rebuild submodels.
External mode — If the current model checksum does not match the checksum of the code that is running on the target, the Simulink Coder build process generates an error.

S-Function Target Limitations

Limitations on Using Tunable Variables in Expressions

Certain limitations apply to the use of tunable variables in expressions. When Simulink Coder software encounters an unsupported expression during code generation, a warning appears and the equivalent numeric value is generated in the code. For a list of the limitations, see Tunable Expression Limitations.

Run-Time Parameters and S-Function Compatibility Diagnostics

If you set the S-function upgrades needed option on the Diagnostics > Compatibility pane of the Configuration Parameters dialog box to warning or error, the Simulink Coder software instructs you to upgrade S-functions that you create with the Generate S-function feature. This is because the S-function target does not register run-time parameters. Run-time parameters are only supported for inlined S-Functions and the generated S-Function supports features that prevent it from being inlined (for example, it can call or contain other noninlined S-functions).

You can work around this limitation by setting the S-function upgrades needed option to none. Alternatively, if you have an Embedded Coder license, select the Create Embedded Coder SIL block check box on the Generate S-function for Subsystem dialog box and create a SIL block (containing the ERT S-function). In this case, you do not receive the upgrade messages. However, you cannot include SIL blocks inside other generated S-functions recursively.

Limitations on Using Goto and From Block

When using the S-function target, the Simulink Coder code generator restricts I/O to correspond to the root model's Inport and Outport blocks (or the Inport and Outport blocks of the Subsystem block from which the S-function target was generated). No code is generated for Goto or From blocks.

To work around this restriction, create your model and subsystem with the required Inport and Outport blocks, instead of using Goto and From blocks to pass data between the root model and subsystem. In the model that incorporates the generated S-function, you would then add Goto and From blocks.

Example Before Work Around

Root model with a From block and subsystem, Subsystem1
Subsystem1 with a Goto block, which has global visibility and passes its input to the From block in the root model
Subsystem1 replaced with an S-function generated with the S-Function target — a warning results when you run the model because the generated S-function does not implement the Goto block

Example After Work Around

An Outport block replaces the GoTo block in Subsystem1. When you plug the generated S-function into the root model, its output connects directly to the To Workspace block.

Limitations on Building and Updating S-Functions

The following limitations apply to building and updating S-functions using the Simulink Coder S-function target:

You cannot build models that contain Model blocks using the Simulink Coder S-function target. This also means that you cannot build a subsystem module by right-clicking (or by using Tools > Code Generation > Build subsystem) if the subsystem contains Model blocks. This restriction applies only to S-functions generated using the S-function target, not to ERT S-functions.
If you modify the model that generated an S-Function block, the Simulink Coder build process does not automatically rebuild models containing the generated S-Function block. This is in contrast to the practice of automatically rebuilding models referenced by Model blocks when they are modified (depending on the Model Reference Rebuild configuration setting).
Handwritten S-functions without corresponding TLC files must contain exception-free code. For more information on exception-free code, see Exception Free Code in the Simulink documentation.

Unsupported Blocks

The S-function format does not support the following built-in blocks:

Interpreted MATLAB Function block
S-Function blocks containing any of the following:
- MATLAB language S-functions (unless you supply a TLC file for C code generation)
- Fortran S-functions (unless you supply a TLC file for C code generation)
- C/C++ MEX S-functions that call into the MATLAB environment
Scope block
To Workspace block

The S-function format does not support blocks from the Embedded Targets (embeddedtargetslib) block library in the Embedded Coder product.

`SimState` Not Supported for Code Generation

You can use SimState within C-MEX and Level-2 MATLAB language S-functions to save and restore the simulation state (see S-Function Compliance with the SimState in the Simulink documentation). However, SimState is not supported for code generation, including with the Simulink Coder S-function target.

Profiling Code Performance Not Supported

Profiling the performance of generated code using the Target Language Compiler (TLC) hook function interface described in is not supported for the S-function target.

Limitations on Nesting S-Functions

The following limitations apply to nesting a generated S-Function block in a model or subsystem from which you generate another S-function:

The software does not support nonvirtual bus input and output signals for a nested S-function.
You should avoid nesting an S-function in a model or subsystem having the same name as the S-function (possibly several levels apart). In such situations, the S-function can be called recursively. The software currently does not detect such loops in S-function dependency, which can result in aborting or hanging your MATLAB session. To prevent this from happening, be sure to name the subsystem or model to be generated as an S-function target uniquely, to avoid duplicating any existing MEX filenames on the MATLAB path.

Limitations on User-Defined Data Types

The Simulink Coder S-function target does not support the HeaderFile property that can be specified on user-defined data types, including those based on Simulink.AliasType, Simulink.Bus, and Simulink.NumericType objects. If a user-defined data type in your model uses the HeaderFile property to specify an associated header file, Simulink Coder S-function target code generation disregards the value and does not generate a corresponding include statement.

Limitation on Right-Click Generation of an S-Function Target

If you generate an S-function target by right-clicking a Function-Call Subsystem block, the original subsystem and the generated S-function might not be consistent. An inconsistency occurs when the States when enabling parameter of the Trigger Port block inside the Function-Call Subsystem block is set to inherit. You must set the States when enabling parameter to reset or held, otherwise Simulink reports an error.

Limitation on S-Functions with Bus I/O Signals

If an S-function generated using the S-function target has bus input or output signals, the generated bus data structures might include padding to align fields of the bus elements with the Simulink representation used during simulation. However, if you insert the S-function in a model and generate code using a model target such as grt.tlc, the bus structure alignment generated for the model build might be incompatible with the padding generated for the S-function and might affect the numerical results of code execution. To make the structure alignment consistent between model simulation and execution of the model code, for each Simulink.Bus object, you can modify the HeaderFile property to remove the unpadded bus structure header file. This will cause the bus typedefs generated for the S-function to be reused in the model code.

Limitation on Subsystems with Function-Call I/O Signals

The S-function target does not support creating an S-Function block from a subsystem that has a function-call trigger input or a function-call output.