Function-Call Subsystems :: Implementing Block Features (Simulink®)

Learn more about Simulink

Function-Call Subsystems

You can create a triggered subsystem whose execution is determined by logic internal to a C MEX S-function instead of by the value of a signal. A subsystem so configured is called a function-call subsystem. You cannot trigger a function-call subsystem from a Level- M-file S-function. To implement a function-call subsystem:

In the Trigger block, select function-call as the Trigger type parameter.
In the S-function, use the ssEnableSystemWithTid and ssDisableSystemWithTid to enable or disable the triggered subsystem and the ssCallSystemWithTid macro to call the triggered subsystem.
In the model, connect the S-Function block output directly to the trigger port.

Function-call subsystems are not executed directly by the Simulink engine; rather, the S-function determines when to execute the subsystem. When the subsystem completes execution, control returns to the S-function. This figure illustrates the interaction between a function-call subsystem and an S-function.

In this figure, ssCallSystemWithTid executes the function-call subsystem that is connected to the first output port element. ssCallSystemWithTid returns 0 if an error occurs while executing the function-call subsystem or if the output is unconnected. After the function-call subsystem executes, control is returned to your S-function.

Function-call subsystems can only be connected to S-functions that have been properly configured to accept them.

To configure an S-function to call a function-call subsystem:

Specify the elements that are to execute the function-call subsystem in mdlInitializeSampleTimes. For example:

ssSetCallSystemOutput(S,0);  /* call on first element */
ssSetCallSystemOutput(S,1);  /* call on second element */

Specify in mdlInitializeSampleTimes whether you want the S-function to be able to enable or disable the function-call subsystem. Only S-functions that explicitly enable and disable the function-call subsystem can reset the states and outputs of the subsystem, as determined by the function-call subsystem's Trigger and Outport blocks. For example, the code
```
ssSetExplicitFCSSCtrl(S, 1);
```
in mdlInitializeSampleTimes specifies that the S-function can enable and disable the function-call subsystem. In this case, the S-function must invoke ssEnableSystemWithTid before executing the subsystem using ssCallSystemWithTid.

Execute the subsystem in the appropriate mdlOutputs or mdlUpdate S-function routine. For example:

static void mdlOutputs(...)
{
    if (((int)*uPtrs[0]) % 2 == 1) {
      if (!ssCallSystemWithTid(S,0,tid)) {
        /* Error occurred, which will be reported by */
				/*the Simulink engine*/
        return;
      }
    } else {
      if (!ssCallSystemWithTid(S,1,tid)) {
        /* Error occurred, which will be reported by */
				/*the Simulink engine*/
        return;
      }
    }
    ...
}

Note Do not use ssSetOutputPortDataType or ssGetOutputPortDataType on an S-function output that emits function-call signals. The Simulink engine explicitly controls the data type of these output signals.

See sfun_fcncall.c for an example that executes a function-call subsystem on the first and second elements of the S-function's first output. The following Simulink model uses this S-function.

Each of the function-call subsystems is a simple feedback loop containing a Unit Delay block, as shown below.

When the Pulse Generator emits its upper value, the function-call subsystem connected to the first element of the S-function's first output port is triggered. Similarly, when the Pulse Generator emits its lower value, the function-call subsystem connected to the second element is triggered. The simulation output is shown on the following Scope.

Function-call subsystems are a powerful modeling construct. You can configure Stateflow^® blocks to execute function-call subsystems, thereby extending the capabilities of the blocks. For more information, see the Stateflow documentation.

Matrices in C S-Functions

Sim Viewing Devices in External Mode

Related Products & Applications

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit