Real-Time Workshop® Embedded Coder™

Generating and Controlling C++ Encapsulation Interfaces

Overview of C++ Encapsulation

Using the Real-Time Workshop Embedded Coder language option C++ (Encapsulated), you can generate a C++ class interface to model code. The generated interface encapsulates all required model data into C++ class attributes and all model entry point functions into C++ class methods. The benefits of encapsulation include:

• Greater control over access to model data

• Ability to multiply instantiate model classes

• Easier integration of model code into C++ programming environments

C++ encapsulation also works for right-click builds of nonvirtual subsystems. (For information on requirements that apply, see Configuring C++ Encapsulation Interfaces for Nonvirtual Subsystems.)

The general procedure for generating C++ encapsulation interfaces to model code is as follows:

1. Configure your model to use an ert.tlc system target file provided by The MathWorks.

2. Select the language option C++ (Encapsulated) for your model.

3. Optionally, configure related C++ encapsulation interface settings for your model code, using either a graphical user interface (GUI) or application programming interface (API).

4. Generate model code and examine the results.

To get started with an example, see C++ Encapsulation Quick-Start Example. For more details about configuring C++ encapsulation interfaces for your model code, see Generating and Configuring C++ Encapsulation Interfaces to Model Code and Configuring C++ Encapsulation Interfaces Programmatically. For limitations that apply, see C++ Encapsulation Interface Control Limitations.

Note   For a demonstration of the C++ encapsulation capability, see the demo model rtwdemo_cppencap.

Back to Top

C++ Encapsulation Quick-Start Example

This example illustrates a simple use of the C++ (Encapsulated) option. It uses C++ encapsulation to generate interfaces for code from a Real-Time Workshop demo model, without extensive modifications to default settings.

Note   For details about setting C++ encapsulation options, see the sections that follow this example, beginning with Generating and Configuring C++ Encapsulation Interfaces to Model Code.

To generate C++ encapsulated interfaces for a Simulink model:

1. Open a model for which you would like to generate C++ encapsulation interfaces. This example uses the Real-Time Workshop demo model rtwdemo_counter.

2. Configure the model to use an ert.tlc system target file provided by The MathWorks. For example, open the Configuration Parameters dialog box, go to the Real-Time Workshop pane, select an appropriate target value from the System target file menu, and click Apply.

3. Optionally, as a baseline for later code comparison, generate code from the model using a different Language parameter setting, C++ or C. (You can set up the build directory naming or location to distinguish your baseline build from later builds of the same model.)

4. On the Real-Time Workshop pane of the Configuration Parameters dialog box, select the C++ (Encapsulated) language option.

   

   Click Apply.

   Note   To immediately generate the default style of encapsulated C++ code, without exploring the related model configuration options, skip steps 5–9 and go directly to step 10.

5. Go to the Interface pane of the Configuration Parameters dialog box and examine the Code interface subpane.

   

   When you selected the C++ (Encapsulated) language option for your model, C++ encapsulation interface controls replaced the default options on the Code interface subpane. See Configuring Code Interface Options for descriptions of these controls. Examine the default settings and modify as appropriate.

6. Click the Configure C++ Encapsulation Interface button. This action opens the Configure C++ encapsulation interface dialog box, which allows you to configure the step method for your generated model class. The dialog box initially displays a view for configuring a void-void style step method (passing no I/O arguments) for the model class. In this view, you can rename the model class and the step method for your model.

   

   See Configuring the Step Method for Your Model Class for descriptions of these controls.

   Note   If the void-void interface style meets your needs, you can skip steps 7–9 and go directly to step 10.

7. If you want root-level model input and output to be arguments on the step method, select the value I/O arguments step method from the Function specification menu. The dialog box displays a view for configuring an I/O arguments style step method for the model class.

   

   See Configuring the Step Method for Your Model Class for descriptions of these controls.

8. Click the Get Default Configuration button. This action causes a Configure C++ encapsulation interface subpane to appear in the dialog box. The subpane displays the initial interface configuration for your model, which provides a starting point for further customization.

   

   See Passing I/O Arguments for descriptions of these controls.

9. Perform this optional step only if you want to customize the configuration of the I/O arguments generated for your model step method.

   Note   If you choose to skip this step, you should click Cancel to exit the dialog box.

   If you choose to perform this step, first you must check that the required option Remove root level I/O zero initialization is selected on the Optimization pane, and then navigate back to the I/O arguments step method view of the Configure C++ encapsulation interface dialog box.

   Now you can use the dialog box controls to configure I/O argument attributes. For example, in the Configure C++ encapsulation interface subpane, in the row for the Input argument, you can change the value of Category from Value to Pointer and change the value of Qualifier from none to const *. The preview updates to reflect your changes. Click the Validate button to validate the modified interface configuration.

   Continue modifying and validating until you are satisfied with the step method configuration.

   

   Click Apply and OK.

