Processor-in-the-Loop (PIL) Simulation for Embedded Targets :: Verification and Profiling Code Generated for Embedded Targets (Embedded Coder™)

Processor-in-the-Loop (PIL) Simulation for Embedded Targets

On this page…
Overview PIL Approaches Communications Running Your PIL Application to Perform Simulation and Verification Example — Performing a Model Block PIL Simulation via SCI Using Makefiles Definitions PIL Issues and Limitations

On this page…

Overview

PIL Approaches

Communications

Running Your PIL Application to Perform Simulation and Verification

Example — Performing a Model Block PIL Simulation via SCI Using Makefiles

Definitions

PIL Issues and Limitations

Overview

Verification consists broadly of running generated code on a processor and verifying that the code does what you intend. Embedded Coder provides processor-in-the-loop (PIL) simulation to meet this need. PIL compares the numeric output of your model under simulation with the numeric output of your model running as an executable on a target processor.

With PIL, you run your generated code on a target processor or instruction set simulator. To verify your generated code, you compare the output of model simulation modes, such as Normal or Accelerator, with the output of the generated code running on the processor. You can switch between simulation and PIL modes. This flexibility allows you to verify the generated code by executing the model as compiled code in the target environment. You can model and test your embedded software component in Simulink and then reuse your regression test suites across simulation and compiled object code. This process avoids the time-consuming process of leaving the Simulink software environment to run tests again on object code compiled for the production hardware.

Embedded Coder supports the following PIL approaches:

Model block PIL
Top-model PIL
PIL block

When you use makefiles with PIL, use the "model block PIL" approach. With makefiles, the other two approaches, "top-model PIL" and "PIL block", and are not supported.

For more information about PIL, see Numerical Equivalence Checking

Processor-in-the-loop (PIL) builds and uses a MEX function to run the PIL simulation block. Before using PIL, set up a compiler for MATLAB to build the MEX files. Run the command |mex -setup| to select a compiler configuration. For more information, read Building MEX-Files

PIL Approaches

Model Block PIL

Use model block PIL to:

Verify code generated for referenced models (model reference code interface).
Provide a test harness model (or a system model) to generate test vector or stimulus inputs.
Switch a model block between normal, SIL, or PIL simulation modes.

To perform a model block PIL simulation, start with a top-model that contains a model block. The top-model serves as a test harness, providing inputs and outputs for the model block. The model block references the model you plan to run on a target processor. During PIL simulation, the referenced model runs on the target processor.

For more information about using the model block, see Model, Model Variants and Referencing a Model.

By default, your MathWorks software uses the IDE debugger for PIL communications with the target processor. To achieve faster communications, consider using one alternatives presented in Communications.

To use model block PIL:

Right-click the Model block, and select ModelReference Parameters.
When the software displays the Function Block Parameters: Model dialog box, set Simulation mode to Processor-in-the-loop (PIL) and click OK.
Open the model block.
Add a Target Preferences block to either model, and configure it for the target processor.
Copy the Target Preferences block from one model to the other. The top-model and the model block now contain identical Target Preference blocks.
In the referenced model (model block) Configuration Parameters (Ctrl+E), under Code Generation > IDE Link, set Build action set to Archive_library. This action avoids a warning when you start the simulation.
Save the changes to both models.
In the top-model menu bar, select Simulation > Start. This action builds the referenced model in the model block, downloads it to your target processor, and runs the PIL simulation.

Note In the top-model Configuration Parameters (Ctrl+E), under Code Generation > IDE Link, leave Build action set to Build_and_execute. Do not change Build action to Create_Processor_In_the_Loop_Project.

For more information, see Numerical Equivalence Checking

Top-Model PIL

Use top-model PIL to:

Verify code generated for a top-model (standalone code interface).
Load test vectors or stimulus inputs from the MATLAB workspace.
Switch the entire model between normal and SIL or PIL simulation modes.

For more information, see Numerical Equivalence Checking

Setting Model Configuration Parameters to Generate the PIL Application. Configure your model to generate the PIL executable from your model:

