Documentation

S-function name

Specifies the name of the target S-function.

Language

Specifies the target language for S-function. You can choose to generate your S-functions in C/C++, or you can inherit the model settings.

S-function parameters

This table displays the parameters of the target S-function. Each row of the table corresponds to a parameter, and each column displays a property of the parameter as follows:

Build/Save

Use this button to generate the C source code and executable MEX file from the information you entered in the S-Function Builder. If the button is labeled Build, the S-Function Builder generates the source code and executable MEX file. If the button is labeled Save, it generates only the C source code. Use the Save code only check box on the Build Info pane to toggle the functionality of this button.

Hide/Show S-function editing tabs

Use the small button at the bottom-right of the Parameters/S-Function Name pane, to collapse and expand the bottom portion of the S-Function Builder dialog box.

Number of discrete states

Number of discrete states in the S-function.

Discrete states IC

Initial conditions of the discrete states in the S-function. 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 in the S-function.

Continuous states IC

Initial conditions of the continuous states in the S-function. 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:

Sample time value

Scalar value indicating the interval between updates of the S-function outputs. This field is enabled only if you select Discrete as the Sample mode.

Number of PWorks

The number of data pointers used by the S-function. The PWorks points to the memory over the lifecycle of the block. For example, you can declare and initialize a pointer to a file or memory at the Start, and access it in Outputs, Update, and Derivatives panes, and deallocate it at the Terminate pane. The code written in these panes are called by mdlStart, mdlOutputs, mdlUpdate, mdlDerivatives, and mdlTerminate. See the examples Moving Average with Start and Terminate and Permutation using Cpp Classes.

Port name

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

Dimensions

Lists the number of dimensions of the input signal accepted by the port. To display a list of supported dimensions, click the adjacent button. To change the port dimensionality, select a new value from the list. Specify 1-D to size the signal dynamically, regardless of the actual dimensionality of the signal.

Rows

Specifies the size of the first (or only) dimension of the input signal. Specify -1 to size the signal dynamically.

Columns

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

Complexity

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

Bus

If the input signal to the S-Function Builder block is a bus, then use the drop-down menu in the Bus column to select 'on'.

Bus Name

Step 2 of the Build S-Functions Automatically instructs you to create a bus object, if your input signal is a bus. In the field provided in the Bus Name column, enter the bus name that you defined while creating the inport bus object.

Port name

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

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 dimensionality, select a new value from the list. Specify 1-D to size the signal dynamically, regardless of the actual dimensionality of the signal.

Rows

Specifies the size of the first (or only) dimension of the output signal. Specify -1 to size the signal dynamically.

Columns

Specifies the size of the second dimension of the output signal (only if the port outputs 2-D signals).

Complexity

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

Bus

If the output signal to the S-Function Builder block is a bus, then use the drop-down menu in the Bus column to select 'on'.

Bus Name

Step 2 of the Build S-Functions Automatically instructs you to create a bus object. In the field provided in the Bus Name column, enter the name that you defined while creating the outport bus object.

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 data type, select a new type from the list.

Complexity

Specifies whether the parameter has real or complex values.

Port

Name of the port. This field displays the name entered in the Input ports and Output ports panes. You cannot edit this field.

Data Type

Data type of the port. Click the adjacent button to display a list of supported data types. To change the data type, select a different data type from the list.

The remaining fields on this pane are enabled only if the Data Type field specifies a fixed-point data type. See Specify Fixed-Point Data Types for more information.

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 folder, you need specify only the file name. If the file resides in another folder, you must specify the full path of the file.

Alternatively, you can also use this field to specify search paths for libraries, object files, header files, and source files. To do this, enter the tag LIB_PATH, INC_PATH, or SRC_PATH, respectively, followed by the path name. You can make as many entries of this kind as you need but each must reside on a separate line.

For example, consider an S-Function Builder project that resides at d:\matlab6p5\work and needs to link against the following files:

The following entries enable the S-Function Builder to find these files:

SRC_PATH d:\externalsource
LIB_PATH $MATLABROOT\customobjs
LIB_PATH c:\customfolder
customfunctions.lib
userfunctions.obj
freesource.c

