Learn more about Real-Time Workshop Embedded Coder

Partitioning Functions in the Generated Code

On this page…

Introduction About Atomic and Virtual Subsystems Viewing Changes in the Model Architecture Controlling Function Location and File Placement in Generated Code Understanding Reentrant Code Using a Mask to Pass Parameters into a Library Subsystem Generating Code from an Atomic Subsystem Generating Code: Full Model vs. Exported Functions Effect of Execution Order on Simulation Results Topics for Further Study

Introduction

This tutorial shows how to associate subsystems in the model with specific function names and files. You examine:

• How to specify function and file names in generated code

• Parts of generated code that you must have for integration

• How to generate code for atomic subsystems

• Data that you must have to execute a generated function

Back to Top

About Atomic and Virtual Subsystems

The models in Understanding the Demo Model and Configuring the Data Interface use virtual subsystems. Virtual subsystems visually organize blocks but have no effect on the behavior of the model. Atomic subsystems evaluate all included blocks as a unit. In addition, atomic subsystems allow you to specify additional function partitioning information. Atomic subsystems display graphically with a bold border.

Back to Top

Viewing Changes in the Model Architecture

This section shows you how to replace the virtual subsystems in the model with function-call subsystems. Function-call subsystems:

• Are always atomic subsystems

• Allow the direct control of subsystem execution order

• Are associated with a function-call signal

• Are executed when the function-call signal is triggered

You might have to exert direct control over execution order if you intend the model to match an existing system with a specific execution order.

The following figure of the rtwdemo_PCG_Eval_P3 model identifies function-call subsystems as PI_ctrl_1, PI_ctrl_2, and Pos_Command_Arbitration.

The Execution_Order_Control subsystem has been added to the model. It is a Stateflow chart that models the calling functionality of a scheduler. It controls the execution order of the function-call subsystems. Later, this tutorial examines how changing execution order can change the simulation results.

Four signal conversion blocks were added to the outports for the PI controllers to make the functions reentrant.

Back to Top

Controlling Function Location and File Placement in Generated Code

In Understanding the Demo Model and Configuring the Data Interface, Real-Time Workshop software generates a single model_step function that contains all the control algorithm code. However, many applications require a greater level of control over the location of functions in the generated code. By using atomic subsystems, you can specify multiple functions within a single model. You specify this information by modifying subsystem parameters, shown in the following figure.

Parameter	What the Parameter Does
Treat as atomic unit	Enables other submenus. This parameter is automatically selected and grayed out for atomic subsystems.
Sample time	Specifies a sample time. Not present for function-call subsystems.
Real-Time Workshop system code	Depends on setting, as follows.
	Auto:Real-Time Workshop software determines how the subsystem appears in the generated code. This is the default.
	Inline:Real-Time Workshop software places the subsystem code inline with the rest of the model code.
	Function:Real-Time Workshop software generates the code for the subsystem as a function.
	Reusable function:Real-Time Workshop software generates a reusable function from the subsystem. Passes all input and output into the function by argument or by reference. Does not pass global variables into the function.
Real-Time Workshop function name options	If you select Function or Reusable function, function name options are enabled as follows.
	Auto:Real-Time Workshop software determines the function.
	Use subsystem name: Base the function name on the subsystem name.
	User Specified: You specify a unique file name.
Real-Time Workshop file name options	If you select Function or Reusable function, file name options are enabled as follows.
	Auto:Real-Time Workshop software generates the function code within the generated code from the parent system or, if the parent of the subsystem is the model itself, within the model.c file.
	Use subsystem name:Real-Time Workshop software generates a separate file and names it with the name of the subsystem or library block.
	Use function name:Real-Time Workshop software generates a separate file and names it with the function name specified for Real-Time Workshop function name options.
	User Specified: You specify a unique file name.
Function with separate data	Enabled when you set Real-Time Workshop system code to Function. If selected, Real-Time Workshop Embedded Coder software generates subsystem function code in which the internal data for an atomic subsystem is separated from its parent model and is owned by the subsystem.

Back to Top

Understanding Reentrant Code

Real-Time Workshop Embedded Coder software supports reentrant code. Reentrant code is a reusable programming routine that multiple programs can use simultaneously. Operating systems and other system software that uses multithreading to handle concurrent events use reentrant code. Reentrant code does not maintain state data: no persistent variables are in the function. Calling programs maintain their state variables and pass them into the function. Any number of users or processes can share one copy of a reentrant routine.

To generate reentrant code, you must first specify the subsystem as a candidate for reuse by specifying the subsystem parameters in the Function Block Parameters dialog box.

In some cases, the configuration of the model prevents Real-Time Workshop software from generating reusable code. Common issues that prevent the generation of reentrant code and corresponding solutions follow.

Cause	Solution
Use of global data on the outport of the subsystem	Add a Signal Conversion block between the subsystem and the signal definition.
Passing data into the system as pointers	In Model Explorer, select the Configuration > Model Referencing > Pass fixed-size scalar root inputs by value check box.
Use of global data inside the subsystem	Use a port to pass the global data in and out of the subsystem.

Back to Top

Using a Mask to Pass Parameters into a Library Subsystem

Subsystem masks enable Simulink software to define subsystem parameters outside the scope of a library block. By changing the parameter value at the top of the library, the same library is usable with multiple sets of parameters within the same model.

When a subsystem is reusable and masked, Real-Time Workshop software passes the masked parameters into the reentrant code as arguments. Real-Time Workshop software fully supports the use of data objects in masks. The data objects are used in the generated code.

