1 Overview of s-functions What is an s-Function? An S-function is a computer language description of a Simulink block S-functions can be written in MATLAB. C. C++. Ada or Fortran. C. C++.Ada and Fortran S-functions are compiled as MEX-files using the mex utility(see Building MEX-Files"in the online matlaB documentation). As with other MEX-files, they are dynamically linked into MATLAB when needed S-functions use a special calling syntax that enables you to interact with Simulink's equation solvers. This interaction is very similar to the interaction that takes place between the solvers and built-in Simulink blocks. The form of an S-function is very general and can accommodate continuous, discrete and hybrid systems S-functions allow you to add your own blocks to Simulink models. You can create your blocks in MATLAB, C, C++, Fortran, or Ada. By following a set of simple rules, you can implement your algorithms in an S-function. After you write your S-function and place its name in an S-Function block(available in he Functions Tables block library), you can customize the user interface by using masking You can use S-functions with the Real-Time Workshop. You can also customize the code generated by the real Time Workshop for S-functions by writing a Target Language CompilerTM(tlC)file. See"Writing S-Functions for Real-Time Workshop"on page 8-1 and the Real-Time Workshop documentation for more information
1 Overview of S-Functions 1-2 What Is an S-Function? An S-function is a computer language description of a Simulink block. S-functions can be written in MATLAB, C, C++, Ada, or Fortran. C, C++, Ada, and Fortran S-functions are compiled as MEX-files using the mex utility (see “Building MEX-Files” in the online MATLAB documentation). As with other MEX-files, they are dynamically linked into MATLAB when needed. S-functions use a special calling syntax that enables you to interact with Simulink’s equation solvers. This interaction is very similar to the interaction that takes place between the solvers and built-in Simulink blocks. The form of an S-function is very general and can accommodate continuous, discrete, and hybrid systems. S-functions allow you to add your own blocks to Simulink models. You can create your blocks in MATLAB®, C, C++, Fortran, or Ada. By following a set of simple rules, you can implement your algorithms in an S-function. After you write your S-function and place its name in an S-Function block (available in the Functions & Tables block library), you can customize the user interface by using masking. You can use S-functions with the Real-Time Workshop®. You can also customize the code generated by the Real Time Workshop for S-functions by writing a Target Language CompilerTM (TLC) file. See “Writing S-Functions for Real-Time Workshop” on page 8-1 and the Real-Time Workshop documentation for more information
Using S-Functions in Models Using S-Functions in Models To incorporate an S-function into an Simulink model, drag an S-Function block from Simulinks Functions Tables block library into the model. Then speci the name of the s-function in the sfunction name field of the s-function blocks dialog box, as illustrated in the following figure S-function dialog box block Blocks may be written n M, C or Fortian and must ction by Simuink. " Extra"parameters may be specified in th S-function source file A model that includes two myefun\ s-function blocks MYSFUN Gauntest Fie Edit Simulaton Format S-Functionl dialog box C mEX file mystus function parameters'field ta'i switch(flag) -funchon pat M file Figure 1-1: Relationship Between an S-Function Block, Its Dialog Box, and the Source file That Defines the block,s behavior In this example, the model contains two instances of an S-Function block. Both blocks reference the same source file(mysfun, which can be either a C mEX-file or an M-file). If both a c MEX-file and an M-file have the same name the c MEX-file takes precedence and is the file that the s-function uses
Using S-Functions in Models 1-3 Using S-Functions in Models To incorporate an S-function into an Simulink model, drag an S-Function block from Simulink’s Functions & Tables block library into the model. Then specify the name of the S-function in the S-function name field of the S-Function block’s dialog box, as illustrated in the following figure. Figure 1-1: Relationship Between an S-Function Block, Its Dialog Box, and the Source File That Defines the Block’s Behavior In this example, the model contains two instances of an S-Function block. Both blocks reference the same source file (mysfun, which can be either a C MEX-file or an M-file). If both a C MEX-file and an M-file have the same name, the C MEX-file takes precedence and is the file that the S-function uses. S-Function1 dialog box /* * MYSFUN * */ /* The follo #define S_FU . . . function[sys % mysfun M-file % switch(flag) . . . S-function dialog box A model that includes two S-function blocks S-function source file C MEX file or M file
1 Overview of s-functions Passing Parameters to S-Functions The S-function block's S-function parameters field allows you to specify parameter values to be passed to the corresponding S-function. To use this field, you must know the parameters the S-function requires and the order in which the function requires them. (If you do not know, consult the S-function's author, documentation, or source code. Enter the parameters, separated by comma, in the order required by the s-function. The parameter values can be constants, names of variables defined in the model's workspace or MAtLAB The following example illustrates usage of the S-function parameters field to enter user-defined parameters y limintm H S-Function Scope User-defnable block Blocks may be written in M C Octan or Ada and Parametes Sfunction name Sfunction parameters c_h」 The model in this example incorporates limintm, a sample S-function that comes with Simulink. The function's source code resides in oolbox/simulink/blocks. The limintm function accepts three parameters lower bound, an upper bound, and an initial condition. It outputs the time integral of the input signal if the time integral is between the lower and upper bounds, the lower bound if the time integral is less than the lower bound, and the upper bound if the time integral is greater than the upper bound. The dialog box in the example specifies a lower and upper bound and an initial condition of 2, 3, and 2.5, respectively. The scope shows the resulting output when the input is a sine wave of amplitude 1
1 Overview of S-Functions 1-4 Passing Parameters to S-Functions The S-function block’s S-function parameters field allows you to specify parameter values to be passed to the corresponding S-function. To use this field, you must know the parameters the S-function requires and the order in which the function requires them. (If you do not know, consult the S-function’s author, documentation, or source code.) Enter the parameters, separated by a comma, in the order required by the S-function. The parameter values can be constants, names of variables defined in the model’s workspace, or MATLAB expressions. The following example illustrates usage of the S-function parameters field to enter user-defined parameters. The model in this example incorporates limintm, a sample S-function that comes with Simulink. The function’s source code resides in toolbox/simulink/blocks. The limintm function accepts three parameters: a lower bound, an upper bound, and an initial condition. It outputs the time integral of the input signal if the time integral is between the lower and upper bounds, the lower bound if the time integral is less than the lower bound, and the upper bound if the time integral is greater than the upper bound. The dialog box in the example specifies a lower and upper bound and an initial condition of 2, 3, and 2.5, respectively. The scope shows the resulting output when the input is a sine wave of amplitude 1
Using S-Functions in Models see“ Processing S- Function parameters” on page2-6and“ Handling errors”on page 7-33 for information on how to access user-specified parameters in an S-function You can use Simulinks masking facility to create custom dialog boxes and icons for your S-function blocks. Masked dialog boxes can make it easier to pecify additional parameters for S-functions. For discussions of additional parameters and masking, see Using Simulink When to use an s-function The most common use of S-functions is to create custom Simulink blocks. You can use S-functions for a variety of applications, including Adding new general purpose blocks to Simulink Adding blocks that represent hardware device drivers Incorporating existing C code into a simulation Describing a system as a set of mathematical equations Using graphical animations(see the inverted pendulum demo, penddemo) An advantage of using S-functions is that you can build a general purpose block that you can use many times in a model, varying parameters with each instance of the block 1-5
Using S-Functions in Models 1-5 See “Processing S-Function Parameters” on page 2-6 and “Handling Errors” on page 7-33 for information on how to access user-specified parameters in an S-function. You can use Simulink’s masking facility to create custom dialog boxes and icons for your S-function blocks. Masked dialog boxes can make it easier to specify additional parameters for S-functions. For discussions of additional parameters and masking, see Using Simulink. When to Use an S-Function The most common use of S-functions is to create custom Simulink blocks. You can use S-functions for a variety of applications, including • Adding new general purpose blocks to Simulink • Adding blocks that represent hardware device drivers • Incorporating existing C code into a simulation • Describing a system as a set of mathematical equations • Using graphical animations (see the inverted pendulum demo, penddemo) An advantage of using S-functions is that you can build a general purpose block that you can use many times in a model, varying parameters with each instance of the block
Overview of s-Functions H。ws- Functions work To create S-functions, you need to know how S-functions work. Understanding how S-functions work, in turn, requires understanding how Simulir simulates a model, and this, in turn requires an understanding of the mathematics of blocks. This section therefore begins by explaining the mathematical relationship between a block's inputs, states, and outputs Mathematics of simulink blocks A Simulink block consists of a set of inputs, a set of states, and a set of outputs where the outputs are a function of the sample time the inputs, and the blocks states (states) (output) The following equations express the mathematical relationships between the inputs, outputs, and the states y=fo(t, x, u) (Output) xe=fa(t, x, u) (Derivative) xd,=fu(t, x, u) (Update) where x=x +x Simulati。 n Stages Execution of a Simulink model proceeds in stages. First comes the initialization phase. In this phase, Simulink incorporates library blocks into the model, propagates widths, data types, and sample times, evaluates block parameters, determines block execution order, and allocates memory. Then Simulink enters a simulation loop, where each pass through the loop is referred
1 Overview of S-Functions 1-6 How S-Functions Work To create S-functions, you need to know how S-functions work. Understanding how S-functions work, in turn, requires understanding how Simulink simulates a model, and this, in turn requires an understanding of the mathematics of blocks. This section therefore begins by explaining the mathematical relationship between a block’s inputs, states, and outputs. Mathematics of Simulink Blocks A Simulink block consists of a set of inputs, a set of states, and a set of outputs, where the outputs are a function of the sample time, the inputs, and the block’s states. The following equations express the mathematical relationships between the inputs, outputs, and the states. Simulation Stages Execution of a Simulink model proceeds in stages. First comes the initialization phase. In this phase, Simulink incorporates library blocks into the model, propagates widths, data types, and sample times, evaluates block parameters, determines block execution order, and allocates memory. Then Simulink enters a simulation loop, where each pass through the loop is referred x (states) u y (input) (output) (Output) (Derivative) (Update) where x x c xd = + y f0 = ( ) txu , , x · c fd = ( ) txu , , xdk + 1 fu = ( ) txu ,