10. Generate code for the model. When the build completes, the code generation report for rtwdemo_counter appears. Examine the report and observe that all required model data is encapsulated into C++ class attributes and all model entry point functions are encapsulated into C++ class methods. For example, click the link for rtwdemo_counter.h to see the class declaration for the model.

Note   If you configured custom I/O arguments for the model step method (optional step 9), examine the generated code for the step method in rtwdemo_counter.h and rtwdemo_counter.cpp. The arguments should reflect your changes. For example, if you performed the Input argument modifications in step 9, the input argument should appear as const int32_T *arg_Input. If you saved a baseline model build (optional step 3), you can traverse and compare the generated files in the corresponding build directories.

Back to Top

Generating and Configuring C++ Encapsulation Interfaces to Model Code

• Selecting the C++ (Encapsulated) Option

• Configuring Code Interface Options

• Configuring the Step Method for Your Model Class

• Configuring C++ Encapsulation Interfaces for Nonvirtual Subsystems

Selecting the C++ (Encapsulated) Option

To select the C++ (Encapsulated) option, use the Language menu on the Real-Time Workshop pane of the Configuration Parameters dialog box or Model Explorer:

Selecting this option has the following effects on other panes in the Configuration Parameters dialog box:

• Disables model configuration options that C++ (Encapsulated) does not support. For details, see C++ Encapsulation Interface Control Limitations.

• Replaces the default options in the Code interface subpane on the Interface pane with C++ encapsulation interface controls, which are described in the next section.

Configuring Code Interface Options

When you select the C++ (Encapsulated) option for your model, the C++ encapsulation interface controls shown below replace the default options in the Code interface subpane on the Interface pane.

• Parameters and states members private

  Generates non-I/O model structures, including states and parameters, as private data members (on by default).

• Parameters and states access methods

  Generates get/set access methodsfor non-I/O model structures, including states and parameters (off by default).

• Generate destructor

  Generates a destructor for the model class (on by default).

• I/O access methods

  Generates access methods for root-level I/O signals if possible (off by default).

  Note   This option affects generated code only if you are using the default (void-void style) step method for your model class, and not if you are explicitly passing arguments for root-level I/O signals using an I/O arguments style step method. For more information, see Passing No Arguments (void-void) and Passing I/O Arguments.

• Inline access methods

  Inlines generated access methods (off by default).

• Suppress error status in real-time model data structure

  Omits the error status field from the generated real-time model data structure rtModel (off by default). This option reduces memory usage.

  Selecting this option can cause the code generator to omit the rtModel data structure from generated code.

• Configure C++ Encapsulation Interface

  Launches the Configure C++ encapsulation interface dialog box, which allows you to configure the step method for your model class. For more information, see Configuring the Step Method for Your Model Class.

Configuring the Step Method for Your Model Class

To configure the step method for your model class, click the Configure C++ Encapsulation Interface button, which appears on the Interface pane when you selectC++ (Encapsulated) for your model. This action opens the Configure C++ encapsulation interface dialog box, which allows you to configure the step method for your model class in either of two styles:

• Passing No Arguments (void-void)

• Passing I/O Arguments

Note   The void-void style of step method specification supports single-rate models and multirate models, while the I/O arguments style supports single-rate models and multirate single-tasking models.

Passing No Arguments (void-void).   The Configure C++ encapsulation interface dialog box initially displays a view for configuring a void-void style step method for the model class.

• Step method name

  Allows you to specify a step method name other than the default, step.

• Class name

  Allows you to specify a model class name other than the default, modelModelClass.

• Step function preview

  Displays a preview of the model step function prototype as currently configured. The preview display is dynamically updated as you make configuration changes.

• Validate

  Validates your current model step function configuration. The Validation pane displays success or failure status and an explanation of any failure.

Passing I/O Arguments.   If you select I/O arguments step method from the Function specification menu, the dialog box displays a view for configuring an I/O arguments style step method for the model class.

Note   To use the I/O arguments style step method, you must select the option Remove root level I/O zero initialization on the Optimization pane of the Configuration Parameters dialog box.

• Get Default Configuration

  Click this button to get the initial interface configuration that provides a starting point for further customization.

• Step function preview

  Displays a preview of the model step function prototype as currently configured. The preview dynamically updates as you make configuration changes.

