Writing S-Functions in C (Writing S-Functions)

Writing S-Functions

S-Function Builder Dialog Box

The tabbed panes on the S-Function Builder dialog box enable you to enter information and custom code required to tailor the S-function to a specific application. The dialog box contains the following panes.

Initialization Pane

The Initialization pane allows you to specify basic features of the S-function, such as the width of its input and output ports and its sample time.

The S-Function Builder uses the information that you enter on this pane to generate the S-function's mdlInitializeSizes callback method. Simulink invokes this method during the model initialization phase of the simulation to obtain basic information about the S-function. (See How Simulink Interacts with C S-Functions for more information on the model initialization phase.)

The Initialization pane contains the following fields.

Number of discrete states. Number of discrete states that the S-function has.

Discrete states IC. Initial conditions of the S-function's discrete states. You can enter the values as a comma-separated list or as a vector (e.g., [0 1 2]). The number of initial conditions must equal the number of discrete states.

Number of continuous states. Number of continuous states that the S-function has.

Continuous states IC. Initial conditions of the S-function's continuous states. You can enter the values as a comma-separated list or as a vector (e.g., [0 1 2]). The number of initial conditions must equal the number of continuous states.

Sample mode. Sample mode of the S-function. The sample mode determines the length of the interval between the times when the S-function updates its output. You can select one of the following options:

Inherited

The S-function inherits its sample time from the block connected to its input port.

Continuous

The block updates its outputs at each simulation step.

Discrete

The S-function updates its outputs at the rate specified in the Discrete sample time value field of the S-Function Builder dialog box.

Sample time value. Interval between updates of the S-function's outputs. This field is enabled only if you have selected Discrete as the S-function's Sample time.

Input port width. Width of the S-function's input port. The width is the number of elements that a vector signal connected to the port must have. To permit connection of matrix (2-D) signals to the input port, specify -1 as the input port width.

Output port width. Width of the S-function's output port. The width is the number of elements in the vector that this S-function outputs. If the S-function outputs matrix signals, specify -1 as the port width.

Number of parameters. Number of parameters that this S-function accepts.

Data Properties Pane

The Data Properties pane allows you to add ports and parameters to your S-function.

This pane itself contains tabbed panes that respectively display the attributes of the S-function's

Input ports (see Input Ports Pane)

Output ports (see Output Ports Pane)

Parameters (see Parameters Pane),

The column of buttons to the left of the panes allows you to add, delete, or reorder ports or parameters, depending on the currently selected pane.

To add add a port or parameter, click the Add button (the top button in the column of buttons).

To delete the currently selected port/parameter , click the Delete button (located beneath the Add button).

To move the currently selected port/parameter up one position in the corresponding S-Function port/parameter list, click the Up button (beneath the Delete button).

To move the currently selected port/parameter down one position in the corresponding S-function port/parameter list, click the Down button (beneath the Up button).

Input Ports Pane

The Input Ports pane allows you to inspect and modify the properties of the S-function's input ports.

The pane comprises an editable table that lists the properties of the input ports in the order in which the ports appear on the S-function block. Each row of the table corresponds to a port. Each entry in the row displays a property of the port as follows.

Port name. Name of the port. Edit this field to change the port name.

Data type

Lists the data type of signals accepted by the port. Click the adjacent button to display a list of supported data types. To change the port's data type, select a new type from the list.

Dimensions. Lists the number of dimensions of input signals accepted by the port. To display a list of supported dimensions, click the adjacent button. To change the port's dimensionality, select a new value from the list. (Simulink signals can have at most two dimensions).

Row. Specifies the size of the input signal's first (or only) dimension.

Column. Specifies the size of the input signal's second dimension (only if the input port accepts 2-D signals).

Complexity. Specifies whether the input port accepts real or complex-valued signals.

Frame. Specifies whether this port accepts frame-based signals generated by the Digital and Signal Processing Blockset and Communications Blockset. See the documentation for these blocksets for more information.

Output Ports Pane

The Output Ports pane allows you to inspect and modify the properties of the S-function's output ports.

