Writing S-Functions

Specifying Port-Based Sample Times

If you want your S-function to use port-based sample times, you must specify the number of sample times as port-based in the S-function's mdlInitializeSizes method:

• ssSetNumSampleTimes(S, PORT_BASED_SAMPLE_TIMES)
  

You must also specify the sample time of each input and output port in the S-function's mdlInitializeSizes method, using the following macros

• ssSetInputPortSampleTime(S, idx, period)
  ssSetInputPortOffsetTime(S, idx, offset)
  ssSetOutputPortSampleTime(S, idx, period)
  ssSetOutputPortOffsetTime(S, idx, offset)
  

Note    mdlInitializeSizes should not contain any ssSetSampleTime or ssSetOffsetTime calls when you use port-based sample times.

For any given port, you can specify

• a specific sample time and period

• For example, the following code sets the sample time of the S-function's first input port to every 0.1 s starting with the simulation start time.

  • ssSetInputPortSampleTime(S, 0, 0.1);
    ssSetInputPortOffsetTime(S, 0, 0);
    

• inherited sample time, i.e., the port inherits its sample time from the port to which it is connected (see Specifying Inherited Sample Time for a Port)
• constant sample time, i.e., the port's input or output never changes (see Specifying Constant Sample Time for a Port)

Note    To be usable in a triggered subsystem, all of your S-function's ports must have either inherited or constant sample time (see Configuring Port-Based Sample Times for Use in Triggered Subsystems).

Specifying Inherited Sample Time for a Port

To specify that a port's sample time is inherited, the mdlInitializeSizes method should set its period to -1 and its offset to 0. For example, the following code specifies inherited sample time for the S-function's first input port:

• ssSetInputPortSampleTime(S, 0, -1);
  ssSetInputPortOffsetTime(S, 0, 0);
  

When you specify port-based sample times, Simulink calls mdlSetInputPortSampleTime and mdlSetOutputPortSampleTime to determine the rates of inherited signals.

Once all rates have been determined, Simulink calls mdlInitializeSampleTimes. Even though there is no need to initialize port-based sample times at this point, Simulink invokes this method to give your S-function an opportunity to configure function-call connections. Your S-function must thus provide an implementation for this method regardless of whether it uses port-based sample times or function-call connections. Although you can provide an empty implementation, you might want to use it to check the appropriateness of the sample times that the block inherited during sample time propagation.

Specifying Constant Sample Time for a Port

If your S-function uses port-based sample times, it can specify that any of its ports has a constant sample time. This means that the signal entering or leaving the port never changes from its initial value at the start of the simulation.

Before specifying constant sample time for an output port whose output depends on the S-function's parameters, the S-function should use ssGetInlineParameters to check whether the user has specified the Inline parameters option on the Advanced pane of the Simulation parameters dialog box. If the user has not checked this option, it is possible for the user to change the values the S-function's parameters and hence its outputs during the simulation. In this case, the S-function should not specify a constant sample time for any ports whose outputs depend on the S-function's parameters.

To specify constant sample time for a port, the S-function must perform the following tasks

• Tell Simulink that it supports constant port sample times in its mdlInitializeSizes method:

• ssSetOptions(S, SS_OPTION_ALLOW_CONSTANT_PORT_SAMPLE_TIME);
  

Note    By setting this option, your S-function is in effect telling Simulink that all of its ports support a constant sample time including ports that inherit their sample times from other blocks. If any of the S-function's inherited sample time ports cannot have a constant sample time, your S-function's mdlSetInputPortSampleTime and mdlSetOutputPortSampleTime methods must eheck whether that port has inherited a constant sample time. If the port has inherited a constant sample time, your S-function should throw an error.

• Set the port's period to inf and its offset to 0, e.g.,

• ssSetInputPortSampleTime(S, 0, mxGetInf());
  ssSetInputPortOffsetTime(S, 0, 0);
  

• Check in mdlOutputs whether the method's tid argument equals CONSTANT_TID and if so, set the value of the port's output if it is an output port.

See sfun_port_constant.c, the source file for the sfcndemo_port_constant demo, for an example of how to create ports with a constant sample time.

Configuring Port-Based Sample Times for Use in Triggered Subsystems

To be usable in a triggered subsystem, your port-based sample time S-function must perform the following tasks.

• Tell Simulink in its mdlInitializeSizes method that it can run in a triggered subsystem:

• ssSetOptions(S, 
  SS_OPTION_ALLOW_PORT_BASED_SAMPLE_TIME_IN_TRIGSS);
  

• Set all of its ports to have either inherited or constant sample time in its mdlInitializeSizes method.
• Handle inheritance of a triggered sample time in mdlSetInputPortSampleTime and mdlSetOutputPortSampleTime methods as follows.

• If the S-function resides in a triggered subsystem, Simulink invokes either mdlSetInputPortSampleTime or mdlSetOutputPortSampleTime once per time step. Whichever method is called must set the sample time and offset of the port for which it is called to INHERITED_SAMPLE_TIME (-1), e.g.,

  • ssSetInputPortSampleTime(S, 0, INHERITED_SAMPLE_TIME);
    ssSetInputPortOffsetTime(S, 0, INHERITED_SAMPLE_TIME);
    

  Setting a port's sample time and offset both to INHERITED_SAMPLE_TIME indicates that the sample time of the port is triggered, i.e., it produces an output or accepts an input only when the subsystem in which it resides is triggered. The method must also set the sample times and offsets of all of the S-function's other input and output ports to have either triggered or constant sample time, whichever is appropriate.

  There is no way for an S-function residing in a triggered subsystem to predict whether Simulink will call mdlSetInputPortSampleTime or mdlSetOutputPortSampleTime to set its port sample times. For this reason, both methods must be able to set the sample times correctly.

• In mdlUpdate and mdlOutputs, use ssGetPortBasedSampleTimeBlockIsTriggered to check whether the S-function resides in a triggered subsystem and if so, use appropriate algorithms for computing its states and outputs.

See sfun_port_triggered.c, the source file for the sfcndemo_port_triggered demo, for an example of how to create ports with a constant sample time.

Hybrid Block-Based and Port-Based Sample Times

The hybrid method of assigning sample times combines the block-based and port-based methods. You first specify, in mdlInitializeSizes, the total number of rates at which your block operates, including both internal and input and output rates, using ssSetNumSampleTimes. You then set the SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED, using ssSetOptions, to tell the simulation engine that you are going to use the port-based method to specify the rates of the input and output ports individually. Next, as in the block-based method, you specify the periods and offsets of all of the block's rates, both internal and external, using

• ssSetSampleTime
  ssSetOffsetTime
  

Finally, as in the port-based method, you specify the rates for each port, using

• ssSetInputPortSampleTime(S, idx, period)
  ssSetInputPortOffsetTime(S, idx, offset)
  ssSetOutputPortSampleTime(S, idx, period)
  ssSetOutputPortOffsetTime(S, idx, offset)
  

Note that each of the assigned port rates must be the same as one of the previously declared block rates.

Block-Based Sample Times

Multirate S-Function Blocks