Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Linux Tools Project/Valgrind/User Guide

< Linux Tools Project
Revision as of 22:54, 21 May 2009 by Unnamed Poltroon (Talk) (Exporting Valgrind Data)

Overview

Valgrind is an instrumentation framework for building dynamic analysis tools used to profile applications in detail. Valgrind tools are generally used to automatically detect many memory management and threading problems. The Valgrind suite also includes tools that allow you to build new profiling tools to suit your profiling needs.

The Valgrind plug-in for Eclipse (documented herein) integrates several Valgrind tools into Eclipse. This allows Eclipse users to seamlessly include profiling capabilities into their workflow. At present, the Valgrind plug-in for Eclipse supports three Valgrind tools: Memcheck, Massif, and Cachegrind.

For more information about Valgrind, refer to http://www.valgrind.org/.

Installing

In order for the Valgrind plug-in for Eclipse to work properly, you should have the valgrind-3.3.0 (or later) package installed on your system first.

Once the valgrind package is installed, the easiest way to install the Valgrind plug-in for Eclipse is through the Software Updates and Add-ons menu. For information on how to use this menu, refer to [this link].

General Usage

You can use the Valgrind plug-in's "one-click launch" shortcut to run a default profile. Doing so is similar to running valgrind ./program_name from the command line. To use the one-click launch shortcut, right-click on the project or binary name in the Project Explorer window and navigate to Profile As > Profile With Valgrind. If a source file belonging to that program is available on any open editor, you can also right-click inside the editor to navigate to the one-click launch.
Shortcut.png

Configuring a Profile Run

To configure a Valgrind profile run, navigate to Profile As > Profile Configurations to access the Profile Configurations menu.
Screenshot-ProfileConfigurations.png

The Profile Configurations menu allows you to configure a profile run with some basic Valgrind profiling options, along with the most useful options for each Valgrind tool. These settings can be configured in the Valgrind Options tab of a specific profile run.
Screenshot-ProfileConfigurations-valgrind-options-tab.png

General Options

The General Options tab allows you to configure the following options:

  • Tool to run allows you to choose between Memcheck, Massif, and Cachegrind in your profile run. By default, using the one-click shortcut will run the Memcheck tool.
  • Trace children on exec configures whether or not to trace into sub-processes initiated via the exec system call. This is identical to using the --trace-children= option. This is disabled by default.
  • Run __libc_freeres on exit configures whether or not to run a __libc_freeres routine after the profile run exits. This routine instructs glibc to release all memory it has allocated, and is similar to using the --run-libc-freeres= option. This is enabled by default.
  • Child silent after fork is enabled by default, and in most cases cannot be configured. This option disables any debugging or logging output from child processes created from a fork call.
  • Demangle C++ names allows Valgrind to translate encoded C++ names ("mangled" by g++ during compilation) back to something similar to their original form. This is enabled by default.
  • Limit errors reported instructs Valgrind to stop reporting errors after a total of 10,000,000 actual errors or 1,000 unique errors have been detected. This is enabled by default.
  • Callers in stack trace configures how many levels of function call names Valgrind should use to identify program locations. By default, Valgrind uses 12 levels.
  • Show errors below main configures stack traces for errors should show any functions that appear beneath main(). This is disabled by default.
  • Max stack frame size is the maximum size of a stack frame, and is set to 2000000 by default.

For more information about these options, refer to man valgrind.

Suppressions

