What is S-Function?

S-Functions is computer language description of Simulink

block
If written in MATLAB programming environment it is
called M-file s-function
If written in C/C++ programming environment it is called
C Mex s-function

What S-Function Do?

Allows you to add your own code to simulink model or

environment
Code can be written for continuous, discrete or hybrid
system
Can be use with Real Time Workshop

Real Time workshop generates code for Simulink/s-function to

run in real time ..faster

How S-function Works

Mathematically simulink block consist of a set of inputs u, a set
of states x, and set of outputs y

Simulation Stages

Initialization
Simulation

port widths, data types, sample time, memories allocation, exec

order, evaluates block parameters
loop Execute block determined during initialization, computes/upd
blocks states, derivatives and outputs during a sample time

M-file S-function
M-files s-function is a matlab function
[sys,x0,str,ts] = f(t,x,u,flag,p1,p2,)
Inputs f
s-function name
t
is the current time
x
is the state vector
flag
indicates the task to be performed
p1, p2
are block parameter to be changed externally
Outputs sys
x0
str
ts

Output of s-function
[ initial value vector of states]
not used [ ]
[sample time offset time]

M-file s-function template

Examples:
<matlabroot>/toolbox/simulink/blocks/msfuntmpl.m
Sfundemos:
>>sfundemos >> is matlab workspace prompt
<matlabroot>/toolbox/simulink/simdemos
User Manaul:
http://www.mathworks.com/access/helpdesk/help/pdf_doc/simulink/sfunction.pdf
Advantage: Easy to write and compatibility with matlab toolbox

C MEX s-function
Mex s-function are written in C or C++, Fortran, Adao
C Mex files can modify data structure of Simulink
SimStruct which is used for housekeeping
Can handle multiple data types and matrix signals
Used with Real Time Workshop , wrapper s-function
How to build C Mex s-function
Simulink specific naming convention and housekeeping
(SimStruct) standards should be followed by C Mex files
Template and examples in <matlabroot> / simulink /src
sfuntmpl_basic.c
>> mex setup should be run a priori to setup the compiler
C Mex files are compiled in MATLAB with mex command
Matlab Executable (mex) creates xxx.dll, dynamically
loadable file excutable for simulink
S- function Builder

S-Function Builder
Easiest way to embed your C code in Simulink model
S-function builder is a Simulink block
Act as calling program (wrapper) to C source code from
Simulink providing necessary interfacing options
S-function builder generates its own:
Have standard code representation
builder-name.c

similar to sfuntmpl_basic.c
builder-name_wrapper.c
Customized interfacing
options entered in builder
builder-name.tlc
Permit code generated to run
in accelerated and real time Workshop
builder-name.dll
Simulink executable dll file

Importing C code into Simulink for Signal

Processing Applications
From

Call

How?

MATLAB

MATLAB Engine
ActiveX/COM & DDE
MATLAB Compiler & runtime

Simulink

Engine or COM
[x,y,t] =
sim(mymodel,u0)

MATLAB

MEX
ActiveX/COM & DDE

MATLAB

Simulink

>> sim(mymodel)

Simulink

MATLAB

M-code S-function
Caution: interpreted, not compiled

Simulink

S-function Builder
C-code S-function

