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:

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.

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