The following figure illustrates the stages of a simulation. Initialize model Calculate time of next sample hit (only for variable sample time blocks) Update discrete states Clean up at fi time step Calculate derivatives Calculate outputs Integration minor time step Calculate derivative Locate zero crossings Figure 1-2: How Simulink Performs Simulation
1 Overview of S-Functions 1-8 The following figure illustrates the stages of a simulation. Figure 1-2: How Simulink Performs Simulation Initialize model Clean up at final time step Calculate time of next sample hit (only for variable sample time blocks) Calculate outputs Update discrete states Integration (minor time step) Calculate derivatives Calculate derivatives Locate zero crossings Calculate outputs Calculate derivatives Simulation loop
How s-Functions Work S-Function callback methods An S-function comprises a set of s-function callback methods that perform tasks required at each simulation stage During simulation of a model, at each imulation stage, Simulink calls the appropriate methods for each S-function block in the model Tasks performed by S-function methods include Initialization- Prior to the first simulation loop, Simulink initializes the S-function. During this stage, Simulink Initializes the simStruct a simulation structure that contains information about the s-function Sets the number and dimensions of input and output ports Allocates storage areas and the sizes array Calculation of next sample hit-If you've created a variable sample time block, this stage calculates the time of the next sample hit; that is, it calculates the next step size. Calculation of outputs in the major time step- After this call is complete all the output ports of the blocks are valid for the current time step Update of discrete states in the major time step- In this call, all blocks should perform once-per-time-step activities such as updating discrete states for next time around the simulation loop Integration- This applies to models with continuous states andor onsampled zero crossings. If your S-function has continuous state Simulink calls the output and derivative portions of your S-function at minor time steps. This is so Simulink can compute the states for your S-function. If our S-function(C MEX only) has nonsampled zero crossings, Simulink calls the output and zero-crossings portions of your S-function at minor time steps so that it can locate the zero crossings Note See "How Simulink Works"in the Using Simulink documentation for an explanation of major and minor time steps 1-9
How S-Functions Work 1-9 S-Function Callback Methods An S-function comprises a set of S-function callback methods that perform tasks required at each simulation stage. During simulation of a model, at each simulation stage, Simulink calls the appropriate methods for each S-function block in the model. Tasks performed by S-function methods include • Initialization — Prior to the first simulation loop, Simulink initializes the S-function. During this stage, Simulink - Initializes the SimStruct, a simulation structure that contains information about the S-function - Sets the number and dimensions of input and output ports - Sets the block sample times - Allocates storage areas and the sizes array • Calculation of next sample hit — If you’ve created a variable sample time block, this stage calculates the time of the next sample hit; that is, it calculates the next step size. • Calculation of outputs in the major time step — After this call is complete, all the output ports of the blocks are valid for the current time step. • Update of discrete states in the major time step — In this call, all blocks should perform once-per-time-step activities such as updating discrete states for next time around the simulation loop. • Integration — This applies to models with continuous states and/or nonsampled zero crossings. If your S-function has continuous states, Simulink calls the output and derivative portions of your S-function at minor time steps. This is so Simulink can compute the states for your S-function. If your S-function (C MEX only) has nonsampled zero crossings, Simulink calls the output and zero-crossings portions of your S-function at minor time steps so that it can locate the zero crossings. Note See “How Simulink Works” in the Using Simulink documentation for an explanation of major and minor time steps
Overview of s-Functions Implementing S-Functions You can implement an S-function as either an M-file or a MEX file. The following sections describe these alternative implementations and discuss the M-File s-Functions An M-file S-function consists of a matLAB function of the following form: [sys, X0, str, ts]=f(t, x, u, flag, p1, p2,...) where f is the S-functions name, t is the current time. x is the state vector of the corresponding S-function block, u is the blocks inputs, flag indicates a task to be performed, and p1, p are the block's parameters. During simulation of a model, Simulink repeatedly invokes f, using flag to indicate the task to be performed for a particular invocation. Each time the S-function performs the ask, it returns the result in a structure having the format shown in the syntax A template implementation of an M-file S-function, sfuntmpl. m, resides in matlabroot/toolbox/simulink/blocks. The template consists of a top-level function and a set of skeleton subfunctions, each of which corresponds to a particular value of flag. The top-level function invokes the subfunction indicated by flag. The subfunctions, called S-function callback methods perform the tasks required of the S-function during simulation. The following table lists the contents of an m-file s-function that follows this standard format Simulation Stag S-Function routine Flas Initialization mdlInitializesizes fl Calculation of next sample mdlGetTimeof NextVarHit flag=4 hit(variable sample time block only) Calculation of output mdloutputs fl Update of discrete states mdlUpdat flag
1 Overview of S-Functions 1-10 Implementing S-Functions You can implement an S-function as either an M-file or a MEX file. The following sections describe these alternative implementations and discuss the advantages of each. M-File S-Functions An M-file S-function consists of a MATLAB function of the following form: [sys,x0,str,ts]=f(t,x,u,flag,p1,p2,...) where f is the S-function’s name, t is the current time, x is the state vector of the corresponding S-function block, u is the block’s inputs, flag indicates a task to be performed, and p1, p2, ... are the block’s parameters. During simulation of a model, Simulink repeatedly invokes f, using flag to indicate the task to be performed for a particular invocation. Each time the S-function performs the task, it returns the result in a structure having the format shown in the syntax example. A template implementation of an M-file S-function, sfuntmpl.m, resides in matlabroot/toolbox/simulink/blocks. The template consists of a top-level function and a set of skeleton subfunctions, each of which corresponds to a particular value of flag. The top-level function invokes the subfunction indicated by flag. The subfunctions, called S-function callback methods, perform the tasks required of the S-function during simulation. The following table lists the contents of an M-file S-function that follows this standard format. Simulation Stage S-Function Routine Flag Initialization mdlInitializeSizes flag = 0 Calculation of next sample hit (variable sample time block only) mdlGetTimeOfNextVarHit flag = 4 Calculation of outputs mdlOutputs flag = 3 Update of discrete states mdlUpdate flag = 2
Simulation Stage S-Function routine Fl Calculation of derivatives mdlDerivatives flag =1 End of simulation tasks mdlTerminate flag =9 We recommend that you follow the structure and naming conventions of the template when creating M-file S-functions. This makes it easier for others to understand and maintain M-file S-functions that you create. See Chapter 2 "Writing M S-Functions, for information on creating M-file S-functions MEX-File S-Functions Like an m-file s-function, a meX-file function consists of a set of callback routines that Simulink invokes to perform various block-related tasks during a simulation. Significant differences exist, however. For one, MEX-file functions are implemented in a different programming language: C, C++, Ada, r Fortran. Also, Simulink invokes MEX S-function routines directly instead of via a flag value as with M-file S-functions. Because Simulink invokes the functions directly, MEX-file functions must follow standard naming conventions specified by Simulink. Other key differences exist. For one, the set of callback functions that mEX functions can implement is much larger than can be implemented by M-file functions. A MEX function also has direct access to the internal data structure called the SimStruct that simulink uses to maintain information about the S-function, MEX-file functions can also use the matlab mex-file api t ccess the matLAB workspace directly A C MEX-file S-function template, called sfuntmpl basic C, resides in the matlabroot/simulink/src directory. The template contains skeleton implementations of all the required and optional callback routines that a c MEX-file S-function can implement. For a more amply commented version of the template, see sfuntmpl doc c in the same directory MEX-File Versus M-File S-Functions M-file and MEX-file S-functions each have advantages. The advantage of M-file S-functions is speed of development. Developing M-file S-functions avoids the time-consuming compile-link-execute cycle required by development in a compiled language. M-file S-functions also have easier access to MATLAB and toolbox functions l-11
Implementing S-Functions 1-11 We recommend that you follow the structure and naming conventions of the template when creating M-file S-functions. This makes it easier for others to understand and maintain M-file S-functions that you create. See Chapter 2, “Writing M S-Functions,” for information on creating M-file S-functions. MEX-File S-Functions Like an M-file S-function, a MEX-file function consists of a set of callback routines that Simulink invokes to perform various block-related tasks during a simulation. Significant differences exist, however. For one, MEX-file functions are implemented in a different programming language: C, C++, Ada, or Fortran. Also, Simulink invokes MEX S-function routines directly instead of via a flag value as with M-file S-functions. Because Simulink invokes the functions directly, MEX-file functions must follow standard naming conventions specified by Simulink. Other key differences exist. For one, the set of callback functions that MEX functions can implement is much larger than can be implemented by M-file functions. A MEX function also has direct access to the internal data structure, called the SimStruct, that Simulink uses to maintain information about the S-function. MEX-file functions can also use the MATLAB MEX-file API to access the MATLAB workspace directly. A C MEX-file S-function template, called sfuntmpl_basic.c, resides in the matlabroot/simulink/src directory. The template contains skeleton implementations of all the required and optional callback routines that a C MEX-file S-function can implement. For a more amply commented version of the template, see sfuntmpl_doc.c in the same directory. MEX-File Versus M-File S-Functions M-file and MEX-file S-functions each have advantages. The advantage of M-file S-functions is speed of development. Developing M-file S-functions avoids the time-consuming compile-link-execute cycle required by development in a compiled language. M-file S-functions also have easier access to MATLAB and toolbox functions. Calculation of derivatives mdlDerivatives flag = 1 End of simulation tasks mdlTerminate flag = 9 Simulation Stage S-Function Routine Flag
1 Overview of s-functions The primary advantage of mEX-file functions is versatility. The larger number of callbacks and access to the sim Struct enable mex-file functions to implement functionality not accessible to M-file S-functions. Such functionality includes the ability to handle data types other than double, complex inputs matrix inputs, and so on
1 Overview of S-Functions 1-12 The primary advantage of MEX-file functions is versatility. The larger number of callbacks and access to the SimStruct enable MEX-file functions to implement functionality not accessible to M-file S-functions. Such functionality includes the ability to handle data types other than double, complex inputs, matrix inputs, and so on