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.
Note
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.
The '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:
subsys_sf.mexext
where subsysmexextmexext). For example,
SourceSubsys_sf.mexw64.
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:
subsys_sf.c.cpp, wheresubsysSourceSubsys_sf.c)subsys_sf.hsubsys_sf.mexextmexextmexext)Subfolder
subsys_sfcn_rtw
The rtwsfcn.tlc system target file is provided for use with the
S-function target.
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
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. 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
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_PrtP) 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 mxGetPr or
mxGetData. Your code should access these parameters in the
same way.
For more information on MEX API calls, see How to Create 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.
Macro Parameters
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 Define, ImportedDefine,
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 HeaderFile to '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 from the
Value property of the parameter object.
To use a macro that you define through a compiler option, for example by applying
the storage class 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:
Defines.
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
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 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, *.mexw64) include:
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.
Parameter Tuning
The S-Function block does not support tuning of tunable parameters with:
Complex values.
Values or data types that are transformed to a constant (by setting the model configuration parameter Optimization > Default parameter behavior to
Inlined).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
needed to
warning or 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 S-functions.
To work around this limitation, set parameter S-function upgrades
needed to
none.
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,
Subsystem1
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.
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
Simulink Function block
Function Caller block
Scope block
To Workspace block
The S-function format does not support blocks from the embeddedtargetslib block library.
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. 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.
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 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
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,
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
grt.tlc, the 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 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.
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
Updatefunction
The Signal Conversion block in the workaround has these parameter settings:
Output set to
Signal copyExclude this block 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.
Related Topics
- 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
You can also select a web site from the following list
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)