Implementing Block Features (Writing S-Functions)

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 section 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 ssGetOutputPortWidth.

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

You specify the sample times as pairs [sample_time, offset_time], using these macros

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

where sampleTimePairIndex starts at 0.

The valid sample time pairs are (uppercase 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                       ]

[INHERITED_SAMPLE_TIME,  FIXED_IN_MINOR_STEP_OFFSET]

The following guidelines might help 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, 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, 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 get incorrect results if you use ssIsSampleHit(S,0,tid).

```
if (ssIsContinuousTask(S,tid)) {
}
```

If, for example, you wanted to determine whether the third (discrete) task has a hit, 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 Specifying Port-Based Sample Times