Export-Function Models Overview - MATLAB & Simulink (original) (raw)

Export-function models are Simulink® models that generate code for independent functions that can be integrated with an external environment and scheduler. Functions are defined using Function-Call Subsystem, function-call Model, Simulink Function,Message Triggered Subsystem, and S-Function blocks.

The following export-function model contains two functions defined withFunction-Call Subsystem blocks. For a step-by-step procedure to create this model, see Create Export-Function Model.

Code generated from this model has two independent functions, one for a delay function and the other for a square function.

  /*
   * File: export_function_model.c    
   * Code generated for Simulink model 'export_function_model'.
   */
    
void function_call_100ms(void)         /* Sample time: [0.1s, 0.0s] */
{
  export_function_model_Y.output_100ms =
    export_function_model_DW.UnitDelay_DSTATE;

  export_function_model_DW.UnitDelay_DSTATE =
    export_function_model_Y.output_100ms + 1.0;	
}

  void function_call_10ms(void)          /* Sample time: [0.01s, 0.0s] */
{
    export_function_model_Y.output_10ms = export_function_model_U.input_10ms *
    export_function_model_U.input_10ms;
}

Workflows for Export-Function Models

Four common processes for creating export-function models differ in how you simulate and test your model before generating code for the functions.

When function-call sequencing is simple enough to be specified as a model input, simulation using an input matrix is the preferred method for testing an export-function model. For more information, see Test Export-Function Model Simulation Using Input Matrix.

When function-call sequencing is too complicated to specify with an input matrix, create a test model (harness) to mimic the target environment behavior. Use this test model to provide function-call inputs to the export-function model. For more information, see Test Export-Function Model Simulation Using Function-Call Generators, Test Export-Function Model Simulation Using Schedule Editor and Test Export-Function Model Simulation Using Stateflow Chart.

Blocks Allowed at Top Level of Export-Function Models

At the top-level, an export-function model is limited to virtual blocks, blocks with constant (inf) sample time, and the following blocks:

• Inport
• Outport
• Bus Creator
• Bus Selector
• In Bus Element
• Out Bus Element
• Function-Call Subsystem
• Model with function-call input ports
• Simulink Function
• Function Element
• Function Element Call
• Message Triggered Subsystem
• Initialize Function
• Reinitialize Function
• Reset Function
• Terminate Function
• Data Store Memory
• Merge
• Message Merge
• S-Function with function-call input port
• Function-Call Split
• Display
• Scope

For more information, see Nonvirtual and Virtual Blocks and Types of Sample Time.

Requirements for Export-Function Models

For an export-function model to successfully generate function code, the following requirements must be met.

Model Configuration Parameters:

• Solver Type set toFixed-step.
• Solver set to auto ordiscrete.
• Code Generation System target file set toert.tlc. Selecting ert.tlc requires an Embedded Coder® license.
• For function-call Model blocks, Periodic sample time constraint for the referenced model set to Ensure sample time independent.

Root-level function-call Inport blocks:

• Output function call check box selected.
• Cannot receive a signal from an Asynchronous Task Specification block.

Root-level Outport blocks must be connected to one of these blocks or left unconnected or grounded:

• Function-call block driven by root-level function-call Inport block. This block can be a Function-Call Subsystem block, a function-call Model block, or an S-Function block with function-call input.
• Simulink Function block.
• Initialize Function, Reinitialize Function,Reset Function, or Terminate Function block.
• Merge or Mux block driven exclusively by such blocks.

Root-level data Inport and Outport blocks cannot connect to virtual bus data signals.

Root-level Function-Call Subsystem blocks and function-callModel blocks:

• All internal blocks within the block must support code generation.
• If the Trigger block Sample time type is set to:
  • triggered, internal blocks must have Sample time set to -1.
  • periodic, the root-level function-callInport block must have its Sample time set to a specified discrete time and all internal blocks must have Sample time set to -1 or the specified discrete time.

Designating an Export-Function Model

When you create an export-function model, tell Simulink to treat your model as an export-function model by designating it as an export-function model.

To designate a model as an export-function model, open the Property Inspector. With the root level of the model displayed and with no blocks highlighted, go to the Execution tab and select the Set execution domain check box. Then, from the Domain list, select Export function.

You can also designate a model as an export-function model by setting theIsExportFunctionModel parameter of the model.

set_param(ModelName,'IsExportFunctionModel','on')

Simulink displays a badge in the lower-left corner of the canvas to indicate that a model is specified as an export-function model.

After you designate a model as an export-function model, Simulink performs compile-time checks to warn you if the model does not meet export-function model requirements.

If you load a model that was created and saved in a release prior to R2022a, Simulink designates the model as an export-function model if the model meets the requirements to be an export-function model. In some cases, you may need to manually designate such a model as an export-function model.

Sample Time for Function-Call Subsystems

In an export-function model, you can specify sample time for root-level function-callInport blocks and the Trigger block inside a root-levelFunction-Call Subsystem block or function-call Model block. The following table shows how to specify these sample times.

Execution Order for Root-Level Function-Call Inport Blocks

