Reuse Simulink Functions in Stateflow Charts

A Simulink^® function is a graphical object that enables you to call a Simulink subsystem in the actions of states and transitions. Simulink functions are not supported in standalone Stateflow^® charts in MATLAB^®.

Simulink functions can improve the efficiency of your design and increase the readability of your model. Typical applications include:

• Defining a function that requires Simulink blocks

• Scheduling execution of multiple controllers

Simulink functions in a Stateflow chart provide these advantages:

• No function-call subsystem blocks

• No output events

• No signal lines

A Simulink function can reside anywhere in a chart, state, or subchart. The location of a function determines what states and transitions are able to call the function.

• If you want to call the function within only one state or subchart and its substates, put your Simulink function in that state or subchart. That function overrides any other functions of the same name in the parents of that state or subchart.

• If you want to call the function from anywhere in a chart, put your Simulink function at the chart level.

• If you want to call the function from any chart in your model, use a Simulink Function (Simulink) block to define the function directly in the Simulink canvas. For more information, see Simulink Functions Overview (Simulink).

To access Stateflow data from your Simulink function, you must include that data as an input to your Simulink function.

This Simulink function has the name sim_fcn. It takes three arguments (a, b, and c) and returns two output values (x and y).

The function contains a Simulink subsystem that multiplies the first argument times a gain of 25 and combines the other two arguments into a complex output signal.

Once you have your Simulink function defined, you can place it anywhere in your Stateflow chart or Simulink model. Additionally, you can reuse this function as many times as needed within the same or different models.

Note

You are unable to call global Simulink Functions from a Stateflow chart within a Model Reference. To resolve this issue, create a new Simulink Function in your Stateflow chart. Inside this Simulink Function, include a Function Caller block that calls the original global Simulink Function. For more information on the Function Caller block, see Function Caller (Simulink).

Define a Simulink Function

1. In the object palette, click the Simulink function icon .

2. On the chart canvas, click the location for the new Simulink function.

3. Enter the signature label for the function.

   The signature label of the function specifies a name for your function and the formal names for its arguments and return values. A signature label has this syntax:

   [return_val1,return_val2,...] = function_name(arg1,arg2,...)

   You can specify multiple return values and multiple input arguments. Each return value and input argument can be a scalar, vector, or matrix of values. For functions with only one return value, omit the brackets in the signature label.

   You must use unique variable names for all arguments and return values.

4. To program the function, open the Simulink Editor by double-clicking the function box. Initially, the editor contains a function-call Trigger (Simulink) block and Inport (Simulink) and Outport (Simulink) blocks that match the function signature. You cannot delete the Trigger block.

5. In the Simulink Editor, add blocks to create your Simulink subsystem and connect them to the Inport and Outport blocks.

6. Configure the Inport and Outport blocks.

   1. Double-click each block to open the Block Parameters dialog box.

   2. In the Signal Attributes tab, enter the Data type and Port dimensions of the input parameter or return value.

   3. Click OK.

   Note

   An Inport block in a Simulink function cannot inherit its Data type and Port dimensions. For more information, see Guidelines for Using Simulink Functions.

Call Simulink Functions in States and Transitions

You can call Simulink functions from the actions of any state or transition or from other functions.

To call a Simulink function, use the function signature and include an argument value for each formal argument in the function signature.

[return_val1,return_val2,...] = function_name(arg1,arg2,...)

If the data types of the two arguments differ, the function casts the argument to the type of the formal argument.

Specify Properties of Simulink Functions

You can modify properties for a Simulink function in the Block Parameters dialog box.

1. In the Stateflow Editor, right-click the Simulink function.

2. Select Properties.

3. Edit the Simulink function properties.

You can also modify these properties in the Model Explorer. For more information, see Model Explorer (Simulink).

For a description of the Simulink function properties, see Subsystem (Simulink).

You can specify additional properties of Simulink functions programmatically by using Stateflow.SLFunction objects. For more information about the Stateflow programmatic interface, see Overview of the Stateflow API.

Use a Simulink Function to Access Simulink Blocks

In this example, you can compare modeling the shift logic of a car system. The first model does not use Simulink functions while the second does.

Model Without a Simulink Function

This model uses a function-call subsystem, run(), Simulink model to calculate the threshold for shifting gears. The Stateflow chart then uses an output event, CALC_TH(), to call the subsystem.

For more information about function-call subsystems, see Using Function-Call Subsystems (Simulink).

Model With a Simulink Function

This same functionality can be achieved with a Simulink function. In this Stateflow chart, the Simulink function calc_th is used to calculate the threshold.

The during action in selection_state contains a function call to calc_th, which contains Simulink blocks.

This modeling method minimizes the objects in your model.

Use a Simulink Function to Schedule Execution of Multiple Controllers

In this example, you can compare two ways of scheduling execution of multiple controllers. The first model does not use Simulink functions while the second does.

Model Without Simulink Functions

This model uses function-call subsystems to model each controller. The model includes output events in a Stateflow chart to schedule execution of the subsystems.

For each output event, a signal line is needed to connect the Stateflow chart with the corresponding function-call subsystem.

Model Method With Simulink Functions

Each controller can also be modeled with a Simulink function in a Stateflow chart. This model uses function calls to schedule execution of the subsystems.

This modeling method minimizes the objects in your model.

Guidelines for Using Simulink Functions

 Use Alphanumeric Characters and Underscores in Argument Names

By using alphanumeric characters for argument names, you ensure that the names of Inport and Output blocks are compatible with the identifier naming rules of Stateflow charts.

 Explicitly Set the Properties of Inport Blocks

The Inport blocks in a Simulink function cannot inherit their data types and sizes. You must set the Data type and Port dimensions of each Inport block that is not a scalar of type double.

The Outport blocks in a Simulink function can inherit sizes and data types based on the connections inside the subsystem. You can specify the Data type and Port dimensions of these blocks as inherited.

Tip

To make it easier to update the properties of Inport blocks, you can specify data types and sizes as parameters.

 Convert Discontiguous Signals to Contiguous Signals

Outport blocks in Simulink functions do not support discontiguous signals. If your function contains a block that outputs a discontiguous signal, insert a Signal Conversion (Simulink) block between the discontiguous output and the Outport block. This ensures that the output signal is contiguous.

Blocks that can output a discontiguous signal include the Bus Creator (Simulink) block and the Mux (Simulink) block. For the Bus Creator block, the output is discontiguous when the block outputs a virtual bus. If you select Output as nonvirtual bus, the output signal is contiguous and no conversion is necessary. For more information, see Create Nonvirtual Buses (Simulink).

 Do Not Use Simulink Functions in Moore Charts

You cannot use Simulink functions in Moore charts. This restriction prevents violations of Moore semantics during chart execution.

 Do Not Call Simulink Functions in Default Transitions That Execute During Chart Initialization

If you select the chart property Execute (enter) Chart At Initialization, you cannot call Simulink functions in default transitions that execute the first time that the chart awakens. Otherwise, the chart generates a run-time error during simulation.

 Do Not Call Simulink Functions in State During Actions Or Transition Conditions of Continuous-time Charts

In continuous-time charts, you cannot call Simulink functions during minor time steps. Instead, call Simulink functions in actions that occur during major time steps: state entry or exit actions and transition actions. Calling Simulink functions in state during actions or transition conditions results in a run-time error during simulation.

 Do Not Generate HDL Code for Simulink Functions

Simulink functions do not support HDL code generation. Generating HDL code for charts that contain Simulink functions results in a run-time error during simulation.

 Pass Arguments by Value

Passing an argument to a Simulink function by reference results in a run-time error during simulation.