Code Profiler Plugin for the MPLAB® X IDE

Overview

This plugin for MPLAB® X IDE works with the MPLAB REAL ICE™ In-Circuit Emulator to display time-stamped function profiling of running project code, enhancing the software debugging capabilities of MPLAB X IDE.

It is used to measure the percentage of time spent in each function in order to determine where your application may be spending the greatest portion of time over an average collected set of data. It adds pre- and post-amble code to all functions in debug sessions and is available for most devices having data capture. It aids in debugging and code optimization by tracking the number of function calls, parent functions, child functions and execution time. Each license is intended for one user.

The use of this plugin requires an MPLAB REAL ICE In-Circuit Emulator.

The Code Profiling plugin supports these device families:

• PIC18F with data capture
• PIC24F, PIC24EP
• dsPIC33FJ, dsPIC33E
• PIC32MX with data capture

To find out if your device has data capture, please see the online Development Tool Selector.

The Code Profiling plugin DOES NOT SUPPORT these device families:

• PIC16F1
• PIC32MZ

These devices use a different type of data capture not supported by the plugin.

Back to top

Code Profiling Capabilities and Limitations

The Code Profiling plugin displays:

• The number of calls to each function
• The percentage of time spent in each function
• The amount of time used by each function.

The percentage of time spent in each function and the number of calls to a function are reliably extracted. The user should not rely on the reported amount of time spent in each function as a definitive indicator of system performance. Code Profiling is a modestly "intrusive" process that prevents the precise timing information from being displayed. Code profiling's intrusion, however, can be measured and accounted for.

Code profiling is accomplished by "instrumenting" each function within the target code. This instrumentation process involves inserting a call at the beginning of each function that retrieves the PC and sends that data up through the debug tool to the IDE for time stamping and logging. Instrumentation also inserts a call at the end of each function that logs the corresponding function exit indicator. These calls add time to the function and may slow down system performance while profile data is being extracted. The amount of time added by these instrumentation calls depends upon the system clock speed, the MCU being used, and the compiler.

Back to top

Timing with a Baseline Function

To determine the instrumented call overhead for a particular MCU/compiler/clock-speed the user will need to create and profile a baseline function. The baseline function is a function with little or no function overhead. A typical baseline function could be:

When profiled, the measured execution time for a baseline function is the overhead for the instrumented calls for the current speed of MCU and compiler. By subtracting this number from time spent in each function the user will get a clearer view of the amount of time spent in each function.

Back to top

Caveats for Baseline Function Timing

If the application being tested uses clock-switching to alter the speed of the system clock during execution, care should be taken on relying on the baseline function as a true overhead indicator as some functions may operate at different clock frequencies.

If a function under consideration makes calls in turn to other sub-functions, the instrumented overhead for these sub-calls would not be included in a simple baseline extraction analysis. Further analysis would need to be performed.

Back to top

Requirements for Code Profiling

To perform code profiling you will need the following:

• MPLAB X IDE version 2.26 or higher with the Code Profiling plugin (SW100100) installed

• One of the following Microchip C compilers:
  • XC8   (v1.20 or higher)
  • XC16 (v1.20 or higher)
  • XC32 (v1.20 or higher)

• MPLAB^® REAL ICE™ in-circuit emulator

• One of the following PIC^® Microcontroller (MCU) family members:
  • PIC18F with Debug Data Capture
  • PIC24FJ
  • PIC24EP
  • dsPIC33FJ
  • dsPIC33E
  • PIC32MX with Debug Data Capture

Not all PIC^® MCUs can be profiled using the plugin. In order to work with the Code Profiling plugin the MCU must be able to allow the emulator to perform data capture during a debug session.

Back to top

Verifying Debug Data Capture capability on the PIC^® MCU

Back to top

Code Profiling Plug-in Installation

A trial version of the Code Profiling plugin can be installed from within MPLAB^®X IDE. The Code Profiling Trial Version is a full-featured, 30-day time-limited version of the plugin.

The full-featured version of the plugin is available from Microchip Direct.

It is not necessary to install the trial version in order to get the full-featured version. The full-featured plugin can be downloaded and installed without previously installing a trial version.

Back to top

Installing the Trial Version  the Code Profiling Plugin

To begin the installation process, from the IDE window go to the Plugins menu under Tools

From the Available Plugins tab select Code Profiling (Trial Version), then select Install.

The Plug-in installer will launch the process in which the user will be asked to accept the license terms for the plugin. The installer will then download the most recent version of the plugin for installation.

At the end of the plugin installation process, the installer will prompt the user to restart MPLAB X IDE to make code profiling available.

Back to top

Obtaining and Installing the full-featured Code Profiling Plugin

The Code Profiling Plugin (SW100100) is available on the "MPLAB® Xpress Cloud-Based IDE" page.
The plugin is delivered as two separately zipped .nbm files. Both of these files must be unzipped and installed for the plugin to operate.

To install:

Back to top

Code Profiling Plug-in Setup

Back to top

Setting the MCU Speed:

Back to top

Enabling Function Level Profiling

From the Project Properties Window:

Back to top

Starting the Code Profiler

To collect data and time stamp information for profiling:

Begin a Debug Session   and run  the application.

Pause program execution (Pause , or break point )

Back to top

