Linux Tools Project/Profiling/User Guide

Overview

The Linux Tools project provides Eclipse interfaces to a number of system tools sufficient to profile a C/C++ application. For example, the Valgrind plug-in provides the ability to profile an application's memory usage while the Perf plug-in allows an end-user to acquire details regarding the amount of time taken in various functions or methods. From the user point-of-view, the user wants to profile a C/C++ executable and this is available via the Profile as.. right-click context menu or via the Profile Configurations... dialog or via the Profile button found next to the Debug and Run buttons at the top of the Eclipse Window.

Support exists for:

• Valgrind (memcheck, massif, cachegrind, and helgrind sub-tools)
• OProfile
• Perf
• SystemTap (using a systemtap script to get call-graph)
• Gcov (code coverage)
• GProf

Profiling Categories

In the past, some of the Linux Tools profiling plug-ins, such as Valgrind, would add a default launch short-cut. The launch short-cut would use a set of default parameters for the profiling tool and would launch the selected executable appropriately. In the case of Valgrind, which supports multiple tools, the short-cut would default one particular tool to use (in Valgrind's case, this is the memcheck tool which checks for memory leaks). In the Eclipse Debug Launch framework, each launch short-cut can specify which mode or modes it applies to (run, debug, and profile). For those short-cuts that specify the profile mode, this results in an added menu entry under the Profile as... context menu. For example, there are short-cuts for Perf, OProfile, and Valgrind which show up as Profile With Perf, Profile With OProfile, and Profile With Valgrind, respectively.

This can be confusing to end-users who are not familiar with the various tools that are out there and what they can do. For example, both OProfile and Perf provide timing results for an application so there is overlap of functionality within the various tools. To alleviate this, the current profiling tools have been grouped into task categories. By default, there are three initial categories:

• Timing - this measure the amount of time taken in functions and methods
  • includes Linux Tools Perf, OProfile, Callgraph (via SystemTap), and Gprof
• Memory - this profiles heap/stack/cache usage for an application
  • includes Linux Tools Memcheck, Massif, Cachegrind, and Helgrind tools from Valgrind
• Coverage - this measures how much of the code gets exercised in a run
  • includes Gcov

For details on using the tools mentioned above, see the appropriate User's Guide for the tool installed from the Linux Tools update site.

The Profiling Category framework is extensible and additional tools such as third-party profiling tools can be added to any of the basic three categories or a new category can be created if needed (e.g. other).

Each category contributes a launch short-cut which results in a menu item under the Profile as... context menu so that an end-user may select to get a timing profile or profile memory usage for a given C/C++ executable. To determine which profiling tool is used from a category short-cut, each tool in a category gives itself a priority so that when multiple tools are installed from the same category, the one with the highest priority becomes the initial default. For example, the Perf tool has the highest priority of the profile timing category tools and so becomes the initial default, if installed. Valgrind memcheck has the highest priority for profiling memory and Gcov is the default for profiling code coverage (at present the only tool in the category).

The default for any category can be directly set/modified by the end-user via Window -> Preferences -> C/C++ -> Profiling Categories. Each category of installed tools using the framework will present a sub-page beneath the top-level Profiling Categories page. The preferences page for each category will display a radio button to represent each tool that is installed that belongs to that particular profiling category. If no tools are installed for a given category, no preferences page is displayed. If the user has not set a preferred tool for a category, the priority of each installed tool will determine the default choice. For example, Perf, if installed, is the highest priority Timing Category profile tool from Linux Tools.

The following shows the Profiling Categories preference for the Timing Category whereby the Linux Tools Perf, OProfile, and Callgraph plug-ins are installed. Note the Perf tool being the default:

Also note that there is additional information presented as to how the tool functions (e.g. Function Timing vs Hardware Events Timing) and that there are special usage notes via tooltips (e.g. see diagram for notes on using gprof).

For projects that want to set a different category default than the workspace, the same settings are available via the Project Properties page. Like the preferences pages, tooltip information is provided. The Profiling Categories property settings can be found under Project -> Properties -> C/C++ General. Each category allows the end-user to specify project-specific settings or to default to use the workspace preferences instead. In the case where project-specific settings are not enabled, the selection of a profiling tool is disabled. The page also includes a link to the associated workspace Profiling Category preferences for that category should the end-user wish to set them that way or verify what is currently in place. When project-specific settings are chosen, they will override the workspace preferences for that particular category when profiling within that project.

Profiling Configurations

As mentioned, each short-cut creates a menu item under the Profile as... context menu (e.g. right-click on a C/C++ executable). In addition to the short-cuts for each category, the end-user may select Profile Configurations...

This brings up a dialog that allows the user to modify current launch configurations or to create new ones:

The following tabs are provided in all Linux Tools profiling configurations:

• Main
  • This tab allows one to set the C/C++ executable and Eclipse project.
• Arguments
  • This tab sets the arguments to pass to the C/C++ program when profiling it.
• Environment
  • This tab sets any environment variables to set when running the program and profiling. You can choose to override the current environment or to replace it entirely.
• Source
  • This tab sets the source lookup path which may be used by the Linux Tools Profiling plug-ins to open source code via the UI.
• Common
  • This tab allows one to specify how the configuration gets stored, mark it as a favorite Profiling configuration, and to set up a console in the case where C/C++ standard input/output is used.

With all short-cuts, a set of default parameters are set up for you such as: the executable will be the one you right-clicked on and the project will be set to its project automatically. If you wish to create a new configuration from scratch, simply select the type of profiling launch configuration you wish to create by clicking in the left-hand tree view and then push the icon found in the top left corner. This will create a new configuration with some defaults, but some options may require setting manually (e.g. the executable and the project).

In addition to the common tabs, each category contributes a tab for its own settings. For example, for Profile Memory, there is a Memory tab added:

The category tab will have the name of the category (i.e. in this case Memory) and will have a drop-down at the top which allows you to specify which tool to use. By default, it will have the current tool selected in the Profiling Category preferences page for the category or the initial default. You may override this for the configuration simply by opening the drop-down box and choosing another tool (if one is installed for that category).

Below that, note there is another set of tabs. These tabs are specific to setting options for the profiling tool chosen at the top. For details on what the options mean, see the appropriate User's Guide for the plug-in supplying the tool for profiling (e.g. in the Memory tab above, this would be the Valgrind tool's User's Guide).

When you choose a short-cut from the Profile as... context menu (e.g. Profile Memory), a launch configuration will be created for you, if one does not currently exist for the C/C++ executable that is chosen. If there are multiple configurations that point to the same executable (obviously with different configuration names), a dialog will be offered to you to select which profile you wish to use.

In the case where a launch configuration already exists for the C/C++ executable but it specifies a different default tool to use than the current one set in the Profiling Category preferences page, a new configuration will also be created. Thus, if you had a single launch configuration already, there will now be two configurations and this will trigger the multiple configuration selection dialog. Unique names for new configurations are created from old ones, adding a numeric value (e.g. (2) ). You are free to rename any configuration to make it easier for choosing via the Profiling Configurations dialog.