Overview of S-Functions (Writing S-Functions)

Writing S-Functions

S-Function Examples

Simulink comes with a library of S-function examples.

To run an example:

Enter sfundemos at the MATLAB command line.

MATLAB displays the S-function demo library.

Each block represents an S-function example.

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

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.

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.

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.
`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).

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_errhndl.c
A simple example of how to check parameters using the mdlCheckParams S-function routine.

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.

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 + Buy = 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.

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.

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).
`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_errhndl.c`	A simple example of how to check parameters using the `mdlCheckParams` S-function routine.
`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.
`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 + Buy = 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.
`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

Filename
Description

sfun_timestwo_for.for
A sample Level 1 Fortran representation of a C timestwo S-function.

sfun_atmos.c
Calculation of the 1976 standard atmosphere to 86 km.

vdpmexf.for
Van der Pol system.

The following table lists sample Fortran S-functions.

Filename	Description
`sfun_timestwo_for.for`	A sample Level 1 Fortran representation of a C `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

Filename
Description

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

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

Filename	Description
`sfun_counter_cpp.cpp`	Stores an C++ object in the pointers vector `PWork`.

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.

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.

S-Function Concepts Writing M S-Functions