In the rtwdemo_PCG_Eval_P3 model, the PI_ctrl_1 and PI_ctrl_2 subsystems are masked. The value of the P and I gains are set in the subsystem Mask Parameters dialog box, shown in the following figure. Simulink creates two new data objects: P_Gain_2 and I_Gain_2.

Back to Top

Generating Code from an Atomic Subsystem

In Understanding the Demo Model and Configuring the Data Interface, the Real-Time Workshop software generates code at the model root level. In addition to building at the system level, it is possible to build at the subsystem level

You start a subsystem build from the right-click context menu. Three different options are available for a subsystem build.

Build Option	What the Option Does
Build Subsystem	Treats the subsystem as a separate model. The full set of source C files and header files are created for the subsystem. Does not support function-call subsystems.
Generate S-Function	Generates C code for the subsystem and creates an S-function wrapper. You can then simulate the code in the original Simulink model. Does not support function-call subsystems.
Export Functions	Generates C code without the scheduling code associated with the Build Subsystem option. Export functions is required when building subsystems that use triggers.

Back to Top

Generating Code: Full Model vs. Exported Functions

In this section, you compare the files generated for the full model build with files generated for exported functions. This module also examines how the masked data appears in the code.

1. Open rtwdemo_PCG_Eval_P3.

2. Generate code for the model.

   The code generator creates code for the rtwdemo_PCG_Eval_P3 model.

3. Export a function for the PI_ctrl_1 subsystem:

   1. In the Model Editor, right-click PI_ctrl_1 and select Real-Time Workshop > Export Functions.

      The Build code for Subsystem: PI_ctrl_1 dialog box opens.

   2. Click the Build button.

      Code is generated for PI_ctrl_1.

4. If you have a Stateflow license, export a function for the Pos_Command_Arbitration chart:

   1. In the Model Editor, right-click Pos_Command_Arbitration and select Real-Time Workshop > Export Functions.

      The Build code for Subsystem: Pos_Command_Arbitration dialog box opens.

   2. Click the Build button.

      Code is generated for Pos_Command_Arbitration.

5. Examine the generated code listed in the table by locating and opening the files in the respective generated code subdirectories.

   File	Full Build	PI_ctrl_1	Pos_Command_Arbitration (requires Stateflow license)
   rtwdemo_PCG_Eval_P3.c	Yes Step function	No	No
   PI_ctrl_1.c	No	Yes Trigger function	No
   Pos_Command_Arbitration.c (requires Stateflow license)	No	No	Yes Init and Function
   PI_Ctrl_Reusable.c	Yes Called by main	Yes Called by PI_ctrl_1	No
   ert_main.c	Yes	Yes	Yes
   eval_data.c	Yes*	Yes*	No Eval data not used in diagram

   * The content of eval_data.c differs between the full model and export function builds. The full model build includes all parameters that the model uses while the export function contains only variables that the subsystem uses.

Masked Data in the Generated Code

The code in rtwdemo_PCG_Eval_P3.c illustrates how data objects from the mask (P_Gain and I_Gain) and P_Gain_2 and I_Gain_2 pass into the reentrant code.

PI_Cntrl_Reusable((*pos_rqst), fbk_1, &rtwdemo_PCG_Eval_P3_B->PI_ctrl_1,
                  &rtwdemo_PCG_Eval_P3_DWork->PI_ctrl_1, I_Gain, P_Gain);
PI_Cntrl_Reusable((*pos_rqst), fbk_2, &rtwdemo_PCG_Eval_P3_B->PI_ctrl_2,
                  &rtwdemo_PCG_Eval_P3_DWork->PI_ctrl_2, I_Gain_2, P_Gain_2);

Back to Top

Effect of Execution Order on Simulation Results

Without explicit control, Simulink software sets the execution order of the subsystems as:

1. PI_ctrl_1

2. PI_ctrl_2

3. Pos_Cmd_Arbitration

You use the test harness to see the effect of the execution order on the simulation results. The Execution_Order_Control subsystem is a configurable subsystem with two configurations that change the execution order of the subsystems.

Note   The following procedure requires a Stateflow license.

Change the execution order as follows:

1. In the rtwdemo_PCG_Eval_P3 model, set the execution order to PI_ctrl_1, PI_ctrl_2, Pos_cmd_Arbitration:

   1. Right-click the Execution_Order_Control subsystem.

   2. On the Block Choice menu, select PI_1_then_PI_2_then_Pos_Cmd_Arb.

2. Save rtwdemo_PCG_Eval_P3.

3. Open the test harness, rtwdemo_PCGEvalHarness.

4. Right-click the Unit_Under_Test Model block and select ModelReference Parameters.

5. Set Model name (without the .mdl extension) to: rtwdemo_PCG_Eval_P3.

6. Click OK.

7. Run the test harness.

8. In rtwdemo_PCG_Eval_P3, change the execution order to Pos_cmd_Arbitration_then_PI_1_then_PI_2.

9. Run the test harness again.

   A slight variation exists in the output results depending on the order of execution. The difference is most noticeable when the desired input changes.

   

10. Close the rtwdemo_PCG_Eval_P3 model.

Back to Top

Topics for Further Study

• Architecture Considerations in the Real-Time Workshop documentation

• Integrating External Code With Generated C and C++ Code in the Real-Time Workshop documentation

• Exporting Function-Call Subsystems in the Real-Time Workshop Embedded Coder documentation

• Controlling Generation of Function Prototypes in the Real-Time Workshop Embedded Coder documentation

• Working with Block Masks in the Simulink documentation

Back to Top

Configuring the Data Interface

Calling External C Functions from the Model and Generated Code

© 1984-2010- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS