Learn more about Real-Time Workshop

Creating Subsystems

On this page…
Introduction Generating Code and Executables from Subsystems Nonvirtual Subsystem Code Generation Options Modularity of Subsystem Code

Introduction

The Real-Time Workshop product allows you to control how code is generated for any nonvirtual subsystem. The categories of nonvirtual subsystems are:

• Conditionally executed subsystems: execution depends upon a control signal or control block. These include triggered subsystems, enabled subsystems, action and iterator subsystems, subsystems that are both triggered and enabled, and function call subsystems. See Creating Conditional Subsystems in the Simulink documentation for more information.

• Atomic subsystems: Any virtual subsystem can be declared atomic (and therefore nonvirtual) by using the Treat as atomic unit option in the Block Parameters dialog box.

Note   You should declare virtual subsystems as atomic subsystems to ensure consistent simulation and execution behavior for your model. If you generate code for a virtual subsystem, the Real-Time Workshop software treats the subsystem as atomic and generates the code accordingly. The resulting code can change the execution behavior of your model, for example, by applying algebraic loops, and introduce inconsistencies with the simulation behavior.

See Systems and Subsystems in the Simulink documentation, and run the sl_subsys_semantics demo for more information on nonvirtual subsystems and atomic subsystems.

You can control the code generated from nonvirtual subsystems as follows:

• You can instruct the Real-Time Workshop code generator to generate separate functions, within separate code files if desired, for selected nonvirtual systems. You can control both the names of the functions and of the code files generated from nonvirtual subsystems.

• You can cause multiple instances of a subsystem to generate reusable code, that is, as a single reentrant function, instead of replicating the code for each instance of a subsystem or each time it is called.

• You can generate inlined code from selected nonvirtual subsystems within your model. When you inline a nonvirtual subsystem, a separate function call is not generated for the subsystem.

Back to Top

Generating Code and Executables from Subsystems

The Real-Time Workshop software can generate code and build an executable from any subsystem within a model. The code generation and build process uses the code generation and build parameters of the root model.

To generate code and build an executable from a subsystem,

1. Set up the desired code generation and build parameters in the Configuration Parameters dialog box, just as you would for code generation from a model.

2. Select the desired subsystem block.

3. Right-click the subsystem block and select Build Subsystem from the Real-Time Workshop submenu of the subsystem block's context menu.

   Alternatively, you can select Build Subsystem from the Real-Time Workshop submenu of the Tools menu. This menu item is enabled when a subsystem is selected in the current model.

   Note   If the model is operating in external mode when you select Build Subsystem, the Real-Time Workshop build process automatically turns off external mode for the duration of the build, then restores external mode upon its completion.

4. The Build Subsystem window opens. This window displays a list of the subsystem parameters. The upper pane displays the name, class, and storage class of each variable (or data object) that is referenced as a block parameter in the subsystem. When you select a parameter in the upper pane, the lower pane shows all the blocks that reference the parameter and the parent system of each such block.

   The StorageClass column contains a popup menu for each row. The menu lets you set the storage class of any parameter or inline the parameter. To inline a parameter, select the Inline option from the menu. To declare a parameter to be tunable, set the storage class to any value other than Inline.

   

   In the previous figure, the parameter K2 is inlined, while the other parameters are tunable and have various storage classes.

   See Parameter Considerations and Simulink Data Object Considerations for more information on tunable and inlined parameters and storage classes.

5. After selecting tunable parameters, click the Build button. This initiates the code generation and build process.

6. The build process displays status messages in the MATLAB Command Window. When the build completes, the generated executable is in your working directory. The name of the generated executable is subsystem.exe (on PC platforms) or subsystem (on The Open Group UNIX^® platforms), where subsystem is the name of the source subsystem block.

   The generated code is in a build subdirectory, named subsystem_target_rtw, where subsystem is the name of the source subsystem block and target is the name of the target configuration.

When you generate code for a subsystem, you can generate an S-function by selecting Tools > Real-Time Workshop > Generate S-function, or you can use a right-click subsystem build. See Automated S-Function Generation and Generating S-Function Wrappers for more details.

Real-Time Workshop Subsystem Build Limitations

The following limitations apply to building subsystems using the Real-Time Workshop software:

• When you right-click build a subsystem that includes an Outport block for which the signal specification Specify properties via bus object is selected, the Real-Time Workshop build process requires that you set the Signal label mismatch option on the Diagnostics > Connectivity pane of the Configuration Parameters dialog box for the parent model to error. You need to address any errors that occur by properly setting signal labels.

• When a subsystem is in a triggered or function-call subsystem, the right-click build process might fail if the subsystem code is not sample-time independent. To find out whether a subsystem is sample-time independent:

  1. Copy all blocks in the subsystem to an empty model.

  2. In the Configuration Parameters > Solver pane, set:

     1. Type to Fixed-step.

     2. Periodic sample time constraint to Ensure sample time independent.

     3. Click Apply.

  3. Update the model. If the model is sample-time dependent, Simulink generates an error in the process of updating the diagram.

Back to Top

Nonvirtual Subsystem Code Generation Options

For any nonvirtual subsystem, you can choose the following code generation options from the Real-Time Workshop system code menu in the subsystem Block parameters dialog box:

• Auto: This is the default option, and provides the greatest flexibility in most situations. See Auto Option below.

• Inline: This option explicitly directs the Real-Time Workshop code generator to inline the subsystem unconditionally.

• Function: This option explicitly directs the Real-Time Workshop code generator to generate a separate function with no arguments, and (optionally), place the subsystem in a separate file. You can name the generated function and file. As functions created with this option rely on global data, they are not reentrant.

• Reusable function: Generates a function with arguments that allows the subsystem's code to be shared by other instances of it in the model. To enable sharing, the Real-Time Workshop software must be able to determine (by using checksums) that subsystems are identical. The generated function will have arguments for block inputs and outputs (rtB_*), continuous states (rtDW_*), parameters (rtP_*), and so on.

  Note   You should not directly call reusable functions generated by the Real-Time Workshop product. The call interface is subject to change.

The following sections discuss these options further.

Auto Option

The Auto option is the default, and is generally appropriate. Auto causes the Real-Time Workshop code generator to inline the subsystem when there is only one instance of it in the model. When multiple instances of a subsystem exist, the Auto option results in a single copy of the function whenever possible (as a reusable function). Otherwise, the result is as though you selected Inline (except for function call subsystems with multiple callers, which is handled as if you specified Function). Choose Inline to always inline subsystem code, or Function when you specifically want to generate a separate function without arguments for each instance, optionally in a separate file.

Note   When you want multiple instances of a subsystem to be represented as one reusable function, you can designate each one of them as Auto or as Reusable function. It is best to use one or the other, as using both creates two reusable functions, one for each designation. The outcomes of these choices differ only when reuse is not possible.

To use the Auto option,

1. Select the subsystem block. Then select Subsystem Parameters from the Simulink model editor Edit menu. The Block Parameters dialog box opens, as shown in the next figure.

   Alternatively, you can open the Block Parameters dialog box by

   • Shift-double-clicking the subsystem block

   • Right-clicking the subsystem block and selecting Block parameters from the menu

2. If the subsystem is virtual, select Treat as atomic unit as shown in the next figure. This makes the subsystem nonvirtual, and the Real-Time Workshop system code option becomes enabled.

   If the system is already nonvirtual, the Real-Time Workshop system code option is already enabled.

3. Select Auto from the Real-Time Workshop system code menu as shown in the figure below.

   

4. Click Apply and close the dialog box.

   The border of the subsystem thickens, indicating that it is nonvirtual.

Auto Optimization for Special Cases.   Rather than reverting to Inline, the Auto option can optimize code in special situations in which identical subsystems contain other identical subsystems, by both reusing and inlining generated code. Suppose a model, such as the one shown in Reuse of Identical Nested Subsystems with the Auto Option, contains identical subsystems A1 and A2. A1 contains subsystem B1, and A2 contains subsystem B2, which are themselves identical. In such cases, the Auto option causes one function to be generated which is called for both A1 and A2, and this function contains one piece of inlined code to execute B1 and B2, ensuring that the resulting code will run as efficiently as possible.

Reuse of Identical Nested Subsystems with the Auto Option

Inline Option

As noted above, you can choose to inline subsystem code when the subsystem is nonvirtual (virtual subsystems are always inlined).

Exceptions to Inlining.   There are certain cases in which the Real-Time Workshop code generator does not inline a nonvirtual subsystem, even though the Inline option is selected. These cases are

• If the subsystem is a function-call subsystem that is called by a noninlined S-function, the Inline option is ignored. Noninlined S-functions make such calls by using function pointers; therefore the function-call subsystem must generate a function with all arguments present.

• In a feedback loop involving function-call subsystems, the Real-Time Workshop code generator forces one of the subsystems to be generated as a function instead of inlining it. The product selects the subsystem to be generated as a function based on the order in which the subsystems are sorted internally.

• If a subsystem is called from an S-Function block that sets the option SS_OPTION_FORCE_NONINLINED_FCNCALL to TRUE, it is not inlined. This might be the case when user-defined Asynchronous Interrupt blocks or Task Synchronization blocks are required. Such blocks must be generated as functions. The Asynchronous Interrupt and Task Synchronization blocks, located in the VxWorks^® block library shipped with the Real-Time Workshop product, use the SS_OPTION_FORCE_NONINLINED_FCNCALL option.^[1]

To generate inlined subsystem code,

1. Select the subsystem block. Then select Subsystem Parameters from the Simulink model editor Edit menu. The Block Parameters dialog box opens.

   Alternatively, you can open the Block Parameters dialog box by

   • Shift-double-clicking the subsystem block

   • Right-clicking the subsystem block and selecting Block parameters from the menu