By specifying sample time and priority for function-call Inport blocks you can control the execution order of function-call subsystems and function-call models during simulation. Alternatively, you can use the Schedule Editor or a Stateflow® chart to test scheduling. For more information, see Test Export-Function Model Simulation Using Schedule Editor and Test Export-Function Model Simulation Using Stateflow Chart.

1. Specify sample time for simulation execution. Right-click a function-callInport block, then select Block parameters.
2. Select the Signal Attributes tab. In the Sample time box, enter a discrete time.
3. Specify the block priority for simulation. Right-click a function-callInport block, then select Properties.
4. In the Priority box, enter a priority value.
5. Display block execution order for simulation. On the Debug tab, select Information Overlays , then from the drop-down dialog, selectExecution Order. This display has no impact on the generated code.

In the following export-function model, Function-Call Subsystem 2 withSample time for Inport block 2 set to0.01 (10 ms) runs before Function-Call Subsystem 1 withSample time for Inport block 1 set to0.1 (100 ms).

Determine Relative Execution Order

Simulink compares function-call Inport block properties to determine their relative execution order using the following rules:

1. Priority – higher priority (smaller number) executes first
2. Sample time – smaller sample time executes first
3. Port number – smaller port number executes first
4. If the OrderFunctionsByDependency parameter for the model is set to 'on', blocks that have the same sample times are further sorted based on the relative data dependency of the functions to which the blocks are connected.

To see the effect of the OrderFunctionsByDependency parameter, consider the following model.

Inport block 1 executes last because it has a longer sample time thanInport blocks 2 and 3, which have the same sample time. IfOrderFunctionsByDependency is set to 'off',Inport block 2 executes before Inport block 3 based on their port numbers. The execution order is 2, 3, 1.

The OrderFunctionsByDependency parameter is set to'off' by default. To turn it on, use this command.

set_param(ModelName,'OrderFunctionsByDependency','on')

With the OrderFunctionsByDependency set to 'on',Inport block 3 executes before Inport block 2 because of the data dependency between function-call subsystems 2 and 3. The execution order is 3, 2, 1.

Note that the OrderFunctionsByDependency parameter affects only the model for which it is set. The parameter does not propagate into referenced models.

When two blocks have different values for the Priority parameter, the block with the higher priority executes first. If the Priority parameter is equal, the block with the faster rate (smaller sample time) executes first. If Priority and sample time are the same for both of the blocks, the block with the lower port number executes first. The exception is when a data dependency exists between the blocks and OrderFunctionsByDependency is set to'on', in which case the dependent block executes after the block on which it depends.

Note

When the simulation mode of the top model is accelerator or rapid accelerator, Simulink does not perform run-time simulation checks for the execution order of root-level function-call Inport blocks inside referenced export-function models.

Suppose that an export-function model has five root-level function-callInport blocks, A to E, with block properties as shown in the table. The blocks have no data dependencies, or OrderFunctionsByDependency is set to 'off'. To determine their relative execution order, Simulink compares their Priority parameters, sample times (if distinct and non-inherited), and port numbers.

• Block A has the highest priority of the five blocks. A executes first.
• B and E execute after A but before C and D. Since B and E have the same priority, Simulink compares their sample times to determine execution order. E has a sample time of -1 (inherited), which is smaller than0.2, the sample time of B. E executes before B.
• C and D have the same priority and the same distinct, non-inherited sample times. The port number for D (2) is smaller than C (3), so D executes before C.

The relative execution order for these function-call Inport blocks is A, E, B, D, C.

Nested Export-Function Models

Nested export-function models provide an additional layer of organization. The following model has two referenced export-function models that are referenced from aModel block.

Note

An export-function model cannot contain a referenced model with asynchronous function-call inputs, but can contain function-call subsystems and function-call models. A model with asynchronous function-call inputs can contain an export-function model, a function-call subsystem, or a function-call model.

Export-Function Model with a Multi-Instanced Function-Call Model

You can use Function-Call Subsystem blocks or function-callModel blocks within an export-function model. If you use a function-callModel block, you can also create multiple instances of the model.

1. Define your algorithm with a model that contains a Trigger block. SetTrigger type to function-call.
   
2. Reference the model from a Model block. The result is a function-call model.
   
3. Connect a function-call Inport block and select theOutput function call check box. Add signalInport and Outport blocks. Update the model (Ctrl+D). The result is an export-function model with a function-call model.
   
4. Copy the referenced model and port blocks to create a second instance of the model. The two instances are called by different root-level function-call Inport blocks in different tasks.
   

Export-Function Models and Models with Asynchronous Function-Call Inputs

Export-function model capability is available for models with asynchronous function-call input ports, also referred to as JMAAB-B models. You use these models primarily in the Simulink environment where the Simulink scheduler calls the functions.

See Also

Function-Call Subsystem | Trigger | Model | Simulink Function | Message Triggered Subsystem | S-Function

Topics

• Create Export-Function Model
• Test Export-Function Model Simulation Using Input Matrix
• Test Export-Function Model Simulation Using Function-Call Generators
• Test Export-Function Model Simulation Using Stateflow Chart
• Test Export-Function Model Simulation Using Schedule Editor
• Generate Code for Export-Function Model