Add a Target Preferences block in to your model. The Target Preferences block is located in the Simulink library browser under Embedded Coder > Embedded Targets.
Open the Target Preferences block and select your processor from the list of processors.
From the model window, select Simulation > Configuration Parameters.
In Configuration Parameters, select Code Generation.
Set System Target File to idelink_ert.tlc.
From the list of panes under Code Generation, choose IDE Link.
Set Build format to Project.
Set Build action to Create_processor_in_the_loop_project.
Click OK to close the Configuration Parameters dialog box.

Running the Top-Model PIL Application. To create a PIL block, perform the following steps:

In the model window menu, select Simulation > Processor-in-the-loop.
In the model toolbar, click the Start simulation button.
A new model window opens and the new PIL model block appears in it. The third-party IDE compiles and links the PIL executable file. Follow the progress of the build process in the MATLAB command window.

PIL Block

Use the PIL block to:

Verify code generated for a top-model (standalone code interface) or subsystem (right-click build standalone code interface).
Represent a component running in SIL or PIL mode. The test harness model or a system model provides test vector or stimulus inputs.

For more information, see Numerical Equivalence Checking.

Preparing Your Model to Generate a PIL Block. Start with a model that contains the algorithm blocks you want to verify on the processor as compiled object code. To create a PIL application and PIL block from your algorithm subsystem, follow these steps:

Identify the algorithm blocks to cosimulate.
Convert those blocks into an unmasked subsystem in your model.
For information about how to convert your process to a subsystem, refer to Creating Subsystems in Using Simulink or in the online Help system.
Open the newly created subsystem and copy a Target Preferences block to it. The Target Preferences block is located in the Simulink library browser under Embedded Coder > Embedded Targets.
Open the Target Preferences block and select your processor from the list of processors.

Setting Model Configuration Parameters to Generate the PIL Application. After you create your subsystem, set the Configuration Parameters for your model to enable the model to generate a PIL block.

Configure your model to enable it to generate PIL algorithm code and a PIL block from your subsystem:

From the model menu bar, select Simulation > Configuration Parameters. This action opens the Configuration Parameters dialog box.
In the Configuration Parameters dialog box, select Code Generation.
Set System Target File to idelink_ert.tlc.
From the list of panes under Code Generation, choose IDE Link.
Set Build format to Project.
Set Build action to Create_processor_in_the_loop_project.
Click OK to close the Configuration Parameters dialog box.

Creating the PIL Block from a Subsystem. To create a PIL block, perform the following steps:

Right-click the masked subsystem in your model and select Code Generation > Build Subsystem from the context menu.
A new model window opens and the new PIL block appears in it. The third-party IDE compiles and links the PIL executable file.
This step builds the PIL algorithm object code and a PIL block that corresponds to the subsystem, with the same inputs and outputs. Follow the progress of the build process in the MATLAB command window.
Copy the new PIL block from the new model to your model. To simulate the subsystem processes concurrently, place it parallel to your masked subsystem. Otherwise, replace the subsystem with the PIL block.
To see a PIL block in a parallel masked subsystem, search the product help for Getting Started with Application Development and select the demo that matches your IDE.

Note Models can have multiple PIL blocks for different subsystems. They cannot have more than one PIL block for the same subsystem. Including multiple PIL blocks for the same subsystem causes errors and inaccurate results.

Communications

Chose one of the following communication methods for transferring code and data during PIL simulations:

Method	Speed	Comments
IDE Debugger	Slow	Supports PIL communications with an executable running an embedded target processor. Supports the largest number of targets. Requires a physical connection between host and target processor. Only works with builds from IDE projects. Does not work with builds from makefiles.
TCP/IP	Fast	Supports PIL communications with an executable running on a Linux or Windows host. Supports embedded targets running Linux, TI DSP/BIOS, and Wind River VxWorks. Requires network connection between host and target processor. Works with builds from IDE projects and from makefiles.
Serial Communication Interface (SCI)	Fast	Supports PIL communications with an executable running an embedded target processor. Supports only TI C28035 and C28335 microcontrollers. Requires an SCI connection between host and target processor. Works with builds from IDE projects and from makefiles.

