Code Profiler Plugin for the MPLAB® X IDE

Last modified by Microchip on 2024/06/24 06:32

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:

void baseline(void)
    {
     return;
    }

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

Go to the DevelopeOpen the Development Tools Selector - DTS.r Tools Selector guide.
Open the Development Tools Selector - DTS.
Enter the Part Number in the Search Box

Development Tool Selector window

Select the "Emulators and Debuggers" tab

Development Tool Selector window

Look for the Words "Data capture: Enabled" under the REAL ICE™ section

MPLAB REAL ICE Probe Kit features

PIC16F1xxx, and PIC32MZ MCUs DO NOT support code profiling. The data capture capability reported for these devices by the Development Tool Selector is not compatible with the code profiling plugin.

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

shows where to find the trial version of the code profiling plugin

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

second step in find the trial version of code profiling

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:

Unzip the purchased ZIP file to two .nbm files on your hard drive.
Select Tools > Plugins from the IDE menu.
Select the Downloaded tab in the Plugins window.
Click the Add Plugins… button to add the two .nbm files, one by one.
Make sure the Install check boxes for both Code Profiling and Plugin Update Services plugins are checked.

Click the Install button and follow the instructions to finish the installation

Shows window to get the full version of the code profiling plugin

Back to top


Code Profiling Plug-in Setup

​Before a project's code is profiled, the REAL ICE in-circuit emulator settings need to be verified. Two settings are essential for code profiling to operate:

  1. Setting the MCU speed
  2. Enabling "Function Level Profiling" on REAL ICE In-circuit emulator.

Back to top

Setting the MCU Speed:

Open the Project Properties window (File > Project Properties).
Click on REAL ICE under Categories and select Clock from the Option categories drop-down box. Ensure this value matches the actual target speed as set by the configuration bits in code.

Click Apply.

Clock - Selection and Setup

​In some instances, the MCU will run at the speed set but the data transfer from the device may not 'keep up.' It is possible to experience periodic speed reductions or pauses in program operation while the target is running during a profile session.

Back to top

Enabling Function Level Profiling

From the Project Properties Window:

Click on REAL ICE under Categories and select Trace and Profiling from the Option categories drop-down box.
Under Data Collection Selection, select Function Level Profiling.
Select a .log file and a desired length for the file that logs the profiled data.

Check Include Time Stamp. Two files are produced:

  1. a file containing raw polling and time stamp data (the log file)
  2. a file containing information about the log file, i.e., how to interpret the log file's contents (the .INX file)

Click OK.

Function Level Profiling - Selection and Setup

Back to top


Starting the Code Profiler

To collect data and time stamp information for profiling:

Open the Code Profiling window in the integrated development environment (IDE) by selecting Tools > Embedded > CodeProfiling.
Begin a Debug Session  debug project button and run continue button the application.
Pause program execution (Pause pause button, or break point line button)
View the data in the Code Profiling window.

Note: Pre-compiled functions are not profiled. Only the C files that are compiled with the project generate the necessary instrumentation settings to enable profiling.

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

An example of the code profiling window

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.

diagram showing an example of 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.

shows an example of 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 Display Timeline Graph button.

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

example of graphic timeline

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 Measure Zoom button 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

IconTextDescription
Project Properties buttonProject PropertiesOpen the Project Properties window.
Filter Functions buttonFilter FunctionsFilter 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 buttonFilter Select AllSelect to display all functions.
Show Function Timeline Graph buttonShow Function
Timeline Graph
Display a graph of data in the window.
Save To File buttonOutput StatisticsOutput window data to a file.
Column Setup buttonColumn SetupClick 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

ItemDescription
Clear View and DataClear all function data from the window.
Reload DataReload function data from a file into the window.

Back to top

Code Profiling Graph Window

The Show Function Timeline Graph button 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

IconTextDescription
Icon-Measure-Zoom.gifMeasure/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

ItemDescription
Turn Off/On Zoom modeClick to disable Zoom mode.
Click again to enable Zoom mode.
Save graph imageSave an image of the graph to a PNG file.
PrintPrint the graph.
Zoom InZoom in on graph data. Choose to zoom in on:
- Both Axes
- Domain Axis (x coordinates)
- Range Axis (y coordinates)
Zoom OutZoom out on graph data. Choose to zoom in on:
- Both Axes
- Domain Axis (x coordinates)
- Range Axis (y coordinates)
Zoom ResetReset zoom to default level.
PropertiesOpen the Chart Properties window.

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

ItemDescription
Show titleCheck to show the graph title listed under Text.
Uncheck to hide the graph title.
TextEnter a title for the graph. Show Title must be checked.
FontSelect font options for the graph title text.
ColorSelect a color scheme for the graph title text.

Back to top

Plot Tab

ItemDescription
LabelEnter a label for the axis.
FontSelect font options for the label.
PaintSelect a color scheme for the label (text and background).
TicksCheck to show tick labels. Uncheck to hide.
Select font options for the tick labels.
Check to show tick marks. Uncheck to hide.
RangeCheck to auto-adjust range values.
Uncheck to enter a minimum range value and
a maximum range value.
TickUnitCheck for Auto-Selection of TickUnit.
Uncheck to enter TickUnit value.

Back to top

Appearance Tab

ItemDescription
Outline strokeSelect the thickness of the line around the graph.
Outline paintSelect the color of the line around the graph.
Background paintSelect the color of the graph background.
OrientationSelect an orientation for the graph domain cancel axis:
- Vertical (default)
- Horizontal

Back to top

Other Tab

ItemDescription
Draw anti-aliasedCheck to use anti-aliasing when drawing the graph.
Uncheck to turn anti-aliasing off.
Background paintSelect the color of the background outside of the graph.
Series painNot implemented.
Series strokeNot implemented.
Series outline paintNot implemented.
Series output strokeNot implemented.

Back to top