The pane comprises an editable table that lists the properties of the output ports in the order in which the ports appear on the S-function block. Each row of the table corresponds to a port. Each entry in the row displays a property of the port as follows.

Port name. Name of the port. Edit this field to change the port name.

Data type

Lists the data type of signals output by the port. Click the adjacent button to display a list of supported data types. To change the port's data type, select a new type from the list.

Dimensions. Lists the number of dimensions of signals output by the port. To display a list of supported dimensions, click the adjacent button. To change the port's dimensionality, select a new value from the list. (Simulink signals can have at most two dimensions).

Row. Specifies the size of the output signal's first (or only) dimension.

Column. Specifies the size of the output signal's second dimension (only if the output port accepts 2-D signals).

Complexity. Specifies whether the port outputs real or complex-valued signals.

Parameters Pane

The Parameters pane allows you to inspect and modify the properties of the S-function's parameters.

The pane comprises an editable table that lists the properties of the S-function's parameters . Each row of the table corresponds to a port. The order in which the parameters appear corresponds to the order in which the user must specify them. Each entry in the row displays a property of the parmeter as follows.

Parameter name. Name of the parameter. Edit this field to change the name.

Data type

Lists the data type of the parameter. Click the adjacent button to display a list of supported data types. To change the parameter's data type, select a new type from the list.

Complexity. Specifies whether the parameter has real or complex values.

Libraries Pane

The Libraries pane allows you to specify the location of external code files referenced by custom code that you enter in other panes of the S-Function Builder dialog box.

The Libraries pane includes the following fields.

Library/Object/Source files. External library, object code, and source files referenced by custom code that you enter elsewhere on the S-Function Builder dialog box. List each file on a separate line. If the file resides in the current directory, you need specify only the file's name. If the file resides in another directory, you must specify the full path of the file.

Includes. Header files containing declarations of functions, variables, and macros referenced by custom code that you enter elsewhere on the S-Function Builder dialog box. Specify each file on a separate line as #include statements. Use brackets to enclose the names of standard C header files (e.g., #include <math.h>). Use quotation marks to enclose names of custom header files (e.g., #include "myutils.h"). If your S-function uses custom include files that do not reside in the current directory, you must set the S-Function Builder's include path to the directories containing the include files (see Setting the Include Path).

External function declarations. Declarations of external functions not declared in the header files listed in the Includes field. Put each declaration on a separate line. The S-Function Builder includes the specified declarations in the S-function source file that it generates. This allows S-function code that computes the S-function's states or output to invoke the external functions.

Outputs Pane

Use the Outputs pane to enter code that computes the outputs of the S-function at each simulation time step.

The Outputs pane contains the following fields.

Code for the mdlOutputs function. Code that computes the output of the S-function at each simulation time step (or sample time hit in the case of a discrete S-function). When generating the source code for the S-function, the S-Function Builder inserts the code in this field in a wrapper function of the form

void sfun_Outputs_wrapper(const real_T *u,
                         real_T       *y,
                         const real_T *xD, /* optional */
                         const real_T *xC, /* optional */
                         const real_T  *param0, /* optional */
                         int_T p_width0 /* optional */
                         real_T  *param1 /* optional */
                         int_t p_width1 /* optional */
                         int_T y_width, /* optional */
                         int_T u_width) /* optional */
{

/* Your code inserted here */
}

where sfun is the name of the S-function. The S-Function Builder inserts a call to this wrapper function in the mdlOutputs callback method that it generates for your S-function. Simulink invokes the mdlOutputs method at each simulation time step (or sample time step in the case of a discrete S-function) to compute the S-function's output. The S-function's mdlOutputs method in turn invokes the wrapper function containing your output code. Your output code then actually computes and returns the S-function's output.

The mdlOutputs method passes some or all of the following arguments to the outputs wrapper function.

Argument
Description

u
Pointer to an array containing the inputs to the S-function. The width of the array is the same as the input width you specified on the Initialization pane. If you specified -1 as the input width, the width of the array is specified by the wrapper function's u_width argument (see below).

y
Pointer to an array containing the output of the S-function.The width of the array is the same as the output width you specified on the Initialization pane. If you specified -1 as the output width, the width of the array is specified by the wrapper function's y_width argument (see below). Use this array to pass the outputs that your code computes back to Simulink.