Structure of code to be
imported: `main() and slicer.c

test_slicer.exe
//test_slicer.c
main()
{
for(){
slicer();
}
}

//slicer.c
slicer()
{
return;
}

Structure of code after import:

`wrapped slicer.c
Call your `slicer.c code from a wrapper to
interface with Simulink
Compile both and link .dll
Simulink calls the DLL using several functions
(methods)
wrap_slicer.dll

Simulink

//wrap_slicer.c
mdlOutputs(S)
{
slicer();
}

//slicer.c
//definition
// of
//slicer()

UNIX is a registered trademark of The Open Group

The S-function DLL contains

several methods
mdlInitializeSizes()

mdlInitializeSampleTimes()

mdlOutputs()

Done?
y

mdlTerminate()

yt = f(t, ut)
y = outputs, t = time
u = inputs

What about leaf functions with states?

int always_one(void)
{
int y = 0;
y = y + 1;
return y;
}

States preserved across time steps

Independent set of states per instance
FIR, IIR, coders, decoders
Also known as...
int up(void)
Computer science: Re-entrant persistent{ storage
static int
y = y + 1;
Object-oriented: property
return y;
C++: member variable
}

y = 0;

int counter(int *z)

{
*z = *z + 1;
return *z;
}

Different from
static variables in C are persistent but shared, not
re-entrant
If a leaf contains static data it can only be
instantiated once

Two main types of state available in

Simulink
Discrete states, xd
Read-only (const) in the mdlOutput() method
Available in S-Function Builder block and full Sfunction
Work vectors, w
Read-write in mdlOutput()
Presently only accessible from full S-function API

input u

states
xd, w

output y=f(t,xd,w,u)

Approach depends on code structure

1) Output-update structure use S-function Builder block
Leaf with separate output and update functions
Use discrete states, update them in mdlUpdate()

yt = f(t, xt, ut), xt+ t = g(t, xt, ut)

y = outputs, t = time, x = states, u = inputs
2) General structure or advanced needs use full Sfunction
Leaf with output and update functions intermixed
Use work vectors , update them in mdlOutputs()

[xt+ t , yt]= f(t, xt, ut)

1) Output-update
function.c structure
mdlInitializeSizes()

mdlInitializeSampleTimes()

mdlOutputs()

yt = f(t, xt, ut)

y = outputs, t = time
x = states, u = inputs
Division of labor is preferred

mdlUpdate()
n

Done?
y

mdlTerminate()

xt+t = g(t, xt, ut)

2) General leaf structure

mdlInitializeSizes()

mdlInitializeSampleTimes()

mdlOutputs()

Done?
y

mdlTerminate()

yt = f(t, wt, ut)

wt+t = g(t, wt, ut)
y = outputs
t = time
w = work vec
u = inputs

Demonstrations
Examples of S-function builder
S-function Builder block features
Slicer: a memoryless block
IIR Filter: a block with memory
Output-update structure
S-function Builder
A Discrete state
Output in mdlOutputs()and update in mdlUpdate()
General structure
Full S-function
1-element Work vector
Output and update in mdlOutputs()
Using the sample code as a resource
Tour of the S-function reference material

Debugging s-function.dll in MSVC

Open sfunc_name.dll file built by S-builder for e.g. simfunc_name.mdl

in MSVC
Setup breakpoint in sfunction.c using Right Mouse button
Click Right mouse button on sfunc_name.dll open setting dialouge
box, select debug tab, under executable field enter
C:\MATLAB6p5\bin\win32\matlab.exe,

OK!

load sfunction.c in MSVC on the desired line enabled

Choose build option from main menu and select start debug and Go!
MATLAB will start under debugging mode
Open simfunc_name.mdl for degguer MATLAB
Run the file
Watch the stop sign in MSVC sfunction.c file, the program should stop
with arrow
Select view from main menu and select debug Windows memory,
variable, registers
use F11 or steps increment icons from the MSVC toolbar to step to next

S-function compilation issue*

Microsoft
Visual C/C+
+

MATLAB

Real Time
Workshop

Windows

XP
or
2000
98
or
2000

Ver 7.1
Recommend
ed

Version 7

Ver 2.5.0

Version 6.0

Version 6

Ver 2.2.0

*MATLAB TECH NOTE 1601

Always set MATLAB Command Window directory to the direct

where source files are stored
>> mex setup
% At matlab startup %
>> rtwintgt install
% At startup %
>> mex g sfun_name.c
% s-function debugging%

s-function use with Real Time Workshop

For Real Time Window Target
Real time Workshop (RTW)
generates portable , customize
standalone C/C++ code of
simulink model which operates in
Real time
Target Language Compiler
(TLC) transform Simulink Block
into C/C++
Simulink external mode
enables communication between
simulink and external process
Real Time Window Target
(RTWT) is a component of RTW
RTWT helps to connect simulink
model with external actuators
and sensor for control and
monitoring of Physical process

s-function examples using s-function

builder
and
MSVC 6.0 Debugging

slicer.c and iir_general.c

Webinar http://www.mathworks.com/cmspro/req4858.html

<%matlabroot>/extern/examples/mex/

<%matlabroot>/toolbox/simulink/blocks/
i) fnpointer - use pointers to pass simulink matrix data to
and from
external source in C. MATLAB7, RTWT compilation
ii) myadd - add matrix internally using array indexes,
MATLAB7
iii) disc_stsp7 Discrete state updates internally, MATLAB7
iv) fnmat use pointers and array index for internal and
external codes, MATLAB7
v) ludlub Linear system equation solver, using C source
code from Numerical Recipes in C ludcmp.c & lubksb.c,
MATLAB 6.5
vi) mylms Least mean square , MATLAB7, RTWT