• Validate

  Validates your current model step function configuration. The Validation pane displays success or failure status and an explanation of any failure.

When you click Get Default Configuration, the Configure C++ encapsulation interface subpane appears in the dialog box, displaying the initial interface configuration. For example:

• Step method name

  Allows you to specify a step method name other than the default, step.

• Class name

  Allows you to specify a model class name other than the default, modelModelClass.

• Order

  Displays the numerical position of each argument. Use the Up and Down buttons to change argument order.

• Port Name

  Displays the port name of each argument (not configurable using this dialog box).

• Port Type

  Displays the port type, Inport or Outport, of each argument (not configurable using this dialog box).

• Category

  Displays the passing mechanism for each argument. To change the passing mechanism for an argument, select Value, Pointer, or Reference from the argument's Category menu.

• Argument Name

  Displays the name of each argument. To change an argument name, click in the argument's Argument name field, position the cursor for text entry, and enter the new name.

• Qualifier

  Displays the const type qualifier for each argument. To change the qualifier for an argument, select an available value from the argument's Qualifier menu. The possible values are:

  • none

  • const (value)

  • const* (value referenced by the pointer)

  • const*const (value referenced by the pointer and the pointer itself)

  • const & (value referenced by the reference)

Configuring C++ Encapsulation Interfaces for Nonvirtual Subsystems

C++ encapsulation interfaces can be configured for right-click builds of nonvirtual subsystems in Simulink models, provided that:

• You select the system target file ert.tlc for the model.

• You select the Language parameter value C++ (Encapsulated) for the model.

• The subsystem is convertible to a Model block using the function Simulink.SubSystem.convertToModelReference. For referenced model conversion requirements, see the Simulink reference page Simulink.SubSystem.convertToModelReference.

To configure C++ encapsulation interfaces for a subsystem that meets the requirements:

1. Open the containing model and select the subsystem block.

2. Enter the following MATLAB command:

   RTW.configSubsystemBuild(gcb)

   where gcb is the Simulink function gcb, returning the full block path name of the current block.

   This command opens a subsystem equivalent of the Configure C++ encapsulation interface dialog sequence that is described in detail in the preceding section, Configuring the Step Method for Your Model Class. (For more information about using the MATLAB command, see RTW.configSubsystemBuild.)

3. Use the Configure C++ encapsulation interface dialog boxes to configure C++ encapsulation settings for the subsystem.

4. Right-click the subsystem and select Real-Time Workshop > Build Subsystem.

5. When the subsystem build completes, you can examine the C++ encapsulation interfaces in the generated files and the HTML code generation report.

Back to Top

Configuring C++ Encapsulation Interfaces Programmatically

If you select the Language option C++ (Encapsulated) for your model, you can use the C++ encapsulation interface control functions (listed in C++ Encapsulation Interface Control Functions) to programmatically configure the step method for your model class.

Typical uses of these functions include:

• Create and validate a new step method interface, starting with default configuration information from your Simulink model

  1. Create a model-specific C++ encapsulation interface with obj = RTW.ModelCPPVoidClass or obj = RTW.ModelCPPArgsClass, where obj returns a handle to an newly created, empty C++ encapsulation interface.

  2. Attach the C++ encapsulation interface to your loaded ERT-based Simulink model using attachToModel (C++ Encapsulation Interface Control).

  3. Get default C++ encapsulation interface configuration information from your model using getDefaultConf (C++ Encapsulation Interface Control).

  4. Use the Get and Set functions listed in C++ Encapsulation Interface Control Functions to test or reset the model class name and model step method name. Additionally, if you are using the I/O arguments style step method, you can test and reset argument names, argument positions, argument categories, and argument type qualifiers.

  5. Validate the C++ encapsulation interface using runValidation (C++ Encapsulation Interface Control). (If validation fails, use the error message information thatrunValidation returns to address the issues.)

  6. Save your model and then generate code using the rtwbuild function.

• Modify and validate an existing step method interface for a Simulink model

  1. Get the handle to an existing model-specific C++ encapsulation interface that is attached to your loaded ERT-based Simulink model using obj = RTW.getEncapsulationInterfaceSpecification(modelName), where modelName is a string specifying the name of a loaded ERT-based Simulink model, and obj returns a handle to a C++ encapsulation interface attached to the specified model. If the model does not have an attached C++ encapsulation interface configuration, the function returns [].

  2. Use the Get and Set functions listed in C++ Encapsulation Interface Control Functions to test or reset the model class name and model step method name. Additionally, if the returned interface uses the I/O arguments style step method, you can test and reset argument names, argument positions, argument categories, and argument type qualifiers.

  3. Validate the C++ encapsulation interface using runValidation (C++ Encapsulation Interface Control). (If validation fails, use the error message information that runValidation returns to address the issues.)

  4. Save your model and then generate code using the rtwbuild function.

