1. No category

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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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, execution
order, evaluates block parameters
loop – Execute block determined during initialization, computes/updates
blocks states, derivatives and outputs during a sample time
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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 functions
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
•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:
• builder-name.c
Have standard code representation
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
Importing C code into Simulink for Signal
Processing Applications
From…
Call…
How?
C
MATLAB
MATLAB Engine
ActiveX/COM & DDE
MATLAB Compiler & runtime
C
Simulink
MATLAB
C
Engine or COM
[x,y,t] =
sim(‘mymodel’,u0)
MEX
ActiveX/COM & DDE
MATLAB
Simulink
>> sim(‘mymodel’)
Simulink
MATLAB
M-code S-function
Caution: interpreted, not compiled
Simulink
C
S-function Builder
C-code S-function
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
Structure of code to be imported:
`main() and slicer.c´
test_slicer.exe
//test_slicer.c
main()
{
for(){
slicer();
}
}
t
//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
t
//wrap_slicer.c
mdlOutputs(S)
{
slicer();
}
//slicer.c
//definition
// of
//slicer()
UNIX is a registered trademark of The Open Group
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
The “S-function” DLL contains several
methods
mdlInitializeSizes()
mdlInitializeSampleTimes()
mdlOutputs()
n
Done?
y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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
– Object-oriented: “property”
y = y + 1;
return y;
– C++: “member variable”
}
y = 0;
int counter(int *z)
{
*z = *z + 1;
return *z;
}
not
re-entrant
Different from…
– static variables in C are persistent but shared,
– If a leaf contains static data it can only be instantiated once
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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 S-function
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)
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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 S-function
– Leaf with output and update functions intermixed
 Use “work vectors” , update them in mdlOutputs()
[xt+ t , yt]= f(t, xt, ut)
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
1) “Output-update” function.c
structure
mdlInitializeSizes()
mdlInitializeSampleTimes()
yt = f(t, xt, ut)
y = outputs, t = time
x = states, u = inputs
mdlOutputs()
“Division of labor is preferred”
mdlUpdate()
n
Done?
y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
xt+t = g(t, xt, ut)
2) General leaf structure
mdlInitializeSizes()
mdlInitializeSampleTimes()
mdlOutputs()
n
Done?
y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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 line in
sfunction.c
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
S-function compilation issue*
Microsoft
Visual
MATLAB
C/C++
Ver 7.1
Version 7
Recommended
Real Time Windows
Workshop
Version 6.0
Ver 2.2.0
Version 6
Ver 2.5.0
XP
or
2000
98
or
2000
*MATLAB TECH NOTE 1601
• Always set MATLAB Command Window directory to the directory
where source files are stored
>> mex –setup
% At matlab startup %
>> rtwintgt –install
% At startup %
>> mex –g sfun_name.c
% s-function debugging%
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional