SIMULINK Model-Based and System-Based Design

Modeling

Simulation

Implementation

Writing S-Functions
Version 4
How to Contact The MathWorks:

www.mathworks.com Web
comp.soft-sys.matlab Newsgroup

[email protected] Technical support

[email protected] Product enhancement suggestions
[email protected] Bug reports
[email protected] Documentation error reports
[email protected] Order status, license renewals, passcodes
[email protected] Sales, pricing, and general information

508-647-7000 Phone

508-647-7001 Fax

The MathWorks, Inc. Mail

3 Apple Hill Drive
Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

Writing S-Functions
 COPYRIGHT 1998 - 2001 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or repro-
duced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by
or for the federal government of the United States. By accepting delivery of the Program, the government
hereby agrees that this software qualifies as "commercial" computer software within the meaning of FAR
Part 12.212, DFARS Part 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Part
252.227-7014. The terms and conditions of The MathWorks, Inc. Software License Agreement shall pertain
to the government’s use and disclosure of the Program and Documentation, and shall supersede any
conflicting contractual terms or conditions. If this license fails to meet the government’s minimum needs or
is inconsistent in any respect with federal procurement law, the government agrees to return the Program
and Documentation, unused, to MathWorks.
MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and
Target Language Compiler is a trademark of The MathWorks, Inc.
Other product or brand names are trademarks or registered trademarks of their respective holders.
Printing History: October 1998 First printing Revised for Simulink 3.0 (Release 11)
November 2000 Second printing Revised for Simulink 4.0 (Release 12)
June 2001 Online only Revised for Simulink 4.1 (Release 12.1)
 Contents
Overview of S-Functions
1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
What Is an S-Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Using S-Functions in Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Passing Parameters to S-Functions . . . . . . . . . . . . . . . . . . . . . . 1-3
When to Use an S-Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
How S-Functions Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Implementing S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
S-Function Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
S-Function Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16

Writing M S-Functions
2
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
S-Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
S-Function Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Defining S-Function Block Characteristics . . . . . . . . . . . . . . . . 2-4
Processing S-Function Parameters . . . . . . . . . . . . . . . . . . . . . . 2-5
A Simple M-File S-Function Example . . . . . . . . . . . . . . . . . . . . 2-5

Examples of M-File S-Functions . . . . . . . . . . . . . . . . . . . . . . . . 2-8

Example - Continuous State S-Function . . . . . . . . . . . . . . . . . . 2-8
Example - Discrete State S-Function . . . . . . . . . . . . . . . . . . . . 2-11
Example - Hybrid System S-Functions . . . . . . . . . . . . . . . . . . 2-13
Example - Variable Sample Time S-Functions . . . . . . . . . . . . 2-16

i
 Writing S-Functions in C
3
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Creating C MEX S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Using the S-Function Builder . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Customizing the S-Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Setting the Include Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21

Example of a Basic C MEX S-Function . . . . . . . . . . . . . . . . . 3-22

Defines and Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
Callback Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
Simulink/Real-Time Workshop Interface . . . . . . . . . . . . . . . . . 3-26
Building the Timestwo Example . . . . . . . . . . . . . . . . . . . . . . . . 3-26

Templates for C S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

S-Function Source File Requirements . . . . . . . . . . . . . . . . . . . 3-28
The SimStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Compiling C S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31

How Simulink Interacts with C S-Functions . . . . . . . . . . . . 3-32

Process View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Data View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36

Writing Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40

Converting Level 1 C MEX S-Functions to Level 2 . . . . . . . 3-41

Obsolete Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43

Creating C++ S-Functions

4
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Source File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

ii Contents
 Making C++ Objects Persistent . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Building C++ S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

Creating Ada S-Functions

5
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Ada S-Function Source File Format . . . . . . . . . . . . . . . . . . . . . 5-3

Ada S-Function Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Ada S-Function Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Writing Callback Methods in Ada . . . . . . . . . . . . . . . . . . . . . . . 5-6

Callbacks Invoked By Simulink . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Implementing Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Omitting Optional Callback Methods . . . . . . . . . . . . . . . . . . . . . 5-7
SimStruct Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Building an Ada S-Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

Using an Ada S-Function in a Model . . . . . . . . . . . . . . . . . . . 5-10

Example of an Ada S-Function . . . . . . . . . . . . . . . . . . . . . . . . 5-11

Creating Fortran S-Functions

6
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Level 1 Versus Level 2 S-Functions . . . . . . . . . . . . . . . . . . . . . . 6-2

Creating Level 1 Fortran S-Functions . . . . . . . . . . . . . . . . . . . 6-3

The Fortran MEX Template File . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

iii
 Inline Code Generation Example . . . . . . . . . . . . . . . . . . . . . . . . 6-6

Creating Level 2 Fortran S-Functions . . . . . . . . . . . . . . . . . . . 6-7

Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
C/Fortran Interfacing Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Constructing the Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
An Example C-MEX S-Function Calling Fortran Code . . . . . . 6-13

Porting Legacy Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15

Find the States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Sample Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Multiple Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Use Flints If Needed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
Considerations for Real Time . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16

Implementing Block Features

7
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Dialog Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Tunable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

Creating Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Updating Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Input and Output Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

Creating Input Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Creating Output Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Scalar Expansion of Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Masked Multiport S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Custom Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15

iv Contents
 Sample Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
Block-Based Sample Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
Port-Based Sample Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19
Specifying the Number of Sample Times in mdlInitializeSizes 7-20
Hybrid Block-Based and Port-Based Sample Times . . . . . . . . 7-20
Multirate S-Function Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21
Synchronizing Multirate S-Function Blocks . . . . . . . . . . . . . . 7-22

Work Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24

Work Vectors and Zero Crossings . . . . . . . . . . . . . . . . . . . . . . . 7-26
An Example Involving a Pointer Work Vector . . . . . . . . . . . . . 7-26
Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-28

Function-Call Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-29

Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-31

Exception Free Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-31
ssSetErrorStatus Termination Criteria . . . . . . . . . . . . . . . . . . 7-32
Checking Array Bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-33

S-Function Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-34

Example - Continuous State S-Function . . . . . . . . . . . . . . . . . 7-34
Example - Discrete State S-Function . . . . . . . . . . . . . . . . . . . . 7-38
Example - Hybrid System S-Functions . . . . . . . . . . . . . . . . . . . 7-42
Example - Variable Step S-Function . . . . . . . . . . . . . . . . . . . . . 7-46
Example - Zero Crossing S-Function . . . . . . . . . . . . . . . . . . . . 7-49
Example - Time Varying Continuous Transfer Function . . . . 7-61

Writing S-Functions for Real-Time Workshop

8
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Classes of Problems Solved by S-Functions . . . . . . . . . . . . . . . . 8-2
Types of S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Basic Files Required for Implementation . . . . . . . . . . . . . . . . . . 8-5

v
 Noninlined S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
S-Function Module Names for Real-Time Workshop Builds . . . 8-7

Writing Wrapper S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

The MEX S-Function Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
The TLC S-Function Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
The Inlined Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

Fully Inlined S-Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Multiport S-Function Example . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Fully Inlined S-Function with the mdlRTW Routine . . . . . 8-21

S-Function RTWdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
The Direct-Index Lookup Table Algorithm . . . . . . . . . . . . . . . . 8-23
The Direct-Index Lookup Table Example . . . . . . . . . . . . . . . . . 8-24

S-Function Callback Methods

9
Callback Method Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
mdlCheckParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
mdlDerivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
mdlGetTimeOfNextVarHit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
mdlInitializeConditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
mdlInitializeSampleTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
mdlInitializeSizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
mdlOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
mdlProcessParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
mdlRTW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
mdlSetDefaultPortComplexSignals . . . . . . . . . . . . . . . . . . . . . 9-21
mdlSetDefaultPortDataTypes . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22
mdlSetDefaultPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . 9-23
mdlSetInputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . . . 9-24
mdlSetInputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25
mdlSetInputPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . . . 9-26
mdlSetInputPortFrameData . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-28
mdlSetInputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . . 9-29

vi Contents
 mdlSetInputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-31
mdlSetOutputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . 9-32
mdlSetOutputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-33
mdlSetOutputPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . . 9-34
mdlSetOutputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . 9-36
mdlSetOutputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-37
mdlSetWorkWidths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-38
mdlStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-39
mdlTerminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-40
mdlUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-41
mdlZeroCrossings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-42

SimStruct Functions
10
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
The SimStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

SimStruct Macros and Functions Listed by Usage . . . . . . . 10-3

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Error Handling and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
I/O Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Dialog Box Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
Run-Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7
Sample Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
State and Work Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
Simulation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Real-Time Workshop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13

Macro Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15

ssCallExternalModeFcn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
ssCallSystemWithTid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
ssGetAbsTol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
ssGetBlockReduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19

vii
 ssGetContStateAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
ssGetContStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
ssGetDataTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
ssGetDataTypeId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
ssGetDataTypeSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
ssGetDataTypeZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
ssGetDiscStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
ssGetDTypeIdFromMxArray . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
ssGetDWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
ssGetDWorkComplexSignal . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
ssGetDWorkDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
ssGetDWorkName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
ssGetDWorkUsedAsDState . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
ssGetDWorkWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
ssGetdX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
ssGetErrorStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-36
ssGetInputPortBufferDstPort . . . . . . . . . . . . . . . . . . . . . . . . . 10-37
ssGetInputPortConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38
ssGetInputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . . . 10-39
ssGetInputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40
ssGetInputPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . . . 10-41
ssGetInputPortDimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-42
ssGetInputPortDirectFeedThrough . . . . . . . . . . . . . . . . . . . . 10-43
ssGetInputPortFrameData . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-44
ssGetInputPortNumDimensions . . . . . . . . . . . . . . . . . . . . . . . 10-45
ssGetInputPortOffsetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-46
ssGetInputPortOverWritable . . . . . . . . . . . . . . . . . . . . . . . . . 10-47
ssGetInputPortRealSignal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-48
ssGetInputPortRealSignalPtrs . . . . . . . . . . . . . . . . . . . . . . . . 10-49
ssGetInputPortRequiredContiguous . . . . . . . . . . . . . . . . . . . . 10-50
ssGetInputPortReusable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-51
ssGetInputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . . 10-52
ssGetInputPortSampleTimeIndex . . . . . . . . . . . . . . . . . . . . . 10-53
ssGetInputPortSignal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-54
ssGetInputPortSignalAddress . . . . . . . . . . . . . . . . . . . . . . . . . 10-56
ssGetInputPortSignalPtrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-57
ssGetInputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-58
ssGetIWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-59
ssGetModelName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-60
ssGetModeVector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-61

viii Contents
ssGetModeVectorValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-62
ssGetNonsampledZCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-63
ssGetNumContStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-64
ssGetNumDataTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-65
ssGetNumDiscStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-66
ssGetNumDWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-67
ssGetNumInputPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-68
ssGetNumIWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-69
ssGetNumModes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-70
ssGetNumNonsampledZCs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-71
ssGetNumOutputPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-72
ssGetNumParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-73
ssGetNumRunTimeParams . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-74
ssGetNumPWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-75
ssGetNumRWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-76
ssGetNumSampleTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-77
ssGetNumSFcnParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-78
ssGetOutputPortBeingMerged . . . . . . . . . . . . . . . . . . . . . . . . 10-79
ssGetOutputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . . 10-80
ssGetOutputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-81
ssGetOutputPortDimensions . . . . . . . . . . . . . . . . . . . . . . . . . 10-82
ssGetOutputPortFrameData . . . . . . . . . . . . . . . . . . . . . . . . . . 10-83
ssGetOutputPortNumDimensions . . . . . . . . . . . . . . . . . . . . . 10-84
ssGetOutputPortOffsetTime . . . . . . . . . . . . . . . . . . . . . . . . . . 10-85
ssGetOutputPortRealSignal . . . . . . . . . . . . . . . . . . . . . . . . . . 10-86
ssGetOutputPortReusable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-87
ssGetOutputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . 10-88
ssGetOutputPortSignal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-89
ssGetOutputPortSignalAddress . . . . . . . . . . . . . . . . . . . . . . . 10-90
ssGetOutputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-91
ssGetPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-92
ssGetParentSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-93
ssGetPlacementGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-94
ssGetPWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-95
ssGetRealDiscStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-96
ssGetRootSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-97
ssGetRunTimeParamInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-98
ssGetRWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-99
ssGetSampleTimeOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-100
ssGetSampleTimePeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-101

ix
 ssGetSFcnParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-102
ssGetSFcnParamsCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-103
ssGetSimMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-104
ssGetSolverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-105
ssGetSolverName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-106
ssGetStateAbsTol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-107
ssGetT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-108
ssGetTNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-109
ssGetTaskTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-110
ssGetTFinal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-111
ssGetTStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-112
ssGetUserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-113
ssIsContinuousTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-114
ssIsFirstInitCond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-115
ssIsMajorTimeStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-116
ssIsMinorTimeStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-117
ssIsSampleHit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-118
ssIsSpecialSampleHit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-119
ssIsVariableStepSolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-120
ssPrintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-121
ssRegAllTunableParamsAsRunTimeParams . . . . . . . . . . . . 10-122
ssRegisterDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-123
ssSetBlockReduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-124
ssSetCallSystemOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-125
ssSetDataTypeSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-126
ssSetDataTypeZero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-127
ssSetDWorkComplexSignal . . . . . . . . . . . . . . . . . . . . . . . . . . 10-129
ssSetDWorkDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-130
ssSetDWorkName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-131
ssSetDWorkUsedAsDState . . . . . . . . . . . . . . . . . . . . . . . . . . 10-132
ssSetDWorkWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-133
ssSetErrorStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-134
ssSetExternalModeFcn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-135
ssSetInputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . . 10-136
ssSetInputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-137
ssSetInputPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . . . 10-138
ssSetInputPortFrameData . . . . . . . . . . . . . . . . . . . . . . . . . . 10-140
ssSetInputPortDirectFeedThrough . . . . . . . . . . . . . . . . . . . . 10-141
ssSetInputPortMatrixDimensions . . . . . . . . . . . . . . . . . . . . 10-142
ssSetInputPortOffsetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-143

x Contents
ssSetInputPortOverWritable . . . . . . . . . . . . . . . . . . . . . . . . . 10-144
ssSetInputPortReusable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-145
ssSetInputPortRequiredContiguous . . . . . . . . . . . . . . . . . . . 10-147
ssSetInputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . 10-148
ssSetInputPortSampleTimeIndex . . . . . . . . . . . . . . . . . . . . . 10-149
ssSetInputPortVectorDimension . . . . . . . . . . . . . . . . . . . . . . 10-150
ssSetInputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-151
ssSetModeVectorValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-152
ssSetNumContStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-153
ssSetNumDiscStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-154
ssSetNumDWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-155
ssSetNumInputPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-156
ssSetNumIWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-157
ssSetNumModes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-158
ssSetNumNonsampledZCs . . . . . . . . . . . . . . . . . . . . . . . . . . 10-159
ssSetNumOutputPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-160
ssSetNumPWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-161
ssSetNumRunTimeParams . . . . . . . . . . . . . . . . . . . . . . . . . . 10-162
ssSetNumRWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-163
ssSetNumSampleTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-164
ssSetNumSFcnParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-165
ssSetOffsetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-166
ssSetOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-167
ssSetOutputPortComplexSignal . . . . . . . . . . . . . . . . . . . . . . 10-171
ssSetOutputPortDataType . . . . . . . . . . . . . . . . . . . . . . . . . . 10-172
ssSetOutputPortDimensionInfo . . . . . . . . . . . . . . . . . . . . . . 10-173
ssSetOutputPortFrameData . . . . . . . . . . . . . . . . . . . . . . . . . 10-174
ssSetOutputPortMatrixDimensions . . . . . . . . . . . . . . . . . . . 10-175
ssSetOutputPortOffsetTime . . . . . . . . . . . . . . . . . . . . . . . . . 10-176
ssSetOutputPortReusable . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-177
ssSetOutputPortSampleTime . . . . . . . . . . . . . . . . . . . . . . . . 10-178
ssSetOutputPortVectorDimension . . . . . . . . . . . . . . . . . . . . 10-179
ssSetOutputPortWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-180
ssSetParameterName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-181
ssSetParameterTunable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-182
ssSetPlacementGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-183
ssSetRunTimeParamInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-184
ssSetSampleTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-187
ssSetSFcnParamNotTunable . . . . . . . . . . . . . . . . . . . . . . . . 10-188
ssSetSFcnParamTunable . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-189

xi
 ssSetSolverNeedsReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-190
ssSetStopRequested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-192
ssSetTNext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-193
ssSetUserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-194
ssSetVectorMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-195
ssUpdateAllTunableParamsAsRunTimeParams . . . . . . . . . 10-196
ssUpdateRunTimeParamData . . . . . . . . . . . . . . . . . . . . . . . 10-197
ssUpdateRunTimeParamInfo . . . . . . . . . . . . . . . . . . . . . . . . 10-198
ssWarning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-199
ssWriteRTWMxVectParam . . . . . . . . . . . . . . . . . . . . . . . . . . 10-200
ssWriteRTWMx2dMatParam . . . . . . . . . . . . . . . . . . . . . . . . 10-201
ssWriteRTWParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-202
ssWriteRTWParamSettings . . . . . . . . . . . . . . . . . . . . . . . . . 10-206
ssWriteRTWScalarParam . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-210
ssWriteRTWStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-211
ssWriteRTWStrParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-212
ssWriteRTWStrVectParam . . . . . . . . . . . . . . . . . . . . . . . . . . 10-213
ssWriteRTWVectParam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-214
ssWriteRTWWorkVect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-215
ssWriteRTW2dMatParam . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-216

xii Contents
 1

Overview of S-Functions

Introduction . . . . . . . . . . . . . . . . . . . . 1-2
What Is an S-Function? . . . . . . . . . . . . . . . . 1-2
Using S-Functions in Models . . . . . . . . . . . . . . 1-2
Passing Parameters to S-Functions . . . . . . . . . . . 1-3
When to Use an S-Function . . . . . . . . . . . . . . 1-5
How S-Functions Work . . . . . . . . . . . . . . . . 1-5
Implementing S-Functions . . . . . . . . . . . . . . . 1-9
S-Function Concepts . . . . . . . . . . . . . . . . 1-11
S-Function Examples . . . . . . . . . . . . . . . . 1-16
1 Overview of S-Functions

Introduction
S-functions (system-functions) provide a powerful mechanism for extending
the capabilities of Simulink®. The introductory sections of this chapter describe
what an S-function is and when and why you might use one. This chapter then
presents a comprehensive description of how to write your own S-functions.
S-functions allow you to add your own blocks to Simulink models. You can
create your blocks in MATLAB®, C, C++, Fortran, or Ada. By following a set of
simple rules, you can implement your algorithms in an S-function. After you
have written your S-function and placed its name in an S-Function block
(available in the Functions & Tables block library), you can customize the user
interface by using masking.
S-functions can be used with the Real-Time Workshop. You can also customize
the code generated by the Real Time Workshop® for S-functions by writing a
Target Language CompilerTM (TLC) file. See the Target Language Compiler
Reference Guide and the Real-Time Workshop User’s Guide for more
information.

What Is an S-Function?
An S-function is a computer language description of a Simulink block.
S-functions can be written in MATLAB, C, C++, Ada, or Fortran. C, C++, Ada,
and Fortran S-functions are compiled as MEX-files using the mex utility
described in the Application Program Interface Guide. As with other MEX-files,
they are dynamically linked into MATLAB when needed.
S-functions use a special calling syntax that enables you to interact with
Simulink’s equation solvers. This interaction is very similar to the interaction
that takes place between the solvers and built-in Simulink blocks. The form of
an S-function is very general and can accommodate continuous, discrete, and
hybrid systems.

Using S-Functions in Models

To incorporate an S-function into an Simulink model, drag an S-Function block
from Simulink’s Functions & Tables block library into the model. Then specify
the name of the S-function in the S-function name field of the S-Function
block’s dialog box as illustrated in the figure below.

1-2
 Introduction

S-Function dialog box

S-function
source file

A model that includes /*

* MYSFUN
two S-Function blocks *
*/
/* The follo
#define S_FU
.
.
.
S-Function1 dialog box
C MEX-file
or

function[sys
% mysfun M-file
%
switch(flag)
.
.
.

M-file

Figure 1-1: The Relationship Between an S-Function Block, Its Dialog Box,
and the Source File That Defines the Block’s Behavior

In this example, the model contains two instances of an S-Function block. Both
blocks reference the same source file (mysfun, which can be either a C MEX-file
or an M-file). If both a C MEX-file and an M-file exist with the same name, the
C MEX-file takes precedence and is the file that the S-function uses.

Passing Parameters to S-Functions

The S-function block’s S-function parameters field allows you to specify
parameter values to be passed to the corresponding S-function. To use this
field, you must know what parameters the S-function requires and the order in
which the function requires them. (If you do not know, consult the S-function’s

1-3
1 Overview of S-Functions

author, documentation, or source code.) Enter each parameter, separated by a

comma, in the order required by the S-function. The parameter values may be
constants, names of variables defined in the model’s workspace, or MATLAB
expressions.
The following example illustrates usage of the S-function parameters field to
enter user-define parameters

The model in this example incorporates limintm, a sample S-function that

comes with Simulink. The function’s source code resides in toolbox/simulink/
blocks. The limintm function accepts three parameters: a lower bound, an
upper bound, and an initial condition. It outputs the time integral of the input
signal, if the time integral is between the lower and upper bounds, the lower
bound if the time-integral is less than the lower bound, and the upper bound if
the time-integral is greater than the upper bound. The dialog box in the
example specifies a lower and upper bound and an initial condition of 2, 3, and
1, respectively. The scope shows the resulting output when the input is a
constant 1.
See “Processing S-Function Parameters” on page 2-5 and “Handling Errors” on
page 7-31 for information on how to access user-specified parameters in an
S-function.

1-4
 Introduction

You can use Simulink’s masking facility to create custom dialog boxes and
icons for your S-function blocks. Masked dialog boxes can make it easier to
specify additional parameters for S-functions. For discussions of additional
parameters and masking, see Using Simulink.

When to Use an S-Function

The most common use of S-functions is to create custom Simulink blocks. You
can use S-functions for a variety of applications, including:

• Adding new general purpose blocks to Simulink

• Adding blocks that represent hardware device drivers
• Incorporating existing C code into a simulation
• Describing a system as a mathematical set of equations
• Using graphical animations (see the inverted pendulum demo, penddemo)

An advantage of using S-functions is that you can build a general purpose block
that you can use many times in a model, varying parameters with each
instance of the block.

How S-Functions Work

To create S-functions, you need to know how S-functions work. Understanding
how S-functions work, in turn, requires understanding how Simulink
simulates a model, and this, in turn requires an understanding of the
mathematics of blocks. This section therefore begins by explaining the
mathematical relationship between a block’s inputs, states, and outputs.

Mathematics of Simulink Blocks

A Simulink block consists of a set of inputs, a set of states, and a set of outputs
where the outputs are a function of the sample time, the inputs, and the block’s
states.

u x y
(input) (states) (output)

1-5
1 Overview of S-Functions

The following equations express the mathematical relationships between the

inputs, outputs, and the states.

y = f 0 ( t, x, u ) (output)

x· c = f d ( t, x, u ) (derivative)

x d k + 1 = f u ( t, x, u ) (update)

where x = xc + xd

Simulation Stages
Execution of a Simulink model proceeds in stages. First comes the
initialization phase. In this phase, Simulink incorporates library blocks into
the model, propagates widths, data types, and sample times, evaluates block
parameters, determines block execution order, and allocates memory. Then
Simulink enters a simulation loop, where each pass through the loop is referred
to as a simulation step. During each simulation step, Simulink executes each
of the model’s blocks in the order determined during initialization. For each
block, Simulink invokes functions that compute the block’s states, derivatives,
and outputs for the current sample time. This continues until the simulation is
complete.

1-6
 Introduction

The figure below illustrates the stages of a simulation.

Initialize model

Calculate time of next sample hit

(only for variable sample time blocks)

Calculate outputs

Update discrete states

Simulation loop

Clean up at final
time step.
Calculate derivatives
Calculate derivatives

Calculate outputs
Integration
(minor time step)
Calculate derivatives

Locate zero crossings

Figure 1-2: How Simulink Performs Simulation

1-7
1 Overview of S-Functions

S-Function Callback Methods

An S-function comprises a set of S-function callback methods that perform
tasks required at each simulation stage. During simulation of model, at each
simulation stage, Simulink calls the appropriate methods for each S-function
block in the model. Tasks performed by S-function methods include:

• Initialization — Prior to the first simulation loop, Simulink initializes the

S-function. During this stage, Simulink:
- Initializes the SimStruct, a simulation structure that contains
information about the S-function.
- Sets the number and dimensions of input and output ports.
- Sets the block sample time(s).
- Allocates storage areas and the sizes array.
• Calculation of next sample hit — If you’ve created a variable sample time
block, this stage calculates the time of the next sample hit, that is, it
calculates the next step size.
• Calculation of outputs in the major time step — After this call is complete,
all the output ports of the blocks are valid for the current time step.
• Update discrete states in the major time step — In this call, all blocks should
perform once-per-time-step activities such as updating discrete states for
next time around the simulation loop.
• Integration — This applies to models with continuous states and/or
nonsampled zero crossings. If your S-function has continuous states,
Simulink calls the output and derivative portions of your S-function at minor
time steps. This is so Simulink can compute the state(s) for your S-function.
If your S-function (C MEX only) has nonsampled zero crossings, then
Simulink will call the output and zero crossings portion of your S-function at
minor time steps, so that it can locate the zero crossings.

Note See “How Simulink Works” in “Using Simulink” for an explanation of

major and minor time steps.

1-8
 Introduction

Implementing S-Functions
You can implement an S-function as either an M-file or a MEX file. The
following sections describes these alternative implementations and discusses
the advantages of each.

M-file S-Functions
An M-file S-function consists of a MATLAB function of the following form
[sys,x0,str,ts]=f(t,x,u,flag,p1,p2,...)

where f is the S-function’s name, t is the current time, x is the state vector of
the corresponding S-function block, u is the block’s inputs, flag indicates a task
to be performed, and p1, p2, ... are the block’s parameters. During simulation
of a model, Simulink repeatedly invokes f, using flag to indicate the task to be
performed for a particular invocation. Each time the S-function performs the
task, it returns the result in a structure having the format shown in the syntax
example.
A template implementation of an M-file S-function, sfuntmpl.m, resides in
matlabroot/toolbox/simulink/blocks. The template consists of a top-level
function and a set of skeletal subfunctions, each of which corresponds to a
particular value of flag. The top-level function simply invokes the subfunction
indicated by flag. The subfunctions, called S-function callback methods,
perform the actual tasks required of the S-function during simulation. The
following table lists the contents of an M-file S-function that follows this
standard format.

Table 1-1: M-File S-Function Routines

Simulation Stage S-Function Routine Flag

Initialization mdlInitializeSizes flag = 0

Calculation of next sample mdlGetTimeOfNextVarHit flag = 4

hit (variable sample time
block only)

Calculation of outputs mdlOutputs flag = 3

Update discrete states mdlUpdate flag = 2

1-9
1 Overview of S-Functions

Table 1-1: M-File S-Function Routines (Continued)

Simulation Stage S-Function Routine Flag

Calculation of derivatives mdlDerivatives flag = 1

End of simulation tasks mdlTerminate flag = 9

We recommend that you follow the structure and naming conventions of the
template when creating M-file S-functions. This will make it easier for others
to understand and maintain M-file S-functions that you create. See Chapter 2,
“Writing M S-Functions” for information on creating M-file S-functions.

MEX-file S-Functions
Like an M-file S-function, a MEX-file function consists of a set of callback
routines that Simulink invokes to perform various block-related tasks during
a simulation. Significant differences exist, however. For one, MEX-file
functions are implemented in a different programming language: C, C++, Ada,
or Fortran. Also, Simulink invokes MEX S-function routines directly instead of
via a flag value as with M-file S-functions. Because Simulink invokes the
functions directly, MEX-file functions must follow standard naming
conventions specified by Simulink.
Other key differences exist. For one, the set of callback functions that MEX
functions can implement is much larger than that can be implemented by
M-file functions. Also, an MEX function has direct access to the internal data
structure, called the SimStruct, that Simulink uses to maintain information
about the S-function. MEX-file functions can also use MATLAB’s MEX-file API
to access the MATLAB workspace directly.
A C MEX-file S-function template, called sfuntmpl_basic.c, resides in the
matlabroot/simulink/src directory. The template contains skeletal
implementations of all the required and optional callback routines that a C
MEX-file S-function can implement. For a more amply commented version of
the template, see sfuntmpl_doc.c in the same directory.

MEX-file Versus M-file S-Functions

M-file and MEX file S-functions each have advantages. The advantage of M-file
S-functions is speed of development. Developing M-file S-functions avoids the
time-consuming compile-link-execute cycle required by development in a

1-10
 Introduction

compiled language. M-file S-functions also have easier access to MATLAB and
toolbox functions.
The primary advantage of MEX file functions is versatility. The larger number
of callbacks and access to the SimStruct enable MEX-file functions to
implement functionality not accessible to M-file S-functions. Such functionality
includes the ability to handle data types other than double, complex inputs,
matrix inputs, and so on.

S-Function Concepts
Understanding these key concepts should enable you to build S-functions
correctly:

• Direct feedthrough
• Dynamically sized inputs
• Setting sample times and offsets

Direct Feedthrough
Direct feedthrough means that the output (or the variable sample time for
variable sample time blocks) is controlled directly by the value of an input port.
A good rule of thumb is that an S-function input port has direct feedthrough if:

• The output function (mdlOutputs or flag==3) is a function of the input u.

That is, there is direct feedthrough if the input u is accessed in mdlOutputs.
Outputs may also include graphical outputs, as in the case of an XY Graph
scope.
• The “time of next hit” function (mdlGetTimeOfNextVarHit or flag==4) of a
variable sample time S-function accesses the input u.

An example of a system that requires its inputs (i.e., has direct feedthrough) is
the operation y = k × u , where u is the input, k is the gain, and y is the output.
An example of a system that does not require its inputs (i.e., does not have
direct feedthrough) is this simple integration algorithm
Outputs: y = x
Derivative: x· = u
where x is the state, x· is the state derivative with respect to time, u is the input
and y is the output. Note that x· is the variable that Simulink integrates. It is

1-11
1 Overview of S-Functions

very important to set the direct feedthrough flag correctly because it affects the
execution order of the blocks in your model and is used to detect algebraic loops.

Dynamically Sized Arrays

S-functions can be written to support arbitrary input dimensions. In this case,
the actual input dimensions are determined dynamically when a simulation is
started by evaluating the dimensions of the input vector driving the S-function.
The input dimensions can also be used to determine the number of continuous
states, the number of discrete states, and the number of outputs.
M-file S-functions can have only one input port and that input port can accept
only one-dimensional (vector) signals. However, the signals can be of varying
width.Within an M-file S-function, to indicate that the input width is
dynamically sized, specify a value of -1 for the appropriate fields in the sizes
structure, which is returned during the mdlInitializeSizes call. You can
determine the actual input width when your S-function is called by using
length(u). If you specify a width of 0, then the input port will be removed from
the S-function block.
A C S-function can have multiple I/O ports and the ports can have different
dimensions. The number of dimensions and the size of each dimension can be
determined dynamically.
For example, the illustration below shows two instances of the same
S-Function block in a model.

The upper S-Function block is driven by a block with a three-element output

vector. The lower S-Function block is driven by a block with a scalar output. By
specifying that the S-Function block has dynamically sized inputs, the same
S-function can accommodate both situations. Simulink automatically calls the
block with the appropriately sized input vector. Similarly, if other block
characteristics, such as the number of outputs or the number of discrete or

1-12
 Introduction

continuous states, are specified as dynamically sized, Simulink defines these

vectors to be the same length as the input vector.
C S-functions give you more flexibility in specifying the widths of input and
output ports. See “Input and Output Ports” on page 7–9.

Setting Sample Times and Offsets

Both M-file and C MEX S-functions allow a high degree of flexibility in
specifying when an S-function executes. Simulink provides the following
options for sample times:

• Continuous sample time — For S-functions that have continuous states and/
or nonsampled zero crossings (see “How Simulink Works” in Using Simulink
for explanation of zero crossings). For this type of S-function, the output
changes in minor time steps.
• Continuous but fixed in minor time step sample time — For S-functions that
need to execute at every major simulation step, but do not change value
during minor time steps.
• Discrete sample time — If your S-Function block’s behavior is a function of
discrete time intervals, you can define a sample time to control when
Simulink calls the block. You can also define an offset that delays each
sample time hit. The value of the offset cannot exceed the corresponding
sample time.
A sample time hit occurs at time values determined by this formula
TimeHit = (n * period) + offset

where n, an integer, is the current simulation step. The first value of n is

always zero.
If you define a discrete sample time, Simulink calls the S-function mdlOutput
and mdlUpdate routines at each sample time hit (as defined in the above
equation).
• Variable sample time — A discrete sample time where the intervals between
sample hits can vary. At the start of each simulation step, S-functions with
variable sample times are queried for the time of next hit.
• Inherited sample time — Sometimes an S-Function block has no inherent
sample time characteristics (that is, it is either continuous or discrete,
depending on the sample time of some other block in the system). You can

1-13
1 Overview of S-Functions

specify that the block’s sample time is inherited. A simple example of this is
a Gain block that inherits its sample time from the block driving it.

A block can inherit its sample time from:

- The driving block
- The destination block
- The fastest sample time in the system
To set a block’s sample time as inherited, use -1 in M-file S-functions and
INHERITED_SAMPLE_TIME in C S-functions as the sample time. For more
information on the propagation of sample times, see “Sample Time Colors” in
Using Simulink.
S-functions can be either single or multirate; a multirate S-function has
multiple sample times.
Sample times are specified in pairs in this format: [sample_time,
offset_time]. The valid sample time pairs are
[CONTINUOUS_SAMPLE_TIME, 0.0]
[CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
[discrete_sample_time_period, offset]
[VARIABLE_SAMPLE_TIME, 0.0]

where
CONTINUOUS_SAMPLE_TIME = 0.0
FIXED_IN_MINOR_STEP_OFFSET = 1.0
VARIABLE_SAMPLE_TIME = -2.0

and the italics indicate a real value is required.

Alternatively, you can specify that the sample time is inherited from the
driving block. In this case the S-function can have only one sample time pair
[INHERITED_SAMPLE_TIME, 0.0]

or
[INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

where
INHERITED_SAMPLE_TIME = -1.0

1-14
 Introduction

The following guidelines may help you specify sample times:

• A continuous S-function that changes during minor integration steps should

register the [CONTINUOUS_SAMPLE_TIME, 0.0] sample time.
• A continuous S-function that does not change during minor integration steps
should register the
[CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.
• A discrete S-function that changes at a specified rate should register the
discrete sample time pair, [discrete_sample_time_period, offset],
where
discrete_sample_period > 0.0

and
0.0 ≤ offset < discrete_sample_period

• A discrete S-function that changes at a variable rate should register the

variable step discrete sample time.
[VARIABLE_SAMPLE_TIME, 0.0]

The mdlGetTimeOfNextVarHit routine is called to get the time of the next

sample hit for the variable step discrete task.
If your S-function has no intrinsic sample time, then you must indicate that
your sample time is inherited. There are two cases:

• An S-function that changes as its input changes, even during minor

integration steps, should register the [INHERITED_SAMPLE_TIME, 0.0]
sample time.
• An S-function that changes as its input changes, but doesn’t change during
minor integration steps (that is, remains fixed during minor time steps),
should register the
[INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.

The Scope block is a good example of this type of block. This block should run
at the rate, either continuous or discrete, of its driving block, but should
never run in minor step. If it did, the scope display would show the
intermediate computations of the solver rather than the final result at each
time point.

1-15
1 Overview of S-Functions

S-Function Examples
Simulink comes with a library of S-function examples.
To run an example:

1 Enter sfundemos at the MATLAB command line.

MATLAB displays the S-function demo library.

Each block represents an S-function example.

2 Click on a block to open and run the example that it represents.

It may be helpful to examine some sample S-functions as you read the next
chapters. Code for the examples are stored in these subdirectories under the
MATLAB root directory:

• M-files: toolbox/simulink/blocks
• C, C++, and Fortran: simulink/src
• Ada: simulink/ada/examples

1-16
 Introduction

M-File S-Function Examples

The simulink/blocks directory contains many M-file S-functions. Consider
starting off by looking at these files.

Filename Description

csfunc.m Defines a continuous system in state-space format.

dsfunc.m Defines a discrete system in state-space format.
vsfunc.m Illustrates how to create a variable sample time
block. This block implements a variable step delay
in which the first input is delayed by an amount of
time determined by the second input.
mixed.m Implements a hybrid system consisting of a
continuous integrator in series with a unit delay.
vdpm.m Implements the Van der Pol equation (similar to
the demo model, vdp).
simom.m An example state-space M-file S-function with
internal A, B, C, and D matrices. This S-function
implements
dx/at = Ax + By
y = Cx + Du

where x is the state vector, u is the input vector, and

y is the output vector. The A, B, C, and D matrices
are embedded in the M-file.
simom2.m An example state-space M-file S-function with
external A, B, C, and D matrices. The state-space
structure is the same as in simom.m, but the A, B, C,
and D matrices are provided externally as
parameters to this file.
limintm.m Implements a continuous limited integrator where
the output is bounded by lower and upper bounds
and includes initial conditions.

1-17
1 Overview of S-Functions

Filename Description

sfun_varargm.m This is an example M-file S-function showing how to

use the MATLAB vararg facility.
vlimintm.m An example of a continuous limited integrator
S-function. This illustrates how to use the size entry
of −1 to build an S-function that can accommodate a
dynamic input/state width.
vdlimintm.m An example of a discrete limited integrator
S-function. This example is identical to vlimint.m,
except that the limited integrator is discrete.

C S-Function Examples
The simulink/src directory also contains examples of C MEX S-functions,
many of which have an M-file S-function counterpart. These C MEX
S-functions are listed in this table.

Filename Description

barplot.c Access simulink signals without using the

standard block inputs.
csfunc.c An example C MEX S-function for defining a
continuous system.
dlimint.c Implements a discrete-time limited integrator.
dsfunc.c An example C MEX S-function for defining a
discrete system.
fcncallgen.c Executes function-call subsystems ntimes at the
designated rate (sample time).
limintc.c Implements a limited integrator.
mixedm.c Implements a hybrid dynamic system consisting
of a continuous integrator (1/s) in series with a
unit delay (1/z).

1-18
 Introduction

Filename Description

mixedmex.c Implements a hybrid dynamic system with a

single output and two inputs.
quantize.c An example MEX-file for a vectorized quantizer
block. Quantizes the input into steps as specified
by the quantization interval parameter, q.
resetint.c A reset integrator.
sdotproduct Compute dot product (multiply-accumulate) of
two real or complex vectors
sftable2.c A two-dimensional table lookup in S-function
form.
sfun_atol.c Sets different absolute tolerances for each
continuous state.
sfun_bitop.c Perform the bitwise operations AND, OR, XOR, left
shift, right shift and one’s complement on uint8,
uint16, and uint32 inputs.

sfun_cplx.c Complex signal add with one input port and one
parameter.
sfun_directlook.c Direct 1-D lookup.
sfun_dtype_io.c Example of the use of Simulink data types for
inputs and outputs.
sfun_dtype_param.c Example of the use of Simulink data types for
parameters.
sfun_dynsize.c A simple example of how to size outputs of an
S-function dynamically.
sfun_errhdl.c A simple example of how to check parameters
using the mdlCheckParams S-function routine.

1-19
1 Overview of S-Functions

Filename Description

sfun_fcncall.c An example of an S-function that is configured to

execute function-call subsystems on the first and
third output element.
sfun_frmad.c Frame-based A/D converter.
sfun_frmda.c frame-based D/A converter.
sfun_frmdft.c A multi-channel frame-based Discrete-Fourier
transform (and its inverse).
sfun_frmunbuff.c A frame-based unbuffer block.
sfun_multiport.c An S-function that has multiple input and output
ports.
sfun_manswitch.c Manual switch.
sfun_matadd.c Matrix add with one input port, one output port,
and one parameter.
sfun_multirate.c Demonstrates how to specify port-based sample
times.
sfun_psbbreaker.c Implements the logic for the breaker block in the
Power System Blockset.
sfun_psbcontc.c Continuous implementation of state-space system.
sfun_psbdiscc.c Discrete implementation of state-space system.
sfun_runtime1.c Run-time parameter example.
sfun_runtime2.c Run-time parameter example.
sfun_zc.c Demonstrates use of nonsampled zero crossings to
implement abs(u). This S-function is designed to
be used with a variable step solver.
sfun_zc_sat.c Saturation example that uses zero crossings.

1-20
 Introduction

Filename Description

sfunmem.c A one integration-step delay and hold “memory”

function.
simomex.c Implements a single output, two input state-space
dynamic system described by these state-space
equations
dx/dt = Ax + Bu
y = Cx + Du

where x is the state vector, u is vector of inputs,

and y is the vector of outputs.
smatrxcat.c Matrix concatenation.
sreshape.c Reshapes the input signal.
stspace.c Implements a set of state-space equations. You
can turn this into a new block by using the
S-Function block and mask facility. This example
MEX-file performs the same function as the
built-in State-Space block. This is an example of a
MEX-file where the number of inputs, outputs,
and states is dependent on the parameters passed
in from the workspace. Use this as a template for
other MEX-file systems.
stvctf.c Implements a continuous-time transfer function
whose transfer function polynomials are passed in
via the input vector. This is useful for continuous
time adaptive control applications.
stvdct.f Implements a discrete-time transfer function
whose transfer function polynomials are passed in
via the input vector. This is useful for
discrete-time adaptive control applications.
stvmgain.c Time-varying matrix gain.
table3.c 3-D lookup table.

1-21
1 Overview of S-Functions

Filename Description

timestwo.c A basic C MEX S-function that doubles its input.

vdlmint.c Implements a discrete-time vectorized limited
integrator.
vdpmex.c Implements the van der Pol equation.
vlimint.c Implements a vectorized limited integrator.
vsfunc.c Illustrates how to create a variable sample time
block in Simulink. This block implements a
variable step delay in which the first input is
delayed by an amount of time determined by the
second input.

Fortran S-Function Examples

The following table lists sample Fortran S-functions.

Filename Description

sfun_timestwo_for. A sample Level 1 Fortran representation of a C

for timestwo S-function.

sfun_atmos.c Calculation of the 1976 standard atmosphere to

86 km.
vdpmexf.for Van der Pol system.

C++ S-Function Examples

The following table lists sample C++ S-functions.

Filename Description

sfun_counter_cpp. Stores an C++ object in the pointers vector PWork.

cpp

1-22
 Introduction

Ada S-Function Examples

The simulink/ada/examples directory contains the following examples of
S-functions implemented in Ada.

Directory Name Description

matrix_gain Implements a matrix gain block.

multi_port Multiport block.
simple_lookup Lookup table. Illustrates use of a “wrapper”
S-function that “wraps” stand-alone Ada code (i.e.,
Ada packages and procedures) both for use with
Simulink as an S-function and directly with Ada
code generated using the RTW Ada Coder.
times_two Outputs twice its input.

1-23
1 Overview of S-Functions

1-24
 2

Writing M S-Functions
Introduction . . . . . . . . . . . . . . . . . . . . 2-2
S-Function Arguments . . . . . . . . . . . . . . . . 2-2
S-Function Outputs . . . . . . . . . . . . . . . . . 2-3
Defining S-Function Block Characteristics . . . . . . . . 2-4
Processing S-Function Parameters . . . . . . . . . . . 2-5
A Simple M-File S-Function Example . . . . . . . . . . 2-5

Examples of M-File S-Functions . . . . . . . . . . . . 2-8

Example - Continuous State S-Function . . . . . . . . . 2-8
Example - Discrete State S-Function . . . . . . . . . . . 2-11
Example - Hybrid System S-Functions . . . . . . . . . . 2-13
Example - Variable Sample Time S-Functions . . . . . . . 2-16
2 Writing M S-Functions

Introduction
An M-file S-function consists of a MATLAB function of the following form
[sys,x0,str,ts]=f(t,x,u,flag,p1,p2,...)

where f is the name of the S-function. During simulation of a model, Simulink

repeatedly invokes f, using the flag argument to indicate the task (or tasks)
to be performed for a particular invocation. Each time the S-function performs
the task and returns the results in an output vector.
A template implementation of an M-file S-function, sfuntmpl.m, resides in
matlabroot/toolbox/simulink/blocks. The template consists of a top-level
function and a set of skeletal subfunctions, called S-function callback methods,
each of which corresponds to a particular value of flag. The top-level function
simply invokes the subfunction indicated by flag. The subfunctions perform
the actual tasks required of the S-function during simulation.

S-Function Arguments
Simulink passes the following arguments to an S-function:

• t, the current time

• x, the state vector
• u, the input vector
• flag, an integer value that indicates the task to be performed by the
S-function

2-2
 Introduction

The following table describes the values that flag can assume and lists the
corresponding S-function method for each value.

Table 2-1: Flag Argument

Flag S-Function Routine Description

0 mdlInitializesizes Defines basic S-Function block

characteristics, including sample
times, initial conditions of
continuous and discrete states, and
the sizes array.
1 mdlDerivatives Calculates the derivatives of the
continuous state variables.
2 mdlUpdate Updates discrete states, sample
times, and major time step
requirements.
3 mdlOutputs Calculates the outputs of the
S-function.
4 mdlGetTimeOfNextVarHit Calculates the time of the next hit
in absolute time. This routine is
used only when you specify a
variable discrete-time sample time
in mdlInitializeSizes.
9 mdlTerminate Performs any necessary end of
simulation tasks.

S-Function Outputs
An M-file returns an output vector containing the following elements:

• sys, a generic return argument. The values returned depend on the flag
value. For example, for flag = 3, sys contains the S-function outputs.
• x0, the initial state values (an empty vector if there are no states in the
system). x0 is ignored, except when flag = 0.

2-3
2 Writing M S-Functions

• str, reserved for future use. M-file S-functions must set this to the empty
matrix, [].
• ts, a two column matrix containing the sample times and offsets of the block.
Continuous systems have their sample time set to zero. The hybrid example,
which starts on page 2-13, demonstrates an S-function with multiple sample
times.

Sample times should be declared in ascending order. For example, if you

want your S-function to execute at [0 0.1 0.25 0.75 1.0 1.1 1.25, etc.], set ts
equal to a two row matrix.
ts = [.25 0; 1.0 .1];

Defining S-Function Block Characteristics

For Simulink to recognize an M-file S-function, you must provide it with
specific information about the S-function. This information includes the
number of inputs, outputs, states, and other block characteristics.
To give Simulink this information, call the simsizes function at the beginning
of mdlInitializeSizes.
sizes = simsizes;

This function returns an uninitialized sizes structure. You must load the
sizes structure with information about the S-function. The table below lists
the sizes structure fields and describes the information contained in each
field.

Table 2-2: Fields in the sizes Structure

Field Name Description

sizes.NumContStates Number of continuous states

sizes.NumDiscStates Number of discrete states
sizes.NumOutputs Number of outputs
sizes.NumInputs Number of inputs
sizes.DirFeedthrough Flag for direct feedthrough
sizes.NumSampleTimes Number of sample times

2-4
 Introduction

After you initialize the sizes structure, call simsizes again.

sys = simsizes(sizes);

This passes the information in the sizes structure to sys, a vector that holds
the information for use by Simulink.

Processing S-Function Parameters

When invoking an M-file S-function, Simulink always passes the standard
block parameters, t, x, u, and flag, to the S-function as function arguments.
Simulink can pass additional, block-specific parameters specified by the user
to the S-function. The user specifies the parameters in the S-function
parameters field of the S-function’s block parameter dialog (see “Passing
Parameters to S-Functions” on page 1-3). If the block dialog specifies additional
parameters, Simulink passes the parameters to the S-function as additional
function arguments. The additional arguments follow the standard arguments
in the S-function argument list in the order in which the corresponding
parameters appear in the block dialog. You can use this block-specific
S-function parameter capability to allow the same S-function to implement
various processing options. See the limintm.m example in the toolbox/
simulink/blocks directory for an example of an S-function that uses
block-specific parameters in this way.

A Simple M-File S-Function Example

The easiest way to understand how S-functions work is to look at a simple
example. This block takes an input scalar signal, doubles it, and plots it to a
scope.

The M-file code that contains the S-function is modeled on an S-function

template called sfuntmpl.m, which is included with Simulink. By using this
template, you can create an M-file S-function that is very close in appearance
to a C MEX S-function. This is useful because it makes a transition from an
M-file to a C MEX-file much easier.
Below is the M-file code for the timestwo.m S-function.

2-5
2 Writing M S-Functions

function [sys,x0,str,ts] = timestwo(t,x,u,flag)

% Dispatch the flag. The switch function controls the calls to
% S-function routines at each simulation stage.
switch flag,

case 0
[sys,x0,str,ts] = mdlInitializeSizes; % Initialization

case 3
sys = mdlOutputs(t,x,u); % Calculate outputs

case { 1, 2, 4, 9 }
sys = []; % Unused flags

otherwise
error(['Unhandled flag = ',num2str(flag)]); % Error handling
end;
% End of function timestwo.

Below are the S-function subroutines that timestwo.m calls.

%==============================================================
% Function mdlInitializeSizes initializes the states, sample
% times, state ordering strings (str), and sizes structure.
%==============================================================
function [sys,x0,str,ts] = mdlInitializeSizes
% Call function simsizes to create the sizes structure.
sizes = simsizes;
% Load the sizes structure with the initialization information.
sizes.NumContStates= 0;
sizes.NumDiscStates= 0;
sizes.NumOutputs= 1;
sizes.NumInputs= 1;
sizes.DirFeedthrough=1;
sizes.NumSampleTimes=1;
% Load the sys vector with the sizes information.
sys = simsizes(sizes);
%
x0 = []; % No continuous states
%
str = []; % No state ordering

2-6
 Introduction

%
ts = [-1 0]; % Inherited sample time
% End of mdlInitializeSizes.
%==============================================================
% Function mdlOutputs performs the calculations.
%==============================================================
function sys = mdlOutputs(t,x,u)
sys = 2*u;

% End of mdlOutputs.

To test this S-function in Simulink, connect a sine wave generator to the input
of an S-Function block. Connect the output of the S-Function block to a Scope.
Double-click on the S-Function block to open the dialog box.

Enter the function name here. In this

example, type timestwo.

If you have additional parameters to

pass to the block, enter their names
here, separating them with commas. In
this example, there are no additional
parameters.

You can now run this simulation.

2-7
2 Writing M S-Functions

Examples of M-File S-Functions

The simple example discussed above (timestwo) has no states. Most
S-Function blocks require the handling of states, whether continuous or
discrete. The sections that follow discuss four common types of systems you can
model in Simulink using S-functions:

• Continuous
• Discrete
• Hybrid
• Variable-step

All examples are based on the M-file S-function template found in sfuntmpl.m.

Example - Continuous State S-Function

Simulink includes a function called csfunc.m, which is an example of a
continuous state system modeled in an S-function. Here is the code for the
M-file S-function.
function [sys,x0,str,ts] = csfunc(t,x,u,flag)
% CSFUNC An example M-file S-function for defining a system of
% continuous state equations:
% x' = Ax + Bu
% y = Cx + Du
%
% Generate a continuous linear system:
A=[−0.09 −0.01
1 0];
B=[ 1 −7
0 −2];
C=[ 0 2
1 −5];
D=[−3 0
1 0];
%
% Dispatch the flag.
%
switch flag,

2-8
 Examples of M-File S-Functions

case 0
[sys,x0,str,ts]=mdlInitializeSizes(A,B,C,D); % Initialization

case 1
sys = mdlDerivatives(t,x,u,A,B,C,D); % Calculate derivatives

case 3
sys = mdlOutputs(t,x,u,A,B,C,D); % Calculate outputs

case { 2, 4, 9 } % Unused flags

sys = [];
otherwise
error(['Unhandled flag = ',num2str(flag)]); % Error handling
end
% End of csfunc.
%==============================================================
% mdlInitializeSizes
% Return the sizes, initial conditions, and sample times for the
% S-function.
%==============================================================
%
function [sys,x0,str,ts] = mdlInitializeSizes(A,B,C,D)
%
% Call simsizes for a sizes structure, fill it in and convert it
% to a sizes array.
%
sizes = simsizes;
sizes.NumContStates = 2;
sizes.NumDiscStates = 0;
sizes.NumOutputs = 2;
sizes.NumInputs = 2;
sizes.DirFeedthrough = 1; % Matrix D is nonempty.
sizes.NumSampleTimes = 1;
sys = simsizes(sizes);
%
% Initialize the initial conditions.
%
x0 = zeros(2,1);
%
% str is an empty matrix.

2-9
2 Writing M S-Functions

%
str = [];
%
% Initialize the array of sample times; in this example the sample
% time is continuous, so set ts to 0 and its offset to 0.
%
ts = [0 0];
% End of mdlInitializeSizes.
%
%==============================================================
% mdlDerivatives
% Return the derivatives for the continuous states.
%==============================================================
function sys = mdlDerivatives(t,x,u,A,B,C,D)
sys = A*x + B*u;
% End of mdlDerivatives.
%
%==============================================================
% mdlOutputs
% Return the block outputs.
%==============================================================
%
function sys = mdlOutputs(t,x,u,A,B,C,D)
sys = C*x + D*u;
% End of mdlOutputs.

The above example conforms to the simulation stages discussed earlier in this
chapter. Unlike timestwo.m, this example invokes mdlDerivatives to
calculate the derivatives of the continuous state variables when flag = 1. The
system state equations are of the form
x'= Ax + Bu
y = Cx + Du

so that very general sets of continuous differential equations can be modeled

using csfunc.m. Note that csfunc.m is similar to the built-in State-Space block.
This S-function can be used as a starting point for a block that models a
state-space system with time-varying coefficients.
Each time the mdlDerivatives routine is called it must explicitly set the value
of all derivatives. The derivative vector does not maintain the values from the

2-10
 Examples of M-File S-Functions

last call to this routine. The memory allocated to the derivative vector changes
during execution.

Example - Discrete State S-Function

Simulink includes a function called dsfunc.m, which is an example of a discrete
state system modeled in an S-function. This function is similar to csfunc.m, the
continuous state S-function example. The only difference is that mdlUpdate is
called instead of mdlDerivative. mdlUpdate updates the discrete states when
the flag = 2. Note that for a single-rate discrete S-function, Simulink calls the
mdlUpdate, mdlOutput, and mdlGetTimeOfNextVarHit (if needed) routines only
on sample hits. Here is the code for the M-file S-function.
function [sys,x0,str,ts] = dsfunc(t,x,u,flag)
% An example M-file S-function for defining a discrete system.
% This S-function implements discrete equations in this form:
% x(n+1) = Ax(n) + Bu(n)
% y(n) = Cx(n) + Du(n)
%
% Generate a discrete linear system:
A=[–1.3839 –0.5097
1.0000 0];
B=[–2.5559 0
0 4.2382];
C=[ 0 2.0761
0 7.7891];
D=[ –0.8141 –2.9334
1.2426 0];

switch flag,
case 0
sys = mdlInitializeSizes(A,B,C,D); % Initialization

case 2
sys = mdlUpdate(t,x,u,A,B,C,D); % Update discrete states

case 3
sys = mdlOutputs(t,x,u,A,B,C,D); % Calculate outputs

case {1, 4, 9} % Unused flags

sys = [];

2-11
2 Writing M S-Functions

otherwise
error(['unhandled flag = ',num2str(flag)]); % Error handling
end
% End of dsfunc.

%==============================================================
% Initialization
%==============================================================

function [sys,x0,str,ts] = mdlInitializeSizes(A,B,C,D)

% Call simsizes for a sizes structure, fill it in, and convert it

% to a sizes array.

sizes = simsizes;
sizes.NumContStates = 0;
sizes.NumDiscStates = 2;
sizes.NumOutputs = 2;
sizes.NumInputs = 2;
sizes.DirFeedthrough = 1; % Matrix D is non-empty.
sizes.NumSampleTimes = 1;
sys = simsizes(sizes);
x0 = ones(2,1); % Initialize the discrete states.
str = []; % Set str to an empty matrix.
ts = [1 0]; % sample time: [period, offset]
% End of mdlInitializeSizes.

%==============================================================
% Update the discrete states
%==============================================================
function sys = mdlUpdates(t,x,u,A,B,C,D)
sys = A*x + B*u;
% End of mdlUpdate.

%==============================================================
% Calculate outputs
%==============================================================
function sys = mdlOutputs(t,x,u,A,B,C,D)
sys = C*x + D*u;

2-12
 Examples of M-File S-Functions

% End of mdlOutputs.

The above example conforms to the simulation stages discussed earlier in

chapter 1. The system discrete state equations are of the form
x(n+1) = Ax(n) + Bu(n)
y(n) = Cx(n) + Du(n)

so that very general sets of difference equations can be modeled using

dsfunc.m. This is similar to the built-in Discrete State-Space block. You can
use dsfunc.m as a starting point for modeling discrete state-space systems with
time-varying coefficients.

Example - Hybrid System S-Functions

Simulink includes a function called mixedm.m, which is an example of a hybrid
system (a combination of continuous and discrete states) modeled in an
S-function. Handling hybrid systems is fairly straightforward; the flag
parameter forces the calls to the correct S-function subroutine for the
continuous and discrete parts of the system. One subtlety of hybrid S-functions
(or any multirate S-function) is that Simulink calls the mdlUpdate, mdlOutput,
and mdlGetTimeOfNextVarHit routines at all sample times. This means that in
these routines you must test to determine which sample hit is being processed
and only perform updates that correspond to that sample hit.
mixed.m models a continuous Integrator followed by a discrete Unit Delay. In
Simulink block diagram form, the model looks like this.

Here is the code for the M-file S-function.

function [sys,x0,str,ts] = mixedm(t,x,u,flag)
% A hybrid system example that implements a hybrid system
% consisting of a continuous integrator (1/s) in series with a
% unit delay (1/z).
%
% Set the sampling period and offset for unit delay.
dperiod = 1;
doffset = 0;

2-13
2 Writing M S-Functions

switch flag,

case 0 % Initialization
[sys,x0,str,ts] = mdlInitializeSizes(dperiod,doffset);

case 1
sys = mdlDerivatives(t,x,u); % Calculate derivatives

case 2
sys = mdlUpdate(t,x,u,dperiod,doffset); % Update disc states

case 3
sys = mdlOutputs(t,x,u,doffset,dperiod); % Calculate outputs
case {4, 9}
sys = []; % Unused flags

otherwise
error(['unhandled flag = ',num2str(flag)]); % Error handling
end
% End of mixedm.
%
%==============================================================
% mdlInitializeSizes
% Return the sizes, initial conditions, and sample times for the
% S-function.
%==============================================================
function [sys,x0,str,ts] = mdlInitializeSizes(dperiod,doffset)
sizes = simsizes;
sizes.NumContStates = 1;
sizes.NumDiscStates = 1;
sizes.NumOutputs = 1;
sizes.NumInputs = 1;
sizes.DirFeedthrough = 0;
sizes.NumSampleTimes = 2;
sys = simsizes(sizes);
x0 = ones(2,1);
str = [];
ts = [0, 0 % sample time
dperiod, doffset];
% End of mdlInitializeSizes.

2-14
 Examples of M-File S-Functions

%==============================================================
% mdlDerivatives
% Compute derivatives for continuous states.
%==============================================================
%
function sys = mdlDerivatives(t,x,u)
sys = u;
% end of mdlDerivatives.
%
%==============================================================
% mdlUpdate
% Handle discrete state updates, sample time hits, and major time
% step requirements.
%==============================================================
%
function sys = mdlUpdate(t,x,u,dperiod,doffset)
% Next discrete state is output of the integrator.
% Return next discrete state if we have a sample hit within a
% tolerance of 1e-8. If we don't have a sample hit, return [] to
% indicate that the discrete state shouldn't change.
%
if abs(round((t-doffset)/dperiod)-(t-doffset)/dperiod) < 1e-8
sys = x(1); % mdlUpdate is "latching" the value of the
% continuous state, x(1), thus introducing a delay.
else
sys = []; % This is not a sample hit, so return an empty
end % matrix to indicate that the states have not
% changed.
% End of mdlUpdate.
%
%==============================================================
% mdlOutputs
% Return the output vector for the S-function.
%==============================================================
%
function sys = mdlOutputs(t,x,u,doffset,dperiod)
% Return output of the unit delay if we have a
% sample hit within a tolerance of 1e-8. If we

2-15
2 Writing M S-Functions

% don't have a sample hit then return [] indicating

% that the output shouldn't change.
%
if abs(round((t-doffset)/dperiod)-(t-doffset)/dperiod) < 1e-8
sys = x(2);

else
sys = []; % This is not a sample hit, so return an empty
end % matrix to indicate that the output has not changed

% End of mdlOutputs.

Example - Variable Sample Time S-Functions

This M-file is an example of an S-function that uses a variable sample time.
This example, in an M-file called vsfunc.m, calls mdlGetTimeOfNextVarHit
when flag = 4. Because the calculation of a next sample time depends on the
input u, this block has direct feedthrough. Generally, all blocks that use the
input to calculate the next sample time (flag = 4) require direct feedthrough.
Here is the code for the M-file S-function.
function [sys,x0,str,ts] = vsfunc(t,x,u,flag)
% This example S-function illustrates how to create a variable
% step block in Simulink. This block implements a variable step
% delay in which the first input is delayed by an amount of time
% determined by the second input.
%
% dt = u(2)
% y(t+dt) = u(t)
%
switch flag,

case 0
[sys,x0,str,ts] = mdlInitializeSizes; % Initialization

case 2
sys = mdlUpdate(t,x,u); % Update Discrete states

case 3
sys = mdlOutputs(t,x,u); % Calculate outputs

2-16
 Examples of M-File S-Functions

case 4
sys = mdlGetTimeOfNextVarHit(t,x,u); % Get next sample time

case { 1, 9 }
sys = []; % Unused flags
otherwise
error(['Unhandled flag = ',num2str(flag)]); % Error handling
end
% End of vsfunc.
%==============================================================
% mdlInitializeSizes
% Return the sizes, initial conditions, and sample times for the
% S-function.
%==============================================================
%
function [sys,x0,str,ts] = mdlInitializeSizes
%
% Call simsizes for a sizes structure, fill it in and convert it
% to a sizes array.
%
sizes = simsizes;
sizes.NumContStates = 0;
sizes.NumDiscStates = 1;
sizes.NumOutputs = 1;
sizes.NumInputs = 2;
sizes.DirFeedthrough = 1; % flag=4 requires direct feedthrough
% if input u is involved in
% calculating the next sample time
% hit.
sizes.NumSampleTimes = 1;
sys = simsizes(sizes);
%
% Initialize the initial conditions.
%
x0 = [0];
%
% Set str to an empty matrix.
%
str = [];
%

2-17
2 Writing M S-Functions

% Initialize the array of sample times.

%
ts = [–2 0]; % variable sample time
% End of mdlInitializeSizes.
%
%==============================================================
% mdlUpdate
% Handle discrete state updates, sample time hits, and major time
% step requirements.
%==============================================================
%
function sys = mdlUpdate(t,x,u)
sys = u(1);
% End of mdlUpdate.
%
%==============================================================
% mdlOutputs
% Return the block outputs.
%==============================================================
%
function sys = mdlOutputs(t,x,u)
sys = x(1);
% end mdlOutputs
%
%==============================================================
% mdlGetTimeOfNextVarHit
% Return the time of the next hit for this block. Note that the
% result is absolute time.
%==============================================================
%
function sys = mdlGetTimeOfNextVarHit(t,x,u)
sys = t + u(2);
% End of mdlGetTimeOfNextVarHit.

mdlGetTimeOfNextVarHit returns the “time of the next hit,” the time in the
simulation when vsfunc is next called. This means that there is no output from
this S-function until the time of the next hit. In vsfunc, the time of the next hit
is set to t + u(2), which means that the second input, u(2), sets the time when
the next call to vsfunc occurs.

2-18
 3
Writing S-Functions in C

Introduction . . . . . . . . . . . . . . . . . . . . 3-2
Creating C MEX S-Functions . . . . . . . . . . . . . . 3-3

Using the S-Function Builder . . . . . . . . . . . . . 3-5

Customizing the S-Function . . . . . . . . . . . . . . 3-8
Setting the Include Path . . . . . . . . . . . . . . . . 3-21

Example of a Basic C MEX S-Function . . . . . . . . . 3-22

Defines and Includes . . . . . . . . . . . . . . . . . 3-24
Callback Implementations . . . . . . . . . . . . . . . 3-24
Simulink/Real-Time Workshop Interface . . . . . . . . . 3-26
Building the Timestwo Example . . . . . . . . . . . . 3-26

Templates for C S-Functions . . . . . . . . . . . . . 3-28

S-Function Source File Requirements . . . . . . . . . . 3-28
The SimStruct . . . . . . . . . . . . . . . . . . . . 3-30
Compiling C S-Functions . . . . . . . . . . . . . . . 3-31

How Simulink Interacts with C S-Functions . . . . . . 3-32

Process View . . . . . . . . . . . . . . . . . . . . 3-32
Data View . . . . . . . . . . . . . . . . . . . . . 3-36

Writing Callback Methods . . . . . . . . . . . . . . 3-40

Converting Level 1 C MEX S-Functions to Level 2 . . . . 3-41

Obsolete Macros . . . . . . . . . . . . . . . . . . . 3-43
3 Writing S-Functions in C

Introduction
A C MEX-file that defines an S-Function block must provide information about
the model to Simulink during the simulation. As the simulation proceeds,
Simulink, the ODE solver, and the MEX-file interact to perform specific tasks.
These tasks include defining initial conditions and block characteristics, and
computing derivatives, discrete states, and outputs.
As with M-file S-functions, Simulink interacts with a C MEX-file S-function by
invoking callback methods that the S-function implements. Each method
performs a predefined task, such as computing block outputs, required to
simulate the block whose functionality the S-function defines. Simulink
defines in a general way the task of each callback. The S-function is free to
perform the task according to the functionality it implements. For example,
Simulink specifies that the S-function’s mdlOutput method must compute that
block’s outputs at the current simulation time. It does not specify what those
outputs must be. This callback-based API allows you to create S-functions, and
hence custom blocks, of any desired functionality.
The set of callback methods, hence functionality, that C MEX-files can
implement is much larger than that available for M-file S-functions. See
Chapter 9, “S-Function Callback Methods” for descriptions of the callback
methods that a C MEX-file S-function can implement. Unlike M-file
S-functions, C MEX-files can access and modify the data structure that
Simulink uses internally to store information about the S-function. The ability
to implement a broader set of callback methods and to access internal data
structures allows C-MEX files to implement a wider set of block features, such
as the ability to handle matrix signals and multiple data types.
C MEX-file S-functions are required to implement only a small subset of the
callback methods that Simulink defines. If your block does not implement a
particular feature, such as matrix signals, you are free to omit the callback
methods required to implement a feature. This allows you to create simple
blocks very quickly.
The general format of a C MEX S-function is shown below.
#define S_FUNCTION_NAME your_sfunction_name_here
#define S_FUNCTION_LEVEL 2
#include "simstruc.h"

static void mdlInitializeSizes(SimStruct *S)

3-2
 Introduction

{
}

<additional S-function routines/code>

static void mdlTerminate(SimStruct *S)

{
}
#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a
MEX-file? */
#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration
function */
#endif

mdlInitializeSizes is the first routine Simulink calls when interacting with

the S-function. Simulink subsequently invokes other S-function methods (all
starting with mdl). At the end of a simulation, Simulink calls mdlTerminate.

Note Unlike M-file S-functions, C MEX S-function methods do not each have
a flag parameter. This is because Simulink calls each S-function method
directly at the appropriate time during the simulation.

Creating C MEX S-Functions

The easiest way to create a C MEX S-function is to use the S-Function Builder
(see “Using the S-Function Builder” on page 3-5). This tool builds a C MEX
S-function from specifications and code fragments that you supply. This
eliminates the need for you to build the S-function from scratch. The S-function
Builder, however, is limited in the kinds of S-functions that it can build. For
example, it cannot build S-functions that have more than one input or output
or that must handle data types other than double. You must create such
S-functions from scratch.

3-3
3 Writing S-Functions in C

The following sections provide information on writing C MEX S-functions from

scratch:

• “Example of a Basic C MEX S-Function” on page 3-22 provides a step-by-step

example of how to write a simple S-function from scratch.
• “Templates for C S-Functions” on page 3-28 describes a complete skeletal
implementation of a C S-function that you can use as a starting point for
creating your own S-functions.

3-4
 Using the S-Function Builder

Using the S-Function Builder

The S-Function Builder is a Simulink block that builds an S-function from
specifications and C code that you supply. The S-Function Builder also serves
as a wrapper for the generated S-function in models that use the S-function.
This section explains how to use the S-Function Builder to build simple C MEX
S-functions.

Note The S-Function Builder is limited to building S-functions that have a

single input and output and that process data of type double. If you need to
create an S-function that has multiple inputs or outputs, that needs to process
data of types other than double, or that support other advanced Simulink
features, you must write the S-function from scratch. See “Creating C MEX
S-Functions” on page 3-3 for more information.

To build an S-function with the S-Function Builder:

1 Set the MATLAB current directory to the directory in which you want to
create the S-function.

2 Create a new Simulink model.

3 Copy an instance of the S-Function Builder block from the Simulink

Functions & Tables library into the new model.

3-5
3 Writing S-Functions in C

4 Double-click the block to open the S-Function Builder dialog box.

5 Enter the name of the S-function in the S-function name field.

6 If the S-function has parameters, enter default values for the parameters in
the S-function parameters field.

7 Use the specification and code entry panes on the S-Function Builder
dialog box to enter information and custom source code required to tailor the
generated S-function to your application (see “Customizing the S-Function”
on page 3-8).

8 If you have not already done so, configure the MATLAB mex command to
work on your system.

To configure the mex command, type mex -setup at the MATLAB command
line.

3-6
 Using the S-Function Builder

9 Click Build on the dialog box to start the build process.

Simulink builds a MEX file that implements the specified S-function and
saves the file in the current directory (“How the S-Function Builder Builds
an S-Function” on page 3-7).

10 Save the model containing the S-Function Builder block.

Deploying the Generated S-function

To use the generated S-function in another model, first check to ensure that the
directory containing the generated S-function is on the MATLAB path. Then
copy the S-Function Builder block from the model used to create the S-function
into the target model and set its parameters, if necessary, to the values
required by the target model.

How the S-Function Builder Builds an S-Function

The S-Function Builder builds an S-function as follows. First, it generates the
following source files in the current directory:
• sfun.c
where sfun is the name of the S-function that you specified in the S-function
name field of the S-Function Builder’s dialog box. This file contains the C
source code representation of the standard portions of the generated
S-function.
• sfun_wrapper.c
This file contains the custom code that you entered in the S-Function
Builder dialog box.
• sfun.tlc
This file permits Simulink to run the generated S-function in accelerated
mode and RTW to include this S-function in the code it generates.

After generating the S-function source code, the S-Function Builder uses the
MATLAB mex command to build the MEX file representation the S-function
from the generated source code and any external custom source code and
libraries that you specified.

3-7
3 Writing S-Functions in C

Customizing the S-Function

The tabbed panes on the S-Function Builder dialog box enable you to enter
information and custom code required to tailor the S-function to a specific
application. The dialog box contains the following panes.

Initialization Pane
The Initialization pane allows you to specify basic features of the S-function,
such as the width of its input and output ports and its sample time.

The S-Function Builder uses the information that you enter on this pane to
generate the S-function’s mdlInitializeSizes callback method. Simulink
invokes this method during the model initialization phase of the simulation to
obtain basic information about the S-function. (see “How Simulink Interacts
with C S-Functions” on page 3-32 for more information on the model
initialization phase).

3-8
 Using the S-Function Builder

The Initialization pane contains the following fields.

Input port width. Width of the S-function’s input port. The width is the number
of elements that a vector signal connected to the port must have. To permit
connection of matrix (2-D) signals to the input port, specify -1 as the input port
width.

Output port width. Width of the S-function’s output port. The width is the
number of elements in the vector that this S-function outputs. If the S-function
outputs matrix signals, specify -1 as the port width.

Number of parameters. Number of parameters that this S-function accepts.

Sample time. Sample time of the S-function. The sample time is the length of the
interval between the times when the S-function updates its output. You can
select one of the following options:
• Inherited
The S-function inherits its sample time from the block connected to its input
port.
• Continuous
The block updates its outputs at each simulation step.
• Discrete
The S-function updates its outputs at the rate specified in the Discrete
sample time value field of the S-Function Builder dialog box.

Discrete sample time value. Interval between updates of the S-function’s outputs.
This field is enabled only if you have selected Discrete as the S-function’s
Sample time.

Number of discrete states. Number of discrete states that the S-function has.

Discrete states IC. Initial conditions of the S-function’s discrete states. You can
enter the values as a comma-separated list or as a vector (e.g., [0 1 2]). The
number of initial conditions must equal the number of discrete states.

Number of continuous states. Number of continuous states that the S-function has.

3-9
3 Writing S-Functions in C

Continuous states IC. Initial conditions of the S-function’s continuous states. You
can enter the values as a comma-separated list or as a vector (e.g., [0 1 2]).
The number of initial conditions must equal the number of continuos states.

Libraries Pane
The Libraries pane allows you to specify the location of external code files
referenced by custom code that you enter in other panes of the S-Function
Builder dialog box.

The Libraries pane includes the following fields.

Library/Object/Source files. External library, object code, and source files

referenced by custom code that you enter elsewhere on the S-Function Builder
dialog box. List each file on a separate line. If the file resides in the current
directory, you need specify only the file’s name. If the file resides in another
directory, you must specify the full path of the file.

3-10
 Using the S-Function Builder

Includes. Header files containing declarations of functions, variables, and

macros referenced by custom code that you enter elsewhere on the S-Function
Builder dialog box. Specify each file on a separate line as #include statements.
Use brackets to enclose the names of standard C header files (e.g., #include
<math.h>). Use quotation marks to enclose names of custom header files (e.g.,
#include "myutils.h"). If your S-function uses custom include files that do
not reside in the current directory, you must set the S-Function Builder’s
include path to the directories containing the include files (see “Setting the
Include Path” on page 3-21).

External Function Declarations. Declarations of external functions not declared in

the header files listed in the Includes field. Put each declaration on a separate
line. The S-Function Builder includes the specified declarations in the
S-function source file that it generates. This allows S-function code that
computes the S-function’s states or output to invoke the external functions.

3-11
3 Writing S-Functions in C

Outputs Pane
Use the Outputs pane to enter code that computes the outputs of the
S-function at each simulation time step.

3-12
 Using the S-Function Builder

The Outputs pane contains the following fields.

Code for the mdlOutputs function. Code that computes the output of the S-function
at each simulation time step (or sample time hit in the case of a discrete
S-function.) When generating the source code for the S-function, the
S-Function Builder inserts the code in this field in a wrapper function of the
form
void sfun_Outputs_wrapper(const real_T *u,
real_T *y,
const real_T *xD, /* optional */
const real_T *xC, /* optional */
const real_T *param0, /* optional */
int_T p_width0 /* optional */
real_T *param1 /* optional */
int_t p_width1 /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */
{

/* Your code inserted here */

}

where sfun is the name of the S-function. The S-Function Builder inserts a call
to this wrapper function in the mdlOutputs callback method that it generates
for your S-function. Simulink invokes the mdlOutputs method at each
simulation time step (or sample time step in the case of a discrete S-function)
to compute the S-function’s output. The S-function’s mdlOutputs method in
turn invokes the wrapper function containing your output code. Your output
code then actually computes and returns the S-function’s output.

3-13
3 Writing S-Functions in C

The mdlOutputs method passes some or all of the following arguments to the
outputs wrapper function.

Argument Description

u Pointer to an array containing the inputs to the S-function.

The width of the array is the same as the input width you
specified on the Initialization pane. If you specified -1 as
the input width, the width of the array is specified by the
wrapper function’s u_width argument (see below).

y Pointer to an array containing the output of the

S-function.The width of the array is the same as the output
width you specified on the Initialization pane. If you
specified -1 as the output width, the width of the array is
specified by the wrapper function’s y_width argument (see
below). Use this array to pass the outputs that your code
computes back to Simulink.

xD Pointer to an array containing the discrete states of the

S-function. This argument appears only if you specified
discrete states on the Initialization pane. At the first
simulation time step, the discrete states have the initial
values that you specified on on the Initialization pane. At
subsequent sample-time steps, the states are obtained from
the values that the S-function computes at the preceding
time step (see “Discrete Update Pane” on page 3-18 for
more information).

xC Pointer to an array containing the continuous states of the

S-function. This argument appears only if you specified
continuous states on the Initialization pane. At the first
simulation time step, the continuous states have the initial
values that you specified on on the Initialization pane. At
subsequent time steps, the states are obtained by
numerically integrating the derivatives of the states at the
preceding time step (see “Continuous Derivatives Pane” on
page 3-16 for more information).

3-14
 Using the S-Function Builder

Argument Description

param0, param0, param1, paramN are pointers to arrays containing

p_width0, the S-function’s parameters, where N is the number of
param1, parameters specified on the Initialization pane. p_width0,
p_width1, ... p_width1, p_widthN are the width of the parameter arrays.
paramN, If a parameter is a matrix, the width equals the product of
p_widthN the dimensions of the arrays. For example, the width of a a
3-by-2 matrix parameter is 6. These arguments appear only
if you specify parameters on the Initialization pane.

y_width Width of the array containing the S-function’s outputs.

This argument appears in the generated code only if you
specified -1 as the width of the S-function’s output. If the
output is a matrix, y_width is the product of the
dimensions of the matrix.

u_width Width of the array containing the S-function’s inputs. This

argument appears in the generated code only if you
specified -1 as the width of the S-function’s input. If the
input is a matrix, u_width is the product of the dimensions
of the matrix.

These arguments permit you to compute the output of the block as a function
of its inputs and, optionally, its states and parameters. The code that you enter
in this field can invoke external functions declared in the header files or
external declarations on the Libraries pane. This allows you to use existing
code to compute the outputs of the S-function.

Inputs are needed in the output function. Checked if the current values of the
S-function’s inputs are used to compute its outputs. Simulink uses this
information to detect algebraic loops created by directly or indirectly
connecting the S-function’s output to its input.

3-15
3 Writing S-Functions in C

Continuous Derivatives Pane

If the S-function has continuous states, use the Continuous Derivatives pane
to enter code required to compute the state derivatives.

Enter code to compute the derivatives of the S-function’s continuous states in

the Code for the mdlDerivatives function field on this pane. When
generating code, the S-Function Builder takes the code in this pane and inserts
it in a wrapper function of the form
void sfun_Derivatives_wrapper(const real_T *u,
const real_T *y,
real_T *dx,
real_T *xC,
const real_T *param0, /* optional */
int_T p_width0, /* optional */
real_T *param1,/* optional */
int_T p_width1, /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */
{

3-16
 Using the S-Function Builder

/* Your code inserted here. */

where sfun is the name of the S-function. The S-Function Builder inserts a call
to this wrapper function in the mdlDerivatives callback method that it
generates for the S-function. Simulink calls the mdlDerivatives method at the
end of each time step to obtain the derivatives of the S-function’s continuous
states (see “How Simulink Interacts with C S-Functions” on page 3-32).
Simulink’s solver numerically integrates the derivatives to determine the
continuous states at the next time step. At the next time step, Simulink passes
the updated states back to the S-function’s mdlOutputs method (see “Outputs
Pane” on page 3-12).
The generated S-function’s mdlDerivatives callback method passes the
following arguments to the derivatives wrapper function:
•u
•y
• dx
• xC
• param0, p_width0, param1, p_width1, ... paramN, p_widthN
• y_width
• x-width

The dx argument is a pointer to an array whose width is the same as the

number of continuous derivatives specified on the Initialization pane. Your
code should use this array to return the values of the derivatives that it
computes. See “mdlOutputs” on page 3-25 for the meanings and usage of the
other arguments. The arguments allow your code to compute derivatives as a
function of the S-function’s inputs, outputs, and, optionally, parameters. Your
code can invoke external functions declared on the Libraries pane.

3-17
3 Writing S-Functions in C

Discrete Update Pane

If the S-function has discrete states, use the Discrete Update pane to enter
code that computes at the current time step the values of the discrete states at
the next time step.

Enter code to compute the values s of the S-function’s discrete states in the
Code for the mdlUpdate function field on this pane. When generating code,
the S-Function Builder takes the code in this pane and inserts it in a wrapper
function of the form
void sfun_Update_wrapper(const real_T *u,
const real_T *y,
real_T *xD,
const real_T *param0, /* optional */
int_T p_width0, /* optional */
real_T *param1,/* optional */
int_T p_width1, /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */

3-18
 Using the S-Function Builder

/* Your code inserted here. */

where sfun is the name of the S-function. The S-Function Builder inserts a call
to this wrapper function in the mdlUpdate callback method that it generates for
the S-function. Simulink calls the mdlUpdate method at the end of each time
step to obtain the values of the S-function’s discrete states at the next time step
(see “How Simulink Interacts with C S-Functions” on page 3-32). At the next
time step, Simulink passes the updated states back to the S-function’s
mdlOutputs method (see “Outputs Pane” on page 3-12).

The generated S-function’s mdlUpdates callback method passes the following

arguments to the updates wrapper function:
•u
•y
• xD
• param0, p_width0, param1, p_width1, ... paramN, p_widthN
• y_width
• x-width

See “mdlOutputs” on page 3-25 for the meanings and usage of these
arguments. Your code should use the xD (discrete states) variable to return the
values of the derivatives that it computes. The arguments allow your code to
compute the discrete states as functions of the S-function’s inputs, outputs,
and, optionally, parameters. Your code can invoke external functions declared
on the Libraries pane.

3-19
3 Writing S-Functions in C

Build Info Pane

Use the Build Info pane to specify options for building the S-function MEX file.

This pane contains the following fields.

Compilation diagnostics. Displays diagnostic messages issued by the S-Function

Builder when building the S-function.

Show compile steps. Log each build step in the Compilation diagnostics field.

Create a debuggable MEX-file. Include debug information in the generated

MEX-file.

Generate wrapper TLC. Generate a TCL file. You do not need to generate a TLC
file if you do not expect the S-function ever to run in accelerated mode or be
used in a model from which RTW generates code.

Save code only. Do not build a MEX file from the generated source code.

3-20
 Using the S-Function Builder

Setting the Include Path

The S-Function Builder searches for custom header files in the directories
specified by the MATLAB application data named
SfunctionBuilderIncludePath. This data is associated with the model in
which you create the S-Function Builder block. If your S-function uses custom
header files and the custom header files do not reside in the current directory
(i.e., the directory containing the generated S-function), you must update
SfunctionBuilderIncludePath to specify the locations of the directories
containing the header files. SfunctionBuilderIncludePath is a three-element
cell array that allows you to specify as many as three include directories. For
example, the following MATLAB commands set
SfunctionBuilderIncludePath to the paths of two include directories.
incPath = getappdata(0,'SfunctionBuilderIncludePath');
incPath{1} = /home/jones/include;
incPath{2} = getenv('PROJECT_INCLUDE_DIR')
setappdata(0,'SfunctionBuilderIncludePath',incPath)

3-21
3 Writing S-Functions in C

Example of a Basic C MEX S-Function

This section presents an example of a C MEX S-function that you can use as a
model for creating simple C S-functions. The example is the timestwo
S-function example that comes with Simulink (see matlabroot/simulink/src/
timestwo.c). This S-function outputs twice its input.

The following model uses the timestwo S-function to double the amplitude of a
sine wave and plot it in a scope.

The block dialog for the S-function specifies timestwo as the S-function name;
the parameters field is empty.
The timestwo S-function contains the S-function callback methods shown in
this figure.

Start of simulation

mdlInitializeSizes
Initialization
mdlInitializeSampleTimes

mdlOutputs
Simulation
loop

mdlTerminate

3-22
 Example of a Basic C MEX S-Function

The contents of timestwo.c are shown below.

#define S_FUNCTION_NAME timestwo
#define S_FUNCTION_LEVEL 2

#include “simstruc.h”

static void mdlInitializeSizes(SimStruct *S)

{
ssSetNumSFcnParams(S, 0);
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
return; /* Parameter mismatch will be reported by Simulink */
}

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED);
ssSetInputPortDirectFeedThrough(S, 0, 1);

if (!ssSetNumOutputPorts(S,1)) return;
ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED);

ssSetNumSampleTimes(S, 1);

/* Take care when specifying exception free code - see sfuntmpl.doc */

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
}

static void mdlInitializeSampleTimes(SimStruct *S)

{
ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}

static void mdlOutputs(SimStruct *S, int_T tid)

{
int_T i;
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
real_T *y = ssGetOutputPortRealSignal(S,0);
int_T width = ssGetOutputPortWidth(S,0);

for (i=0; i<width; i++) {

*y++ = 2.0 *(*uPtrs[i]);
}
}

static void mdlTerminate(SimStruct *S){}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include “simulink.c” /* MEX-file interface mechanism */
#else
#include “cg_sfun.h” /* Code generation registration function */
#endif

3-23
3 Writing S-Functions in C

This is example has three parts:

• Defines and includes

• Callback implementations
• Simulink (or Real-Time Workshop) interface

The following sections explains each of these parts.

Defines and Includes

The example starts with the following defines.
#define S_FUNCTION_NAME timestwo
#define S_FUNCTION_LEVEL 2

The first specifies the name of the S-function (timestwo). The second specifies
that the S-function is in the level 2 format (for more information about level 1
and level 2 S-functions, see “Converting Level 1 C MEX S-Functions to Level
2” on page 3-41).
After defining these two items, the example includes simstruc.h, which is a
header file that gives access to the SimStruct data structure and the MATLAB
Application Program Interface (API) functions.
#define S_FUNCTION_NAME timestwo
#define S_FUNCTION_LEVEL 2
#include "simstruc.h"

The simstruc.h file defines a a data structure, called the SimStruct, that
Simulink uses to maintain information about the S-function. The simstruc.h
file also defines macros that enable your MEX-file to set values in and get
values (such as the input and output signal to the block) from the SimStruct
(see Chapter 10, “SimStruct Functions”).

Callback Implementations
The next part of the timestwo S-function contains implementations of callback
methods required by Simulink.

3-24
 Example of a Basic C MEX S-Function

mdlInitializeSizes
Simulink calls mdlInitializeSizes to inquire about the number of input and
output ports sizes of the ports and any other objects (such as the number of
states) needed by the S-function.
The timestwo implementation of mdlInitializeSizes specifies the following
size information:

• Zero parameters
This means that the S-function parameters field of the S-functions’s dialog
box must be empty. If it contains any parameters, Simulink will report a
parameter mismatch.
• One input port and one output port
The widths of the input and output ports are dynamically sized. This tells
Simulink to multiply each element of the input signal to the S-function by
two and to place the result in the output signal. Note that the default
handling for dynamically sized S-functions for this case (one input and one
output) is that the input and output widths are equal.
• One sample time
The timestwo example specifies the actual value of the sample time in the
mdlInitializeSampleTimes routine.
• The code is exception free.

Specifying exception free code speeds up execution of your S-function. Care

must be taken when specifying this option. In general, if your S-function isn’t
interacting with MATLAB, it is safe to specify this option. For more details,
see “How Simulink Interacts with C S-Functions” on page 3–32.

mdlInitializeSampleTimes
Simulink calls mdlInitializeSampleTimes to set the sample time(s) of the
S-function. A timestwo block executes whenever the driving block executes.
Therefore, it has a single inherited sample time, SAMPLE_TIME_INHERITED.

mdlOutputs
Simulink calls mdlOutputs at each time step to calculate a block’s outputs. The
timestwo implementation of mdlOutputs takes the input, multiplies it by two,
and writes the answer to the output.

3-25
3 Writing S-Functions in C

The timestwo mdlOutputs method uses a SimStruct macro,

InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

to access the input signal. The macro returns a vector of pointers, which must
be accessed using
*uPtrs[i]

For more details, see “Data View” on page 3–36.

The timestwo mdlOutputs method uses the macro
real_T *y = ssGetOutputPortRealSignal(S,0);

To access the output signal. This macro returns a pointer to an array

containing the block’s outputs.
The S-function uses
int_T width = ssGetOutputPortWidth(S,0);

to get the width of the signal passing through the block. Finally the S-function
loops over the inputs to compute the outputs.

mdlTerminate
Perform tasks at end of simulation. This is a mandatory S-function routine.
However, the timestwo S-function doesn’t need to perform any termination
actions, so this routine is empty.

Simulink/Real-Time Workshop Interface

At the end of the S-function, specify code that attaches this example to either
Simulink or the Real-Time Workshop.
#ifdef MATLAB_MEX_FILE
#include "simulink.c"
#else
#include "cg_sfun.h"
#endif

Building the Timestwo Example

To incorporate this S-function into Simulink, type

3-26
 Example of a Basic C MEX S-Function

mex timestwo.c

at the command line. The mex command compiles and links the timestwo.c file
to create a dynamically loadable executable for Simulink’s use.
The resulting executable is referred to as a MEX S-function, where MEX
stands for “MATLAB EXecutable.” The MEX-file extension varies from
platform to platform. For example, in Microsoft Windows, the MEX-file
extension is .dll.

3-27
3 Writing S-Functions in C

Templates for C S-Functions

Simulink provides skeleton implementations of C MEX S-functions, called
templates, intended to serve as starting points for creating your own
S-functions. The templates contain skeleton implementations of callback
methods with comments that explain their use. The template file,
sfuntmpl_basic.c, which can be found in the directory simulink/src below
the MATLAB root directory, contains commonly used S-function routines. A
template containing all available routines (as well as more comments) can be
found in sfuntmpl_doc.c in the same directory.

Note We recommend that you use the C MEX-file template when developing
MEX S-functions.

S-Function Source File Requirements

This section describes requirements that every S-function source file must
meet to compile correctly. The S-function templates meet these requirements.

Statements Required at the Top of S-Functions

For S-functions to operate properly, each source module of your S-function that
accesses the SimStruct must contain the following sequence of defines and
include
#define S_FUNCTION_NAME your_sfunction_name_here
#define SFUNCTION_LEVEL 2
#include "simstruc.h"

Where your_sfunction_name_here is the name of your S-function (i.e., what

you enter in the Simulink S-Function block dialog). These statements give you
access to the SimStruct data structure that contains pointers to the data used
by the simulation. The included code also defines the macros used to store and
retrieve data in the SimStruct, described in detail in “Converting Level 1 C
MEX S-Functions to Level 2” on page 3–41. In addition, the code specifies that
you are using the level 2 format of S-functions.

3-28
 Templates for C S-Functions

Note All S-functions from Simulink 1.3 through 2.1 are considered to be level
1 S-functions. They are compatible with Simulink 3.0, but we recommend that
you write new S-functions in the level 2 format.

The following headers are included by matlabroot/simulink/include/

simstruc.h when compiling as a MEX-file.

Table 3-1: Header Files Included by Simstruc.h When Compiling as a MEX-File

Header File Description

matlabroot/extern/include/tmwtypes.h General data types, e.g.,

real_T

matlabroot/extern/include/mex.h MATLAB MEX-file API

routines
matlabroot/extern/include/matrix.h MATLAB MEX-file API
routines

When compiling your S-function for use with the Real-Time Workshop,
simstruc.h includes the following.

Table 3-2: Header Files Included by Simstruc.h When Used

by the Real-Time Workshop

Header File Description

matlabroot/extern/include/tmwtypes.h General types, e.g. real_T

matlabroot/rtw/c/libsrc/rt_matrx.h Macros for MATLAB API
routines

Statements Required at the Bottom of S-Functions

Include this trailer code at the end of your C MEX S-function main module
only.
#ifdef MATLAB_MEX_FILE /* Is this being compiled as MEX-file? */
#include "simulink.c" /* MEX-file interface mechanism */

3-29
3 Writing S-Functions in C

#else
#include "cg_sfun.h" /* Code generation registration func */
#endif

These statements select the appropriate code for your particular application:

• simulink.c is included if the file is being compiled into a MEX-file.

• cg_sfun.h is included if the file is being used in conjunction with the
Real-Time Workshop to produce a stand-alone or real-time executable.

Note This trailer code must not be in the body of any S-function routine.

The SimStruct
The file matlabroot/simulink/include/simstruc.h is a C language header
file that defines the Simulink data structure and the SimStruct access macros.
It encapsulates all the data relating to the model or S-function, including block
parameters and outputs.
There is one SimStruct data structure allocated for the Simulink model. Each
S-function in the model has its own SimStruct associated with it. The
organization of these SimStructs is much like a directory tree. The SimStruct
associated with the model is the root SimStruct. The SimStructs associated
with the S-functions are the child SimStructs.

Note By convention, port indices begin at 0 and finish at the total number of
ports minus 1.

Simulink provides a set of macros that S-functions can use to access the fields
of the SimStruct. See Chapter 10, “SimStruct Functions” for more information.

3-30
 Templates for C S-Functions

Compiling C S-Functions
S-functions can be compiled in one of three modes identified by the presence of
one of the following defines:

• MATLAB_MEX_FILE — Indicates that the S-function is being built as a

MEX-file for use with Simulink.
• RT — Indicates that the S-function is being built with the Real-Time
Workshop generated code for a real-time application using a fixed-step
solver.
• NRT — Indicates that the S-function is being built with the Real-Time
Workshop generated code for a nonreal-time application using a
variable-step solver.

3-31
3 Writing S-Functions in C

How Simulink Interacts with C S-Functions

It is helpful in writing C MEX-file S-functions to understand how Simulink
interacts with S-functions. This section examines the interaction from two
perspectives: a process perspective, i.e., at which points in a simulation
Simulink invokes the S-function, and a data perspective, i.e., how Simulink
and the S-function exchange information during a simulation.

Process View
The following figures shows the order in which Simulink invokes an
S-function’s callback methods.

3-32
 How Simulink Interacts with C S-Functions

Model Initialization

mdlIntializeSizes mdlCheckParameters

mdlSetInputPortFrameData

mdlSetInputPortWidth/mdlSetOutputPortWidth
mdlSetInputPortDimensionInfo/mdlSetOutputPortDimensionInfo

mdlSetInputPortSampleTime/mdlSetOutputPortSampleTime
Simulink Engine

mdlInitializeSampleTime

mdlSetInputPortDataType/mdlSetOutputPortDatatype
mdlSetDefaultPortDataTypes

mdlSetInputPortComplexSignal/mdlSetOutputPortComplexSignal
mdlSetDefaultPortComplexSignals

mdlSetWorkWidths mdlStart optionally calls

mdlCheckParameters
mdlCheckParameters
mdlStart followed by
mdlProcessParameters mdlProcessParameters

mdlInitializeConditions

Sets output of
mdlOutputs
constant blocks

To simulation loop

3-33
3 Writing S-Functions in C

Simulation Loop
Initialize Model

Called when parameters

mdlProcessParameters change.
major time step

mdlGetTimeOfNextVarHit

Called if sample time of

mdlInitalizeConditions this S-function varies.

mdlOutputs
Simulink Engine

mdlUpdate
mdlCheckParameters

Integration Called if this S-function

has continuous states.
mdlDerivatives

mdlOutputs
minor time step

mdlDerivatives

Zero crossing detection

Called when parameters Called if this S-function
change. mdlOutputs detects zero crossings.

mdlZeroCrossings

mdlTerminate

End Simulation

3-34
 How Simulink Interacts with C S-Functions

Calling Structure for the Real Time Workshop

When generating code, the Real-Time Workshop does not go through the entire
calling sequence outlined above. After initializing the model as outlined in the
preceding section, Simulink calls mdlRTW, an S-function routine unique to the
Real-Time Workshop, mdlTerminate, and exits.
For more information about the Real-Time Workshop and how it interacts with
S-functions, see The Real-Time Workshop User’s Guide and The Target
Language Compiler Reference Guide.

Alternate Calling Structure for External Mode

When running Simulink in external mode, the calling sequence for S-function
routines changes. This picture shows the correct sequence for external mode.

Model Initialization
parameter change loop

mdlCheckParameters p. 9-3
External mode

mdlProcessParameters p. 9-18

mdlRTW p. 9-20 Called only if no runtime parameters

mdlTerminate p. 9-40

Simulink calls mdlRTW once when it enters external mode and again each time
a parameter changes or when you select Update Diagram under your model’s
Edit menu.

Note Running Simulink in external mode requires the Real-Time Workshop.

For more information about external mode, see the Real-Time Workshop
User’s Guide.

3-35
3 Writing S-Functions in C

Data View
S-function blocks have input and output signals, parameters, internal states,
plus other general work areas. In general, block inputs and outputs are written
to, and read from, a block I/O vector. Inputs can also come from

• External inputs via the root inport blocks

• Ground if the input signal is unconnected or grounded

Block outputs can also go to the external outputs via the root outport blocks. In
addition to input and output signals, S-functions can have:

• Continuous states
• Discrete states
• Other working areas such as real, integer or pointer work vectors

S-function blocks can be parameterized by passing parameters them using the

S-function block dialog box.
The following picture shows the general mapping between these various types
of data.

External External
Inputs Outputs
Block I/O (root
(root
inport outport
blocks) blocks)

Ground Block
Work
Vectors,
DWork,
RWork,
States Parameters IWork,
PWork,
...

3-36
 How Simulink Interacts with C S-Functions

An S-function’s mdlInitializeSizes routine sets the sizes of the various

signals and vectors. S-function methods called during the simulation loop can
determine the sizes and values of the signals.
An S-function method can access input signals in two ways:

• Via pointers
• Using contiguous inputs

Accessing Signals Using Pointers

During the simulation loop, accessing the input signals is performed using
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,portIndex)

This is an array of pointers, where portIndex starts at 0. There is one for each
input port. To access an element of this signal you must use
*uPtrs[element]

as described by this figure.

Input 1 S-function
Input 2 Block

To Access Input 1:
InputRealPtrsType uPtrs0 = ssGetInputPortRealSignalPtrs(S,0)
uPtrs0
...

To Access Input 2:
InputRealPtrsType uPtrs1 = ssGetInputPortRealSignalPtrs(S,1)
uPtrs1
...
...

Block I/O
Vector

3-37
3 Writing S-Functions in C

Note that input array pointers may point at noncontiguous places in memory.
You can retrieve the output signal by using this code.
real_T *y = ssGetOutputPortSignal(S,outputPortIndex);

Accessing Contiguous Input Signals

An S-function’s mdlInitializeSizes method can specify that the elements of
its input signals must occupy contiguous areas of memory, using
ssSetInputPortRequiredContiguous. If the inputs are contiguous, other
methods can use ssGetInputPortSignal to access the inputs.

Accessing Input Signal of Individual Ports

This section describes how to access all input signals of a particular port and
write them to the output port. The figure above shows that the input array of
pointers may point to noncontiguous entries in the block I/O vector. The output
signals of a particular port form a contiguous vector. Therefore, the correct way
to access input elements and write them to the output elements (assuming the
input and output ports have equal widths) is to use this code.
int_T element;
int_T portWidth = ssGetInputPortWidth(S,inputPortIndex);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,inputPortIndex);
real_T *y = ssGetOutputPortSignal(S,outputPortIdx);

for (element=0; element<portWidth; element++) {

y[element] = *uPtrs[element];
}

A common mistake is to try and access the input signals via pointer arithmetic.
For example, if you were to place
real_T *u = *uPtrs; /* Incorrect */

just below the initialization of uPtrs and replace the inner part of the above
loop with
*y++ = *u++; /* Incorrect */

the code compiles, but the MEX-file may crash Simulink. This is because it is
possible to access invalid memory (which depends on how you build your
model). When accessing the input signals incorrectly, a crash will happen when
the signals entering your S-function block are not contiguous. Noncontiguous
signal data occur when signals pass through virtual connection blocks such as
the Mux or Selector blocks.

3-38
 How Simulink Interacts with C S-Functions

To verify that you are correctly accessing wide input signals, pass a replicated
signal to each input port of your S-function. This is done by creating a Mux
block with the number of input ports equal to the width of the desired signal
entering your S-function. Then the driving source should be connected to each
input port as shown in this figure.

Source signal Mux S-function

3-39
3 Writing S-Functions in C

Writing Callback Methods

Writing an S-function basically involves creating implementations of the
callback functions that Simulink invokes during a simulation. For guidelines
on implementing a particular callback, see the documentation for the callback
in Chapter 9, “S-Function Callback Methods.” For information on using
callbacks to implement specific block features, such as parameters or sample
times, see Chapter 7, “Implementing Block Features.”

3-40
 Converting Level 1 C MEX S-Functions to Level 2

Converting Level 1 C MEX S-Functions to Level 2

Level 2 S-functions were introduced with Simulink 2.2. Level 1 S-functions
refer to S-functions that were written to work with Simulink 2.1 and previous
releases. Level 1 S-functions are compatible with Simulink 2.2 and subsequent
releases; you can use them in new models without making any code changes.
However, to take advantage of new features in S-functions, level 1 S-functions
must be updated to level 2 S-functions. Here are some guidelines:

• Start by looking at simulink/src/sfunctmpl_doc.c. This template

S-function file concisely summarizes level 2 S-functions.
• At the top of your S-function file, add this define:
#define S_FUNCTION_LEVEL 2

• Update the contents of mdlIntializeSizes, in particular add the following

error handling for the number of S-function parameters:
ssSetNumSFcnParams(S, NPARAMS); /*Number of expected parameters*/
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
/* Return if number of expected != number of actual parameters */
return;
}
Set up the inputs using:
if (!ssSetNumInputPorts(S, 1)) return; /*Number of input ports */
ssSetInputPortWidth(S, 0, width); /* Width of input
port one (index 0)*/
ssSetInputPortDirectFeedThrough(S, 0, 1); /* Direct feedthrough
or port one */
ssSetInputPortRequiredContiguous(S, 0);
Set up the outputs using:
if (!ssSetNumOutputPorts(S, 1)) return;
ssSetOutputPortWidth(S, 0, width); /* Width of output port
one (index 0) */
• If your S-function has a nonempty mdlInitializeConditions, then update
it to the following form
#define MDL_INITIALIZE_CONDITIONS
static void mdlInitializeConditions(SimStruct *S)
{
}
otherwise, delete the function.
- The continuous states are accessed using ssGetContStates. The ssGetX
macro has been removed.
- The discrete states are accessed using ssGetRealDiscStates(S). The
ssGetX macro has been removed.

3-41
3 Writing S-Functions in C

- For mixed continuous and discrete state S-functions, the state vector no
longer consists of the continuous states followed by the discrete states. The
states are saved in separate vectors and hence may not be contiguous in
memory.
• The mdlOutputs prototype has changed from
static void mdlOutputs( real_T *y, const real_T *x,
const real_T *u, SimStruct *S, int_T tid)

to:
static void mdlOutputs(SimStruct *S, int_T tid)

Since y, x, and u are not explicitly passed into Level-2 S-functions, you must
use:
- ssGetInputPortSignal to access inputs.
- ssGetOutputPortSignal to access the outputs.
- ssGetContStates or ssGetRealDiscStates to access the states.
• The mdlUpdate function prototype has been changed from
void mdlUpdate(real_T *x, real_T *u, Simstruct *S, int_T tid)

to:
void mdlUpdate(SimStruct *S, int_T tid)

• If your S-function has a nonempty mdlUpdate, then update it to this form

#define MDL_UPDATE
static void mdlUpdate(SimStruct *S, int_T tid)
{
}

otherwise, delete the function.

• If your S-function has a nonempty mdlDerivatives, then update it to this
form
#define MDL_DERIVATIVES
static void mdlDerivatives(SimStruct *S, int_T tid)
{
}

otherwise, delete the function.

3-42
 Converting Level 1 C MEX S-Functions to Level 2

• Replace all obsolete SimStruct macros. See “Obsolete Macros” on page 3–43
for a complete list of obsolete macros.
• When converting level 1 S-functions to level 2 S-functions, you should build
your S-functions with full (i.e., highest) warning levels. For example, if you
have gcc on a UNIX system, use these options with the mex utility.
mex CC=gcc CFLAGS=-Wall sfcn.c

If your system has Lint, use this code.

lint -DMATLAB_MEX_FILE -I<matlabroot>/simulink/include
-Imatlabroot/extern/include sfcn.c

On a PC, to use the highest warning levels, you must create a project file
inside of the integrated development environment (IDE) for the compiler you
are using. Within the project file, define MATLAB_MEX_FILE and add
matlabroot/simulink/include
matlabroot/extern/include

to the path (be sure to build with alignment set to 8).

Obsolete Macros
The following macros are obsolete. Each obsolete macro should be replaced
with the specified macro.

Obsolete Macro Replace With

ssGetU(S), ssGetUPtrs(S) ssGetInputPortSignalPtrs(S,port)

ssGetY(S) ssGetOutputPortRealSignal(S,port)

ssGetX(S) ssGetContStates(S), ssGetRealDiscStates(S)

ssGetStatus(S) Normally not used, but ssGetErrorStatus(S) is

available.
ssSetStatus(S,msg) ssSetErrorStatus(S,msg)

ssGetSizes(S) Specific call the desired item (i.e.,

ssGetNumContStates(S)).

3-43
3 Writing S-Functions in C

Obsolete Macro Replace With

ssGetMinStepSize(S) No longer supported.

ssGetPresentTimeEvent(S,sti) ssGetTaskTime(S,sti)

ssGetSampleTimeEvent(S,sti) ssGetSampleTime(S,sti)

ssSetSampleTimeEvent(S,t) ssSetSampleTime(S,sti,t)

ssGetOffsetTimeEvent(S,sti) ssGetOffsetTime(S,sti)

ssSetOffsetTimeEvent(S,sti,t) ssSetOffsetTime(S,sti,t)

ssIsSampleHitEvent(S,sti,tid) ssIsSampleHit(S,sti,tid)

ssGetNumInputArgs(S) ssGetNumSFcnParams(S)

ssSetNumInputArgs(S, numInputArgs) ssSetNumSFcnParams(S,numInputArgs)

ssGetNumArgs(S) ssGetSFcnParamsCount(S)

ssGetArg(S,argNum) ssGetSFcnParam(S,argNum)

ssGetNumInputs ssGetNumInputPorts(S) and

ssGetInputPortWidth(S,port)

ssSetNumInputs ssSetNumInputPorts(S,nInputPorts) and

ssSetInputPortWidth(S,port,val)

ssGetNumOutputs ssGetNumOutputPorts(S) and

ssGetOutputPortWidth(S,port)

ssSetNumOutputs ssSetNumOutputPorts(S,nOutputPorts) and

ssSetOutputPortWidth(S,port,val)

3-44
 4

Creating C++ S-Functions

Overview . . . . . . . . . . . . . . . . . . . . . . 4-2

Source File Format . . . . . . . . . . . . . . . . . 4-3

Making C++ Objects Persistent . . . . . . . . . . . . 4-7

Building C++ S-Functions . . . . . . . . . . . . . . 4-8

4 Creating C++ S-Functions

Overview
The procedure for creating C++ S-functions is nearly the same as that for
creating C S-functions (see Chapter 3, “Writing S-Functions in C”). This section
explains the differences.

4-2
 Source File Format

Source File Format

The format of the C++ source for an S-function is nearly identical to that of the
source for an S-function written in C. The main difference is that you must use
tell the C++ compiler to use C call conventions when compiling the callback
methods. This is necessary because the Simulink simulation engine assumes
that callback methods obey C calling conventions.
To tell the compiler to use C calling conventions when compiling the callback
methods, wrap the C++ source for the S-function callback methods in an
extern “C” statement. The C++ version of the sfun_counter S-function
example (matlabroot/simulink/src/sfun_counter_cpp.cpp) illustrates
usage of the extern “C” directive to ensure that the compiler generates
Simulink-compatible callback methods.
/* File : sfun_counter_cpp.cpp
* Abstract:
*
* Example of an C++ S-function which stores an C++ object in
* the pointers vector PWork.
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.1 $
*/

#include "iostream.h"

class counter {
double x;
public:
counter() {
x = 0.0;
}
double output(void) {
x = x + 1.0;
return x;
}
};

#ifdef __cplusplus
extern "C" { // use the C fcn-call standard for all functions
#endif // defined within this scope

#define S_FUNCTION_LEVEL 2
#define S_FUNCTION_NAME sfun_counter_cpp

/*
* Need to include simstruc.h for the definition of the SimStruct and
* its associated macro definitions.

4-3
4 Creating C++ S-Functions

*/
#include "simstruc.h"

/*====================*
* S-function methods *
*====================*/

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
/* See sfuntmpl_doc.c for more details on the macros below */

ssSetNumSFcnParams(S, 1); /* Number of expected parameters */

if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
/* Return if number of expected != number of actual parameters */
return;
}

ssSetNumContStates(S, 0);
ssSetNumDiscStates(S, 0);

if (!ssSetNumInputPorts(S, 0)) return;

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, 1);

ssSetNumSampleTimes(S, 1);
ssSetNumRWork(S, 0);
ssSetNumIWork(S, 0);
ssSetNumPWork(S, 1); // reserve element in the pointers vector
ssSetNumModes(S, 0); // to store a C++ object
ssSetNumNonsampledZCs(S, 0);

ssSetOptions(S, 0);
}

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* This function is used to specify the sample time(s) for your
* S-function. You must register the same number of sample times as
* specified in ssSetNumSampleTimes.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, mxGetScalar(ssGetSFcnParam(S, 0)));
ssSetOffsetTime(S, 0, 0.0);

4-4
 Source File Format

#define MDL_START /* Change to #undef to remove function */

#if defined(MDL_START)
/* Function: mdlStart =======================================================
* Abstract:
* This function is called once at start of model execution. If you
* have states that should be initialized once, this is the place
* to do it.
*/
static void mdlStart(SimStruct *S)
{
ssGetPWork(S)[0] = (void *) new counter; // store new C++ object in the
} // pointers vector
#endif /* MDL_START */

/* Function: mdlOutputs =======================================================

* Abstract:
* In this function, you compute the outputs of your S-function
* block. Generally outputs are placed in the output vector, ssGetY(S).
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
counter *c = (counter *) ssGetPWork(S)[0]; // retrieve C++ object from
real_T *y = ssGetOutputPortRealSignal(S,0); // the pointers vector and use
y[0] = c->output(); // member functions of the
} // object

/* Function: mdlTerminate =====================================================

* Abstract:
* In this function, you should perform any actions that are necessary
* at the termination of a simulation. For example, if memory was
* allocated in mdlStart, this is the place to free it.
*/
static void mdlTerminate(SimStruct *S)
{
counter *c = (counter *) ssGetPWork(S)[0]; // retrieve and destroy C++
delete c; // object in the termination
} // function
/*======================================================*
* See sfuntmpl_doc.c for the optional S-function methods *
*======================================================*/

/*=============================*
* Required S-function trailer *
*=============================*/

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

4-5
4 Creating C++ S-Functions

#ifdef __cplusplus
} // end of extern "C" scope
#endif

4-6
 Making C++ Objects Persistent

Making C++ Objects Persistent

Your C++ callback methods may need to create persistent C++ objects, that is,
objects that continue to exist after the method exits. For example, a callback
method may need to access an object created during a previous invocation. Or
one callback method may need to access an object created by another callback
method. To create persistent C++ objects in your S-function:

1 Create a pointer work vector to hold pointers to the persistent object

between method invocations.
static void mdlInitializeSizes(SimStruct *S)
{
...
ssSetNumPWork(S, 1); // reserve element in the pointers vector
// to store a C++ object
...
}

2 Store a pointer to each object that you want to be persistent in the pointer
work vector.
static void mdlStart(SimStruct *S)
{
ssGetPWork(S)[0] = (void *) new counter; // store new C++ object in the
} // pointers vector

3 Retrieve the pointer in any subsequent method invocation to access the

object.
static void mdlOutputs(SimStruct *S, int_T tid)
{
counter *c = (counter *) ssGetPWork(S)[0]; // retrieve C++ object from
real_T *y = ssGetOutputPortRealSignal(S,0); // the pointers vector and use
y[0] = c->output(); // member functions of the
} // object

4 Destroy the objects when the simulation terminates.

static void mdlTerminate(SimStruct *S)
{
counter *c = (counter *) ssGetPWork(S)[0]; // retrieve and destroy C++
delete c; // object in the termination
} // function

4-7
4 Creating C++ S-Functions

Building C++ S-Functions

Use the MATLAB mex command to build C++ S-functions exactly the way you
use it to build C S-functions. For example, to build the C++ version of the
sfun_counter example, enter
mex sfun_counter_cpp.cpp

at the MATLAB command line.

Note The extension of the source file for a C++ S-function must be .cpp to
ensure that the compiler treats the file’s contents as C++ code.

4-8
 5

Creating Ada S-Functions

Introduction . . . . . . . . . . . . . . . . . . . . 5-2

Ada S-Function Source File Format . . . . . . . . . . 5-3

Ada S-Function Specification . . . . . . . . . . . . . . 5-3
Ada S-Function Body . . . . . . . . . . . . . . . . . 5-4

Writing Callback Methods in Ada . . . . . . . . . . . 5-6

Callbacks Invoked By Simulink . . . . . . . . . . . . . 5-6
Implementing Callbacks . . . . . . . . . . . . . . . . 5-7
Omitting Optional Callback Methods . . . . . . . . . . 5-7
SimStruct Functions . . . . . . . . . . . . . . . . . 5-7

Building an Ada S-Function . . . . . . . . . . . . . 5-9

Using an Ada S-Function in a Model . . . . . . . . . . 5-10

Example of an Ada S-Function . . . . . . . . . . . . 5-11

5 Creating Ada S-Functions

Introduction
Simulink allows you to use the Ada programming language to create
S-functions. As with S-functions coded in other programming languages,
Simulink interacts with an Ada S-function by invoking callback methods that
the S-function implements. Each method performs a predefined task, such as
computing block outputs, required to simulate the block whose functionality
the S-function defines. Creating an Ada S-function thus entails writing Ada
implementations of the callback methods required to simulate the S-function
and then compiling and linking the callbacks into a library that Simulink can
load and invoke during simulation The following sections explain how to
perform theses tasks.

5-2
 Ada S-Function Source File Format

Ada S-Function Source File Format

To create an Ada S-function, you must create an Ada package that implements
the callback methods required to simulate the S-function. The S-function
package comprises a specification and a body.

Ada S-Function Specification

The specification specifies the methods that the Ada S-function uses and
implements. The specification must specify that the Ada S-function uses the
Simulink package, which defines data types and functions that the S-function
can use to access the internal data structure (SimStruct) that Simulink uses to
store information about the S-function (see Chapter 10, “SimStruct
Functions”). The specification and body of the Simulink package reside in the
matlabroot/simulink/ada/interface/ directory.

The specification should also specify each callback method that the S-function
implements as an Ada procedure exported to C. The following is an example
of an Ada S-function specification that meets these requirements.
-- The Simulink API for Ada S-Function
with Simulink; use Simulink;

package Times_Two is

-- The S_FUNCTION_NAME has to be defined as a constant

-- string.
--
S_FUNCTION_NAME : constant String := "times_two";

-- Every S-Function is required to have the

-- "mdlInitializeSizes" method.
-- This method needs to be exported as shown below, with the
-- exported name being "mdlInitializeSizes".
--
procedure mdlInitializeSizes(S : in SimStruct);
pragma Export(C, mdlInitializeSizes, "mdlInitializeSizes");

procedure mdlOutputs(S : in SimStruct; TID : in Integer);

pragma Export(C, mdlOutputs, "mdlOutputs");

end Times_Two;

5-3
5 Creating Ada S-Functions

Ada S-Function Body

The Ada S-Function body provides the implementations of the S-function
callback methods as illustrated in the following example.
with Simulink; use Simulink;
with Ada.Exceptions; use Ada.Exceptions;

package body Times_Two is

-- Function: mdlInitializeSizes ---------------------------------------------

-- Abstract:
-- Setup the input and output port attributes for this
-- S-Function.
--
procedure mdlInitializeSizes(S : in SimStruct) is

begin
-- Set the input port attributes
--
ssSetNumInputPorts( S, 1);
ssSetInputPortWidth( S, 0, DYNAMICALLY_SIZED);
ssSetInputPortDataType( S, 0, SS_DOUBLE);
ssSetInputPortDirectFeedThrough(S, 0, TRUE);
ssSetInputPortOverWritable( S, 0, FALSE);
ssSetInputPortOptimizationLevel(S, 0, 3);

-- Set the output port attributes

--
ssSetNumOutputPorts( S, 1);
ssSetOutputPortWidth( S, 0, DYNAMICALLY_SIZED);
ssSetOutputPortDataType( S, 0, SS_DOUBLE);
ssSetOutputPortOptimizationLevel(S, 0, 3);

-- Set the block sample time.

ssSetSampleTime( S, INHERITED_SAMPLE_TIME);

exception
when E : others =>
if ssGetErrorStatus(S) = "" then
ssSetErrorStatus(S,
"Exception occured in mdlInitializeSizes. " &
"Name: " & Exception_Name(E) & ", " &
"Message: " & Exception_Message(E) &
" and " & "Information: " &
Exception_Information(E));
end if;
end mdlInitializeSizes;

-- Function: mdlOutputs -----------------------------------------------------

-- Abstract:

5-4
 Ada S-Function Source File Format

-- Compute the S-Function's output,

-- given its input: y = 2 * u
--
procedure mdlOutputs(S : in SimStruct; TID : in Integer) is

uWidth : Integer := ssGetInputPortWidth(S,0);

U : array(0 .. uWidth-1) of Real_T;
for U'Address use ssGetInputPortSignalAddress(S,0);

yWidth : Integer := ssGetOutputPortWidth(S,0);

Y : array(0 .. yWidth-1) of Real_T;
for Y'Address use ssGetOutputPortSignalAddress(S,0);

begin
if uWidth = 1 then
for Idx in 0 .. yWidth-1 loop
Y(Idx) := 2.0 * U(0);
end loop;
else
for Idx in 0 .. yWidth-1 loop
Y(Idx) := 2.0 * U(Idx);
end loop;
end if;

exception
when E : others =>
if ssGetErrorStatus(S) = "" then
ssSetErrorStatus(S,
"Exception occured in mdlOutputs. " &
"Name: " & Exception_Name(E) & ", " &
"Message: " & Exception_Message(E) & " and " &
"Information: " & Exception_Information(E));
end if;
end mdlOutputs;

end Times_Two;

5-5
5 Creating Ada S-Functions

Writing Callback Methods in Ada

Simulink interacts with an Ada S-function by invoking callback methods that
the S-function implements. This section specifies the callback methods that an
Ada S-function can implement and provides guidelines for implementing them.

Callbacks Invoked By Simulink

The following diagram shows the callback methods that Simulink invokes
when interacting with an Ada S-function during a simulation and the order in
which Simulink invokes them.

5-6
 Writing Callback Methods in Ada

Note When interacting with Ada S-functions, Simulink invokes only a subset
of the callback methods that it invokes for C S-functions. The “Languages
Supported” section of the reference page for each callback method specifies
whether Simulink invokes that callback when interacting with an Ada
S-function.

Implementing Callbacks
Simulink defines in a general way the task of each callback. The S-function is
free to perform the task according to the functionality it implements. For
example, Simulink specifies that the S-function’s mdlOutput method must
compute that block’s outputs at the current simulation time. It does not specify
what those outputs must be. This callback-based API allows you to create
S-functions, and hence custom blocks, that meet your requirements.
Chapter 9, “S-Function Callback Methods” explains the purpose of each
callbacks and provides guidelines for implementing them. Chapter 3, “Writing
S-Functions in C” provides information on using these callbacks to implement
specific S-function features, such as the ability to handle multiple signal data
types.

Omitting Optional Callback Methods

The method mdlInitializeSizes is the only callback that an Ada S-function
must implement. The source for your Ada S-function needs to include
implementations only for callbacks that it must handle. If the source for your
S-function does not include an implementation for a particular callback, the
mex tool that builds the S-function (see “Building an Ada S-Function” on
page 5-9) provides a stub implementation.

SimStruct Functions
Simulink provides a set of functions that enable an Ada S-function to access the
internal data structure (SimStruct) that Simulink maintains for the
S-function. These functions consist of Ada wrappers around the SimStruct
macros used to access the SimStruct from a C S-function (see Chapter 10,
“SimStruct Functions”). Simulink provides Ada wrappers for a substantial

5-7
5 Creating Ada S-Functions

subset of the SimStruct macros. The “Languages Supported” section of the

reference page for a macro specifies whether it has an Ada wrapper.

5-8
 Building an Ada S-Function

Building an Ada S-Function

To use your Ada S-function with Simulink, you must build a MATLAB
executable (MEX) file from the Ada source code for the S-function. Use the
MATLAB mex command to perform this step.
The mex syntax for building an Ada S-function MEX file is
mex [-v] [-g] -ada SFCN.ads

where SFCN.ads is the name of the S-function’s package specification.

For example, to build the timestwo S-function example that comes with
Simulink, enter the command
mex -ada timestwo.ads

Note To build a MEX file from Ada source code, using the mex tool, you must
have previously installed a copy of version 3.2 (or higher) of the GNAT Ada95
compiler on your system. You can obtain the latest Solaris, Windows, and
GNU-Linux versions of the compiler at the GNAT ftp site (ftp://
cs.nyu.edu/pub/gnat). Make sure that the compiler executable is in
MATLAB’s command path so that the mex tool can find it.

5-9
5 Creating Ada S-Functions

Using an Ada S-Function in a Model

The way to include an Ada S-function in a model is the same at that for
including any other type of S-function. See “Using S-Functions in Models” on
page 1–2 for more information.

5-10
 Example of an Ada S-Function

Example of an Ada S-Function

This section presents an example of a basic Ada S-function that you can use as
a model when creating your own Ada S-functions. The example is the timestwo
S-function example that comes with Simulink (see matlabroot/simulink/ada/
examples/timestwo.ads and matlabroot/simulink/ada/examples/
timestwo.adb). This S-function outputs twice its input.

The following model uses the timestwo S-function to double the amplitude of a
sine wave and plot it in a scope.

The block dialog for the S-function specifies timestwo as the S-function name;
the parameters field is empty.
The timestwo S-function contains the S-function callback methods shown in
this figure.

Start of simulation

mdlInitializeSizes
Initialization
mdlInitializeSampleTimes

mdlOutputs
Simulation
loop

end of simulation

5-11
5 Creating Ada S-Functions

The source code for the timestwo S-function comprises two parts:

• Package specification
• Package body

The following sections explains each of these parts.

Timestwo Package Specification

The timestwo package specification, timestwo.ads, contains the following
code.
-- The Simulink API for Ada S-Function

with Simulink; use Simulink;

package Times_Two is

-- The S_FUNCTION_NAME has to be defined as a constant string. Note that

-- the name of the S-Function (ada_times_two) is different from the name
-- of this package (times_two). We do this so that it is easy to identify
-- this example S-Function in the MATLAB workspace. Normally you would use
-- the same name for S_FUNCTION_NAME and the package.
--
S_FUNCTION_NAME : constant String := "ada_times_two";

-- Every S-Function is required to have the "mdlInitializeSizes" method.

-- This method needs to be exported as shown below, with the exported name
-- being "mdlInitializeSizes".
--
procedure mdlInitializeSizes(S : in SimStruct);
pragma Export(C, mdlInitializeSizes, "mdlInitializeSizes");

procedure mdlOutputs(S : in SimStruct; TID : in Integer);

pragma Export(C, mdlOutputs, "mdlOutputs");

end Times_Two;

The package specification begins by specifying that the S-function uses the
Simulink package.
with Simulink; use Simulink;

The Simulink package defines Ada procedures for accessing the internal data
structure (SimStruct) that Simulink maintains for each S-function (see
Chapter 10, “SimStruct Functions”).

5-12
 Example of an Ada S-Function

Next the specification specifies the name of the S-function.

S_FUNCTION_NAME : constant String := "ada_times_two";

The name ada_times_two serves to distinguish the MEX file generated from
Ada source from those generated from the timestwo source coded in other
languages.
Finally the specification specifies the callback methods implemented by the
timestwo S-function.
procedure mdlInitializeSizes(S : in SimStruct);
pragma Export(C, mdlInitializeSizes, "mdlInitializeSizes");

procedure mdlOutputs(S : in SimStruct; TID : in Integer);

pragma Export(C, mdlOutputs, "mdlOutputs");

The specification specifies that the Ada compiler should compile each method
as a C-callable function. This is because the Simulink engine assumes that
callback methods are C functions.

Note When building an Ada S-function, MATLAB’s mex tool uses the package
specification to determine which callbacks the S-function does not implement.
It then generates stubs for the non implemented methods.

Timestwo Package Body

The timestwo package body, timestwo.adb, contains
with Simulink; use Simulink;
with Ada.Exceptions; use Ada.Exceptions;

package body Times_Two is

-- Function: mdlInitializeSizes ---------------------------------------------

-- Abstract:
-- Setup the input and output port attrubouts for this S-Function.
--
procedure mdlInitializeSizes(S : in SimStruct) is

begin
-- Set the input port attributes
--
ssSetNumInputPorts( S, 1);

5-13
5 Creating Ada S-Functions

ssSetInputPortWidth( S, 0, DYNAMICALLY_SIZED);
ssSetInputPortDataType( S, 0, SS_DOUBLE);
ssSetInputPortDirectFeedThrough(S, 0, TRUE);
ssSetInputPortOverWritable( S, 0, FALSE);
ssSetInputPortOptimizationLevel(S, 0, 3);

-- Set the output port attributes

--
ssSetNumOutputPorts( S, 1);
ssSetOutputPortWidth( S, 0, DYNAMICALLY_SIZED);
ssSetOutputPortDataType( S, 0, SS_DOUBLE);
ssSetOutputPortOptimizationLevel(S, 0, 3);

-- Set the block sample time.

ssSetSampleTime( S, INHERITED_SAMPLE_TIME);

exception
when E : others =>
if ssGetErrorStatus(S) = "" then
ssSetErrorStatus(S,
"Exception occured in mdlInitializeSizes. " &
"Name: " & Exception_Name(E) & ", " &
"Message: " & Exception_Message(E) & " and " &
"Information: " & Exception_Information(E));
end if;
end mdlInitializeSizes;

-- Function: mdlOutputs -----------------------------------------------------

-- Abstract:
-- Compute the S-Function's output, given its input: y = 2 * u
--
procedure mdlOutputs(S : in SimStruct; TID : in Integer) is

uWidth : Integer := ssGetInputPortWidth(S,0);

U : array(0 .. uWidth-1) of Real_T;
for U'Address use ssGetInputPortSignalAddress(S,0);

yWidth : Integer := ssGetOutputPortWidth(S,0);

Y : array(0 .. yWidth-1) of Real_T;
for Y'Address use ssGetOutputPortSignalAddress(S,0);

begin
if uWidth = 1 then
for Idx in 0 .. yWidth-1 loop
Y(Idx) := 2.0 * U(0);
end loop;
else
for Idx in 0 .. yWidth-1 loop
Y(Idx) := 2.0 * U(Idx);
end loop;
end if;

5-14
 Example of an Ada S-Function

exception
when E : others =>
if ssGetErrorStatus(S) = "" then
ssSetErrorStatus(S,
"Exception occured in mdlOutputs. " &
"Name: " & Exception_Name(E) & ", " &
"Message: " & Exception_Message(E) & " and " &
"Information: " & Exception_Information(E));
end if;
end mdlOutputs;

end Times_Two;

The package body contains implementations of the callback methods needed to

implement the timestwo example.

mdlInitializeSizes
Simulink calls mdlInitializeSizes to inquire about the number of input and
output ports sizes of the ports and any other objects (such as the number of
states) needed by the S-function.
The timestwo implementation of mdlInitializeSizes uses SimStruct
functions defined in the Simulink package to specify the following size
information:

• One input port and one output port

The widths of the input and output port are dynamically sized. This tells
Simulink to multiply each element of the input signal to the S-function by
two and to place the result in the output signal. Note that the default
handling for dynamically sized S-functions for this case (one input and one
output) is that the input and output widths are equal.
• One sample time

Finally the method provides an exception handler to handle any errors that
occur in invoking the SimStruct functions.

mdlOutputs
Simulink calls mdlOutputs at each time step to calculate a block’s outputs. The
timestwo implementation of mdlOutputs takes the input, multiplies it by two,
and writes the answer to the output.

5-15
5 Creating Ada S-Functions

The timestwo implementation of the mdlOutputs method uses the SimStruct

functions, ssGetInputPortWidth and ssGetInputPortSignalAddress, to
access the input signal.
uWidth : Integer := ssGetInputPortWidth(S,0);
U : array(0 .. uWidth-1) of Real_T;
for U'Address use ssGetInputPortSignalAddress(S,0);

Similarly, the mdlOutputs method uses the functions, ssGetOutputPortWidth

and ssGetOutputPortSignalAddress, to access the output signal.
yWidth : Integer := ssGetOutputPortWidth(S,0);
Y : array(0 .. yWidth-1) of Real_T;
for Y'Address use ssGetOutputPortSignalAddress(S,0);

Finally the method loops over the inputs to compute the outputs.

Building the Timestwo Example

To build this S-function into Simulink, type
mex -ada timestwo.abs

at the command line.

5-16
 6
Creating Fortran
S-Functions
Introduction . . . . . . . . . . . . . . . . . . . . 6-2
Level 1 Versus Level 2 S-Functions . . . . . . . . . . . 6-2

Creating Level 1 Fortran S-Functions . . . . . . . . 6-3

The Fortran MEX Template File . . . . . . . . . . . . 6-3
Example . . . . . . . . . . . . . . . . . . . . . . 6-3
Inline Code Generation Example . . . . . . . . . . . . 6-6

Creating Level 2 Fortran S-Functions . . . . . . . . 6-7

Template File . . . . . . . . . . . . . . . . . . . . 6-7
C/Fortran Interfacing Tips . . . . . . . . . . . . . . . 6-7
Constructing the Gateway . . . . . . . . . . . . . . . 6-11
An Example C-MEX S-Function Calling Fortran Code . . . 6-13

Porting Legacy Code . . . . . . . . . . . . . . . . 6-15

Find the States . . . . . . . . . . . . . . . . . . . 6-15
Sample Times . . . . . . . . . . . . . . . . . . . . 6-15
Multiple Instances . . . . . . . . . . . . . . . . . . 6-15
Use Flints If Needed . . . . . . . . . . . . . . . . . 6-16
Considerations for Real Time . . . . . . . . . . . . . . 6-16
6 Creating Fortran S-Functions

Introduction
There are two main strategies to executing Fortran code from Simulink. One is
from a Level 1 Fortran-MEX (F-MEX) S-function, the other is from a Level 2
gateway S-function written in C. Each has its advantages and both can be
incorporated into code generated by the Real-Time Workshop.

Level 1 Versus Level 2 S-Functions

The original S-function interface has been dubbed the “Level 1” API. As the
capabilities of Simulink grew over the years, the S-function API was
rearchitected into the more extensible “Level 2” API. This allows S-functions to
have all the capabilities of a full Simulink model (except automatic algebraic
loop identification and solving) and to grow as Simulink grows.

6-2
 Creating Level 1 Fortran S-Functions

Creating Level 1 Fortran S-Functions

The Fortran MEX Template File
A template file for Fortran MEX S-functions is located at matlabroot/
simulink/src/sfuntmpl_fortran.for. The template file compiles as-is and
merely copies the input to the output.
To use the template to create a new Fortran S-function:

1 Create a copy under another filename.

2 Edit the copy to perform the operations you need.

3 Compile the edited file into a MEX file, using the mex command.

4 Include the MEX file in your model, using the S-Function block.

Example
The example file, matlabroot/simulink/src/sfun_timestwo_for.for,
implements an S-function that multiplies its input by two.
C
C File: SFUN_TIMESTWO_FOR.F
C
C Abstract:
C A sample Level 1 FORTRAN representation of a
C timestwo S-function.
C
C The basic mex command for this example is:
C
C >> mex sfun_timestwo_for.for simulink.for
C
C Copyright 1990-2000 The MathWorks, Inc.
C
C $Revision: 1.1 $
C
C=====================================================
C Function: SIZES
C
C Abstract:
C Set the size vector.
C
C SIZES returns a vector which determines model
C characteristics. This vector contains the
C sizes of the state vector and other
C parameters. More precisely,

6-3
6 Creating Fortran S-Functions

C SIZE(1) number of continuous states

C SIZE(2) number of discrete states
C SIZE(3) number of outputs
C SIZE(4) number of inputs
C SIZE(5) number of discontinuous roots in
C the system
C SIZE(6) set to 1 if the system has direct
C feedthrough of its inputs,
C otherwise 0
C
C=====================================================
C
SUBROUTINE SIZES(SIZE)
C .. Array arguments ..
INTEGER*4 SIZE(*)
C .. Parameters ..
INTEGER*4 NSIZES
PARAMETER (NSIZES=6)

SIZE(1) = 0
SIZE(2) = 0
SIZE(3) = 1
SIZE(4) = 1
SIZE(5) = 0
SIZE(6) = 1

RETURN
END

C
C=====================================================
C
C Function: OUTPUT
C
C Abstract:
C Perform output calculations for continuous
C signals.
C
C=====================================================
C .. Parameters ..
SUBROUTINE OUTPUT(T, X, U, Y)
REAL*8 T
REAL*8 X(*), U(*), Y(*)

Y(1) = U(1) * 2.0

RETURN
END

C
C=====================================================
C
C Stubs for unused functions.

6-4
 Creating Level 1 Fortran S-Functions

C
C=====================================================

SUBROUTINE INITCOND(X0)
REAL*8 X0(*)
C --- Nothing to do.
RETURN
END

SUBROUTINE DERIVS(T, X, U, DX)

REAL*8 T, X(*), U(*), DX(*)
C --- Nothing to do.
RETURN
END

SUBROUTINE DSTATES(T, X, U, XNEW)

REAL*8 T, X(*), U(*), XNEW(*)
C --- Nothing to do.
RETURN
END

SUBROUTINE DOUTPUT(T, X, U, Y)
REAL*8 T, X(*), U(*), Y(*)
C --- Nothing to do.
RETURN
END

SUBROUTINE TSAMPL(T, X, U, TS, OFFSET)

REAL*8 T,TS,OFFSET,X(*),U(*)
C --- Nothing to do.
RETURN
END

SUBROUTINE SINGUL(T, X, U, SING)

REAL*8 T, X(*), U(*), SING(*)
C --- Nothing to do.
RETURN
END

A Level 1 S-function’s input/output is limited to using the REAL*8 data type,

(DOUBLE PRECISION), which is equivalent to a double in C. Of course, the
internal calculations can use whatever data types you need.
To see how this S-function works, type
sfcndemo_timestwo_for

at the MATLAB prompt and then run the model.

6-5
6 Creating Fortran S-Functions

Inline Code Generation Example

Real-Time Workshop users can use a sample block target file for
sfun_timestwo_for.mex to generate code for sfcndemo_timestwo_for. If you
want to learn how to inline your own Fortran MEX file, see the example at
matlabroot/toolbox/simulink/blocks/tlc_c/sfun_timestwo_for.tlc and
read the Target Language Compiler Reference Guide.

6-6
 Creating Level 2 Fortran S-Functions

Creating Level 2 Fortran S-Functions

To use the features of a Level 2 S-function with Fortran code, it is necessary to
write a skeleton S-function in C that has code for interfacing to Simulink and
also calls your Fortran code.
Using the C-MEX S-function as a gateway is quite simple if you are writing the
Fortran code from scratch. If instead your Fortran code already exists as a
standalone simulation, there is some work to be done to identify parts of the
code that need to be registered with Simulink, such as identifying continuous
states if you are using variable step solvers or getting rid of static variables if
you want to have multiple copies of the S-function in a Simulink model (see
“Porting Legacy Code” on page 6-15).

Template File
The file matlabroot/simulink/src/sfungate.c is a C-MEX template file for
calling into a Fortran subroutine. It will work with a simple Fortran
subroutine, if you modify the Fortran subroutine name in the code.

C/Fortran Interfacing Tips

The following are some tips for creating the C-to-Fortran gateway S-function.

Mex Environment
Remember that mex -setup needs to find both the C and the Fortran compilers.
If you install or change compilers it is necessary to run mex -setup after
installation or reconfiguration of compilers.
Test out the installation and setup using sample MEX files from MATLAB's C
and Fortran MEX examples in matlabroot/extern/examples/mex as well as
Simulink's examples, which are located in matlabroot/simulink/src.

Compiler Compatibility
Your C and Fortran compilers need to use the same object format. If you use
the compilers explicitly supported by the mex command this is not a problem.
When using the C gateway to Fortran, it is possible to use Fortran compilers
not supported by the mex command, but only if the object file format is
compatible with the C compiler format. Common object formats include ELF
and COFF.

6-7
6 Creating Fortran S-Functions

The compiler must also be configurable so that the caller cleans up the stack
instead of the callee. Compaq Visual Fortran (formerly known as Digital
Fortran) is one compiler whose default stack cleanup is the callee.

Symbol Decorations
Symbol decorations can cause runtime errors. For example, g77 will decorate
subroutine names with a trailing underscore when in its default configuration.
You can either recognize this and adjust the C function prototype or alter the
Fortran compiler’s name decoration policy via command line switches, if the
compiler supports this. See the Fortran compiler manual about altering symbol
decoration policies.
If all else fails, use utilities, such as od (octal dump), to display the symbol
names. For example, the command
od -s 2 <file>

lists strings and symbols in binary (.obj) files.

These binary utilities can be obtained for Windows as well. MKS is one
company that has commercial versions of powerful UNIX utilities, though most
can also be obtained for free on the Web. hexdump is another common program
for viewing binary files. As an example, here is the output of
od -s 2 sfun_atmos_for.o

on Linux.
0000115 EÈÙ
0000136 EÈÙ
0000271 EȺ
0000467 ÇEÈ@
0000530 ÇEÈ
0000575 EÈÙEäØ5@
0001267 Cf¦VC-ò:C
0001323 :|.-:8Æ#8ýKw6
0001353 ?333@
0001364 333À
0001414 01.01
0001425 GCC: (GNU) egcs-2.91.66 19990314/Linux
0001522 .symtab
0001532 .strtab
0001542 .shstrtab
0001554 .text
0001562 .rel.text
0001574 .data
0001602 .bss

6-8
 Creating Level 2 Fortran S-Functions

0001607 .note
0001615 .comment
0003071 sfun_atmos_for.for
0003101 gcc2_compiled.
0003120 rearth.0
0003131 gmr.1
0003137 htab.2
0003146 ttab.3
0003155 ptab.4
0003164 gtab.5
0003173 atmos_
0003207 exp
0003213 pow_d

Note that Atmos has been changed to atmos_ and the latter is what the C
program must call to be successful.
With Compaq Visual Fortran, the symbol is suppressed, so that Atmos becomes
ATMOS (no underscore).

Fortran Math Library

Fortran math library symbols may not match C math library symbols. For
example A^B in Fortran will call library function pow_dd, which is not in the C
math library. In these cases, you must tell mex to link in the Fortran math
library. For gcc environments, these routines are usually found in /usr/
local/lib/libf2c.a, /usr/lib/libf2c.a or equivalent.

The mex command becomes

mex -L/usr/local/lib -lf2c cmex_c_file fortran_object_file

Note On UNIX, the -lf2c option follows the conventional UNIX library
linking syntax where ’-l’ is the library option itself and ’f2c’ is the unique
part of the library file’s name, libf2c.a. Be sure to use the -L option for the
library search path since -I is only followed while searching for include files.

The f2c package can be obtained for Windows and UNIX environments from
the Internet. The file libf2c.a is usually part of g77 distributions, or else the
file is not needed as the symbols match. In obscure cases, it must be installed
separately, but even this is not difficult once the need for it is identified.

6-9
6 Creating Fortran S-Functions

On Windows using Microsoft Visual C/C++ and Compaq Visual Fortran 6.0
(formerly known as Digital Fortran), this example can be compiled using the
following mex commands (each command is on one line).
mex -v COMPFLAGS#”$COMPFLAGS /iface:cref” -c sfun_atmos_sub.for
-f ..\..\bin\win32\mexopts\df60opts.bat
mex -v LINKFLAGS#”$LINKFLAGS dfor.lib dfconsol.lib dfport.lib
/LIBPATH:$DF_ROOT\DF98\LIB” sfun_atmos.c sfun_atmos_sub.obj

See matlabroot/simulink/src/sfuntmpl_fortran.txt and matlabroot/

simulink/src/sfun_atmos.c for the latest information on compiling Fortran
for C on Windows.

CFortran
Or try using CFortran to create an interface. CFortran is a tool for automated
interface generation between C and Fortran modules, in either direction.
Search the Web for cfortran or visit
http://www-zeus.desy.de/~burow/cfortran/

for downloading.

Obtaining a Fortran Compiler

On Windows using Visual C/C++ with Fortran is best done with Compaq Visual
Fortran, Absoft, Lahey or other third-party compilers. See Compaq
(www.compaq.com) and Absoft (www.absoft.com) for Windows, Linux, and Sun
compilers and see Lahey (www.lahey.com) for more choices in Windows Fortran
compilers.
For Sun (Solaris) and other commercial UNIX platforms, one can purchase the
computer vendor’s Fortran compiler, a third-party Fortran such as Absoft, or
even use the Gnu Fortran port for that platform (if available).
As long as the compiler can output the same object (.o) format as the platform’s
C compiler, the Fortran compiler will work with the gateway C-MEX
S-function technique.
Gnu Fortran (g77) can be obtained free for several platforms from many
download sites, including tap://www.redhat.com in the download area. A
useful keyword on search engines is g77.

6-10
 Creating Level 2 Fortran S-Functions

Constructing the Gateway

The mdlInitializeSizes() and mdlInitializeSampleTimes() methods are
coded in C. It is unlikely that you will need to call Fortran routines from these
S-function methods. In the simplest case, the Fortran is called only from
mdlOutputs().

Simple Case
The Fortran code must at least be callable in a “step at a time” fashion. If the
code doesn’t have any states, it can be called from mdlOutputs() and no
mdlDerivatives() or mdlUpdate() methods are required.

Code with States

If the code has states, you must decide if the Fortran code can support a
variable step solver or not. For fixed-step solver only support, the C gateway
consists of a call to the Fortran code from mdlUpdate() and outputs are cached
in an S-function DWork vector so that subsequent calls by Simulink into
mdlOutputs() will work properly and the Fortran code won't be called until the
next invocation of mdlUpdate(). In this case, the states in the code can be
stored however you like, typically in the work vector or as discrete states in
Simulink.
If instead the code needs to have continuous time states with support for
variable step solvers, the states must be registered and stored with Simulink
as doubles. This is done in mdlInitializeSizes() (registering states), then
the states are retrieved and sent to the Fortran code whenever you need to
execute it. In addition, the main body of code has to be separable into a call
form that can be used by mdlDerivatives() to get derivatives for the state
integration and also by the mdlOutputs() and mdlUpdate() methods as
appropriate.

Setup Code
If there is a lengthy setup calculation, it is best to make this part of the code
separable from the “one step at a time” code and call it from mdlStart(). This
can either be a separate SUBROUTINE called from mdlStart() that
communicates with the rest of the code through COMMON blocks or argument
I/O, or it can be part of the same piece of Fortran code that is isolated by an
IF-THEN-ELSE construct. This construct can be triggered by one of the input
arguments that tells the code if it is to either perform the setup calculations or
the “one step” calculations.

6-11
6 Creating Fortran S-Functions

SUBROUTINE Versus PROGRAM

To be able to call Fortran from Simulink directly without having to launch
processes, etc., it is necessary to convert a Fortran PROGRAM into a SUBROUTINE.
This consists of three steps. The first is trivial, the second and third can take a
bit of examination:

1 Change the line PROGRAM to SUBROUTINE subName.

Now you can call it from C using C function syntax.

2 Identify variables that need to be inputs and outputs and put them in the

SUBROUTINE argument list or in a COMMON block.

It is customary to strip out all hard-coded cases and output dumps. In the
Simulink environment, you want to convert inputs and outputs into block
I/O.

3 If you are converting a stand-alone simulation to work inside of Simulink,

identify the “main loop” of time integration and remove both the loop and, if
you want Simulink to integrate continuous states, remove any time
integration code. Leave time integrations in the code if you intend to make
a discrete time (sampled) S-function.

Arguments to a SUBROUTINE
Most Fortran compilers generate SUBROUTINE code that passes arguments “by
reference.” This means that the C code calling the Fortran code must use only
pointers in the argument list.
PROGRAM ...

becomes
SUBROUTINE somename( U, X, Y )

A SUBROUTINE never has a return value. I/O is achieved by using some of the
arguments for input, the rest for output.

6-12
 Creating Level 2 Fortran S-Functions

Arguments to a FUNCTION
A FUNCTION has a scalar return value passed by value, so a calling C program
should expect this. The argument list is passed by reference (i.e., pointers) as
in the SUBROUTINE.
If the result of a calculation is an array, then a subroutine should be used as a
FUNCTION cannot return an array.

Interfacing to COMMON blocks

While there are several ways for Fortran COMMON blocks to be visible to C code,
it is often recommended to use an input/output argument list to a SUBROUTINE
or FUNCTION. If the Fortran code has already been written and uses COMMON
blocks, it is a simple matter to write a small SUBROUTINE that has an input/
output argument list and copies data into and out of the COMMON block.
The procedure for copying in and out of the COMMON block begins with a write of
the inputs to the COMMON block before calling the existing SUBROUTINE. The
SUBROUTINE is called, then the output values are read out of the COMMON block
and copied into the output variables just before returning.

An Example C-MEX S-Function Calling Fortran Code

The subroutine Atmos is in file sfun_atmos_sub.for. The gateway C-MEX
S-function is sfun_atmos.c, which is built on UNIX using the command
mex -L/usr/local/lib -lf2c sfun_atmos.c sfun_atmos_sub.o

On Windows, the command is

>> mex -v COMPFLAGS#”$COMPFLAGS /iface:cref” -c sfun_atmos_sub.for
-f ..\..\bin\win32\mexopts\df60opts.bat
>> mex -v LINKFLAGS#”$LINKFLAGS dfor.lib dfconsol.lib dfport.lib
/LIBPATH:$DF_ROOT\DF98\LIB” sfun_atmos.c sfun_atmos_sub.obj

On some UNIX systems where the C and Fortran compiler were installed
separately (or aren’t aware of each other), you may need to reference the library
libf2c.a. To do this, use the -lf2c flag.

UNIX only: if the libf2c.a library isn’t on the library path, you need to add it
the path to the mex process explicitly with the -L command, for instance:
mex -L/usr/local/lib/ -lf2c sfun_atmos.c sfun_atmos_sub.o

6-13
6 Creating Fortran S-Functions

This sample is prebuilt and is on the MATLAB search path already, so you can
see it working by opening the sample model sfcndemo_atmos.mdl. Just type
sfcndemo_atmos

at the command prompt, or to get all the S-function demos for Simulink, type
sfcndemos at the MATLAB prompt.

6-14
 Porting Legacy Code

Porting Legacy Code

Find the States
If a variable step solver is being used, it is critical that all continuous states are
identified in the code and put into Simulink’s state vector for integration
instead of being integrated by the Fortran code. Likewise, all derivative
calculations must be made available separately to be called from the
mdlDerivatives() method in the S-function. Without these steps, any Fortran
code with continuous states will not be compatible with variable step solvers,
if the S-function is registered as a continuous block with continuous states.
Telltale signs of implicit advancement are incremented variables such as M=M+1
or X=X+0.05. If the code has many of these constructs and you determine that
it is impractical to recode the source to not “ratchet forward,” you may need to
try another approach using fixed step solvers.
If it is impractical to find all the implicit states and to separate out the
derivative calculations for Simulink, another approach can be used, but you are
limited to using fixed step solvers. The technique here is to call the Fortran
code from the mdlUpdate() method so the Fortran code is only executed once
per Simulink major integration step. Any block outputs must be cached in a
work vector so that mdlOutputs() can be called as often as needed and output
the values from the work vector instead of calling the Fortran routine again
(which would cause it to inadvertently advance time). See matlabroot/
simulink/src/sfuntmpl_gate_fortran.c for an example that uses DWork
vectors.

Sample Times
Be sure if the code has an implicit step size in its algorithm, coefficients, etc.,
that you register the proper discrete sample time in the
mdlInitializeSampleTimes() S-function method and only change the block's
output values from the mdlUpdate() method.

Multiple Instances
If you plan on having multiple copies of this S-function used in one Simulink
model, it is necessary to allocate storage for each copy of the S-function in the
model. The recommended approach is to use DWork vectors, see matlabroot/

6-15
6 Creating Fortran S-Functions

simulink/include/simstruc.h and matlabroot/simulink/src/

sfuntmpl_doc.c for details on allocating data typed work vectors.

Use Flints If Needed

Use flints (floating-point ints) to keep track of time. Flints (for IEEE-754
floating-point numerics) have the useful property of not accumulating round off
error when adding and subtracting flints. Using flint variables in DOUBLE
PRECISION storage (with integer values) avoids round off error accumulation
that would accumulate when floating point numbers are added together
thousands of times.
DOUBLE PRECISION F
:
:
F = F + 1.0
TIME = 0.003 * F

This technique avoids a common pitfall in simulations.

Considerations for Real Time

Since very few Fortran applications are used in a real-time environment, it is
more common to come across simulation code that is incompatible with a
real-time environment. Common failures include unbounded (or large)
iterations and sporadic but time-intensive side calculations. These must be
dealt with directly if there is to be any hope of running in real time.
Conversely, it is still perfectly good practice to have iterative or sporadic
calculations if the generated code is not being used for a real-time application.

6-16
 7
Implementing
Block Features
Introduction . . . . . . . . . . . . . . . . . . . . 7-2

Dialog Parameters . . . . . . . . . . . . . . . . . 7-3

Run-Time Parameters . . . . . . . . . . . . . . . . 7-6

Input and Output Ports . . . . . . . . . . . . . . . 7-9

Custom Data Types . . . . . . . . . . . . . . . . . 7-15

Sample Times . . . . . . . . . . . . . . . . . . . . 7-16

Work Vectors . . . . . . . . . . . . . . . . . . . . 7-24

Function-Call Subsystems . . . . . . . . . . . . . . 7-29

Handling Errors . . . . . . . . . . . . . . . . . . 7-31

S-Function Examples . . . . . . . . . . . . . . . . 7-34

7 Implementing Block Features

Introduction
This chapter explains how to use S-function callback methods to implement
various block features.

7-2
 Dialog Parameters

Dialog Parameters
A user can pass parameters to an S-function at the start of and, optionally,
during the simulation, using the S-Function parameters field of the block’s
dialog box. Such parameters are called dialog box parameters to distinguish
them from run-time parameters created by the S-function to facilitate code
generation (see “Run-Time Parameters” on page 7-6). Simulink stores the
values of the dialog box parameters in the S-function’s SimStruct structure.
Simulink provides callback methods and SimStruct macros that allow the
S-function to access and check the parameters and use them in the
computation of the block’s output.
If you want your S-function to be able to use dialog parameters, you must
perform the following steps when you create the S-function:

1 Determine the order in which the parameters are to be specified in the

block’s dialog box.

2 In the mdlInitializeSizes function, use the ssSetNumSFcnParams macro to

tell Simulink how many parameters the S-function accepts. Specify S as the
first argument and the number of parameters you are defining interactively
as the second argument. If your S-function implements the
mdlCheckParameters method, the mdlInitializeSizes routine should call
mdlCheckParameters to check the validity of the initial values of the
parameters.

3 Access these input arguments in the S-function using the ssGetSFcnParam

macro.

Specify S as the first argument and the relative position of the parameter in
the list entered on the dialog box (0 is the first position) as the second
argument. The ssGetSFcnParam returns a pointer to the mxArray containing
the parameter. You can use ssGetDTypeIdFromMxArray to get the data type
of the parameter.
When running a simulation, the user must specify the parameters in the
S-Function parameters field of the block’s dialog box in the same order that
you defined them in step 1 above. The user can enter any valid MATLAB
expression as the value of a parameter, including literal values, names of
workspace variables, function invocations, or arithmetic expressions. Simulink
evaluates the expression and passes its value to the S-function.

7-3
7 Implementing Block Features

For example, the following code is part of a device driver S-function. Four input
parameters are used: BASE_ADDRESS_PRM, GAIN_RANGE_PRM, PROG_GAIN_PRM,
and NUM_OF_CHANNELS_PRM. The code uses #define statements to associate
particular input arguments with the parameter names.
/* Input Parameters */
#define BASE_ADDRESS_PRM(S) ssGetSFcnParam(S, 0)
#define GAIN_RANGE_PRM(S) ssGetSFcnParam(S, 1)
#define PROG_GAIN_PRM(S) ssGetSFcnParam(S, 2)
#define NUM_OF_CHANNELS_PRM(S) ssGetSFcnParam(S, 3)

When running the simulation, a user would enter four variable names or
values in the S-Function parameters field of the block’s dialog box. The first
corresponds to the first expected parameter, BASE_ADDRESS_PRM(S). The
second corresponds to the next expected parameter, and so on.
The mdlInitializeSizes function contains this statement.
ssSetNumSFcnParams(S, 4);

Tunable Parameters
Dialog parameters can be either tunable or nontunable. A tunable parameter
is a parameter that a user can change while the simulation is running. Use the
macro ssSetSFcnParamTunable in mdlInitializeSizes to specify the
tunability of each dialog parameter used by the macro.

Note Dialog parameters are tunable by default. Nevertheless, it is good

programming practise to set the tunability of every parameter, even those that
are tunable. If the user enables the simulation diagnostic, S-function
upgrade needed, Simulink issues the diagnostic whenever it encounters an
S-function that fails to specify the tunability of all its parameters.

The mdlCheckParameters method enables you to validate changes to tunable

parameters during a simulation run. Simulink invokes the
mdlCheckParameters method whenever a user changes the values of
parameters during the simulation loop. This method should check the
S-function’s dialog parameters to ensure the changes are valid.

7-4
 Dialog Parameters

Note The S-function’s mdlInitializeSizes routine should also invoke the

mdlCheckParameters method to ensure that the initial values of the
parameters are valid.

The optional mdlProcessParameters callback method allows an S-function to

process changes to tunable parameters. Simulink invokes this method only if
valid parameter changes have occurred in the previous time step. A typical use
of this method is to perform computations that depend only on the values of
parameters and hence need to be computed only when parameter values
change. The method can cache the results of the parameter computations in
work vectors or, preferably, as run-time parameters (see “Run-Time
Parameters” on page 7-6).

Tuning Parameters in External Mode

When a user tunes parameters during simulation, Simulink invokes the
S-function’s mdlCheckParameters method to validate the changes and then the
S-functions’ mdlProcessParameters method to give the S-function a chance to
process the parameters in some way. When running in external mode,
Simulink invokes these methods as well but it passed the unprocessed changes
onto the S-function target. Thus, if it is essential that your S-function process
parameter changes, you need to create a Target Language Compiler (TLC) file
that inlines the S-function, including its parameter processing code, during the
code generation process. For information on inlining S-functions, see the
Target Language Compiler Reference Guide.

7-5
7 Implementing Block Features

Run-Time Parameters
Simulink allows an S-function to create and use internal representations of
external dialog parameters called run-time parameters. Every run-time
parameter corresponds to one or more dialog parameters and can have the
same value and data type as its corresponding external parameter(s) or a
different value or data type. If a run-time parameter differs in value or data
type from its external counterpart, the dialog parameter is said to have been
transformed to create the run-time parameter. The value of a run-time
parameter that corresponds to multiple dialog parameter is typically a function
of the values of the dialog parameters. Simulink allocates and frees storage for
run-time parameters and provides functions for updating and accessing them,
thus eliminating the need for S-functions to performs these tasks.
Run-time parameters facilitate the following kinds of S-function operations:

• Computed parameters
Often the output of a block is a function of the values of several dialog
parameters. For example, suppose a block has two parameters, the volume
and density of some object, and the output of the block is a function of the
input signal and the weight of the object. In this case, the weight can be
viewed as a third internal parameter computed from the two external
parameters, volume and density. An S-function can create a run-time
parameter corresponding to the computed weight, thereby eliminating the
need to provide special case handling for weight in the output computation.
• Data type conversions
Often a block may need to change the data type of a dialog parameter to
facilitate internal processing. For example, suppose that the output of the
block is a function of the input and a parameter and the input and parameter
are of different data types. In this case, the S-function can create a run-time
parameter that has the same value as the dialog parameter but has the data
type of the input signal and use the run-time parameter in the computation
of the output.
• Code generation
During code generation, Real-Time Workshop writes all run-time
parameters automatically to the model.rtw file, eliminating the need for
the S-function to perform this task via a mdlRTW method.

7-6
 Run-Time Parameters

Creating Run-Time Parameters

An S-function can create run-time parameters all at once or one by one.

Creating Run-Time Parameters All at Once

Use the SimStruct function, ssRegAllTunableParamsAsRunTimeParams, in
mdlSetWorkWidths to create run-time parameters corresponding to all tunable
parameters. This function requires that you pass it an array of names, one for
each run-time parameter. Real-Time Workshop uses this name as the name of
the parameter during code generation.
This approach to creating run-time parameters assumes that there is a
one-to-one correspondence between an S-function’s run-time parameters and
its tunable dialog parameters. This may not be the case. For example, an
S-function may want to use a computed parameter whose value is a function of
several dialog parameters. In such cases, the S-function may need to create the
run-time parameters individually.

Creating Run-Time Parameters Individually

To create run-time parameters individually, the S-function’s
mdlSetWorkWidths method should:

1 Specify the number of run-time parameters it intends to use, using

ssSetNumRunTimeParams.

2 Specify the attributes of each run-time parameter, using

ssSetRunTimeParamInfo.

Updating Run-Time Parameters

Whenever a user changes the values of an S-function’s dialog parameters
during a simulation run, Simulink invokes the S-function’s
mdlCheckParameters method to validate the changes. If the changes are valid,
Simulink invokes the S-function’s mdlProcessParameters method at the
beginning of the next time step. This method should update the S-function’s
run-time parameters to reflect the changes in the dialog parameters.

Updating All Parameters at Once

If there is a one-to-one correspondence between the S-function’s tunable dialog
parameters and the run-time parameters, the S-function can use the

7-7
7 Implementing Block Features

SimStruct function, ssUpdateAllTunableParamsAsRunTimeParams, to

accomplish this task. This function updates each run-time parameter to have
the same value as the corresponding dialog parameter.

Updating Parameters Individually

If there is not a one-to-one correspondence between the S-function’s dialog and
run-time parameters or the run-time parameters are transformed versions of
the dialog parameters, the mdlProcessParameters method must update each
parameter individually.
If a run-time parameter and its corresponding dialog parameter differ only in
value, the method can use the SimStruct macro, ssUpdateRunTimeParamData,
to update the run-time parameter. This function updates the data field in the
parameter’s attributes record (ssParamRec) with a new value. Otherwise, the
mdlProcessParameters method must update the parameter’s attributes record
itself.To update the attributes record, the method should:

1 Get a pointer to the parameter’s attributes record, using

ssGetRunTimeParamIInfo.

2 Update the attributes record to reflect the changes in the corresponding

dialog parameter(s).

3 Register the changes, using ssUpdateRunTimeParamInfo.

7-8
 Input and Output Ports

Input and Output Ports

Simulink allows S-functions to create and use any number of block I/O ports.
This section shows how to create and initialize I/O ports and how to change the
characteristics of an S-function block’s ports, such as dimensionality and data
type, based on its connections to other blocks.

Creating Input Ports

To create and configure input ports, the mdlInitializeSizes method should
first specify the number of input ports that the S-function has, using
ssSetNumInputPorts. Then, for each input port, the method should specify:

• The dimensions of the input port (see “Initializing Input Port Dimensions”
on page 7-10)
If you want your S-function to inherit its dimensionality from the port to
which it is connected, you should specify that the port is dynamically sized
in mdlInitializeSizes (see “Sizing an Input Port Dynamically” on
page 7-10).
• Whether the input port allows scalar expansion of inputs (see “Scalar
Expansion of Inputs” on page 7-12)
• Whether the input port has direct feedthrough, using
ssSetInputPortDirectFeedThrough
A port has direct feedthrough if the input is used in either the mdlOutputs or
mdlGetTimeOfNextVarHit functions. The direct feedthrough flag for each
input port can be set to either 1=yes or 0=no. It should be set to 1 if the input,
u, is used in the mdlOutput or mdlGetTimeOfNextVarHit routine. Setting the
direct feedthrough flag to 0 tells Simulink that u will not be used in either of
these S-function routines. Violating this will lead to unpredictable results.
• The data type of the input port, if not the default double
Use ssSetInputPortDataType to set the input port’s data type. If you want
the data type of the port to depend on the data type of the port to which it is
connected, specify the data type as DYNAMICALLY_TYPED. In this case, you
must provide implementations of the mdlSetInputPortDataType and
mdlSetDefaultPortDataTypes methods to enable the data type to be set
correctly during signal propagation.

7-9
7 Implementing Block Features

• The numeric type of the input port, if the port accepts complex-valued signals
Use ssSetInputComplexSignal to set the input port’s numeric type. If you
want the numeric type of the port to depend on the numeric type of the port
to which it is connected, specify the data type as inherited. In this case, you
must provide implementations of the mdlSetInputPortComplexSignal and
mdlSetDefaultPortComplexSignal methods to enable the numeric type to
be set correctly during signal propagation.

Note The mdlInitializeSizes method must specify the number of ports

before setting any properties. If it attempts to set a property of a port that
doesn't exist, it will be accessing invalid memory and Simulink will crash.

Initializing Input Port Dimensions

The following options exist for setting the input port dimensions:.

• If the input signal is one-dimensional, and the input port width is w, use
ssSetInputPortVectorDimension(S, inputPortIdx, w)
• If the input signal is a matrix of dimension m-by-n, use
ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)
• Otherwise use
ssSetInputPortDimensionInfo(S, inputPortIdx, dimsInfo)
This function can be used to fully or partially initialize the port dimensions
(see next section).

Sizing an Input Port Dynamically

If your S-function does not require that an input signal have a specific
dimensionality, you may want to set the dimensionality of the input port to
match the dimensionality of the signal actually connected to the port. To
dimension an input port dynamically, your S-function should:

• Specify some or all of the dimensions of the input port as dynamically sized
in mdlInitializeSizes

7-10
 Input and Output Ports

- If the input port can accept a signal of any dimensionality, use

ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION)
to set the dimensionality of the input port.
- If the input port can accept only vector (1-D) signals but the signals can be
of any size, use
ssSetInputPortWidth(S, inputPortIdx, DYNAMICALLY_SIZED)
to specify the dimensionality of the input port.
If the input port can accept only matrix signals but can accept any row or
column size, use
ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)
where m and/or n are DYNAMICALLY_SIZED.
• Provide a mdlSetInputPortDimensionInfo method that sets the dimensions
of the input port to the size of the signal connected to it
Simulink invokes this method during signal propagation when it has
determined the dimensionality of the signal connected to the input port.
• Provide a mdlSetDefaultPortDimensionInfo method that sets the
dimensions of the block’s ports to a default value
Simulink invokes this method during signal propagation when it cannot
determine the dimensionality of the signal connected to some or all of the
block’s input ports. This can happen, for example, if an input port is
unconnected. If the S-function does not provide this method, Simulink sets
the dimension the block’s ports to 1-D scalar.

Creating Output Ports

To create and configure output ports, the mdlInitializeSizes method should
first specify the number of input ports that the S-function has, using
ssSetNumOutputPorts. Then, for each output port, the method should specify:

• Dimensions of the output port

Simulink provides the following macros for setting the port’s dimensions.
- ssSetOutputPortDimensionInfo
- ssSetOutputPortMatrixDimensions
- ssSetOutputPortVectorDimensions
- ssSetOutputWidth

7-11
7 Implementing Block Features

If you want the port’s dimensions to depend on block connectivity, set the
dimensions to DYNAMICALLY_SIZED. The S-function must then provide
mdlSetOutputPortDimensionInfo and ssSetDefaultPortDimensionInfo
methods to ensure that output port dimensions are set to the correct values
in code generation.
• Data type of the output port
Use ssSetOutputPortDataType to set the output port’s data type. If you want
the data type of the port to depend on block connectivity, specify the data
type as DYNAMICALLY_TYPED. In this case, you must provide implementations
of the mdlSetOutputPortDataType and mdlSetDefaultPortDataTypes
methods to enable the data type to be set correctly during signal propagation.
• The numeric type of the input port, if the port outputs complex-valued
signals
Use ssSetOutputComplexSignal to set the output port’s numeric type. If you
want the numeric type of the port to depend on the numeric type of the port
to which it is connected, specify the data type as inherited. In this case, you
must provide implementations of the mdlSetOutputPortComplexSignal and
mdlSetDefaultPortComplexSignal methods to enable the numeric type to
be set correctly during signal propagation.

Scalar Expansion of Inputs

Scalar expansion of inputs refers conceptually to the process of expanding
scalar input signals to have the same dimensions as the port to which they are
connected. This is done by setting each element of the expanded signal to the
value of the scalar input. An S-function’s mdlInitializeSizes method can
enable scalar expansion of inputs for its input ports by setting the
SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION option, using ssSetOptions.

The best way to understand the scalar expansion rules is to consider a sum
block with two input ports, where the first input signal is scalar, the second
input signal is a 1-D vector with w > 1 elements, and the output signal is a 1-D
vector with w elements. In this case, the scalar input is expanded to a 1-D vector
with w elements in the output method, and each element of the expanded signal
is set to the value of the scalar input.
Outputs
<snip>
u1inc = (u1width > 1);

7-12
 Input and Output Ports

u2inc = (u2width > 1);

for (i=0;i<w;i++) {
y[i] = *u1 + *u2;
u1 += u1inc;
u2 += u2inc;
}

If the block has more than two inputs, each input signal must be scalar, or the
wide signals must have the same number of elements. In addition, if the wide
inputs are driven by 1-D and 2-D vectors, the output will be a 2-D vector signal,
and the scalar inputs are expanded to a 2-D vector signal.
The way scalar expansion actually works depends on whether the S-function
manages the dimensions of its input and output ports using
mdlSetInputPortWidth and mdlSetOutputPortWidth or
mdlSetInputPortDimensionInfo, mdlSetOutputPortDimensionInfo, and
mdlSetDefaultPortDimensionInfo.

If the S-function does not specify/control the dimensions of its input and output
ports using the above methods, Simulink uses a default method to set the input
and output ports using the above methods, Simulink uses a default method to
set the S-function port dimensions.
In mdlInitializeSizes method, the S-function can enable scalar expansion
for its input ports by setting the SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION
option, using ssSetOptions. Simulink default method uses the above option to
allow or disallow scalar expansion for a block input ports. If the above option is
not set by an S-function, Simulink assumes all ports (input and output ports)
must have the same dimensions, and it sets all port dimensions to the same
dimensions specified by one of the driving blocks.
If the S-function specifies/controls the dimensions of its input and output ports,
Simulink ignores the SCALAR_EXPANSION option.
See matlabroot/simulink/src/sfun_multiport.c for an example.

Masked Multiport S-Functions

If you are developing masked multiport S-function blocks whose number of
ports varies based on some parameter, and if you want to place them in a
Simulink library, then you must specify that the mask modifies the appearance
of the block. To do this, execute this command

7-13
7 Implementing Block Features

set_param('block','MaskSelfModifiable','on')

at the MATLAB prompt before saving the library. Failure to specify that the
mask modifies the appearance of the block means that an instance of the block
in a model reverts to the number of ports in the library whenever you load the
model or update the library link.

7-14
 Custom Data Types

Custom Data Types

An S-function can accept and output user-defined as well as built-in Simulink
data types. To use a user-defined data type, the S-function’s mdlInitializeSizes
routine must:

1 Register the data type, using ssRegisterDataType.

2 Specify the amount of memory in bytes required to store an instance of the

data type, using ssSetDataTypeSize.

3 Specify the value that represents zero for the data type, using
ssSetDataTypeZero.

7-15
7 Implementing Block Features

Sample Times
Simulink supports blocks that execute at different rates. An S-function block
can specify its rates (i.e., sample times) as:

• Block-based sample times

• Port-based sample times
• Hybrid block-based and port-based sample times

With block-based sample times, the S-function specifies a set of operating rates
for the block as a whole during the initialization phase of the simulation.With
port-based sample times, the S-function specifies a sample time for each input
and output port individually during initialization. During the execution phase,
with block-based sample times, the S-function processes all inputs and outputs
each time a sample hit occurs for the block. By contrast, with port-based
sample times, the block processes a particular port only when a sample hit
occurs for that port.
For example, consider two sample rates, 0.5 and 0.25 seconds, respectively:

• In the block-based method, selecting 0.5 and 0.25 would direct the block to
execute inputs and outputs at 0.25 second increments.
• In the port-based method, you could set the input port to 0.5 and the output
port to 0.25, and the block would process inputs at 2Hz and outputs at 4Hz.

You should use port-based sample times if your application requires unequal
sample rates for input and output execution or if you don’t want the overhead
associated with running input and output ports at the highest sample rate of
your block.
In some applications, an S-Function block may need to operate internally at
one or more sample rates while inputting or outputting signals at other rates.
The hybrid block- and port-based method of specifying sample rates allows you
to create such blocks.
In typical applications, you will specify only one block-based sample time.
Advanced S-functions may require the specification of port-based or multiple
block sample times.

Block-Based Sample Times

The next two sections discuss how to specify block-based sample times. You
must specify information in

7-16
 Sample Times

• mdlInitializeSizes
• mdlInitializeSampleTimes
A third sections presents a simple example that shows how to specify sample
times in mdlInitializeSampleTimes.

Specifying the Number of Sample Times in mdlInitializeSizes. To configure your

S-function block for block-based sample times, use
ssSetNumSampleTimes(S,numSampleTimes);

where numSampleTimes > 0. This tells Simulink that your S-function has
block-based sample times. Simulink calls mdlInitializeSampleTimes, which
in turn sets the sample times.

Setting Sample Times and Specifying Function Calls in

mdlInitializeSampleTimes
mdlInitializeSampleTimes is used to specify two pieces of execution
information:

• Sample and offset times — In mdlInitializeSizes, specify the number of

sample times you’d like your S-function to have by using the
ssSetNumSampleTimes macro. In mdlInitializeSampleTimes, you must
specify the sampling period and offset for each sample time.
Sample times can be a function of the input/output port widths. In
mdlInitializeSampleTimes, you can specify that sample times are a
function of ssGetInputPortWidth and ssGetGetOutputPortWidth.
• Function calls — In ssSetCallSystemOutput, specify which output elements
are performing function calls. See matlabroot/simulink/src/
sfun_fcncall.c for an example.

The sample times are specified as pairs [sample_time, offset_time] by using

these macros
ssSetSampleTime(S, sampleTimePairIndex, sample_time)
ssSetOffsetTime(S, offsetTimePairIndex, offset_time)

where sampleTimePairIndex starts at 0.

The valid sample time pairs are (upper-case values are macros defined in
simstruc.h).

7-17
7 Implementing Block Features

[CONTINUOUS_SAMPLE_TIME, 0.0 ]
[CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
[discrete_sample_period, offset ]
[VARIABLE_SAMPLE_TIME , 0.0 ]

Alternatively, you can specify that the sample time is inherited from the
driving block in which case the S-function can have only one sample time pair
[INHERITED_SAMPLE_TIME, 0.0 ]

or
[INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

The following guidelines may help aid in specifying sample times:

• A continuous function that changes during minor integration steps should

register the [CONTINUOUS_SAMPLE_TIME, 0.0] sample time.
• A continuous function that does not change during minor integration steps
should register the
[CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.
• A discrete function that changes at a specified rate should register the
discrete sample time pair
[discrete_sample_period, offset]

where
discrete_sample_period > 0.0

and
0.0 <= offset < discrete_sample_period

• A discrete function that changes at a variable rate should register the

variable step discrete [VARIABLE_SAMPLE_TIME, 0.0] sample time. The
mdlGetTimeOfNextVarHit function is called to get the time of the next
sample hit for the variable step discrete task. The VARIABLE_SAMPLE_TIME
can be used with variable step solvers only.

If your function has no intrinsic sample time, then you must indicate that it is
inherited according to the following guidelines:

• A function that changes as its input changes, even during minor integration
steps, should register the [INHERITED_SAMPLE_TIME, 0.0] sample time.

7-18
 Sample Times

• A function that changes as its input changes, but doesn’t change during
minor integration steps (that is, held during minor steps), should register the
[INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.
To check for a sample hit during execution (in mdlOutputs or mdlUpdate), use
the ssIsSampleHit or ssIsContinuousTask macro. For example, if your first
sample time is continuous, then you used the following code fragment to check
for a sample hit. Note that you would get incorrect results if you used
ssIsSampleHit(S,0,tid).
if (ssIsContinuousTask(S,tid)) {
}

If, for example, you wanted to determine if the third (discrete) task has a hit,
then you would use the following code-fragment.
if (ssIsSampleHit(S,2,tid) {
}

Example: mdlInitializeSampleTimes
This example specifies that there are two discrete sample times with periods of
0.01 and 0.5 seconds.
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, 0.01);
ssSetOffsetTime(S, 0, 0.0);
ssSetSampleTime(S, 1, 0.5);
ssSetOffsetTime(S, 1, 0.0);
} /* End of mdlInitializeSampleTimes. */

Port-Based Sample Times

The next three sections discuss how to specify port-based sample times. You
must specify information in:
• mdlInitializeSizes
• mdlSetInputPortSampleTime
• mdlSetOutputPortSampleTime

7-19
7 Implementing Block Features

Specifying the Number of Sample Times in

mdlInitializeSizes
To specify port-based sample times, use
ssSetNumSampleTimes(S, PORT_BASED_SAMPLE_TIMES)

with:
ssSetInputPortSampleTime(S, idx, period)
ssSetInputPortOffsetTime(S, idx, offset)
ssSetOutputPortSampleTime(S, idx, period)
ssSetOutputPortOffsetTime(S, idx, offset)

The inputPortIndex and outputPortIndex range from 0 to the number of

input (output) ports minus 1.
When you specify port based sample times, Simulink will call
mdlSetInputPortSampleTime and mdlSetOutputPortSampleTime to determine
the rates of inherited signals. Once all rates have been determined completed,
Simulink will also call mdlInitializeSampleTimes to configure function-call
connections. If your S-function does not have any function-call connections this
routine should be empty.

Note mdlInitializeSizes should not contain any ssSetSampleTime or

ssSetOffsetTime calls when using port-based sample times.

Hybrid Block-Based and Port-Based Sample Times

The hybrid method of assigning sample times combines the block-based and
port-based methods. You first specify, in mdlInitializeSizes, the total
number of rates at which your block operates, including both internal and
input and output rates, using ssSetNumSampleTimes. You then set the
SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED, using ssSetOption, to tell the
simulation engine that you are going to use the port-based method to specify
the rates of the input and output ports individually. Next, as in the block-based
method, you specify the period and offset of all of the block’s rates, both internal
and external, using
ssSetSampleTime
ssSetOffsetTime

7-20
 Sample Times

Finally, as in the port-based method, you specify the rates for each port, using
ssSetInputPortSampleTime(S, idx, period)
ssSetInputPortOffsetTime(S, idx, offset)
ssSetOutputPortSampleTime(S, idx, period)
ssSetOutputPortOffsetTime(S, idx, offset)

Note that each of the assigned port rates must be the same as one of the
previously declared block rates.

Multirate S-Function Blocks

In a multirate S-Function block, you can encapsulate the code that defines each
behavior in the mdlOutput and mdlUpdate functions with a statement that
determines whether a sample hit has occurred. The ssIsSampleHit macro
determines whether the current time is a sample hit for a specified sample
time. The macro has this syntax
ssIsSampleHit(S, st_index, tid)

where S is the SimStruct, st_index identifies a specific sample time index, and
tid is the task ID (tid is an argument to the mdlOutput and mdlUpdate).

For example, these statements specify three sample times: one for continuous
behavior, and two for discrete behavior.
ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetSampleTime(S, 1, 0.75);
ssSetSampleTime(S, 2, 1.0);

In the mdlUpdate function, the following statement would encapsulate the code
that defines the behavior for the sample time of 0.75 second.
if (ssIsSampleHit(S, 1, tid)) {
}

The second argument, 1, corresponds to the second sample time, 0.75 second.

Example - Defining a Sample Time for a Continuous Block

This example defines a sample time for a block that is continuous in nature.
/* Initialize the sample time and offset. */
static void mdlInitializeSampleTimes(SimStruct *S)
{

7-21
7 Implementing Block Features

ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}

You must add this statement to the mdlInitializeSizes function.

ssSetNumSampleTimes(S, 1);

Example - Defining a Sample Time for a Hybrid Block

This example defines sample times for a hybrid S-Function block.
/* Initialize the sample time and offset. */
static void mdlInitializeSampleTimes(SimStruct *S)
{
/* Continuous state sample time and offset. */
ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);

/* Discrete state sample time and offset. */

ssSetSampleTime(S, 1, 0.1);
ssSetOffsetTime(S, 1, 0.025);
}

In the second sample time, the offset causes Simulink to call the mdlUpdate
function at these times: 0.025 second, 0.125 second, 0.225 second, and so on, in
increments of 0.1 second.
The following statement, which indicates how many sample times are defined,
also appears in the mdlInitializeSizes function.
ssSetNumSampleTimes(S, 2);

Synchronizing Multirate S-Function Blocks

If tasks running at different rates need to share data, you must ensure that
data generated by one task is valid when accessed by another task running at
a different rate. You can use the ssIsSpecialSampleHit macro in the
mdlUpdate or mdlOutputs routines of a multirate S-Function to ensure that
the shared data is valid. This macro returns true if a sample hit has occurred
at one rate and a sample hit has also occurred at another rate in the same time
step. It thus permits a higher rate task to provide data needed by a slower rate
task at a rate the slower task can accommodate.

7-22
 Sample Times

Suppose, for example, that your model has an input port operating at one rate,
0, and an output port operating at a slower rate, 1. Further, suppose that you
want the output port to output the value currently on the input. The following
example illustrates usage of this macro.
if (ssISampleHit(S, 0, tid) {
if (ssIsSpecialSampleHit(S, 0, 1, tid) {
/* Transfer input to output memory. */
...
}
}

if (ssIsSampleHit(S, 1, tid) {
/* Emit output. */
...
}

In this example, the first block runs when a sample hit occurs at the input rate.
If the hit also occurs at the output rate, the block transfers the input to the
output memory. The second block runs when a sample hit occurs at the output
rate. It transfers the output in its memory area to the block’s output.
Note that higher-rate tasks always run before slower-rate tasks. Thus, the
input task in the preceding example always runs before the output task,
ensuring that valid data is always present at the output port.

7-23
7 Implementing Block Features

Work Vectors
If your S-function needs persistent memory storage, use S-function work
vectors instead of static or global variables. If you use static or global variables,
they are used by multiple instances of your S-function. This occurs when you
have multiple S-Function blocks in a Simulink model and the same S-function
C MEX-file has been specified. The ability to keep track of multiple instances
of an S-function is called re-entrancy.
You can create an S-function that is re-entrant by using work vectors. These
are persistent storage locations that Simulink manages for an S-function.
Integer, floating point (real), pointer, and general data types are supported.
The number of elements in each vector can be specified dynamically as a
function of the number of inputs to the S-function.
Work vectors have several advantages:

• Instance specific storage for block variables

• Integer, real, pointer, and general data types
• Elimination of static and global variables and the associated multiple
instance problems

For example, suppose you’d like to track the previous value of each input signal
element entering input port 1 of your S-function. Either the discrete-state
vector or the real-work vector could be used for this, depending upon whether
the previous value is considered a discrete state (that is, compare the unit delay
and the memory block). If you do not want the previous value to be logged when
states are saved, use the real-work vector, rwork. To do this, in
mdlInitializeSizes specify the length of this vector by using ssSetNumRWork.
Then in either mdlStart or mdlInitializeConditions, initialize the rwork
vector, ssGetRWork. In mdlOutputs, you can retrieve the previous inputs by
using ssGetRWork. In mdlUpdate, update the previous value of the rwork vector
by using ssGetInputPortRealSignalPtrs.

7-24
 Work Vectors

Use the macros in this table to specify the length of the work vectors for each
instance of your S-function in mdlInitializeSizes.

Table 7-1: Macros Used in Specifying Vector Widths

Macro Description

ssSetNumContStates Width of the continuous-state vector

ssSetNumDiscStates Width of the discrete-state vector
ssSetNumDWork Width of the data type work vector
ssSetNumRWork Width of the real-work vector
ssSetNumIWork Width of the integer-work vector
ssSetNumPWork Width of the pointer-work vector
ssSetNumModes Width of the mode-work vector
ssSetNumnonsampledZCs Width of the nonsampled zero-crossing
vector

Specify vector widths in mdlInitializeSizes. There are three choices:

• 0 (the default). This indicates that the vector is not used by your S-function.
• A positive nonzero integer. This is the width of the vector that will be
available for use by mdlStart, mdlInitializeConditions, and S-function
routines called in the simulation loop.
• The DYNAMICALLY_SIZED define. The default behavior for dynamically sized
vectors is to set them to the overall block width. Simulink does this after
propagating line widths and sample times. The block width is the width of
the signal passing through your block. In general this is equal to the output
port width.

If the default behavior of dynamically sized vectors does not meet your needs,
use mdlSetWorkWidths and the macros listed in Table 7-1, Macros Used in
Specifying Vector Widths to set explicitly the sizes of the work vectors. Also,
mdlSetWorkWidths allows you to set your work vector lengths as a function of
the block sample time and/or port widths.

7-25
7 Implementing Block Features

The continuous states are used when you have a state that needs to be
integrated by one of Simulink’s solvers. When you specify continuous states,
you must return the states’ derivatives in mdlDerivatives. The discrete state
vector is used to maintain state information that changes at fixed intervals.
Typically the discrete state vector is updated in place in mdlUpdate.
The integer, real and pointer work vectors are storage locations that do not get
logged by Simulink during simulations. They maintain persistent data
between calls to your S-function.

Work Vectors and Zero Crossings

The mode-work vector and the nonsampled zero-crossing vector are typically
used with zero crossings. Elements of the mode vector are integer values. You
specify the number of mode-vector elements in mdlInitializeSizes using
ssSetNumModes(S,num). You can then access the mode vector using
ssGetModeVector. The mode vector is used to determine how the mdlOutput
routine should operate when the solvers are honing in on zero crossings. The
zero crossings or state events (i.e., discontinuities in the first derivatives) of
some signal, usually a function of an input to your S-function, are tracked by
the solver by looking at the nonsampled zero crossings. To register nonsampled
zero crossings, set the number of nonsampled zero crossings in
mdlInitializeSizes using ssSetNumNonsampledZCs(S, num). Then, define
the mdlZeroCrossings routine to return the nonsampled zero crossings. See
matlabroot/simulink/src/sfun_zc.c for an example.

An Example Involving a Pointer Work Vector

This example opens a file and stores the FILE pointer in the pointer-work
vector.
The statement below, included in the mdlInititalizeSizes function, indicates
that the pointer-work vector is to contain one element.
ssSetNumPWork(S, 1) /* pointer-work vector */

The code below uses the pointer-work vector to store a FILE pointer, returned
from the standard I/O function, fopen.
#define MDL_START /* Change to #undef to remove function. */
#if defined(MDL_START)
static void mdlStart(real_T *x0, SimStruct *S)

7-26
 Work Vectors

{
FILE *fPtr;
void **PWork = ssGetPWork(S);
fPtr = fopen("file.data", "r");
PWork[0] = fPtr;
}
#endif /* MDL_START */

This code retrieves the FILE pointer from the pointer-work vector and passes it
to fclose to close the file.
static void mdlTerminate(SimStruct *S)
{
if (ssGetPWork(S) != NULL) {
FILE *fPtr;
fPtr = (FILE *) ssGetPWorkValue(S,0);
if (fPtr != NULL) {
fclose(fPtr);
}
ssSetPWorkValue(S,0,NULL);
}
}

Note If you are using mdlSetWorkWidths, then any work vectors you use in
your S-function should be set to DYNAMICALLY_SIZED in mdlInitializeSizes,
even if the exact value is known before mdlIntializeSizes is called. The size
to be used by the S-function should be specified in mdlSetWorkWidths.

The synopsis is
#define MDL_SET_WORK_WIDTHS /* Change to #undef to remove function. */
#if defined(MDL_SET_WORK_WIDTHS) && defined(MATLAB_MEX_FILE)
static void mdlSetWorkWidths(SimStruct *S)
{
}
#endif /* MDL_SET_WORK_WIDTHS */

For an example, see matlabroot/simulink/src/sfun_dynsize.c.

7-27
7 Implementing Block Features

Memory Allocation
When creating an S-function, it is possible that the available work vectors don’t
provide enough capability. In this case, you will need to allocate memory for
each instance of your S-function. The standard MATLAB API memory
allocation routines (mxCalloc, mxFree) should not be used with C MEX
S-functions. The reason is that these routines are designed to be used with
MEX-files that are called from MATLAB and not Simulink. The correct
approach for allocating memory is to use the stdlib.h (calloc, free) library
routines. In mdlStart allocate and initialize the memory and place the pointer
to it either in pointer-work vector elements
ssGetPWork(S)[i] = ptr;

or attach it as user data.

ssSetUserData(S,ptr);

In mdlTerminate, free the allocated memory.

7-28
 Function-Call Subsystems

Function-Call Subsystems
You can create a triggered subsystem whose execution is determined by logic
internal to an S-function instead of by the value of a signal. A subsystem so
configured is called a function-call subsystem. To implement a function-call
subsystem:

• In the Trigger block, select function-call as the Trigger type parameter.

• In the S-function, use the ssCallSystemWithTid macro to call the triggered
subsystem.
• In the model, connect the S-Function block output directly to the trigger port.

Note Function-call connections can only be performed on the first output

port.

Function-call subsystems are not executed directly by Simulink; rather, the

S-function determines when to execute the subsystem. When the subsystem
completes execution, control returns to the S-function. This figure illustrates
the interaction between a function-call subsystem and an S-function.
void mdlOutputs(SimStruct *S, int_T tid)
{
... f()
if (!ssCallSystemWithTid(S,outputElement,tid)) {
return; /* error or output is unconnected */
}
<next statement> Function-call
... subsystem
}

In this figure, ssCallSystemWithTid executes the function-call subsystem that

is connected to the first output port element. ssCallSystemWithTid returns 0
if an error occurs while executing the function-call subsystem or if the output
is unconnected. After the function-call subsystem executes, control is returned
to your S-function.
Function-call subsystems can only be connected to S-functions that have been
properly configured to accept them.

7-29
7 Implementing Block Features

To configure an S-function to call a function-call subsystem:

1 Specify which elements are to execute the function-call system in

mdlInitializeSampleTimes. For example,
ssSetCallSystemOutput(S,0); /* call on 1st element */
ssSetCallSystemOutput(S,2); /* call on 3rd element */

2 Execute the subsystem in the appropriate mdlOutputs or mdlUpdates

S-function routines. For example,

static void mdlOutputs(...)

{
if (((int)*uPtrs[0]) % 2 == 1) {
if (!ssCallSystemWithTid(S,0,tid)) {
/* Error occurred, which will be reported by Simulink */
return;
}
} else {
if (!ssCallSystemWithTid(S,2,tid)) {
/* Error occurred, which will be reported by Simulink */
return;
}
}
...
}

See simulink/src/sfun_fcncall.c for an example.

Function-call subsystems are a powerful modeling construct. You can configure
Stateflow® blocks to execute function-call subsystems, thereby extending the
capabilities and integration of the blocks. For more information on their use
in Stateflow, see the Stateflow documentation.

7-30
 Handling Errors

Handling Errors
When working with S-functions, it is important to handle unexpected events
correctly such as invalid parameter values.
If your S-function has parameters whose contents you need to validate, use the
following technique to report errors encountered.
ssSetErrorStatus(S,"error encountered due to ...");
return;

Note that the second argument to ssSetErrorStatus must be persistent

memory. It cannot be a local variable in your procedure. For example, the
following will cause unpredictable errors.
mdlOutputs()
{
char msg[256]; /* ILLEGAL: should be "static char msg[256];" */
sprintf(msg,"Error due to %s", string);
ssSetErrorStatus(S,msg);
return;
}

The ssSetErrorStatus error handling approach is the suggested alternative to

using the mexErrMsgTxt function. The function mexErrMsgTxt uses exception
handling to immediately terminate S-function execution and return control to
Simulink. In order to support exception handling inside of S-functions,
Simulink must set up exception handlers prior to each S-function invocation.
This introduces overhead into simulation.

Exception Free Code

You can avoid this overhead by ensuring that your S-function contains entirely
exception free code. Exception free code refers to code that never long jumps.
Your S-function is not exception free if it contains any routine that, when
called, has the potential of long jumping. For example mexErrMsgTxt throws an
exception (i.e., long jumps) when called, thus ending execution of your
S-function. Using mxCalloc may cause unpredictable results in the event of a
memory allocation error since mxCalloc will long jump. If memory allocation is
needed, use the stdlib.h calloc routine directly and perform your own error
handling.

7-31
7 Implementing Block Features

If you do not call mexErrMsgTxt or other API routines that cause exceptions,
then use the SS_OPTION_EXCEPTION_FREE_CODE S-function option. This is done
by issuing the following command in the mdlInitializeSizes function.
ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);

Setting this option will increase the performance of your S-function by allowing
Simulink to bypass the exception handling setup that is usually performed
prior to each S-function invocation. Extreme care must be taken to verify that
your code is exception free when using SS_OPTION_EXCEPTION_FREE_CODE. If
your S-function generates an exception when this option is set, unpredictable
results will occur.
All mex* routines have the potential of long jumping. In addition several mx*
routines have the potential of long jumping. To avoid any difficulties, use only
the API routines that retrieve a pointer or determine the size of parameters.
For example, the following will never throw an exception: mxGetPr, mxGetData,
mxGetNumberOfDimensions, mxGetM, mxGetN, and mxGetNumberOfElements.

Code in run-time routines can also throw exceptions. Run-time routines refer
to certain S-function routines that Simulink calls during the simulation loop
(see “How Simulink Interacts with C S-Functions” on page 3-32). The run-time
routines include:
• mdlGetTimeOfNextVarHit
• mdlOutputs
• mdlUpdate
• mdlDerivatives
If all run-time routines within your S-function are exception free, you can use
this option.
ssSetOptions(S, SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE);

The other routines in your S-function do not have to be exception free.

ssSetErrorStatus Termination Criteria

When you call ssSetErrorStatus and return from your S-function, Simulink
stops the simulation and posts the error. To determine how the simulation
shuts down, refer to the flow chart figure on “How Simulink Interacts with C
S-Functions” on page 3–32. If ssSetErrorStatus is called prior to mdlStart, no

7-32
 Handling Errors

other S-function routine will be called. If ssSetErrorStatus is called in

mdlStart or later, mdlTerminate will be called.

Checking Array Bounds

If your S-function causes otherwise inexplicable errors, the reason may be that
the S-function is writing beyond its assigned areas in memory. You can verify
this possibility by enabling Simulink’s array bounds checking feature. This
feature detects any attempt by an S-function block to write beyond the areas
assigned to it for the following types of block data:

• work vectors (R, I, P, D and mode)

• states (continuous and discrete)
• uutputs

To enable array bounds checking, select warning or error from the Bounds
checking options list on the Simulation Parameters dialog box or enter the
following command at the MATLAB command line.
set_param(modelName, 'ArrayBoundsChecking', 'none' | 'warning' |
'error')

7-33
7 Implementing Block Features

S-Function Examples
Most S-Function blocks require the handling of states, continuous or discrete.
The following sections discuss common types of systems that you can model in
Simulink with S-functions:

• Continuous state
• Discrete state
• Hybrid
• Variable step sample time
• Zero crossings
• Time varying continuous transfer function

All examples are based on the C MEX-file S-function template,

sfuntmpl_basic.c, and sfuntmpl_doc.c, which contains a discussion of the
S-function template.

Example - Continuous State S-Function

The matlabroot/simulink/src/csfunc.c example shows how to model a
continuous system with states in a C MEX S-function. In continuous state
integration, there is a set of states that Simulink’s solvers integrate using the
equations.

u xc y
(input) (states) (output)

y = f 0 ( t, x c, u ) (output)

x· c = f d ( t, x c, u ) (derivative)

S-functions that contain continuous states implement a state-space equation.

The output portion is placed in mdlOutputs and the derivative portion in
mdlDerivatives. To visualize how the integration works, refer back to the
flowchart in “How Simulink Interacts with C S-Functions” on page 3–32. The
output equation above corresponds to the mdlOutputs in the major time step.

7-34
 S-Function Examples

Next, the example enters the integration section of the flowchart. Here
Simulink performs a number of minor time steps during which it calls
mdlOutputs and mdlDerivatives. Each of these pairs of calls is referred to as
an integration stage. The integration returns with the continuous states
updated and the simulation time moved forward. Time is moved forward as far
as possible, providing that error tolerances in the state are met. The maximum
time step is subject to constraints of discrete events such as the actual
simulation stop time and the user-imposed limit.
Note that csfunc.c specifies that the input port has direct feedthrough. This
is because matrix D is initialized to a nonzero matrix. If D were set equal to a
zero matrix in the state-space representation, the input signal isn’t used in
mdlOutputs. In this case, the direct feedthrough can be set to 0, which indicates
that csfunc.c does not require the input signal when executing mdlOutputs.

matlabroot/simulink/src/csfunc.c
/* File : csfunc.c
* Abstract:
*
* Example C-file S-function for defining a continuous system.
*
* x' = Ax + Bu
* y = Cx + Du
*
* For more details about S-functions, see simulink/src/sfuntmpl_doc.c.
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.7 $
*/

#define S_FUNCTION_NAME csfunc

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

#define U(element) (*uPtrs[element]) /* Pointer to Input Port0 */

static real_T A[2][2]={ { -0.09, -0.01 } ,

{ 1 , 0 }
};

static real_T B[2][2]={ { 1 , -7 } ,

{ 0 , -2 }
};

static real_T C[2][2]={ { 0 , 2 } ,

{ 1 , -5 }
};

7-35
7 Implementing Block Features

static real_T D[2][2]={ { -3 , 0 } ,

{ 1 , 0 }
};

/*====================*
* S-function methods *
*====================*/

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
ssSetNumSFcnParams(S, 0); /* Number of expected parameters */
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
return; /* Parameter mismatch will be reported by Simulink */
}

ssSetNumContStates(S, 2);
ssSetNumDiscStates(S, 0);

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 2);
ssSetInputPortDirectFeedThrough(S, 0, 1);

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, 2);

ssSetNumSampleTimes(S, 1);
ssSetNumRWork(S, 0);
ssSetNumIWork(S, 0);
ssSetNumPWork(S, 0);
ssSetNumModes(S, 0);
ssSetNumNonsampledZCs(S, 0);

/* Take care when specifying exception free code - see sfuntmpl_doc.c */

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
}

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* Specifiy that we have a continuous sample time.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}

7-36
 S-Function Examples

#define MDL_INITIALIZE_CONDITIONS
/* Function: mdlInitializeConditions ========================================
* Abstract:
* Initialize both continuous states to zero.
*/
static void mdlInitializeConditions(SimStruct *S)
{
real_T *x0 = ssGetContStates(S);
int_T lp;

for (lp=0;lp<2;lp++) {
*x0++=0.0;
}
}

/* Function: mdlOutputs =======================================================

* Abstract:
* y = Cx + Du
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
real_T *y = ssGetOutputPortRealSignal(S,0);
real_T *x = ssGetContStates(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

UNUSED_ARG(tid); /* not used in single tasking mode */

/* y=Cx+Du */
y[0]=C[0][0]*x[0]+C[0][1]*x[1]+D[0][0]*U(0)+D[0][1]*U(1);
y[1]=C[1][0]*x[0]+C[1][1]*x[1]+D[1][0]*U(0)+D[1][1]*U(1);
}

#define MDL_DERIVATIVES
/* Function: mdlDerivatives =================================================
* Abstract:
* xdot = Ax + Bu
*/
static void mdlDerivatives(SimStruct *S)
{
real_T *dx = ssGetdX(S);
real_T *x = ssGetContStates(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

/* xdot=Ax+Bu */
dx[0]=A[0][0]*x[0]+A[0][1]*x[1]+B[0][0]*U(0)+B[0][1]*U(1);
dx[1]=A[1][0]*x[0]+A[1][1]*x[1]+B[1][0]*U(0)+B[1][1]*U(1);

7-37
7 Implementing Block Features

/* Function: mdlTerminate =====================================================

* Abstract:
* No termination needed, but we are required to have this routine.
*/
static void mdlTerminate(SimStruct *S)
{
UNUSED_ARG(S); /* unused input argument */
}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

Example - Discrete State S-Function

The matlabroot/simulink/src/dsfunc.c example shows how to model a
discrete system in a C MEX S-function. Discrete systems can be modeled by the
following set of equations.

u xd y
(input) (states) (output)

y = f 0 ( t, x d, u ) (output)

x d + 1 = f u ( t, x d, u ) (update)

dsfunc.c implements a discrete state-space equation. The output portion is

placed in mdlOutputs and the update portion in mdlUpdate. To visualize how
the simulation works, refer to the flowchart in “How Simulink Interacts with
C S-Functions” on page 3-32. The output equation above corresponds to the
mdlOutputs in the major time step. The update equation above corresponds to
the mdlUpdate in the major time step. If your model does not contain
continuous elements, the integration phase is skipped and time is moved
forward to the next discrete sample hit.

7-38
 S-Function Examples

matlabroot/simulink/src/dsfunc.c
/* File : dsfunc.c
* Abstract:
*
* Example C-file S-function for defining a discrete system.
*
* x(n+1) = Ax(n) + Bu(n)
* y(n) = Cx(n) + Du(n)
*
* For more details about S-functions, see simulink/src/sfuntmpl_doc.c.
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.10 $
*/

#define S_FUNCTION_NAME dsfunc

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

#define U(element) (*uPtrs[element]) /* Pointer to Input Port0 */

static real_T A[2][2]={ { -1.3839, -0.5097 } ,

{ 1 , 0 }
};

static real_T B[2][2]={ { -2.5559, 0 } ,

{ 0 , 4.2382 }
};

static real_T C[2][2]={ { 0 , 2.0761 } ,

{ 0 , 7.7891 }
};

static real_T D[2][2]={ { -0.8141, -2.9334 } ,

{ 1.2426, 0 }
};

/*====================*
* S-function methods *
*====================*/

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
ssSetNumSFcnParams(S, 0); /* Number of expected parameters */
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {

7-39
7 Implementing Block Features

return; /* Parameter mismatch will be reported by Simulink */

}

ssSetNumContStates(S, 0);
ssSetNumDiscStates(S, 2);

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 2);
ssSetInputPortDirectFeedThrough(S, 0, 1);

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, 2);

ssSetNumSampleTimes(S, 1);
ssSetNumRWork(S, 0);
ssSetNumIWork(S, 0);
ssSetNumPWork(S, 0);
ssSetNumModes(S, 0);
ssSetNumNonsampledZCs(S, 0);

/* Take care when specifying exception free code - see sfuntmpl_doc.c */

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
}

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* Specifiy that we inherit our sample time from the driving block.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, 1.0);
ssSetOffsetTime(S, 0, 0.0);
}

#define MDL_INITIALIZE_CONDITIONS
/* Function: mdlInitializeConditions ========================================
* Abstract:
* Initialize both discrete states to one.
*/
static void mdlInitializeConditions(SimStruct *S)
{
real_T *x0 = ssGetRealDiscStates(S);
int_T lp;

for (lp=0;lp<2;lp++) {
*x0++=1.0;
}
}

7-40
 S-Function Examples

/* Function: mdlOutputs =======================================================

* Abstract:
* y = Cx + Du
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
real_T *y = ssGetOutputPortRealSignal(S,0);
real_T *x = ssGetRealDiscStates(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

UNUSED_ARG(tid); /* not used in single tasking mode */

/* y=Cx+Du */
y[0]=C[0][0]*x[0]+C[0][1]*x[1]+D[0][0]*U(0)+D[0][1]*U(1);
y[1]=C[1][0]*x[0]+C[1][1]*x[1]+D[1][0]*U(0)+D[1][1]*U(1);
}

#define MDL_UPDATE
/* Function: mdlUpdate ======================================================
* Abstract:
* xdot = Ax + Bu
*/
static void mdlUpdate(SimStruct *S, int_T tid)
{
real_T tempX[2] = {0.0, 0.0};
real_T *x = ssGetRealDiscStates(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

UNUSED_ARG(tid); /* not used in single tasking mode */

/* xdot=Ax+Bu */
tempX[0]=A[0][0]*x[0]+A[0][1]*x[1]+B[0][0]*U(0)+B[0][1]*U(1);
tempX[1]=A[1][0]*x[0]+A[1][1]*x[1]+B[1][0]*U(0)+B[1][1]*U(1);

x[0]=tempX[0];
x[1]=tempX[1];
}

/* Function: mdlTerminate =====================================================

* Abstract:
* No termination needed, but we are required to have this routine.
*/
static void mdlTerminate(SimStruct *S)
{
UNUSED_ARG(S); /* unused input argument */
}

7-41
7 Implementing Block Features

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

Example - Hybrid System S-Functions

The S-function, matlabroot/simulink/src/mixedm.c, is an example of a
hybrid (a combination of continuous and discrete states) system. mixedm.c
combines elements of csfunc.c and dsfunc.c. If you have a hybrid system,
place your continuous equations in mdlDerivative and your discrete equations
in mdlUpdate. In addition, you need to check for sample hits to determine at
what point your S-function is being called.
In Simulink block diagram form, the S-function, mixedm.c looks like

which implements a continuous integrator followed by a discrete unit delay.

Since there are no tasks to complete at termination, mdlTerminate is an empty
function. mdlDerivatives calculates the derivatives of the continuous states of
the state vector x, and mdlUpdate contains the equations used to update the
discrete state vector, x.

matlabroot/simulink/src/mixedm.c
/* File : mixedm.c
* Abstract:
*
* An example S-function illustrating multiple sample times by implementing
* integrator -> ZOH(Ts=1second) -> UnitDelay(Ts=1second)
* with an initial condition of 1.
* (e.g. an integrator followed by unit delay operation).
*
* For more details about S-functions, see simulink/src/sfuntmpl_doc.c
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.11 $
*/

#define S_FUNCTION_NAME mixedm

#define S_FUNCTION_LEVEL 2

7-42
 S-Function Examples

#include "simstruc.h"

#define U(element) (*uPtrs[element]) /* Pointer to Input Port0 */

/*====================*
* S-function methods *
*====================*/

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
ssSetNumSFcnParams(S, 0); /* Number of expected parameters */
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
return; /* Parameter mismatch will be reported by Simulink */
}

ssSetNumContStates(S, 1);
ssSetNumDiscStates(S, 1);
ssSetNumRWork(S, 1); /* for zoh output feeding the delay operator */

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 1);
ssSetInputPortDirectFeedThrough(S, 0, 1);
ssSetInputPortSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetInputPortOffsetTime(S, 0, 0.0);

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, 1);
ssSetOutputPortSampleTime(S, 0, 1.0);
ssSetOutputPortOffsetTime(S, 0, 0.0);

ssSetNumSampleTimes(S, 2);

/* Take care when specifying exception free code - see sfuntmpl_doc.c. */

ssSetOptions(S, (SS_OPTION_EXCEPTION_FREE_CODE |
SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED));

} /* end mdlInitializeSizes */

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* Two tasks: One continuous, one with discrete sample time of 1.0.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);

7-43
7 Implementing Block Features

ssSetSampleTime(S, 1, 1.0);
ssSetOffsetTime(S, 1, 0.0);

} /* end mdlInitializeSampleTimes */

#define MDL_INITIALIZE_CONDITIONS
/* Function: mdlInitializeConditions ==========================================
* Abstract:
* Initialize both continuous states to one.
*/
static void mdlInitializeConditions(SimStruct *S)
{
real_T *xC0 = ssGetContStates(S);
real_T *xD0 = ssGetRealDiscStates(S);

xC0[0] = 1.0;
xD0[0] = 1.0;

} /* end mdlInitializeConditions */

/* Function: mdlOutputs =======================================================

* Abstract:
* y = xD, and update the zoh internal output.
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
/* update the internal "zoh" output */
if (ssIsContinuousTask(S, tid)) {
if (ssIsSpecialSampleHit(S, 1, 0, tid)) {
real_T *zoh = ssGetRWork(S);
real_T *xC = ssGetContStates(S);
*zoh = *xC;
}
}

/* y=xD */
if (ssIsSampleHit(S, 1, tid)) {
real_T *y = ssGetOutputPortRealSignal(S,0);
real_T *xD = ssGetRealDiscStates(S);
y[0]=xD[0];
}

} /* end mdlOutputs */

#define MDL_UPDATE

7-44
 S-Function Examples

/* Function: mdlUpdate ======================================================

* Abstract:
* xD = xC
*/
static void mdlUpdate(SimStruct *S, int_T tid)
{
UNUSED_ARG(tid); /* not used in single tasking mode */

/* xD=xC */
if (ssIsSampleHit(S, 1, tid)) {
real_T *xD = ssGetRealDiscStates(S);
real_T *zoh = ssGetRWork(S);
xD[0]=*zoh;
}

} /* end mdlUpdate */

#define MDL_DERIVATIVES
/* Function: mdlDerivatives =================================================
* Abstract:
* xdot = U
*/
static void mdlDerivatives(SimStruct *S)
{
real_T *dx = ssGetdX(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

/* xdot=U */
dx[0]=U(0);

} /* end mdlDerivatives */

/* Function: mdlTerminate =====================================================

* Abstract:
* No termination needed, but we are required to have this routine.
*/
static void mdlTerminate(SimStruct *S)
{
UNUSED_ARG(S); /* unused input argument */
}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

7-45
7 Implementing Block Features

Example - Variable Step S-Function

The example S-function, vsfunc.c uses a variable step sample time. Variable
step-size functions require a call to mdlGetTimeOfNextVarHit, which is an
S-function routine that calculates the time of the next sample hit. S-functions
that use the variable step sample time can only be used with variable step
solvers. vsfunc is a discrete S-function that delays its first input by an amount
of time determined by the second input.
This example demonstrates how to correctly work with the fixed and variable
step solvers when the equations (functions) that are being integrated change
during the simulation. In the transfer function used in this example, the
parameters of the transfer function vary with time.
The output of vsfunc is simply the input u delayed by a variable amount of
time. mdlOutputs sets the output y equal to state x. mdlUpdate sets the state
vector x equal to u, the input vector. This example calls
mdlGetTimeOfNextVarHit, an S-function routine that calculates and sets the
“time of next hit,” that is, the time when is vsfunc is next called. In
mdlGetTimeOfNextVarHit the macro ssGetU is used to get a pointer to the input
u. Then this call is made.
ssSetTNext(S, ssGetT(S)(*u[1]));

The macro ssGetT gets the simulation time t. The second input to the block,
(*u[1]), is added to t, and the macro ssSetTNext sets the time of next hit equal
to t+(*u[1]), delaying the output by the amount of time set in (*u[1]).

matlabroot/simulink/src/vsfunc.c
/* File : vsfunc.c
* Abstract:
*
* Example C-file S-function for defining a continuous system.
*
* Variable step S-function example.
* This example S-function illustrates how to create a variable step
* block in Simulink. This block implements a variable step delay
* in which the first input is delayed by an amount of time determined
* by the second input:
*
* dt = u(2)
* y(t+dt) = u(t)
*
* For more details about S-functions, see simulink/src/sfuntmpl_doc.c.
*
* Copyright 1990-2000 The MathWorks, Inc.

7-46
 S-Function Examples

* $Revision: 1.10 $
*/

#define S_FUNCTION_NAME vsfunc

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

#define U(element) (*uPtrs[element]) /* Pointer to Input Port0 */

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
ssSetNumSFcnParams(S, 0); /* Number of expected parameters */
if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
return; /* Parameter mismatch will be reported by Simulink */
}

ssSetNumContStates(S, 0);
ssSetNumDiscStates(S, 1);

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 2);
ssSetInputPortDirectFeedThrough(S, 0, 1);

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, 1);

ssSetNumSampleTimes(S, 1);
ssSetNumRWork(S, 0);
ssSetNumIWork(S, 0);
ssSetNumPWork(S, 0);
ssSetNumModes(S, 0);
ssSetNumNonsampledZCs(S, 0);

if (ssGetSimMode(S) == SS_SIMMODE_RTWGEN && !ssIsVariableStepSolver(S)) {

ssSetErrorStatus(S, "S-function vsfunc.c cannot be used with RTW "
"and Fixed-Step Solvers because it contains variable"
" sample time");
}

/* Take care when specifying exception free code - see sfuntmpl_doc.c */

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
}

7-47
7 Implementing Block Features

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* Variable-Step S-function
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, VARIABLE_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}

#define MDL_INITIALIZE_CONDITIONS
/* Function: mdlInitializeConditions ========================================
* Abstract:
* Initialize discrete state to zero.
*/
static void mdlInitializeConditions(SimStruct *S)
{
real_T *x0 = ssGetRealDiscStates(S);

x0[0] = 0.0;
}

#define MDL_GET_TIME_OF_NEXT_VAR_HIT
static void mdlGetTimeOfNextVarHit(SimStruct *S)
{
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

/* Make sure input will increase time */

if (U(1) <= 0.0) {
/* If not, abort simulation */
ssSetErrorStatus(S,"Variable step control input must be "
"greater than zero");
return;
}
ssSetTNext(S, ssGetT(S)+U(1));
}

/* Function: mdlOutputs =======================================================

* Abstract:
* y = x
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
real_T *y = ssGetOutputPortRealSignal(S,0);
real_T *x = ssGetRealDiscStates(S);

/* Return the current state as the output */

7-48
 S-Function Examples

y[0] = x[0];
}

#define MDL_UPDATE
/* Function: mdlUpdate ========================================================
* Abstract:
* This function is called once for every major integration time step.
* Discrete states are typically updated here, but this function is useful
* for performing any tasks that should only take place once per integration
* step.
*/
static void mdlUpdate(SimStruct *S, int_T tid)
{
real_T *x = ssGetRealDiscStates(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

x[0]=U(0);
}

/* Function: mdlTerminate =====================================================

* Abstract:
* No termination needed, but we are required to have this routine.
*/
static void mdlTerminate(SimStruct *S)
{
}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

Example - Zero Crossing S-Function

The example S-function, sfun_zc_sat demonstrates how to implement a
saturation block. This S-function is designed to work with either fixed or
variable step solvers. When this S-function inherits a continuous sample time,
and a variable step solver is being used, a zero crossings algorithm is used to
locate the exact points at which the saturation occurs.

7-49
7 Implementing Block Features

matlabroot/simulink/src/sfun_zc_sat.c
/* File : sfun_zc_sat.c
* Abstract:
*
* Example of an S-function which has nonsampled zero crossings to
* implement a saturation function. This S-function is designed to be
* used with a variable or fixed step solver.
*
* A saturation is described by three equations
*
* (1) y = UpperLimit
* (2) y = u
* (3) y = LowerLimit
*
* and a set of inequalities that specify which equation to use
*
* if UpperLimit < u then use (1)
* if LowerLimit <= u <= UpperLimit then use (2)
* if u < LowerLimit then use (3)
*
* A key fact is that the valid equation 1, 2, or 3, can change at
* any instant. Nonsampled zero crossing support helps the variable step
* solvers locate the exact instants when behavior switches from one equation
* to another.
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.10 $
*/

#define S_FUNCTION_NAME sfun_zc_sat

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

/*========================*
* General Defines/macros *
*========================*/

/* index to Upper Limit */

#define I_PAR_UPPER_LIMIT 0

/* index to Lower Limit */

#define I_PAR_LOWER_LIMIT 1

/* total number of block parameters */

#define N_PAR 2

/*
* Make access to mxArray pointers for parameters more readable.
*/
#define P_PAR_UPPER_LIMIT ( ssGetSFcnParam(S,I_PAR_UPPER_LIMIT) )

7-50
 S-Function Examples

#define P_PAR_LOWER_LIMIT ( ssGetSFcnParam(S,I_PAR_LOWER_LIMIT) )

#define MDL_CHECK_PARAMETERS
#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)

/* Function: mdlCheckParameters =============================================

* Abstract:
* Check that parameter choices are allowable.
*/
static void mdlCheckParameters(SimStruct *S)
{
int_T i;
int_T numUpperLimit;
int_T numLowerLimit;
const char *msg = NULL;

/*
* check parameter basics
*/
for ( i = 0; i < N_PAR; i++ ) {
if ( mxIsEmpty( ssGetSFcnParam(S,i) ) ||
mxIsSparse( ssGetSFcnParam(S,i) ) ||
mxIsComplex( ssGetSFcnParam(S,i) ) ||
!mxIsNumeric( ssGetSFcnParam(S,i) ) ) {
msg = "Parameters must be real vectors.";
goto EXIT_POINT;
}
}

/*
* Check sizes of parameters.
*/
numUpperLimit = mxGetNumberOfElements( P_PAR_UPPER_LIMIT );
numLowerLimit = mxGetNumberOfElements( P_PAR_LOWER_LIMIT );

if ( ( numUpperLimit != 1 ) &&
( numLowerLimit != 1 ) &&
( numUpperLimit != numLowerLimit ) ) {
msg = "Number of input and output values must be equal.";
goto EXIT_POINT;
}

/*
* Error exit point
*/
EXIT_POINT:
if (msg != NULL) {
ssSetErrorStatus(S, msg);
}
}
#endif /* MDL_CHECK_PARAMETERS */

7-51
7 Implementing Block Features

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* Initialize the sizes array.
*/
static void mdlInitializeSizes(SimStruct *S)
{
int_T numUpperLimit, numLowerLimit, maxNumLimit;

/*
* Set and Check parameter count
*/
ssSetNumSFcnParams(S, N_PAR);

#if defined(MATLAB_MEX_FILE)
if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
mdlCheckParameters(S);
if (ssGetErrorStatus(S) != NULL) {
return;
}
} else {
return; /* Parameter mismatch will be reported by Simulink */
}
#endif

/*
* Get parameter size info.
*/
numUpperLimit = mxGetNumberOfElements( P_PAR_UPPER_LIMIT );
numLowerLimit = mxGetNumberOfElements( P_PAR_LOWER_LIMIT );

if (numUpperLimit > numLowerLimit) {

maxNumLimit = numUpperLimit;
} else {
maxNumLimit = numLowerLimit;
}

/*
* states
*/
ssSetNumContStates(S, 0);
ssSetNumDiscStates(S, 0);

/*
* outputs
* The upper and lower limits are scalar expanded
* so their size determines the size of the output
* only if at least one of them is not scalar.
*/
if (!ssSetNumOutputPorts(S, 1)) return;

7-52
 S-Function Examples

if ( maxNumLimit > 1 ) {
ssSetOutputPortWidth(S, 0, maxNumLimit);
} else {
ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED);
}

/*
* inputs
* If the upper or lower limits are not scalar then
* the input is set to the same size. However, the
* ssSetOptions below allows the actual width to
* be reduced to 1 if needed for scalar expansion.
*/
if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortDirectFeedThrough(S, 0, 1 );

if ( maxNumLimit > 1 ) {
ssSetInputPortWidth(S, 0, maxNumLimit);
} else {
ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED);
}

/*
* sample times
*/
ssSetNumSampleTimes(S, 1);

/*
* work
*/
ssSetNumRWork(S, 0);
ssSetNumIWork(S, 0);
ssSetNumPWork(S, 0);

/*
* Modes and zero crossings:
* If we have a variable step solver and this block has a continuous
* sample time, then
* o One mode element will be needed for each scalar output
* in order to specify which equation is valid (1), (2), or (3).
* o Two ZC elements will be needed for each scalar output
* in order to help the solver find the exact instants
* at which either of the two possible "equation switches"
* One will be for the switch from eq. (1) to (2);
* the other will be for eq. (2) to (3) and vise versa.
* otherwise
* o No modes and nonsampled zero crossings will be used.
*
*/
ssSetNumModes(S, DYNAMICALLY_SIZED);
ssSetNumNonsampledZCs(S, DYNAMICALLY_SIZED);

7-53
7 Implementing Block Features

/*
* options
* o No mexFunctions and no problematic mxFunctions are called
* so the exception free code option safely gives faster simulations.
* o Scalar expansion of the inputs is desired. The option provides
* this without the need to write mdlSetOutputPortWidth and
* mdlSetInputPortWidth functions.
*/
ssSetOptions(S, ( SS_OPTION_EXCEPTION_FREE_CODE |
SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION));

} /* end mdlInitializeSizes */

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* Specify that the block is continuous.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0);
}

#define MDL_SET_WORK_WIDTHS
#if defined(MDL_SET_WORK_WIDTHS) && defined(MATLAB_MEX_FILE)
/* Function: mdlSetWorkWidths ===============================================
* The width of the Modes and the ZCs depends on the width of the output.
* This width is not always known in mdlInitializeSizes so it is handled
* here.
*/
static void mdlSetWorkWidths(SimStruct *S)
{
int nModes;
int nNonsampledZCs;

if (ssIsVariableStepSolver(S) &&
ssGetSampleTime(S,0) == CONTINUOUS_SAMPLE_TIME &&
ssGetOffsetTime(S,0) == 0.0) {

int numOutput = ssGetOutputPortWidth(S, 0);

/*
* modes and zero crossings
* o One mode element will be needed for each scalar output
* in order to specify which equation is valid (1), (2), or (3).
* o Two ZC elements will be needed for each scalar output
* in order to help the solver find the exact instants
* at which either of the two possible "equation switches"

7-54
 S-Function Examples

* One will be for the switch from eq. (1) to (2);

* the other will be for eq. (2) to (3) and vise-versa.
*/
nModes = numOutput;
nNonsampledZCs = 2 * numOutput;
} else {
nModes = 0;
nNonsampledZCs = 0;
}
ssSetNumModes(S,nModes);
ssSetNumNonsampledZCs(S,nNonsampledZCs);
}
#endif /* MDL_SET_WORK_WIDTHS */

/* Function: mdlOutputs =======================================================

* Abstract:
*
* A saturation is described by three equations
*
* (1) y = UpperLimit
* (2) y = u
* (3) y = LowerLimit
*
* When this block is used with a fixed-step solver or it has a noncontinuous
* sample time, the equations are used as it
*
* Now consider the case of this block being used with a variable step solver
* and it has a continusous sample time. Solvers work best on smooth problems.
* In order for the solver to work without chattering, limit cycles, or
* similar problems. It is absolutely crucial that the same equation be used
* throughout the duration of a MajorTimeStep. To visualize this, consider
* the case of the Saturation block feeding an Integrator block.
*
* To implement this rule, the mode vector is used to specify the
* valid equation based on the following:
*
* if UpperLimit < u then use (1)
* if LowerLimit <= u <= UpperLimit then use (2)
* if u < LowerLimit then use (3)
*
* The mode vector is changed only at the beginning of a MajorTimeStep.
*
* During a minor time step, the equation specified by the mode vector
* is used without question. Most of the time, the value of u will agree
* with the equation specified by the mode vector. However, sometimes u's
* value will indicate a different equation. Nonetheless, the equation
* specified by the mode vector must be used.
*
* When the mode and u indicate different equations, the corresponding
* calculations are not correct. However, this is not a problem. From
* the ZC function, the solver will know that an equation switch occured

7-55
7 Implementing Block Features

* in the middle of the last MajorTimeStep. The calculations for that

* time step will be discarded. The ZC function will help the solver
* find the exact instant at which the switch occured. Using this knowledge,
* the length of the MajorTimeStep will be reduced so that only one equation
* is valid throughout the entire time step.
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
real_T *y = ssGetOutputPortRealSignal(S,0);
int_T numOutput = ssGetOutputPortWidth(S,0);
int_T iOutput;

/*
* Set index and increment for input signal, upper limit, and lower limit
* parameters so that each gives scalar expansion if needed.
*/
int_T uIdx = 0;
int_T uInc = ( ssGetInputPortWidth(S,0) > 1 );
const real_T *upperLimit = mxGetPr( P_PAR_UPPER_LIMIT );
int_T upperLimitInc = ( mxGetNumberOfElements( P_PAR_UPPER_LIMIT ) > 1 );
const real_T *lowerLimit = mxGetPr( P_PAR_LOWER_LIMIT );
int_T lowerLimitInc = ( mxGetNumberOfElements( P_PAR_LOWER_LIMIT ) > 1 );

UNUSED_ARG(tid); /* not used in single tasking mode */

if (ssGetNumNonsampledZCs(S) == 0) {
/*
* This block is being used with a fixed-step solver or it has
* a noncontinuous sample time, so we always saturate.
*/
for (iOutput = 0; iOutput < numOutput; iOutput++) {
if (*uPtrs[uIdx] >= *upperLimit) {
*y++ = *upperLimit;
} else if (*uPtrs[uIdx] > *lowerLimit) {
*y++ = *uPtrs[uIdx];
} else {
*y++ = *lowerLimit;
}

upperLimit += upperLimitInc;
lowerLimit += lowerLimitInc;
uIdx += uInc;
}

} else {
/*
* This block is being used with a variable-step solver.
*/
int_T *mode = ssGetModeVector(S);

/*
* Specify indices for each equation.

7-56
 S-Function Examples

*/
enum { UpperLimitEquation, NonLimitEquation, LowerLimitEquation };

/*
* Update the Mode Vector ONLY at the beginning of a MajorTimeStep
*/
if ( ssIsMajorTimeStep(S) ) {
/*
* Specify the mode, ie the valid equation for each output scalar.
*/
for ( iOutput = 0; iOutput < numOutput; iOutput++ ) {
if ( *uPtrs[uIdx] > *upperLimit ) {
/*
* Upper limit eq is valid.
*/
mode[iOutput] = UpperLimitEquation;
} else if ( *uPtrs[uIdx] < *lowerLimit ) {
/*
* Lower limit eq is valid.
*/
mode[iOutput] = LowerLimitEquation;
} else {
/*
* Nonlimit eq is valid.
*/
mode[iOutput] = NonLimitEquation;
}
/*
* Adjust indices to give scalar expansion if needed.
*/
uIdx += uInc;
upperLimit += upperLimitInc;
lowerLimit += lowerLimitInc;
}

/*
* Reset index to input and limits.
*/
uIdx = 0;
upperLimit = mxGetPr( P_PAR_UPPER_LIMIT );
lowerLimit = mxGetPr( P_PAR_LOWER_LIMIT );

} /* end IsMajorTimeStep */

/*
* For both MinorTimeSteps and MajorTimeSteps calculate each scalar
* output using the equation specified by the mode vector.
*/
for ( iOutput = 0; iOutput < numOutput; iOutput++ ) {
if ( mode[iOutput] == UpperLimitEquation ) {
/*
* Upper limit eq.
*/

7-57
7 Implementing Block Features

*y++ = *upperLimit;
} else if ( mode[iOutput] == LowerLimitEquation ) {
/*
* Lower limit eq.
*/
*y++ = *lowerLimit;
} else {
/*
* Nonlimit eq.
*/
*y++ = *uPtrs[uIdx];
}

/*
* Adjust indices to give scalar expansion if needed.
*/
uIdx += uInc;
upperLimit += upperLimitInc;
lowerLimit += lowerLimitInc;
}
}
} /* end mdlOutputs */

#define MDL_ZERO_CROSSINGS
#if defined(MDL_ZERO_CROSSINGS) && (defined(MATLAB_MEX_FILE) || defined(NRT))

/* Function: mdlZeroCrossings =================================================

* Abstract:
* This will only be called if the number of nonsampled zero crossings is
* greater than 0 which means this block has a continuous sample time and the
* the model is using a variable step solver.
*
* Calculate zero crossing (ZC) signals that help the solver find the
* exact instants at which equation switches occur:
*
* if UpperLimit < u then use (1)
* if LowerLimit <= u <= UpperLimit then use (2)
* if u < LowerLimit then use (3)
*
* The key words are help find. There is no choice of a function that will
* direct the solver to the exact instant of the change. The solver will
* track the zero crossing signal and do a bisection style search for the
* exact instant of equation switch.
*
* There is generally one ZC signal for each pair of signals that can
* switch. The three equations above would broken into two pairs (1)&(2)
* and (2)&(3). The possibility of a "long jump" from (1) to (3) does
* not need to be handled as a separate case. It is implicitly handled.
*
* When a ZCs are calculated, the value is normally used twice. When it is
* first calculated, it is used as the end of the current time step. Later,

7-58
 S-Function Examples

* it will be used as the beginning of the following step.

*
* The sign of the ZC signal always indicates an equation from the pair. For
* S-functions, which equation is associated with a positive ZC and which is
* associated with a negative ZC doesn't really matter. If the ZC is positive
* at the beginning and at the end of the time step, this implies that the
* "positive" equation was valid throughout the time step. Likewise, if the
* ZC is negative at the beginning and at the end of the time step, this
* implies that the "negative" equation was valid throughout the time step.
* Like any other nonlinear solver, this is not fool proof, but it is an
* excellent indicator. If the ZC has a different sign at the beginning and
* at the end of the time step, then a equation switch definitely occured
* during the time step.
*
* Ideally, the ZC signal gives an estimate of when an equation switch
* occurred. For example, if the ZC signal is -2 at the beginning and +6 at
* the end, then this suggests that the switch occured
* 25% = 100%*(-2)/(-2-(+6)) of the way into the time step. It will almost
* never be true that 25% is perfectly correct. There is no perfect choice
* for a ZC signal, but there are some good rules. First, choose the ZC
* signal to be continuous. Second, choose the ZC signal to give a monotonic
* measure of the "distance" to a signal switch; strictly monotonic is ideal.
*/
static void mdlZeroCrossings(SimStruct *S)
{
int_T iOutput;
int_T numOutput = ssGetOutputPortWidth(S,0);
real_T *zcSignals = ssGetNonsampledZCs(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

/*
* Set index and increment for the input signal, upper limit, and lower
* limit parameters so that each gives scalar expansion if needed.
*/
int_T uIdx = 0;
int_T uInc = ( ssGetInputPortWidth(S,0) > 1 );
real_T *upperLimit = mxGetPr( P_PAR_UPPER_LIMIT );
int_T upperLimitInc = ( mxGetNumberOfElements( P_PAR_UPPER_LIMIT ) > 1 );
real_T *lowerLimit = mxGetPr( P_PAR_LOWER_LIMIT );
int_T lowerLimitInc = ( mxGetNumberOfElements( P_PAR_LOWER_LIMIT ) > 1 );

/*
* For each output scalar, give the solver a measure of "how close things
* are" to an equation switch.
*/
for ( iOutput = 0; iOutput < numOutput; iOutput++ ) {

/* The switch from eq (1) to eq (2)

*
* if UpperLimit < u then use (1)
* if LowerLimit <= u <= UpperLimit then use (2)
*
* is related to how close u is to UpperLimit. A ZC choice

7-59
7 Implementing Block Features

* that is continuous, strictly monotonic, and is

* u - UpperLimit
* or it is negative.
*/
zcSignals[2*iOutput] = *uPtrs[uIdx] - *upperLimit;

/* The switch from eq (2) to eq (3)

*
* if LowerLimit <= u <= UpperLimit then use (2)
* if u < LowerLimit then use (3)
*
* is related to how close u is to LowerLimit. A ZC choice
* that is continuous, strictly monotonic, and is
* u - LowerLimit.
*/
zcSignals[2*iOutput+1] = *uPtrs[uIdx] - *lowerLimit;

/*
* Adjust indices to give scalar expansion if needed.
*/
uIdx += uInc;
upperLimit += upperLimitInc;
lowerLimit += lowerLimitInc;
}
}

#endif /* end mdlZeroCrossings */

/* Function: mdlTerminate =====================================================

* Abstract:
* No termination needed, but we are required to have this routine.
*/
static void mdlTerminate(SimStruct *S)
{
UNUSED_ARG(S); /* unused input argument */
}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

7-60
 S-Function Examples

Example - Time Varying Continuous Transfer

Function
The stvctf S-function is an example of a time varying continuous transfer
function. It demonstrates how to work with the solvers so that the simulation
maintains consistency, which means that block maintains smooth and
consistent signals for the integrators despite the fact that the equations that
are being integrated are changing.

matlabroot/simulink/src/stvctf.c
/*
* File : stvctf.c
* Abstract:
* Time Varying Continuous Transfer Function block
*
* This S-function implements a continous time transfer function
* whose transfer function polynomials are passed in via the input
* vector. This is useful for continuous time adapative control
* applications.
*
* This S-function is also an example of how to "use banks" to avoid
* problems with computing derivatives when a continuous output has
* discontinuities. The consistency checker can be used to verify that
* your S-function is correct with respect to always maintaining smooth
* and consistent signals for the integrators. By consistent we mean that
* two mdlOutput calls at major time t and minor time t are always the
* same. The consistency checker is enabled on the diagnostics page of the
* simulation parameters dialog box. The update method of this S-function
* modifies the coefficients of the transfer function, which cause the
* output to "jump." To have the simulation work properly, we need to let
* the solver know of these discontinuities by setting
* ssSetSolverNeedsReset and then we need to use multiple banks of
* coefficients so the coefficients used in the major time step output
* and the minor time step outputs are the same. In the simulation loop
* we have:
* Loop:
* o Output in major time step at time t
* o Update in major time step at time t
* o Integrate (minor time step):
* o Consistency check: recompute outputs at time t and compare
* with current outputs.
* o Derivatives at time t
* o One or more Output,Derivative evaluations at time t+k
* where k <= step_size to be taken.
* o Compute state, x
* o t = t + step_size
* End_Integrate
* End_Loop
* Another purpose of the consistency checker is used to verify that when

7-61
7 Implementing Block Features

* the solver needs to try a smaller step_size that the recomputing of

* the output and derivatives at time t doesn't change. Step size
* reduction occurs when tolerances aren't met for the current step size.
* The ideal ordering would be to update after integrate. To achieve
* this we have two banks of coefficients. And the use of the new
* coefficients, which were computed in update, are delayed until after
* the integrate phase is complete.
*
* This block has multiple sample times and will not work correctly
* in a multitasking environment. It is designed to be used in
* a single tasking (or variable step) simulation environment.
* Because this block accesses the input signal in both tasks,
* it cannot specify the sample times of the input and output ports
* (SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED).
*
* See simulink/src/sfuntmpl_doc.c.
*
* Copyright 1990-2000 The MathWorks, Inc.
* $Revision: 1.14 $
*/

#define S_FUNCTION_NAME stvctf

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

/*
* Defines for easy access to the numerator and denominator polynomials
* parameters
*/
#define NUM(S) ssGetSFcnParam(S, 0)
#define DEN(S) ssGetSFcnParam(S, 1)
#define TS(S) ssGetSFcnParam(S, 2)
#define NPARAMS 3

#define MDL_CHECK_PARAMETERS
#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)
/* Function: mdlCheckParameters =============================================
* Abstract:
* Validate our parameters to verify:
* o The numerator must be of a lower order than the denominator.
* o The sample time must be a real positive nonzero value.
*/
static void mdlCheckParameters(SimStruct *S)
{
int_T i;

for (i = 0; i < NPARAMS; i++) {

real_T *pr;
int_T el;
int_T nEls;
if (mxIsEmpty( ssGetSFcnParam(S,i)) ||

7-62
 S-Function Examples

mxIsSparse( ssGetSFcnParam(S,i)) ||
mxIsComplex( ssGetSFcnParam(S,i)) ||
!mxIsNumeric( ssGetSFcnParam(S,i)) ) {
ssSetErrorStatus(S,"Parameters must be real finite vectors");
return;
}
pr = mxGetPr(ssGetSFcnParam(S,i));
nEls = mxGetNumberOfElements(ssGetSFcnParam(S,i));
for (el = 0; el < nEls; el++) {
if (!mxIsFinite(pr[el])) {
ssSetErrorStatus(S,"Parameters must be real finite vectors");
return;
}
}
}

if (mxGetNumberOfElements(NUM(S)) > mxGetNumberOfElements(DEN(S)) &&

mxGetNumberOfElements(DEN(S)) > 0 && *mxGetPr(DEN(S)) != 0.0) {
ssSetErrorStatus(S,"The denominator must be of higher order than "
"the numerator, nonempty and with first "
"element nonzero");
return;
}

/* xxx verify finite */

if (mxGetNumberOfElements(TS(S)) != 1 || mxGetPr(TS(S))[0] <= 0.0) {
ssSetErrorStatus(S,"Invalid sample time specified");
return;
}
}
#endif /* MDL_CHECK_PARAMETERS */

/* Function: mdlInitializeSizes ===============================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block's characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)
{
int_T nContStates;
int_T nCoeffs;

/* See sfuntmpl_doc.c for more details on the macros below. */

ssSetNumSFcnParams(S, NPARAMS); /* Number of expected parameters. */

#if defined(MATLAB_MEX_FILE)
if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
mdlCheckParameters(S);
if (ssGetErrorStatus(S) != NULL) {
return;
}
} else {

7-63
7 Implementing Block Features

return; /* Parameter mismatch will be reported by Simulink. */

}
#endif

/*
* Define the characteristics of the block:
*
* Number of continuous states: length of denominator - 1
* Inputs port width 2 * (NumContStates+1) + 1
* Output port width 1
* DirectFeedThrough: 0 (Although this should be computed.
* We'll assume coefficients entered
* are strictly proper).
* Number of sample times: 2 (continuous and discrete)
* Number of Real work elements: 4*NumCoeffs
* (Two banks for num and den coeff's:
* NumBank0Coeffs
* DenBank0Coeffs
* NumBank1Coeffs
* DenBank1Coeffs)
* Number of Integer work elements: 2 (indicator of active bank 0 or 1
* and flag to indicate when banks
* have been updated).
*
* The number of inputs arises from the following:
* o 1 input (u)
* o the numerator and denominator polynomials each have NumContStates+1
* coefficients
*/
nCoeffs = mxGetNumberOfElements(DEN(S));
nContStates = nCoeffs - 1;

ssSetNumContStates(S, nContStates);
ssSetNumDiscStates(S, 0);

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 1 + (2*nCoeffs));
ssSetInputPortDirectFeedThrough(S, 0, 0);
ssSetInputPortSampleTime(S, 0, mxGetPr(TS(S))[0]);
ssSetInputPortOffsetTime(S, 0, 0);

if (!ssSetNumOutputPorts(S,1)) return;
ssSetOutputPortWidth(S, 0, 1);
ssSetOutputPortSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOutputPortOffsetTime(S, 0, 0);

ssSetNumSampleTimes(S, 2);

ssSetNumRWork(S, 4 * nCoeffs);
ssSetNumIWork(S, 2);
ssSetNumPWork(S, 0);

7-64
 S-Function Examples

ssSetNumModes(S, 0);
ssSetNumNonsampledZCs(S, 0);

/* Take care when specifying exception free code - see sfuntmpl_doc.c */

ssSetOptions(S, (SS_OPTION_EXCEPTION_FREE_CODE));

} /* end mdlInitializeSizes */

/* Function: mdlInitializeSampleTimes =========================================

* Abstract:
* This function is used to specify the sample time(s) for the
* S-function. This S-function has two sample times. The
* first, a continous sample time, is used for the input to the
* transfer function, u. The second, a discrete sample time
* provided by the user, defines the rate at which the transfer
* function coefficients are updated.
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
/*
* the first sample time, continuous
*/
ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);

/*
* the second, discrete sample time, is user provided
*/
ssSetSampleTime(S, 1, mxGetPr(TS(S))[0]);
ssSetOffsetTime(S, 1, 0.0);

} /* end mdlInitializeSampleTimes */

#define MDL_INITIALIZE_CONDITIONS
/* Function: mdlInitializeConditions ==========================================
* Abstract:
* Initalize the states, numerator and denominator coefficients.
*/
static void mdlInitializeConditions(SimStruct *S)
{
int_T i;
int_T nContStates = ssGetNumContStates(S);
real_T *x0 = ssGetContStates(S);
int_T nCoeffs = nContStates + 1;
real_T *numBank0 = ssGetRWork(S);
real_T *denBank0 = numBank0 + nCoeffs;
int_T *activeBank = ssGetIWork(S);

/*

7-65
7 Implementing Block Features

* The continuous states are all initialized to zero.

*/
for (i = 0; i < nContStates; i++) {
x0[i] = 0.0;
numBank0[i] = 0.0;
denBank0[i] = 0.0;
}
numBank0[nContStates] = 0.0;
denBank0[nContStates] = 0.0;

/*
* Set up the initial numerator and denominator.
*/
{
const real_T *numParam = mxGetPr(NUM(S));
int numParamLen = mxGetNumberOfElements(NUM(S));

const real_T *denParam = mxGetPr(DEN(S));

int denParamLen = mxGetNumberOfElements(DEN(S));
real_T den0 = denParam[0];

for (i = 0; i < denParamLen; i++) {

denBank0[i] = denParam[i] / den0;
}

for (i = 0; i < numParamLen; i++) {

numBank0[i] = numParam[i] / den0;
}
}

/*
* Normalize if this transfer function has direct feedthrough.
*/
for (i = 1; i < nCoeffs; i++) {
numBank0[i] -= denBank0[i]*numBank0[0];
}

/*
* Indicate bank0 is active (i.e. bank1 is oldest).
*/
*activeBank = 0;

} /* end mdlInitializeConditions */

/* Function: mdlOutputs =======================================================

* Abstract:
* The outputs for this block are computed by using a controllable state-
* space representation of the transfer function.
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{

7-66
 S-Function Examples

if (ssIsContinuousTask(S,tid)) {
int i;
real_T *num;
int nContStates = ssGetNumContStates(S);
real_T *x = ssGetContStates(S);
int_T nCoeffs = nContStates + 1;
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
real_T *y = ssGetOutputPortRealSignal(S,0);
int_T *activeBank = ssGetIWork(S);

/*
* Switch banks we've updated them in mdlUpdate and we're no longer
* in a minor time step.
*/
if (ssIsMajorTimeStep(S)) {
int_T *banksUpdated = ssGetIWork(S) + 1;
if (*banksUpdated) {
*activeBank = !(*activeBank);
*banksUpdated = 0;
/*
* Need to tell the solvers that the derivatives are no
* longer valid.
*/
ssSetSolverNeedsReset(S);
}
}
num = ssGetRWork(S) + (*activeBank) * (2*nCoeffs);

/*
* The continuous system is evaluated using a controllable state space
* representation of the transfer function. This implies that the
* output of the system is equal to:
*
* y(t) = Cx(t) + Du(t)
* = [ b1 b2 ... bn]x(t) + b0u(t)
*
* where b0, b1, b2, ... are the coefficients of the numerator
* polynomial:
*
* B(s) = b0 s^n + b1 s^n-1 + b2 s^n-2 + ... + bn-1 s + bn
*/
*y = *num++ * (*uPtrs[0]);
for (i = 0; i < nContStates; i++) {
*y += *num++ * *x++;
}
}

} /* end mdlOutputs */

#define MDL_UPDATE
/* Function: mdlUpdate ========================================================
* Abstract:

7-67
7 Implementing Block Features

* Every time through the simulation loop, update the

* transfer function coefficients. Here we update the oldest bank.
*/
static void mdlUpdate(SimStruct *S, int_T tid)
{
UNUSED_ARG(tid); /* not used in single tasking mode */

if (ssIsSampleHit(S, 1, tid)) {
int_T i;
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
int_T uIdx = 1;/*1st coeff is after signal input*/
int_T nContStates = ssGetNumContStates(S);
int_T nCoeffs = nContStates + 1;
int_T bankToUpdate = !ssGetIWork(S)[0];
real_T *num = ssGetRWork(S)+bankToUpdate*2*nCoeffs;
real_T *den = num + nCoeffs;

real_T den0;
int_T allZero;

/*
* Get the first denominator coefficient. It will be used
* for normalizing the numerator and denominator coefficients.
*
* If all inputs are zero, we probably could have unconnected
* inputs, so use the parameter as the first denominator coefficient.
*/
den0 = *uPtrs[uIdx+nCoeffs];
if (den0 == 0.0) {
den0 = mxGetPr(DEN(S))[0];
}

/*
* Grab the numerator.
*/
allZero = 1;
for (i = 0; (i < nCoeffs) && allZero; i++) {
allZero &= *uPtrs[uIdx+i] == 0.0;
}

if (allZero) { /* if numerator is all zero */

const real_T *numParam = mxGetPr(NUM(S));
int_T numParamLen = mxGetNumberOfElements(NUM(S));
/*
* Move the input to the denominator input and
* get the denominator from the input parameter.
*/
uIdx += nCoeffs;
num += nCoeffs - numParamLen;
for (i = 0; i < numParamLen; i++) {
*num++ = *numParam++ / den0;
}

7-68
 S-Function Examples

} else {
for (i = 0; i < nCoeffs; i++) {
*num++ = *uPtrs[uIdx++] / den0;
}
}

/*
* Grab the denominator.
*/
allZero = 1;
for (i = 0; (i < nCoeffs) && allZero; i++) {
allZero &= *uPtrs[uIdx+i] == 0.0;
}

if (allZero) { /* If denominator is all zero. */

const real_T *denParam = mxGetPr(DEN(S));
int_T denParamLen = mxGetNumberOfElements(DEN(S));

den0 = denParam[0];
for (i = 0; i < denParamLen; i++) {
*den++ = *denParam++ / den0;
}
} else {
for (i = 0; i < nCoeffs; i++) {
*den++ = *uPtrs[uIdx++] / den0;
}
}

/*
* Normalize if this transfer function has direct feedthrough.
*/
num = ssGetRWork(S) + bankToUpdate*2*nCoeffs;
den = num + nCoeffs;
for (i = 1; i < nCoeffs; i++) {
num[i] -= den[i]*num[0];
}

/*
* Indicate oldest bank has been updated.
*/
ssGetIWork(S)[1] = 1;
}

} /* end mdlUpdate */

#define MDL_DERIVATIVES
/* Function: mdlDerivatives ===================================================
* Abstract:
* The drivatives for this block are computed by using a controllable
* state-space representation of the transfer function.
*/

7-69
7 Implementing Block Features

static void mdlDerivatives(SimStruct *S)

{
int_T i;
int_T nContStates = ssGetNumContStates(S);
real_T *x = ssGetContStates(S);
real_T *dx = ssGetdX(S);
int_T nCoeffs = nContStates + 1;
int_T activeBank = ssGetIWork(S)[0];
const real_T *num = ssGetRWork(S) + activeBank*(2*nCoeffs);
const real_T *den = num + nCoeffs;
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

/*
* The continuous system is evaluated using a controllable state-space
* representation of the transfer function. This implies that the
* next continuous states are computed using:
*
* dx = Ax(t) + Bu(t)
* = [-a1 -a2 ... -an] [x1(t)] + [u(t)]
* [ 1 0 ... 0] [x2(t)] + [0]
* [ 0 1 ... 0] [x3(t)] + [0]
* [ . . ... .] . + .
* [ . . ... .] . + .
* [ . . ... .] . + .
* [ 0 0 ... 1 0] [xn(t)] + [0]
*
* where a1, a2, ... are the coefficients of the numerator polynomial:
*
* A(s) = s^n + a1 s^n-1 + a2 s^n-2 + ... + an-1 s + an
*/
dx[0] = -den[1] * x[0] + *uPtrs[0];
for (i = 1; i < nContStates; i++) {
dx[i] = x[i-1];
dx[0] -= den[i+1] * x[i];
}

} /* end mdlDerivatives */

/* Function: mdlTerminate =====================================================

* Abstract:
* Called when the simulation is terminated.
* For this block, there are no end of simulation tasks.
*/
static void mdlTerminate(SimStruct *S)
{
UNUSED_ARG(S); /* unused input argument */
} /* end mdlTerminate */

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include "simulink.c" /* MEX-file interface mechanism */

7-70
 S-Function Examples

#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

7-71
7 Implementing Block Features

7-72
 8
Writing S-Functions for
Real-Time Workshop
Introduction . . . . . . . . . . . . . . . . . . . . 8-2
Classes of Problems Solved by S-Functions . . . . . . . . 8-2
Types of S-Functions . . . . . . . . . . . . . . . . . 8-3
Basic Files Required for Implementation . . . . . . . . . 8-5

Noninlined S-Functions . . . . . . . . . . . . . . . 8-7

S-Function Module Names for Real-Time Workshop Builds . 8-7

Writing Wrapper S-Functions . . . . . . . . . . . . . 8-9

The MEX S-Function Wrapper . . . . . . . . . . . . . 8-9
The TLC S-Function Wrapper . . . . . . . . . . . . . 8-14
The Inlined Code . . . . . . . . . . . . . . . . . . . 8-18

Fully Inlined S-Functions . . . . . . . . . . . . . . 8-19

Multiport S-Function Example . . . . . . . . . . . . . 8-19

Fully Inlined S-Function with the mdlRTW Routine . . . 8-21

S-Function RTWdata . . . . . . . . . . . . . . . . . 8-22
The Direct-Index Lookup Table Algorithm . . . . . . . . 8-23
The Direct-Index Lookup Table Example . . . . . . . . . 8-24
8 Writing S-Functions for Real-Time Workshop

Introduction
This chapter describes how to create S-functions that work seamlessly with
both Simulink and the Real-Time Workshop. 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 these concepts:

• Level 2 S-functions
• Target Language Compiler (TLC)
• The basics of how the Real-Time Workshop creates generated code

See the Target Language Compiler Reference Guide, and the Real-Time
Workshop User’s Guide for more information about these subjects.
A note on terminology: when this chapter refers actions performed by the
Target Language Compiler, including parsing, caching, creating buffers, etc.,
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, we
recommend that you follow the guidelines presented in this chapter when
writing S-functions, especially if you are creating general-purpose S-functions.

Classes of Problems Solved by S-Functions

S-functions help solve various kinds of problems you may face when working
with Simulink and the Real-Time Workshop (Real-Time Workshop). These
problems include:

• Extending the set of algorithms (blocks) provided by Simulink and

Real-Time Workshop
• Interfacing legacy (hand-written) C-code with Simulink and Real-Time
Workshop
• Generating highly optimized C-code for embedded systems

8-2
 Introduction

S-functions and S-function routines form 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. For
example, it is not possible to access the MATLAB workspace from an S-function
that is used with the Real-Time Workshop. However, using the techniques
presented in this chapter, you can create S-functions for most applications that
work with the generated code from the Real-Time Workshop.
Although S-functions provide a generic and flexible solution for implementing
complex algorithms in Simulink, they require significant 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 to
inline your S-functions.

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 Simulink and the
Real-Time Workshop. 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 Simulink and the Real-Time Workshop
automatically.”

2 “I have a lot of hand-written code that I need to interface. I want to call my

function from Simulink and the Real-Time Workshop 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 Simulink and the
Real-Time Workshop.”

8-3
8 Writing S-Functions for Real-Time Workshop

3 “I want to implement a highly optimized algorithm in Simulink and the

Real-Time Workshop that looks like a built-in block and generates very
efficient code.”

The MathWorks has 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-MEX S-function that is treated identically by
Simulink and the Real-Time Workshop. In general, you implement your
algorithm once according to the S-function API. Simulink and the Real-Time
Workshop call the S-function routines (e.g., mdlOutputs) at the appropriate
points during model execution.
Significant memory and computation resources are required for each instance
of a noninlined S-function block. However, this routine of incorporating
algorithms into Simulink and the Real-Time Workshop is typical during the
prototyping phase of a project where efficiency is not important. The advantage
gained by foregoing efficiency is the ability to change model parameters and/or
structures rapidly.
Note that writing a noninlined S-function does not involve any TLC coding.
Noninlined S-functions are the default case for the Real-Time Workshop in the
sense that once you’ve built a C-MEX S-function in your model, there is no
additional preparation prior to clicking Build in the Real-Time Workshop
Page of the Simulation Parameters dialog box for your model.

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 C-MEX
S-function. The S-function module typically contains a few calls to your
procedures. Since 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.

8-4
 Introduction

In addition to the C-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

A fully inlined S-function builds your algorithm (block) into Simulink and the
Real-Time Workshop 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 Simulink (C-MEX S-function) and once for the
Real-Time Workshop (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.

Basic Files Required for Implementation

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

• Noninlined S-functions require the C-MEX S-function source code

(sfunction.c).
• Wrapper S-functions that inline a call to your algorithm (your C function)
require an sfunction.tlc file.
• Fully inlined S-functions 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 parameter(s) that do not change during model execution. For a
given operating mode, the sfunction.tlc specifies the exact code that will
be 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 may require the placement of the mdlRTW routine
in your S-function MEX-file, sfunction.c. The mdlRTW routine lets you
place information in model.rtw, which is the file that is processed by the
Target Language Compiler prior to executing sfunction.tlc when
generating code. This is useful when you want to introduce nontunable
parameters into your TLC file.

8-5
8 Writing S-Functions for Real-Time Workshop

For S-functions to work correctly in the Simulink environment, a certain

amount of overhead code is necessary. When the Real-Time Workshop
generates code from models that contain S-functions (without sfunction.tlc
files), it embeds some of this overhead code in the generated C 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 directs the Real-Time Workshop to eliminate all
overhead code from the generated code. The Target Language Compiler, which
is part of the Real-Time Workshop, 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
MathWorks terminology, inline means to specify a textual string in place of
the call to the general S-function API routines (e.g., mdlOutputs). For example,
when we say that a TLC file is used to inline an S-function, we mean that the
generated code contains the appropriate C code that would normally appear
within the S-function routines and the S-function itself has been removed
from the build process.

8-6
 Noninlined S-Functions

Noninlined S-Functions
Noninlined S-functions are identified by the absence of an sfunction.tlc file
for your S-function (sfunction.mex). When placing a noninlined S-function in
a model that is to be used with the Real-Time Workshop, the following
MATLAB API functions are supported:
• mxGetEps
• mxGetInf
• mxGetM
• mxGetN
• mxGetNaN
• mxGetPr — Note: using mxGetPr on an empty matrix does not return NULL;
rather, it returns a random value. Therefore, you should protect calls to
mxGetPr with mxIsEmpty.
• mxGetScalar
• mxGetString
• mxIsEmpty
• mxIsFinite
• mxIsInf
In addition, parameters to S-functions can only be of type double precision or
characters contained in scalars, vectors, or 2-D matrices. To obtain more
flexibility in the type of parameters you can supply to S-functions or the
operations in the S-function, you need to inline your S-function and (possibly)
use a mdlRTW S-function routine.

S-Function Module Names for Real-Time Workshop

Builds
If your S-function is built with multiple modules, you must provide the build
process names of additional modules. You can do this through the Real-Time
Workshop template makefile technology, or more conveniently by using the
set_param MATLAB command. For example, if your S-function is built with
multiple modules, as in
mex sfun_main.c sfun_module1.c sfun_module2.c

then specify the names of the modules without the extension using the
command

8-7
8 Writing S-Functions for Real-Time Workshop

set_param(sfun_block,'SFunctionModules','sfun_module1 sfun_module2')

The parameter can also be a variable as in

modules = 'sfun_module1 sfun_module2'
set_param(sfun_block,'SFunctionModules','modules')

or a string to be evaluated (this is needed when the modules are valid

identifiers).
set_param(sfun_block,'SFunctionModules','''sfun_module1 sfun_module2''')

8-8
 Writing Wrapper S-Functions

Writing Wrapper S-Functions

This section describes how to create S-functions that work seamlessly with
Simulink and the Real-time Workshop using the wrapper concept. This section
begins by describing how to interface your algorithms in Simulink by writing
MEX S-function wrappers (sfunction.mex). It finishes with a description of
how to direct the Real-Time Workshop to insert your algorithm into the
generated code by creating a TLC S-function wrapper (sfunction.tlc).

The MEX S-Function Wrapper

Creating S-functions using an S-function wrapper allows you to insert your C
code algorithms in Simulink and the Real-Time Workshop with little or no
change to your original C code function. A MEX S-function wrapper is an
S-function that calls code that resides in another module. In effect, the wrapper
binds your code to Simulink. A TLC S-function wrapper is a TLC file that
specifies how the Real-Time Workshop should call your code (the same code
that was called from the C-MEX S-function wrapper).
Suppose you have an algorithm (i.e., a C function), called my_alg that resides
in the file my_alg.c. You can integrate my_alg into Simulink by creating a
MEX S-function wrapper (e.g., wrapsfcn.c). Once this is done, Simulink will
be able to call my_alg from an S-function block. However, the Simulink
S-function contains a set of empty functions that Simulink requires for various
API-related purposes. For example, although only mdlOutputs calls my_alg,
Simulink calls mdlTerminate as well, even though this S-function routine
performs no action.
You can integrate my_alg into the Real-Time Workshop generated code (i.e.,
embed the call to my_alg in the generated code) by creating a TLC S-function
wrapper (e.g., wrapsfcn.tlc). The advantage of creating a TLC S-function
wrapper is that the empty function calls can be eliminated and the overhead of
executing the mdlOutputs function and then the my_alg function can be
eliminated.
Wrapper S-functions are useful when creating new algorithms that are
procedural in nature or when integrating legacy code into Simulink. However,
if you want to create code that is:

• Interpretive in nature in Simulink (i.e., highly-parameterized by operating

modes)

8-9
8 Writing S-Functions for Real-Time Workshop

• Heavily optimized in the Real-Time Workshop (i.e., no extra tests to decide

what mode the code is operating in)

then you must create a fully inlined TLC file for your S-function.

8-10
 Writing Wrapper S-Functions

This figure illustrates the wrapper S-function concept.

Simulink Real-Time Workshop

Place the name of your wrapper.c, the generated
code, calls MdlOutputs,
wrapper.mdl which then calls my_alg.
wrapper.c
...
wrapsfcn
*see note below MdlOutputs(...)
S-function {
...
my_alg();
In Simulink, the }
S-function calls
mdlOutputs, which in

wrapsfcn.c In the TLC wrapper

... version of the
mdlOutputs(...)
S-function,
{
MdlOutputs in
...
my_alg(); wrapper.exe calls
}

mdlOutputs in my_alg.c
wrapsfcn.mex ...
calls external real_T my_alg(real_T u)
function my_alg. {
...
y=f(u);
}

*The dotted line above would be the path taken if the S-function did not
have a TLC wrapper file. If there is no TLC wrapper file, the generated code
calls mdlOutputs.

Figure 8-1: How S-Functions Interface with Hand-Written Code

8-11
8 Writing S-Functions for Real-Time Workshop

Using an S-function wrapper to import algorithms in your Simulink model

means that the S-function serves as an interface that calls your C code
algorithms from mdlOutputs. S-function wrappers have the advantage that you
can quickly integrate large stand-alone C code into your model without having
to make changes to the code.
This is an example of a model that includes an S-function wrapper.

Figure 8-1: An Example Model That Includes an S-Function Wrapper

There are two files associated with wrapsfcn block, the S-function wrapper and
the C code that contains the algorithm. This is the S-function wrapper code for
this example, called wrapsfcn.c.
#define S_FUNCTION_NAME wrapsfcn
#define S_FUNCTION_LEVEL 2
#include “simstruc.h”
Declare my_alg as
extern real_T my_alg(real_T u);
extern.
/*
* mdlInitializeSizes - initialize the sizes array
*/
static void mdlInitializeSizes(SimStruct *S)
{

ssSetNumSFcnParams( S, 0); /*number of input arguments*/

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, 1);
ssSetInputPortDirectFeedThrough(S, 0, 1);

if (!ssSetNumOutputPorts(S,1)) return;
ssSetOutputPortWidth(S, 0, 1);

ssSetNumSampleTimes( S, 1);
}

8-12
 Writing Wrapper S-Functions

/*
* mdlInitializeSampleTimes - indicate that this S-function runs
*at the rate of the source (driving block)
*/
static void mdlInitializeSampleTimes(SimStruct *S)
{
ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
}

/*
* mdlOutputs - compute the outputs by calling my_alg, which
*resides in another module, my_alg.c
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
Place the call to real_T *y = ssGetOutputPortRealSignal(S,0);
my_alg in *y = my_alg(*uPtrs[0]);
mdlOutputs. }
/*
* mdlTerminate - called when the simulation is terminated.
*/
static void mdlTerminate(SimStruct *S)
{
}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include “simulink.c” /* MEX-file interface mechanism */
#else
#include “cg_sfun.h” /* Code generation registration function */
#endif

The S-function routine mdlOutputs contains a function call to my_alg, which is

the C function that contains the algorithm that the S-function performs. This
is the code for my_alg.c.
#include "tmwtypes.h"
real_T my_alg(real_T u)
{
return(u * 2.0);
}

The wrapper S-function (wrapsfcn) calls my_alg, which computes u * 2.0. To

build wrapsfcn.mex, use the following command.
mex wrapsfcn.c my_alg.c

8-13
8 Writing S-Functions for Real-Time Workshop

The TLC S-Function Wrapper

This section describes how to inline the call to my_alg in the MdlOutputs
section of the generated code. In the above example, the call to my_alg is
embedded in the mdlOutputs section as
*y = my_alg(*uPtrs[0]);

When creating a TLC S-function wrapper, the goal is to have the Real-Time
Workshop embed the same type of call in the generated code.
It is instructive to look at how the Real-Time Workshop executes S-functions
that are not inlined. A noninlined S-function is identified by the absence of the
file sfunction.tlc and the existence of sfunction.mex. When generating code
for a noninlined S-function, the Real-Time Workshop generates a call to
mdlOutputs through a function pointer that, in this example, then calls my_alg.

The wrapper example contains one S-function (wrapsfcn.mex). You must

compile and link an additional module, my_alg, with the generated code. To do
this, specify
set_param('wrapper/S-Function','SFunctionModules','my_alg')

The code generated when using grt.tlc as the system target file without
wrapsfcn.tlc is
<Generated code comments for wrapper model with noninlined wrapsfcn S-function>

#include <math.h>
#include <string.h>
#include “wrapper.h”
#include “wrapper.prm”

/* Start the model */

void MdlStart(void)
{
/* (no start code required) */
}

/* Compute block outputs */

void MdlOutputs(int_T tid)
{
/* Sin Block: <Root>/Sin */
rtB.Sin = rtP.Sin.Amplitude *
sin(rtP.Sin.Frequency * ssGetT(rtS) + rtP.Sin.Phase);

8-14
 Writing Wrapper S-Functions

/* Level2 S-Function Block: <Root>/S-Function (wrapsfcn) */

Noninlined {
S-functions create a SimStruct *rts = ssGetSFunction(rtS, 0);
SimStruct object and sfcnOutputs(rts, tid);
}
generate a call to the
S-function routine /* Outport Block: <Root>/Out */
rtY.Out = rtB.S_Function;
}

/* Perform model update */

void MdlUpdate(int_T tid)
{
/* (no update code required) */
}

/* Terminate function */
void MdlTerminate(void)
{
/* Level2 S-Function Block: <Root>/S-Function (wrapsfcn) */
Noninlined {
S-functions require a SimStruct *rts = ssGetSFunction(rtS, 0);
SimStruct object and sfcnTerminate(rts);
}
the call to the }

#include “wrapper.reg”

/* [EOF] wrapper.c */

In addition to the overhead outlined above, the wrapper.reg generated file

contains the initialization of the SimStruct for the wrapper S-function block.
There is one child SimStruct for each S-function block in your model. This
overhead can be significantly reduced by creating a TLC wrapper for the
S-function.

How to Inline
The generated code makes the call to your S-function, wrapsfcn.c, in
MdlOutputs by using this code.
SimStruct *rts = ssGetSFunction(rtS, 0);
sfcnOutputs(rts, tid);

This call has a significant amount of computational overhead associated with

it. First, Simulink creates a SimStruct data structure for the S-function block.
Second, the Real-Time Workshop constructs a call through a function pointer
to execute MdlOutputs, and then MdlOutputs calls my_alg. By inlining the call

8-15
8 Writing S-Functions for Real-Time Workshop

to your C algorithm (my_alg), you can eliminate both the SimStruct and the
extra function call, thereby improving the efficiency and reducing the size of
the generated code.
Inlining a wrapper S-function requires an sfunction.tlc file for the
S-function; this file must contain the function call to my_alg. This picture
shows the relationships between the algorithm, the wrapper S-function, and
the sfunction.tlc file.

wrapper.c
my_alg.c
...
myalg() MdlOutputs
{ {
<C code here> ...
} y = my_alg();
...
}
...
The wrapsfcn.tlc file tells the
Real-Time Workshop how to inline the
call to my_alg using this statement:
wrapsfcn.tlc
...
%<y> = my_alg(%<u>);
...

Figure 8-2: Inlining an Algorithm by Using a TLC File

To inline this call, you have to place your function call into an sfunction.tlc
file with the same name as the S-function (in this example, wrapsfcn.tlc).
This causes the Target Language Compiler to override the default method of
placing calls to your S-function in the generated code.

8-16
 Writing Wrapper S-Functions

This is the wrapsfcn.tlc file that inlines wrapsfcn.c.

%% File : wrapsfcn.tlc
%% Abstract:
%% Example inlined tlc file for S-function wrapsfcn.c
%%

%implements “wrapsfcn” “C”

%% Function: BlockTypeSetup ====================================================

%% Abstract:
%% Create function prototype in model.h as:
%% “extern real_T my_alg(real_T u);”
%%
%function BlockTypeSetup(block, system) void
This line is placed in %openfile buffer
extern real_T my_alg(real_T u);
wrapper.h. %closefile buffer
%<LibCacheFunctionPrototype(buffer)>
%endfunction %% BlockTypeSetup

%% Function: Outputs ===========================================================

%% Abstract:
%% y = my_alg( u );
%%
%function Outputs(block, system) Output
/* %<Type> Block: %<Name> */
%assign u = LibBlockInputSignal(0, ““, ““, 0)
%assign y = LibBlockOutputSignal(0, ““, ““, 0)
This line is expanded %% PROVIDE THE CALLING STATEMENT FOR “algorithm”
and placed in %<y> = my_alg(%<u>);
MdlOutputs within
wrapper.c. %endfunction %% Outputs

The first section of this code directs the Real-Time Workshop to inline the
wrapsfcn S-function block and generate the code in C:
%implements "wrapsfcn" "C"

The next task is to tell the Real-Time Workshop that the routine, my_alg, needs
to be declared external in the generated wrapper.h file for any wrapsfcn
S-function blocks in the model. You only need to do this once for all wrapsfcn
S-function blocks, so use the BlockTypeSetup function. In this function, you tell
the Target Language Compiler to create a buffer and cache the my_alg as
extern in the wrapper.h generated header file.

The final step is the actual inlining of the call to the function my_alg. This is
done by the Outputs function. In this function, you load the input and output
and call place a direct call to my_alg. The call is embedded in wrapper.c.

8-17
8 Writing S-Functions for Real-Time Workshop

The Inlined Code

The code generated when you inline your wrapper S-function is similar to the
default generated code. The MdlTerminate function no longer contains a call to
an empty function and the MdlOutputs function now directly calls my_alg.
void MdlOutputs(int_T tid)
{
/* Sin Block: <Root>/Sin */
rtB.Sin = rtP.Sin.Amplitude *
sin(rtP.Sin.Frequency * ssGetT(rtS) + rtP.Sin.Phase);

/* S-Function Block: <Root>/S-Function */

Inlined call to the rtB.S_Function = my_alg(rtB.Sin);
function my_alg.
/* Outport Block: <Root>/Out */
rtY.Out = rtB.S_Function;
}

In addition, wrapper.reg no longer creates a child SimStruct for the S-function

since the generated code is calling my_alg directly. This eliminates over 1K of
memory usage.

8-18
 Fully Inlined S-Functions

Fully Inlined S-Functions

Continuing the example of the previous section, you could eliminate the call to
my_alg entirely by specifying the explicit code (i.e., 2.0*u) in wrapsfcn.tlc.
This is referred to as a fully inlined S-function. While this can improve
performance, if your C code is large this may be a lengthy task. In addition, you
now have to maintain your algorithm in two places, the C S-function itself and
the corresponding TLC file. However the performance gains may outweigh the
disadvantages. To inline the algorithm used in this example, in the Outputs
section of your wrapsfcn.tlc file, instead of writing
%<y> = my_alg(%<u>);

use:
%<y> = 2.0 * %<u>;

This is the code produced in MdlOutputs.

void MdlOutputs(int_T tid)
{
/* Sin Block: <Root>/Sin */
rtB.Sin = rtP.Sin.Amplitude *
sin(rtP.Sin.Frequency * ssGetT(rtS) + rtP.Sin.Phase);

/* S-Function Block: <Root>/S-Function */

This is the explicit rtB.S_Function = 2.0 * rtB.Sin;
embedding of the
algorithm. /* Outport Block: <Root>/Out */
rtY.Out = rtB.S_Function;
}

The Target Language Compiler has replaced the call to my_alg with the
algorithm itself.

Multiport S-Function Example

A more advanced multiport inlined S-function example exists in
matlabroot/simulink/src/sfun_multiport.c and
matlabroot/toolbox/simulink/blocks/tlc_c/sfun_multiport.tlc. This
S-function demonstrates how to create a fully inlined TLC file for an S-function

8-19
8 Writing S-Functions for Real-Time Workshop

that contains multiple ports. You may find that looking at this example will aid
in the understanding of fully inlined TLC files.

8-20
 Fully Inlined S-Function with the mdlRTW Routine

Fully Inlined S-Function with the mdlRTW Routine

You can make a more fully inlined S-function that uses the S-function mdlRTW
routine. The purpose of the mdlRTW routine is to provide the code generation
process with more information about how the S-function is to be inlined,
including:

• Renaming of tunable parameters in the generated code. This improves

readability of the code by replacing p1, p2, etc., by names of your choice.
• Creating a parameter record of a nontunable parameter for use with a TLC
file.

mdlRTW does this by placing information into the model.rtw file. The mdlRTW
routine is described in the text file matlabroot/simulink/src/
sfuntmpl_doc.c.

As an example of how to use the mdlRTW function, this section discusses the
steps you must take to create a direct-index lookup S-function. Look-up tables
are a collection of ordered data points of a function. Typically, these tables use
some interpolation scheme to approximate values of the associated function
between known data points. To incorporate the example lookup table algorithm
in Simulink, the first step is to write an S-function that executes the algorithm
in mdlOutputs. To produce the most efficient C code, the next step is to create
a corresponding TLC file to eliminate computational overhead and improve the
performance of the lookup computations.
For your convenience, Simulink provides support for two general purpose
lookup 1-D and 2-D algorithms. You can use these algorithms as they are or
create a custom lookup table S-function to fit your requirements. This section
demonstrates how to create a 1-D lookup S-function (sfun_directlook.c) and
its corresponding inlined sfun_directlook.tlc file (see the Real-Time
Workshop User’s Guide and the Target Language Compiler Reference Guide for
more details on the Target Language Compiler). This 1-D direct-index lookup
table example demonstrates the following concepts that you need to know to
create your own custom lookup tables:

• Error checking of S-function parameters

• Caching of information for the S-function that doesn’t change during model
execution

8-21
8 Writing S-Functions for Real-Time Workshop

• How to use the mdlRTW routine to customize the Real-Time Workshop

generated code to produce the optimal code for a given set of block
parameters
• How to generate an inlined TLC file for an S-function in a combination of the
fully-inlined form and/or the wrapper form

S-Function RTWdata
There is a property of blocks called RTWdata, which can be used by the Target
Language Compiler when inlining an S-function. RTWdata is a structure of
strings that you can attach to a block. It is saved with the model and placed in
the model.rtw file when generating code. For example, this set of MATLAB
commands,
mydata.field1 = 'information for field1';
mydata.field2 = 'information for field2';
set_param(gcb,'RTWdata',mydata)
get_param(gcb,'RTWdata')

produces this result:

ans =

field1: 'information for field1'

field2: 'information for field2'

Inside the model.rtw for the associated S-function block is this information.
Block {
Type "S-Function"
RTWdata {
field1 "information for field1"
field2 "information for field2"
}

8-22
 Fully Inlined S-Function with the mdlRTW Routine

The Direct-Index Lookup Table Algorithm

The 1-D lookup table block provided in the Simulink library uses interpolation
or extrapolation when computing outputs. This extra accuracy is not needed in
all situations. In this example, you will create a lookup table that directly
indexes the output vector (y-data vector) based on the current input (x-data)
point.
This direct 1-D lookup example computes an approximate solution, p(x), to a
partially known function f(x) at x=x0, given data point pairs (x,y) in the form of
an x data vector and a y data vector. For a given data pair (e.g., the i’th pair),
y_i = f(x_i). It is assumed that the x-data values are monotonically increasing.
If x0 is outside of the range of the x-data vector, then the first or last point will
be returned.
The parameters to the S-function are
XData, YData, XEvenlySpaced

XData and YData are double vectors of equal length representing the values of
the unknown function. XDataEvenlySpaced is a scalar, 0.0 for false and 1.0 for
true. If the XData vector is evenly spaced, then more efficient code is generated.

8-23
8 Writing S-Functions for Real-Time Workshop

The following graph illustrates how the parameters XData=[1:6],

YData=[1,2,7,4,5,9] are handled. For example, if the input (x-value) to the
S-function block is 3, then the output (y-value) is 7.

1
1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6

Figure 8-3: Typical Output from a Lookup Table Example

The Direct-Index Lookup Table Example

This section shows how to improve the lookup table by inlining a direct-index
S-function with a TLC file. Note that this direct-index lookup table S-function
doesn’t require a TLC file for it to work with the Real-Time Workshop. Here the
example uses a TLC file for the direct-index lookup table S-function to reduce
the code size and increase efficiency of the generated code.
Implementation of the direct-index algorithm with inlined TLC file requires
the S-function main module, sfun_directlook.c (see page 8– 28) and a
corresponding lookup_index.c module (see page 8– 37). The lookup_index.c
module contains the GetDirectLookupIndex routine that is used to locate the

8-24
 Fully Inlined S-Function with the mdlRTW Routine

index in the XData for the current x input value when the XData is unevenly
spaced. The GetDirectLookupIndex routine is called from both the S-function
and the generated code. Here the example uses the wrapper concept for sharing
C code between Simulink MEX-files and the generated code.
If the XData is evenly spaced, then both the S-function main module and the
generated code contain the lookup algorithm (not a call to the algorithm) to
compute the y-value of a given x-value because the algorithm is short. This
demonstrates the use of a fully inlined S-function for generating optimal code.
The inlined TLC file, which performs either a wrapper call or embeds the
optimal C code, is sfun_directlook.tlc (see page 8– 39).

Error Handling
In this example, the mdlCheckParameters routine on page 8– 31 verifies that:
• The new parameter settings are correct.
• XData and YData are vectors of the same length containing real finite
numbers.
• XDataEvenlySpaced is a scalar.
• The XData vector is a monotonically increasing vector and evenly spaced if
needed.

Note that the mdlInitilizeSizes routine explicitly calls mdlCheckParameters

after it has verified the number of parameters passed to the S-function are
correct. After Simulink calls mdlInitializeSizes, it will then call
mdlCheckParameters whenever you change the parameters or there is a need
to re-evaluate them.

User Data Caching

The mdlStart routine on page 8– 34 illustrates how to cache information that
does not change during the simulation (or while the generated code is
executing). The example caches the value of the XDataEvenlySpaced parameter
in UserData, a field of the SimStruct. The
ssSetSFcnParamNotTunable(S, XDATAEVENLYSPACED_PIDX);

line in mdlInitializeSizes tells Simulink to disallow changes to the

XDataEvenlySpaced parameter. During execution, mdlOutputs accesses the
value of XDataEvenlySpaced from the UserData rather than calling the

8-25
8 Writing S-Functions for Real-Time Workshop

mxGetPr MATLAB API function. This results in a slight increase in

performance.

mdlRTW Usage
The Real-Time Workshop calls the mdlRTW routine while it (the Real-Time
Workshop) generates the model.rtw file. You can add information to the
model.rtw file about the mode in which your S-function block is operating to
produce optimal code for your Simulink model.
This example adds the following information to the model.rtw file:

• Parameters — these are items that can be modified during execution by

external mode. In this example, the XData and YData S-function parameters
can change during execution and are written using the function
ssWriteRTWParameters.
• Parameter settings — these are items that do not change during execution.
In this case the XDataEvenlySpaced S-function parameter cannot change
during execution (ssSetSFcnParamNotTunable was specified for it in
mdlInitializeSizes). This example writes it out as a parameter setting
(XSpacing) using the function ssWriteRTWParamSettings.

Example Model
Before examining the S-function and the inlined TLC file, consider the
generated code for the following model.

8-26
 Fully Inlined S-Function with the mdlRTW Routine

When creating this model, you need to specify the following for each S-function
block.
set_param(‘sfun_directlook_ex/S-Function’,’SFunctionModules’,’lookup_index’)
set_param(‘sfun_directlook_ex/S-Function1’,’SFunctionModules’,’lookup_index’)

This informs the Real-Time Workshop build process that the module
lookup_index.c is needed when creating the executable.

The generated code for the lookup table example model is

<Generated header for sfun_directlook_ex model>

#include <math.h>
#include <string.h>
#include “sfun_directlook_ex.h”
#include “sfun_directlook_ex.prm”

/* Start the model */

void MdlStart(void)
{
/* (no start code required) */
}

/* Compute block outputs */

void MdlOutputs(int_T tid)
{
/* local block i/o variables */
real_T rtb_Sine_Wave;
real_T rtb_buffer2;

/* Sin Block: <Root>/Sine Wave */

rtb_Sine_Wave = rtP.Sine_Wave.Amplitude *
sin(rtP.Sine_Wave.Frequency * ssGetT(rtS) + rtP.Sine_Wave.Phase);

/* S-Function Block: <Root>/S-Function */

{
real_T *xData = &rtP.S_Function.XData[0];
real_T *yData = &rtP.S_Function.YData[0];
real_T spacing = xData[1] - xData[0];

if ( rtb_Sine_Wave <= xData[0] ) {

rtb_buffer2 = yData[0];
This is the code that is } else if ( rtb_Sine_Wave >= yData[20] ) {
inlined for the top rtb_buffer2 = yData[20];
S-function block in the } else {
int_T idx = (int_T)( ( rtb_Sine_Wave - xData[0] ) / spacing );
sfun_directlook_ex. rtb_buffer2 = yData[idx];
}
}

/* Outport Block: <Root>/Out1 */

8-27
8 Writing S-Functions for Real-Time Workshop

rtY.Out1 = rtb_buffer2;

/* S-Function Block: <Root>/S-Function1 */

{
real_T *xData = &rtP.S_Function1.XData[0];
real_T *yData = &rtP.S_Function1.YData[0];
int_T idx;
This is the code that is
inlined for the bottom idx = GetDirectLookupIndex(xData, 5, rtb_Sine_Wave);
S-function block in the rtb_buffer2 = yData[idx];
}
sfun_directlook_ex
model. /* Outport Block: <Root>/Out2 */
rtY.Out2 = rtb_buffer2;
}

/* Perform model update */

void MdlUpdate(int_T tid)
{
/* (no update code required) */
}

/* Terminate function */
void MdlTerminate(void)
{
/* (no terminate code required) */
}

#include “sfun_directlook_ex.reg”

/* [EOF] sfun_directlook_ex.c */

matlabroot/simulink/src/sfun_directlook.c
/*
* File : sfun_directlook.c
* Abstract:
*
* Direct 1-D lookup. Here we are trying to compute an approximate
* solution, p(x) to an unknown function f(x) at x=x0, given data point
* pairs (x,y) in the form of a x data vector and a y data vector. For a
* given data pair (say the i’th pair), we have y_i = f(x_i). It is
* assumed that the x data values are monotonically increasing. If the
* x0 is outside of the range of the x data vector, then the first or
* last point will be returned.
*
* This function returns the “nearest” y0 point for a given x0. No
* interpolation is performed.
*
* The S-function parameters are:
* XData - double vector
* YData - double vector

8-28
 Fully Inlined S-Function with the mdlRTW Routine

* XDataEvenlySpacing - double scalar 0 (false) or 1 (true)

* The third parameter cannot be changed during simulation.
*
* To build:
* mex sfun_directlook.c lookup_index.c
*
* Copyright (c) 1990-1998 by The MathWorks, Inc. All Rights Reserved.
* $Revision: 1.3 $
*/

#define S_FUNCTION_NAME sfun_directlook

#define S_FUNCTION_LEVEL 2

#include <math.h>
#include “simstruc.h”
#include <float.h>

/*=========*
* Defines *
*=========*/

#define XVECT_PIDX 0
#define YVECT_PIDX 1
#define XDATAEVENLYSPACED_PIDX 2
#define NUM_PARAMS 3

#define XVECT(S) ssGetSFcnParam(S,XVECT_PIDX)

#define YVECT(S) ssGetSFcnParam(S,YVECT_PIDX)
#define XDATAEVENLYSPACED(S) ssGetSFcnParam(S,XDATAEVENLYSPACED_PIDX)

/*==============*
* misc defines *
*==============*/
#if !defined(TRUE)
#define TRUE 1
#endif
#if !defined(FALSE)
#define FALSE 0
#endif

/*===========*
* typedef’s *
*===========*/

typedef struct SFcnCache_tag {

boolean_T evenlySpaced;
} SFcnCache;

/*===================================================================*
* Prototype define for the function in separate file lookup_index.c *
*===================================================================*/

8-29
8 Writing S-Functions for Real-Time Workshop

extern int_T GetDirectLookupIndex(const real_T *x, int_T xlen, real_T u);

/*=========================*
* Local Utility Functions *
*=========================*/

/* Function: IsRealVect ========================================================

* Abstract:
* Verify that the mxArray is a real vector.
*/
static boolean_T IsRealVect(const mxArray *m)
{
if (mxIsNumeric(m) &&
mxIsDouble(m) &&
!mxIsLogical(m) &&
!mxIsComplex(m) &&
!mxIsSparse(m) &&
!mxIsEmpty(m) &&
mxGetNumberOfDimensions(m) == 2 &&
(mxGetM(m) == 1 || mxGetN(m) == 1))
{

real_T *data = mxGetPr(m);

int_T numEl = mxGetNumberOfElements(m);
int_T i;

for (i = 0; i < numEl; i++) {

if (!mxIsFinite(data[i])) {
return(FALSE);
}
}

return(TRUE);
} else {
return(FALSE);
}
}
/* end IsRealVect */

/*====================*
* S-function routines *
*====================*/

#define MDL_CHECK_PARAMETERS /* Change to #undef to remove function */

#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)
/* Function: mdlCheckParameters ================================================
* Abstract:
* This routine will be called after mdlInitializeSizes, whenever
* parameters change or get re-evaluated. The purpose of this routine is

8-30
 Fully Inlined S-Function with the mdlRTW Routine

* to verify that the new parameter settings are correct.

*
* You should add a call to this routine from mdlInitalizeSizes
* to check the parameters. After setting your sizes elements, you should:
* if (ssGetSFcnParamsCount(S) == ssGetNumSFcnParams(S)) {
* mdlCheckParameters(S);
* }
*/
static void mdlCheckParameters(SimStruct *S)
{

if (!IsRealVect(XVECT(S))) {
ssSetErrorStatus(S,”1st, X-vector parameter must be a real finite “
“ vector”);
return;
}

if (!IsRealVect(YVECT(S))) {
ssSetErrorStatus(S,”2nd, Y-vector parameter must be a real finite “
“vector”);
return;
}

/*
* Verify that the dimensions of X and Y are the same.
*/
if (mxGetNumberOfElements(XVECT(S)) != mxGetNumberOfElements(YVECT(S)) ||
mxGetNumberOfElements(XVECT(S)) == 1) {
ssSetErrorStatus(S,”X and Y-vectors must be of the same dimension “
“and have at least two elements”);
return;
}

/*
* Verify we have a valid XDataEvenlySpaced parameter.
*/
if (!mxIsNumeric(XDATAEVENLYSPACED(S)) ||
!(mxIsDouble(XDATAEVENLYSPACED(S)) ||
mxIsLogical(XDATAEVENLYSPACED(S))) ||
mxIsComplex(XDATAEVENLYSPACED(S)) ||
mxGetNumberOfElements(XDATAEVENLYSPACED(S)) != 1) {
ssSetErrorStatus(S,”3rd, X-evenly-spaced parameter must be scalar “
“(0.0=false, 1.0=true)”);
return;
}

/*
* Verify x-data is correctly spaced.
*/
{
int_T i;
boolean_T spacingEqual;
real_T *xData = mxGetPr(XVECT(S));

8-31
8 Writing S-Functions for Real-Time Workshop

int_T numEl = mxGetNumberOfElements(XVECT(S));

/*
* spacingEqual is TRUE if user XDataEvenlySpaced
*/
spacingEqual = (mxGetScalar(XDATAEVENLYSPACED(S)) != 0.0);

if (spacingEqual) { /* XData is ‘evenly-spaced’ */

boolean_T badSpacing = FALSE;
real_T spacing = xData[1] - xData[0];
real_T space;

if (spacing <= 0.0) {

badSpacing = TRUE;
} else {
real_T eps = DBL_EPSILON;

for (i = 2; i < numEl; i++) {

space = xData[i] - xData[i-1];
if (space <= 0.0 ||
fabs(space-spacing) >= 128.0*eps*spacing ){
badSpacing = TRUE;
break;
}
}
}

if (badSpacing) {
ssSetErrorStatus(S,”X-vector must be an evenly spaced “
“strictly monotonically increasing vector”);
return;
}
} else { /* XData is ‘unevenly-spaced’ */
for (i = 1; i < numEl; i++) {
if (xData[i] <= xData[i-1]) {
ssSetErrorStatus(S,”X-vector must be a strictly “
“monotonically increasing vector”);
return;
}
}
}
}
}
#endif /* MDL_CHECK_PARAMETERS */

/* Function: mdlInitializeSizes ================================================

* Abstract:
* The sizes information is used by Simulink to determine the S-function
* block’s characteristics (number of inputs, outputs, states, etc.).
*/
static void mdlInitializeSizes(SimStruct *S)

8-32
 Fully Inlined S-Function with the mdlRTW Routine

{
ssSetNumSFcnParams(S, NUM_PARAMS); /* Number of expected parameters */

/*
* Check parameters passed in, providing the correct number was specified
* in the S-function dialog box. If an incorrect number of parameters
* was specified, Simulink will detect the error since ssGetNumSFcnParams
* and ssGetSFcnParamsCount will differ.
* ssGetNumSFcnParams - This sets the number of parameters your
* S-function expects.
* ssGetSFcnParamsCount - This is the number of parameters entered by
* the user in the Simulink S-function dialog box.
*/
#if defined(MATLAB_MEX_FILE)
if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
mdlCheckParameters(S);
if (ssGetErrorStatus(S) != NULL) {
return;
}
} else {
return; /* Parameter mismatch will be reported by Simulink */
}
#endif

ssSetNumContStates(S, 0);
ssSetNumDiscStates(S, 0);

if (!ssSetNumInputPorts(S, 1)) return;

ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED);
ssSetInputPortDirectFeedThrough(S, 0, 1);

ssSetInputPortTestPoint(S, 0, FALSE);
ssSetInputPortOverWritable(S, 0, TRUE);

if (!ssSetNumOutputPorts(S, 1)) return;

ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED);

ssSetOutputPortTestPoint(S, 0, FALSE);

ssSetNumSampleTimes(S, 1);

ssSetSFcnParamNotTunable(S, XDATAEVENLYSPACED_PIDX);

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);

} /* mdlInitializeSizes */

/* Function: mdlInitializeSampleTimes ==========================================

* Abstract:
* The lookup inherits its sample time from the driving block.
*/
static void mdlInitializeSampleTimes(SimStruct *S)

8-33
8 Writing S-Functions for Real-Time Workshop

{
ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
ssSetOffsetTime(S, 0, 0.0);
} /* end mdlInitializeSampleTimes */

#define MDL_START /* Change to #undef to remove function */

#if defined(MDL_START)
/* Function: mdlStart ==========================================================
* Abstract:
* Here we cache the state (true/false) of the XDATAEVENLYSPACED parameter.
* We do this primarily to illustrate how to “cache” parameter values (or
* information that is computed from parameter values) that do not change
* for the duration of the simulation (or in the generated code). In this
* case, rather than repeated calls to mxGetPr, we save the state once.
* This results in a slight increase in performance.
*/
static void mdlStart(SimStruct *S)
{
SFcnCache *cache = malloc(sizeof(SFcnCache));

if (cache == NULL) {
ssSetErrorStatus(S,”memory allocation error”);
return;
}

ssSetUserData(S, cache);

if (mxGetScalar(XDATAEVENLYSPACED(S)) != 0.0){
cache->evenlySpaced = TRUE;
}else{
cache->evenlySpaced = FALSE;
}

}
#endif /* MDL_START */

/* Function: mdlOutputs ========================================================

* Abstract:
* In this function, we compute the outputs of our S-function
* block. Generally outputs are placed in the output vector, ssGetY(S).
*/
static void mdlOutputs(SimStruct *S, int_T tid)
{
SFcnCache *cache = ssGetUserData(S);
real_T *xData = mxGetPr(XVECT(S));
real_T *yData = mxGetPr(YVECT(S));
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
real_T *y = ssGetOutputPortRealSignal(S,0);
int_T ny = ssGetOutputPortWidth(S,0);

8-34
 Fully Inlined S-Function with the mdlRTW Routine

int_T xLen = mxGetNumberOfElements(XVECT(S));

int_T i;

/*
* When the XData is evenly spaced, we use the direct lookup algorithm
* to calculate the lookup
*/
if (cache->evenlySpaced) {
real_T spacing = xData[1] - xData[0];
for (i = 0; i < ny; i++) {
real_T u = *uPtrs[i];

if (u <= xData[0]) {
y[i] = yData[0];
} else if (u >= xData[xLen-1]) {
y[i] = yData[xLen-1];
} else {
int_T idx = (int_T)((u - xData[0])/spacing);
y[i] = yData[idx];
}
}
} else {
/*
* When the XData is unevenly spaced, we use a bisection search to
* locate the lookup index.
*/
for (i = 0; i < ny; i++) {
int_T idx = GetDirectLookupIndex(xData,xLen,*uPtrs[i]);
y[i] = yData[idx];
}
}

} /* end mdlOutputs */

/* Function: mdlTerminate ======================================================

* Abstract:
* Free the cache that was allocated in mdlStart.
*/
static void mdlTerminate(SimStruct *S)
{
SFcnCache *cache = ssGetUserData(S);
if (cache != NULL) {
free(cache);
}
} /* end mdlTerminate */

#define MDL_RTW /* Change to #undef to remove function */

#if defined(MDL_RTW) && (defined(MATLAB_MEX_FILE) || defined(NRT))
/* Function: mdlRTW ============================================================

8-35
8 Writing S-Functions for Real-Time Workshop

* Abstract:
* This function is called when the Real-Time Workshop is generating the
* model.rtw file. In this routine, you can call the following functions
* which add fields to the model.rtw file.
*
* Important! Since this S-function has this mdlRTW routine, it must have
* a correSponding .tlc file to work with the Real-Time Workshop. You will find
* the sfun_directlook.tlc in the same directory as sfun_directlook.dll.
*/
static void mdlRTW(SimStruct *S)
{
/*
* Write out the [X,Y] data as parameters, i.e., these values can be
* changed during execution.
*/
{
real_T *xData = mxGetPr(XVECT(S));
int_T xLen = mxGetNumberOfElements(XVECT(S));
real_T *yData = mxGetPr(YVECT(S));
int_T yLen = mxGetNumberOfElements(YVECT(S));

if (!ssWriteRTWParameters(S,2,
SSWRITE_VALUE_VECT,”XData”,””,xData,xLen,
SSWRITE_VALUE_VECT,”YData”,””,yData,yLen)) {
return; /* An error occurred which will be reported by Simulink */
}
}
/*
* Write out the spacing setting as a param setting, i.e., this cannot be
* changed during execution.
*/
{
boolean_T even = (mxGetScalar(XDATAEVENLYSPACED(S)) != 0.0);

if (!ssWriteRTWParamSettings(S, 1,
SSWRITE_VALUE_QSTR,
“XSpacing”,
even ? “EvenlySpaced” : “UnEvenlySpaced”)){
return;/* An error occurred which will be reported by Simulink */
}
}
}
#endif /* MDL_RTW */

/*=============================*
* Required S-function trailer *
*=============================*/

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */

#include “simulink.c” /* MEX-file interface mechanism */
#else
#include “cg_sfun.h” /* Code generation registration function */

8-36
 Fully Inlined S-Function with the mdlRTW Routine

#endif

/* [EOF] sfun_directlook.c */

matlabroot/simulink/src/lookup_index.c
/* File : lookup_index.c
* Abstract:
*
* Contains a routine used by the S-function sfun_directlookup.c to
* compute the index in a vector for a given data value.
*
* Copyright (c) 1990-1998 by The MathWorks, Inc. All Rights Reserved.
* $Revision: 1.3 $
*/
#include “tmwtypes.h”

/*
* Function: GetDirectLookupIndex ==============================================
* Abstract:
* Using a bisection search to locate the lookup index when the x-vector
* isn’t evenly spaced.
*
* Inputs:
* *x : Pointer to table, x[0] ....x[xlen-1]
* xlen : Number of values in xtable
* u : input value to look up
*
* Output:
* idx : the index into the table such that:
* if u is negative
* x[idx] <= u < x[idx+1]
* else
* x[idx] < u <= x[idx+1]
*/
int_T GetDirectLookupIndex(const real_T *x, int_T xlen, real_T u)
{
int_T idx = 0;
int_T bottom = 0;
int_T top = xlen-1;

/*
* Deal with the extreme cases first:
*
* i] u <= x[bottom] then idx = bottom
* ii] u >= x[top] then idx = top-1
*
*/
if (u <= x[bottom]) {
return(bottom);
} else if (u >= x[top]) {

8-37
8 Writing S-Functions for Real-Time Workshop

return(top);
}

/*
* We have: x[bottom] < u < x[top], onward
* with search for the appropriate index ...
*/
for (;;) {
idx = (bottom + top)/2;
if (u < x[idx]) {
top = idx;
} else if (u > x[idx+1]) {
bottom = idx + 1;
} else {
/*
* We have: x[idx] <= u <= x[idx+1], only need
* to do two more checks and we have the answer.
*/
if (u < 0) {
/*
* We want right continuity, i.e.,
* if u == x[idx+1]
* then x[idx+1] <= u < x[idx+2]
* else x[idx ] <= u < x[idx+1]
*/
return( (u == x[idx+1]) ? (idx+1) : idx);
} else {
/*
* We want left continuity, i.e.,
* if u == x[idx]
* then x[idx-1] < u <= x[idx ]
* else x[idx ] < u <= x[idx+1]
*/
return( (u == x[idx]) ? (idx-1) : idx);
}
}
}
} /* end GetDirectLookupIndex */

/* [EOF] lookup_index.c */

8-38
 Fully Inlined S-Function with the mdlRTW Routine

matlabroot/toolbox/simulink/blocks/tlc_c/sfun_directlook.tlc
%% File : sfun_directlook.tlc
%% Abstract:
%% Level-2 S-function sfun_directlook block target file.
%% It is using direct lookup algorithm without interpolation.
%%
%% Copyright (c) 1994-1998 by The MathWorks, Inc. All Rights Reserved.
%% $Revision: 1.3 $

%implements “sfun_directlook” “C”

%% Function: BlockTypeSetup ====================================================

%% Abstract:
%% Place include and function prototype in the model’s header file.
%%
%function BlockTypeSetup(block, system) void

%% Add this external function’s prototype in the header of the generated

%% file.
%%
%openfile buffer
extern int_T GetDirectLookupIndex(const real_T *x, int_T xlen, real_T u);
%closefile buffer

%<LibCacheFunctionPrototype(buffer)>

%endfunction

%% Function: mdlOutputs ========================================================

%% Abstract:
%% Direct 1-D lookup table S-function example.
%% Here we are trying to compute an approximate solution, p(x) to an
%% unknown function f(x) at x=x0, given data point pairs (x,y) in the
%% form of a x data vector and a y data vector. For a given data pair
%% (say the i’th pair), we have y_i = f(x_i). It is assumed that the x
%% data values are monotonically increasing. If the first or last x is
%% outside of the range of the x data vector, then the first or last
%% point will be returned.
%%
%% This function returns the “nearest” y0 point for a given x0.
%% No interpolation is performed.
%%
%% The S-function parameters are:
%% XData
%% YData
%% XEvenlySpaced: 0 or 1
%% The third parameter cannot be changed during execution and is
%% written to the model.rtw file in XSpacing filed of the SFcnParamSettings
%% record as “EvenlySpaced” or “UnEvenlySpaced”. The first two parameters
%% can change during execution and show up in the parameter vector.
%%

8-39
8 Writing S-Functions for Real-Time Workshop

%function Outputs(block, system) Output

/* %<Type> Block: %<Name> */
{
%assign rollVars = [“U”, “Y”]
%%
%% Load XData and YData as local variables
%%
real_T *xData = %<LibBlockParameterAddr(XData, ““, ““, 0)>;
real_T *yData = %<LibBlockParameterAddr(YData, ““, ““, 0)>;
%assign xDataLen = SIZE(XData.Value, 1)
%%
%% When the XData is evenly spaced, we use the direct lookup algorithm
%% to locate the lookup index.
%%
%if SFcnParamSettings.XSpacing == “EvenlySpaced”
real_T spacing = xData[1] - xData[0];

%roll idx = RollRegions, lcv = RollThreshold, block, “Roller”, rollVars

%assign u = LibBlockInputSignal(0, ““, lcv, idx)
%assign y = LibBlockOutputSignal(0, ““, lcv, idx)
if ( %<u> <= xData[0] ) {
%<y> = yData[0];
} else if ( %<u> >= yData[%<xDataLen-1>] ) {
%<y> = yData[%<xDataLen-1>];
} else {
int_T idx = (int_T)( ( %<u> - xData[0] ) / spacing );
%<y> = yData[idx];
}
%%
%% Generate an empty line if we are not rolling,
%% so that it looks nice in the generated code.
%%
%if lcv == ““

%endif
%endroll
%else
%% When the XData is unevenly spaced, we use a bisection search to
%% locate the lookup index.
int_T idx;

%assign xDataAddr = LibBlockParameterAddr(XData, ““, ““, 0)

%roll idx = RollRegions, lcv = RollThreshold, block, “Roller”, rollVars
%assign u = LibBlockInputSignal(0, ““, lcv, idx)
idx = GetDirectLookupIndex(xData, %<xDataLen>, %<u>);
%assign y = LibBlockOutputSignal(0, ““, lcv, idx)
%<y> = yData[idx];
%%
%% Generate an empty line if we are not rolling,
%% so that it looks nice in the generated code.
%%
%if lcv == ““

8-40
 Fully Inlined S-Function with the mdlRTW Routine

%endif
%endroll
%endif
}

%endfunction

%% EOF: sfun_directlook.tlc

8-41
8 Writing S-Functions for Real-Time Workshop

8-42
 9
S-Function
Callback Methods
Callback Method Reference . . . . . . . . . . . . . . 9-2
mdlCheckParameters . . . . . . . . . . . . . . . . . 9-3
mdlDerivatives . . . . . . . . . . . . . . . . . . . 9-5
mdlGetTimeOfNextVarHit . . . . . . . . . . . . . . . 9-6
mdlInitializeConditions . . . . . . . . . . . . . . . . 9-7
mdlInitializeSampleTimes . . . . . . . . . . . . . . . 9-9
mdlInitializeSizes . . . . . . . . . . . . . . . . . . 9-13
mdlOutputs . . . . . . . . . . . . . . . . . . . . . 9-17
mdlProcessParameters . . . . . . . . . . . . . . . . 9-18
mdlRTW . . . . . . . . . . . . . . . . . . . . . . 9-20
mdlSetDefaultPortComplexSignals . . . . . . . . . . . 9-21
mdlSetDefaultPortDataTypes . . . . . . . . . . . . . 9-22
mdlSetDefaultPortDimensionInfo . . . . . . . . . . . . 9-23
mdlSetInputPortComplexSignal . . . . . . . . . . . . 9-24
mdlSetInputPortDataType . . . . . . . . . . . . . . . 9-25
mdlSetInputPortDimensionInfo . . . . . . . . . . . . . 9-26
mdlSetInputPortFrameData . . . . . . . . . . . . . . 9-28
mdlSetInputPortSampleTime . . . . . . . . . . . . . 9-29
mdlSetInputPortWidth . . . . . . . . . . . . . . . . 9-31
mdlSetOutputPortComplexSignal . . . . . . . . . . . . 9-32
mdlSetOutputPortDataType . . . . . . . . . . . . . . 9-33
mdlSetOutputPortDimensionInfo . . . . . . . . . . . . 9-34
mdlSetOutputPortSampleTime . . . . . . . . . . . . . 9-36
mdlSetOutputPortWidth . . . . . . . . . . . . . . . 9-37
mdlSetWorkWidths . . . . . . . . . . . . . . . . . . 9-38
mdlStart . . . . . . . . . . . . . . . . . . . . . . 9-39
mdlTerminate . . . . . . . . . . . . . . . . . . . . 9-40
mdlUpdate . . . . . . . . . . . . . . . . . . . . . 9-41
mdlZeroCrossings . . . . . . . . . . . . . . . . . . 9-42
9 S-Function Callback Methods

Callback Method Reference

Every user-written S-function must implement a set of methods, called
callback methods or simply callbacks, that Simulink invokes when simulating
a model that contains the S-function. Some callback methods are optional.
Simulink invokes an optional callback only if the S-function defines the
callback. This section describes the purpose and syntax of all callback methods
that an S-function can implement. In each case, the documentation for a
callback method indicates whether it is required or optional.

9-2
 mdlCheckParameters

Purpose 9mdlCheckParameters
Check the validity of an S-function’s parameters.

Syntax void mdlCheckParameters(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Verifies new parameter settings whenever parameters change or are

re-evaluated during a simulation.
When a simulation is running, changes to S-function parameters can occur at
any time during the simulation loop; that is, either at the start of a simulation
step or during a simulation step. When the change occurs during a simulation
step, Simulink calls this routine twice to handle the parameter change. The
first call during the simulation step is used to verify that the parameters are
correct. After verifying the new parameters, the simulation continues using the
original parameter values until the next simulation step at which time the new
parameter values will be used. Redundant calls are needed to maintain
simulation consistency.

Note You cannot access the work, state, input, output, and other vectors in
this routine. Use this routine only to validate the parameters. Additional
processing of the parameters should be done in mdlProcessParameters.

Example This example checks the first S-function parameter to verify that it is a real
nonnegative scalar.
#define PARAM1(S) ssGetSFcnParam(S,0)
#define MDL_CHECK_PARAMETERS /* Change to #undef to remove function */
#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)
static void mdlCheckParameters(SimStruct *S)
{
if (mxGetNumberOfElements(PARAM1(S)) != 1) {
ssSetErrorStatus(S,”Parameter to S-function must be a scalar”);
return;
} else if (mxGetPr(PARAM1(S))[0] < 0) {
ssSetErrorStatus(S, “Parameter to S-function must be non-negative”);
return;
}
}
#endif /* MDL_CHECK_PARAMETERS */

9-3
mdlCheckParameters

In addition to the above routine, you must add a call to this routine from
mdlInitializSizes to check parameters during initialization since
mdlCheckParameters is only called while the simulation is running. To do this,
in mdlInitializeSizes, after setting the number of parameters you expect in
your S-function by using ssSetNumSFcnParams, use this code:
static void mdlInitializeSizes(SimStruct *S)
{
ssSetNumSFcnParams(S, 1); /* Number of expected parameters */
#if defined(MATLAB_MEX_FILE)
if(ssGetNumSfcnParams(s) == ssGetSFcnParamsCount(s) {
mdlCheckParameters(S);
if(ssGetErrorStates(S) != NULL) return;
} else {
return; /* Simulink will report a mismatch error. */
}
#endif
...
}

Note The macro ssGetSfcnParamsCount returns the actual number of

parameters entered in the dialog box.

See matlabroot/simulink/src/sfun_errhdl.c for an example.

Languages Ada, C

See Also mdlProcessParameters, ssGetSfcnParamsCount

9-4
 mdlDerivatives

Purpose 9mdlDerivatives
Compute the S-function’s derivatives.

Syntax void mdlDerivatives(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this optional method at each time step to compute the
derivatives of the S-function’s continuous states. This method should store the
derivatives in the S-function’s state derivatives vector. This method can use
ssGetdX to get a pointer to the derivatives vector.

Each time the mdlDerivatives routine is called, it must explicitly set the value
of all derivatives. The derivative vector does not maintain the values from the
last call to this routine. The memory allocated to the derivative vector changes
during execution.

Example For an example, see matlabroot/simulink/src/csfunc.c.

Languages Ada, C, M

See Also ssGetdx

9-5
mdlGetTimeOfNextVarHit

Purpose 9mdlGetTimeOfNextVarHit
Initialize the state vectors of this S-function.

Syntax void mdlGetTimeOfNextVarHit(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this optional method at every major integration step to get
the time of the next sample time hit. This method should set the time of next
hit, using ssSetTNext. The time of the next hit must be greater than the
current simulation time as returned by ssGetT. The S-function must
implement this method if it operates at a discrete, variable-step sample time.

Note The time of next hit can be a function of the input signal(s).

Languages C, M

Example
static void mdlGetTimeOfNextVarHit(SimStruct *S)
{
time_T offset = getOffset();
time_T timeOfNextHit = ssGetT(S) + offset;
ssSetTNext(S, timeOfNextHit);
}

See Also mdlInitializeSampleTimes, ssSetTNext, ssGetT

9-6
 mdlInitializeConditions

Purpose 9mdlInitializeConditions
Initialize the state vectors of this S-function.

Syntax void mdlInitializeConditions(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this optional method at the beginning of a simulation. It

should initialize the continuous and discrete states, if any, of this S-function
block. Use ssGetContStates and/or ssGetDiscStates to get the states. This
method can also perform any other initialization activities that this S-function
requires.
If this S-function resides in an enabled subsystem configured to reset states,
Simulink also calls this method when the enabled subsystem restarts
execution. This method can use ssIsFirstInitCond macro to determine if it is
being called for the first time.

Example This example is an S-function with both continuous and discrete states; it
initializes both sets of states to 1.0:
#define MDL_INITIALIZE_CONDITIONS /* Change to #undef to remove function */
#if defined(MDL_INITIALIZE_CONDITIONS)

static void mdlInitializeConditions(SimStruct *S)

{
int i;
real_T *xcont = ssGetContStates(S);
int_T nCStates = ssGetNumContStates(S);
real_T *xdisc = ssGetRealDiscStates(S);
int_T nDStates = ssGetNumDiscStates(S);

for (i = 0; i < nCStates; i++) {

*xcont++ = 1.0;
}

for (i = 0; i < nDStates; i++) {

*xdisc++ = 1.0;
}

}
#endif /* MDL_INITIALIZE_CONDITIONS */

For another example which initializes only the continuous states, see
matlabroot/simulink/src/resetint.c.

9-7
mdlInitializeConditions

Languages C

See Also mdlStart, ssIsFirstInitCond, ssGetContStates, ssGetDiscStates

9-8
 mdlInitializeSampleTimes

Purpose 9mdlInitializeSampleTimes
Specify the sample rates at which this S-function operates.

Syntax void mdInitializeSampleTimes(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description This method should specify the sample time and offset time for each sample
rate at which this S-function operates via the following paired macros
ssSetSampleTime(S, sampleTimeIndex, sample_time)
ssSetOffsetTime(S, offsetTimeIndex, offset_time)

where sampleTimeIndex runs from 0 to one less than the number of sample
times specified in mdlInitializeSizes via ssSetNumSampleTimes.
If the S-function operates at one or more sample rates, this method can specify
any of the following sample time and offset values for a given sample time:

• [CONTINUOUS_SAMPLE_TIME, 0.0]
• [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
• [discrete_sample_period, offset]
• [VARIABLE_SAMPLE_TIME, 0.0]
The upper case values are macros defined in simstruc.h.
If the S-function operates at one rate, this method can alternatively set the
sample time to one of the following sample/offset time pairs.
• [INHERITED_SAMPLE_TIME, 0.0]
• [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

If the number of sample times is 0, Simulink assumes that the S-function

inherits its sample time from the block to which it is connected, i.e., that the
sample time is
[INHERITED_SAMPLE_TIME, 0.0]

This method can therefore return without doing anything.

9-9
mdlInitializeSampleTimes

Use the following guidelines when specifying sample times.

• A continuous function that changes during minor integration steps should

set the sample time to
[CONTINUOUS_SAMPLE_TIME, 0.0]
• A continuous function that does not change during minor integration steps
should set the sample time to
[CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
• A discrete function that changes at a specified rate should set the sample
time to
[discrete_sample_period, offset]
where
discrete_sample_period > 0.0
and
0.0 <= offset < discrete_sample_period
• A discrete function that changes at a variable rate should set the sample
time to
[VARIABLE_SAMPLE_TIME, 0.0]
Simulink invokes mdlGetTimeOfNextVarHit function to get the time of the
next sample hit for the variable step discrete task.
Note that VARIABLE_SAMPLE_TIME requires a variable step solver.
• To operate correctly in a triggered subsystem or a periodic system, a discrete
S-function should:
- Specify a single sample time set to
[INHERITED_SAMPLE_TIME, 0.0]
- Set the SS_DISALLOW_CONSTANT_SAMPLE_TIME simulation option in
mdlInitializeSizes

9-10
 mdlInitializeSampleTimes

- Verify that it was assigned a discrete or triggered sample time in

mdlSetWorkWidths:
if (ssGetSampleTime(S, 0) == CONTINUOUS_SAMPLE_TIME) {
ssSetErrorStatus(S,
“This block cannot be assigned a continuous sample time”);
}
After propagating sample times throughout the block diagram, Simulink
assigns the sample time
[INHERITED_SAMPLE_TIME, INHERITED_SAMPLE_TIME]
to discrete blocks residing in triggered subsystems.

If this function has no intrinsic sample time, it should set its sample time to
inherited according to the following guidelines:

• A function that changes as its input changes, even during minor integration
steps, should set its sample time to
[INHERITED_SAMPLE_TIME, 0.0]
A function that changes as its input changes, but doesn’t change during
minor integration steps (i.e., held during minor steps) should set its sample
time to
[INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

The S-function should use the ssIsSampleHit or ssIsContinuousTask macros

to check for a sample hit during execution (in mdlOutputs or mdlUpdate). For
example, if the block’s first sample time is continuous, the function can use the
following code-fragment to check for a sample hit.
if (ssIsContinuousTask(S,tid)) {
}

Note The function would get incorrect results if it used

ssIsSampleHit(S,0,tid).

9-11
mdlInitializeSampleTimes

If the function wanted to determine if the third (discrete) task has a hit, it could
use the following code-fragment.
if (ssIsSampleHit(S,2,tid) {
}

Languages C

See Also mdlSetInputPortSampleTime, mdlSetOutputPortSampleTime

9-12
 mdlInitializeSizes

Purpose 9mdlInitializeSizes
Specify the number of inputs, outputs, states, parameters, and other
characteristics of the S-function.

Syntax void mdlInitializeSizes(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description This is the first of the S-function’s callback methods that Simulink calls. This
method should perform the following tasks:

• Specify the number of parameters that this S-function supports, using

ssSetNumSFcnParams.
Use ssSetSFcnParamNotTunable(S,paramIdx) when a parameter cannot
change during simulation, where paramIdx starts at 0. When a parameter
has been specified as “not tunable,” Simulink will issue an error during
simulation (or the Real-Time Workshop external mode) if an attempt is made
to change the parameter.
• Specify the number of states that this function has, using
ssSetNumContStates and ssSetNumDiscStates.
• Configure the block’s input ports.
This entails the following tasks.
- Specify the number of input ports that this S-function has, using
ssSetNumInputPorts
- Specify the dimensions of the input ports.
See“Dynamically Sized Block Features” on page 9-14 for more
information.
- Specify for each input port whether it has direct feedthrough, using
ssSetInputPortDirectFeedThrough
A port has direct feedthrough if the input is used in either the mdlOutputs
or mdlGetTimeOfNextVarHit functions.The direct feedthrough flag for
each input port can be set to either 1=yes or 0=no. It should be set to 1 if
the input, u, is used in the mdlOutput or mdlGetTimeOfNextVarHit routine.
Setting the direct feedthrough flag to 0 tells Simulink that u will not be
used in either of these S-function routines. Violating this will lead to
unpredictable results.

9-13
mdlInitializeSizes

• Configure the block’s output ports.

This entails the following tasks.
- Specify the number of output ports that the block has, using
ssSetNumOutputPorts
- Specify the dimensions of the output ports
See mdlSetOutputPortDimensionInfo and
ssSetOutputPortDimensionInfo for more information.
If your S-function outputs are discrete (e.g., can only take on the values, 1
and 2), then specify SS_OPTION_DISCRETE_VALUED_OUTPUT.
• Set the number of sample times (i.e., sample rates) at which the block
operates.
There are two ways of specifying sample times:
- Port-based sample times
- Block-based sample times
See “Sample Times” on page 7-16 for a complete discussion of sample time
issues.
For multi-rate S-functions, the suggested approach to setting sample times
is via the port based sample times method. When you create a multirate
S-function, care needs to be taking to verify that when slower tasks are
preempted that your S-function correctly manages data as to avoid race
conditions. When port based sample times are specified, the block cannot
inherit a constant sample time at any port.
• Set the size of the block’s work vectors, using ssSetNumRWork,
ssSetNumIWork, ssSetNumPWork, ssSetNumModes, ssSetNumNonsampledZCs
• Set the simulation options that this block implements, using ssSetOptions.
All options have the form SS_OPTION_<name>. See ssSetOptions for
information on each option. The options should be bitwise or’d together as in
ssSetOptions(S, (SS_OPTION_name1 | SS_OPTION_name2))

Dynamically Sized Block Features

You can set the parameters NumContStates, NumDiscStates, NumInputs,
NumOutputs, NumRWork, NumIWork, NumPWork, NumModes, and NumNonsampledZCs
to a fixed nonnegative integer or tell Simulink to size them dynamically:

9-14
 mdlInitializeSizes

• DYNAMICALLY_SIZED — Sets lengths of states, work vectors, and so on to

values inherited from the driving block. It sets widths to the actual input
width, according to the scalar expansion rules unless you use
mdlSetWorkWidths to set the widths.
• 0 or positive number — Sets lengths (or widths) to the specified value. The
default is 0.

Languages Ada, C, M

Example
static void mdlInitializeSizes(SimStruct *S)
{
int_T nInputPorts = 1; /* number of input ports */
int_T nOutputPorts = 1; /* number of output ports */
int_T needsInput = 1; /* direct feed through */

int_T inputPortIdx = 0;
int_T outputPortIdx = 0;

ssSetNumSFcnParams(S, 0); /* Number of expected parameters */

if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
/*
* If the the number of expected input parameters is not
* equal to the number of parameters entered in the
* dialog box, return. Simulink will generate an error
* indicating that there is aparameter mismatch.
*/
return;
}else {
mdlCheckParameters(S);

if (ssGetErrorStatus(s) != NULL)
return;
}

ssSetNumContStates( S, 0);
ssSetNumDiscStates( S, 0);

/*
* Configure the input ports. First set the number of input
* ports.
*/
if (!ssSetNumInputPorts(S, nInputPorts)) return;
/*
* Set input port dimensions for each input port index

9-15
mdlInitializeSizes

* starting at 0.
*/
if(!ssSetInputPortDimensionInfo(S, inputPortIdx,
DYNAMIC_DIMENSION)) return;
/*
* Set direct feedthrough flag (1=yes, 0=no).
*/
ssSetInputPortDirectFeedThrough(S, inputPortIdx, needsInput);

/*
* Configure the output ports. First set the number of
* output ports.
*/
if (!ssSetNumOutputPorts(S, nOutputPorts)) return;

/*
* Set output port dimensions for each output port index
* starting at 0.
*/
if(!ssSetOutputPortDimensionInfo(S,outputPortIdx,
DYNAMIC_DIMENSION)) return;

/*
* Set the number of sample times. */
ssSetNumSampleTimes(S, 1);

/*
* Set size of the work vectors.
*/
ssSetNumRWork(S, 0); /* real vector */
ssSetNumIWork(S, 0); /* integer vector */
ssSetNumPWork(S, 0); /* pointer vector */
ssSetNumModes(S, 0); /* mode vector */
ssSetNumNonsampledZCs(S, 0); /* zero crossings */

ssSetOptions(S, 0);

} /* end mdlInitializeSizes */

9-16
 mdlOutputs

Purpose 9mdlOutputs
Compute the signals that this block emits.

Syntax void mdlOutputs(SimStruct *S, int_T tid)

Arguments S
Simstruct representing an S-function block.
tid
Task id

Description Simulink invokes this required method at each simulation time step. The
method should compute the S-function’s outputs at the current time step and
store the results in the S-function’s output signal arrays.
The tid (task ID) argument specifies the task running when the mdlOutputs
routine is invoked. You can use this argument in the mdlOutports routine of a
multirate S-Function block to encapsulate task-specific blocks of code (see
“Multirate S-Function Blocks” on page 7-21).
For an example of an mdlOutputs routine that works with multiple input and
output ports, see matlabroot/simulink/src/sfun_multiport.c.

Languages A, C, M

See Also ssGetOutputPortSignal, ssGetOutputPortRealSignals,

ssGetOutputPortComplexSignal

9-17
mdlProcessParameters

Purpose 9mdlProcessParameters
Process the S-function’s parameters.

Syntax void mdlProcessParameters(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description This is an optional routine that Simulink calls after mdlCheckParameters

changes and verifies parameters. The processing is done at the top of the
simulation loop when it is safe to process the changed parameters. This routine
can only be used in a C MEX S-function.
The purpose of this routine is to process newly changed parameters. An
example is to cache parameter changes in work vectors. Simulink does not call
this routine when it is used with the Real-Time Workshop. Therefore, if you use
this routine in an S-function designed for use with the Real-Time Workshop,
you must write your S-function so that it doesn’t rely on this routine. To do this,
you must inline your S-function by using the Target Language Compiler. See
“The Target Language Compiler Reference Guide” for information on inlining
S-functions.
The synopsis is
#define MDL_PROCESS_PARAMETERS /* Change to #undef to remove function */
#if defined(MDL_PROCESS_PARAMETERS) && defined(MATLAB_MEX_FILE)
static void mdlProcessParameters(SimStruct *S)
{
}
#endif /* MDL_PROCESS_PARAMETERS */

Example This example processes a string parameter that mdlCheckParameters has

verified to be of the form '+++' (where there could be any number of '+' or '-'
characters).
#define MDL_PROCESS_PARAMETERS /* Change to #undef to remove function */
#if defined(MDL_PROCESS_PARAMETERS) && defined(MATLAB_MEX_FILE)
static void mdlProcessParameters(SimStruct *S)
{
int_T i;
char_T *plusMinusStr;
int_T nInputPorts = ssGetNumInputPorts(S);
int_T *iwork = ssGetIWork(S);
if ((plusMinusStr=(char_T*)malloc(nInputPorts+1)) == NULL) {
ssSetErrorStatus(S,"Memory allocation error in mdlStart");
return;

9-18
 mdlProcessParameters

}
if (mxGetString(SIGNS_PARAM(S),plusMinusStr,nInputPorts+1) != 0) {
free(plusMinusStr);
ssSetErrorStatus(S,"mxGetString error in mdlStart");
return;
}
for (i = 0; i < nInputPorts; i++) {
iwork[i] = plusMinusStr[i] == '+'? 1: -1;
}
free(plusMinusStr);

}
#endif /* MDL_PROCESS_PARAMETERS */

mdlProcessParameters is called from mdlStart to load the signs string prior to

the start of the simulation loop.
#define MDL_START
#if defined(MDL_START)
static void mdlStart(SimStruct *S)
{
mdlProcessParameters(S);
}
#endif /* MDL_START */

For more details on this example, see matlabroot/simulink/src/

sfun_multiport.c.

Languages Ada, C, M

See Also mdlCheckParameters

9-19
mdlRTW

Purpose 9mdlRTW
Generate code generation data.

Syntax void mdlRTW(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description This function is called when the Real-Time Workshop is generating the
model.rtw file. In this method, you can call the following functions which add
fields to the model.rtw file:
• ssWriteRTWParameters
• ssWriteRTWParamSettings
• ssWriteRTWWorkVect
• ssWriteRTWStr
• ssWriteRTWStrParam
• ssWriteRTWScalarParam
• ssWriteRTWStrVectParam
• ssWriteRTWVectParam
• ssWriteRTW2dMatParam
• ssWriteRTWMxVectParam
• ssWriteRTWMx2dMatParam

Languages C

See Also ssSetInputPortFrameData, ssSetOutputPortFrameData, ssSetErrorStatus

9-20
 mdlSetDefaultPortComplexSignals

Purpose 9mdlSetDefaultPortComplexSignals
Set the numeric type (real, complex, or inherited) of ports whose numeric type
cannot be determined from block connectivity.

Syntax void mdlSetDefaultPortComplexSignals(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this method if the block has ports whose numeric type cannot
be determined from connectivity. (This usually happens when the block is
unconnected or is part of a feedback loop.) This method must set the data type
of all ports whose data type is not set.
If the block does not implement this method and Simulink cannot determine
the data types of any of its ports, Simulink sets the data types of all the ports
to double. If the block does not implement this method and Simulink cannot
determine the data types of some, but not all, of its ports, Simulink sets the
unknown ports to the data type of the port whose data type has the largest size.

Languages C

See Also ssSetOutputPortDataType, ssSetInputPortDataType

9-21
mdlSetDefaultPortDataTypes

Purpose 9mdlSetDefaultPortDataTypes
Set the data type of ports whose data type cannot be determined from block
connectivity.

Syntax void mdlSetDefaultPortDataTypes(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this method if the block has ports whose numeric type cannot
be determined from connectivity. (This usually happens when the block is
unconnected or is part of a feedback loop.) This method must set the numeric
type of all ports whose numeric type is not set.
If the block does not implement this method and at least one port is known to
be complex, Simulink sets the unknown ports to COMPLEX_YES; otherwise, it
sets the unknown ports to COMPLEX_NO.

Languages C

See Also ssSetOutputPortComplexSignal, ssSetInputPortComplexSignal

9-22
 mdlSetDefaultPortDimensionInfo

Purpose 9mdlSetDefaultPortDimensionInfo
Set the default dimensions of the signals accepted or emitted by an S-function’s
ports.

Syntax void mdlSetDefaultPortDimensionInfo(SimStruct *S, int_T port)

Arguments S
Simstruct representing an S-function block.

Description Simulink calls this method during signal dimension propagation when a model
does not supply enough information to determine the dimensionality of signals
that can enter or leave the block represented by S. This method should set the
dimensions of any input and output ports that are dynamically sized to default
values. If S does not implement this method, Simulink set the dimensions of
dynamically sized ports for which dimension information is unavailable to
scalar, i.e., 1-D signals containing one element.

Example See matlabroot/simulink/src/sfun_matadd.c for an example of how to use

this function.

Languages C

See Also ssSetOutputPortDimensionInfo, ssSetOutputPortDimensionInfo,

ssSetErrorStatus

9-23
mdlSetInputPortComplexSignal

Purpose 9mdlSetInputPortComplexSignal
Set the numeric type (real, complex, or inherited) of the signals accepted by an
input port.

Syntax void mdlSetInputPortDataType(SimStruct *S, int_T port, CSignal_T

csig)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
csig
Numeric type of signal

Description Simulink calls this routine to set the input port signal type. The S-function
must check if the specified signal type is a valid type for the specified port. If it
is valid, the s-function must set the signal type of the specified input port.
Otherwise, it must report an error using ssSetErrorStatus. The s-function
can also set the signal type of other input and output ports with unknown
signal types. Simulink reports an error if the S-function changes the signal
type of a port whose signal type is known.
If the S-function does not implement this routine, Simulink assumes that the
S-function accepts a real or complex signal and sets the input port signal type
to the specified value.

Languages C

See Also ssSetInputPortComplexSignal, ssSetErrorStatus

9-24
 mdlSetInputPortDataType

Purpose 9mdlSetInputPortDataType
Set the data type of the signals accepted by an input port.

Syntax void mdlSetInputPortDataType (SimStruct *S, int_T port, DTypeId id)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
id
Data type id

Description Simulink calls this routine to set the data type of port. The S-function must
check if the specified data type is a valid data type for the specified port. If it is
a valid data type, it must set the data type of the input port. Otherwise, it must
report an error using ssSetErrorStatus.
The S-function can also set the data type of other input and output ports if they
are unknown. Simulink reports an error if the S-function changes the data type
of a port whose data type has been set.
If the block does not implement this routine, Simulink assumes that the block
accepts any data type and sets the input port data type to the specified value.

Languages C

See Also ssSetInputPortDataType, ssSetErrorStatus

9-25
mdlSetInputPortDimensionInfo

Purpose 9mdlSetInputPortDimensionInfo
Set the dimensions of the signals accepted by an input port.

Syntax void mdlSetInputPortDimensionInfo(SimStruct *S, int_T port,

const DimsInfo_T *dimsInfo)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
dimsInfo
Structure that specifies the signal dimensions supported by port
See ssSetInputPortDimensionInfo for a description of this structure.

Description Simulink calls this method during dimension propagation with candidate
dimensions, dimsInfo, for port. If the proposed dimensions are acceptable, this
method should go ahead and set the actual port dimensions, using
ssSetInputPortDimensionInfo. If they are unacceptable, this method should
generate an error via ssSetErrorStatus.

Note This method can set the dimensions of any other input or output port
whose dimensions derive from the dimensions of port.

By default, Simulink calls this method only if it can fully determine the
dimensionality of port from the port to which it is connected. If it cannot
completely determine the dimensionality from port connectivity, it invokes
mdlSetDefaultPortDimensionInfo. If an S-function can fully determine the
port dimensionality from partial information, the function should set the
option, SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL, in
mdlInitializeSizes, using ssSetOptions. If this option is set, Simulink
invokes mdlSetInputPortDimensionInfo even if it can only partially
determine the dimensionality of the input port from connectivity.

Languages C

9-26
 mdlSetInputPortDimensionInfo

Example See matlabroot/simulink/src/sfun_matadd.c for an example of how to use

this function.

See Also ssSetInputPortDimensionInfo, ssSetErrorStatus

9-27
mdlSetInputPortFrameData

Purpose 9mdlSetInputPortFrameData
Set frame data entering an input port.

Syntax void mdlSetInputPortFrameData(SimStruct *S, int_T port,

Frame_T frameData)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
frameData
frame data

Description This method is called with the candidate frame setting (FRAME_YES, or
FRAME_NO) for an input port. If the proposed setting is acceptable, the method
should go ahead and set the actual frame data setting using
ssSetInputPortFrameData. If the setting is unacceptable an error should
generated via ssSetErrorStatus. Note that any other dynamic frame input or
output ports whose frame data setting are implicitly defined by virtue of
knowing the frame data setting of the given port can also have their frame data
settings set via calls to ssSetInputPortFrameData and
ssSetOutputPortFrameData.

Languages C

See Also ssSetInputPortFrameData, ssSetOutputPortFrameData, ssSetErrorStatus

9-28
 mdlSetInputPortSampleTime

Purpose 9mdlSetInputPortSampleTime
Set the sample time of an input port that inherits its sample time from the port
to which it is connected.

Syntax void mdlSetInputPortSampleTime(SimStruct *S, int_T port,

real_T sampleTime, real_T offsetTime)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
sampleTime
Inherited sample time for port
offsetTime
Inherited offset time for port

Description Simulink invokes this method with the sample time that port inherits from the
port to which it is connected. If the inherited sample time is acceptable, this
method should set the sample time of port to the inherited time, using
ssSetInputPortSampleTime. If the sample time is unacceptable, this method
should generate an error via ssSetErrorStatus. Note that any other inherited
input or output ports whose sample times are implicitly defined by virtue of
knowing the sample time of the given port can also have their sample times set
via calls to ssSetInputPortSampleTime or ssSetOutputPortSampleTime.
When inherited port based sample times are specified, we are guaranteed that
the sample time will be one of the following:.

Sample Time Offset Time

Continuous 0.0 0.0

Discrete period offset

where 0.0 < period < inf and 0.0 <= offset < period. Constant, triggered,
and variable step sample times are not be propagated to S-functions with port-
based sample times.

9-29
mdlSetInputPortSampleTime

Generally mdlSetInputPortSampleTime is called once with the input port

sample time. However, there can be cases where this function will be called
more than once. This happens when the simulation engine is converting
continuous sample times to continuous but fixed in minor steps sample times.
When this occurs, the original values of the sample times specified in
mdlInitializeSizes will be restored before calling this method again.

The final sample time specified at the port may be different from (but
equivalent to) the sample time specified by this method. This occurs when:

• The model uses a fixed step solver and the port has a continuous but fixed in
minor step sample time. In this case, Simulink converts the sample time to
the fundamental sample time for the model.
• Simulink adjusts the sample time to be as numerically sound as possible. For
example, Simulink converts [0.2499999999999, 0] to [0.25, 0].

The S-function can examine the final sample times in

mdlInitializeSampleTimes.

Languages C

See Also ssSetInputPortSampleTime, ssSetOutputPortSampleTimes,

mdlInitializeSampleTimes

9-30
 mdlSetInputPortWidth

Purpose 9mdlSetInputPortWidth
Set the width of an input port that accepts 1-D (vector) signals.

Syntax void mdlSetInputPortWidth (SimStruct *S, int_T port, int_T width)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
width
Width of signal

Description This method is called with the candidate width for a dynamically sized port. If
the proposed width is acceptable, the method should go ahead and set the
actual port width using ssSetInputPortWidth. If the size is unacceptable an
error should generated via ssSetErrorStatus. Note that any other
dynamically sized input or output ports whose widths are implicitly defined by
virtue of knowing the width of the given port can also have their widths set via
calls to ssSetInputPortWidth or ssSetOutputPortWidth.

Languages C

See Also ssSetInputPortWidth, ssSetOutputPortWidth, ssSetErrorStatus

9-31
mdlSetOutputPortComplexSignal

Purpose 9mdlSetOutputPortComplexSignal
Set the numeric type (real, complex, or inherited) of the signals accepted by an
output port.

Syntax void mdlSetOutputPortDataType(SimStruct *S, int_T port, CSignal_T

csig)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
csig
Numeric type of signal

Description Simulink calls this routine to set the output port signal type. The S-function
must check if the specified signal type is a valid type for the specified port. If it
is valid, the s-function must set the signal type of the specified output port.
Otherwise, it must report an error using ssSetErrorStatus. The s-function
can also set the signal type of other input and output ports with unknown
signal types. Simulink reports an error if the S-function changes the signal
type of a port whose signal type is known.
If the S-function does not implement this routine, Simulink assumes that the
S-function accepts a real or complex signal and sets the output port signal type
to the specified value.

Languages C

See Also ssSetOutputPortComplexSignal, ssSetErrorStatus

9-32
 mdlSetOutputPortDataType

Purpose 9mdlSetOutputPortDataType
Set the data type of the signals emitted by an output port.

Syntax void mdlSetOutputPortDataType (SimStruct *S, int_T port, DTypeId id)

Arguments S
Simstruct representing an S-function block.
port
Index of an output port
id
Data type id

Description Simulink calls this routine to set the data type of port. The S-function must
check if the specified data type is a valid data type for the specified port. If it is
a valid data type, it must set the data type of port. Otherwise, it must report
an error using ssSetErrorStatus.
The S-function can also set the data type of other input and output ports if their
data types have not been set. Simulink reports an error if the S-function
changes the data type of a port whose data type has been set.
If the block does not implement this method, Simulink assumes that the block
accepts any data type and sets the input port data type to the specified value.

Languages C

See Also ssSetOutputPortDataType, ssSetErrorStatus

9-33
mdlSetOutputPortDimensionInfo

Purpose 9mdlSetOutputPortDimensionInfo
Set the dimensions of the signals accepted by an output port.

Syntax void mdlSetOutputPortDimensionInfo(SimStruct *S, int_T port, const

DimsInfo_T *dimsInfo)

Arguments S
Simstruct representing an S-function block or a Simulink model.
port
Index of a port
dimsInfo
Structure that specifies the signal dimensions supported by port
See ssSetInputPortDimensionInfo for a description of this structure.

Description Simulink calls this method with candidate dimensions, dimsInfo, for port. If
the proposed dimensions are acceptable, this method should go ahead and set
the actual port dimensions, using ssSetOutputPortDimensionInfo. If they are
unacceptable, this method should generate an error via ssSetErrorStatus.

Note This method can set the dimensions of any other input or output port
whose dimensions derive from the dimensions of port.

By default, Simulink calls this method only if it can fully determine the
dimensionality of port from the port to which it is connected. If it cannot
completely determine the dimensionality from port connectivity, it invokes
mdlSetDefaultPortDimensionInfo. If an S-function can fully determine the
port dimensionality from partial information, the function should set the
option, SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL, in
mdlInitializeSizes, using ssSetOptions. If this option is set, Simulink
invokes mdlSetOutputPortDimensionInfo even if it can only partially
determine the dimensionality of the input port from connectivity.

Languages C

Example See matlabroot/simulink/src/sfun_matadd.c for an example of how to use

this function.

9-34
 mdlSetOutputPortDimensionInfo

See Also ssSetOutputPortDimensionInfo, ssSetErrorStatus

9-35
mdlSetOutputPortSampleTime

Purpose 9mdlSetOutputPortSampleTime
Set the sample time of an output port that inherits its sample time from the
port to which it is connected.

Syntax void mdlSetOutputPortSampleTime(SimStruct *S, int_T port,

real_T sampleTime, real_T offsetTime)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
sampleTime
Inherited sample time for port
offsetTime
Inherited offset time for port

Description Simulink calls this method with the sample time that port inherits from the
port to which it is connected. If the inherited sample time is acceptable, this
method should set the sample time of port to the inherited sample time, using
ssSetOutputPortSampleTime. If the inherited sample time is unacceptable,
this method should generate an error generated via ssSetErrorStatus. Note
that this method can set the sample time of any other input or output port
whose sample time derives from the sample time of port, using
ssSetInputPortSampleTime or ssSetOutputPortSampleTime.

Normally, sample times are propagated forwards, however if sources feeding

this block have an inherited sample time, Simulink may choose to back
propagate known sample times to this block. When back propagating sample
times, we call this method in succession for all inherited output port signals.
See mdlSetInputPortSampleTime for more information about when this
method is called.

Languages C

See Also ssSetOutputPortSampleTime, ssSetErrorStatus,

ssSetInputPortSampleTime, ssSetOutputPortSampleTime,
mdlSetInputPortSampleTime

9-36
 mdlSetOutputPortWidth

Purpose 9mdlSetOutputPortWidth
Set the width of an output port that outputs 1-D (vector) signals.

Syntax void mdlSetOutputPortWidth(SimStruct *S, int_T port, int_T width)

Arguments S
Simstruct representing an S-function block.
port
Index of a port
width
Width of signal

Description This method is called with the candidate width for a dynamically sized port. If
the proposed width is acceptable, the method should go ahead and set the
actual port width using ssSetOutputPortWidth. If the size is unacceptable an
error should generated via ssSetErrorStatus. Note that any other
dynamically sized input or output ports whose widths are implicitly defined by
virtue of knowing the width of the given port can also have their widths set via
calls to ssSetInputPortWidth or ssSetOutputPortWidth.

Languages C

See Also ssSetInputPortWidth, ssSetOutputPortWidth, ssSetErrorStatus

9-37
mdlSetWorkWidths

Purpose 9mdlSetWorkWidths
Specify the sizes of the work vectors and create the runtime parameters
required by this S-function.

Syntax void mdlSetWorkWidths(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink calls this optional method to enable this S-function to set the sizes of
state and work vectors that it needs to store global data and to create runtime
parameters (see “Run-Time Parameters” on page 7-6). Simulink invokes this
method after it has determined the input port width, output port width, and
sample times of the S-function. This allows the S-function to size the state and
work vectors based on the number and sizes of inputs and outputs and/or the
number of sample times. This method specify the state and work vector sizes
via the macros ssNumContStates, ssSetNumDiscStates, ssSetNumRWork,
ssSetNumIWork, ssSetNumPWork, ssSetNumModes, and
ssSetNumNonsampledZCs.

The S-function needs to implement this method only if it does not know the
sizes of all the work vectors it requires when Simulink invokes the function’s
mdlInitializeSizes method. If this S-function implements
mdlSetWorkWidths, it should initialize the sizes of any work vectors that it
needs to DYNAMICALLY_SIZED in mdlIntializeSizes, even for those whose
exact size it knows at that point. The S-function should then specify the actual
size in mdlSetWorkWidths.

Languages Ada, C

See Also mdlIntializeSizes

9-38
 mdlStart

Purpose 9mdlStart
Initialize the state vectors of this S-function.

Syntax void mdlStart(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description Simulink invokes this optional method at the beginning of a simulation. It

should initialize the continuous and discrete states, if any, of this S-function
block. Use ssGetContStates and/or ssGetDiscStates to get the states. This
method can also perform any other initialization activities that this S-function
requires.

Languages Ada, C

See Also mdlInitializeConditions, ssGetContStates, ssGetDiscStates

9-39
mdlTerminate

Purpose 9mdlTerminate
Perform any actions required at termination of the simulation.

Syntax void mdlTerminate(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description This method should perform any actions, such as freeing memory, that must be
performed at the end of simulation or when an S-function block is destroyed
(e.g., when it is deleted from a model). The option
SS_OPTION_CALL_TERMINATE_ON_EXIT (see ssSetOptions) determines
whether Simulink invokes this method. If this option is not set, Simulink
invokes mdlTerminate at the end of simulation only if the mdlStart method of
at least one block in the model has executed during simulation. If this option is
set, Simulink always invokes the mdlTerminate method at the end of a
simulation run and whenever it destroys a block.

Languages Ada, C, M

Example Suppose your S-function allocates blocks of memory in mdlStart and saves
pointers to the blocks in a PWork vector. The following code fragment would free
this memory.
{
int i;
for (i = 0; i<ssGetNumPWork(S); i++) {
if (ssGetPWorkValue(S,i) != NULL) {
free(ssGetPWorkValue(S,i));
}
}
}

9-40
 mdlUpdate

Purpose 9mdlUpdate
Update a block’s states.

Syntax void mdlUpdate(SimStruct *S, int_T tid)

Arguments S
Simstruct representing an S-function block.
tid
Task ID

Description Simulink invokes this optional method at each major simulation time step. The
method should compute the S-function’s states at the current time step and
store the states in the S-function’s state vector. The method can also perform
any other tasks that the S-function needs to perform at each major time step.
Use this code if your S-function has one or more discrete states or does not have
direct feedthrough.
The reason for this is that most S-functions that do not have discrete states but
do have direct feedthrough do not have update functions. Therefore, Simulink
is able to eliminate the need for the extra call in these circumstances.
If your S-function needs to have its mdlUpdate routine called and it does not
satisfy either of the above two conditions, specify that it has a discrete state
using the ssSetNumDiscStates macro in the mdlInitializeSizes function.
The tid (task ID) argument specifies the task running when the mdlOutputs
routine is invoked. You can use this argument in the mdlUpdate routine of a
multirate S-Function block to encapsulate task-specific blocks of code (see
“Multirate S-Function Blocks” on page 7-21).

Example For an example, see matlabroot/simulink/src/dsfunc.c

Languages Ada, C, M

See Also mdlDerivatives, ssGetContStates, ssGetDiscStates

9-41
mdlZeroCrossings

Purpose 9mdlZeroCrossings
Update zero-crossing vector.

Syntax void mdlZeroCrossings(SimStruct *S)

Arguments S
Simstruct representing an S-function block.

Description An S-function needs to provide this optional method only if it does zero-crossing
detection. This method should update the S-function’s zero-crossing vector,
using ssGetNonsampleZCs.
You can use the optional mdlZeroCrossings routine, when your S-function has
registered the CONTINUOUS_SAMPLE_TIME and has nonsampled zero crossings
(ssGetNumNonsampledZCs(S) > 0). The mdlZeroCrossings routine is used to
provide Simulink with signals that are to be tracked for zero crossings. These
are typically:

• Continuous signals entering the S-function

• Internally generated signals that cross zero when a discontinuity would
normally occur in mdlOutputs

Thus, the zero crossing signals are used to locate the discontinuities and end
the current time step at the point of the zero crossing. To provide Simulink with
zero crossing signal(s), mdlZeroCrossings updates the ssGetNonsampleZCs(S)
vector.

Example See matlabroot/simulink/src/sfun_zc.c.

Languages C

See Also mdlInitializeSizes, ssGetNonsampleZCs

9-42
 10

SimStruct Functions
Introduction . . . . . . . . . . . . . . . . . . . . 10-2
Language Support . . . . . . . . . . . . . . . . . . 10-2
The SimStruct . . . . . . . . . . . . . . . . . . . . 10-2

SimStruct Macros and Functions Listed by Usage . . . 10-3

Miscellaneous . . . . . . . . . . . . . . . . . . . . 10-3
Error Handling and Status . . . . . . . . . . . . . . . 10-3
I/O Port . . . . . . . . . . . . . . . . . . . . . . 10-4
Dialog Box Parameters . . . . . . . . . . . . . . . . 10-6
Run-Time Parameters . . . . . . . . . . . . . . . . 10-7
Sample Time . . . . . . . . . . . . . . . . . . . . 10-8
State and Work Vector . . . . . . . . . . . . . . . . 10-9
Simulation Information . . . . . . . . . . . . . . . 10-12
Function Call . . . . . . . . . . . . . . . . . . . 10-12
Data Type . . . . . . . . . . . . . . . . . . . . 10-13
Real-Time Workshop . . . . . . . . . . . . . . . . 10-13

Macro Reference . . . . . . . . . . . . . . . . . 10-15

10 SimStruct Functions

Introduction
Simulink provides a set of functions for accessing the fields of an S-function’s
simulation data structure (SimStruct). S-function callback methods use these
functions to store and retrieve information about an S-function.
This reference describes the syntax and usage of each SimStruct function. The
descriptions appear alphabetically by name to facilitate location of a particular
macro. This section also provides listings of functions by usage to speed
location of macros for specific purposes, such as implementing data type
support.

Language Support
Some SimStruct functions are available only in some of the languages
supported by Simulink.The reference page for each SimStruct function lists the
languages in which it is available. If the SimStruct function is available in C,
the reference page gives its C syntax. Otherwise, it gives its syntax in the
language in which it is available.

Note Most SimStruct functions available in C are implemented as C macros.

The SimStruct
The file matlabroot/simulink/include/simstruc.h is a C language header
file that defines the Simulink data structure and the SimStruct access macros.
It encapsulates all the data relating to the model or S-function, including block
parameters and outputs.
There is one SimStruct data structure allocated for the Simulink model. Each
S-function in the model has its own SimStruct associated with it. The
organization of these SimStructs is much like a directory tree. The SimStruct
associated with the model is the root SimStruct. The SimStructs associated
with the S-functions are the child SimStructs.

10-2
 SimStruct Macros and Functions Listed by Usage

SimStruct Macros and Functions Listed by Usage

This section groups SimStruct macros by usage.

Miscellaneous

Macro Description

ssGetModelName Get the name of an S-function block or

model containing the S-function.
ssGetParentSS Get the parent of an S-function.
ssGetPath Get the path of an S-function or the model
containing the S-function.
ssGetRootSS Return the root (model) SimStruct.
ssSetOptions Set various simulation options.
ssSetPlacementGroup Specify the execution order of a sink or
source S-function.

Error Handling and Status

Macros Description

ssGetSimMode Determine context in which an S-function is

being invoked: normal simulation,
external-mode simulation, model editor, etc.
ssGetSolverName Get name of the solver being used for the
simulation.
ssIsVariableStepSolver Determine if the current solver is a variable
step solver.
ssPrintf Print a variable-content msg.

10-3
10 SimStruct Functions

Macros Description

ssSetErrorStatus Report errors.

ssWarning Display a warning message.

I/O Port

Macro Description

ssGetInputPortBufferDstPort Determine the output port that is

overwriting an input port’s memory
buffer.
ssGetInputPortConnected Determine if an S-function block port
is connected to a nonvirtual block.
ssGetInputPortDirectFeedThrough Determine if an input port has direct
feedthrough.
ssGetInputPortOffsetTime Determine the offset time of an input
port.
ssGetInputPortRealSignalPtrs Access the signal elements connected
to an input port.
ssGetInputPortSampleTime Determine the sample time of an
input port.
ssGetInputPortSignalPtrs Get pointers to input signal elements
of type other than double.
ssGetInputPortWidth Determine the width of an input port.
ssGetNumInputPorts Determine how many input ports a
block has.
ssGetNumOutputPorts Can be used in any routine (except
mdlInitializeSizes) to determine
how many output ports you have set.

10-4
 SimStruct Macros and Functions Listed by Usage

Macro Description

ssGetOutputPortOffsetTime Determine the offset time of an

output port.
ssGetOutputPortRealSignal Access the elements of a signal
connected to an output port.
ssGetOutputPortSample Determine the sample time of an
Time output port.
ssGetOutputPortWidth Determine the width of an output
port.
ssSetInputPortDirectFeedThrough Specify that an input port is a direct
feedthrough port.
ssSetInputPortOffsetTime Specify the sample time offset for an
input port.
ssSetInputPortOver Specify whether an input port is
Writable overwritable by an output port.
ssSetInputPortReusable Specify whether an input port’s
memory buffer can be reused by other
signals in the model.
ssSetInputPortSampleTime Set the sample time of an input port.
ssSetInputPortWidth Set width of an input port.
ssSetNumInputPorts Set the number of input ports on an
S-function block.
ssSetNumOutputPorts Specify the number of output ports on
an S-function block.
ssSetOutputPortComplexSignal Specify the numeric type (real or
complex) of this port.
ssSetOutputPortDataType Specify the data type of an output
port.

10-5
10 SimStruct Functions

Macro Description

ssSetOutputPortOffsetTime Specify the sample time offset value

of an output port.
ssSetOutputPortReusable Specify whether an output port’s
memory can be reused.
ssSetOutputPortSample Specify the sample time of an output
Time port.
ssSetOutputPortWidth Specify width of a 1-D (vector) output
port.
ssSetOutputPortDimensionInfo Specify the dimensions of an output
port.
ssSetOutputPortMatrixDimensions Specify the dimensions of a 2-D
(matrix) signal.
ssSetOutputPortVectorDimension Specify the dimension of a 1-2
(vector) signal.

Dialog Box Parameters

These macros enable an S-function to access and set the tunability of
parameters that a user specifies in the S-function’s dialog box.

Macro Description

ssGetDTypeIdFromMxArray Returns the Simulink data type of a dialog

parameter.
ssGetNumSFcnParams Get the number of parameters that an
S-function expects.
ssGetSFcnParam Get a parameter entered by a user in the
S-function block dialog box.
ssSetNumSFcnParams Set the number of parameters that an
S-function expects.

10-6
 SimStruct Macros and Functions Listed by Usage

Macro Description

ssGetSFcnParamsCount Get the actual number of parameters

specified by the user.
ssSetSFcnParamNotTunable Obsolete.
ssSetSFcnParamTunable Specify the tunability of a dialog box
parameter.

Run-Time Parameters
These macros allow you to create, update, and access run-time parameters
corresponding to a block’s dialog parameters.

Macro Description

ssGetNumRunTimeParams Gets the number of run-time parameters

created by this S-function.
ssGetRunTimeParamInfo Gets attributes of a specified run-time
parameter.
ssRegAllTunableParamsAsR Register all tunable dialog parameters as
unTimeParams run-time parameters.
ssSetNumRunTimeParams Specify the number of run-time parameters
to be created by this S-function.
ssSetRunTimeParamInfo Specify attributes of a specified run-time
parameter.
ssUpdateAllTunableParams Update all run-time parameters
AsRunTimeParams corresponding to tunable dialog
parameters.
ssUpdateRunTimeParamData Update the value of a specified run-time
parameter.
ssUpdateRunTimeParamInfo Update the attributes of a specified
run-time from the attributes of the
corresponding dialog parameters.

10-7
10 SimStruct Functions

Sample Time

Macro Description

ssGetTNext Get the time of the next sample hit in a

discrete S-function with a variable sample
time.
ssGetNumSampleTimes Get the number of sample times an
S-function has.
ssIsContinuousTask Determine if a specified rate is the
continuous rate.
ssIsSampleHit Determine the sample rate at which an
S-function is operating.
ssIsSpecialSampleHit Determine if the current sample time hits
two specified rates.
ssSetNumSampleTimes Set the number of sample times an
S-function has.
ssSetOffsetTime Specify the offset of a sample time.
ssSetSampleTime Specify a sample time for an S-function.
ssSetTNext Specify time of next sample hit in an
S-function.

10-8
 SimStruct Macros and Functions Listed by Usage

State and Work Vector

Macro Description

ssGetContStates Get an S-function’s continuous states.

ssGetDiscStates Get an S-function’s discrete states.
ssGetDWork Get a DWork vector.
ssGetDWorkComplexSignal Determine whether the elements of a data
type work vector are real or complex
numbers.
ssGetDWorkDataType Get the data type of a data type work
vector.
ssGetDWorkName Get the name of a data type work vector.
ssGetDWorkUsedAsDState Determine whether a data type work vector
is used as a discrete state vector.
ssGetDWorkWidth Get the size of a data type work vector.
ssGetdX Get the derivatives of the continuous states
of an S-function.
ssGetIWork Get an S-function’s integer-valued (int_T)
work vector.
ssGetModeVector Get an S-function’s mode work vector.
ssGetNonsampledZCs Get an S-function’s zero-crossing signals
vector.
ssGetNumContStates Determine the number of continuous states
that an S-function has.
ssGetNumDiscStates Determine the number of discrete states
that an S-function has.
ssGetNumDWork Get the number of data type work vectors
used by a block

10-9
10 SimStruct Functions

Macro Description

ssGetNumIWork Get the size of an S-function’s integer work

vector.
ssGetNumModes Determine the size of an S-function’s mode
vector.
ssGetNumNonsampledZCs Determine the number of nonsampled zero
crossings that an S-function detects.
ssGetNumPWork Determine the size of an S-function’s
pointer work vector.
ssGetNumRWork Determine the size of an S-function’s
real-valued (real_T) work vector.
ssGetPWork Get an S-function’s pointer (void *) work
vector.
ssGetRealDiscStates Get the real (real_T) values of an
S-function’s discrete state vector.
ssGetRWork Get an S-function’s real-valued (real_T)
work vector.
ssSetDWorkComplexSignal Specify whether the elements of a data type
work vector are real or complex.
ssSetDWorkDataType Specify the data type of a data type work
vector.
ssSetDWorkName Specify the name of a data type work
vector.
ssSetDWorkUsedAsDState Specify that a data type work vector is used
as a discrete state vector.
ssSetDWorkWidth Specify the width of a data type work
vector.
ssSetNumContStates Specify the number of continuous states
that an S-function has.

10-10
 SimStruct Macros and Functions Listed by Usage

Macro Description

ssSetNumDiscStates Specify the number of discrete states a that

an S-function has.
ssSetNumDWork Specify the number of data type work
vectors used by a block.
ssSetNumIWork Specify the size of an S-function’s integer
(int_T) work vector.
ssSetNumModes Specify the number of operating modes that
an S-function has.
ssSetNumNonsampledZCs Specify the number of zero crossings that
an S-function detects.
ssSetNumPWork Specify the size of an S-function’s pointer
(void *) work vector.
ssSetNumRWork Specify the size of an S-function’s real
(real_T) work vector.

10-11
10 SimStruct Functions

Simulation Information

Macro Description

ssGetT Get the current base simulation time.

ssGetTaskTime Get the current time for a task.
ssGetTFinal Get the end time of the current simulation.
ssGetTStart Get the start time of the current
simulation.
ssIsMajorTimeStep Determine if the current time step is a
major time step.
ssIsMinorTimeStep Determine if the current time step is a
minor time step.
ssSetSolverNeedsReset Ask Simulink to reset the solver.
ssSetStopRequested Ask Simulink to terminate the simulation
at the end of the current time step.

Function Call

Macro Description

ssCallSystemWithTid Execute a function-call subsystem

connected to an S-function.
ssSetCallSystemOutput Specify that an output port element issues
a function call.

10-12
 SimStruct Macros and Functions Listed by Usage

Data Type

Macro Description

ssGetDataTypeId Get the id for a data type.

ssGetDataTypeName Get a data type’s name.
ssGetDataTypeSize Get a data type’s size.
ssGetDataTypeZero Get the zero representation of a data type.
ssGetInputPortDataType Get the data type of an input port.
ssGetNumDataTypes Get the number of data types defined by an
S-function or the model.
ssGetOutputPortDataType Get the data type of an output port.
ssGetOutputPortSignal Get an output signal of any type except
double.

ssRegisterDataType Register a data type.

ssSetDataTypeSize Specify the size of a data type.
ssSetDataTypeZero Specify the zero representation of a data
type.
ssSetInputPortDataType Specify the data type of signals accepted by
an input port.

Real-Time Workshop

Macro Description

ssWriteRTWParameter Write tunable parameters to the

S-function’s model.rtw file.
ssWriteRTWParamSettings Write settings for the S-function’s
parameters to the model.rtw file.

10-13
10 SimStruct Functions

Macro Description

ssWriteRTWWorkVect Write the S-function’s work vectors to the

model.rtw file.

ssWriteRTWStr Write a string to the S-function’s model.rtw

file.
ssWriteRTWStrParam Write a string parameter to the S-function’s
model.rtw file.

ssWriteRTWScalarParam Write a scalar parameter to the S-function’s

model.rtw file.

ssWriteRTWStrVectParam Write a string vector parameter to the

S-function’s model.rtw file
ssWriteRTWVectParam Write a Simulink vector parameter to the
S-function’s model.rtw file.
ssWriteRTW2dMatParam Write a Simulink matrix parameter to the
S-function’s model.rtw file.
ssWriteRTWMxVectParam Write a MATLAB vector parameter to the
S-function’s model.rtw file.
ssWriteRTWMx2dMatParam Write a MATLAB matrix parameter to the
S-function’s model.rtw file.

10-14
 Macro Reference

Macro Reference
This section contains descriptions of each SimStruct macro.

10-15
ssCallExternalModeFcn

Purpose 10ssCallExternalModeFcn
Invoke the external mode function for an S-function.

Syntax void ssCallExternalModeFcn(SimStruct *S, SFunExtModeFcn *fcn)

Arguments S
SimStruct representing an S-function block or a Simulink model.
fcn
external mode function

Description Specifies the external mode function for S.

Languages C

See Also ssSetExternalModeFcn

10-16
 ssCallSystemWithTid

Purpose 10ssCallSystemWithTid
Specify that an output port is issuing a function call.

Syntax ssCallSystemWithTid(SimStruct *S, port_index, tid)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port_index
Index of port that is issuing the function call
tid
Task ID.

Description Use in mdlOutputs to execute a function-call subsystem connected to the

S-function. The invoking syntax is:
if (!ssCallSystemWithTid(S,index, tid)) {
/* Error occurred which will be reported by Simulink */
return;
}

Languages C

See Also ssSetCallSystemOutput

10-17
ssGetAbsTol

Purpose 10ssGetAbsTol
Get the absolute tolerances used by the model’s variable step solver.

Syntax real_T *ssGetAbsTol(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Use in mdlStart to get the absolute tolerances used by the variable step solver
for this simulation. Returns a pointer to an array that contains the tolerance
for each continuous state.

Note Absolute tolerances are not allocated for fixed step solvers. Therefore,
you should not invoke this macro until you have verified that the simulation is
using a variable step solver, using ssIsVariableStepSolver.

Languages C, C++

Example {
int isVarSolver = ssIsVariableStepSolver(S);

if (isVarSolver) {
real_T *absTol = ssGetAbsTol(S);
int nCStates = ssGetNumContStates(S);

absTol[0] = whatever_value;
...
absTol[nCStates-1] = whatever_value;
}
}

See Also ssGetStateAbsTol, ssIsVariableStepSolver

10-18
 ssGetBlockReduction

Purpose 10ssGetBlockReduction
Determine whether a block has requested block reduction before the
simulation has begun and whether it has actually been reduced after the
simulation loop has begun.

Syntax unsigned int_T ssGetBlockReduction(SimStruct *S)

Arguments S
SimStruct representing an S-function block

Description The result of this function depends on when it is invoked. When invoked before
the simulation loop has started, i.e., in mdlSetWorkWidths or earlier, this
macro returns TRUE if the block has previously requested that it be reduced.
When invoked after the simulation loop has begun, this macro returns TRUE
if the block has actually been reduced, i.e., eliminated from the list of blocks to
be executed during the simulation loop.

Note If a block has been reduced, the only callback method invoked for the
block after the simulation loop has begun is the block’s mdlTerminate method.
Further, Simulink invokes the mdlTerminate method only if the block has set
its SS_OPTION_CALL_TERMINATE_AT_EXIT option, using ssSetOption. Thus, if
your block needs to determine whether it has actually been reduced, it must
set the SS_OPTION_CALL_TERMINATE_AT_EXIT option before the simulation
loop has begun and invoke ssGetBlockReduction in its mdlTerminate
method.

Languages C

See Also ssSetBlockReduction

10-19
ssGetContStateAddress

Purpose 10ssGetContStateAddress
Get the address of a block’s continuous states.

Ada Syntax ssGetContStateAddress(S : in SimStruct) return System.Address

Arguments S
SimStruct representing an S-function block.

Description Can be used in the simulation loop, mdlInitializeConditions, or mdlStart

routines to get the address of the S-function’s continuous state vector. This
vector has length ssGetNumContStates(S). Typically, this vector is initialized
in mdlInitializeConditions and used in mdlOutputs.

Languages Ada

See Also ssGetNumContStates, ssGetRealDiscStates, ssGetdX,

mdlInitializeConditions, mdlStart

10-20
 ssGetContStates

Purpose 10ssGetContStates
Get a block’s continuous states.

Syntax real_T *ssGetContStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Can be used in the simulation loop, mdlInitializeConditions, or mdlStart

routines to get the real_T continuous state vector. This vector has length
ssGetNumContStates(S). Typically, this vector is initialized in
mdlInitializeConditions and used in mdlOutputs.

Languages C

See Also ssGetNumContStates, ssGetRealDiscStates, ssGetdX,

mdlInitializeConditions, mdlStart

10-21
ssGetDataTypeName

Purpose 10ssGetDataTypeName
Get the name of a data type.

Syntax char *ssGetDataTypeName(SimStruct *S, DTypeId id)

Arguments S
SimStruct representing an S-function block.
id
ID of data type

Description Returns the name of the data type specified by id, if id is valid. Otherwise, this
macro returns NULL and reports an error. Because this macro reports any error
that occurs, you do not need to use ssSetErrorStatus to report the error.

Example The following example gets the name of a custom data type.
const char *dtypeName = ssGetDataName(S, id);
if(dtypeName == NULL) return;

Languages C

See Also ssRegisterDataType

10-22
 ssGetDataTypeId

Purpose 10ssGetDataTypeId
Get the id of a data type.

Syntax DTypeID ssGetDataTypeId(SimStruct *S, char *name)

Arguments S
SimStruct representing an S-function block.
name
Name of data type

Description Returns the id of the data type specified by name, if name is a registered type
name. Otherwise, this macro returns INVALID_DTYPE_IDL and reports an
error. Because this macro reports any error that occurs, you do not need to use
ssSetErrorStatus to report the error.

Languages C

Example The following example gets the id of the data type named Color.
int_T id = ssGetDataTypeId (S, “Color”);
if(id == INVALID_DTYPE_ID) return;

See Also ssRegisterDataType

10-23
ssGetDataTypeSize

Purpose 10ssGetDataTypeSize
Get the size of a custom data type.

Syntax GetDataTypeSize(SimStruct *S, DTypeId id)

Arguments S
SimStruct representing an S-function block.
id
ID of data type

Description Returns the size of the data type specified by id, if id is valid and the data types
size has been set. Otherwise, this macro returns INVALID_DTYPE_SIZE and
reports an error.

Note Because this macro reports any error that occurs when it is invoked,
you do not need to use ssSetErrorStatus to report the error.

Languages C

Example The following example gets the size of the int16 data type.
int_T size = ssGetDataTypeSize(S, SS_INT16);
if(size == INVALID_DTYPE_SIZE) return;

See Also ssSetDataTypeSize

10-24
 ssGetDataTypeZero

Purpose 10ssGetDataTypeZero
Get the zero representation of a data type.

Syntax void* ssGetDataTypeZero(SimStruct *S, DTypeId id)

Arguments S
SimStruct representing an S-function block.
id
ID of data type

Description Returns a pointer to the zero representation of the data type specified by id, if
id is valid and the data type’s size has been set. Otherwise, this macro returns
NULL and reports an error. Because this macro reports any error that occurs,
you do not need to use ssSetErrorStatus to report the error.

Languages C

Example The following example gets the zero representation of a custom data type.
const void *myZero = ssGetDataTypeZero(S, id);
if(myZero == NULL) return;

See Also ssRegisterDataType, ssSetDataTypeSize, ssSetDataTypeZero

10-25
ssGetDiscStates

Purpose 10ssGetDiscStates
Get a block’s discrete states.

Syntax real_T *ssGetDiscStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns a block’s discrete state vector has an array of real_T elements of
length ssGetNumDiscStates(S). Typically, the state vector is initialized in
mdlInitializeConditions, updated in mdlUpdate, and used in mdlOutputs.
You can use this macro in the simulation loop, mdlInitializeConditions, or
mdlStart routines.

Languages C

See Also ssGetNumDiscStates, mdlInitializeConditions, mdlUpdate, mdlOutputs,

mdlStart

10-26
 ssGetDTypeIdFromMxArray

Purpose 10ssGetDTypeIdFromMxArray
Get the data type of an S-function parameter.

Syntax DTypeId ssGetDTypeIdFromMxArray(const mxArray *m)

Arguments m
MATLAB array representing the parameter

Description Returns the data type of an S-function parameter represented by a MATLAB

array. This macro returns an enumerated type representing the data type. The
enumerated type, DTypeId, is defined in simstruc.h. The following table shows
the equivalency of Simulink, MATLAB, and C data types.

Simulink Data Type MATLAB DATA TYPE

DtypeId mxClassID C- Data Type

SS_DOUBLE mxDOUBLE_CLASS real_T

SS_SINGLE mxSINGLE_CLASS real32_T

SS_INT8 mxINT8_CLASS int8_T

SS_UINT8 mxUINT8_CLASS uint8_T

SS_INT16 mxINT16_CLASS int16_T

SS_UINT16 mxUINT16_CLASS uint16_T

SS_INT32 mxINT32_CLASS int32_T

SS_UINT32 mxUINT32_CLASS uint32_T

SS_BOOLEAN mxUINT8_CLASS+ logical boolean_T

ssGetDTypeIdFromMxArray returns INVALID_DTYPE_ID if the mxClassId does

not map to any built-in Simulink data type id. For example, if mxId ==
mxSTRUCT_CLASS, the return value is INVALID_DTYPE_ID. Otherwise the return
value is one of the enum values in BuiltInDTypeId. For example if mxId ==
mxUINT16_CLASS, the return value is SS_UINT16.

10-27
ssGetDTypeIdFromMxArray

Note Use ssGetSFcnParam to get the array representing the parameter.

Example See the example in matlabroot/simulink/src/sfun_dtype_param.c to learn

how to use a data typed parameters in an S-function.

Languages C

See Also ssGetSFcnParam

10-28
 ssGetDWork

Purpose 10ssGetDWork
Get a DWork vector.

Syntax void *ssGetDWork(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Description Returns a pointer to the specified vector

Languages C, C++

See Also ssSetNumDWork

10-29
ssGetDWorkComplexSignal

Purpose 10ssGetDWorkComplexSignal
Determine whether the elements of a data type work vector are real or complex
numbers.

Syntax CSignal_T ssGetDWorkComplexSignal(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Description Returns COMPLEX_YES if the specified vector contains complex numbers;

otherwise, COMPLEX_NO

Languages C, C++

See Also ssSetDWorkComplexSignal

10-30
 ssGetDWorkDataType

Purpose 10ssGetDWorkDataType
Get the data type of a data type work vector.

Syntax DTypeId ssGetDWorkDataType(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Description Returns the data type of the specified data type work vectoer.

Languages C, C++

See Also ssSetDWorkDataType

10-31
ssGetDWorkName

Purpose 10ssGetDWorkName
Get the name of a data type work vector.

Syntax char_T *ssSetDWorkName(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
name
Index of the work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Description Returns the name of the specified data type work vector.

Languages C, C++

See Also ssSetDWorkName

10-32
 ssGetDWorkUsedAsDState

Purpose 10ssGetDWorkUsedAsDState
Determine whether a data type work vector is used as a discrete state vector.

Syntax int_T ssGetDWorkUsedAsDState(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Description Returns SS_DWORK_USED_AS_DSTATE if this vector is used to store a block’s

discrete states.

Languages C, C++

See Also ssSetDWorkUsedAsDState

10-33
ssGetDWorkWidth

Purpose 10ssGetDWorkWidth
Get the size of a data type work vector.

Syntax int_T ssGetDWorkWidth(SimStruct *S, int_T vector)

Arguments S
SimStruct representing an S-function block.
vector
Index of a work vector, where the index is one of 0, 1, 2, ... ssGetNumDWork(S)

Description Returns the number of elements in the specified work vector.

Languages C, C++

See Also ssSetDWorkWidth

10-34
 ssGetdX

Purpose 10ssGetdX
Get the derivatives of a block’s continuous states.

Syntax ssGetContStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Use in mdlDerivatives to get the derivatives of a block’s continuous states.

This macro returns a vector that has length ssGetNumContStates(S).

Languages C

See Also ssGetNumContStates, ssGetContStates

10-35
ssGetErrorStatus

Purpose 10ssGetErrorStatus
Get a string that identifies the last error.

C Syntax const char_T *ssGetContStates(SimStruct *S)

Ada Syntax const char_T *ssGetContStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns a string that identifies the last error.

Languages Ada, C

See Also ssSetErrorString

10-36
 ssGetInputPortBufferDstPort

Purpose 10ssGetInputPortBufferDstPort
Determine the output port that is sharing this input port’s buffer.

Syntax ssGetInputPortBufferDstPort(SimStruct *S, int_T inputPortIdx)

Arguments S
SimStruct representing an S-function block.
inputPortIdx
Index of port overwritten by an output port.

Description Use in any run-time S-function callback routine to determine the output port
that is overwriting the specified input port. This can be used when you have
specified the following:

• The input port and some output port on an S-Function are not test points
(ssSetInputPortTestPoint and ssSetOutputPortTestPoint)
• The input port is overwritable (ssSetInputPortOverWritable)

If you have this set of conditions, Simulink may use the same memory buffer
for an input port and an output port. Simulink determines which ports share
memory buffers. Use this function any time after model initialization to get the
index of the output port that reuses the specified input port’s buffer. If none of
the S-function’s output ports reuse this input port buffer, this macro returns
INVALID_PORT_IDX (= -1).

Languages C

See Also ssSetNumInputPorts, ssSetInputPOrtOverWritable

10-37
ssGetInputPortConnected

Purpose 10ssGetInputPortConnected
Determine whether a port is connected to a nonvirtual block.

Syntax int_T ssGetInputPortConnected(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Port whose connection status is needed.

Description Returns true if the specified port on the block represented by S is connected to
a nonvirtual block. Can be invoked anywhere except in mdlInitializeSizes or
mdlCheckParameters. The S-function must have previously set the number of
input ports in mdlInitializeSizes, using ssSetNumInputPorts.

Languages C

See Also ssSetNumInputPorts

10-38
 ssGetInputPortComplexSignal

Purpose 10ssGetInputPortComplexSignal
Get the numeric type (complex or real) of an input port.

Syntax DTypeId ssGetInputPortDataType(SimStruct *S,input_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns the numeric type of port:.

Languages C

See Also ssSetInputPortComplexSignal

10-39
ssGetInputPortDataType

Purpose 10ssGetInputPortDataType
Get the data type of an input port.

C Syntax DTypeId ssGetInputPortDataType(SimStruct *S,input_T port)

Ada Syntax function ssGetInputPortDataType(S : in SimStruct; port : in Integer

:= 0) return Integer;

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port

Description Returns the data type of the input port specified by port.

Languages Ada, C

See Also ssSetInputPortDataType

10-40
 ssGetInputPortDimensionInfo

Purpose 10ssGetInputPortDimensionInfo
Specify information about the dimensionality of an input port.

Syntax DimsInfo_T *ssGetInputPortDimensionInfo(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Gets the dimension information for port.

Languages C, C++

See Also ssSetInputPortDimensionInfo

10-41
ssGetInputPortDimensions

Purpose 10ssGetInputPortDimensions
Get the dimensions of the signal accepted by an input port.

Syntax int_T *ssGetInputPortDimensions(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns an array of integers that specifies the dimensions of the signal
accepted by port, e.g., [4 2] for a 4-by-2 matrix array. The size of the
dimensions array is equal to the number of signal dimensions accepted by the
port, e.g., 1 for a vector signal or 2 for a matrix signal.

Languages C

See Also ssGetInputPortNumDimensions

10-42
 ssGetInputPortDirectFeedThrough

Purpose 10ssGetInputPortDirectFeedThrough
Determine whether a port has direct feedthrough.

C Syntax int_T ssGetInputPortDirectFeedThrough(SimStruct *S, int_T port)

Ada Syntax function ssGetInputPortDirectFeedThrough(S : in SimStruct;

port : in Integer := 0) return Boolean;

Arguments S
SimStruct representing an S-function block.
port
Index of port whose direct feedthrough property is required.

Description Use in any routine (except mdlInitializeSizes) to determine if an input port

has direct feedthrough.

Languages Ada, C

See Also ssSetInputPortDirectFeedThrough

10-43
ssGetInputPortFrameData

Purpose 10ssGetInputPortFrameData
Determine if a port accepts signal frames.

Syntax int_T ssGetInputPortFrameData(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns one of the following

• -1
Port accepts either frame or unframed input.
•0
Port accepts unframed input only.
•1
Port accepts frame input only.

Languages C

See Also ssSetInputPortFrameData, mdlSetInputPortFrameData

10-44
 ssGetInputPortNumDimensions

Purpose 10ssGetInputPortNumDimensions
Get the dimensionality of the signals accepted by an input port.

Syntax int_T ssGetInputPortNumDimensions(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns the number of dimensions of port or DYNAMICALLY_SIZED, if the number of

dimensions is unknown.

Languages C

See Also ssGetInputPortDimensions

10-45
ssGetInputPortOffsetTime

Purpose 10ssGetInputPortOffsetTime
Get the offset time of an input port.

Syntax ssGetInputPortOffsetTime(SimStruct *S,inputPortIdx)

Arguments S
SimStruct representing an S-function block.
inputPortIdx
Index of port whose offset time is required.

Description Use in any routine (except mdlInitializeSizes) to determine the offset time
of an input port. This should only be used if you have specified the sample times
as port-based.

Languages C

See Also ssSetInputPortOffsetTime, ssGetInputPortSampleTime

10-46
 ssGetInputPortOverWritable

Purpose 10ssGetInputPortOverWritable
Determine whether an input port can be overwritten.

C Syntax int_T ssGetInputPortOverWritable(SimStruct *S, int_T port)

Ada Syntax function ssGetInputPortOverWritable(S : in SimStruct; port : in

Integer := 0) return Boolean;

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the input port whose overwritability is being set.

Description Returns true if input port can be overwritten.

Languages Ada, C

See Also ssSetInputPortOverWritable

10-47
ssGetInputPortRealSignal

Purpose 10ssGetInputPortRealSignal
Get the address of a real, contiguous signal entering an input port.

Syntax const real_T *ssGetInputPortRealSignal(SimStruct *S, inputPortIdx)

Arguments S
SimStruct representing an S-function block.
inputPortIdx
Index of port whose sample time is required.

Description Returns the address of a real signal on the specified input port. A method
should use this macro only if the input signal is known to be real and
mdlIntializeSizes has specified that the elements of the input signal be
contiguous, using ssSetInputPortRequiredContiguous.

Languages C, C++

Example The following code demonstrates the use of ssGetInputPortRealSignal.

nInputPorts = ssGetNumInputPorts(S);
for (i = 0; i < nInputPorts; i++) {
int_T nu = ssGetInputPortWidth(S,i);

if ( ssGetInputPortRequiredContiguous(S,i) ) {

const real_T *u = ssGetInputPortRealSignal(S,i);

UseInputVectorInSomeFunction(u, nu);

} else {

InputPtrsType u = ssGetInputPortSignalPtrs(S,i);
for (j = 0; j < nu; j++) {
UseInputInSomeFunction(*u[j]);
}
}
}

See Also ssSetInputPortRequiredContiguous, ssGetInputPortSignal,

mdlInitializeSizes

10-48
 ssGetInputPortRealSignalPtrs

Purpose 10ssGetInputPortRealSignalPtrs
Get pointers to signals of type double connected to an input port.

Syntax InputRealPtrsType ssGetInputPortRealSignalPtrs(SimStruct *S,

int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of port whose signal is required.

Description Returns pointers to the elements of a signal of type double connected to port.
The input port index starts at 0 and ends at the number of input ports minus
1. This macro returns a pointer to an array of pointers to the real_T input
signal elements. The length of the array of pointers is equal to the width of the
input port.

Languages C

Example The following example read all input port signals.

int_T i,j;
int_T nInputPorts = ssGetNumInputPorts(S);
for (i = 0; i < nInputPorts; i++) {
InputRealPtrsType uPtrs =
ssGetInputPortRealSignal(S,i);
int_T nu = ssGetInputPortWidth(S,i);
for (j = 0; j < nu; j++) {
SomeFunctionToUseInputSignalElement(*uPtrs
[j]);
}
}

See Also ssGetInputPortWidth, ssGetInputPortDataType,

ssGetInputPortSignalPtrs

10-49
ssGetInputPortRequiredContiguous

Purpose 10ssGetInputPortRequiredContiguous
Determine whether the signal elements entering a port must be contiguous.

Syntax int_T ssSetInputPortRequiredContiguous(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port

Description Returns true if the signal elements entering the specified port must occupy
contiguous areas of memory. If the elements are contiguous, a method can
access the elements of the signal simply by incrementing the signal pointer
returned by ssGetInputPortSignal.

Note The default setting for this flag is false. Hence, the default method for
accessing the input signals is ssGetInputSignalPtrs.

Languages C, C++

See Also ssSetInputPortRequiredContiguous, ssGetInputPortSignal,

ssGetInputPortSignalPtrs

10-50
 ssGetInputPortReusable

Purpose 10ssGetInputPortReusable
Determine whether memory allocated to input port is reusable.

Syntax int_T ssGetInputPortReusable(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port

Description Returns TRUE if input port memory buffer can be reused by other signals in
the model.

Languages C, C++

See Also ssSetInputPortReusable

10-51
ssGetInputPortSampleTime

Purpose 10ssGetInputPortSampleTime
Get the sample time of an input port.

Syntax ssGetInputPortSampleTime(SimStruct *S, inputPortIdx)

Arguments S
SimStruct representing an S-function block.
inputPortIdx
Index of port whose sample time is required.

Description Use in any routine (except mdlInitializeSizes) to determine the sample time
of an input port. You should use this macro only if you have specified the
sample times as port-based.

Languages C

See Also ssSetInputPortSampleTime, ssGetInputPortOffsetTime

10-52
 ssGetInputPortSampleTimeIndex

Purpose 10ssGetInputPortSampleTimeIndex
Get the sample time index of an input port.

Syntax int_T ssGetInputPortSampleTimeIndex(SimStruct *S,

int_T inputPortIdx)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port whose sample time index is being set.

Description Returns the index of the sample time for the port.

Languages C, C++

See Also ssSetInputPortSampleTimeIndex

10-53
ssGetInputPortSignal

Purpose 10ssGetInputPortSignal
Get the address of a contiguous signal entering an input port.

Syntax const void* ssGetInputPortSignal(SimStruct *S, inputPortIdx)

Arguments S
SimStruct representing an S-function block.
inputPortIdx
Index of port whose sample time is required.

Description Returns the address of the specified input port. A method should use this
macro only if mdlIntializeSizes has specified that the elements of the input
signal be contiguous, using ssSetInputPortRequiredContiguous.

Languages C, C++

Example The following code demonstrates the use of ssGetInputPortSignal.

nInputPorts = ssGetNumInputPorts(S);
for (i = 0; i < nInputPorts; i++) {
int_T nu = ssGetInputPortWidth(S,i);

if ( ssGetInputPortRequiredContiguous(S,i) ) {

const void *u = ssGetInputPortSignal(S,i);

UseInputVectorInSomeFunction(u, nu);

} else {

InputPtrsType u = ssGetInputPortSignalPtrs(S,i);
for (j = 0; j < nu; j++) {
UseInputInSomeFunction(*u[j]);
}
}
}

If you know that the inputs are always real_T signals, the
ssGetInputPortSignal line in the above code snippet would be:

const real_T *u = ssGetInputPortRealSignal(S,i);

10-54
 ssGetInputPortSignal

See Also ssSetInputPortRequiredContiguous, ssGetInputPortRealSignal

10-55
ssGetInputPortSignalAddress

Purpose 10ssGetInputPortSignalAddress
Get address of an input port’s signal.

Syntax function ssGetInputPortSignalAddress(S : in SimStruct;

port : in Integer := 0) return System.Address;

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns the address of the signal connected to port.

Languages Ada

Example The following code gets the signal connected to a block’s input port.
uWidth : Integer := ssGetInputPortWidth(S,0);
U : array(0 .. uWidth-1) of Real_T;
for U'Address use ssGetInputPortSignalAddress(S,0);

See Also ssGetInputPortWidth

10-56
 ssGetInputPortSignalPtrs

Purpose 10ssGetInputPortSignalPtrs
Get pointers to an input port’s signal elements.

Syntax InputPtrsType ssGetInputPortSignalPtrs(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port

Description Returns a pointer to an array of signal element pointers for the specified input
port. For example, if the input port width is 5, this function returns a pointer
to a 5-element pointer array. Each element in the pointer array points to the
specific element of the input signal.
You must use ssGetInputPortRealSignalPtrs to get pointers to signals of
type double (real_T).

Languages C

Example Assume that the input port data types are int8_T.
int_T nInputPorts = ssGetNumInputPorts(S);
for (i = 0; i < nInputPorts; i++) {
InputPtrsType u = ssGetInputPortSignalPtrs(S,i);
InputInt8PtrsType uInt8 = (InputInt8PtrsType)u;
int_T nu = ssGetInputPortWidth(S,i);
for (j = 0; j < nu; j++) {
/* u[j] is an int8_T pointer that points to the j-th element
of the input signal.
*/
UseInputInSomeFunction(*u[j]);
}

See Also ssGetInputPortRealSignalPtrs

10-57
ssGetInputPortWidth

Purpose 10ssGetInputPortWidth
Get the width of an input port.

C Syntax int_T ssGetInputPortWidth(SimStruct *S, int_T port)

Ada Syntax function ssGetInputPortWidth(S : in SimStruct;

port : in Integer := 0) return Integer;

Arguments S
SimStruct representing an S-function block.
port
Index of port whose width is required.

Description Get the input port number of elements. If the input port is a 1-D array with w
elements, this function returns w. If the input port is an M-by-N matrix, this
function returns m*n. If m or n is unknown, this function returns
DYNAMICALLY_SIZED. Use in any routine (except mdlInitializeSizes) to
determine the width of an input port.

Languages Ada, C

See Also ssSetInputPortWidth

10-58
 ssGetIWork

Purpose 10ssGetIWork
Get a block’s integer work vector.

Syntax ssGetIWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the integer work vector used by the block represented by S. The vector
consists of elements of type int_T and is of length ssGetNumRWork(S).
Typically, this vector is initialized in mdlStart or mdlInitializeConditions,
updated in mdlUpdate, and used in mdlOutputs. You can use this macro in the
simulation loop, mdlInitializeConditions, or mdlStart routines.

Languages C

See Also ssGetNumIWork

10-59
ssGetModelName

Purpose 10ssGetModelName
Get the model name.

Syntax ssGetModelName(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description If S is a SimStruct for an S-function block, this macro returns the name of the
S-function MEX-file associated with the block. If S is the root SimStruct, this
macro returns the name of the Simulink block diagram.

Languages C

See Also ssGetPath

10-60
 ssGetModeVector

Purpose 10ssGetModeVector
Get the mode vector.

Syntax int_T *ssGetModeVector(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns a pointer (int_T *) to the mode vector.

This vector has length ssGetNumModes(S). Typically, this vector is initialized in
mdlInitializeConditions if the default value of zero isn’t acceptable. It is
then used in mdlOutputs in conjunction with nonsampled zero crossings to
determine when the output function should change mode. For example
consider an absolute value function. When the input is negative, negate it to
create a positive value, otherwise take no action. This function has two modes.
The output function should be designed not to change modes during minor time
steps. The mode vector may also be used in the mdlZeroCrossings routine to
determine the current mode.

Languages C, C++

See Also ssSetNumModes

10-61
ssGetModeVectorValue

Purpose 10ssGetModeVectorValue
Get an element of a block’s mode vector.

Syntax int_T ssGetModeVectorValue(SimStruct *S, element)

Arguments S
SimStruct representing an S-function block.
elementx
Index of a mode vector element

Description Returns the specified mode vector element.

Languages C, C++

See Also ssSetModeVectorValue, ssGetModeVector

10-62
 ssGetNonsampledZCs

Purpose 10ssGetNonsampledZCs
Get the zero-crossing signal values.

Syntax ssGetNumNonSampledZCs(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns a pointer to the vector containing the current values of the signals that
the variable-step solver monitors for zero crossings. The variable step solver
tracks the signs of these signals to bracket points where they cross zero. The
solver then takes simulation time steps at the points where the zero crossings
occur. This vector has length ssGetNumNonsampledZCs(S).

Example The following excerpt from matlabroot/simulink/src/sfun_zc.c illustrates

usage of this macro to update the zero-crossing array in the mdlZeroCrossings
callback function.
static void mdlZeroCrossings(SimStruct *S)
{
int_T i;
real_T *zcSignals = ssGetNonsampledZCs(S);
InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
int_T nZCSignals = ssGetNumNonsampledZCs(S);

for (i = 0; i < nZCSignals; i++) {

zcSignals[i] = *uPtrs[i];
}
}

Languages C

See Also ssGetNumNonsampledZCs

10-63
ssGetNumContStates

Purpose 10ssGetNumContStates
Get the number of continuous states that a block has.

C Syntax int_T ssGetNumContStates(SimStruct *S)

Ada Syntax function ssGetNumContStates(S : in SimStruct) return Integer;

Arguments S
SimStruct representing an S-function block or model.

Description Returns the number of continuous states in the block or model represented by
S.You can use this macro in any routine except mdlInitializeSizes.

Languages Ada, C

See Also ssSetNumContStates, ssGetNumDiscStates, ssGetContStates

10-64
 ssGetNumDataTypes

Purpose 10ssGetNumDataTypes
Get number of data types registered for this simulation, including built-in
types.

Syntax int_T ssGetNumDataTypes(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the number of data types registered for this simulation. This includes
all custom data types registered by custom S-function blocks and all built-in
data types.

Note S-functions register their data types in their implementations of the

mdlInitializeSize callback function. Therefore, to ensure that this macro
returns an accurate count, your S-function should invoke it only after the
point in the simulation at which Simulink invokes the mdlInitializeSize
callback function.

Languages C

See Also ssRegisterDataType

10-65
ssGetNumDiscStates

Purpose 10ssGetNumDiscStates
Get the number of discrete states that a block has.

Syntax int_T ssGetNumDiscStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Use in any routine (except mdlInitializeSizes) to determine the number of

discrete states that the S-function has.

Languages C

See Also ssSetNumDiscStates, ssGetNumContStates

10-66
 ssGetNumDWork

Purpose 10ssGetNumDWork
Get the number of data type work vectors used by a block.

Syntax int_T ssGetNumDWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the number of data type work vectors used by S.

Languages C, C++

See Also ssSetNumDWork

10-67
ssGetNumInputPorts

Purpose 10ssGetNumInputPorts
Get the number of input ports that a block has.

C Syntax int_T ssGetNumInputPorts(SimStruct *S)

Ada Syntax function ssGetNumInputPorts(S : in SimStruct) return Integer;

Arguments S
SimStruct representing an S-function block.

Description Use in any routine (except mdlInitializeSizes) to determine how many input
ports a block has.

Languages Ada, C

See Also ssGetNumOutputPorts

10-68
 ssGetNumIWork

Purpose 10ssGetNumIWork
Get the size of a block’s integer work vector.

Syntax int_T ssGetNumIWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the size of the integer (int_T) work vector used by the block
represented by S. You can use this macro in any routine except
mdlInitializeSizes

Languages C

See Also ssSetNumIWork, ssGetNumRWork

10-69
ssGetNumModes

Purpose 10ssGetNumModes
Get the size of the mode vector.

Syntax ssGetNumModes(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the size of the modes vector. You can use this macro in any routine
except mdlInitializeSizes

Languages C

See Also ssSetNumNonsampledZCs, ssGetNonsampledZCs

10-70
 ssGetNumNonsampledZCs

Purpose 10ssGetNumNonsampledZCs
Get the size of the zero-crossing vector.

Syntax ssGetNumNonSampledZCs(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the size of the zero-crossing vector. You can use this macro in any
routine except mdlInitializeSizes

Languages C

See Also ssSetNumNonsampledZCs, ssGetNonsampledZCs

10-71
ssGetNumOutputPorts

Purpose 10ssGetNumOutputPorts
Get the number of output ports that a block has.

C Syntax int_T ssGetNumOutputPorts(SimStruct *S)

Ada Syntax function ssGetNumOutputPorts(S : in SimStruct) return Integer;

Arguments S
SimStruct representing an S-function block.

Description Use in any routine (except mdlInitializeSizes) to determine how many

output ports a block has.

Languages Ada, C

See Also ssGetNumInputPorts

10-72
 ssGetNumParameters

Purpose 10ssGetNumParameters
Get the number of parameters that this block has.

Syntax function ssGetNumParameters(S : in SimStruct) return Integer;

Arguments S
SimStruct representing an S-function block.

Description Returns the number of parameters that this block has.

Languages Ada

See Also ssGetParameterName

10-73
ssGetNumRunTimeParams

Purpose 10ssGetNumRunTimeParams
Get the number of run-time parameters created by this S-function.

Syntax int_T ssGetNumRunTimeParams(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Use this function to get the number of run-time parameters created by this
S-function.

Languages C

See Also ssSetNumRunTimeParams

10-74
 ssGetNumPWork

Purpose 10ssGetNumPWork
Get the size of a block’s pointer work vector.

Syntax int_T ssGetNumPWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the size of the pointer work vector used by the block represented by S.
You can use this macro in any routine except mdlInitializeSizes

Languages C

See Also ssSetNumPWork

10-75
ssGetNumRWork

Purpose 10ssGetNumRWork
Get the size of a block’s floating-point work vector.

Syntax int_T ssGetNumRWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the size of the floating-point (real_T) work vector used by the block
represented by S. You can use this macro in any routine except
mdlInitializeSizes

Languages C

See Also ssSetNumRWork

10-76
 ssGetNumSampleTimes

Purpose 10ssGetNumSampleTimes
Get the number of sample times that a block has.

Syntax int_T ssGetNumOutputPorts(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Use in any routine (except mdlInitializeSizes) to determine the number of

sample times S has.

Languages C

See Also ssSetNumSampleTimes

10-77
ssGetNumSFcnParams

Purpose 10ssGetNumSFcnParams
Get the number of parameters that an S-function block expects.

Syntax int_T ssGetNumSFcnParams(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the number of parameters that S expects the user to enter.

Languages C

See Also ssSetSFcnNumSFcnParams

10-78
 ssGetOutputPortBeingMerged

Purpose 10ssGetOutputPortBeingMerged
Determine whether the output of this block is connected to a Merge block.

Syntax int_T ssGetOutputPortBeingMerged(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the output port

Description Returns TRUE if this output port signal is being merged with other signals
(this happens if the S-function block output port is directly or via connection
type blocks is connected to a Merge block). This macro retursn the correct
answer in and after the S-function’s mdlSetWorkWidths method.

Languages C, C++

See Also mdlSetWorkWidths

10-79
ssGetOutputPortComplexSignal

Purpose 10ssGetOutputPortComplexSignal
Get the numeric type (complex or real) of an output port.

Syntax DTypeId ssGetOutputPortDataType(SimStruct *S,input_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port

Description Returns the numeric type of port: COMPLEX_NO (real signal), COMPLEX_YES
(complex signal) or COMPLEX_INHERITED (dynamically determined).

Languages C

See Also ssSetOutputPortComplexSignal

10-80
 ssGetOutputPortDataType

Purpose 10ssGetOutputPortDataType
Get the data type of an output port.

C Syntax DTypeId ssSetOutputPortDataType(SimStruct *S,input_T port)

Ada Syntax function ssGetOutputPortDataType (S : in SimStruct;

port : in Integer := 0) return Integer;

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an output port

Description Returns the data type of the output port specified by port.

Languages Ada, C

See Also ssSetOutputPortDataType

10-81
ssGetOutputPortDimensions

Purpose 10ssGetOutputPortDimensions
Get the dimensions of the signal leaving an output port.

Syntax int_T *ssGetOutputPortDimensions(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port

Description Returns an array of integers that specifies the dimensions of the signal leaving
port, e.g., [4 2] for a 4-by-2 matrix array. The size of the dimensions array is
equal to the number of signal dimensions accepted by the port, e.g., 1 for a
vector signal or 2 for a matrix signal.

Languages C

See Also ssGetOutputPortNumDimensions

10-82
 ssGetOutputPortFrameData

Purpose 10ssGetOutputPortFrameData
Determine if a port accepts signal frames.

Syntax int_T ssGetOutputPortFrameData(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port

Description Returns one of the following

• -1
Port outputs either frame or unframed data.
•0
Port outputs unframed data only.
•1
Port outputs frame data only.

Languages C

See Also ssSetOutputPortFrameData, mdlSetOutputPortFrameData

10-83
ssGetOutputPortNumDimensions

Purpose 10ssGetOutputPortNumDimensions
Get the offset time of an output port.

Syntax int_T ssGetOutputPortNumDimensions(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of output port.

Description Returns number of dimensions of port.

Languages C

See Also ssSetOutputPortDimensionInfo

10-84
 ssGetOutputPortOffsetTime

Purpose 10ssGetOutputPortOffsetTime
Get the offset time of an output port.

Syntax real_T ssGetOutputPortOffsetTime(SimStruct *S,outputPortIdx)

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of output port.

Description Use in any routine (except mdlInitializeSizes) to determine the sample time
of an output port. This macro should only be used if you have specified
port-based sample times.

Languages C

See Also ssSetOutputOffsetTime, ssGetOutputPortSampleTime

10-85
ssGetOutputPortRealSignal

Purpose 10ssGetOutputPortRealSignal
Get a pointer to an output signal of type double (real_T).

Syntax real_T *ssGetOutputPortRealSignal(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of output port.

Description Use in any simulation loop routine, mdlInitializeConditions, or mdlStart to

access an output port signal where the output port index starts at 0 and must
be less than the number of output ports. This returns a contiguous real_T
vector of length equal to the width of the output port.

Example To write to all output ports, you would use

int_T i,j;
int_T nOutputPorts = ssGetNumOutputPorts(S);
for (i = 0; i < nOutputPorts; i++) {
real_T *y = ssGetOutputPortRealSignal(S,i);
int_T ny = ssGetOutputPortWidth(S,i);
for (j = 0; j < ny; j++) {
y[j] = SomeFunctionToFillInOutput();
}
}

Languages C

See Also ssGetInputPortRealSignalPtrs

10-86
 ssGetOutputPortReusable

Purpose 10ssGetOutputPortReusable
Determine whether memory allocated to output port is reusable.

Syntax int_T ssGetOutputPortReusable(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the output port

Description Returns TRUE if output port memory buffer can be reused by other signals in
the model.

Languages C, C++

See Also ssSetOutputPortReusable

10-87
ssGetOutputPortSampleTime

Purpose 10ssGetOutputPortSampleTime
Get the sample time of an output port.

Syntax ssGetOutputPortSampleTime(SimStruct *S,outputPortIdx)

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of output port.

Description Use in any routine (except mdlInitializeSizes) to determine the sample time
of an output port. This macro should only be used if you have specified
port-based sample times.

Languages C

See Also ssSetOutputSampleTime

10-88
 ssGetOutputPortSignal

Purpose 10ssGetOutputPortSignal
Get the vector of signal elements emitted by an output port.

Syntax void *ssGetOutputPortSignal(SimStruct *S, int_T port)

Arguments S
SimStruct representing an S-function block.
port
Index of output port.

Description Returns a pointer to the vector of signal elements output by port.

Note If the port outputs a signal of type double (real_T), you must use
ssGetOutputPortRealSignal to get the signal vector.

Example Assume that the output port data types are int16_T.
nOutputPorts = ssGetNumOutputPorts(S);
for (i = 0; i < nOutputPorts; i++) {
int16_T *y = (int16_T *)ssGetOutputPortSignal(S,i);
int_T ny = ssGetOutputPortWidth(S,i);
for (j = 0; j < ny; j++) {
SomeFunctionToFillInOutput(y[j]);
}
}

Languages C

See Also ssGetOutputPortRealSignal

10-89
ssGetOutputPortSignalAddress

Purpose 10ssGetOutputPortSignalAddress
Get address of an output port’s signal.

Syntax ssGetOutputPortSignalAddress(S : in SimStruct; port : in Integer :=

0) return System.Address

Arguments S
SimStruct representing an S-function block.
port
Index of an output port

Description Returns the address of the signal connected to port.

Languages Ada

Example The following code gets the signal connected to a block’s input port.
yWidth : Integer := ssGetOutputPortWidth(S,0);
Y : array(0 .. yWidth-1) of Real_T;
for Y'Address use ssGetOutputPortSignalAddress(S,0);

See Also ssGetOutputPortWidth

10-90
 ssGetOutputPortWidth

Purpose 10ssGetOutputPortWidth
Get the width of an output port.

C Syntax int_T ssGetOutputPortWidth(SimStruct *S, int_T port)

Ada Syntax function ssGetOutputPortWidth(S : in SimStruct; port : in Integer

:= 0) return Integer;

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of output port.

Description Use in any routine (except mdlInitializeSizes) to determine the width of an

output port where the output port index starts at 0 and must be less than the
number of output ports.

Languages Ada, C

See Also ssSetOutputPortWidth

10-91
ssGetPath

Purpose 10ssGetPath
Get the path of a block.

C Syntax const char_T *ssGetPath(SimStruct *S)

Ada Syntax function ssGetPath(S : in SimStruct) return String;

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description If S is an S-function block, this macro returns the full Simulink path to the
block. If S is the root SimStruct of the model, this macro returns the model
name. In a C MEX S-function, in mdlInitializeSizes, if
strcmp(ssGetModelName(S),ssGetPath(S))==0

the S-function is being called from MATLAB and is not part of a simulation.

Languages Ada, C

See Also ssGetModelName

10-92
 ssGetParentSS

Purpose 10ssGetParentSS
Get the parent of a SimStruct.

Syntax SimStruct *ssGetParentSS(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns the parent SimStruct of S, or NULL if S is the root SimStruct.

Note There is one SimStruct for each S-Function in your model and one for
the model itself. The structures are arranged as a tree with the model
SimStruct as the root. User-written S-functions should not use the
ssGetParentSS macro.

Languages C

See Also ssGetRoot

10-93
ssGetPlacementGroup

Purpose 10ssGetPlacementGroup
Get the name of the placement group of a block.

Syntax const char *ssGetPlacementGroup(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model. The block
must be either a source block (i.e., a block without input ports) or a sink block
(i.e., a block without output ports).

Description Use this macro in mdlInitializeSizes to get the name of this block’s
placement group.

Note This macro is typically used to create Real-Time Workshop device

driver blocks.

Languages C

See Also ssGetPlacementGroup

10-94
 ssGetPWork

Purpose 10ssGetPWork
Get a block’s pointer work vector.

Syntax ssGetPWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the pointer work vector used by the block represented by S. The vector
consists of elements of type void * and is of length ssGetNumRWork(S).
Typically, this vector is initialized in mdlStart or mdlInitializeConditions,
updated in mdlUpdate, and used in mdlOutputs. You can use this macro in the
simulation loop, mdlInitializeConditions, or mdlStart routines.

Languages C

See Also ssGetNumPWork

10-95
ssGetRealDiscStates

Purpose 10ssGetRealDiscStates
Get a block’s discrete state vector.

Syntax real_T *ssGetRealDiscStates(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Same as ssGetDiscStates.

Languages C

See Also ssGetDiscStates

10-96
 ssGetRootSS

Purpose 10ssGetRootSS
Get the root of a SimStruct hierarchy.

Syntax SimStruct *ssGetRootSS(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns the root of the SimStruct hierarchy containing S.

Languages C

See Also ssGetParent

10-97
ssGetRunTimeParamInfo

Purpose 10ssGetRunTimeParamInfo
Gets the attributes of a run-time parameter.

Syntax ssParamRec *ssGetRunTimeParamInfo(SimStruct *S, int_T param)

Arguments S
SimStruct representing an S-function block.
param
Index of a run-time parameter

Description Returns the attributes of the run-time parameter specified by param. See the
documentation for ssSetRunTimeParamInfo for a description of the ssParamRec
structure returned by this function.

Languages C

See Also ssSetRunTimeParamInfo

10-98
 ssGetRWork

Purpose 10ssGetRWork
Get a block’s floating-point work vector.

Syntax ssGetRWork(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the floating-point work vector used by the block represented by S. The
vector consists of elements of type real_T and is of length ssGetNumRWork(S).
Typically, this vector is initialized in mdlStart or mdlInitializeConditions,
updated in mdlUpdate, and used in mdlOutputs. You can use this macro in the
simulation loop, mdlInitializeConditions, or mdlStart routines.

Languages C

See Also ssGetNumRWork

10-99
ssGetSampleTimeOffset

Purpose 10ssGetSampleTimeOffset
Get the period of the current sample time.

Syntax function ssGetSampleTimeOffset(S : in SimStruct) return time_T;

Arguments S
SimStruct representing an S-function block.

Description Returns the offset of the current sample time.

Languages Ada

See Also ssGetSampleTimePeriod

10-100
 ssGetSampleTimePeriod

Purpose 10ssGetSampleTimePeriod
Get the period of the current sample time.

Syntax function ssGetSampleTimePeriod(S : in SimStruct) return time_T;

Arguments S
SimStruct representing an S-function block.

Description Returns the period of the current sample time.

Languages Ada

See Also ssGetSampleTimeOffset

10-101
ssGetSFcnParam

Purpose 10ssGetSFcnParam
Get a parameter of an S-function block.

Syntax const mxArray *ssGetSFcnParam(SimStruct *S, int_T index)

Arguments S
SimStruct representing an S-function block.
index
Index of the parameter to be returned.

Description Use in any routine to access a parameter entered in the S-function’s block
dialog box where index starts at 0 and is less than ssGetSFcnParamsCount(S).

Languages C

See Also ssGetSFcnParamsCount

10-102
 ssGetSFcnParamsCount

Purpose 10ssGetSFcnParamsCount
Get the number of block dialog parameters that an S-function block has.

Syntax int_T ssGetSFcnParamsCount(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns the number of parameters that a user can set for the block represented
by S.

Languages C

See Also ssGetNumSFcnParams

10-103
ssGetSimMode

Purpose 10ssGetSimMode
Get the simulation mode an S-function block.

Syntax ssGetSimMode(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns the simulation mode of the block represented by S:

• SS_SIMMODE_NORMAL
Running in a normal Simulink simulation
• SS_SIMMODE_SIZES_CALL_ONLY
Invoked by editor to obtain number of ports
• SS_SIMMODE_RTWGEN
Generating code
• SS_SIMMODE_EXTERNAL
External mode simulation

Languages C

See Also ssGetSolverName

10-104
 ssGetSolverMode

Purpose 10ssGetSolverMode
Get the solver mode being used to solve the S-function.

Syntax SolverMode ssGetSolverMode(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns one of:

• SOLVER_MODE_AUTO
• SOLVER_MODE_SINGLETASKING
• SOLVER_MODE_MULTITASKING
This macro can return SOLVER_MODE_AUTO in mdlInitializeSizes. However,
in mdlSetWorkWidths and any methods called after mdlSetWorkWidths, solver
mode will be either SOLVER_MODE_SINGLETASKING or
SOLVER_MODE_MULTITASKING.

Languages C, C++

See Also ssGetSimMode, ssIsVariableStepSolver

10-105
ssGetSolverName

Purpose 10ssGetSolverName
Get the name of the solver being used to solve the S-function.

Syntax ssGetSolverName(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns a pointer (char *) to the name of the solver being used to solve the
S-function represented by S.

Languages C

See Also ssGetSimMode, ssIsVariableStepSolver

10-106
 ssGetStateAbsTol

Purpose 10ssGetStateAbsTol
Get the absolute tolerance used by the model’s variable step solver for a
specified state.

Syntax real_T ssGetStateAbsTol(SimStruct *S, int_T state)

Arguments S
SimStruct representing an S-function block.

Description Use in mdlStart to get the absolute tolerance for a particular state.

Note Absolute tolerances are not allocated for fixed step solvers. Therefore,
you should not invoke this macro until you have verified that the simulation is
using a variable step solver, using ssIsVariableStepSolver.

Languages C, C++

See Also ssGetAbsTol, ssIsVariableStepSolver

10-107
ssGetT

Purpose 10ssGetT
Get the current simulation time.

C Syntax ssGetT(SimStruct *S)

Ada Syntax function ssGetT(S : in SimStruct) return Real_T;

Arguments S
SimStruct representing an S-function block.

Description Returns the current base simulation time (time_T) for the model. You can use
this macro in mdlOutputs and mdlUpdate to compute the output of your block.

Note Use this macro only if your block operates at the base rate of the model,
for example, if your block operates at a single, continuous rate. If your block
operates at multiple rates or operates at a single rate that is different from
the model’s base, use ssGetTaskTime to get the correct time for the current
task.

Languages Ada, C

See Also ssGetTaskTime, ssGetTStart, ssGetTFinal

10-108
 ssGetTNext

Purpose 10ssGetTNext
Get the time of the next sample hit.

Syntax time_T ssGetTNext(SimStruct *S)

Arguments S
SimStruct representing an S-function block

Description Returns the next time that a sample hit occurs in a discrete S-function with a
variable sample time.

Languages C

See Also ssSetTNext, mdlGetTimeOfNextVarHit

10-109
ssGetTaskTime

Purpose 10ssGetTaskTime
Get the current time for the current task.

Syntax ssGetTaskTime(SimStruct *S, st_index)

Arguments S
SimStruct representing an S-function block.
st_index
Index of the sample time corresponding to the task for which the current time
is to be returned.

Description Returns the current time (time_T) of the task corresponding to the sample rate
specified by st_index. You can use this macro in mdlOutputs and mdlUpdate to
compute the output of your block.

Languages C

See Also ssGetT

10-110
 ssGetTFinal

Purpose 10ssGetTFinal
Get the simulation stop time.

C Syntax time_T ssGetTFinal(SimStruct *S)

Ada Syntax function ssGetTFinal(S : in SimStruct) return Real_T;

Arguments S
SimStruct representing an S-function block.

Description Returns the stop time of the current simulation.

Languages Ada, C

See Also ssGetT, ssGetTStart

10-111
ssGetTStart

Purpose 10ssGetTStart
Get the simulation start time.

C Syntax time_T ssGetTStart(SimStruct *S)

Ada Syntax function ssGetTStart(S : in SimStruct) return Real_T;

Arguments S
SimStruct representing an S-function block.

Description Returns the start time of the current simulation.

Languages Ada, C

See Also ssGetT, ssGetTFinal

10-112
 ssGetUserData

Purpose 10ssGetUserData
Access user data.

Syntax void ssGetUserData(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Retrieves pointer to user data.

Languages C, C++

See Also ssSetUserData

10-113
ssIsContinuousTask

Purpose 10ssIsContinuousTask
Determine if a task is continuous.

Syntax ssIsContinuousTask(SimStruct *S,st_index,tid)

Arguments S
SimStruct representing an S-function block
tid
task ID

Description Use in mdlOutputs or mdlUpdate when your S-function has multiple sample
times to determine if your S-function is executing in the continuous task. This
should not be used in single rate S-functions, or if you did not register a
continuous sample time.

Languages C

See Also ssSetNumContStates

10-114
 ssIsFirstInitCond

Purpose 10ssIsFirstInitCond
Determine whether this is the first call to mdlInitializeConditions.

Syntax int_T ssGetFirstInitCond(SimStruct *S)

Arguments S
SimStruct representing an S-function block.

Description Returns true if the current simulation time is equal to the simulation start
time.

Languages C

See Also mdlInitializeConditions

10-115
ssIsMajorTimeStep

Purpose 10ssIsMajorTimeStep
Determine if the simulation is in a major step.

C Syntax int_T ssIsMajorTimeStep(SimStruct *S)

Ada Syntax function ssIsMajorTimeStep(S : in SimStruct) return Boolean;

Arguments S
SimStruct representing an S-function block

Description Returns 1 if the simulation is in a major time step.

Languages Ada, C

See Also ssIsMinorTimeStep

10-116
 ssIsMinorTimeStep

Purpose 10ssIsMinorTimeStep
Determine if the simulation is in a minor step.

Syntax int_T ssIsMinorTimeStep(SimStruct *S)

Arguments S
SimStruct representing an S-function block

Description Returns 1 if the simulation is in a minor time step.

Languages C

See Also ssIsMajorTimeStep

10-117
ssIsSampleHit

Purpose 10ssIsSampleHit
Determine if sample is hit.

Syntax ssIsSampleHit(SimStruct *S,st_index,tid)

Arguments S
SimStruct representing an S-function block
st_index
Index of the sample time
tid
task ID

Description Use in mdlOutputs or mdlUpdate when your S-function has multiple sample
times to determine what task your S-function is executing in. This should not
be used in single rate S-functions or for an st_index corresponding to a
continuous task.

Languages C

See Also ssIsContinuousTask, ssIsSpecialSampleHit

10-118
 ssIsSpecialSampleHit

Purpose 10ssIsSpecialSampleHit
Determine if sample is hit.

Syntax ssIsSpecialSampleHit(SimStruct *S, sti1, sti2, tid)

Arguments S
SimStruct representing an S-function block
sti1
Index of the sample time
sti2
Index of the sample time
tid
task ID

Description Returns true if a sample hit has occurred at sti1 and a sample hit has also
occurred at sti2 in the same time step. You can used this macro in mdlUpdate
and mdlOutputs to ensure the validity of data shared by multiple tasks running
at different rates. For more information, see “Synchronizing Multirate
S-Function Blocks” on page 7-22.

Languages C

See Also ssIsSampleHit

10-119
ssIsVariableStepSolver

Purpose 10ssIsVariableStepSolver
Get the name of the solver being used to solve the S-function.

Syntax ssGetSolverName(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description Returns 1 if the solver being used to solve S is a variable step solver. This is
useful when creating S-functions that have zero crossings and an inherited
sample time.

Languages C

See Also ssGetSimMode, ssGetSolverName

10-120
 ssPrintf

Purpose 10ssPrintf
Print a variable-content message.

Syntax ssPrintf(msg, ...)

Arguments msg
Message. Must be a string with optional variable replacement parameters.
...
Optional replacement arguments.

Description Prints variable-content msg. This macro expands to mexPrintf when the
S-function is compiled via mex for use with Simulink. When the S-function is
compiled for use with the Real-Time Workshop, this macro expands to printf,
if the target has stdio facilities; otherwise, it becomes a call to an empty
function (rtPrintfNoOp). In the case of Real-Time Workshop, you can avoid a
call altogether, using the SS_STDIO_AVAILABLE macro, e.g.,
#if defined(SS_STDIO_AVAILABLE)
ssPrintf("my message ...");
#endif

Languages C

See Also ssWarning

10-121
ssRegAllTunableParamsAsRunTimeParams

Purpose 10ssRegAllTunableParamsAsRunTimeParams
Register all tunable parameters as run-time parameters.

Syntax void ssRegAllTunableParamsAsRunTimeParams(S,

const char_T *names[]))

Arguments S
SimStruct representing an S-function block.
names
Array of names for the run-time parameters

Description Use this function in mdlSetWorkWidths to register all tunable dialog

parameters as run-time parameters. Specify the names of the run-time
versions of the parameters in the names array.

Note Simulink assumes that the names array is always available. Therefore,
you must allocate the names array in such a way that it persists throughout
the simulation.

You can register dialog parameters individually as run-time parameters, using

ssSetNumRunTimeParameters and ssSetRunTimeParamInfo.

Languages C

See Also mdlSetWorkWidths, ssSetNumRunTimeParameters, ssSetRunTimeParamInfo

10-122
 ssRegisterDataType

Purpose 10ssRegisterDataType
Register a custom data type.

Syntax DtypeId ssRegisterDataType(SimStruct *S, char *name)

Arguments S
SimStruct representing an S-function block.
name
Name of custom data type

Description Register a custom data type. Each data type must be a valid MATLAB
identifier. That is, the first char is an alpha and all subsequent characters are
alphanumeric or “_”. The name length must be less than 32. Data types must
be registered in mdlInitializeSizes.
If the registration is successful, the function returns the DataTypeId associated
with the registered data type, otherwise, it reports an error and returns
INVALID_DTYPE_ID.

After registering the data type, you must specify its size, using
ssSetDataTypeSize.

Note You can call this function to get the data type id associated with a
registered data type.

Example The following example registers a custom data type named Color.
DtypeId id = ssRegisterDataType(S, “Color”);
if(id == INVALID_DTYPE_ID) return;

Languages C

See Also ssSetDataTypeSize

10-123
ssSetBlockReduction

Purpose 10ssSetBlockReduction
Request that Simulink attempt to reduce a block.

Syntax ssSetBlockReduction(SimStruct *S, unsigned int_T flag)

Arguments S
SimStruct representing an S-function block
flag
If TRUE, Simulink should attempt to reduce this block.

Description Use this macro to ask Simulink to reduce this block. A block is reducible if it
can be eliminated from the model without affecting the model’s behavior.
Simulink optimizes performance by skipping execution of reducible blocks
during model simulation. In particular, Simulink does not invoke the
mdlStart, mdlUpdate, and mdlOutput methods of reducible blocks. Further,
Simulink executes the mdlTerminate method of a reduced block only if the
block has set the SS_OPTION_CALL_TERMINATE_AT_EXIT option before the
simulation loop has begun, using ssSetOption.
A block must meet certain criteria to be considered reducible. For example, a
block must have at least one input, must have the same number of outputs as
inputs or no outputs, and none of the block’s inputs can be a bus signal. If a
block fails to meet any of these criteria, Simulink includes the block in the
simulation regardless of whether the block has requested reduction.
Your S-function must invoke this macro before Simulink would otherwise
invoke the S-function’s mdlStart method (see the callback flow diagram in
“How Simulink Interacts with C S-Functions” on page 3-32). This means your
S-function must invoke this macro no later than its mdlInitializeWorkWidths
method to be considered a candidate for block reduction.

Languages C

See Also ssGetBlockReduction

10-124
 ssSetCallSystemOutput

Purpose 10ssSetCallSystemOutput
Specify that an output port is issuing a function call.

Syntax ssSetCallSystemOutput(SimStruct *S, port_index)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port_index
Index of port that is issuing the function call

Description Use in mdlInitializeSampleTimes to specify that the output port element

specified by index is issuing a function call by using
ssCallSystemWithTid(S,index,tid). The index specified starts at 0 and
must be less than ssGetOutputPortWidth(S,0).

Languages C

See Also ssCallSystemWithTid

10-125
ssSetDataTypeSize

Purpose 10ssSetDataTypeSize
Set the size of a custom data type.

Syntax int_T ssSetDataTypeSize(SimStruct *S, DTypeId id, int_T size)

Arguments S
SimStruct representing an S-function block.
id
ID of data type
size
Size of the custom data type in bytes

Description Sets the size of the data type specified by id to size. If the call is successful,
the macro returns 1 (true), otherwise, it returns 0 (false).Use this macro in
mdlInitializeSizes to set the size of a data type you have registered.

Example The following example registers and sets the size of the custom data type
named Color to four bytes.
int_T status;
DtypeId id;

id = ssRegisterDataType(SimStruct *S, “Color”);

if(id == INVALID_DTYPE_ID) return;

status = ssSetDataTypeSize(S, id, 4);

if(status == 0) return;

Languages C

See Also ssRegisterDataType, ssGetDataTypeSize

10-126
 ssSetDataTypeZero

Purpose 10ssSetDataTypeZero
Set zero representation of a data type.

Syntax int_T ssSetDataTypeZero(SimStruct *S, DTypeId id, void* zero)

Arguments S
SimStruct representing an S-function block.
id
ID of data type
zero
Zero representation of the data type specified by id

Description Sets the zero representation of the data type specified by id to zero and
returns 1 (true), if id valid, and the size of the data type has been set, and the
zero representation has not already been set. Otherwise, this macro returns 0
(false) and reports an error. Because this macro reports any error that occurs,
you do not need to use ssSetErrorStatus to report the error.

Note This macro makes a copy of the zero representation of the data type for
Simulink’s use. Thus, your S-function does not have to maintain the original
in memory.

Languages C

Example The following example registers and sets the size and zero representation of a
custom data type named myDataType.
typedef struct{
int8_T a;
uint16_T b;
}myStruct;

int_T status;
DtypeId id;
myStruct tmp;

id = ssRegisterDataType(S, “myDataType”);

10-127
ssSetDataTypeZero

if(id == INVALID_DTYPE_ID) return;

status = ssSetDataTypeSize(S, id, sizeof(tmp));

if(status == 0) return;

tmp.a = 0;
tmp.b = 1;
status = ssSetDataTypeZero(S, id, &tmp);
if(status == 0) return;

See Also ssRegisterDataType, ssSetDataTypeSize, ssGetDataTypeZero

10-128
 ssSetDWorkComplexSignal

Purpose 10ssSetDWorkComplexSignal
Specify whether the elements of a data type work vector are real or complex.

Syntax void ssSetDWorkComplexSignal(SimStruct *S, int_T vector,

CSignal_T numType)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

numType
Numeric type, either COMPLEX_YES or COMPLEX_NO.

Description Use in mdlInitializeSizes or mdlSetWorkWidths to specify whether the

values of the specified work vector are complex numbers (COMPLEX_YES) or real
numbers (COMPLEX_NO, the default).

Languages C, C++

See Also ssSetDWorkDataType, ssGetNumDWork

10-129
ssSetDWorkDataType

Purpose 10ssSetDWorkDataType
Specify the data type of a data type work vector.

Syntax void ssSetDWorkDataType(SimStruct *S, int_T vector, DTypeId dtID)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

dtID
Id of a data type

Description Use in mdlInitializeSizes or mdlSetWorkWidths to set the data type of the

specified work vector.

Languages C, C++

See Also ssSetDWorkWidth, ssGetNumDWork

10-130
 ssSetDWorkName

Purpose 10ssSetDWorkName
Specify the name of a data type work vector.

Syntax void ssSetDWorkName(SimStruct *S, int_T vector, char_T *name)

Arguments S
SimStruct representing an S-function block.
name
Index of the work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

name
Name of work vector.

Description Use in mdlInitializeSizes or in mdlSetWorkWidths to specify a name for the

specified data type work vector. The Real-Time Workshop uses this name to
label the work vector in generated code. If you do not specify a name, the
Real-Time Workshop generates a name for the work vector.

Languages C, C++

See Also ssGetDWorkName, ssSetNumDWork

10-131
ssSetDWorkUsedAsDState

Purpose 10ssSetDWorkUsedAsDState
Specify that a data type work vector is used as a discrete state vector.

Syntax void ssSetDWorkUsedAsDState(SimStruct *S, int_T vector,

int_T usage)

Arguments S
SimStruct representing an S-function block.
vector
Index of a data type work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

Usage
How this vector is used

Description Use in mdlInitializeSizes or mdlSetWorkWidths to specify the usage of the

specified work vector, either SS_DWORK_USED_AS_DSTATE (used to store the
block’s discrete states) or SS_DWORK_USED_AS_DWORK (used as a work vector, the
default).

Note Specify the usage as SS_DWORK_USED_AS_DSTATE if the following

conditions are true. You want to use the vector to store discrete states and
and you want Simulink to log the discrete states to the workspace at the end
of a simulation, if the user has selected the Save to Workspace option on
Simulink’s Simulation Parameters dialog.

Languages C, C++

See Also ssGetDWorkUsedAsDState

10-132
 ssSetDWorkWidth

Purpose 10ssSetDWorkWidth
Specify the width of a data type work vector.

Syntax void ssSetDWorkWidth(SimStruct *S, int_T vector, int_T width)

Arguments S
SimStruct representing an S-function block.
vector
Index of the work vector, where the index is one of 0, 1, 2, ...
ssGetNumDWork(S)

width
Number of elements in the work vector.

Description Use in mdlInitializeSizes or in mdlSetWorkWidths to set the number of

elements in the specified data type work vector.

Languages C, C++

See Also ssGetDWorkWidth, ssSetDWorkDataType, ssSetNumDWork

10-133
ssSetErrorStatus

Purpose 10ssSetErrorStatus
Report an error.

C Syntax void ssSetErrorStatus(SimStruct *S, const char_T *msg)

Ada Syntax procedure ssSetErrorStatus(S : in SimStruct; msg : in String);

Arguments S
SimStruct representing an S-function block or a Simulink model.
msg
Error message

Description Use this function to report errors that occur in your S-function, e.g.,
ssSetErrorStatus(S, "error message");
return;

Note The error message string must be in persistent memory; it cannot be a

local variable.

Languages Ada, C

See Also ssWarning

10-134
 ssSetExternalModeFcn

Purpose 10ssSetExternalModeFcn
Specify the external mode function for an S-function.

Syntax void ssSetExternalModeFcn(SimStruct *S, SFunExtModeFcn *fcn)

Arguments S
SimStruct representing an S-function block or a Simulink model.
fcn
external mode function

Description Specifies the external mode function for S.

Languages C

See Also ssCallExternalModeFcn

10-135
ssSetInputPortComplexSignal

Purpose 10ssSetInputPortComplexSignal
Set the numeric type (real or complex) of an input port.

Syntax void ssSetInputPortComplexSignal(SimStruct *S, input_T port,

CSignal_T csig)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port
csignal
Numeric type of the signals accepted by port. Valid values are COMPLEX_NO
(real signal), COMPLEX_YES (complex signal), COMPLEX_INHERITED (numeric type
inherited from driving block).

Description Use this function in mdlInitializeSizes to initialize input port signal type. If
the numeric type of the input port is inherited from the block to which it is
connected, set the numeric type to COMPLEX_INHERITED. The default numeric
type of an input port is real.

Languages C

Example Assume that an S-function has three input ports. The first input port accepts
real (non-complex) signals. The second input port accepts complex signal. The
third port accepts signals of either type. The following example specifies the
correct numeric type for each port.
ssSetInputPortComplexSignal(S, 0, COMPLEX_NO)
ssSetInputPortComplexSignal(S, 1, COMPLEX_YES)
ssSetInputPortComplexSignal(S, 2, COMPLEX_INHERITED)

See Also ssGetInputPortComplexSignal

10-136
 ssSetInputPortDataType

Purpose 10ssSetInputPortDataType
Set the data type of an input port.

C Syntax void ssSetInputPortDataType(SimStruct *S,input_T port, DTypeId id)

Ada Syntax procedure ssSetInputPortDataType(S : in SimStruct;

port : in Integer := 0; id : in Integer);

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port
id
Id of data type accepted by port

Description Use this function in mdlInitializeSizes to set the data type of the input port
specified by port. If the input port’s data type is inherited from the block
connected to the port, set the data type to DYNAMICALLY_TYPED.

Note The data type of an input port is double (real_T) by default.

Languages Ada, C

Example Suppose that you want to create an S-function with two input ports, the first of
which inherits its data type the driving block and the second of which accepts
inputs of type int8_T. The following code sets up the data types.
ssSetInputPortDataType(S, 0, DYNAMICALLY_TYPED)
ssSetInputPortDataType(S, 1, SS_INT8)

See Also ssGetInputPortDataType

10-137
ssSetInputPortDimensionInfo

Purpose 10ssSetInputPortDimensionInfo
Specify information about the dimensionality of an input port.

Syntax void ssSetInputPortDimensionInfo(SimStruct *S, int_T port,

DimsInfo_T *dimsInfo)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port
dimsInfo
Structure of type DimsInfo_T that specifies the dimensionality of the signals
accepted by port.
The structure is defined as
typedef struct DimsInfo_tag{
int width;/* number of elements */
int numDims/* Number of dimensions */
int *dims;/* Dimensions. */
[snip]
}DimsInfo_T;

where:

• numDims specifies the number of dimensions of the signal, e.g., 1 for a 1-D
(vector) signal or 2 for a 2-D (matrix) signal, or DYNAMICALLY_SIZED if the
number of dimensions is determined dynamically
• dims is an integer array that specifies the size of each dimension, e.g., [2 3]
for a 2-by-3 matrix signal, or DYNAMICALLY_SIZED for each dimension that
is determined dynamically, e.g., [2 DYNAMICALL_SIZED]
• width equals the total number of elements in the signal, e.g., 12 for a 3-by-4
matrix signal or 8 for an 8-element vector signal, or DYNAMICALLY_SIZED if
the total number of elements is determined dynamically

Note Use the macro, DECL_AND_INIT_DIMSINFO, to declare and initialize an

instance of this structure.

10-138
 ssSetInputPortDimensionInfo

Description Specifies the dimension information for port. Use this function in
mdlInitializeSizes to initialize the input port dimension information. If you
want the port to inherit its dimensions from the port to which it is connected,
specify DYNAMIC_DIMENSION as the dimsInfo for port.

Languages C

Example The following example specifies that input port 0 accepts 2-by-2 matrix signals.
{
DECL_AND_INIT_DIMSINFO(di);
int dims[2];

di.numDims = 2;
dims[0] = 2;
dims[1] = 2;
di.dims = &dims;
di.width = 4;
ssSetInputPortDimensionInfo(S, 0, &di);
}

See Also ssSetInputPortMatrixDimensions, ssSetInputPortVectorDimensions

10-139
ssSetInputPortFrameData

Purpose 10ssSetInputPortFrameData
Specify whether a port accepts signal frames.

Syntax void ssSetInputPortFrameData(SimStruct *S, int_T port,

int_T acceptsFrames)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port
acceptsFrames
Type of signal accepted by port. Acceptable values are -1 (either frame or
unframed input), 0 (unframed input only), 1 (framed input only).

Description Use in mdlSetInputPortFrameData to specify whether a port accepts frame

data only, unframed data only, or both.

Languages C

See Also ssGetInputPortFrameData, mdlSetInputPortFrameData

10-140
 ssSetInputPortDirectFeedThrough

Purpose 10ssSetInputPortDirectFeedThrough
Specify the direct feedthrough status of a block’s ports.

C Syntax void ssSetInputPortDirectFeedThrough(SimStruct *S, int_T port,

int_T dirFeed)

Ada Syntax procedure ssSetInputPortDirectFeedThrough(S : in SimStruct; port :

in Integer := 0; dirFeed : in Boolean);

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the input port whose direct feedthrough property is being set.
dirFeed
Direct feedthrough status of block specified by inputPortIdx.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify the direct

feedthrough (0 or 1) for each input port index. If not specified, the default direct
feedthrough is 0. Setting direct feedthrough to 0 for an input port is equivalent
to saying that the corresponding input port signal is not used in mdlOutputs or
mdlGetTimeOfNextVarHit. If it is used, you may or may not see a delay of one
simulation step in the input signal. This may cause the simulation solver to
issue an error due to simulation inconsistencies.

Languages Ada, C

See Also ssSetInputPorts

10-141
ssSetInputPortMatrixDimensions

Purpose 10ssSetInputPortMatrixDimensions
Specify dimension information for an input port that accepts matrix signals.

Syntax void ssSetInputPortMatrixDimensions(SimStruct *S, int_T port, int_T

m, int_T n)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port
m
Row dimension of matrix signals accepted by port or DYNAMICALLY_SIZED
n
Column dimension of matrix signals accepted by port or DYNAMICALLY_SIZED

Description Specifies that port accepts an m-by-n matrix signal. If either dimension is
DYNAMICALLY_SIZED, the other must be DYNAMICALLY_SIZED or 1.

Languages C

Example The following example specifies that input port 0 accepts 2-by-2 matrix signals.
ssSetInputPortMatrixDimensions(S, 0, 2, 2);

See Also ssSetInputPortDimensionInfo

10-142
 ssSetInputPortOffsetTime

Purpose 10ssSetInputPortOffsetTime
Specify the offset time of an input port.

Syntax void ssSetInputPortOffsetTime(SimStruct *S,

int_T inputPortIdx, int_T period)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port whose offset time is being set.
offset
Offset time

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify the sample

time offset for each input port index. You can use this macro in conjunction with
ssSetInputPortSampleTime if you have specified port-based sample times for
your S-function.

Languages C

See Also ssSetNumInputPorts, ssSetInputPortSampleTime

10-143
ssSetInputPortOverWritable

Purpose 10ssSetInputPortOverWritable
Specify whether an input port can be overwritten.

C Syntax void ssSetInputPortOverWritable(SimStruct *S, int_T port, int_T

isOverwritable)

Ada Syntax procedure ssSetInputPortOverWritable(S : in SimStruct; port : in

Integer := 0; isOverwritable : in Boolean);

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the input port whose overwritability is being set.
isOverwritable
Value specifying whether port is overwritable.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify whether

the input port is overwritable by an output port. The default is
isOverwritable=0, which means that the input port does not share memory
with an output port. When isOverwritable=1, the input port shares memory
with an output port.

Note ssSetInputPortReusable and ssSetOutputPortReusable must both be

set to 0, meaning that neither port involved can have global and persistent
memory.

Languages Ada, C

See Also ssSetNumInputPorts, ssSetInputPortReusable,

ssSetOutputPortReusable, ssGetInputPortBufferDstPort

10-144
 ssSetInputPortReusable

Purpose 10ssSetInputPortReusable
Specify whether where memory allocated to port is reusable.

Syntax void ssSetInputPortReusable(SimStruct *S, int_T port, int_T

isReusable)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port whose reusability is being set.
isReusable
Value specifying whether port is reusable.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify whether

the input port memory buffer can be reused by other signals in the model. This
macro can take on two values:

• Off (isReusable=0) — specifies that the input port is not reusable. This is the
default.
• On (isReusable=1) — specifies that the input port is reusable.

In Simulink, reusable signals share the same memory space. When this macro
is turned on, the input port signal to the S-function may be reused by other
signals in the model. This reuse results in less memory use during Simulink
simulation and more efficiency in the Real-Time Workshop generated code.
You must use caution when using this macro; you can safely turn it on only if
the S-function reads its input port signal in its mdlOutputs routine and does
not access this input port signal until the next call to mdlOutputs.
When an S-functions’s input port signal is reused, other signals in the model
overwrite it prior to the execution of mdlUpdate, mdlDerivatives, or other
run-time S-function routines. For example, if the S-function reads the input
port signal in its mdlUpdate routine, or reads the input port signal in the
mdlOutputs routine and expects this value to be persistent until the execution
of its mdlUpdate routine, turning this attribute on is incorrect and will lead to
erroneous results.
The default setting, off, is safe. It prevents any reuse of the S-function input
port signals, which means that the inport port signals have the same value in

10-145
ssSetInputPortReusable

any run-time S-function routine during a single execution of the simulation

loop.
Note that this is a suggestion and not a requirement for the Simulink engine.
If Simulink cannot resolve buffer reuse in local memory, it resets value=0 and
places the input port signals into global memory

Languages C

See Also ssSetNumInputPorts, ssSetInputPortOverwritable,

ssSetOutputPortReusable

10-146
 ssSetInputPortRequiredContiguous

Purpose 10ssSetInputPortRequiredContiguous
Specify that the signal elements entering a port must be contiguous.

Syntax void ssSetInputPortRequiredContiguous(SimStruct *S, int_T port,

int_T flag)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port
flag
TRUE if signal elements must be contiguous.

Description Specifies that the signal elements entering the specified port must occupy
contiguous areas of memory. This allows a method to access the elements of the
signal simply by incrementing the signal pointer returned by
ssGetInputPortSignal. The S-function can set the value of this attribute as
early as in the mdlInitializeSizes method and at the latest in the
mdlSetWorkWidths method.

Note The default setting for this flag is false. Hence, the default method for
accessing the input signals is ssGetInputSignalPtrs.

Languages C, C++

See Also mdlInitializeSizes, mdlSetWorkWidths, ssGetInputPortSignal,

ssGetInputPortSignalPtrs

10-147
ssSetInputPortSampleTime

Purpose 10ssSetInputPortSampleTime
Specify the sample time of an input port.

Syntax ssSetInputPortSampleTime(SimStruct *S,inputPortIdx,period)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port whose sample time is being set.
period
Sample period.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify the sample

time period as continuous or as a discrete value for each input port. Input port
index numbers start at 0 and end at the total number of input ports minus 1.
You should use this macro only if you have specified port-based sample times.

Languages C

See Also ssSetNumInputPorts, ssSetInputPortOffsetTime

10-148
 ssSetInputPortSampleTimeIndex

Purpose 10ssSetInputPortSampleTimeIndex
Specify the sample time index of an input port.

Syntax void ssSetInputPortSampleTimeIndex(SimStruct *S,

int_T inputPortIdx, int_T sampleTimeIdx)

Arguments S
SimStruct representing an S-function block or a Simulink model.
inputPortIdx
Index of the input port whose sample time index is being set.
sampleTimeIdx
Sample time index.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify the index of

the sample time for the port to be used in mdlOutputs and mdlOutputs when
checking for sample hits.

Note This should only be used when the PORT_BASED_SAMPLE_TIMES has been
specified for ssSetNumSampleTimes in mdlInitializeSizes.

Languages C, C++

See Also ssGetInputPortSampleTimeIndex, mdlInitializeSizes,

ssSetNumInputPorts, mdlOutputs, mdlOutputs

10-149
ssSetInputPortVectorDimension

Purpose 10ssSetInputPortVectorDimension
Specify dimension information for an input port that accepts vector signals.

Syntax void ssSetInputPortVectorDimension(SimStruct *S, int_T port, int_T

w)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port
w
Width of vector or DYNAMICALLY_SIZED

Description Specifies that port accepts a w-element vector signal.

Note This macro and ssSetInputPortWidth are functionally identical.

Languages C

Example The following example specifies that input port 0 accepts an 8-element matrix
signal.
ssSetInputPortVectorDimension(S, 0, 8);

See Also ssSetInputPortDimensionInfo, ssSetInputPortWidth

10-150
 ssSetInputPortWidth

Purpose 10ssSetInputPortWidth
Specify the number of input ports that a block has.

C Syntax void ssSetInputPortWidth(SimStruct *S, int_T port, int_T width)

Ada Syntax procedure ssSetInputPortWidth (S : in SimStruct;

port : in Integer := 0; width : in Integer);

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of the input port whose width is being set.
width
Width of input port.

Description Use in mdlInitializeSizes (after ssSetNumInputPorts) to specify a nonzero

positive integer width or DYNAMICALLY_SIZED for each input port index starting
at 0r

Languages Ada, C

See Also ssSetNumInputPorts, ssSetOutputPortWidth

10-151
ssSetModeVectorValue

Purpose 10ssSetModeVectorValue
Set an element of a block’s mode vector.

Syntax void ssSetModeVectorValue(SimStruct *S, int_T element, int_T value)

Arguments S
SimStruct representing an S-function block.
element
Index of a mode vector element
value
Mode vector value

Description Sets the specified mode vector element to the specified value.

Languages C, C++

See Also ssGetModeVectorValue, ssGetModeVector

10-152
 ssSetNumContStates

Purpose 10ssSetNumContStates
Specify the number of continuous states that a block has.

C Syntax void ssSetNumContStates(SimStruct *S, int_T n)

Ada Syntax procedure ssSetNumContStates(S : in SimStruct; n : in Integer);

Arguments S
SimStruct representing an S-function block.
n
Number of continuous states to be set for the block represented by S.

Description Use in mdlInitializeSizes to specify the number of continuous states as 0, a

positive integer, or DYNAMICALLY_SIZED. If you specify DYNAMICALLY_SIZED, you
can specify the true (positive integer) width in mdlSetWorkWidths, otherwise
the width to is the width of the signal passing through the block. If your
S-function has continuous states, it needs to return the derivatives of the states
in mdlDerivatives so that the solvers can integrate them. Continuous states
are logged if the States option is checked on the Workspace I/O pane of the
Simulation Parameters dialog box.

Languages Ada, C

See Also ssSetNumDiscStates, ssGetNumContStates

10-153
ssSetNumDiscStates

Purpose 10ssSetNumDiscStates
Specify the number of discrete states that a block has.

Syntax ssSetNumDiscStates(SimStruct *S, int_T nDiscStates)

Arguments S
SimStruct representing an S-function block.
nDiscStates
Number of discrete states to be set for the block represented by S.

Description Use in mdlInitializeSizes to specify the number of discrete states as 0, a

positive integer, or DYNAMICALLY_SIZED. If you specify DYNAMICALLY_SIZED, you
can specify the true (positive integer) width in mdlSetWorkWidths, otherwise
the width used is the width of the signal passing through the block. If your
S-function has discrete states, it should return the next discrete state (in place)
in mdlUpdate. Discrete states are logged if the States is checked on the
Workspace I/O page of the Simulation Parameters dialog box.

Languages C

See Also ssSetNumContStates, ssGetNumDiscStates

10-154
 ssSetNumDWork

Purpose 10ssSetNumDWork
Specify the number of data type work vectors used by a block.

Syntax void ssSetNumDWork(SimStruct *S, int_T nDWork)

Arguments S
SimStruct representing an S-function block.
DWork
Number of data type work vectors.

Description Use in mdlInitializeSizes to specify the number of data type work vectors as
0, a positive integer, or DYNAMICALLY_SIZED. If you specify DYNAMICALLY_SIZED,
you can specify the true (positive integer) number of vectors in
mdlSetWorkWidths.

You can specify the size and data type of each work vector, using the macros
ssSetDWorkWidth and ssSetDWorkDataType, respectively. You can also specify
that the work vector holds complex values, using ssSetDWorkComplexSignal.

Languages C, C++

See Also ssGetNumDWork, ssSetDWorkWidth, ssSetDWorkDataType,

ssSetDWorkComplexSignal

10-155
ssSetNumInputPorts

Purpose 10ssSetNumInputPorts
Specify the number of input ports that a block has.

C Syntax void ssSetNumInputPorts(SimStruct *S, int_T nInputPorts)

Ada Syntax procedure ssSetNumInputPorts(S : in SimStruct;

nInputPorts : in Integer);

Arguments S
SimStruct representing an S-function block.
nInputPorts
Number of input ports on the block represented by S. Must be a nonnegative
integer.

Description Used in mdlInitializeSizes to set to the number of input ports to a

nonnegative integer. It should be invoked using
if (!ssSetNumInputPorts(S,nInputPorts)) return;

where ssSetNumInputPorts returns 0 if nInputPorts is negative or an error

occurred while creating the ports. When this occurs, Simulink displays an
error.

Languages Ada, C

See Also ssSetInputPortWidth, ssSetNumOutputPorts

10-156
 ssSetNumIWork

Purpose 10ssSetNumIWork
Specify the size of a block’s integer work vector.

Syntax void ssSetNumIWork(SimStruct *S, int_T nIWork)

Arguments S
SimStruct representing an S-function block.
nIWork
Number of elements in the integer work vector.

Description Use in mdlInitializeSizes to specify the number of int_T work vector

elements as 0, a positive integer, or DYNAMICALLY_SIZED. If you specify
DYNAMICALLY_SIZED, you can specify the true (positive integer) width in
mdlSetWorkWidths, otherwise the width used is the width of the signal passing
through the block.

Languages C

See Also ssSetNumRWork, ssSetNumPWork

10-157
ssSetNumModes

Purpose 10ssSetNumModes
Specifies the size of the block’s mode vector.

Syntax ssSetNumModes(SimStruct *S,nModes)

Arguments S
SimStruct representing an S-function block.
nModes
Size of the mode vector for the block represented by S. Valid values are 0, a
positive integer, or DYNAMICALLY_SIZED.

Description Sets the size of the block’s mode vector to nModes. If nModes is
DYNAMICALLY_SIZED, you can specify the true (positive integer) width in
mdlSetWorkWidths, otherwise the width used is the width of the signal passing
through the block. Use this macro in mdlInitializeSizes to specify the
number of int_T elements in the mode vector. Simulink allocates the mode
vector and initializes its elements to 0. If the default value of 0 is not
appropriate, you can set the elements of the array to other initial values in
mdlInitializeConditions. Use ssGetModeVector to access the mode vector.

The mode vector, combined with zero-crossing detection, allows you to create
blocks that have distinct operating modes, depending on the current values of
input or output signals. For example, consider a block that outputs the absolute
value of its input. Such a block operates in two distinct modes, depending on
whether its input is positive or negative. If the input is positive, the block
outputs the input unchanged. If the input is negative, the block outputs the
negative of the input. You can use zero-crossing detection to detect when the
input changes sign and update the single-element mode vector accordingly (for
example, by setting its element to 0 for negative input and 1 for positive input).
You can then use the mode vector in mdlOutputs to determine the mode in
which the block is currently operating.

Languages C

See Also ssGetNumModes, ssGetModeVector

10-158
 ssSetNumNonsampledZCs

Purpose 10ssSetNumNonsampledZCs
Specify the number of states for which a block detects zero crossings that occur
between sample points.

Syntax ssSetNumNonsampledZCs(SimStruct *S, nNonsampledZCs)

Arguments S
SimStruct representing an S-function block.
nNonsampledZCs
Number of nonsampled zero crossings that a block detects.

Description Use in mdlInitializeSizes to specify the number of states for which the block
detects nonsampled zero crossings (real_T) as 0, a positive integer, or
DYNAMICALLY_SIZED. If you specify DYNAMICALLY_SIZED, you can specify the
true (positive integer) width in mdlSetWorkWidths, otherwise the width to be
used will be the width of the signal passing through the block.

Languages C

See Also ssSetNumModes

10-159
ssSetNumOutputPorts

Purpose 10ssSetNumOutputPorts
Specify the number of output ports that a block has.

C Syntax void ssSetNumInputPorts(SimStruct *S, int_T nOutputPorts)

Ada Syntax procedure ssSetNumOutputPorts(S : in SimStruct;

nOutputPorts : in Integer);

Arguments S
SimStruct representing an S-function block.
nOutputPorts
Number of output ports on the block represented by S. Must be a nonnegative
integer.

Description Use in mdlInitializeSizes to set to the number of output ports to a

nonnegative integer. It should be invoked using
if (!ssSetNumOutputPorts(S,nOutputPorts)) return;

where ssSetNumOutputPorts returns a 0 if nOutputPorts is negative or an

error occurred while creating the ports. When this occurs, and you return out
of your S-function, Simulink will display an error message.

Languages Ada, C

See Also ssSetInputPortWidth, ssSetNumInputPorts

10-160
 ssSetNumPWork

Purpose 10ssSetNumPWork
Specify the size of a block’s pointer work vector.

Syntax void ssSetNumPWork(SimStruct *S, int_T nPWork)

Arguments S
SimStruct representing an S-function block.
nPWork
Number of elements to be allocated to the pointer work vector of the block
represented by S.

Description Use in mdlInitializeSizes to specify the number of pointer (void *) work

vector elements as 0, a positive integer, or DYNAMICALLY_SIZED. If you specify
DYNAMICALLY_SIZED, you can specify the true (positive integer) width in
mdlSetWorkWidths, otherwise the width used is the width of the signal passing
through the block.

Languages C

See Also ssSetNumIWork, ssSetNumPWork

10-161
ssSetNumRunTimeParams

Purpose 10ssSetNumRunTimeParams
Specify the number of run-time parameters created by this S-function.

Syntax void ssSetNumRunTimeParams(S, int_T num)

Arguments S
SimStruct representing an S-function block.
num
Number of run-time parameters

Description Use this function in mdlSetWorkWidths to specify the number of run-time

parameters created by this S-function.

Languages C

See Also mdlSetWorkWidths, ssGetNumRunTimeParams, ssSetRunTimeParamInfo

10-162
 ssSetNumRWork

Purpose 10ssSetNumRWork
Specify the size of a block’s floating-point work vector.

Syntax void ssSetNumRWork(SimStruct *S, int_T nRWork)

Arguments S
SimStruct representing an S-function block.
nRWork
Number of elements in the floating-point work vector.

Description Use in mdlInitializeSizes to specify the number of real_T work vector

elements as 0, a positive integer, or DYNAMICALLY_SIZED. If you specify
DYNAMICALLY_SIZED, you can specify the true (positive integer) width in
mdlSetWorkWidths, otherwise the width used is the width of the signal passing
through the block.

Languages C

See Also ssSetNumIWork, ssSetNumPWork

10-163
ssSetNumSampleTimes

Purpose 10ssSetNumSampleTimes
Specify the number of sample times that an S-function block has.

Syntax void ssSetNumSampleTimes(SimStruct *S, int_T nSampleTimes)

Arguments S
SimStruct representing an S-function block.
nSampleTimes
Number of sample times that S has.

Description Use in mdlInitializeSizes to set the number of sample times S has. This
must be a positive integer greater than 0.

Languages C

See Also ssGetNumSampleTimes

10-164
 ssSetNumSFcnParams

Purpose 10ssSetNumSFcnParams
Specify the number of parameters that an S-function block has.

Syntax ssSetNumSFcnParams(SimStruct *S, int_T nSFcnParams)

Arguments S
SimStruct representing an S-function block.
nSFcnParams
Number of parameters that S has.

Description Use in mdlInitializeSizes to set the number of S-function parameters.

Languages C

See Also ssGetSFcnNumParams

10-165
ssSetOffsetTime

Purpose 10ssSetOffsetTime
Set the offset time of a block.

Syntax ssSetOffsetTime(SimStruct *S, st_index, period)

Arguments S
SimStruct representing an S-function block.
st_index
Index of sample time whose offset is to be set.
offset
Offset of the sample time specified by st_index

Description Use this macro in mdlInitializeSizes to specify the offset of the sample time
where st_index starts at 0.

Languages C

See Also ssSetSampleTime, ssSetInputPortOffsetTime, ssSetOutputPortOffsetTime

10-166
 ssSetOptions

Purpose 10ssSetOptions
Specify S-function options.

Syntax void ssSetOptions(SimStruct *S, uint_T options)

Arguments S
SimStruct representing an S-function block.
options
Options

Description Use in mdlInitializeSizes to specifiy S-function options (see below). The

options must be joined using the OR operator. For example:
ssSetOption(S, (SS_OPTION_EXCEPTION_FREE_CODE |
SS_OPTION_DISCRETE_VALUED_OUTPUT));

S-Function Options
An S-function can specify the following options, using ssSetOptions:
• SS_OPTION_EXCEPTION_FREE_CODE
If your S-function does not use mexErrMsgTxt, mxCalloc, or any other
routines that can throw an exception when called, you can set this option for
improved performance.
• SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE
Similar to SS_OPTION_EXCEPTION_FREE_CODE except it only applies to the
“run-time” routines: mdlGetTimeOfNextVarHit, mdlOutputs, mdlUpdate, and
mdlDerivatives.
• SS_OPTION_DISCRETE_VALUED_OUTPUT
Specify this if your S-function has discrete valued outputs. This is checked
when your S-function is placed within an algebraic loop. If your S-function
has discrete valued outputs, then its outputs will not be assigned algebraic
variables.
• SS_OPTION_PLACE_ASAP
Used to specify that your S-function should be placed as soon as possible.
This is typically used by devices connecting to hardware.

10-167
ssSetOptions

• SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION
Used to specify that the input to your S-function input ports can be either 1
or the size specified by the port, which is usually referred to as the block
width.
• SS_OPTION_DISALLOW_CONSTANT_SAMPLE_TIME
Use to disable an S-function block from inheriting a constant sample time.
• SS_OPTION_ASYNCHRONOUS
This option applies only to S-functions that have 0 or 1 input ports and 1
output port. The output port must be configured to perform function calls on
every element. If any of these requirements are not met, the
SS_OPTION_ASYNCHRONOUS is ignored. Use this option when driving
function-call subsystems that will be attached to interrupt service routines.
• SS_OPTION_ASYNC_RATE_TRANSITION
Use this when your S-function converts a signal from one rate to another
rate.
• SS_OPTION_RATE_TRANSITION
Use this option when your S-function is behaving as a unit delay or a ZOH.
This macro support these two operations only. It identifies a unit delay by the
presence of mdlUpdate; if mdlUpdate is absent, the operation is taken to be
ZOH.
• SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED
Use this when you have registered multiple sample times
(ssSetNumSampleTimes > 1) to specify the rate at when each input and
output port is running at. The simulation engine needs this information
when checking for illegal rate transitions.
• SS_OPTION_SFUNCTION_INLINED_FOR_RTW
Set this if you have a .tlc file for your S-function and do not have a mdlRTW
method. Setting option has no effect if you have a mdlRTW method.
• SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL
Indicates that the S-function can handle dynamically dimensioned signals.
See mdlSetInputPortDimensions, mdlSetOutputPortDimensions, or
mdlSetDefaultPortDimensions for more information.

10-168
 ssSetOptions

• SS_OPTION_FORCE_NONINLINED_FCNCALL
Use this flag if the block requires that all function-call subsystems that it
calls should be generated as procedures instead of possibly being generated
as inlined code.
• SS_OPTION_USE_TLC_WITH_ACCELERATOR
Use this to force the Accelerator to use the TLC inlining code for a S-function
which will speed up execution of the S-function. By default, the Accelerator
will use the mex version of the S-function even though a TLC file for the
S-function exists. This option should not be set for device driver blocks (A/D)
or when there is an incompatability between running the mex Start/
InitializeConditions functions together with the TLC Outputs/Update/
Derivatives.
• SS_OPTION_SIM_VIEWING_DEVICE
This S-function is a SimViewingDevice. As long as it meets the other
requirement for this type of block (no states, no outputs, etc), it will be
considered to be an external mode block (show up in the external mode GUI
and no code is generated for it). During an external mode simulation, this
block is run on the host only.
• SS_OPTION_CALL_TERMINATE_ON_EXIT
This option allows S-function authors to better manage the data cached in
run-time parameters and UserData. Setting this option guarantees that the
mdlTerminate function is called if mdlInitializeSizes is called. This means
that mdlTerminate is called:

- When a simulation ends.

Note that it does not matter if the simulation failed and at what stage the
simulation failed. Therefore, if the mdlSetWorkWidths of some block errors
out, the model’s other blocks have a chance to free the memory during a
call to mdlTerminate.
- Every time an S-function block is destroyed.
- If the user is editing the S-function graphically.
- If the S-function block was reduced as a result of invoking
ssSetBlockReduction.
If this option is not set, mdlTerminate is called only if at least one of the
blocks has had its mdlStart called.

10-169
ssSetOptions

• SS_OPTION_REQ_INPUT_SAMPLE_TIME_MATCH
Use this to option to specify that the input signal sample time(s) match the
sample time assigned to the block input port. For example,

S-function
src(0.1) Port-based Ts = 1

generates an error if this option is set. If the block (or input port) sample
time is inherited, then there will be no error generated.

Languages C, C++

10-170
 ssSetOutputPortComplexSignal

Purpose 10ssSetOutputPortComplexSignal
Set the numeric type (real or complex) of an output port.

Syntax void ssSetOutputPortComplexSignal(SimStruct *S, input_T port,

CSignal_T csig)

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an output port
csignal
Numeric type of the signals emitted by port. Valid values are COMPLEX_NO (real
signal), COMPLEX_YES (complex signal), COMPLEX_INHERITED (dynamically
determined).

Description Use this function in mdlInitializeSizes to initialize input port signal type. If
the numeric type of the input port is determined dynamically, e.g., by a
parameter setting, set the numeric type to COMPLEX_INHERITED. The default
numeric type of an output port is real.

Languages C

Example Assume that an S-function has three output ports. The first output port emits
real (non-complex) signals. The second input port emits a complex signal. The
third port emits signals of a type determined by a parameter setting. The
following example specifies the correct numeric type for each port.
ssSetOutputPortComplexSignal(S, 0, COMPLEX_NO)
ssSetOutputPortComplexSignal(S, 1, COMPLEX_YES)
ssSetOutputPortComplexSignal(S, 2, COMPLEX_INHERITED)

See Also ssGetOutputPortComplexSignal

10-171
ssSetOutputPortDataType

Purpose 10ssSetOutputPortDataType
Set the data type of an output port.

C Syntax void ssSetOutputPortDataType(SimStruct *S, input_T port, DTypeId id)

Ada Syntax procedure ssSetOutputPortDataType(S : in SimStruct;

port : in Integer := 0; id : in Integer);

Arguments S
SimStruct representing an S-function block or a Simulink model.
port
Index of an input port
id
Id of data type accepted by port

Description Use this function in mdlInitializeSizes to set the data type of the output port
specified by port. If the input port’s data type is determined dynamically, for
example, from the data type of a block parameter, set the data type to
DYNAMICALLY_TYPED.

Note The data type of an output port is double (real_T) by default.

Languages Ada, C

Example Suppose that you want to create an S-function with two input ports, the first of
which gets its data type from a block parameter and the second of which
outputs signals of type int16_T. The following code sets up the data types.
ssSetInputPortDataType(S, 0, DYNAMICALLY_TYPED)
ssSetInputPortDataType(S, 1, SS_INT16)

See Also ssGetOutputPortDataType

10-172
 ssSetOutputPortDimensionInfo

Purpose 10ssSetOutputPortDimensionInfo
Specify information about the dimensionality of an output port.

Syntax void ssSetInputPortDimensionInfoSimStruct *S, int_T port,

DimsInfo_T *dimsInfo)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port
dimsInfo
Structure of type DimsInfo_T that specifies the dimensionality of the signals
emitted by port
See ssSetInputPortDimensionInfo for a description of this structure.

Description Specifies the dimension information for port. Use this function in
mdlInitializeSizes to initialize the output port dimension info. If you want
the port to inherit its dimensionality from the block to which it is connected,
specify DYNAMIC_DIMENSION as the dimsInfo for port.

Languages C

Example The following example specifies that input port 0 accepts 2-by-2 matrix signals.
DECL_AND_INIT_DIMSINFO(di);
di.numDims = 2;
int dims[2];
dims[0] = 2;
dims[1] = 2;
di.dims = &dims;
di.width = 4;
ssSetOutputPortDimensionInfo(S, 0, &di);

See Also ssSetInputPortDimensionInfo

10-173
ssSetOutputPortFrameData

Purpose 10ssSetOutputPortFrameData
Specify whether a port outputs framed data.

Syntax void ssSetOutputPortFrameData(SimStruct *S, int_T port,

int_T outputsFrames)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port
outputsFrames
Type of signal output by port. Acceptable values are -1 (either frame or
unframed input), 0 (unframed input only), 1 (framed input only).

Description Use in mdlSetInputPortFrameData to specify whether an output port issues

frame data only, unframed data only, or both.

Languages C

See Also ssGetOutputPortFrameData, mdlSetInputPortFrameData

10-174
 ssSetOutputPortMatrixDimensions

Purpose 10ssSetOutputPortMatrixDimensions
Specify dimension information for an output port that emits matrix signals.

Syntax void ssSetOutputPortMatrixDimensions(SimStruct *S, int_T port,

int_T m, in_T n)

Arguments S
SimStruct representing an S-function block.
port
Index of an input port
m
Row dimension of matrix signals emitted by port or DYNAMICALLY_SIZED
n
Column dimension of matrix signals emitted by port or DYNAMICALLY_SIZED

Description Specifies that port emits an m-by-n matrix signal. If either dimension is
DYNAMICALLY_SIZED, the other must be DYNAMICALLY_SIZED or 1.

Languages C

Example The following example specifies that input port 0 emits 2-by-2 matrix signals.
ssSetOutputPortDimensionInfo(S, 0, 2, 2);

See Also ssSetOutputPortDimensionInfo

10-175
ssSetOutputPortOffsetTime

Purpose 10ssSetOutputPortOffsetTime
Specify the offset time of an output port.

Syntax ssSetOutputPortOffsetTime(SimStruct *S,outputPortIdx,offset)

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of the output port whose sample time is being set.
period
Sample time of output port.

Description Use in mdlInitializeSizes (after ssSetNumOutputPorts) to specify the

sample time offset value for each output port index. This should only be used if
you have specified the S-function’s sample times as port-based.

Languages C

See Also ssSetNumOutputPorts, ssSetOutputPortSampleTime

10-176
 ssSetOutputPortReusable

Purpose 10ssSetOutputPortReusable
Specify that an output port is reusable.

Syntax ssSetOutputPortReusable(SimStruct *S,outputPortIdx,isReusable)

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of the output port whose reusability is being set.
isReusable
Value specifying reusability of port

Description Use in mdlInitializeSizes (after ssSetNumOutputPorts) to specify whether

output ports have a test point. This macro can take on two values:

• Off (isReusable=0) — specifies that the output port is not reusable. This is
the default.
• On (isReusable=1) — specifies that the output port is reusable.

In Simulink, reusable signals share the same memory space. When this macro
is turned on, the output port signal to the S-function may be reused by other
signals in the model. This reuse results in less memory use during Simulink
simulation and more efficiency in the Real-Time Workshop generated code.
When you mark an output port as reusable, your S-function must update the
output once in mdlOutputs. It cannot expect the previous output value to be
persistent.
By default, the output port signals are not reusable. This forces Simulink’s
simulation engine (and the Real-Time Workshop) to allocate global memory for
these output port signals. Hence this memory is only written to by your
S-function and persists between model execution steps.

Languages C

See Also ssSetNumOutputPorts, ssSetInputPortReusable

10-177
ssSetOutputPortSampleTime

Purpose 10ssSetOutputPortSampleTime
Specify the sample time of an output port.

Syntax ssSetOutputPortSampleTime(SimStruct *S,outputPortIdx,period)

Arguments S
SimStruct representing an S-function block.
outputPortIdx
Index of the output port whose sample time is being set.
period
Sample time of output port.

Description Use in mdlInitializeSizes (after ssSetNumOutputPorts) to specify the

sample time period as continuous or as a discrete value for each output port
index. This should only be used if you have specified port-based sample times.

Languages C

See Also ssSetNumOutputPorts, ssSetOutputPortOffsetTime

10-178
 ssSetOutputPortVectorDimension

Purpose 10ssSetOutputPortVectorDimension
Specify dimension information for an output port that emits vector signals.

Syntax void ssSetOutputPortVectorDimension(SimStruct *S, int_T port, int_T

w)

Arguments S
SimStruct representing an S-function block.
port
Index of an output port
w
Width of vector or DYNAMICALLY_SIZED

Description Specifies that port emits a w-element vector signal.

Note This macro and ssSetOutputPortWidth are functionally identical.

Example The following example specifies that output port 0 emits an 8-element matrix
signal.
ssSetOutputPortVectorDimension(S, 0, 8);

Languages C

See Also ssSetOutputPortDimensionInfo, ssSetOutputPortWidth

10-179
ssSetOutputPortWidth

Purpose 10ssSetOutputPortWidth
Specify the width of an output port.

C Syntax void ssSetOutputPortWidth(SimStruct *S, int_T port, int_T width)

Ada Syntax procedurw ssSetOutputPortWidth(S : in SimStruct;

port : in Integer := 0; Width : in Integer);

Arguments S
SimStruct representing an S-function block.
port
Index of the output port whose width is being set.
width
Width of output port.

Description Use in mdlInitializeSizes (after ssSetNumOutputPorts) to specify a nonzero

positive integer width or DYNAMICALLY_SIZED for each output port index
starting at 0.

Languages Ada, C

See Also ssSetNumOutputPorts, ssSetInputPortWidth

10-180
 ssSetParameterName

Purpose 10ssSetParameterName
Set the name of a parameter.

Syntax procedure ssSetParameterName (S : in SimStruct; Parameter : in

Integer; Name : in String);

Arguments S
SimStruct representing an S-function block.
Parameter
Index of a parameter
Name
Name of the parameter

Description Sets the name of Parameter to Name.

Languages Ada

10-181
ssSetParameterTunable

Purpose 10ssSetParameterTunable
Set the tunability of a parameter.

Syntax procedure ssSetParameterTunable (S : in SimStruct; Parameter : in

Integer; IsTunable : in Boolean);

Arguments S
SimStruct representing an S-function block.
Parameter
Index of a parameter
IsTunable
true indicates that the parameter is tunable.

Description Sets the tunability of Parameter to the value of IsTunable.

Languages Ada

10-182
 ssSetPlacementGroup

Purpose 10ssSetPlacementGroup
Specify the name of the placement group of a block.

Syntax void ssSetPlacementGroup(SimStruct *S, const char *groupName)

Arguments S
SimStruct representing an S-function block. The block must be either a source
block (i.e., a block without input ports) or a sink block (i.e., a block without
output ports).
groupName
Name of placement group name of the block represented by S.

Description Use this macro to specify the name of the placement group to which the block
represented by S belongs. S-functions that share the same placement group
name are placed adjacent to each other in the block execution order list for the
model. This macro should be invoked in mdlInitializeSizes.

Note This macro is typically used to create Real-Time Workshop device

driver blocks.

Languages C

See Also ssGetPlacementGroup

10-183
ssSetRunTimeParamInfo

Purpose 10ssSetRunTimeParamInfo
Specify the attributes of a run-time parameter.

Syntax void ssSetRunTimeParamInfo(SimStruct *S, int_T param, ssParamRec

*info)

Arguments S
SimStruct representing an S-function block.
param
Index of a run-time parameter

Description Use this function in mdlSetWorkWidths or mdlProcessParameters to specify

information about a run-time parameter. Use a ssParamRec structure to pass
the parameter attributes to the function.

ssParamRec Structure
The simstruc.h macro defines this structure as follows.
typedef struct ssParamRec_tag {
const char *name;
int_T nDimensions;
int_T *dimensions;
DTypeId dataTypeId;
boolean_T complexSignal;
void *data;
const void *dataAttributes;
int_T nDlgParamIndices;
int_T *dlgParamIndices;
TransformedFlag transformed; /* Transformed status */
boolean_T outputAsMatrix; /* Write out parameter as a
vector (false)
* [default] or a matrix (true)
*/
} ssParamRec;

The record contains the following fields.

name. Name of the parameter. This must point to persistent memory. Do not
set to a local variable (static char name[32] or strings name are okay).
nDimensions. Number of dimensions that this parameter has

10-184
 ssSetRunTimeParamInfo

dimensions. Array giving the size of each dimension of the parameter

dataTypeId. Data type of the parameter. For built-in data types, see
BuiltInDTypeId in simstruc_types.h.

complexSignal. Specifies whether this parameter has complex numbers (TRUE) or

real numbers (FALSE) as values.
data. Pointer to value of this run-time parameter. If the parameter is a vector
or matrix or a complex number, this field points to an array of values
representing the parameter elements. Complex Simulink signals are store
interleaved. Likewise complex run-time parameters must be stored
interleaved. Note that mxArrays store the real and complex parts of complex
matrices as two separate contiguous pieces of data instead of interleaving the
real and complex parts.
dataAttributes. The data attributes pointer is a persistent storage location where
the S-function can store additional information describing the data and then
recover this information later (potentially in a different function).
nDlgParamIndices.

Number of dialog parameters used to compute this run-time parameter.

dlgParamIndices. Indices of dialog parameters used to compute this run-time
parameter
transformed. Specifies the relationship between this run-time parameter and
the dialog parameters specified by dlgParamIndices. This field may have any
of the following values defined by TransformFlag in simstruc.h.
• RTPARAM_NOT_TRANSFORMED
Specifies that this run-time parameter corresponds to a single dialog
parameter (nDialogParamIndices is one) and has the same value as the
dialog parameter.
• RTPARAM_TRANSFORMED
Specifies that the value of this run-time parameter depends on the values of
multiple dialog parameters (nDialogParamIndices > 1) or that this
run-time parameter corresponds to one dialog parameter but has a different
value or data type.

10-185
ssSetRunTimeParamInfo

• RTPARAM_MAKE_TRANSFORMED_TUNABLE
Specifies that this run-time parameter corresponds to a single tunable dialog
parameter (nDialogParamIndices is one) and that the run-time parameter’s
value or data type differs from the dialog parameter’s. During code
generation, Real-Time Workshop writes the data type and value of the
run-time parameter (rather than the dialog parameter) out to the Real-Time
Workshop file. For example, suppose that the dialog parameter contains a
workspace variable, k, of type double and value 1. Further, suppose the
S-function sets the data type of the corresponding run-time variable to int8
and the run-time parameter’s value to 2. In this case, during code generation,
the Real-Time Workshop writes k out to the Real-Time Workshop file as an
int8 variable with an initial value of 2.

outputAsMatrix. Specifies whether to write the value(s) of this parameter out to

the model.rtw file has a matrix (TRUE) or as a vector (FALSE).

Languages C

See Also mdlSetWorkWidths, mdlProcessParameters, ssGetNumRumTimeParams,

ssGetRunTimeParamInfo

10-186
 ssSetSampleTime

Purpose 10ssSetSampleTime
Set the period of a sample time.

C Syntax void ssSetSampleTime(SimStruct *S, st_index, time_T period)

Ada Syntax procedure ssSetSampleTime(S : in SimStruct; Period : in time_T;

st_index : in time_T := 0.0);

Arguments S
SimStruct representing an S-function block.
st_index
Index of sample time whose period is to be set.
period
Period of the sample time specified by st_index

Description Use this macro in mdlInitializeSizes to specify the “period” of the sample
time where st_index starts at 0.

Languages Ada, C

See Also ssGetSampleTime, ssSetInputPortSampleTime, ssSetOutputPortSampleTime,

ssSetOffsetTime

10-187
ssSetSFcnParamNotTunable

Purpose 10ssSetSFcnParamNotTunable
Make a block parameter untunable.

Syntax void ssSetSFcnParamNotTunable(SimStruct *S, int_T index)

Arguments S
SimStruct representing an S-function block.
index
Index of parameter to be made untunable.

Description Use this macro in mdlInitializeSizes to specify that a parameter doesn’t

change during the simulation, where index starts at 0 and is less than
ssGetSFcnParamsCount(S). This will improve efficiency and provide error
handling in the event that an attempt is made to change the parameter.

Note This macro is obsolete. It is provided only for compatibility with

S-functions created with earlier versions of Simulink

Languages C

See Also ssSetSFcnParamTunable, ssGetSFcnParamsCount

10-188
 ssSetSFcnParamTunable

Purpose 10ssSetSFcnParamTunable
Make a block parameter tunable.

Syntax void ssSetSFcnParamTunable(SimStruct *S, int_T param,

int_T isTunable)

Arguments S
SimStruct representing an S-function block.
param
Index of parameter
isTunable
Valid values are 1 (tunable) or 0 (not tunable)

Description Use this macro in mdlInitializeSizes to specify whether a user can change a
dialog parameter during the simulation. The parameter index starts at 0 and
is less than ssGetSFcnParamsCount(S). This improves efficiency and provide
errors handling in the event that an attempt is made to change the parameter.

Note Dialog parameters are tunable by default. However, an S-function

should declare the tunability of all parameters, whether tunable or not, to
avoid programming errors. If the user enables the simulation diagnostic,
S-function upgrade needed, Simulink issues the diagnostic whenever it
encounters an S-function that fails to specify the tunability of all its
parameters.

Languages C

See Also ssGetSFcnParamsCount

10-189
ssSetSolverNeedsReset

Purpose 10ssSetSolverNeedsReset
Ask Simulink to reset the solver.

Syntax void ssSetSolverNeedsReset(SimStruct *S)

Arguments S
SimStruct representing an S-function block or a Simulink model.

Description This macro causes the solver for the current simulation to reinitialize variable
step size and zero-crossing computations. This happens only if the solver is a
variable-step, continuous solver. (The macro has no effect if the user has
selected another type of solver for the current simulation.) An S-function
should invoke this macro whenever changes occur in the dynamics of the
S-function, e.g., a discontinuity in a state or output, that might invalidate the
solver’s step-size computations. Otherwise, the solver might take
unnecessarily small steps, slowing down the simulation.

Note If a change in the dynamics of the S-function necessitates reinitializing

its continuous states, the S-function should reinitialize the states before
invoking this macro to assure accurate computation of the next step size.

Languages C

Example The following example uses this macro to ask Simulink to reset the solver.
static void mdlOutputs(SimStruct *S, int_T tid)
{
:
: <snip>
:
if ( under_certain_conditions ) {
double *x = ssGetContStates(S);
/* reset the states */
for (i=0; i<nContStates; i++) {
x[i] = 0.0;
}
/* Ask Simulink to reset the solver. */
ssSetSolverNeedsReset(S);

10-190
 ssSetSolverNeedsReset

}
}

Also see the source code for the Time-Varying Continuous Transfer Function
(matlabroot/simulink/src/stvctf.c) for an example of where and how to use
this macro.

10-191
ssSetStopRequested

Purpose 10ssSetStopRequested
Set the simulation stop requested flag.

Syntax ssSetStopRequested(SimStruct *S, val)

Arguments S
SimStruct representing an S-function block or a Simulink model.
val
Boolean value (int_T) specifying whether stopping the simulation has been
requested (1) or not (0).

Description Sets the simulation stop requested flag to val. If val is not zero, Simulink halts
the simulation at the end of the current time step.

Languages C

See Also ssGetStopRequested

10-192
 ssSetTNext

Purpose 10ssSetTNext
Set the time of the next sample hit.

Syntax void ssSetTNext(SimStruct *S, time_T tnext)

Arguments S
SimStruct representing an S-function block
tnext
Time of the next sample hit

Description A discrete S-function with a variable sample time should use this macro in
mdlGetTimeOfNextVarHit to specify the time of the next sample hit.

Languages C

See Also ssGetTNext, ssGetT, mdlGetTimeOfNextVarHit

10-193
ssSetUserData

Purpose 10ssSetUserData
Specify user data.

Syntax void ssSetUserData(SimStruct *S, void * data)

Arguments S
SimStruct representing an S-function block.
data
User data

Description Specifies user data.

Languages C, C++

See Also ssGetUserData

10-194
 ssSetVectorMode

Purpose 10ssSetVectorMode
Specify the vector mode that an S-function supports.

Syntax void ssSetVectorMode(SimStruct *S, ssVectorMode mode)

Arguments S
SimStruct representing an S-function block.
mode
vector mode

Description Specifies the types of vector-like signals that an S-function block’s input and
output ports support. Simulink uses this information during signal dimension
propagation to check the validity of signals connected to the block or emitted
by the block. The enumerate type, ssVectorMode, defines the set of values that
mode can have.

Mode Value Signal Dimensionality Supported

SS_UNKNOWN_MODE Unknown
SS_1_D_OR_COL_VECT 1-D (vector) or single-column 2-D (column
vector)
SS_1_D_OR_ROW_VECT 1-D or single-row 2-D (row vector) signals
SS_1_D_ROW_OR_COL_VECT Vector or row or column vector
SS_1_D_VECT Vector
SS_COL_VECT Column vector
SS_ROW_VECT Row vector

Languages C

Example See simulink/src/sfun_bitop.c for examples that use this macro.

10-195
ssUpdateAllTunableParamsAsRunTimeParams

Purpose 10ssUpdateAllTunableParamsAsRunTimeParams
Updates the values of run-time parameters to be the same as those of the
corresponding tunable dialog parameters.

Syntax void ssUpdateAllTunableParamsAsRunTimeParams(SimStruct *S)

Arguments S

Description Use this macro in the S-function’s mdlProcessParameters method to update

the values of all run-time parameters created by the
ssRegAllTunableParamsAsRunTimeParam macro.

Languages C

See Also mdlProcessParameters, ssUpdateRunTimeParamInfo,

ssRegAllTunableParamsAsRunTimeParams

10-196
 ssUpdateRunTimeParamData

Purpose 10ssUpdateRunTimeParamData
Updates the value of a run-time parameter.

Syntax void ssUpdateRunTimeParamInfo(SimStruct *S, int_T param, void *data)

Arguments S
SimStruct representing an S-function block.
param
Index of a run-time parameter
data
New value of the parameter

Description Use this macro in the S-function’s mdlProcessParameters method to update

the value of the run-time parameter specified by param.

Languages C

See Also mdlProcessParameters, ssGetRunTimeParamInfo,

ssUpdateAllTunableParamsAsRunTimeParams,
ssRegAllTunableParamsAsRunTimeParams

10-197
ssUpdateRunTimeParamInfo

Purpose 10ssUpdateRunTimeParamInfo
Updates the attributes of a run-time parameter.

Syntax void ssUpdateRunTimeParamInfo(SimStruct *S, int_T param, ssParamRec

*info)

Arguments S
SimStruct representing an S-function block.
param
Index of a run-time parameter
info
Attributes of the run-time parameter

Description Use this macro in the S-function’s mdlProcessParameters method to update

specific run-time parameters. For each parameter to be updated, the method
should first obtain a pointer to the parameter’s attributes record (ssParamRec),
using ssGetRunTimeParamInfo. The method should then update the record and
pass it back to Simulink, using this macro.

Note If you used ssRegAllTunableParamsAsRunTimeParams to create the

run-time parameters, use ssUpdateAllTunableParamsAsRunTimeParams to
update the parameters.

Languages C

See Also mdlProcessParameters, ssGetRunTimeParamInfo,

ssUpdateAllTunableParamsAsRunTimeParams,
ssRegAllTunableParamsAsRunTimeParams

10-198
 ssWarning

Purpose 10ssWarning
Display a warning message.

Syntax ssWarning(SimStruct *S, msg)

Arguments S
SimStruct representing an S-function block or a Simulink model.
msg
Warning message.

Description Displays msg. Expands to mexWarnMsgTxt when compiled for use with
Simulink. When compiled for use with the Real-Time Workshop, expands to
printf("Warning:%s from '%s'\n",msg, ssGetPath(S));, if the target has
stdio facilities; otherwise, it expands to a comment.

Languages C

See Also ssSetErrorMessage, ssPrintf

10-199
ssWriteRTWMxVectParam

Purpose 10ssWriteRTWMxVectParam
Write a vector parameter in MATLAB format to the model.rtw file.

Syntax int_T ssWriteRTWMxVectParam(SimStruct *S, const char_T *name,

const void *rValue, const void *iValue, int_T dataType, int_T
size)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
rValue
Real values of parameter
cValue
Complex values of parameter
dataType
Data type of parameter elements (see “Specifying Data Type Info” on
page 10-204)
size
Number of elements in vector

Description Use this function in mdlRTW to write a vector parameter in Simulink format to
this S-function’s model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW, ssWriteRTWMxVectParam

10-200
 ssWriteRTWMx2dMatParam

Purpose 10ssWriteRTWMx2dMatParam
Write a matrix parameter in MATLAB format to the model.rtw file.

Syntax int_T ssWriteRTWMx2dMatParam(SimStruct *S, const char_T *name,

const void *rValue, const void *iValue, int_T dataType, int_T
nRows, int_T nCols)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
rValue
Real elements of parameter array
iValue
Imaginary elements of parameter array
dataType
Data type of parameter elements (see “Specifying Data Type Info” on
page 10-204)
nRows
Number of rows in matrix
nColumns
Number of columns in matrix

Description Use this function in mdlRTW to write a matrix parameter in MATLAB format to
this S-function’s model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW, ssWriteRTW2dMatParam

10-201
ssWriteRTWParameters

Purpose 10ssWriteRTWParameters
Write tunable parameter information to model.rtw file.

Syntax int_T ssWriteRTWParameters(SimStruct *S, int_T nParams, int_T

paramType, const char_T *paramName, const char_T *stringInfo,
...)

Arguments S
SimStruct representing an S-function block.
nParams
Number of tunable parameters
paramType
Type of parameter (see “Parameter Type-Specific Arguments”)
paramName
Name of parameter
stringInfo
General information about the parameter, such as how it was derived
...
Remaining arguments depend on parameter type (see “Parameter
Type-Specific Arguments”).

Description Use this function in mdlRTW to write tunable parameter information to this
S-function’s model.rtw file. Your S-function must write the parameters out in
the same order as they are declared at the beginning of the S-function. This
function returns TRUE if successful.

Note This function is provided for compatibility with S-functions that do not
use run-time parameters. It is suggested that you use run-time parameters
(see “Run-Time Parameters” on page 7-6). If you do use run-time parameters,
you do not need to use this function.

Parameter Type-Specific Arguments

This section lists the parameter-specific arguments required by each
parameter type.

10-202
 ssWriteRTWParameters

• SS_WRITE_VALUE_VECT (vector parameter)

Argument Description

const real_T *valueVect Pointer to array of vector values

int_T vectLen Length of vector

• SSWRITE_VALUE_2DMAT (matrix parameter)

Argument Description

const real_T *valueMat Pointer to array of matrix elements

int_T nRows Number of rows in matrix
int_T nCols Number of columns in matrix

• SSWRITE_VALUE_DTYPE_2DMAT

Argument Description

const real_T *valueMat Pointer to array of matrix elements

int_T nRows Number of rows in matrix
int_T nCols Number of columns in matrix
int_T dtInfo Data type of matrix elements (see
“Specifying Data Type Info” on
page 10-204)

• SSWRITE_VALUE_DTYPE_ML_VECT

Argument Description

const void *rValueVect Real component of complex vector

const void *iValueVect Imaginary component of complex vector

10-203
ssWriteRTWParameters

Argument Description

int_T vectLen Length of vector

int_T dtInfo Data type of vector (see “Specifying Data
Type Info” on page 10-204)

• SSWRITE_VALUE_DTYPE_ML_2DMAT

Argument Description

const void *rValueMat Real component of complex matrix

const void *iValueMat Imaginary component of complex matrix
int_T nRows Number of rows in matrix
int_T nCols Number of columns in matrix
int_T dtInfo Data type of matrix

Specifying Data Type Info

The data type of value argument passed to the ssWriteRTW macros is obtained
using
DTINFO(dTypeId, isComplex),

where dTypeId can be any one of the enum values in BuitlInDTypeID

(SS_DOUBLE, SS_SINGLE, SS_INT8, SS_UINT8, SS_INT16, SS_UINT16, SS_INT32,
SS_UINT32, SS_BOOLEAN) defined in simstuc_types.h. The isComplex
argument is either 0 or 1.
For example, DTINFO(SS_INT32,0) is a noncomplex 32-bit signed integer.
If isComplex==1, it is assumed that the array of values has the real and
imaginary parts arranged in an interleaved manner (i.e., Simulink format). If
you prefer to pass the real and imaginary parts as two separate arrays, you
should use the macros ssWriteRTWMxVectParam or ssWriteRTWMx2dMatParam.

Example See simulink/src/sfun_multiport.c for an example that uses this function.

10-204
 ssWriteRTWParameters

Languages C

See Also mdlRTW

10-205
ssWriteRTWParamSettings

Purpose 10ssWriteRTWParamSettings
Write values of nontunable parameters to the model.rtw file.

Syntax int_T ssWriteRTWParamSettings(SimStruct *S, int_T nParamSettings,

int_T paramType, const char_T *settingName, ...)

Arguments S
SimStruct representing an S-function block.
nParamSettings
Number of parameter settings
settingType
Type of parameter (see “Parameter Setting Type-Specific Arguments”)
settingName
Name of parameter
...
Remaining arguments depend on parameter type (see “Parameter Setting
Type-Specific Arguments”).

Description Use this function in mdlRTW to write nontunable parameter setting information
to this S-function’s model.rtw file. A nontunable parameter is any parameter
that the S-function has declared as nontunable, using the
ssSetParameterTunable macro. You can also use this macro to write out other
constant values required to generate code for this S-function.
This function returns TRUE if successful.

Parameter Setting Type-Specific Arguments

This section lists the parameter-specific arguments required by each
parameter type.

• SSWRITE_VALUE_STR (unquoted string)

Argument Description

const char_T *value string (Example: U.S.A.)

10-206
 ssWriteRTWParamSettings

• SSWRITE_VALUE_QSTR (quoted string)

Argument Description

const char_T *value string (Example: “U.S.A.”)

• SSWRITE_VALUE_VECT_STR (vector of strings)

Argument Description

const char_T *value Vector of strings (e.g., ["USA", "Mexico"])

int_T nItemsInVect Size of vector

• SSWRITE_VALUE_NUM (number)

Argument Description

const real_T value Number (e.g., 2)

• SSWRITE_VALUE_VECT (vector of numbers)

Argument Description

const real_T *value Vector of numbers (e.g., [300, 100])

int_T vectLen Size of vector

• SSWRITE_VALUE_2DMAT (matrix of numbers)

Argument Description

const real_T *value Matrix of numbers (e.g.,

[[170, 130],[60, 40]])

int_T nRows Number of rows in vector

int_T nCols Number of columns in vector

10-207
ssWriteRTWParamSettings

• SSWRITE_VALUE_DTYPE_NUM (data typed number)

Argument Description

const void *value Number (e.g., [3+4i])

int_T dtInfo Data type (see “Specifying Data Type Info”
on page 10-204)

• SSWRITE_VALUE_DTYPE_VECT (data typed vector)

Argument Description

const void *value Data typed vector (e.g., [1+2i, 3+4i])

int_T vectLen Size of vector
int_T dtInfo Data type (see “Specifying Data Type Info”
on page 10-204)

• SSWRITE_VALUE_DTYPE_2DMAT (data typed matrix)

Argument Description

const void *value Matrix (e.g., [1+2i 3+4i; 5 6])

int_T nRows Number of rows in matrix
int_T nCols Number of columns in matrix
int_T dtInfo Data type (see “Specifying Data Type Info”
on page 10-204)

• SSWRITE_VALUE_DTYPE_ML_VECTOR (data typed MATLAB vector)

Argument Description

const void *RValue Real component of vector (e.g., [1 3])

const void *IValue Imaginary component of vector (e.g., [2 5])

10-208
 ssWriteRTWParamSettings

Argument Description

int_T vectLen Number of elements in vector

int_T dtInfo Data type (see “Specifying Data Type Info”
on page 10-204)

• SSWRITE_VALUE_DTYPE_ML_2DMAT (data typed MATLAB matrix)

Argument Description

const void *RValue Real component of matrix (e.g., [1 5 3 6])

const void *IValue Real component of matrix (e.g., [2 0 4 0])
int_T nRows Number of rows in matrix
int_T nCols Number of columns in matrix
int_T dtInfo Data type (see “Specifying Data Type Info”
on page 10-204)

Example See simulink/src/sfun_multiport.c for an example that uses this function.

Languages C

See Also mdlRTW, ssSetParameterTunable

10-209
ssWriteRTWScalarParam

Purpose 10ssWriteRTWScalarParam
Write a scalar parameter to the model.rtw file.

Syntax int_T ssWriteRTWScalarParam(SimStruct *S, const char_T *name,

const void *value, int_T type)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
value
Parameter value
type
Integer ID of the type of the parameter value, for example, the ID of one of
Simulink’s builtin datatypes (see BuiltInDTypeId in simstruc_types.h in
MATLAB’s simulink/include subdirectory) or the ID of a user-defined type
(see “Custom Data Types” on page 7-15).

Description Use this function in mdlRTW to write scalar parameters to this S-function’s
model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-210
 ssWriteRTWStr

Purpose 10ssWriteRTWStr
Write a string to the model.rtw file.

Syntax int_T ssWriteRTWStr(SimStruct *S, const char_T *str)

Arguments S
SimStruct representing an S-function block.
str
String

Description Use this function in mdlRTW to write strings to this S-function’s model.rtw file.
This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-211
ssWriteRTWStrParam

Purpose 10ssWriteRTWStrParam
Write a string parameter to the model.rtw file.

Syntax int_T ssWriteRTWStrParam(SimStruct *S, const char_T *name,

const char_T *value)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
value
Parameter value

Description Use this function in mdlRTW to write string parameters to this S-function’s
model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-212
 ssWriteRTWStrVectParam

Purpose 10ssWriteRTWStrVectParam
Write a string vector parameter to the model.rtw file.

Syntax int_T ssWriteRTWStrVectParam(SimStruct *S, const char_T *name,

const void *value, int_T size)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
value
Parameter values
size
Number of elements in vector

Description Use this function in mdlRTW to write a vector of string parameters to this
S-function’s model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-213
ssWriteRTWVectParam

Purpose 10ssWriteRTWVectParam
Write a vector parameter to the model.rtw file.

Syntax int_T ssWriteRTWStrVectParam(SimStruct *S, const char_T *name,

const void *value, int_T dataType, int_T size)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
value
Parameter values
dataType
Data type of parameter elements (see “Specifying Data Type Info” on
page 10-204)
size
Number of elements in vector

Description Use this function in mdlRTW to write a vector parameter in Simulink format to
this S-function’s model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW, ssWriteRTWMxVectParam

10-214
 ssWriteRTWWorkVect

Purpose 10ssWriteRTWWorkVect
Write work vectors to model.rtw file.

Syntax int_T ssWriteRTWWorkVect(SimStruct *S, const char_T *vectName,

int_T nNames, const char_T *name1, int_T size1, ...,
const char_T * nameN, int_T sizeN)

Arguments S
SimStruct representing an S-function block.
vectName
Name of work vector (must be “RWork”, “IWork” or “PWork”)
settingType
Type of parameter (see “Parameter Setting Type-Specific Arguments”)
name1 ... nameN
Names of groups of work vector elements
size1 ... sizeN
Size of each element group (the total of the sizes must equal the size of the work
vector

Description Use this function in mdlRTW to write work vectors to this S-function’s model.rtw
file. This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-215
ssWriteRTW2dMatParam

Purpose 10ssWriteRTW2dMatParam
Write a matrix parameter to the model.rtw file.

Syntax int_T ssWriteRTW2dMatParam(SimStruct *S, const char_T *name,

const void *value, int_T dataType, int_T nRows, int_T nCols)

Arguments S
SimStruct representing an S-function block.
name
Parameter name
value
Parameter values
dataType
Data type of parameter elements (see “Specifying Data Type Info” on
page 10-204)
nRows
Number of rows in matrix
nColumns
Number of columns in matrix

Description Use this function in mdlRTW to write a vector of numeric parameters to this
S-function’s model.rtw file. This function returns TRUE if successful.

Languages C

See Also mdlRTW

10-216
 Index

A
additional parameters for S-functions 2-5 sample time for hybrid block 7-22
array bounds checking 7-33 variable step S-function (C MEX) 7-46
variable step S-function (M-file) 2-16
exception free code 7-31
B
block-based sample times 7-16
H
hybrid block, setting sample time 7-22
C hybrid system S-function example (C MEX) 7-42
C MEX S-functions 1-2, 4-1, 5-1, 6-1 hybrid system S-function example (M-file) 2-13
callback methods 1-9
continuous block, setting sample time 7-21
continuous state S-function example (C MEX) I
7-34 input arguments for M-file S-functions 2-6
continuous state S-function example (M-file) 2-8 inputs, dynamically sized 1-12

D M
direct feedthrough 1-11 masked multiport S-functions 7-13
direct index lookup table example 8-24 matrix.h 3-29
discrete state S-function example (C MEX) 7-38 mdlCheckParameters 9-3
discrete state S-function example (M-file) 2-11 mdlDerivatives 9-5
dynamically sized inputs 1-12 mdlGetTimeOfNextVarHit 9-6
mdlInitializeConditions 9-7
mdlInitializeSampleTimes 9-9
E mdlInitializeSizes 1-12, 2-4, 9-13
examples mdlOutput function 7-21
continuous state S-function (C MEX) 7-34 mdlOutputs 9-17
continuous state S-function (M-file) 2-8 mdlProcessParameters 9-18
direct index lookup table 8-24 mdlRTW 8-21, 9-20
discrete state S-function (C MEX) 7-38 mdlSetDefaultPortComplexSignals 9-21
discrete state S-function (M-file) 2-11 mdlSetDefaultPortDataTypes 9-22
hybrid system S-function (C MEX) 7-42 mdlSetDefaultPortDimensionInfo 9-23
hybrid system S-function (M-file) 2-13 mdlSetInputPortComplexSignal 9-24
pointer work vector 7-26 mdlSetInputPortDataType 9-25
sample time for continuous block 7-21 mdlSetInputPortDimensionInfo 9-26

I-1
 Index

mdlSetInputPortFrameData 9-28 S
mdlSetInputPortSampleTime 9-29 S_FUNCTION_LEVEL 2, #define 3-28
mdlSetInputPortWidth 9-31 S_FUNCTION_NAME, #define 3-28
mdlSetOutputPortComplexSignal 9-32 sample times
mdlSetOutputPortDataType 9-33 block-based 7-16
mdlSetOutputPortDimensionInfo 9-34 continuous block, example 7-21
mdlSetOutputPortSampleTime 9-36 hybrid block, example 7-22
mdlSetOutputPortWidth 9-37 port-based 7-19
mdlSetWorkWidths 9-38 S-Function block 1-2
mdlStart 9-39 multirate 7-21
mdlTerminate 9-40 S-Function Builder 3-5
mdlUpdate 7-21, 9-41 S-function options 10-167
mdlZeroCrossings 9-42 S-function routines 1-8
memory and work vectors 7-24 M-file 2-2
mex utility 1-2 S-functions
mex.h 3-29 additional parameters 2-5
M-file S-function routines 2-2 C MEX 1-2, 4-1, 5-1, 6-1
mixedm.c example 7-42 definition 1-2
multirate S-Function blocks 7-21 direct feedthrough 1-11
exception free code 7-31
inlined 8-7, 8-19
O input arguments for M-files 2-6
options, S-function 10-167 masked multiport 7-13
parameter field 7-3
purpose 1-5
P routines 1-8
parameters run-time routines 7-32
passing to S-functions 1-3 types of 8-3
parameters, S-function 2-5 using in models 1-2
penddemo demo 1-5 when to use 1-5
pointer work vector, example 7-26 wrapper 8-9
port-based sample times 7-19 sfuntmpl.c template 3-28
simsizes function 2-4
simulation loop 1-6
R simulation stages 1-6
re-entrancy 7-24
simulink.c 3-30
run-time routines 7-32
sizes structure 1-12, 2-4

I-2
 Index

SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION ssGetDWorkWidth 10-34

10-168 ssGetdX 10-35
SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL ssGetErrorStatus 10-36
10-168 ssGetInputPortBufferDstPort 10-37
SS_OPTION_ASYNC_RATE_TRANSITION 10-168 ssGetInputPortComplexSignal 10-39
SS_OPTION_ASYNCHRONOUS 10-168 ssGetInputPortConnected 10-38
SS_OPTION_CALL_TERMINATE_ON_EXIT 10-169 ssGetInputPortDataType 10-40
SS_OPTION_DISALLOW_CONSTANT_SAMPLE_TIME ssGetInputPortDimensions 10-42
10-168 ssGetInputPortDirectFeedThrough 10-43
SS_OPTION_DISCRETE_VALUED_OUTPUT 10-167 ssGetInputPortFrameData 10-44
SS_OPTION_EXCEPTION_FREE_CODE 10-167 ssGetInputPortNumDimensions 10-45
SS_OPTION_FORCE_NONINLINED_FCNCALL ssGetInputPortOffsetTime 10-46
10-169 ssGetInputPortRealSignal 10-48
SS_OPTION_PLACE_ASAP 10-167 ssGetInputPortRealSignalPtrs 10-49
SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED ssGetInputPortReusable 10-51
10-168 ssGetInputPortSampleTime 10-52
SS_OPTION_RATE_TRANSITION 10-168 ssGetInputPortSampleTimeIndex 10-53
SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE ssGetInputPortSignal 10-54
10-167 ssGetInputPortSignalAddress 10-56
SS_OPTION_SFUNCTION_INLINED_FOR_RTW ssGetInputPortSignalPtrs 10-57
10-168 ssGetInputPortWidth 10-58
SS_OPTION_SIM_VIEWING_DEVICE 10-169 ssGetIWork 10-59
SS_OPTION_USE_TLC_WITH_ACCELERATOR ssGetModelName 10-60
10-169 ssGetModeVector 10-61
ssCallSystemWithTid 10-17 ssGetModeVectorValue 10-62
ssGetContStateAddress 10-20 ssGetNonsampledZCs 10-63
ssGetContStates 10-21 ssGetNumDWork 10-67
ssGetDataTypeId 10-23 ssGetOutputPortBeingMerged 10-79
ssGetDataTypeName 10-22 ssGetOutputPortDimensions 10-82
ssGetDataTypeSize 10-24 ssGetOutputPortFrameData 10-85
ssGetdataTypeZero 10-25 ssGetOutputPortReusable 10-87
ssGetDiscStates 10-26 ssGetSFcnParamsCount 10-103
ssGetDTypeIdFromMxArray 10-27 ssGetUserData 10-113
ssGetDWork 10-29 ssParamRec 10-98, 10-184
ssGetDWorkComplexSignal 10-30 ssSetDWorkComplexSignal 10-129
ssGetDWorkDataType 10-31 ssSetDWorkDataType 10-130
ssGetDWorkUsedAsDState 10-33 ssSetDWorkName 10-32, 10-131

I-3
 Index

ssSetDWorkUsedAsDState 10-132
ssSetDWorkWidth 10-133
ssSetErrorStatus 10-134
ssSetExternalModeFcn 10-16, 10-135
ssSetInputPortDimensionInfo 10-138
ssSetInputPortDirectFeedThrough 10-141
ssSetInputPortFrameData 10-140
ssSetInputPortOffsetTime 10-143
ssSetInputPortRequiredContiguous 10-50,
10-147
ssSetInputPortReusable 10-145
ssSetInputPortSampleTime 10-148
ssSetInputPortSampleTimeIndex 10-149
ssSetModeVectorValue 10-152
ssSetNumDWork 10-155
ssSetNumNonsampledZCs 10-159
ssSetNumSFcnParams 10-165
ssSetSFcnParamNotTunable 10-188
ssSetUserData 10-194
synchronizing multirate S-Function blocks 7-22

T
tmwtypes.h 3-29

V
variable step S-function example (C MEX) 7-46
variable step S-function example (M-file) 2-16

W
work vectors 7-24

I-4