Note   You should not use the same model-specific C++ encapsulation interface control object across multiple models. If you do, changes that you make to the step method configuration in one model propagate to other models, which is usually not desirable.

C++ Encapsulation Interface Control Functions

Back to Top

Sample M-Script for Configuring the Step Method for a Model Class

The following sample M-script configures the step method for the rtwdemo_counter model class, using the C++ Encapsulation Interface Control Functions.

%% Open the rtwdemo_counter model
rtwdemo_counter

%% Select ert.tlc as the System Target File for the model
set_param(gcs,'SystemTargetFile','ert.tlc')

%% Select C++ (Encapsulated) as the target language for the model
set_param(gcs,'TargetLang','C++ (Encapsulated)')

%% Set required option for I/O arguments style step method (cmd off = GUI on)
set_param(gcs,'ZeroExternalMemoryAtStartup','off')

%% Create a C++ encapsulated interface using an I/O arguments style step method
a=RTW.ModelCPPArgsClass

%% Attach the C++ encapsulated interface to the model
attachToModel(a,gcs)

%% Get the default C++ encapsulation interface configuration from the model
getDefaultConf(a)

%% Move the Output port argument from position 2 to position 1
setArgPosition(a,'Output',1)

%% Reset the model step method name from step to StepMethod
setStepMethodName(a,'StepMethod')

%% Change the Input port argument name, category, and qualifier
setArgName(a,'Input','inputArg')
setArgCategory(a,'Input','Pointer')
setArgQualifier(a,'Input','const *')

%% Validate the function prototype against the model
[status,message]=runValidation(a)

%% if validation succeeded, generate code and build
if status
    rtwbuild(gcs)
end

Back to Top

C++ Encapsulation Interface Control Limitations

• The C++ (Encapsulated) option does not support some Simulink model configuration options. Selecting C++ (Encapsulated) disables the following items in the Configuration Parameters dialog box:

  • Identifier format control subpane on the Symbols pane

  • Templates pane

    • The Templates pane parameter File customization template is not supported for C++ (Encapsulated) code generation.

    • Selecting C++ (Encapsulated) turns on the Templates pane option Generate an example main program but removes it from the Configuration Parameters dialog box. If desired, you can disable it using the command line parameter GenerateSampleERTMain.

  • Data Placement pane

  • Memory Sections pane

  Note   Selecting C++ (Encapsulated) forces on the Real-Time Workshop pane model option Ignore custom storage classes. By design, C++ (Encapsulated) code generation treats data objects with custom storage classes as if their storage class attribute is set to Auto.

• Among the data exchange interfaces available on the Interface pane of the Configuration Parameters dialog box, only the C API interface is supported for C++ (Encapsulated) code generation. If you select External mode or ASAP2, code generation fails with a validation error.

• The I/O arguments style of step method specification supports single-rate models and multirate single-tasking models, but not multirate multitasking models.

• A generated model class provides an encapsulated interface only to the top model in a model reference hierarchy. The C++ (Encapsulated) Language setting should be selected only for the top model in a hierarchy, not for the referenced models. If you build a model containing a Model block whose referenced model has C++ (Encapsulated) selected as the Language setting, the build reports an error.

• The C++ (Encapsulated) option does not support use of the IncludeERTFirstTime model option to include the firstTime argument in the model_initialize function generated for an ERT-based models. (The IncludeERTFirstTime option is off by default except for models created with R2006a.) Also, the C++ (Encapsulated) option requires that the target selected for the model support firstTime argument control by setting the ERTFirstTimeCompliant target option, which all targets provided by The MathWorks do by default. In other words, the C++ (Encapsulated) option requires that the target option ERTFirstTimeCompliant is on and the model option IncludeERTFirstTime is off.

• The Real-Time Workshop > Export Functions capability does not support C++ (Encapsulated) as the target language.

• For a Stateflow chart that uses a model root inport value, or that calls a subsystem that uses a model root inport value, you must do one of the following to generate code:

  • Clear the Execute (enter) Chart At Initialization check box in the Stateflow chart.

  • Make the Stateflow function a nonreusable function.

  • Insert a Signal Conversion block immediately after the root inport and select the Override optimizations and always copy signal check box in the Signal Conversion block parameters.

Back to Top

Controlling Model Function Prototypes

Creating and Using Host-Based Shared Libraries