Method

Speed

Comments

IDE Debugger

Slow

Supports PIL communications with an executable running an embedded target processor.
Supports the largest number of targets.
Requires a physical connection between host and target processor.
Only works with builds from IDE projects. Does not work with builds from makefiles.

TCP/IP

Fast

Supports PIL communications with an executable running on a Linux or Windows host.
Supports embedded targets running Linux, TI DSP/BIOS, and Wind River VxWorks.
Requires network connection between host and target processor.
Works with builds from IDE projects and from makefiles.

Serial Communication Interface (SCI)

Fast

Supports PIL communications with an executable running an embedded target processor.
Supports only TI C28035 and C28335 microcontrollers.
Requires an SCI connection between host and target processor.
Works with builds from IDE projects and from makefiles.

TCP/IP

You can use TCP/IP for PIL communications with a hardware target running:

Linux
Texas Instruments DSP/BIOS
Wind River VxWorks

Using TCP/IP for PIL communications is typically faster than using a debugger, particularly for large data sets, such as with video and audio applications.

It also works well when you build an application on a remote Linux target using the remoteBuild function.

You can use TCP/IP with the following PIL approaches:

Top-model PIL
Model block PIL

TCP/IP does not work with the Subsystem PIL approach.

To enable and configure TCP/IP with PIL:

Set up a PIL simulation according to the PIL approach you have chosen.
At the MATLAB command line, use setpref to specify the IP address of the PIL server (servername).
If you are running the PIL server on a remote target, specify the IP address of the target processor. For example:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','servername','144.212.109.114');
```
If you are running PIL server locally, on your host Windows or Linux system, enter 'localhost' instead of an IP address:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','servername','localhost');
```
Specify the TCP/IP port number to use for PIL data communication. Use one of the free ports in your system. For example:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','portnum', 17025);
```
Enable PIL communications over TCP/IP:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enabletcpip', true);
```
To disable PIL communications over TCP/IP, change the value to false. This action automatically enables PIL communications over an IDE debugger, if an IDE is available.
Open the Target Preferences block in your model, then set the Operating System parameter to an operating system.
Regenerate the code or PIL block.

To disable PIL communications over TCP/IP, enter:

setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enabletcpip', false);

Additional Steps for TI C6000 Processors

Serial Communication Interface (SCI) for Texas Instruments C2000

You can use SCI for processor-in-the-loop (PIL) simulations with Texas Instruments C2000 processors that support Serial Communications Interface (SCI). For other targets, configure PIL to communicate through TCP/IP or an IDE debugger.

SCI typically provides faster communications than an IDE debugger, particularly for large data sets.

To enable and configure SCI with PIL:

Set up a PIL simulation according to the PIL approach you have chosen.
At the MATLAB command line, use setpref to specify the Configuration Parameters:
1. Select the SCI port on your host computer that will be used for communicating with the target processor. For example, to use COM1, enter the following command:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences', 'COMPort','COM1');
```
2. Set the baud rate of the SCI port. For example, if both the host computer and the target support 115200 baud, enter:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','BaudRate', 115200);
```
3. Enable PIL communications over SCI:
```
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enableserial',true);
```
Configure the serial communications settings on your host computer to match the preceding values. For example, in Windows 7:
1. Open the Windows Device Manager. (Press the Windows key on your keyboard and search for "Device Manager".)
2. Expand Ports (COM & LPT1).
3. Right-click the communications port you previously specified in MATLAB, such as Communications Port (COM1), and select Properties.
4. Go to the Port Settings tab, and match the value of Bits per second with the baud rate you previously specified in MATLAB. This value should match the baud rate you set in MATLAB. For example, 'BaudRate',115200.
Regenerate the code or PIL block.

To disable PIL communications over SCI, enter:

setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enableserial',false);

See Example — Performing a Model Block PIL Simulation via SCI Using Makefiles

IDE Debugger

To enable PIL communications over an IDE debugger, disable PIL communications over TCP/IP and SCI by entering the following commands:

setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enabletcpip',false);
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enableserial',false);

Then regenerate the code or PIL block.

Using IDE debugger for PIL communication only works when you build your code from IDE projects. Using IDE debugger for PIL communication does not work with builds from makefiles.

Configuring Breakpoints. You can use the setStartApplicationPause API to set breakpoints in the PIL application on the first PIL block simulation. If you do not use the setStartApplicationPause API, you can configure breakpoints after the initial run. The breakpoints remain active for subsequent runs.

You can enter the following static API method to pause after loading the application and manually configure breakpoints:

rtw.connectivity.Launcher.setStartApplicationPause(pauseAmount)

About this method:

This method tells the MATLAB session to pause immediately after the PIL launcher starts the PIL application.
pauseAmount is a pause time in seconds. To disable the pause, enter 0.

When you do not specify a pause, the software displays the following message:

### To pause during PIL application start, run: >> rtw.connectivity.Launcher.
setStartApplicationPause(120)

The default pause is 120 sec. You can change this value.

When you specify a pause, a Start PIL Application Pause message box appears and displays following message:

Pausing during PIL application start for 120s (click OK to continue).
To disable this pause, see the hyperlink in the MATLAB command window.

The MATLAB command window shows the following text:
```
### To remove the pause during PIL application start, 
run: >> rtw.connectivity.Launcher. setStartApplicationPause(0)
```
where rtw.connectivity.Launcher. setStartApplicationPause(0) is a hyperlink.
The pause times out, or you can clear it early by closing the message box.
During the pause, you cannot access MATLAB and thus cannot configure breakpoints programmatically via the IDE Automation Interface API.
For the PIL block, the IDE Link debugger stays open between simulation runs. When you perform an initial simulation run, you can automatically configure breakpoints via the IDE Automation Interface API before starting the second simulation.

Running Your PIL Application to Perform Simulation and Verification

After you add your PIL block to your model, click Simulation > Start to run the PIL simulation and view the results.

Example — Performing a Model Block PIL Simulation via SCI Using Makefiles

This example shows you the complete workflow for performing a processor-in-the loop (PIL) simulation that uses Serial Communications Interface (SCI) for communications.

Prerequisites

Follow the board vendor's instructions for setting up a Texas Instruments C2000-based board that supports SCI. Connect the board to your host computer using a serial cable.

Add a Target Preferences Block to Your Model

Enter fuelsys_pil in MATLAB. This action opens the fuelsys_pil model with the title, "Verifying the Fixed-Point Fuel Control System".
Open the Simulink Library Browser and search for "Target Preferences". The search results display a Target Preferences block.
Copy the Target Preferences block into the fuelsys_pil model. This action opens the In fuelsys_pil/Target Preferences: Initialize Configuration Parameters dialog box.
In the dialog box, set IDE/Tool Chain to Texas Instruments Code Composer Studio (CCSv3), or to Texas Instruments Code Composer Studio v4 (makefile generation only) (CCSv4).
Set Board to an option that supports using SCI for PIL communications, such as SD F28335 eZdsp.
Click Yes.

If you are working with CCSv3, configure fuelsys_pil to use makefiles:

Select Simulation > Configuration Parameters.
In the Configuration Parameters dialog box, expand Code Generation and select IDE Link.
On the IDE Link pane, set Build format to Makefile.

If you are working with CCSv4, you do not need to configure the model to use makefiles. Initializing the configuration parameters for CCSv4 automatically sets Build format to Makefile.

Configure Your Model for the Model Block PIL Approach

