Writing S-Functions

Block-Based Sample Times

The next two sections discuss how to specify block-based sample times. You must specify information in

• mdlInitializeSizes
• mdlInitializeSampleTimes

A third sections presents a simple example that shows how to specify sample times in mdlInitializeSampleTimes.

Specifying the Number of Sample Times in mdlInitializeSizes.   To configure your S-function block for block-based sample times, use

ssSetNumSampleTimes(S,numSampleTimes);

where numSampleTimes > 0. This tells Simulink that your S-function has block-based sample times. Simulink calls mdlInitializeSampleTimes, which in turn sets the sample times.

Setting Sample Times and Specifying Function Calls in mdlInitializeSampleTimes

mdlInitializeSampleTimes is used to specify two pieces of execution information:

• Sample and offset times -- In mdlInitializeSizes, specify the number of sample times you'd like your S-function to have by using the ssSetNumSampleTimes macro. In mdlInitializeSampleTimes, you must specify the sampling period and offset for each sample time.

Sample times can be a function of the input/output port widths. In mdlInitializeSampleTimes, you can specify that sample times are a function of ssGetInputPortWidth and ssGetGetOutputPortWidth.

• Function calls -- In ssSetCallSystemOutput, specify which output elements are performing function calls. See matlabroot/simulink/src/sfun_fcncall.c for an example.

The sample times are specified as pairs [sample_time, offset_time] by using these macros

ssSetSampleTime(S, sampleTimePairIndex, sample_time)
ssSetOffsetTime(S, offsetTimePairIndex, offset_time)

where sampleTimePairIndex starts at 0.

The valid sample time pairs are (upper-case values are macros defined in simstruc.h).

[CONTINUOUS_SAMPLE_TIME,  0.0                       ]
[CONTINUOUS_SAMPLE_TIME,  FIXED_IN_MINOR_STEP_OFFSET]
[discrete_sample_period,  offset                    ]
[VARIABLE_SAMPLE_TIME  ,  0.0                       ]

Alternatively, you can specify that the sample time is inherited from the driving block in which case the S-function can have only one sample time pair

[INHERITED_SAMPLE_TIME,  0.0                       ]

or

[INHERITED_SAMPLE_TIME,  FIXED_IN_MINOR_STEP_OFFSET]

The following guidelines may help aid in specifying sample times:

• A continuous function that changes during minor integration steps should register the [CONTINUOUS_SAMPLE_TIME, 0.0] sample time.
• A continuous function that does not change during minor integration steps should register the
  [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.
• A discrete function that changes at a specified rate should register the discrete sample time pair

[discrete_sample_period, offset]

where

discrete_sample_period > 0.0

and

0.0 <= offset < discrete_sample_period

• A discrete function that changes at a variable rate should register the variable step discrete [VARIABLE_SAMPLE_TIME, 0.0] sample time. The mdlGetTimeOfNextVarHit function is called to get the time of the next sample hit for the variable step discrete task. The VARIABLE_SAMPLE_TIME can be used with variable step solvers only.

If your function has no intrinsic sample time, then you must indicate that it is inherited according to the following guidelines:

• A function that changes as its input changes, even during minor integration steps, should register the [INHERITED_SAMPLE_TIME, 0.0] sample time.
• A function that changes as its input changes, but doesn't change during minor integration steps (that is, held during minor steps), should register the [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.

To check for a sample hit during execution (in mdlOutputs or mdlUpdate), use the ssIsSampleHit or ssIsContinuousTask macro. For example, if your first sample time is continuous, then you used the following code fragment to check for a sample hit. Note that you would get incorrect results if you used ssIsSampleHit(S,0,tid).

if (ssIsContinuousTask(S,tid)) {
}

If, for example, you wanted to determine if the third (discrete) task has a hit, then you would use the following code-fragment.

if (ssIsSampleHit(S,2,tid) {
}

Example: mdlInitializeSampleTimes

This example specifies that there are two discrete sample times with periods of 0.01 and 0.5 seconds.

static void mdlInitializeSampleTimes(SimStruct *S)
{
  ssSetSampleTime(S, 0, 0.01);
  ssSetOffsetTime(S, 0, 0.0);
  ssSetSampleTime(S, 1, 0.5);
  ssSetOffsetTime(S, 1, 0.0);
} /* End of mdlInitializeSampleTimes. */

Sample Times

Port-Based Sample Times