Difference between revisions of "Linux Tools Project/Valgrind/User Guide"

Revision as of 00:19, 19 May 2009

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.

Configuring a Profile Run

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

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.

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.

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.

Alternatively, you can also use the available export shortcut on the Valgrind view toolbar.

Using Memcheck

• Memcheck discovers memory management problems in your program. (http://www.valgrind.org/docs/manual/mc-manual.html)
• It is the default tool.
• Any memory management errors reported by Valgrind are listed in the Valgrind view, which should appear automatically.
  • Each error has a stack trace.
  • If the source can be resolved, double-clicking on the stack frame will open an editor to its line.
    
• View and modify your profile configuration by selecting "Profile Configurations".
  • All Valgrind related configuration options can be changed from the Valgrind Options tab.
    
  • General options and Suppressions are Valgrind core options and are not dependent on the tool being run.
  • Details on Memcheck suppressions can be found here.
  • Specific Memcheck options can also be configured.
    

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.
  
• 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 ) and have a function call trace corresponding to contribution heap allocations.
    • The peak snapshot is in bold text.
      
  • 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.
      
    • Toggle between the snapshot table and detailed snapshot tree with the "Show Heap Tree" 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.
        
• Similarly to Memcheck, there are Massif-specific options configurable in the Valgrind Options tab for your profile configurations.
  

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.
  
• 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.
    
• As with the other tools, there are specific Cachegrind options available from the Valgrind Options tab in your profile configuration.
  

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.
  
  • 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.
    
  • 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" dropdown in the Valgrind view's toolbar.
  • Cachegrind reports each PID separately as a top-level element in it's output tree.