As this example illustrates, you can use LIB_PATH to specify both object and library file paths. You can include the library name in the LIB_PATH declaration, however you must place the object file name on a separate line. The tag $MATLABROOT indicates a path relative to the MATLAB installation. You include multiple LIB_PATH entries on separate lines. The paths are searched in the order specified.

You can also enter preprocessor (-D) directives in this field, for example,

-DDEBUG

Each directive must reside on a separate line.

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 folder, you must use the INC_PATH tag in the Library/Object/Source files field to set the include path for the S-Function Builder to the directories containing the include files (see Library/Object/Source files).

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 states or outputs to invoke the external functions.

Code description

Code for the mdlOutputs function that computes the output of the S-function at each 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. The Simulink engine 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 output. The mdlOutputs method in turn invokes the wrapper function containing your output code. Your output code then actually computes and returns the S-function output.

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

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

Select this check box if the current values of the S-function inputs are used to compute its outputs. The Simulink engine uses this information to detect algebraic loops created by directly or indirectly connecting the S-function output to the S-function input.

Compilation diagnostics

Displays information as the S-Function Builder is generating the C source and executable files.

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.

Enable support for coverage

Make S-Function compatible with model coverage. For more information, see Coverage for Custom C/C++ Code in Simulink Models (Simulink Coverage) in Simulink Coverage™ documentation.

Generate wrapper TLC

Selecting this option allows you to generate a TLC file. You need to generate a TLC file if you are running your model in Rapid Accelerator mode or generating Simulink Coder™ code from your model. Also, while it is not necessary for Accelerator mode simulations, the TLC file will generate code for the S-function and thus makes your model run faster in Accelerator mode.

Save code only

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

Enable access to SimStruct

Makes the SimStruct (S) accessible to the wrapper functions that S-Function Builder generates. This enables you to use the SimStruct macros and functions with your code in the Outputs, Continuous Derivatives, and Discrete Updates panes. For example, with this option enabled, you can use macros such as ssGetT in code that computes the S-function outputs:

double t = ssGetT(S);
  if(t < 2 ) {
    y0[0] = u0[0];
  } else {
    y0[0]= 0.0;
  }

Additional methods

Click this button to include additional TLC methods in the TLC file for your S-function. Check the methods you want to add and click the Close button to include the methods in your TLC file. For more information, see Block Target File Methods (Simulink Coder).

Initializing S-Function Settings

The Initialization pane specifies the number of discrete states and their initial conditions, as well as sets the sample time of the S-function. This example contains two discrete states, each initialized to 1, and a discrete sample mode with a sample time of 1.

Initializing Inputs, Outputs, and Parameters

The Data Properties pane specifies the dimensions of the S-function input and output, as well as initializes the state-space matrices.

The Input ports pane defines the one S-function input port as a 1-D vector with two rows.

The Output ports pane similarly defines the one S-function output port as a 1-D vector with two rows.

The Parameters pane defines four parameters, one for each of the four state-space matrices.

The S-function parameters pane at the top of the S-Function Builder contains the actual values for the state-space matrices, entered as MATLAB expressions. In this example, each state-space parameter is a two-by-two matrix. Alternatively, you can store the state-space matrices in variables in the MATLAB workspace and enter the variable names into the Value field for each parameter.

Defining the Output Method

The Outputs pane calculates the S-function output as a function of the input and state vectors and the state-space matrices. In the outputs code, reference S-function parameters using the parameter names defined on the Data Properties — Parameters pane. Index into 2-D matrices using a scalar index, keeping in mind that S-functions use zero-based indexing. For example, to access the element C(2,1) in the S-function parameter C, use C[1]in the S-function code.

The Outputs pane also selects the Inputs are needed in the output function (direct feedthrough) option since this state-space model has a nonzero D matrix.

Defining the Discrete Update Method

The Discrete Update pane updates the discrete states. As with the outputs code, use the S-function parameter names and index into 2-D matrices using a scalar index, keeping in mind that S-functions use zero-based indexing. For example, to access the element A(2,1) in the S-function parameter A, use A[1]in the S-function code. The variable xD stores the final values of the discrete states.

Building the State-Space Example

Click the Build button on the S-Function Builder to create an executable for this S-function. You can now run the model and compare the output to the original discrete state-space S-function contained in sfcndemo_dsfunc.