Writing S-Functions

Dialog Parameters

A user can pass parameters to an S-function at the start of and, optionally, during the simulation, using the S-Function parameters field of the block's dialog box. Such parameters are called dialog box parameters to distinguish them from run-time parameters created by the S-function to facilitate code generation (see Run-Time Parameters). Simulink stores the values of the dialog box parameters in the S-function's SimStruct structure. Simulink provides callback methods and SimStruct macros that allow the S-function to access and check the parameters and use them in the computation of the block's output.

If you want your S-function to be able to use dialog parameters, you must perform the following steps when you create the S-function:

1. Determine the order in which the parameters are to be specified in the block's dialog box.
2. In the mdlInitializeSizes function, use the ssSetNumSFcnParams macro to tell Simulink how many parameters the S-function accepts. Specify S as the first argument and the number of parameters you are defining interactively as the second argument. If your S-function implements the mdlCheckParameters method, the mdlInitializeSizes routine should call mdlCheckParameters to check the validity of the initial values of the parameters.
3. Access these input arguments in the S-function using the ssGetSFcnParam macro.

Specify S as the first argument and the relative position of the parameter in the list entered on the dialog box (0 is the first position) as the second argument. The ssGetSFcnParam returns a pointer to the mxArray containing the parameter. You can use ssGetDTypeIdFromMxArray to get the data type of the parameter.

When running a simulation, the user must specify the parameters in the S-Function parameters field of the block's dialog box in the same order that you defined them in step 1 above. The user can enter any valid MATLAB expression as the value of a parameter, including literal values, names of workspace variables, function invocations, or arithmetic expressions. Simulink evaluates the expression and passes its value to the S-function.

For example, the following code is part of a device driver S-function. Four input parameters are used: BASE_ADDRESS_PRM, GAIN_RANGE_PRM, PROG_GAIN_PRM, and NUM_OF_CHANNELS_PRM. The code uses #define statements to associate particular input arguments with the parameter names.

/* Input Parameters */
#define BASE_ADDRESS_PRM(S)     ssGetSFcnParam(S, 0)
#define GAIN_RANGE_PRM(S)       ssGetSFcnParam(S, 1)
#define PROG_GAIN_PRM(S)        ssGetSFcnParam(S, 2)
#define NUM_OF_CHANNELS_PRM(S)  ssGetSFcnParam(S, 3)

When running the simulation, a user would enter four variable names or values in the S-Function parameters field of the block's dialog box. The first corresponds to the first expected parameter, BASE_ADDRESS_PRM(S). The second corresponds to the next expected parameter, and so on.

The mdlInitializeSizes function contains this statement.

ssSetNumSFcnParams(S, 4);

Implementing Block Features

Tunable Parameters