In the fuelsys_pil, copy the fuelsys_ctr model and paste it into the vacant space below. Connect it to the input/output signals provided.
Right-click the upper fuelsys_ctr model, labeled "Model", and select ModelReference Parameters.
In the Function Block Parameters: Model dialog box, set the Simulation mode parameter to Processor-in-the-loop (PIL). Click the OK button.
Open the upper fuelsys_ctr model, labeled "Model".
Copy the Target Preferences block from fuelsys_pil to the open fuelsys_ctr model.
Without changing any parameters, click Yes in the In fuelsys_ctr/Target Preferences: Initialize Configuration Parameters dialog box.
From the menu in the open fuelsys_ctr model, select Simulation > Configuration Parameters (or press Ctrl+E).
In the Configuration Parameters dialog box, in the Solver pane, set the Type parameter to Fixed-step, and set Solver to ode3 (Bogacki-Shampine).

At the MATLAB command line, enter:

set_param('fuelsys_ctr', 'ModelReferenceSymbolNameMessage', 'none')

In the Code Generation > Interface pane, clear the Software environment absolute time checkbox.
In the Code Generation > IDE Link pane, set the Run time Build action parameter to Archive library.
Save the changes to your model, and leave the model open.

Note For information other PIL approaches, see PIL Approaches.

Enable and configure SCI

Use setpref to specify the Configuration Parameters in MATLAB :

setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','COMPort','COM1');
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','BaudRate',115200);
setpref('MathWorks_Embedded_IDE_Link_PIL_Preferences','enableserial',true);

Configure the serial communications settings on your host computer to match the preceding values. For example, in Windows 7:
1. Open the Windows Device Manager. (Press the Windows key on your keyboard and search for "Device Manager".)
2. Expand Ports (COM & LPT1).
3. Right-click the communications port you previously specified in MATLAB, such as Communications Port (COM1), and select Properties.
4. Go to the Port Settings tab, and match the value of Bits per second with the baud rate you previously specified in MATLAB. This value should match the baud rate you set in MATLAB. For example, 'BaudRate',115200.

Configure the Software to Use Makefiles

Enter xmakefilesetup in MATLAB. This action opens the XMakefile User Configuration dialog box.
In the dialog box, set the Configuration parameter to ticcs_c2000_ccsv3 or ticcs_c2000_ccsv4. To see more options, clear the Display operational configurations only checkbox.
Click the Apply button, and respond to any messages requesting the location of your tool chain.
Click the OK button.

Run the PIL Simulation

Make sure the SD F28335 eZdsp board is connected to your host computer via serial and USB cables and powered up.
Simulate the fuelsys_pil model (press Ctrl+T).

Definitions

PIL Algorithm

The algorithmic code, which corresponds to a subsystem or portion of a model, to test during the PIL simulation. The PIL algorithm is in compiled object form to enable verification at the object level.

PIL Application

The executable application that runs on the processor platform. Your coder product creates a PIL application by augmenting your algorithmic code with the PIL execution framework. The PIL execution framework code compiles as part of your embedded application.

The PIL execution framework code includes the string.h header file so that the PIL application can use the memcpy function. The PIL application uses memcpy to exchange data between the Simulink model and the simulation processor.

PIL Block

When you build a subsystem from a model for PIL, the process creates a PIL block optimized for PIL simulation. When you run the simulation, the PIL block acts as the interface between the model and the PIL application running on the processor. The PIL block inherits the signal names and shape from the source subsystem in your model, as shown in the following example. Inheritance is convenient for copying the PIL block into the model to replace the original subsystem for simulation.

PIL Issues and Limitations

Consider the following issues when you work with PIL blocks.

Constraints

When using PIL in your models, keep the following constraints in mind:

Models can have multiple PIL blocks for different subsystems. They cannot have more than one PIL block for the same subsystem. Including multiple PIL blocks for the same subsystem causes errors and inaccurate results.
A model can contain a single model block running PIL mode.
A model can contain a subsystem PIL block or a model block in PIL mode, but not both.

Generic PIL Issues

Refer to PIL Feature Support and Limitations for general information about using the PIL block with embedded link products.

With Texas Instruments CCS, PIL with DSP/BIOS Enabled Does Not Support System Stack Profiling

Enabling DSP/BIOS for Texas Instruments processors disables the stack profiling option. To use stack profiling with PIL, disable DSP/BIOS in the model Target Preferences block and rebuild your project.