2. If the subsystem is virtual, select Treat as atomic unit as shown in the next figure. This makes the subsystem atomic, and the Real-Time Workshop system code menu becomes enabled.

   If the system is already nonvirtual, the Real-Time Workshop system code menu is already enabled.

3. Select Inline from the Real-Time Workshop system code menu as shown in the figure below.

   

4. Click Apply and close the dialog box.

When you generate code from your model, the Real-Time Workshop code generator writes inline code within model.c or model.cpp (or in its parent system's source file) to perform subsystem computations. You can identify this code by system/block identification tags, such as the following.

/* Atomic SubSystem Block: <Root>/AtomicSubsys1 */

See Tracing Generated Code for more information on system/block identification tags.

Function Option

Choosing the Function or Reusable function option lets you direct the Real-Time Workshop code generator to generate a separate function and optionally a separate file for the subsystem. When you select the Function option, two additional options are enabled:

• The Real-Time Workshop function name options menu lets you control the naming of the generated function.

• The Real-Time Workshop file name options menu lets you control the naming of the generated file (if a separate file is generated and you select the User specified option).

The figure below shows the Block Parameters dialog box with the Function option selected, with Real-Time Workshop file name options set to User specified, and with a name specified for the generated file.

Subsystem Function Code Generation Option with User-Specified File Name

Real-Time Workshop Function Name Options Menu.   This menu offers the following choices, but the resulting identifiers are also affected by which General code appearance options are in effect for the model:

• Auto: By default, the Real-Time Workshop code generator assigns a unique function name using the default naming convention: model_subsystem(), where subsystem is the name of the subsystem (or that of an identical one when code is being reused).

• Use subsystem name: the Real-Time Workshop code generator uses the subsystem name as the function name.

  Note   When a subsystem is a library block, the Use subsystem name option causes its function identifier (and file name, see below) to be that of the library block, regardless of the names used for that subsystem in the model.

• User specified: When this option is selected, the Real-Time Workshop function name field is enabled. Enter any legal C or C++ function name (which must be unique).

Real-Time Workshop File Name Options Menu.   This menu offers the following choices:

• Use subsystem name: the Real-Time Workshop software generates a separate file, using the subsystem (or library block) name as the file name.

  Note   When a subsystem's Real-Time Workshop file name options is set to Use subsystem name, the subsystem file name is mangled if the model contains Model blocks, or if a model reference target is being generated for the model. In these situations, the file name for the subsystem consists of the subsystem name prefixed by the model name.

• Use function name: the Real-Time Workshop software generates a separate file, using the function name (as specified by the Real-Time Workshop function name options) as the file name.

• User specified: When this option is selected, the Real-Time Workshop file name (no extension) text entry field is enabled. The Real-Time Workshop software generates a separate file, using the name you enter as the file name. Enter any file name, but do not include the .c or .cpp (or any other) extension. This file name need not be unique.

  Note   While a subsystem source file name need not be unique, you must avoid giving nonunique names that result in cyclic dependencies (for example, sys_a.h includes sys_b.h, sys_b.h includes sys_c.h, and sys_c.h includes sys_a.h).

• Auto: The Real-Time Workshop software does not generate a separate file for the subsystem. Code generated from the subsystem is generated within the code module generated from the subsystem's parent system. If the subsystem's parent is the model itself, code generated from the subsystem is generated within model.c or model.cpp.

To generate both a separate subsystem function and a separate file,

1. Select the subsystem block. Then select Subsystem Parameters from the Simulink model editor Edit menu, to open the Block Parameters dialog box.

   Alternatively, you can open the Block Parameters dialog box by

   • Shift-double-clicking the subsystem block

   • Right-clicking the subsystem block and selecting Block parameters from the menu.

2. If the subsystem is virtual, select Treat as atomic unit. The Real-Time Workshop system code menu becomes enabled.

   If the system is already nonvirtual, the Real-Time Workshop system code menu is already enabled.

3. Select Function from the Real-Time Workshop system code menu as shown in Subsystem Function Code Generation Option with User-Specified File Name.

4. Set the function name, using the Real-Time Workshop function name options described in Real-Time Workshop Function Name Options Menu.

5. Set the file name, using any Real-Time Workshop file name option other than Auto (options are described in Real-Time Workshop File Name Options Menu).

   Subsystem Function Code Generation Option with User-Specified File Name shows the use of the User Specified file name option.

6. Click Apply and close the dialog box.

Back to Top

Modularity of Subsystem Code

Code generated from nonvirtual subsystems, when written to separate files, is not completely independent of the generating model. For example, subsystem code may reference global data structures of the model. Each subsystem code file contains appropriate include directives and comments explaining the dependencies. The Real-Time Workshop software checks for cyclic file dependencies and warns about them at build time. For descriptions of how generated code is packaged, see Generated Source Files and File Dependencies.

---

^[1] VxWorks is a registered trademark of Wind River^® Systems, Inc.

Back to Top

Laying Out the Model Architecture

Creating Model Components

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