Writing S-Functions

Run-Time Parameters

Simulink allows an S-function to create and use internal representations of external dialog parameters called run-time parameters. Every run-time parameter corresponds to one or more dialog parameters and can have the same value and data type as its corresponding external parameters or a different value or data type. If a run-time parameter differs in value or data type from its external counterpart, the dialog parameter is said to have been transformed to create the run-time parameter. The value of a run-time parameter that corresponds to multiple dialog parameters is typically a function of the values of the dialog parameters. Simulink allocates and frees storage for run-time parameters and provides functions for updating and accessing them, thus eliminating the need for S-functions to perform these tasks.

Run-time parameters facilitate the following kinds of S-function operations:

• Computed parameters

• Often the output of a block is a function of the values of several dialog parameters. For example, suppose a block has two parameters, the volume and density of some object, and the output of the block is a function of the input signal and the weight of the object. In this case, the weight can be viewed as a third internal parameter computed from the two external parameters, volume and density. An S-function can create a run-time parameter corresponding to the computed weight, thereby eliminating the need to provide special case handling for weight in the output computation.

• Data type conversions

• Often a block needs to change the data type of a dialog parameter to facilitate internal processing. For example, suppose that the output of the block is a function of the input and a parameter and the input and parameter are of different data types. In this case, the S-function can create a run-time parameter that has the same value as the dialog parameter but has the data type of the input signal, and use the run-time parameter in the computation of the output.

• Code generation

• During code generation, Real-Time Workshop writes all run-time parameters automatically to the model.rtw file, eliminating the need for the S-function to perform this task via an mdlRTW method.

Creating Run-Time Parameters

An S-function can create run-time parameters all at once or one by one.

Creating Run-Time Parameters All at Once

Use the SimStruct function ssRegAllTunableParamsAsRunTimeParams in mdlSetWorkWidths to create run-time parameters corresponding to all tunable parameters. This function requires that you pass it an array of names, one for each run-time parameter. Real-Time Workshop uses this name as the name of the parameter during code generation.

This approach to creating run-time parameters assumes that there is a one-to-one correspondence between an S-function's run-time parameters and its tunable dialog parameters. This might not be the case. For example, an S-function might want to use a computed parameter whose value is a function of several dialog parameters. In such cases, the S-function might need to create the run-time parameters individually.

Creating Run-Time Parameters Individually

    To create run-time parameters individually, the S-function's mdlSetWorkWidths method should:

1. Specify the number of run-time parameters it intends to use, using ssSetNumRunTimeParams.
2. Use ssRegDlgParamAsRunTimeParam to register a run-time parameter that corresponds to a single, untransformed dialog parameter or ssSetRunTimeParamInfo to set the attributes of a run-time parameter that corresponds to more than one dialog parameter or a transformed dialog parameter.

Note    The first four characters of block's run-time parameter names must be unique. If they are not, Simulink signals an error. For example, trying to register a parameter named param2 triggers an error if a parameter named param1 already exists.

Updating Run-Time Parameters

Whenever a user changes the values of an S-function's dialog parameters during a simulation run, Simulink invokes the S-function's mdlCheckParameters method to validate the changes. If the changes are valid, Simulink invokes the S-function's mdlProcessParameters method at the beginning of the next time step. This method should update the S-function's run-time parameters to reflect the changes in the dialog parameters.

Updating All Parameters at Once

If there is a one-to-one correspondence between the S-function's tunable dialog parameters and the run-time parameters, the S-function can use the SimStruct function ssUpdateAllTunableParamsAsRunTimeParams to accomplish this task. This function updates each run-time parameter to have the same value as the corresponding dialog parameter.

Updating Parameters Individually

If there is not a one-to-one correspondence between the S-function's dialog and run-time parameters or the run-time parameters are transformed versions of the dialog parameters, the mdlProcessParameters method must update each parameter individually.

If a run-time parameter and its corresponding dialog parameter differ only in value, the method can use ssUpdateRunTimeParamData to update the run-time parameter. This function updates the data field in the parameter's attributes record, ssParamRec, with a new value. If the run-time parameter and the dialog parameter differ only in value and data type, the method can use ssUpdateDlgParamAsRunTimeParam to update the run-time parameter. Otherwise, the mdlProcessParameters method must update the parameter's attributes record itself. To update the attributes record, the method should:

1. Get a pointer to the parameter's attributes record, using ssGetRunTimeParamInfo.
2. Update the attributes record to reflect the changes in the corresponding dialog parameters.
3. Register the changes, using ssUpdateRunTimeParamInfo.

Tunable Parameters

Creating Input and Output Ports