xD
Pointer to an array containing the discrete states of the S-function. This argument appears only if you specified discrete states on the Initialization pane. At the first simulation time step, the discrete states have the initial values that you specified on the Initialization pane. At subsequent sample-time steps, the states are obtained from the values that the S-function computes at the preceding time step (see Discrete Update Pane for more information).

xC
Pointer to an array containing the continuous states of the S-function. This argument appears only if you specified continuous states on the Initialization pane. At the first simulation time step, the continuous states have the initial values that you specified on the Initialization pane. At subsequent time steps, the states are obtained by numerically integrating the derivatives of the states at the preceding time step (see Continuous Derivatives Pane for more information).

param0, p_width0, param1, p_width1, ... paramN, p_widthN
param0, param1, paramN are pointers to arrays containing the S-function's parameters, where N is the number of parameters specified on the Initialization pane. p_width0, p_width1, p_widthN are the widths of the parameter arrays. If a parameter is a matrix, the width equals the product of the dimensions of the arrays. For example, the width of a a 3-by-2 matrix parameter is 6. These arguments appear only if you specify parameters on the Initialization pane.

y_width
Width of the array containing the S-function's outputs. This argument appears in the generated code only if you specified -1 as the width of the S-function's output. If the output is a matrix, y_width is the product of the dimensions of the matrix.

u_width
Width of the array containing the S-function's inputs. This argument appears in the generated code only if you specified -1 as the width of the S-function's input. If the input is a matrix, u_width is the product of the dimensions of the matrix.

Argument	Description
`u`	Pointer to an array containing the inputs to the S-function. The width of the array is the same as the input width you specified on the Initialization pane. If you specified -1 as the input width, the width of the array is specified by the wrapper function's `u_width` argument (see below).
`y`	Pointer to an array containing the output of the S-function.The width of the array is the same as the output width you specified on the Initialization pane. If you specified -1 as the output width, the width of the array is specified by the wrapper function's `y_width` argument (see below). Use this array to pass the outputs that your code computes back to Simulink.
`xD`	Pointer to an array containing the discrete states of the S-function. This argument appears only if you specified discrete states on the Initialization pane. At the first simulation time step, the discrete states have the initial values that you specified on the Initialization pane. At subsequent sample-time steps, the states are obtained from the values that the S-function computes at the preceding time step (see Discrete Update Pane for more information).
`xC`	Pointer to an array containing the continuous states of the S-function. This argument appears only if you specified continuous states on the Initialization pane. At the first simulation time step, the continuous states have the initial values that you specified on the Initialization pane. At subsequent time steps, the states are obtained by numerically integrating the derivatives of the states at the preceding time step (see Continuous Derivatives Pane for more information).
`param0`, `p_width0`, `param1`, `p_width1`, ... `paramN`, `p_widthN`	`param0`, `param1`, `paramN` are pointers to arrays containing the S-function's parameters, where `N` is the number of parameters specified on the Initialization pane. `p_width0`, `p_width1`, `p_widthN` are the widths of the parameter arrays. If a parameter is a matrix, the width equals the product of the dimensions of the arrays. For example, the width of a a 3-by-2 matrix parameter is 6. These arguments appear only if you specify parameters on the Initialization pane.
`y_width`	Width of the array containing the S-function's outputs. This argument appears in the generated code only if you specified -1 as the width of the S-function's output. If the output is a matrix, `y_width` is the product of the dimensions of the matrix.
`u_width`	Width of the array containing the S-function's inputs. This argument appears in the generated code only if you specified -1 as the width of the S-function's input. If the input is a matrix, `u_width` is the product of the dimensions of the matrix.

These arguments permit you to compute the output of the block as a function of its inputs and, optionally, its states and parameters. The code that you enter in this field can invoke external functions declared in the header files or external declarations on the Libraries pane. This allows you to use existing code to compute the outputs of the S-function.

Inputs are needed in the output function. Selected if the current values of the S-function's inputs are used to compute its outputs. Simulink uses this information to detect algebraic loops created by directly or indirectly connecting the S-function's output to its input.