You can also configure your profile run to use a suppressions file (similar to the --suppressions= option. To do this, click the Suppressions tab.
Screenshot-Suppressions.png

The Workspace button allows you to select a resource from the workspace as your suppressions file. To use a suppressions file outisde of the workspace, use the File System button.

Exporting Valgrind Data

To export the raw data collected during a Valgrind profile run, use the Export wizard menu. To access the Export wizard menu, navigate to File > Export and select Valgrind Log Files under the category Other.


ValgrindExportWizard.png

Alternatively, you can also use the available export shortcut ( Exportbuttonvalgrindview.png ) on the Valgrind view toolbar.

Using Memcheck

Memcheck is the default tool used by Valgrind and the Valgrind plug-in for Eclipse. It allows you to detect memory-related problems such as memory leaks, use of uninitialized memory, and reads from/writes to inappropriate stack areas. For more information about Memcheck, refer to http://www.valgrind.org/docs/manual/mc-manual.html.

Any memory management errors detected by Memcheck are displayed in the Valgrind view, which appears automatically after a profile run. Each displayed error can be expanded in the Valgrind view to display its stack trace.


MemcheckOutput.png

In some cases, Memcheck can determine which section of the source code causes a reported error. Whenever this is the case, double-clicking on the stack trace of the reported error will open the related source file and place the insertion point on the line responsible for the error.

Configuring a Memcheck Profile Run

To configure a Memcheck profile run, navigate to Profile As > Profile Configurations to access the Profile Configurations menu. In the Valgrind Options tab, navigate further to the Memcheck Options.
MemcheckOptions.png

The Memcheck Options tab allows you to configure the following Memcheck options:

  • leak resolution sets how tolerant Memcheck should be in considering different stack traces to be the same. The default setting is "low", which means only the first two entries need to match. The "med" setting requires four entries to declare a match. The "high" setting requires all entries to declare match.
  • freelist size (blocks) is identical to the Memcheck option --freelist-vol=, which specifies the maximum total size (in bytes) of memory blocks to be marked "inaccessible" once they have been freed using free (as in C) or delete (as in C++). The default value for freelist size (blocks) is 10000000.
  • minimum heap block alignment is identical to the Memcheck option --alignment=, which specifies the minimum alignment/size of heap blocks. The default value for this option is 8.
  • show reachable blocks configures whether or not Memcheck should report blocks it could not find a pointer to during leak detection. This is disabled by default (i.e. do not report blocks with undetermined pointers).
  • undef value errors configures whether or not Memcheck should detect dangerous uses of undefined value errors. This is enabled by default.
  • allow partial loads is identical to the Memcheck option --partial-loads-ok=, which controls how Memcheck handles word-sized, word-aligned loads from addresses from which bytes are addressable and others are not. This is disabled by default (i.e. treat loads from partially invalid and completely invalid addresses as the same).
  • gcc 2.96 workarounds is identical to the Memcheck option --workaround-gcc296-bugs, which controls whether Memcheck should assume that small reads/writes below the stack pointer are due to bugs in gcc-2.96. This option is disabled by default (i.e. do not assume them to be reslting from gcc-2.96 bugs; report such reads/writes as errors).

Refer to http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles for information about Memcheck suppression files. For more information about each Memcheck option in the Valgrind plug-in for Eclipse, refer to man valgrind.

Using Massif

  • Massif is heap profiling tool that details memory usage throughout your program's execution. (http://www.valgrind.org/docs/manual/ms-manual.html)
  • To use Massif, you need to switch the tool in your profile configuration.
    SwitchMassif.png
  • Massif has a lot of output to distil. There are 3 ways to view the data.
  • Massif outputs statistics for each unit of time (default: instructions) in the application. These are called "snapshots" of your program.
    • The Valgrind view initially displays each snapshot in a table showing heap allocation statistics.
      • Some snapshots are detailed (denoted by Hierarchy.gif) and have a function call trace corresponding to contribution heap allocations.
      • The peak snapshot is in bold text.
        MassifTable.png
    • Detailed snapshots can be inspected by double-clicking on them in the snapshot table.
      • Each detailed snapshot is shown in a tree structure that forms a hierarchy of function calls accounting for that snapshot's allocations.
      • Double clicking on any function with a source file listed will attempt to open an editor to it.
        MassifTree.png
      • Toggle between the snapshot table and detailed snapshot tree with the "Show Heap Tree" Hierarchy.gif button in the view's toolbar.
    • The data presented in the snapshot table is also shown in line chart form.
      • Clicking on any data point selects it in the snapshot table.
      • Double-clicking on any data point that corresponds to a detailed snapshot will open an editor to one of its function calls.
        • The top-most function calls in the trace that contain source files are presented as choices if more than one exists.
          MassifChartSelect.png
  • Similarly to Memcheck, there are Massif-specific options configurable in the Valgrind Options tab for your profile configurations.
    MassifOptions.png

Using Cachegrind

  • Cachegrind performs cache and branching profiling. It can measure the number of cache misses and branch mispredictions your program performs. (http://www.valgrind.org/docs/manual/cg-manual.html)
  • To use Cachegrind, you need to switch the tool in your profile configuration.
    SwitchCachegrind.png
  • In the Valgrind view, Cachegrind's cache/branch data is shown in various levels of granularity.
    • A total is shown for each process and then you can navigate through each file, function and line.
    • Double-clicking on any file, function or line will open an editor to it, if the source can be resolved.
      CachegrindOutput.png
  • As with the other tools, there are specific Cachegrind options available from the Valgrind Options tab in your profile configuration.
    CachegrindOptions.png

Special Cases

  • In the event of an error in your program or with the options supplied to Valgrind, they will be reported in the Core Messages pane of the Valgrind view.
    ValgrindSegfault.png
    • This is where Memcheck does all of its reporting.
    • For other tools, it is possible to switch between this pane and the tool's output in the view's menu.
      SwitchCoreTool.png
    • If your program does encounter some problem, any data collected by Valgrind is still reported.
  • Profiling child processes is available in all tools and enabled by selected "Trace children on exec" in the profile configuration.
    • Memcheck handles this transparently and lists the process ID (PID) for each error it reports.
    • Massif presents each process separately and allows you to switch between them with the "Select Process ID" Thread.gif dropdown in the Valgrind view's toolbar.
    • Cachegrind reports each PID separately as a top-level element in it's output tree.

Back to the top