Use S-Function Target for Model or Subsystem - MATLAB & Simulink (original) (raw)

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 theS-Function block was created. The required file is:

• _`subsys`__sf._`mexext`_

where _`subsys`_ is the subsystem name and _`mexext`_ is a platform-dependent MEX-file extension (see mexext). 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 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

The rtwsfcn.tlc system target file is provided for use with the S-function target.

The generated S-function code uses > 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 generatedS-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 theS-Function block is generated. Set model configuration parameterType to Fixed-step andPeriodic sample time constraint toEnsure 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 theauto 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 (formerlyrtP) 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 ormxGetData. 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 aSimulink.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 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 settingData 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 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 attributeHeaderFile 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 > > > 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

1. 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.
2. 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 functionssSetChecksumVal. 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
• Tunable Variables in Expressions
• Parameter Tuning
• Run-Time Parameters and S-Function Compatibility Diagnostics
• Goto and From Blocks
• Building and Updating S-Functions
• Unsupported Blocks
• Model Operating Point not Supported for Code Generation
• Nesting S-Functions
• User-Defined Data Types
• Right-Click Generation of an S-Function Target
• Bus Input and Output
• Subsystems with Function-Call Input and Output Signals
• Function-Call Subsystem Modeling Pattern
• Data Store Access
• Inport or Outport Block Parameters Through Subsystem Mask
• MEX S-Function Wrappers

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 generatedS-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 > 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 towarning 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 tonone.

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 andOutport blocks (or the Inport andOutport 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
  
• Subsystem1 that includes a Goto block that has global visibility and passes its input to theFrom block in the root model
  
• Subsystem1 replaced 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 inSubsystem1. 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.
• 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 byModel 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, seeException 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](https://mdsite.deno.dev/matlab: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 generatedS-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 theHeaderFile 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 theHeaderFile 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 toinherit. You must set the States when enabling parameter to reset orheld, 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 asgrt.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 theHeaderFile 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:

1. Between the subsystem block and the branch
2. Between the branch and the root Outport block
3. Between the branch and the block that has theUpdate function

The Signal Conversion block in the workaround has these parameter settings:

• Output set to Signal copy
• Exclude 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 byData Store Read or Data Store Write blocks.

Inport or Outport Block Parameters Through Subsystem Mask

S-functions generated from a subsystem with Inport orOutport block parameters specified by subsystem mask variables produce an error when you try to run a simulation that uses theS-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.

See Also

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