Real-Time Workshop® Embedded Coder™

Controlling Model Function Prototypes

Overview

The Real-Time Workshop Embedded Coder software provides a Configure Model Functions button, located on the Interface pane of the Configuration Parameters dialog box, that allows you to control the model function prototypes that are generated for ERT-based Simulink models.

By default, the function prototype of an ERT-based model's generated model_step function resembles the following:

void model_step(void);

The function prototype of an ERT-based model's generated model_init function resembles the following:

void model_init(void);

(For more detailed information about the default calling interface for the model_step function, see the model_step reference page.)

The Configure Model Functions button on the Interface pane provides you flexible control over the model function prototypes that are generated for your model. Clicking Configure Model Functions launches a Model Interface dialog box (see Configuring Model Function Prototypes). Based on the Function specification value you specify for your model function (supported values include Default model initialize and step functions and Model specific C prototypes), you can preview and modify the function prototypes. Once you validate and apply your changes, you can generate code based on your function prototype modifications.

For more information about using the Configure Model Functions button and the Model Interface dialog box, see Model Function Prototypes Example and the demo model rtwdemo_fcnprotoctrl, which is preconfigured to demonstrate function prototype control.

Alternatively, you can use function prototype control functions to programmatically control model function prototypes. For more information, see Configuring Model Function Prototypes Programmatically.

You can also control model function prototypes for nonvirtual subsystems, if you generate subsystem code using right-click build. To launch the Model Interface for subsystem dialog box, use the RTW.configSubsystemBuild function.

Right-click building the subsystem generates the step and initialization functions according to the customizations you make. For more information, see Configuring Function Prototypes for Nonvirtual Subsystems.

For limitations that apply, see Model Function Prototype Control Limitations.

Back to Top

Configuring Model Function Prototypes

• Launching the Model Interface Dialog Boxes

• Default Model Initialize and Step Functions View

• Model Specific C Prototypes View

• Configuring Function Prototypes for Nonvirtual Subsystems

Launching the Model Interface Dialog Boxes

Clicking the Configure Model Functions button on the Interface pane of the Configuration Parameters dialog box launches the Model Interface dialog box. This dialog box is the starting point for configuring the model function prototypes that are generated during code generation for ERT-based Simulink models. Based on the Function specification value you select for your model function (supported values include Default model initialize and step functions and Model specific C prototypes), you can preview and modify the function prototype. Once you validate and apply your changes, you can generate code based on your function prototype modifications.

To configure function prototypes for a right-click build of a nonvirtual subsystem, invoke the RTW.configSubsystemBuild function, which launches the Model Interface for subsystem dialog box. For more information, see Configuring Function Prototypes for Nonvirtual Subsystems

Default Model Initialize and Step Functions View

The figure below shows the Model Interface dialog box in the Default model initialize and step functions view.

The Default model initialize and step functions view allows you to validate and preview the predicted default model step and initialization function prototypes. To validate the default function prototype configuration against your model, click the Validate button. If the validation succeeds, the predicted step function prototype appears in the Step function preview subpane.

Note   You cannot use the Default model initialize and step functions view to modify the function prototype configuration.

Model Specific C Prototypes View

Selecting Model specific C prototypes for the Function specification parameter displays the Model specific C prototypes view of your model function prototypes. This view provides controls that you can use to customize the function names, the order of arguments, and argument attributes including name, passing mechanism, and type qualifier for each of the model's root-level I/O ports.

To begin configuring your function control prototype configuration, click the Get Default Configuration button. This activates and initializes the function names and properties in the Configure model initialize and step functions subpane, as shown below. If you click Get Default Configuration again later, only the properties of the step function arguments are reset to default values.

In the Configure model initialize and step functions subpane:

The Step function preview subpane provides a preview of how your step function prototype is interpreted in generated code. The preview is updated dynamically as you make modifications.

An argument foo whose Category is Pointer is previewed as * foo. If its Category is Value, it is previewed as foo. Notice that argument types and qualifiers are not represented in the Step function preview subpane.

Configuring Function Prototypes for Nonvirtual Subsystems

You can control step and initialization function prototypes for nonvirtual subsystems in ERT-based Simulink models, if you generate subsystem code using right-click build. Function prototype control is supported for the following types of nonvirtual subsystems:

• Triggered subsystems

• Enabled subsytems

• Enabled trigger subsystems

• While subsystems

• For subsystems

• Stateflow subsystems if atomic

• Embedded MATLAB™ subsystems if atomic

To launch the Model Interface for subsystem dialog box, open the model containing the subsystem and invoke the RTW.configSubsystemBuild function.

The Model Interface dialog box for modifying the model-specific C prototypes for the rtwdemo_counter/Amplifier subsystem appears as follows:

Right-click building the subsystem generates the step and initialization functions according to the customizations you make.

Back to Top

Model Function Prototypes Example

The following procedure demonstrates how to use the Configure Model Functions button on the Interface pane of the Configuration Parameters dialog box to control the model function prototypes that the Real-Time Workshop Embedded Coder software generates for your Simulink model.

1. Open a MATLAB session and launch the rtwdemo_counter demo model.

2. In the rtwdemo_counter Model Editor, double-click the Generate Code Using Real-Time Workshop Embedded Coder (double-click) button to generate code for an ERT-based version of rtwdemo_counter. The code generation report for rtwdemo_counter appears.

3. In the code generation report, click the link for rtwdemo_counter.c.

4. In the rtwdemo_counter.c code display, locate and examine the generated code for the rtwdemo_counter_step and the rtwdemo_counter_initialize functions:

   /* Model step function */
   void rtwdemo_counter_step(void)
   {
    ...
   }

   /* Model initialize function */
   void rtwdemo_counter_initialize(void)
   {
    ...
   }

   You can close the report window after you have examined the generated code. Optionally, you can save rtwdemo_counter.c and any other generated files of interest to a different location for later comparison.

5. From the rtwdemo_counter model, open the Configuration Parameters dialog box.

6. Navigate to the Real-Time Workshop > Interface pane and click the Configure Model Functions button. The Model Interface dialog box appears.

7. In the initial (Default model initialize and step funtions) view of the Model Interface dialog box, click the Validate button to validate and preview the default function prototype for the rtwdemo_counter_step function. The function prototype arguments under Step function preview should correspond to the default prototype in step 4.

   

8. In the Model Interface dialog box, set Function specification field to Model specific C prototypes. Making this selection switches the dialog box from the Default model initialize and step functions view to the Model specific C prototypes view.

   

9. In the Model specific C prototypes view, click the Get Default Configuration button to activate the Configure model initialize and step functions subpane.

   

10. In the Configure model initialize and step functions subpane, change Initialize function name to rtwdemo_counter_cust_init.

11. In the Configure model initialize and step functions subpane, in the row for the Input argument, change the value of Category from Value to Pointer and change the value of Qualifier from none to const *. The preview reflects your changes.

    

12. Click the Validate button to validate the modified function prototype. The Validation subpane displays a message that the validation succeeded.

13. Click OK to exit the Model Interface dialog box.

14. Generate code for the model. When the build completes, the code generation report for rtwdemo_counter appears.

15. In the code generation report, click the link for rtwdemo_counter.c.

16. Locate and examine the generated code for the rtwdemo_counter_custom and rtwdemo_counter_cust_init functions:

    /* Customized model step function */
    void rtwdemo_counter_custom(const int32_T *arg_Input, int32_T *arg_Output)
    {
     ...
    }

     /* Model initialize function */
    void rtwdemo_counter_cust_init(void)
    {
     ...
    }

17. Verify that the generated code is consistent with the function prototype modifications that you specified in the Model Interface dialog box.

Back to Top

Configuring Model Function Prototypes Programmatically

You can use the function prototype control functions (listed in Function Prototype Control Functions), to programmatically control model function prototypes. Typical uses of these functions include:

• Create and validate a new function prototype

  1. Create a model-specific C function prototype with obj = RTW.ModelSpecificCPrototype, where obj returns a handle to a newly created, empty function prototype.

  2. Add argument configuration information for your model ports using addArgConf.

  3. Attach the function prototype to your loaded ERT-based Simulink model using attachToModel (Function Prototype Control).

  4. Validate the function prototype using runValidation (Function Prototype Control).

  5. If validation succeeds, save your model and then generate code using the rtwbuild function.

