Use S-Function Target for Model or Subsystem
S-functions are a class of system target file for which the code generator can produce code. An S-function target can encapsulate a subsystem to increase its execution efficiency, facilitate code reuse, and protect its intellectual property.
While you can use the S-function target 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 that hides block and line information. For more information, see Protect Models to Conceal Contents.
The 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 Package Generated Code as Shared Libraries.
These solutions also increase execution efficiency and facilitate code reuse.
You can use a generated S-function target with a Generated S-Function block.
'S-Function' value for the
CodeFormat TLC variable
used by the S-function target generates code that conforms to the Simulink C MEX S-function application programming interface (API).
Required Files for S-Function Deployment
There are different files required to deploy a generated S-Function block for simulation versus code generation.
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. The required file is:
is the subsystem name and
is a platform-dependent MEX-file
mexext). For example,
To deploy your generated S-Function block for inclusion in other models for code generation, provide the files that were generated in the current working folder when the S-Function block was created. The required files are:
is the subsystem name (for example,
is a platform-dependent MEX-file extension (see
and its contents
The generated S-function code uses Configuration Parameters > Hardware Implementation parameter values that match the host system on which the function was built. When you use the S-function in a model for code generation, make sure that these parameter values for the model match the parameter values of the S-function.
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 Referenced Model Sample Times and S-Functions That Specify Sample Time Inheritance Rules.
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. Set model configuration parameter
Fixed-step and Periodic
sample time constraint to
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. For more
information about this option, see Periodic sample time constraint.
Solver Type for Top Models with Generated S-Functions
The table shows the possible combinations of top model solver types as these types relate to whether the model has discrete or continuous sample times and solver types for generated S-functions.
Top Model Solver Options and Sample Times
|Model Configuration Parameters: Top-level model configuration|
|Sample Times||Solver Options, Type: Variable-step||Solver Options, Type: Fixed-step|
|Discrete||Generated S-function requires a variable-step solver||Generated S-function can have a variable-step solver or a fixed-step solver|
|Continuous||Generated S-function requires a variable-step solver||Generated S-function requires a fixed-step solver|
S-functions generated from a subsystem have parameters that are hardcoded into the block. Simulink calculates parameters such as sample time when it generates the block, not during simulation run time. It is important to verify whether the generated S-Function block works as expected in the destination model.
Tunable Parameters in Generated S-Functions
To use tunable parameters in generated S-functions, use model configuration parameters to declare desired block parameters tunable. See Declare Workspace Variables as Tunable Parameters Using the Model Parameter Configuration Dialog Box.
Block parameters that you declare as tunable with the
storage class in the source model become tunable parameters of the generated S-function.
These parameters do not become part of a generated
parameter data structure, as they would in code generated from other system target files.
Instead, the generated code accesses these parameters by using MEX API calls such as
mxGetData. Your code should access these
parameters in the same way.
For more information on MEX API calls, see About C MEX S-Functions and Integrate MATLAB with External Programming Languages and Systems.
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 model configuration parameter Use value for tunable parameters.
When select this parameter, the value of the variable (at code generation time) is displayed in the edit field.
Suppose that you apply a storage class such as
Define to a
Simulink.Parameter object so that the parameter appears as a macro in the
generated code. If you use the parameter object inside a subsystem from which you generate
an ERT S-function, you cannot select the parameter object as a tunable parameter. Instead,
the S-function code generator applies the custom storage class to the parameter object. This
generation of macros in the S-function code enables you to generate S-functions from
subsystems that contain variant elements, such as Variant Subsystem blocks,
that you configure to produce preprocessor conditionals in the generated code. You cannot
change the value of the parameter during simulation of the S-function.
To select the parameter object as a tunable parameter, apply a different storage class
or create your own storage class. Storage classes that treat parameters as macros include
CompilerFlag, and storage classes that you create by setting
Data initialization to
Macro in the Custom
Storage Class Designer. If you use a non-macro storage class, you cannot use the parameter
object as a variant control variable and generate preprocessor conditionals.
If you apply a storage class that treats the parameter object as an imported macro,
before you generate the ERT S-function, provide the macro definition. For example, suppose
that you apply the storage class
ImportedDefine to a
Simulink.Parameter object and use the parameter object as a
variant control variable in the subsystem. If you set the custom attribute
'myHdr.h', when you generate the
S-function, place the custom header file
myHdr.h in the current folder.
The generated S-function uses the macro value from your header file instead of the value
Value property of the parameter object.
To use a macro that you define through a compiler option, for example by applying the
CompilerFlag, use the model configuration parameter Code Generation > Custom Code > Code information > Defines to specify the compiler option. For more information, see Code Generation Pane: Custom Code: Additional Build Information:
System Target File
rtwsfcn.tlc system target file is provided for use with the
Checksums and the S-Function Target
The code generator creates a checksum for a model and uses the checksum during the build process for code reuse, model reference, and external mode features.
The code generator calculates a model 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 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
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 code generator applies the subsystem and model checksums as follows:
Code reuse — If two subsystems in a model have the same checksum, the code generator produces code for one function only.
Model reference — If the current model checksum matches the checksum when the model was built, the build process does not rebuild referenced models.
External mode — If the current model checksum does not match the checksum of the code that is running on the target hardware, the build process generates an error.
Generated S-Function Compatibility
When you build a MEX S-function from your model, the code generator builds a level 2
noninlined S-function. Cross-release usage limitations on the generated code and binary MEX
file (for example,
S-function target generated code from previous MATLAB® release software is not compatible with newer releases. Do not recompile the generated code from a previous release with newer MATLAB release software. Use the same MATLAB release software to generate code for the S-function target and compile the code into a MEX file.
You can use binary S-function MEX files generated from previous MATLAB release software with the same or newer releases with the same compatibility considerations as handwritten S-functions. For more information, see S-Function Compatibility.
The code generator can generate code and build an executable from a model that contains generated S-functions. This support requires that the S-functions are built with the same MATLAB release software that builds the model. It is not possible to incorporate a generated S-function MEX file from previous MATLAB release software into a model and build the model with newer releases.
S-Function Target Limitations
Inport and Outport Blocks with Continuous Sample Time
The right-click build method for generating an S-function does not preserve continuous sample time for Inport and Outport blocks. Because the sample time is not preserved, simulation of the generated S-Function block can be affected.
Tunable Variables in Expressions
Certain limitations apply to the use of tunable variables in expressions. When the code generator encounters an unsupported expression while producing code, a warning appears and the equivalent numeric value is generated in the code. For a list of the limitations, see Tunable Expression Limitations.
The S-Function block does not support tuning of tunable parameters with:
Values or data types that are transformed to a constant (by setting the model configuration parameter Optimization > Default parameter behavior to
Data types that are not built-in.
Floating-point data types that are not equivalent to a built-in type.
Run-Time Parameters and S-Function Compatibility Diagnostics
If you set model configuration parameter S-function upgrades
error, the code
generator instructs you to upgrade S-functions generated from subsystems. The S-function
system target file 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
To work around this limitation, set parameter S-function upgrades
Goto and From Blocks
When using the S-function system target file, the code generator restricts input and output to correspond to the root model Inport and Outport blocks (or the Inport and Outport blocks of the Subsystem block from which the S-function target was generated). The code generator does not produce code 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 that includes a From block and subsystem,
Subsystem1that includes a Goto block that has global visibility and passes its input to the From block in the root model
Subsystem1replaced with an S-function generated with the S-Function system target file — 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.
Building and Updating S-Functions
The following limitations apply to building and updating S-functions using the S-function system target file:
You cannot build models that contain Model blocks using the S-function system target file. This also means that you cannot build a subsystem by using the right-click context menu if the subsystem contains Model blocks. This restriction applies only to S-functions generated using the S-function target, not to ERT S-functions.
You can build a model with:
A toolchain only if the toolchain supports MEX-file generation.
A template makefile only if the template makefile is associated with a toolchain that supports MEX-file generation.
If you modify the model that generated an S-Function block, the 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.
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
Simulink Function block
Function Caller block
To Workspace block
The S-function format does not support blocks from the
Model Operating Point not Supported for Code Generation
You can write C-MEX and Level-2 MATLAB S-functions that leverage the model operating point, which is used to save and restore the simulation state, as described in S-Function Compliance with the ModelOperatingPoint. The model operating point is not supported for code generation, including with the S-function system target file.
When you generate code for an S-function that specifies default operating point compliance or no operating point support, the generated code does not include the model operating point functionality. You cannot generate code for an S-function that implements custom operating point functionality.
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 for a nested S-function.
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, name the subsystem or model to be generated as an S-function target uniquely to avoid duplicating existing MEX filenames on the MATLAB path.
User-Defined Data Types
The S-function system target file does not support the
property that can be specified on user-defined data types, including those based on
Simulink.NumericType objects. If a user-defined data type in your model
HeaderFile property to specify an associated header file, code
generation with the S-function system target file disregards the value and does not
generate a corresponding include statement.
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.
Bus Input and Output
If an S-function generated using the S-function target has bus input or output, 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
bus structure alignment generated for the model build might be incompatible with the
padding generated for the S-function and might impact 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
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
Subsystems with Function-Call Input and Output 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.
Function-Call Subsystem Modeling Pattern
When you add a generated S-Function block to a model and then simulate that model, MATLAB might crash if the generated S-function uses this function-call subsystem modeling pattern.
The function-call subsystem connects directly to an Outport block. The
signal line that connects the subsystem to the Outport block branches to a
block that has an
Update function, that is, a block that updates at
each major time step, such as Unit Delay and Memory. The
branch can be inside or outside of the subsystem.
In the model that includes the function-call subsystem, a Signal Conversion block in one of these locations can work around the problem with the generated S-function:
Between the subsystem block and the branch
Between the branch and the root Outport block
Between the branch and the block that has the
The Signal Conversion block in the workaround has these parameter settings:
Output set to
Exclude this bock from 'Block reduction' optimization selected
Data Store Access
When an S-Function block in your model accesses a data store during simulation, Simulink disables data store diagnostics.
If you created the S-Function block from a model, the diagnostic is disabled for global data stores as well.
If you created the S-Function block from a subsystem, the diagnostic is disabled for the following data stores:
Global data stores
Data stores placed outside the subsystem, but accessed by Data Store Read or Data Store Write blocks.
Inport or Outport Block Parameters Through Subsystem Mask
S-functions generated from a subsystem with Inport or Outport block parameters specified by subsystem mask variables produce an error when you try to run a simulation that uses the S-Function block.
Invalid setting in 'testSystem/Subsystem/__OutputSSForSFun__/Out2' for parameter 'PortDimensions' ...
MEX S-Function Wrappers
Use a MEX S-function wrapper only in the MATLAB version in which the wrapper is created.
- Protect Models to Conceal Contents
- Accelerate, Refine, and Test Hybrid Dynamic System on Host Computer by Using RSim System Target File
- C/C++ S-Function Basics
- S-Functions and Code Generation
- Import Calls to External Code into Generated Code with Legacy Code Tool
- Use a Bus with S-Function Builder to Create an S-Function