| Writing S-Functions | |
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 parameter(s) 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 parameter 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 performs these tasks.
Run-time parameters facilitate the following kinds of S-function operations:
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.
Often a block may need 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.
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 a 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 may not be the case. For example, an S-function may want to use a computed parameter whose value is a function of several dialog parameters. In such cases, the S-function may 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:
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 the SimStruct macro, ssUpdateRunTimeParamData, to update the run-time parameter. This function updates the data field in the parameter's attributes record (ssParamRec) with a new value. Otherwise, the mdlProcessParameters method must update the parameter's attributes record itself.To update the attributes record, the method should:
| | Tunable Parameters | Input and Output Ports | |