• Modify and validate an existing function prototype

  1. Get the handle to an existing model-specific C function prototype that is attached to your loaded ERT-based Simulink model with obj = RTW.getFunctionSpecification(modelName), where modelName is a string specifying the name of a loaded ERT-based Simulink model, and obj returns a handle to a function prototype attached to the specified model.

     You can use other function prototype control functions on the returned handle only if the test isa(obj,'RTW.ModelSpecificCPrototype') returns 1. If the model does not have a function prototype configuration, the function returns []. If the function returns a handle to an object of type RTW.FcnDefault, you cannot modify the existing function prototype.

  2. Use the Get and Set functions listed in Function Prototype Control Functions to test and reset such items as the function names, argument names, argument positions, argument categories, and argument type qualifiers.

  3. Validate the function prototype using runValidation (Function Prototype Control).

  4. If validation succeeds, save your model and then generate code using the rtwbuild function.

• Create and validate a new function prototype, starting with default configuration information from your Simulink model

  1. Create a model-specific C function prototype using obj = RTW.ModelSpecificCPrototype, where obj returns a handle to a newly created, empty function prototype.

  2. Attach the function prototype to your loaded ERT-based Simulink model using attachToModel (Function Prototype Control).

  3. Get default configuration information from your model using getDefaultConf (Function Prototype Control).

  4. Use the Get and Set functions listed in Function Prototype Control Functions to test and reset such items as the function names, argument names, argument positions, argument categories, and argument type qualifiers.

  5. Validate the function prototype using runValidation (Function Prototype Control).

  6. If validation succeeds, save your model and then generate code using the rtwbuild function.

Note   You should not use the same model-specific C function prototype object across multiple models. If you do, changes that you make to the step and initialization function prototypes in one model are propagated to other models, which is usually not desirable.

Function Prototype Control Functions

Back to Top

Sample M Script for Configuring Model Function Prototypes

The following sample M script configures the model function prototypes for the rtwdemo_counter model, using the Function Prototype 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')

%% Create a model-specific C function prototype
a=RTW.ModelSpecificCPrototype

%% Add argument configuration information for Input and Output ports
addArgConf(a,'Input','Pointer','inputArg','const *')
addArgConf(a,'Output','Pointer','outputArg','none')

%% Attach the model-specific C function prototype to the model
attachToModel(a,gcs)

%% Rename the initialization function
setFunctionName(a,'InitFunction','init')

%% Rename the step function and change some argument attributes
setFunctionName(a,'StepFunction','step')
setArgPosition(a,'Output',1)
setArgCategory(a,'Input','Value')
setArgName(a,'Input','InputArg')
setArgQualifier(a,'Input','none')

%% 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

Verifying Generated Code for Customized Functions

You can use software-in-the-loop (SIL) testing to verify the generated code for your customized step and initialization functions. This involves generating an ERT S-function wrapper for your generated code, which then can be integrated into a Simulink model to verify that the generated code provides the same result as the original model or nonvirtual subsystem. For more information, see Automatic S-Function Wrapper Generation and Verifying Generated Code with Software-in-the-Loop.

Back to Top

Model Function Prototype Control Limitations

The following limitations apply to controlling model function prototypes:

• Function prototype control supports only step and initialization functions generated from a Simulink model.

• Function prototype control supports only single-instance implementations. For standalone targets, you must clear the Generate reusable code check box (on the Interface pane of the Configuration Parameters dialog box). For model reference targets, you must select One for the Total number of instances allowed per top model parameter (on the Model Referencing pane of the Configuration Parameters dialog box).

• For model reference targets, the code generator ignores the Generate reusable code parameter (on the Interface pane of the Configuration Parameters dialog box).

• You must select the Single output/update function parameter (on the Interface pane of the Configuration Parameters dialog box).

• Function prototype control does not support multitasking models. Multirate models are supported, but you must configure the models for single-tasking.

• You must configure root-level inports and outports to use Auto storage classes.

• The generated code for a parent model does not call the function prototype control step functions generated from referenced models.

• Do not control function prototypes with the static ert_main.c provided by The MathWorks™. Specifying a function prototype control configuration other than the default creates a mismatch between the generated code and the default static ert_main.c.

• The code generator removes the data structure for the root inports of the model unless a subsystem implemented by a nonreusable function uses the value of one or more of the inports.

• The code generator removes the data structure for the root outports of the model except when you enable MAT-file logging, or if the sample time of one or more of the outports is not the fundamental base rate (including a constant rate).

• If you copy a subsystem block and paste it to create a new block in either a new model or the same model, the function prototype control interface information from the original subsystem block does not copy to the new subsystem block.

• 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

Nonvirtual Subsystem Modular Function Code Generation

Generating and Controlling C++ Encapsulation Interfaces