Continuous Derivatives Pane

If the S-function has continuous states, use the Continuous Derivatives pane to enter code required to compute the state derivatives.

Enter code to compute the derivatives of the S-function's continuous states in the Code for the mdlDerivatives function field on this pane. When generating code, the S-Function Builder takes the code in this pane and inserts it in a wrapper function of the form

void sfun_Derivatives_wrapper(const real_T *u,
                             const real_T *y, 
                             real_T *dx,
                             real_T *xC, 
                             const real_T  *param0,  /* optional */
                             int_T p_width0, /* optional */
                             real_T  *param1,/* optional */
                             int_T p_width1, /* optional */
                             int_T y_width, /* optional */
                             int_T u_width) /* optional */
{

    /* Your code inserted here. */

}

where sfun is the name of the S-function. The S-Function Builder inserts a call to this wrapper function in the mdlDerivatives callback method that it generates for the S-function. Simulink calls the mdlDerivatives method at the end of each time step to obtain the derivatives of the S-function's continuous states (see How Simulink Interacts with C S-Functions). Simulink's solver numerically integrates the derivatives to determine the continuous states at the next time step. At the next time step, Simulink passes the updated states back to the S-function's mdlOutputs method (see Outputs Pane).

The generated S-function's mdlDerivatives callback method passes the following arguments to the derivatives wrapper function:

dx

xC

param0, p_width0, param1, p_width1, ... paramN, p_widthN

y_width

x-width

The dx argument is a pointer to an array whose width is the same as the number of continuous derivatives specified on the Initialization pane. Your code should use this array to return the values of the derivatives that it computes. See mdlOutputs for the meanings and usage of the other arguments. The arguments allow your code to compute derivatives as a function of the S-function's inputs, outputs, and, optionally, parameters. Your code can invoke external functions declared on the Libraries pane.

Discrete Update Pane

If the S-function has discrete states, use the Discrete Update pane to enter code that computes at the current time step the values of the discrete states at the next time step.

Enter code to compute the values of the S-function's discrete states in the Code for the mdlUpdate function field on this pane. When generating code, the S-Function Builder takes the code in this pane and inserts it in a wrapper function of the form

void sfun_Update_wrapper(const real_T *u,
                         const real_T *y, 
                         real_T *xD, 
                         const real_T  *param0,  /* optional */
                         int_T p_width0, /* optional */
                         real_T  *param1,/* optional */
                         int_T p_width1, /* optional */
                         int_T y_width, /* optional */
                         int_T u_width) /* optional */
{

    /* Your code inserted here. */

}

where sfun is the name of the S-function. The S-Function Builder inserts a call to this wrapper function in the mdlUpdate callback method that it generates for the S-function. Simulink calls the mdlUpdate method at the end of each time step to obtain the values of the S-function's discrete states at the next time step (see How Simulink Interacts with C S-Functions). At the next time step, Simulink passes the updated states back to the S-function's mdlOutputs method (see Outputs Pane).

The generated S-function's mdlUpdates callback method passes the following arguments to the updates wrapper function:

xD

param0, p_width0, param1, p_width1, ... paramN, p_widthN

y_width

x-width

See mdlOutputs for the meanings and usage of these arguments. Your code should use the xD (discrete states) variable to return the values of the derivatives that it computes. The arguments allow your code to compute the discrete states as functions of the S-function's inputs, outputs, and, optionally, parameters. Your code can invoke external functions declared on the Libraries pane.

Build Info Pane

Use the Build Info pane to specify options for building the S-function MEX file.

This pane contains the following fields.

Compilation diagnostics. Display diagnostic messages issued by the S-Function Builder when building the S-function.

Show compile steps. Log each build step in the Compilation diagnostics field.

Create a debuggable MEX-file. Include debug information in the generated MEX-file.

Generate wrapper TLC. Generate a TCL file. You do not need to generate a TLC file if you do not expect the S-function ever to run in accelerated mode or be used in a model from which RTW generates code.

Save code only. Do not build a MEX file from the generated source code.

Building S-Functions Automatically Setting the Include Path