What is S-Function?

1. 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. 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. 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 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 http://www.mathworks.com/access/helpdesk/help/pdf_doc/simulink/sfunction.pdf F. Nagi Dep. Of Mech Eng. Universiti Tenaga Nasional

6. 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. 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. From… Call… How? C MATLAB MATLAB Engine ActiveX/COM & DDE MATLAB Compiler & runtime C Simulink Engine or COM[x,y,t] = sim(‘mymodel’,u0) MATLAB C 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 Importing C code into Simulink for Signal Processing Applications 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. The “S-function” DLL contains several methods mdlInitializeSizes() mdlInitializeSampleTimes() mdlOutputs() yt = f(t, ut) y = outputs, t = time u = inputs Done? n 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; y = y + 1; return y; } 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. 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. 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. 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. S-function compilation issue* Microsoft Visual C/C++ MATLAB Real Time Workshop Windows Ver 7.1 Recommended Ver 2.5.0 Version 7 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 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 • 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