Code Profiling Window

The Code Profiling window displays function-level instrumentation counts, with timing, for each function entry and return during a sampled interval.

At the top of the Code Profiling window are totals:

• Time Stamps - Count of every function entry and return sampled during execution
• Calls - Count of every function entry sampled during execution
• Time - Duration of sampling (mS)

The data in the Function Time tab shows three sets of data for each function:

• Calls to Function
• Excluded Times
• Included Times

Back to top

Calls to Function

There are two columns in the Calls to Functions data set (shown in pink in the Code Profiling window).

The Calls column displays the number of times the function in the Function column was called during execution.

The Percentage column shows the percentage of the total functions calls were made to the function named in the Function column.

Back to top

Excluded Times

There are four columns in the Excluded Times data set (shown in green in the Code Profiling window).

The Excluded (mS) is the time spent in the function listed in the Function column, excluding the time used by the functions called by the named function.

Example of Excluded Time

If Function F1 calls Function F2 which in turn calls Function F3 the figure below shows the excluded time.

The “Avg (mS)” column displays the average excluded time for each call to the function.

The “Min-Max (mS)” column shows the slowest and fastest excluded times for the function.

The "Percentage” column shows the percent of the total excluded profile time used by each function time.

Back to top

Included Times

There are four columns in "Included Times" data set (shown in blue in the Code Profiling window).

The “Included (mS)” column is the time spent in the function listed in the “Function” column including the time spent by functions called.

Example of Included Time
If Functions F1 calls Function F2 which in turn calls Function F3 the figure below would represent the Included Time.

The Avg (mS) column displays the average duration of the included function times.

The Min-Max (mS) column shows the shortest and longest included amount of included time for each function.

The Percentage column display the percent of the total included profile time represented by each function time.

Back to top

Graphing Profile Data

To display the Code Profiling data click on the Display Timeline Graph button .

The Code Profiling Graph Window will appear displaying the time spent in each function for the entire simulation period.

The X-axis Time (mS) shows the profile time (in milliseconds) for the entire sample session

The Y-axis - Duration ms shows the time spent in each instance of a function call. The functions are color coded in the graph with the legend at the bottom of the graph

Back to top

Panning

To move left and right through the data on the Time axis, use:

• The Pan Graph slider
• <Ctrl> + click on mouse (on Windows and Linux OS systems)
• <Apple> + click on the mouse (on Mac OS systems)

Back to top

Zooming

Ensure the magnifying glass icon  is selected:

• Click and drag with your mouse to zoom in.
• Right click on the graph, click on Zoom In or Zoom Out, and select an axes on which to zoom.
• Use the mouse wheel to zoom on the Time axis and <Ctrl> + mouse wheel to zoom on the Duration axis.

Reset the Zoom by clicking Reset Zoom.

Back to top

Data Point Values

The graph allows the user the ability to specific time intervals manually. To do this first ensure magnifying glass icon is NOT selected then click and drag with the mouse to measure a time interval.

Back to top

Code Profiling Controls

The Code Profiling Plugin has control icons and associated windows to assist in data display and analysis.

• Code Profiling Window
• Code Profiling Graph Window
• Chart Properties Window

Back to top

Code Profiling Window Controls

The Code Profiling window opens up next to the Output tab in the IDE when the plugin is run. It has several control icons, all but one of the icons is on the left side of the window. The Column Setup icon is on the right side of the window.

Back to top

Code Profiling Window Icons

Icon	Text	Description
	Project Properties	Open the Project Properties window.
	Filter Functions	Filter the display to show only the selected functions. Note: Code is not run again, the data already collected is reduced to remove all non-selected functions.
	Filter Select All	Select to display all functions.
	Show Function Timeline Graph	Display a graph of data in the window.
	Output Statistics	Output window data to a file.
	Column Setup	Click to display a menu for selecting which columns to show or hide. Also, show or hide horizontal scroll or pack columns (all or selected).

The Code Profiling window has a context menu. The context menu items may be accessed by right-clicking anywhere in the Code Profile window.

Back to top

Code Profiling Window Context Menu

Back to top

Code Profiling Graph Window

The Show Function Timeline Graph button  can be found on the left side of the Code Profile window. Clicking on this icon opens up a graph of the simulation timeline.

Code Profiling Graph Window Icons

Icon	Text	Description
	Measure/Zoom mode select	Icon unselected: Measurement mode. Drag mouse to measure time value. Icon selected: Zoom mode. Drag mouse to zoom in on an area.

The Code Profiling Graph window has a context menu. To access the context menu, right-click anywhere inside the Graph window.

Back to top

Code Profiling Graph Window Context Menu

When Properties is selected from the Graph window, the properties window appears. This window has four tabs: Tile, Plot, Appearance, and Other. The table below shows the functions found under these tabs.

Back to top

Chart Properties Window

Set up the graph look and feel on the tabs of this window.

Back to top

Title Tab

Back to top

Plot Tab

Back to top

Appearance Tab

Item	Description
Outline stroke	Select the thickness of the line around the graph.
Outline paint	Select the color of the line around the graph.
Background paint	Select the color of the graph background.
Orientation	Select an orientation for the graph domain  axis: - Vertical (default) - Horizontal

Back to top

Other Tab

Back to top