Pass Dialog Parameters to S-Functions

About Dialog Parameters

You can pass parameters to an S-function at the start of and during the simulation, using the S-function parameters field of the Block Parameters 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 Create and Update S-Function Run-Time Parameters).

Note

You cannot use the Model Explorer, the S-function Block Parameters dialog box, or a mask to tune the parameters of a source S-function, i.e., an S-function that has outputs but no inputs, while a simulation is running. For more information, see Tune and Experiment with Block Parameter Values.

Using C S-Function Dialog Parameters

The Simulink^® engine stores the values of the dialog box parameters in the S-function SimStruct structure. Use the S-function callback methods and SimStruct macros to access and check the parameters and use them to compute the S-function output. To use dialog parameters in your C S-function, perform the following steps when you create the S-function:

Determine the order in which the parameters are to be specified in the block's dialog box.
In the mdlInitializeSizes function, use the ssSetNumSFcnParams macro to tell the Simulink engine how many parameters the S-function accepts. Specify S as the first argument and the number of dialog box parameters 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. For example, the mdlInitializeSizes function in sfun_runtime1.c begins with the following code.
```
ssSetNumSFcnParams(S, NPARAMS);  /* Number of expected parameters */
#if defined(MATLAB_MEX_FILE)
    if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
        mdlCheckParameters(S);
        if (ssGetErrorStatus(S) != NULL) {
            return;
        }
    } else {
        return; /* Parameter mismatch reported by the Simulink engine*/
    }
#endif
```
Access the dialog box parameters 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 macro returns a pointer to the mxArray containing the parameter. You can use ssGetDTypeIdFromMxArray to get the data type of the parameter. Alternatively, you can use ssGetSFcnParamDataType to get the data type of the parameter by specifying the index of the parameter.
For example, in sfun_runtime1.c, the following #define statements at the beginning of the S-function specify the order of three dialog box parameters and access their values on the block's dialog.
```
#define SIGNS_IDX 0
#define SIGNS_PARAM(S) ssGetSFcnParam(S,SIGNS_IDX) /* First parameter */

#define GAIN_IDX  1
#define GAIN_PARAM(S) ssGetSFcnParam(S,GAIN_IDX) /* Second parameter */

#define OUT_IDX   2
#define OUT_PARAM(S) ssGetSFcnParam(S,OUT_IDX) /* Third parameter */
```

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

As another 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 at the top of the S-function 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, enter four variable names or values in the S-function parameters field of the S-Function Block Parameters 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);

Tunable Parameters

Dialog box parameters can be either tunable or nontunable. A tunable parameter is a parameter that a user can change while the simulation is running.

Note

Dialog box parameters are tunable by default. Nevertheless, it is good programming practice to set the tunability of every parameter, even those that are tunable. If you enable the simulation diagnostic S-function upgrades needed, the Simulink engine issues the diagnostic whenever it encounters an S-function that fails to specify the tunability of all its parameters.

The mdlCheckParameters method enables you to validate changes to tunable parameters during a simulation. The engine invokes the mdlCheckParameters method whenever you change the values of parameters during the simulation loop. This method should check the S-function dialog box parameters to ensure that the changes are valid.

The optional mdlProcessParameters callback method allows an S-function to process changes to tunable parameters. The engine invokes this method only if valid parameter changes have occurred in the previous time step. A typical use of this method is to perform computations that depend only on the values of parameters and hence need to be computed only when parameter values change. The method can cache the results of the parameter computations in work vectors or, preferably, as run-time parameters (see Create and Update S-Function Run-Time Parameters).

Using Tunable Parameters in a C S-Function

In a C S-function, use the macro ssSetSFcnParamTunable in mdlInitializeSizes to specify the tunability of each S-function dialog box parameter. The code below is taken from the mdlInitializeSizes function in the example sfun_runtime1.c. The code first sets the number of S-function dialog box parameters to three before invoking mdlCheckParameters. If the parameter check passes, the tunability of the three S-function dialog box parameters is specified.

 ssSetNumSFcnParams(S, 3); /* Three dialog box parameters*/

 #if defined(MATLAB_MEX_FILE)
    if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
        mdlCheckParameters(S);
        if (ssGetErrorStatus(S) != NULL) {
            return;
        }
    } else {
        return; /* Parameter mismatch reported by the Simulink engine*/
    }
 #endif

 ssSetSFcnParamTunable(S,GAIN_IDX,true);   /* Tunable */
 ssSetSFcnParamTunable(S,SIGNS_IDX,false); /* Not tunable */
 ssSetSFcnParamTunable(S,OUT_IDX,false);   /* Not tunable */

Note

The S-function mdlInitializeSizes routine invokes the mdlCheckParameters method to ensure that the initial values of the parameters are valid.

Tuning Parameters in External Mode

When you tune parameters during simulation, the Simulink engine invokes the S-function mdlCheckParameters method to validate the changes and then the S-functions' mdlProcessParameters method to give the S-function a chance to process the parameters in some way. The engine also invokes these methods when running in external mode, but it passes the unprocessed changes to the S-function target. Thus, if it is essential that your S-function process parameter changes, you need to create a Target Language Compiler (TLC) file that inlines the S-function, including its parameter processing code, during the code generation process. For information on inlining S-functions, see “Inlining S-Functions” in the Simulink Coder™ Target Language Compiler documentation.