1. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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

2. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

3. 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 – port widths, data types, sample time, memories allocation, execution
order, evaluates block parameters
Simulation 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

4. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

5. 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, p are block parameter to be changed externally
Outputs sys Output of s-function
x0 [ initial value vector of states]
str not used [ ]
ts [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:
Advantage: Easy to write and compatibility with matlab toolbox functions
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

6. Mex s-function are written in C or C++, Fortran, Adao
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

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

8. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
Importing C code into Simulink for Signal Processing Applications
S-function Builder
C-code S-function C
Simulink
M-code S-function
Caution: interpreted, not compiled
MATLAB
>> sim(‘mymodel’)
MEX
ActiveX/COM & DDE
Engine or COM [x,y,t] = sim(‘mymodel’,u0)
MATLAB Engine
MATLAB Compiler & runtime
How?
Call…
From…
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

9. Structure of code to be imported: `main() and slicer.c´
test_slicer.exe
//slicer.c
slicer() {
return; }
//test_slicer.c
main() {
for(){
slicer(); } t

10. 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
//slicer.c
//definition
// of
//slicer()
//wrap_slicer.c
mdlOutputs(S) {
slicer(); }
Simulink t
UNIX is a registered trademark of The Open Group
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

11. mdlInitializeSizes() mdlInitializeSampleTimes()
The “S-function” DLL contains several methods
mdlInitializeSizes()
mdlInitializeSampleTimes()
mdlOutputs()
yt = f(t, ut)
y = outputs, t = time
u = inputs n
Done? y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

12. What about leaf functions with states?
int always_one(void) {
int y = 0;
y = y + 1;
return y; }
int up(void)
static int y = 0;
int counter(int *z)
*z = *z + 1;
return *z;
States preserved across time steps
Independent set of states per instance
FIR, IIR, coders, decoders
Also known as...
Computer science: “Re-entrant persistent storage”
Object-oriented: “property”
C++: “member variable”
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
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

13. 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
states
xd, w
output y=f(t,xd,w,u)
input u
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

14. 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()
2) General structure or advanced needs – use full S-function
Leaf with output and update functions intermixed
 Use “work vectors” , update them in mdlOutputs()
yt = f(t, xt, ut), xt+ t = g(t, xt, ut)
y = outputs, t = time, x = states, u = inputs
[xt+ t , yt]= f(t, xt, ut)
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

15. mdlInitializeSizes() mdlInitializeSampleTimes()
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()
xt+t = g(t, xt, ut) n
Done? y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

16. mdlInitializeSizes() mdlInitializeSampleTimes()
2) General leaf structure
mdlInitializeSizes()
mdlInitializeSampleTimes()
mdlOutputs()
yt = f(t, wt, ut)
wt+t = g(t, wt, ut)
y = outputs
t = time
w = work vec
u = inputs n
Done? y
mdlTerminate()
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

17. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
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

18. 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

19. F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional
S-function compilation issue*
Microsoft Visual C/C++
MATLAB
Real Time Workshop
Windows
Ver 7.1 Recommended
Version 7
Ver 2.5.0 XP or
2000
Version 6.0
Version 6
Ver 2.2.0 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

20. 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

21. s-function examples using s-function builder
and
MSVC 6.0 Debugging
slicer.c and iir_general.c
Webinar
<%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
ludlub – Linear system equation solver, using C source code from ‘Numerical Recipes in C’ ludcmp.c & lubksb.c, MATLAB 6.5
mylms – Least mean square , MATLAB7, RTWT
F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional