Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorElliott Baron2009-06-26 21:24:33 +0000
committerElliott Baron2009-06-26 21:24:33 +0000
commit5e27b8372a723d68b823df3660900827bae89f49 (patch)
treebb8b57a138979ca428552ca22d7bb519fea6110e /valgrind
parent878227c06864516204067adfd54971104bf63b7f (diff)
downloadorg.eclipse.linuxtools-5e27b8372a723d68b823df3660900827bae89f49.tar.gz
org.eclipse.linuxtools-5e27b8372a723d68b823df3660900827bae89f49.tar.xz
org.eclipse.linuxtools-5e27b8372a723d68b823df3660900827bae89f49.zip
Added Valgrind doc to feature, map file and psf.
Diffstat (limited to 'valgrind')
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind-feature/ChangeLog4
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind-feature/feature.xml12
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/ChangeLog14
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Updating-This-Document.html8
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Using-Cachegrind.html2
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference-toc.xml36
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.html493
-rw-r--r--valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.xml1168
8 files changed, 645 insertions, 1092 deletions
diff --git a/valgrind/org.eclipse.linuxtools.valgrind-feature/ChangeLog b/valgrind/org.eclipse.linuxtools.valgrind-feature/ChangeLog
index 817bb15864..9e4357a144 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind-feature/ChangeLog
+++ b/valgrind/org.eclipse.linuxtools.valgrind-feature/ChangeLog
@@ -1,3 +1,7 @@
+2009-06-26 Elliott Baron <ebaron@redhat.com>
+
+ * feature.xml: Added doc plugin. Recomputed dependencies.
+
2009-06-04 Elliott Baron <ebaron@redhat.com>
* feature.xml: Removing birt.chart from deps.
diff --git a/valgrind/org.eclipse.linuxtools.valgrind-feature/feature.xml b/valgrind/org.eclipse.linuxtools.valgrind-feature/feature.xml
index b053512565..779a6150e4 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind-feature/feature.xml
+++ b/valgrind/org.eclipse.linuxtools.valgrind-feature/feature.xml
@@ -32,6 +32,7 @@
<import plugin="org.eclipse.core.variables"/>
<import plugin="org.eclipse.debug.ui"/>
<import plugin="org.eclipse.linuxtools.profiling.launch"/>
+ <import plugin="org.eclipse.ui.console"/>
<import plugin="org.eclipse.ui.ide"/>
<import plugin="org.eclipse.birt.chart.device.swt" version="2.3.1" match="greaterOrEqual"/>
<import plugin="org.eclipse.birt.chart.device.extension" version="2.3.1" match="greaterOrEqual"/>
@@ -46,8 +47,10 @@
<import plugin="org.mozilla.rhino"/>
<import plugin="org.eclipse.core.filesystem"/>
<import plugin="org.eclipse.ui.editors"/>
- <import plugin="org.eclipse.ui.console"/>
<import feature="org.eclipse.linuxtools.profiling" version="0.2.0" match="greaterOrEqual"/>
+ <import plugin="org.eclipse.core.expressions"/>
+ <import plugin="org.eclipse.birt.chart.device.svg" version="2.3.1" match="greaterOrEqual"/>
+ <import plugin="org.eclipse.cdt.ui"/>
</requires>
<plugin
@@ -92,4 +95,11 @@
version="0.0.0"
unpack="false"/>
+ <plugin
+ id="org.eclipse.linuxtools.valgrind.doc"
+ download-size="0"
+ install-size="0"
+ version="0.0.0"
+ unpack="false"/>
+
</feature>
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/ChangeLog b/valgrind/org.eclipse.linuxtools.valgrind.doc/ChangeLog
index 5d1f9bf0a0..02c508f727 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/ChangeLog
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/ChangeLog
@@ -1,3 +1,17 @@
+2009-06-26 Elliott Baron <ebaron@redhat.com>
+
+ * userguide/General-Usage.html: New file.
+ * userguide/images/Exportbuttonvalgrindview.gif: New file.
+ * userguide/Installing.html: New file.
+ * userguide/Special-Cases.html: New file.
+ * userguide/Using-Cachegrind.html: New file.
+ * userguide/Using-Massif.html: New file.
+ * userguide/Using-Memcheck.html: New file.
+ * userguide/Updating-This-Document.html: Regenerated documentation.
+ * userguide/Valgrind\ Reference-toc.xml: Likewise.
+ * userguide/Valgrind\ Reference.html: Likewise.
+ * userguide/Valgrind\ Reference.xml: Likewise.
+
2009-06-18 Elliott Baron <ebaron@redhat.com>
* build-helper.xml: Added call to wikitext-to-docbook target.
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Updating-This-Document.html b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Updating-This-Document.html
index 869fd4453b..e72d76a724 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Updating-This-Document.html
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Updating-This-Document.html
@@ -12,7 +12,7 @@
</tr>
<tr>
<td style="width: 20%" align="left">
- <a href="Valgrind Reference.html" title="Overview">
+ <a href="Special-Cases.html" title="Special Cases">
<img alt="Previous" border="0" src="images/images/prev.gif"/>
</a>
</td>
@@ -20,7 +20,7 @@
<td style="width: 20%" align="right"></td>
</tr>
<tr>
- <td style="width: 20%" align="left" valign="top">Overview</td>
+ <td style="width: 20%" align="left" valign="top">Special Cases</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top"></td>
</tr>
@@ -33,7 +33,7 @@
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<td style="width: 20%" align="left">
- <a href="Valgrind Reference.html" title="Overview">
+ <a href="Special-Cases.html" title="Special Cases">
<img alt="Previous" border="0" src="images/images/prev.gif"/>
</a>
</td>
@@ -45,7 +45,7 @@
<td style="width: 20%" align="right"></td>
</tr>
<tr>
- <td style="width: 20%" align="left" valign="top">Overview</td>
+ <td style="width: 20%" align="left" valign="top">Special Cases</td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right" valign="top"></td>
</tr>
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Using-Cachegrind.html b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Using-Cachegrind.html
index 2c1a9820e0..55ba720cc4 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Using-Cachegrind.html
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Using-Cachegrind.html
@@ -52,7 +52,7 @@
<img border="0" src="images/SwitchCachegrind.png"/>
</p>
<h2 id="Analyzing_Cachegrind_Profile_Results">Analyzing Cachegrind Profile Results</h2>
- <p>The results of a Cachegrind profile run are displayed in the Valgrind view. These results show Cachegrind's cache/branch data in different levels of granularity. Double-clicking on any file, function, or line will open the corresponding source file and place the cursor on the appropriate location (if the source can be resolved).</p>
+ <p>The results of a Cachegrind profile run are displayed in the Valgrind view. These results show Cachegrind's cache/branch data in different levels of granularity. Double-clicking on any file, function, or line will open the corresponding source file and place the insertion point on the appropriate function (if such a link can be resolved).</p>
<p>
<br/>
<img border="0" src="images/CachegrindOutput.png"/>
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference-toc.xml b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference-toc.xml
index 86b46266e7..9b81567de9 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference-toc.xml
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference-toc.xml
@@ -1,29 +1,29 @@
<?xml version='1.0' encoding='utf-8' ?>
<toc topic="userguide/Valgrind Reference.html" label="Valgrind Reference">
<topic href="userguide/Valgrind Reference.html" label="Overview"></topic>
- <topic href="userguide/Valgrind Reference.html#Installing" label="Installing"></topic>
- <topic href="userguide/Valgrind Reference.html#General_Usage" label="General Usage">
- <topic href="userguide/Valgrind Reference.html#Configuring_a_Profile_Run" label="Configuring a Profile Run">
- <topic href="userguide/Valgrind Reference.html#General_Options" label="General Options"></topic>
- <topic href="userguide/Valgrind Reference.html#Suppressions" label="Suppressions"></topic>
+ <topic href="userguide/Installing.html" label="Installing"></topic>
+ <topic href="userguide/General-Usage.html" label="General Usage">
+ <topic href="userguide/General-Usage.html#Configuring_a_Profile_Run" label="Configuring a Profile Run">
+ <topic href="userguide/General-Usage.html#General_Options" label="General Options"></topic>
+ <topic href="userguide/General-Usage.html#Suppressions" label="Suppressions"></topic>
</topic>
- <topic href="userguide/Valgrind Reference.html#Exporting_Valgrind_Data" label="Exporting Valgrind Data"></topic>
+ <topic href="userguide/General-Usage.html#Exporting_Valgrind_Data" label="Exporting Valgrind Data"></topic>
</topic>
- <topic href="userguide/Valgrind Reference.html#Using_Memcheck" label="Using Memcheck">
- <topic href="userguide/Valgrind Reference.html#Analyzing_Memcheck_Profile_Results" label="Analyzing Memcheck Profile Results"></topic>
- <topic href="userguide/Valgrind Reference.html#Configuring_a_Memcheck_Profile_Run" label="Configuring a Memcheck Profile Run"></topic>
+ <topic href="userguide/Using-Memcheck.html" label="Using Memcheck">
+ <topic href="userguide/Using-Memcheck.html#Analyzing_Memcheck_Profile_Results" label="Analyzing Memcheck Profile Results"></topic>
+ <topic href="userguide/Using-Memcheck.html#Configuring_a_Memcheck_Profile_Run" label="Configuring a Memcheck Profile Run"></topic>
</topic>
- <topic href="userguide/Valgrind Reference.html#Using_Massif" label="Using Massif">
- <topic href="userguide/Valgrind Reference.html#Analyzing_Massif_Profile_Results" label="Analyzing Massif Profile Results"></topic>
- <topic href="userguide/Valgrind Reference.html#Configuring_a_Massif_Profile_Run" label="Configuring a Massif Profile Run"></topic>
+ <topic href="userguide/Using-Massif.html" label="Using Massif">
+ <topic href="userguide/Using-Massif.html#Analyzing_Massif_Profile_Results" label="Analyzing Massif Profile Results"></topic>
+ <topic href="userguide/Using-Massif.html#Configuring_a_Massif_Profile_Run" label="Configuring a Massif Profile Run"></topic>
</topic>
- <topic href="userguide/Valgrind Reference.html#Using_Cachegrind" label="Using Cachegrind">
- <topic href="userguide/Valgrind Reference.html#Analyzing_Cachegrind_Profile_Results" label="Analyzing Cachegrind Profile Results"></topic>
- <topic href="userguide/Valgrind Reference.html#Configuring_a_Cachegrind_Profile_Run" label="Configuring a Cachegrind Profile Run"></topic>
+ <topic href="userguide/Using-Cachegrind.html" label="Using Cachegrind">
+ <topic href="userguide/Using-Cachegrind.html#Analyzing_Cachegrind_Profile_Results" label="Analyzing Cachegrind Profile Results"></topic>
+ <topic href="userguide/Using-Cachegrind.html#Configuring_a_Cachegrind_Profile_Run" label="Configuring a Cachegrind Profile Run"></topic>
</topic>
- <topic href="userguide/Valgrind Reference.html#Special_Cases" label="Special Cases">
- <topic href="userguide/Valgrind Reference.html#Encountering_Errors" label="Encountering Errors"></topic>
- <topic href="userguide/Valgrind Reference.html#Profiling_Child_Processes" label="Profiling Child Processes"></topic>
+ <topic href="userguide/Special-Cases.html" label="Special Cases">
+ <topic href="userguide/Special-Cases.html#Encountering_Errors" label="Encountering Errors"></topic>
+ <topic href="userguide/Special-Cases.html#Profiling_Child_Processes" label="Profiling Child Processes"></topic>
</topic>
<topic href="userguide/Updating-This-Document.html" label="Updating This Document"></topic>
</toc> \ No newline at end of file
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.html b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.html
index 9966a84ad6..6d06003370 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.html
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.html
@@ -14,7 +14,7 @@
<td style="width: 20%" align="left"></td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right">
- <a href="Updating-This-Document.html" title="Updating This Document">
+ <a href="Installing.html" title="Installing">
<img alt="Next" border="0" src="images/images/next.gif"/>
</a>
</td>
@@ -22,500 +22,27 @@
<tr>
<td style="width: 20%" align="left" valign="top"></td>
<td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Updating This Document</td>
+ <td style="width: 20%" align="right" valign="top">Installing</td>
</tr>
</table><hr/>
- <h2 id="Overview">Overview</h2>
+ <h1 id="Overview">Overview</h1>
<p>
- <b>Valgrind</b> 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.
+ <b>Valgrind</b> is an instrumentation framework for building dynamic analysis tools that can be 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 needs.
</p>
<p>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:
- <a href="Valgrind%20Reference.html#Using_Memcheck">Memcheck</a>,
- <a href="Valgrind%20Reference.html#Using_Massif">Massif</a>, and
- <a href="Valgrind%20Reference.html#Using_Cachegrind">Cachegrind</a>.
+ <a href="Using-Memcheck.html#Using_Memcheck">Memcheck</a>,
+ <a href="Using-Massif.html#Using_Massif">Massif</a>, and
+ <a href="Using-Cachegrind.html#Using_Cachegrind">Cachegrind</a>.
</p>
<p>For more information about Valgrind, refer to
<a href="http://www.valgrind.org/">http://www.valgrind.org/</a>.
- </p>
- <h2 id="Installing">Installing</h2>
- <p>In order for the Valgrind plug-in for Eclipse to work properly, you should have the
- <i>valgrind-3.3.0</i> (or later) package installed on your system first.
- </p>
- <p>Once the
- <i>valgrind</i> package is installed, the easiest way to install the Valgrind plug-in for Eclipse is through the
- <b>
- <i>Software Updates and Add-ons</i>
- </b> menu. For information on how to use this menu, refer to
- <a href="http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site">this link</a>.
- </p>
- <h2 id="General_Usage">General Usage</h2>
- <p>You can use the Valgrind plug-in's "one-click launch" shortcut to run a default profile. Doing so is similar to running <code>valgrind ./<i>program_name</i></code> from the command line. To use the one-click launch shortcut, right-click on the
- <i>project</i> or
- <i>binary</i> name in the
- <b>
- <i>Project Explorer</i>
- </b> window and navigate to <u>Profile As</u> > <u>Profile With Valgrind</u>. 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.
-
- <br/>
- <img border="0" src="images/Shortcut.png"/>
- </p>
- <h3 id="Configuring_a_Profile_Run">Configuring a Profile Run</h3>
- <p>To configure a Valgrind profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu.
- <br/>
- <img border="0" src="images/Screenshot-ProfileConfigurations.png"/>
- </p>
- <p>The
- <b>
- <i>Profile Configurations</i>
- </b> 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
- <b>
- <i>Valgrind Options</i>
- </b> tab of a specific profile run.
-
- <br/>
- <img border="0" src="images/Screenshot-ProfileConfigurations-valgrind-options-tab.png"/>
- </p>
- <h4 id="General_Options">General Options</h4>
- <p>The
- <b>
- <i>General Options</i>
- </b> tab allows you to configure the following options:
- </p>
- <ul>
- <li>
- <b>
- <i>Tool to run</i>
- </b> allows you to choose between
- <a href="Valgrind%20Reference.html#Using_Memcheck">Memcheck</a>,
- <a href="Valgrind%20Reference.html#Using_Massif">Massif</a>, and
- <a href="Valgrind%20Reference.html#Using_Cachegrind">Cachegrind</a> in your profile run. By default, using the one-click shortcut will run the
- <a href="Valgrind%20Reference.html#Using_Memcheck">Memcheck</a> tool.
- </li>
- <li>
- <b>
- <i>Trace children on exec</i>
- </b> configures whether or not to trace into sub-processes initiated via the <code>exec</code> system call. This is identical to using the <code>--trace-children=</code> option. This is disabled by default.
- <br/>For more details on the use of the
- <b>
- <i>Trace children on exec</i>
- </b> option for each Valgrind tool, refer to
- <a href="Valgrind%20Reference.html#Profiling_Child_Processes">Profiling Child Processes</a>.
- </li>
- <li>
- <b>
- <i>Run __libc_freeres on exit</i>
- </b> configures whether or not to run a <code>__libc_freeres</code> routine after the profile run exits. This routine instructs <code>glibc</code> to release all memory it has allocated, and is similar to using the <code>--run-libc-freeres=</code> option. This is enabled by default.
- </li>
- <li>
- <b>
- <i>Child silent after fork</i>
- </b> 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 <code>fork</code> call.
- </li>
- <li>
- <b>
- <i>Demangle C++ names</i>
- </b> allows Valgrind to translate encoded C++ names ("mangled" by <code>g++</code> during compilation) back to something similar to their original form. This is enabled by default.
- </li>
- <li>
- <b>
- <i>Limit errors reported</i>
- </b> 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.
- </li>
- <li>
- <b>
- <i>Callers in stack trace</i>
- </b> configures how many levels of function call names Valgrind should use to identify program locations. By default, Valgrind uses 12 levels.
- </li>
- <li>
- <b>
- <i>Show errors below main</i>
- </b> configures stack traces for errors should show any functions that appear beneath <code>main()</code>. This is disabled by default.
- </li>
- <li>
- <b>
- <i>Max stack frame size</i>
- </b> is the maximum size of a stack frame, and is set to 2000000 by default.
- </li>
- </ul>
- <p>For more information about these options, refer to <code>man valgrind</code>.</p>
- <h4 id="Suppressions">Suppressions</h4>
- <p>You can also configure your profile run to use a suppressions file (similar to the <code>--suppressions=</code> option. To do this, click the
- <b>
- <i>Suppressions</i>
- </b> tab.
-
- <br/>
- <img border="0" src="images/Screenshot-Suppressions.png"/>
- </p>
- <p>The <u>Workspace</u> 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 <u>File System</u> button.</p>
- <h3 id="Exporting_Valgrind_Data">Exporting Valgrind Data</h3>
- <p>To export the raw data collected during a Valgrind profile run, use the
- <b>
- <i>Export</i>
- </b> wizard menu. To access the
- <b>
- <i>Export</i>
- </b> wizard menu, navigate to <u>File</u> > <u>Export</u> and select <u>Valgrind Log Files</u> under the category <u>Other</u>.
- </p>
- <p>
- <br/>
- <img border="0" src="images/ValgrindExportWizard.png"/>
- </p>
- <p>Alternatively, you can also use the <u>Export Valgrind Log Files</u> icon (
- <img border="0" src="images/exportbuttonvalgrindview.png"/> ) on the Valgrind view toolbar to access the
- <b>
- <i>Export</i>
- </b> wizard menu.
- </p>
- <h2 id="Using_Memcheck">Using Memcheck</h2>
- <p>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
- <a href="http://www.valgrind.org/docs/manual/mc-manual.html">http://www.valgrind.org/docs/manual/mc-manual.html</a>.
- </p>
- <h3 id="Analyzing_Memcheck_Profile_Results">Analyzing Memcheck Profile Results</h3>
- <p>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. </p>
- <p>
- <br/>
- <img border="0" src="images/MemcheckOutput.png"/>
- </p>
- <p>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. </p>
- <h3 id="Configuring_a_Memcheck_Profile_Run">Configuring a Memcheck Profile Run</h3>
- <p>To configure a Memcheck profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu. In the
- <b>
- <i>Valgrind Options</i>
- </b> tab, navigate further to
- <b>
- <i>Memcheck Options</i>
- </b>.
- <br/>
- <img border="0" src="images/MemcheckOptions.png"/>
- </p>
- <p>The
- <b>
- <i>Memcheck Options</i>
- </b> tab allows you to configure the following Memcheck options:
- </p>
- <ul>
- <li>
- <b>
- <i>leak resolution</i>
- </b> 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.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>freelist size (blocks)</i>
- </b> is identical to the Memcheck command-line option <code>--freelist-vol=</code>, which specifies the maximum total size (in bytes) of memory blocks to be marked "inaccessible" once they have been freed using <code>free</code> (as in C) or <code>delete</code> (as in C++). The default value for
- <b>
- <i>freelist size (blocks)</i>
- </b> is 10000000.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>minimum heap block alignment</i>
- </b> is identical to the Memcheck command-line option <code>--alignment=</code>, which specifies the minimum alignment/size of heap blocks. The default value for this option is 8.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>show reachable blocks</i>
- </b> 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).
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>undef value errors</i>
- </b> configures whether or not Memcheck should detect dangerous uses of undefined value errors. This is enabled by default.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>allow partial loads</i>
- </b> is identical to the Memcheck command-line option <code>--partial-loads-ok=</code>, 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).
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>gcc 2.96 workarounds</i>
- </b> is identical to the Memcheck command-line option <code>--workaround-gcc296-bugs</code>, which controls whether Memcheck should assume that small reads/writes below the stack pointer are due to bugs in
- <i>gcc-2.96</i>. This option is disabled by default (i.e. do not assume them to be reslting from
- <i>gcc-2.96</i> bugs; report such reads/writes as errors).
- </li>
- </ul>
- <p>Refer to
- <a href="http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles">http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles</a> for information about Memcheck suppression files. For more information about each Memcheck option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.
- </p>
- <h2 id="Using_Massif">Using Massif</h2>
- <p>Massif is a Valgrind tool that measures how much heap memory an application uses. Heap memory profiling is useful in determining how to reduce the memory usage of an application. For more information about Massif, refer to
- <a href="http://www.valgrind.org/docs/manual/ms-manual.html">http://www.valgrind.org/docs/manual/ms-manual.html</a>.
- </p>
- <p>To use Massif, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu. Open the
- <b>
- <i>Valgrind Options</i>
- </b> tab and choose Massif from the <u>Tool to run:</u> drop-down list.
- <br/>
- <img border="0" src="images/SwitchMassif.png"/>
- </p>
- <h3 id="Analyzing_Massif_Profile_Results">Analyzing Massif Profile Results</h3>
- <p>Massif distills a large volume of data. The Valgrind plug-in for Eclipse presents three ways to view this data:</p>
- <ul>
- <li>
- <b>Snapshots Table</b>. Each entry in the Valgrind view contains useful information about each snapshot taken by Massif during the profile run. The peak snapshot is highlighed in bold text.
- </li>
- </ul>
- <p>
- <br/>
- <img border="0" src="images/MassifTable.png"/>
- </p>
- <ul>
- <li>
- <b>Heap Tree</b>. Detailed snapshots are denoted by the <u>Show Heap Tree</u> icon (
- <img border="0" src="images/hierarchy.gif"/> ). Double-clicking any of these snapshots will modify the Valgrind view to display all detailed snapshots. Collapsing each detailed snapshot in this view will display a heirarchy of function calls (i.e. heap tree) detailing the heap allocations used during the snapshot.
- <br/>
- <img border="0" src="images/MassifTree.png"/>
- <br/>Some functions within the heap tree list a related source file. Double-clicking these functions will open the listed source file and place the insertion point on the specific function responsible for the call.
- <br/>You also can also toggle the <u>Show Heap Tree</u> shortcut on the Valgrind view toolbar to switch between
- <b>Snapshots Table</b> and
- <b>Heap Tree</b> views.
- </li>
- </ul>
- <ul>
- <li>
- <b>Heap Chart</b>. The information in the snapshots table is also available in line chart form, displayed in the
- <b>Heap Chart</b> window. Clicking any data point in the chart will highlight its corresponding snapshot in the snapshot table. Double-clicking on a data point that corresponds to a detailed snapshot will open an editor to one of its function calls.
- <br/>
- <img border="0" src="images/MassifChartSelect.png"/>
- <br/>If a detailed snapshot contains calls to multiple source files (or multiple functions within a source file), double-clicking its corresponding data point on the heap chart will open the
- <b>
- <i>Open Allocation Function Call</i>
- </b> menu. Double-clicking a function from the
- <b>
- <i>Open Allocation Function Call</i>
- </b> menu will open its corresponding source file and place the insertion point on the specific function responsible for the call.
- </li>
- </ul>
- <h3 id="Configuring_a_Massif_Profile_Run">Configuring a Massif Profile Run</h3>
- <p>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu. In the
- <b>
- <i>Valgrind Options</i>
- </b> tab, navigate further to
- <b>
- <i>Massif Options</i>
- </b>.
- <br/>
- <img border="0" src="images/MassifOptions.png"/>
- </p>
- <p>The
- <b>
- <i>Massif Options</i>
- </b> tab allows you to configure the following Massif options:
- </p>
- <ul>
- <li>
- <b>
- <i>profile heap</i>
- </b> specifies whether or not heap profiling should be performed. This option is enabled by default.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>profile stack</i>
- </b> specifies whether or not stack profiling should be performed. This option is disabled by default, as it significantly slows down Massif.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>heap allocation threshold</i>
- </b> specifies the significance threshold for heap allocations (as a percentage). Allocation tree entries that account for less than this will be aggregated. The default value for this option is 1%.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>time unit</i>
- </b> specifies what time unit should be used for the profile. The possible values for this are instructions (default), milliseconds, or bytes.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>max snapshots</i>
- </b> specifies the maximum number of snapshots that the profile should take. The default value for this is 100.
- </li>
- </ul>
- <ul>
- <li>The
- <b>
- <i>allocated functions</i>
- </b> field is identical to the Massif command-line option <code>--alloc-fn=</code>, which allows you to specify any function to be treated as a heap allocation function. To add or remove functions to this field, use the <u>New</u> or <u>Remove</u> buttons. You can specify multiple functions in this field.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>administrative bytes per block</i>
- </b> is identical to the Massif command-line option <code>--heap-admin=</code>, which specifies the number of administrative bytes (per block) to use if heap profiling is enabled. The default value for this option is 8.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>allocation tree depth</i>
- </b> is identical to the Massif command-line option <code>--depth=</code>, which specifies the maximum depth of the allocation trees recorded for detailed snapshots. The default value for this option is 30.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>allocation peak inaccuracy</i>
- </b> is identical to the Massif command-line option <code>--peak-inaccuracy=</code>. Massif records a peak only when the global memory allocation size exceeds the previous peak by the specified percentage value of this option. The default value for this option is 1.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>detailed snapshot frequency</i>
- </b> specifies the frequency at which Massif should take detailed snapshots. The default value for this option is 10; to specify that each snapshot should be detailed, set this option to 1.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>minimum heap block alignment</i>
- </b> specifies the minimum alignment (i.e. size) of heap blocks.
- </li>
- </ul>
- <p>For more information about each Massif option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</p>
- <h2 id="Using_Cachegrind">Using Cachegrind</h2>
- <p>Cachegrind performs cache and branching profiling. A Cachegrind profile run measures the number of cache misses and branch mispredictions performed by an application. Cachegrind collects the following statistics:</p>
- <ul>
- <li>L1 instruction cache reads and misses</li>
- <li>L1 data cache reads and read misses, writes, and write misses</li>
- <li>L2 unified cache reads and read misses, writes and write misses</li>
- <li>Conditional branches and mispredicted conditional branches</li>
- <li>Indirect branches and mispredicted indirect brances</li>
- </ul>
- <p>To use Cachegrind, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu. Open the
- <b>
- <i>Valgrind Options</i>
- </b> tab and choose Cachegrind from the
- <b>
- <i>Tool to run:</i>
- </b> drop-down list.
- <br/>
- <img border="0" src="images/SwitchCachegrind.png"/>
- </p>
- <h3 id="Analyzing_Cachegrind_Profile_Results">Analyzing Cachegrind Profile Results</h3>
- <p>The results of a Cachegrind profile run are displayed in the Valgrind view. These results show Cachegrind's cache/branch data in different levels of granularity. Double-clicking on any file, function, or line will open the corresponding source file and place the insertion point on the appropriate function (if such a link can be resolved).</p>
- <p>
- <br/>
- <img border="0" src="images/CachegrindOutput.png"/>
- </p>
- <h3 id="Configuring_a_Cachegrind_Profile_Run">Configuring a Cachegrind Profile Run</h3>
- <p>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <b>
- <i>Profile Configurations</i>
- </b> menu. In the
- <b>
- <i>Valgrind Options</i>
- </b> tab, navigate further to
- <b>
- <i>Cachegrind Options</i>
- </b>.
- <br/>
- <img border="0" src="images/CachegrindOptions.png"/>
- </p>
- <p>The
- <b>
- <i>Cachegrind Options</i>
- </b> tab allows you to configure the following Cachegrind options:
- </p>
- <ul>
- <li>
- <b>
- <i>Profile Cache Accesses/Misses</i>
- </b> is identical to the Cachegrind command-line option <code>--cache-sim=</code>, which specifies whether or not to collect cache accesses and miss counts. This option is enabled by default.
- </li>
- </ul>
- <ul>
- <li>
- <b>
- <i>Profile Branch Instructions/Mispredictions</i>
- </b> is identical to the Cachegrind command-line option <code>--branch-sim=</code>, wich specifies whether or not to collect branch instruction and misprediction counts. This option is disabled by default.
- </li>
- </ul>
- <ul>
- <li>The options inside the <u>Manually Set Cache Specifications</u> box allow you to configure the size, associativity, and line size of the following caches:
- <ul>
- <li>
- <b>l1</b> (level 1 instruction) cache
- </li>
- <li>
- <b>D1</b> (level 1 data) cache
- </li>
- <li>
- <b>L2</b> (level 2) cache
- </li>
- </ul>
- </li>
- </ul>
- <p>For more information about each Cachegrind option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</p>
- <h2 id="Special_Cases">Special Cases</h2>
- <h3 id="Encountering_Errors">Encountering Errors</h3>
- <p>If the profiled application contains any errors or if any Valgrind options you selected result in an error, these errors will be reported in the
- <i>Core Messages</i> pane of the Valgrind View. The Memcheck tool outputs all of its profile results on this pane.
- <br/>
- <img border="0" src="images/ValgrindSegfault.png"/>
- </p>
- <p>For other tools, it is possible to switch between the Core Messages pane and the tool's output in the Valgrind view menu.
- <br/>
- <img border="0" src="images/SwitchCoreTool.png"/>
- </p>
- <h3 id="Profiling_Child_Processes">Profiling Child Processes</h3>
- <p>To profile child processes during a profile run, enable the
- <b>
- <i>Trace children on exec</i>
- </b> option in the
- <b>
- <i>General Options</i>
- </b> tab (of the
- <b>
- <i>Valgrind Options</i>
- </b> tab). Memcheck's results will list the process ID (PID) for each reported error in the Valgrind view.
- </p>
- <p>Massif, on the other hand, will present each process separately and allow you to switch between processes with the <u>Select Process ID</u> dropdown icon (
- <img border="0" src="images/Thread.gif"/> ) in the Valgrind view toolbar.
- </p>
- <p>Cachegrind will report each PID separately as a top-level element in its output tree.</p><hr/>
+ </p><hr/>
<table class="navigation" style="width: 100%;" border="0" summary="navigation">
<tr>
<td style="width: 20%" align="left"></td>
<td style="width: 60%" align="center"></td>
<td style="width: 20%" align="right">
- <a href="Updating-This-Document.html" title="Updating This Document">
+ <a href="Installing.html" title="Installing">
<img alt="Next" border="0" src="images/images/next.gif"/>
</a>
</td>
@@ -523,7 +50,7 @@
<tr>
<td style="width: 20%" align="left" valign="top"></td>
<td style="width: 60%" align="center"></td>
- <td style="width: 20%" align="right" valign="top">Updating This Document</td>
+ <td style="width: 20%" align="right" valign="top">Installing</td>
</tr>
</table>
</body>
diff --git a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.xml b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.xml
index e7743bd883..a74ead03d8 100644
--- a/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.xml
+++ b/valgrind/org.eclipse.linuxtools.valgrind.doc/userguide/Valgrind Reference.xml
@@ -2,689 +2,687 @@
<book>
<title>Valgrind Reference</title>
<chapter id="Overview">
- <section>
- <title>Overview</title>
- <para>
- <emphasis role="bold">Valgrind</emphasis> 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.
- </para>
- <para>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:
- <link linkend="Using_Memcheck">Memcheck</link>,
- <link linkend="Using_Massif">Massif</link>, and
- <link linkend="Using_Cachegrind">Cachegrind</link>.
- </para>
- <para>For more information about Valgrind, refer to
- <ulink url="http://www.valgrind.org/">http://www.valgrind.org/</ulink>.
- </para>
- </section>
- <section id="Installing">
- <title>Installing</title>
- <para>In order for the Valgrind plug-in for Eclipse to work properly, you should have the
- <emphasis role="italic">valgrind-3.3.0</emphasis> (or later) package installed on your system first.
- </para>
- <para>Once the
- <emphasis role="italic">valgrind</emphasis> package is installed, the easiest way to install the Valgrind plug-in for Eclipse is through the
- <emphasis role="bold">
- <emphasis role="italic">Software Updates and Add-ons</emphasis>
- </emphasis> menu. For information on how to use this menu, refer to
- <ulink url="http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site">this link</ulink>.
- </para>
- </section>
- <section id="General_Usage">
- <title>General Usage</title>
- <para>You can use the Valgrind plug-in's "one-click launch" shortcut to run a default profile. Doing so is similar to running <code>valgrind ./<i>program_name</i></code> from the command line. To use the one-click launch shortcut, right-click on the
- <emphasis role="italic">project</emphasis> or
- <emphasis role="italic">binary</emphasis> name in the
- <emphasis role="bold">
- <emphasis role="italic">Project Explorer</emphasis>
- </emphasis> window and navigate to <u>Profile As</u> > <u>Profile With Valgrind</u>. 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.
+ <title>Overview</title>
+ <para>
+ <emphasis role="bold">Valgrind</emphasis> is an instrumentation framework for building dynamic analysis tools that can be 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 needs.
+ </para>
+ <para>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:
+ <link linkend="Using_Memcheck">Memcheck</link>,
+ <link linkend="Using_Massif">Massif</link>, and
+ <link linkend="Using_Cachegrind">Cachegrind</link>.
+ </para>
+ <para>For more information about Valgrind, refer to
+ <ulink url="http://www.valgrind.org/">http://www.valgrind.org/</ulink>.
+ </para>
+ </chapter>
+ <chapter id="Installing">
+ <title>Installing</title>
+ <para>In order for the Valgrind plug-in for Eclipse to work properly, you should have the
+ <emphasis role="italic">valgrind-3.3.0</emphasis> (or later) package installed on your system first.
+ </para>
+ <para>Once the
+ <emphasis role="italic">valgrind</emphasis> package is installed, the easiest way to install the Valgrind plug-in for Eclipse is through the
+ <emphasis role="bold">
+ <emphasis role="italic">Software Updates and Add-ons</emphasis>
+ </emphasis> menu. For information on how to use this menu, refer to
+ <ulink url="http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site">this link</ulink>.
+ </para>
+ </chapter>
+ <chapter id="General_Usage">
+ <title>General Usage</title>
+ <para>You can use the Valgrind plug-in's "one-click launch" shortcut to run a default profile. Doing so is similar to running <code>valgrind ./<i>program_name</i></code> from the command line. To use the one-click launch shortcut, right-click on the
+ <emphasis role="italic">project</emphasis> or
+ <emphasis role="italic">binary</emphasis> name in the
+ <emphasis role="bold">
+ <emphasis role="italic">Project Explorer</emphasis>
+ </emphasis> window and navigate to <u>Profile As</u> > <u>Profile With Valgrind</u>. 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.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Shortcut.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <section id="Configuring_a_Profile_Run">
+ <title>Configuring a Profile Run</title>
+ <para>To configure a Valgrind profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> menu.
<mediaobject>
<imageobject>
- <imagedata fileref="Shortcut.png"/>
+ <imagedata fileref="Screenshot-ProfileConfigurations.png"/>
</imageobject>
</mediaobject>
</para>
- <section id="Configuring_a_Profile_Run">
- <title>Configuring a Profile Run</title>
- <para>To configure a Valgrind profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Screenshot-ProfileConfigurations.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>The
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> 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
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab of a specific profile run.
-
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Screenshot-ProfileConfigurations-valgrind-options-tab.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <section id="General_Options">
- <title>General Options</title>
- <para>The
- <emphasis role="bold">
- <emphasis role="italic">General Options</emphasis>
- </emphasis> tab allows you to configure the following options:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Tool to run</emphasis>
- </emphasis> allows you to choose between
- <link linkend="Using_Memcheck">Memcheck</link>,
- <link linkend="Using_Massif">Massif</link>, and
- <link linkend="Using_Cachegrind">Cachegrind</link> in your profile run. By default, using the one-click shortcut will run the
- <link linkend="Using_Memcheck">Memcheck</link> tool.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Trace children on exec</emphasis>
- </emphasis> configures whether or not to trace into sub-processes initiated via the <code>exec</code> system call. This is identical to using the <code>--trace-children=</code> option. This is disabled by default.
- For more details on the use of the
- <emphasis role="bold">
- <emphasis role="italic">Trace children on exec</emphasis>
- </emphasis> option for each Valgrind tool, refer to
- <link linkend="Profiling_Child_Processes">Profiling Child Processes</link>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Run __libc_freeres on exit</emphasis>
- </emphasis> configures whether or not to run a <code>__libc_freeres</code> routine after the profile run exits. This routine instructs <code>glibc</code> to release all memory it has allocated, and is similar to using the <code>--run-libc-freeres=</code> option. This is enabled by default.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Child silent after fork</emphasis>
- </emphasis> 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 <code>fork</code> call.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Demangle C++ names</emphasis>
- </emphasis> allows Valgrind to translate encoded C++ names ("mangled" by <code>g++</code> during compilation) back to something similar to their original form. This is enabled by default.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Limit errors reported</emphasis>
- </emphasis> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Callers in stack trace</emphasis>
- </emphasis> configures how many levels of function call names Valgrind should use to identify program locations. By default, Valgrind uses 12 levels.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Show errors below main</emphasis>
- </emphasis> configures stack traces for errors should show any functions that appear beneath <code>main()</code>. This is disabled by default.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Max stack frame size</emphasis>
- </emphasis> is the maximum size of a stack frame, and is set to 2000000 by default.
- </para>
- </listitem>
- </itemizedlist>
- <para>For more information about these options, refer to <code>man valgrind</code>.</para>
- </section>
- <section id="Suppressions">
- <title>Suppressions</title>
- <para>You can also configure your profile run to use a suppressions file (similar to the <code>--suppressions=</code> option. To do this, click the
- <emphasis role="bold">
- <emphasis role="italic">Suppressions</emphasis>
- </emphasis> tab.
-
+ <para>The
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> 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
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab of a specific profile run.
- <mediaobject>
- <imageobject>
- <imagedata fileref="Screenshot-Suppressions.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>The <u>Workspace</u> 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 <u>File System</u> button.</para>
- </section>
- </section>
- <section id="Exporting_Valgrind_Data">
- <title>Exporting Valgrind Data</title>
- <para>To export the raw data collected during a Valgrind profile run, use the
- <emphasis role="bold">
- <emphasis role="italic">Export</emphasis>
- </emphasis> wizard menu. To access the
- <emphasis role="bold">
- <emphasis role="italic">Export</emphasis>
- </emphasis> wizard menu, navigate to <u>File</u> > <u>Export</u> and select <u>Valgrind Log Files</u> under the category <u>Other</u>.
- </para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="ValgrindExportWizard.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>Alternatively, you can also use the <u>Export Valgrind Log Files</u> icon (
- <mediaobject>
- <imageobject>
- <imagedata fileref="exportbuttonvalgrindview.png"/>
- </imageobject>
- </mediaobject> ) on the Valgrind view toolbar to access the
- <emphasis role="bold">
- <emphasis role="italic">Export</emphasis>
- </emphasis> wizard menu.
- </para>
- </section>
- </section>
- <section id="Using_Memcheck">
- <title>Using Memcheck</title>
- <para>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
- <ulink url="http://www.valgrind.org/docs/manual/mc-manual.html">http://www.valgrind.org/docs/manual/mc-manual.html</ulink>.
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Screenshot-ProfileConfigurations-valgrind-options-tab.png"/>
+ </imageobject>
+ </mediaobject>
</para>
- <section id="Analyzing_Memcheck_Profile_Results">
- <title>Analyzing Memcheck Profile Results</title>
- <para>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. </para>
- <para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="MemcheckOutput.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>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. </para>
- </section>
- <section id="Configuring_a_Memcheck_Profile_Run">
- <title>Configuring a Memcheck Profile Run</title>
- <para>To configure a Memcheck profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu. In the
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab, navigate further to
- <emphasis role="bold">
- <emphasis role="italic">Memcheck Options</emphasis>
- </emphasis>.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="MemcheckOptions.png"/>
- </imageobject>
- </mediaobject>
- </para>
+ <section id="General_Options">
+ <title>General Options</title>
<para>The
<emphasis role="bold">
- <emphasis role="italic">Memcheck Options</emphasis>
- </emphasis> tab allows you to configure the following Memcheck options:
+ <emphasis role="italic">General Options</emphasis>
+ </emphasis> tab allows you to configure the following options:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">leak resolution</emphasis>
- </emphasis> 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.
+ <emphasis role="italic">Tool to run</emphasis>
+ </emphasis> allows you to choose between
+ <link linkend="Using_Memcheck">Memcheck</link>,
+ <link linkend="Using_Massif">Massif</link>, and
+ <link linkend="Using_Cachegrind">Cachegrind</link> in your profile run. By default, using the one-click shortcut will run the
+ <link linkend="Using_Memcheck">Memcheck</link> tool.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">freelist size (blocks)</emphasis>
- </emphasis> is identical to the Memcheck command-line option <code>--freelist-vol=</code>, which specifies the maximum total size (in bytes) of memory blocks to be marked "inaccessible" once they have been freed using <code>free</code> (as in C) or <code>delete</code> (as in C++). The default value for
+ <emphasis role="italic">Trace children on exec</emphasis>
+ </emphasis> configures whether or not to trace into sub-processes initiated via the <code>exec</code> system call. This is identical to using the <code>--trace-children=</code> option. This is disabled by default.
+ For more details on the use of the
<emphasis role="bold">
- <emphasis role="italic">freelist size (blocks)</emphasis>
- </emphasis> is 10000000.
+ <emphasis role="italic">Trace children on exec</emphasis>
+ </emphasis> option for each Valgrind tool, refer to
+ <link linkend="Profiling_Child_Processes">Profiling Child Processes</link>.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">minimum heap block alignment</emphasis>
- </emphasis> is identical to the Memcheck command-line option <code>--alignment=</code>, which specifies the minimum alignment/size of heap blocks. The default value for this option is 8.
+ <emphasis role="italic">Run __libc_freeres on exit</emphasis>
+ </emphasis> configures whether or not to run a <code>__libc_freeres</code> routine after the profile run exits. This routine instructs <code>glibc</code> to release all memory it has allocated, and is similar to using the <code>--run-libc-freeres=</code> option. This is enabled by default.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">show reachable blocks</emphasis>
- </emphasis> 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).
+ <emphasis role="italic">Child silent after fork</emphasis>
+ </emphasis> 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 <code>fork</code> call.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">undef value errors</emphasis>
- </emphasis> configures whether or not Memcheck should detect dangerous uses of undefined value errors. This is enabled by default.
+ <emphasis role="italic">Demangle C++ names</emphasis>
+ </emphasis> allows Valgrind to translate encoded C++ names ("mangled" by <code>g++</code> during compilation) back to something similar to their original form. This is enabled by default.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">allow partial loads</emphasis>
- </emphasis> is identical to the Memcheck command-line option <code>--partial-loads-ok=</code>, 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).
+ <emphasis role="italic">Limit errors reported</emphasis>
+ </emphasis> 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.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
<emphasis role="bold">
- <emphasis role="italic">gcc 2.96 workarounds</emphasis>
- </emphasis> is identical to the Memcheck command-line option <code>--workaround-gcc296-bugs</code>, which controls whether Memcheck should assume that small reads/writes below the stack pointer are due to bugs in
- <emphasis role="italic">gcc-2.96</emphasis>. This option is disabled by default (i.e. do not assume them to be reslting from
- <emphasis role="italic">gcc-2.96</emphasis> bugs; report such reads/writes as errors).
- </para>
- </listitem>
- </itemizedlist>
- <para>Refer to
- <ulink url="http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles">http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles</ulink> for information about Memcheck suppression files. For more information about each Memcheck option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.
- </para>
- </section>
- </section>
- <section id="Using_Massif">
- <title>Using Massif</title>
- <para>Massif is a Valgrind tool that measures how much heap memory an application uses. Heap memory profiling is useful in determining how to reduce the memory usage of an application. For more information about Massif, refer to
- <ulink url="http://www.valgrind.org/docs/manual/ms-manual.html">http://www.valgrind.org/docs/manual/ms-manual.html</ulink>.
- </para>
- <para>To use Massif, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu. Open the
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab and choose Massif from the <u>Tool to run:</u> drop-down list.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="SwitchMassif.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <section id="Analyzing_Massif_Profile_Results">
- <title>Analyzing Massif Profile Results</title>
- <para>Massif distills a large volume of data. The Valgrind plug-in for Eclipse presents three ways to view this data:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Snapshots Table</emphasis>. Each entry in the Valgrind view contains useful information about each snapshot taken by Massif during the profile run. The peak snapshot is highlighed in bold text.
+ <emphasis role="italic">Callers in stack trace</emphasis>
+ </emphasis> configures how many levels of function call names Valgrind should use to identify program locations. By default, Valgrind uses 12 levels.
</para>
</listitem>
- </itemizedlist>
- <para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="MassifTable.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">Heap Tree</emphasis>. Detailed snapshots are denoted by the <u>Show Heap Tree</u> icon (
- <mediaobject>
- <imageobject>
- <imagedata fileref="hierarchy.gif"/>
- </imageobject>
- </mediaobject> ). Double-clicking any of these snapshots will modify the Valgrind view to display all detailed snapshots. Collapsing each detailed snapshot in this view will display a heirarchy of function calls (i.e. heap tree) detailing the heap allocations used during the snapshot.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="MassifTree.png"/>
- </imageobject>
- </mediaobject>
- Some functions within the heap tree list a related source file. Double-clicking these functions will open the listed source file and place the insertion point on the specific function responsible for the call.
- You also can also toggle the <u>Show Heap Tree</u> shortcut on the Valgrind view toolbar to switch between
- <emphasis role="bold">Snapshots Table</emphasis> and
- <emphasis role="bold">Heap Tree</emphasis> views.
+ <emphasis role="bold">
+ <emphasis role="italic">Show errors below main</emphasis>
+ </emphasis> configures stack traces for errors should show any functions that appear beneath <code>main()</code>. This is disabled by default.
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
<para>
- <emphasis role="bold">Heap Chart</emphasis>. The information in the snapshots table is also available in line chart form, displayed in the
- <emphasis role="bold">Heap Chart</emphasis> window. Clicking any data point in the chart will highlight its corresponding snapshot in the snapshot table. Double-clicking on a data point that corresponds to a detailed snapshot will open an editor to one of its function calls.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="MassifChartSelect.png"/>
- </imageobject>
- </mediaobject>
- If a detailed snapshot contains calls to multiple source files (or multiple functions within a source file), double-clicking its corresponding data point on the heap chart will open the
- <emphasis role="bold">
- <emphasis role="italic">Open Allocation Function Call</emphasis>
- </emphasis> menu. Double-clicking a function from the
<emphasis role="bold">
- <emphasis role="italic">Open Allocation Function Call</emphasis>
- </emphasis> menu will open its corresponding source file and place the insertion point on the specific function responsible for the call.
+ <emphasis role="italic">Max stack frame size</emphasis>
+ </emphasis> is the maximum size of a stack frame, and is set to 2000000 by default.
</para>
</listitem>
</itemizedlist>
+ <para>For more information about these options, refer to <code>man valgrind</code>.</para>
</section>
- <section id="Configuring_a_Massif_Profile_Run">
- <title>Configuring a Massif Profile Run</title>
- <para>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu. In the
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab, navigate further to
+ <section id="Suppressions">
+ <title>Suppressions</title>
+ <para>You can also configure your profile run to use a suppressions file (similar to the <code>--suppressions=</code> option. To do this, click the
<emphasis role="bold">
- <emphasis role="italic">Massif Options</emphasis>
- </emphasis>.
+ <emphasis role="italic">Suppressions</emphasis>
+ </emphasis> tab.
+
<mediaobject>
<imageobject>
- <imagedata fileref="MassifOptions.png"/>
+ <imagedata fileref="Screenshot-Suppressions.png"/>
</imageobject>
</mediaobject>
</para>
- <para>The
- <emphasis role="bold">
- <emphasis role="italic">Massif Options</emphasis>
- </emphasis> tab allows you to configure the following Massif options:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">profile heap</emphasis>
- </emphasis> specifies whether or not heap profiling should be performed. This option is enabled by default.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">profile stack</emphasis>
- </emphasis> specifies whether or not stack profiling should be performed. This option is disabled by default, as it significantly slows down Massif.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">heap allocation threshold</emphasis>
- </emphasis> specifies the significance threshold for heap allocations (as a percentage). Allocation tree entries that account for less than this will be aggregated. The default value for this option is 1%.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">time unit</emphasis>
- </emphasis> specifies what time unit should be used for the profile. The possible values for this are instructions (default), milliseconds, or bytes.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">max snapshots</emphasis>
- </emphasis> specifies the maximum number of snapshots that the profile should take. The default value for this is 100.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>The
- <emphasis role="bold">
- <emphasis role="italic">allocated functions</emphasis>
- </emphasis> field is identical to the Massif command-line option <code>--alloc-fn=</code>, which allows you to specify any function to be treated as a heap allocation function. To add or remove functions to this field, use the <u>New</u> or <u>Remove</u> buttons. You can specify multiple functions in this field.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">administrative bytes per block</emphasis>
- </emphasis> is identical to the Massif command-line option <code>--heap-admin=</code>, which specifies the number of administrative bytes (per block) to use if heap profiling is enabled. The default value for this option is 8.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">allocation tree depth</emphasis>
- </emphasis> is identical to the Massif command-line option <code>--depth=</code>, which specifies the maximum depth of the allocation trees recorded for detailed snapshots. The default value for this option is 30.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">allocation peak inaccuracy</emphasis>
- </emphasis> is identical to the Massif command-line option <code>--peak-inaccuracy=</code>. Massif records a peak only when the global memory allocation size exceeds the previous peak by the specified percentage value of this option. The default value for this option is 1.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">detailed snapshot frequency</emphasis>
- </emphasis> specifies the frequency at which Massif should take detailed snapshots. The default value for this option is 10; to specify that each snapshot should be detailed, set this option to 1.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">minimum heap block alignment</emphasis>
- </emphasis> specifies the minimum alignment (i.e. size) of heap blocks.
- </para>
- </listitem>
- </itemizedlist>
- <para>For more information about each Massif option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</para>
+ <para>The <u>Workspace</u> 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 <u>File System</u> button.</para>
</section>
</section>
- <section id="Using_Cachegrind">
- <title>Using Cachegrind</title>
- <para>Cachegrind performs cache and branching profiling. A Cachegrind profile run measures the number of cache misses and branch mispredictions performed by an application. Cachegrind collects the following statistics:</para>
+ <section id="Exporting_Valgrind_Data">
+ <title>Exporting Valgrind Data</title>
+ <para>To export the raw data collected during a Valgrind profile run, use the
+ <emphasis role="bold">
+ <emphasis role="italic">Export</emphasis>
+ </emphasis> wizard menu. To access the
+ <emphasis role="bold">
+ <emphasis role="italic">Export</emphasis>
+ </emphasis> wizard menu, navigate to <u>File</u> > <u>Export</u> and select <u>Valgrind Log Files</u> under the category <u>Other</u>.
+ </para>
+ <para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="ValgrindExportWizard.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>Alternatively, you can also use the <u>Export Valgrind Log Files</u> icon (
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Exportbuttonvalgrindview.gif"/>
+ </imageobject>
+ </mediaobject> ) on the Valgrind view toolbar to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Export</emphasis>
+ </emphasis> wizard menu.
+ </para>
+ </section>
+ </chapter>
+ <chapter id="Using_Memcheck">
+ <title>Using Memcheck</title>
+ <para>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
+ <ulink url="http://www.valgrind.org/docs/manual/mc-manual.html">http://www.valgrind.org/docs/manual/mc-manual.html</ulink>.
+ </para>
+ <section id="Analyzing_Memcheck_Profile_Results">
+ <title>Analyzing Memcheck Profile Results</title>
+ <para>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. </para>
+ <para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="MemcheckOutput.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>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. </para>
+ </section>
+ <section id="Configuring_a_Memcheck_Profile_Run">
+ <title>Configuring a Memcheck Profile Run</title>
+ <para>To configure a Memcheck profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> menu. In the
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab, navigate further to
+ <emphasis role="bold">
+ <emphasis role="italic">Memcheck Options</emphasis>
+ </emphasis>.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="MemcheckOptions.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>The
+ <emphasis role="bold">
+ <emphasis role="italic">Memcheck Options</emphasis>
+ </emphasis> tab allows you to configure the following Memcheck options:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">leak resolution</emphasis>
+ </emphasis> 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">freelist size (blocks)</emphasis>
+ </emphasis> is identical to the Memcheck command-line option <code>--freelist-vol=</code>, which specifies the maximum total size (in bytes) of memory blocks to be marked "inaccessible" once they have been freed using <code>free</code> (as in C) or <code>delete</code> (as in C++). The default value for
+ <emphasis role="bold">
+ <emphasis role="italic">freelist size (blocks)</emphasis>
+ </emphasis> is 10000000.
+ </para>
+ </listitem>
+ </itemizedlist>
<itemizedlist>
<listitem>
- <para>L1 instruction cache reads and misses</para>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">minimum heap block alignment</emphasis>
+ </emphasis> is identical to the Memcheck command-line option <code>--alignment=</code>, which specifies the minimum alignment/size of heap blocks. The default value for this option is 8.
+ </para>
</listitem>
+ </itemizedlist>
+ <itemizedlist>
<listitem>
- <para>L1 data cache reads and read misses, writes, and write misses</para>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">show reachable blocks</emphasis>
+ </emphasis> 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).
+ </para>
</listitem>
+ </itemizedlist>
+ <itemizedlist>
<listitem>
- <para>L2 unified cache reads and read misses, writes and write misses</para>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">undef value errors</emphasis>
+ </emphasis> configures whether or not Memcheck should detect dangerous uses of undefined value errors. This is enabled by default.
+ </para>
</listitem>
+ </itemizedlist>
+ <itemizedlist>
<listitem>
- <para>Conditional branches and mispredicted conditional branches</para>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">allow partial loads</emphasis>
+ </emphasis> is identical to the Memcheck command-line option <code>--partial-loads-ok=</code>, 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).
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">gcc 2.96 workarounds</emphasis>
+ </emphasis> is identical to the Memcheck command-line option <code>--workaround-gcc296-bugs</code>, which controls whether Memcheck should assume that small reads/writes below the stack pointer are due to bugs in
+ <emphasis role="italic">gcc-2.96</emphasis>. This option is disabled by default (i.e. do not assume them to be reslting from
+ <emphasis role="italic">gcc-2.96</emphasis> bugs; report such reads/writes as errors).
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>Refer to
+ <ulink url="http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles">http://www.valgrind.org/docs/manual/mc-manual.html#mc-manual.suppfiles</ulink> for information about Memcheck suppression files. For more information about each Memcheck option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.
+ </para>
+ </section>
+ </chapter>
+ <chapter id="Using_Massif">
+ <title>Using Massif</title>
+ <para>Massif is a Valgrind tool that measures how much heap memory an application uses. Heap memory profiling is useful in determining how to reduce the memory usage of an application. For more information about Massif, refer to
+ <ulink url="http://www.valgrind.org/docs/manual/ms-manual.html">http://www.valgrind.org/docs/manual/ms-manual.html</ulink>.
+ </para>
+ <para>To use Massif, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> menu. Open the
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab and choose Massif from the <u>Tool to run:</u> drop-down list.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="SwitchMassif.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <section id="Analyzing_Massif_Profile_Results">
+ <title>Analyzing Massif Profile Results</title>
+ <para>Massif distills a large volume of data. The Valgrind plug-in for Eclipse presents three ways to view this data:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">Snapshots Table</emphasis>. Each entry in the Valgrind view contains useful information about each snapshot taken by Massif during the profile run. The peak snapshot is highlighed in bold text.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="MassifTable.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">Heap Tree</emphasis>. Detailed snapshots are denoted by the <u>Show Heap Tree</u> icon (
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="hierarchy.gif"/>
+ </imageobject>
+ </mediaobject> ). Double-clicking any of these snapshots will modify the Valgrind view to display all detailed snapshots. Collapsing each detailed snapshot in this view will display a heirarchy of function calls (i.e. heap tree) detailing the heap allocations used during the snapshot.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="MassifTree.png"/>
+ </imageobject>
+ </mediaobject>
+ Some functions within the heap tree list a related source file. Double-clicking these functions will open the listed source file and place the insertion point on the specific function responsible for the call.
+ You also can also toggle the <u>Show Heap Tree</u> shortcut on the Valgrind view toolbar to switch between
+ <emphasis role="bold">Snapshots Table</emphasis> and
+ <emphasis role="bold">Heap Tree</emphasis> views.
+ </para>
</listitem>
+ </itemizedlist>
+ <itemizedlist>
<listitem>
- <para>Indirect branches and mispredicted indirect brances</para>
+ <para>
+ <emphasis role="bold">Heap Chart</emphasis>. The information in the snapshots table is also available in line chart form, displayed in the
+ <emphasis role="bold">Heap Chart</emphasis> window. Clicking any data point in the chart will highlight its corresponding snapshot in the snapshot table. Double-clicking on a data point that corresponds to a detailed snapshot will open an editor to one of its function calls.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="MassifChartSelect.png"/>
+ </imageobject>
+ </mediaobject>
+ If a detailed snapshot contains calls to multiple source files (or multiple functions within a source file), double-clicking its corresponding data point on the heap chart will open the
+ <emphasis role="bold">
+ <emphasis role="italic">Open Allocation Function Call</emphasis>
+ </emphasis> menu. Double-clicking a function from the
+ <emphasis role="bold">
+ <emphasis role="italic">Open Allocation Function Call</emphasis>
+ </emphasis> menu will open its corresponding source file and place the insertion point on the specific function responsible for the call.
+ </para>
</listitem>
</itemizedlist>
- <para>To use Cachegrind, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ </section>
+ <section id="Configuring_a_Massif_Profile_Run">
+ <title>Configuring a Massif Profile Run</title>
+ <para>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
<emphasis role="bold">
<emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu. Open the
+ </emphasis> menu. In the
<emphasis role="bold">
<emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab and choose Cachegrind from the
+ </emphasis> tab, navigate further to
<emphasis role="bold">
- <emphasis role="italic">Tool to run:</emphasis>
- </emphasis> drop-down list.
+ <emphasis role="italic">Massif Options</emphasis>
+ </emphasis>.
<mediaobject>
<imageobject>
- <imagedata fileref="SwitchCachegrind.png"/>
+ <imagedata fileref="MassifOptions.png"/>
</imageobject>
</mediaobject>
</para>
- <section id="Analyzing_Cachegrind_Profile_Results">
- <title>Analyzing Cachegrind Profile Results</title>
- <para>The results of a Cachegrind profile run are displayed in the Valgrind view. These results show Cachegrind's cache/branch data in different levels of granularity. Double-clicking on any file, function, or line will open the corresponding source file and place the insertion point on the appropriate function (if such a link can be resolved).</para>
- <para>
+ <para>The
+ <emphasis role="bold">
+ <emphasis role="italic">Massif Options</emphasis>
+ </emphasis> tab allows you to configure the following Massif options:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">profile heap</emphasis>
+ </emphasis> specifies whether or not heap profiling should be performed. This option is enabled by default.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">profile stack</emphasis>
+ </emphasis> specifies whether or not stack profiling should be performed. This option is disabled by default, as it significantly slows down Massif.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">heap allocation threshold</emphasis>
+ </emphasis> specifies the significance threshold for heap allocations (as a percentage). Allocation tree entries that account for less than this will be aggregated. The default value for this option is 1%.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">time unit</emphasis>
+ </emphasis> specifies what time unit should be used for the profile. The possible values for this are instructions (default), milliseconds, or bytes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">max snapshots</emphasis>
+ </emphasis> specifies the maximum number of snapshots that the profile should take. The default value for this is 100.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>The
+ <emphasis role="bold">
+ <emphasis role="italic">allocated functions</emphasis>
+ </emphasis> field is identical to the Massif command-line option <code>--alloc-fn=</code>, which allows you to specify any function to be treated as a heap allocation function. To add or remove functions to this field, use the <u>New</u> or <u>Remove</u> buttons. You can specify multiple functions in this field.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">administrative bytes per block</emphasis>
+ </emphasis> is identical to the Massif command-line option <code>--heap-admin=</code>, which specifies the number of administrative bytes (per block) to use if heap profiling is enabled. The default value for this option is 8.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">allocation tree depth</emphasis>
+ </emphasis> is identical to the Massif command-line option <code>--depth=</code>, which specifies the maximum depth of the allocation trees recorded for detailed snapshots. The default value for this option is 30.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">allocation peak inaccuracy</emphasis>
+ </emphasis> is identical to the Massif command-line option <code>--peak-inaccuracy=</code>. Massif records a peak only when the global memory allocation size exceeds the previous peak by the specified percentage value of this option. The default value for this option is 1.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">detailed snapshot frequency</emphasis>
+ </emphasis> specifies the frequency at which Massif should take detailed snapshots. The default value for this option is 10; to specify that each snapshot should be detailed, set this option to 1.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">minimum heap block alignment</emphasis>
+ </emphasis> specifies the minimum alignment (i.e. size) of heap blocks.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>For more information about each Massif option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</para>
+ </section>
+ </chapter>
+ <chapter id="Using_Cachegrind">
+ <title>Using Cachegrind</title>
+ <para>Cachegrind performs cache and branching profiling. A Cachegrind profile run measures the number of cache misses and branch mispredictions performed by an application. Cachegrind collects the following statistics:</para>
+ <itemizedlist>
+ <listitem>
+ <para>L1 instruction cache reads and misses</para>
+ </listitem>
+ <listitem>
+ <para>L1 data cache reads and read misses, writes, and write misses</para>
+ </listitem>
+ <listitem>
+ <para>L2 unified cache reads and read misses, writes and write misses</para>
+ </listitem>
+ <listitem>
+ <para>Conditional branches and mispredicted conditional branches</para>
+ </listitem>
+ <listitem>
+ <para>Indirect branches and mispredicted indirect brances</para>
+ </listitem>
+ </itemizedlist>
+ <para>To use Cachegrind, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> menu. Open the
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab and choose Cachegrind from the
+ <emphasis role="bold">
+ <emphasis role="italic">Tool to run:</emphasis>
+ </emphasis> drop-down list.
- <mediaobject>
- <imageobject>
- <imagedata fileref="CachegrindOutput.png"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
- <section id="Configuring_a_Cachegrind_Profile_Run">
- <title>Configuring a Cachegrind Profile Run</title>
- <para>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
- <emphasis role="bold">
- <emphasis role="italic">Profile Configurations</emphasis>
- </emphasis> menu. In the
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab, navigate further to
- <emphasis role="bold">
- <emphasis role="italic">Cachegrind Options</emphasis>
- </emphasis>.
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="SwitchCachegrind.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <section id="Analyzing_Cachegrind_Profile_Results">
+ <title>Analyzing Cachegrind Profile Results</title>
+ <para>The results of a Cachegrind profile run are displayed in the Valgrind view. These results show Cachegrind's cache/branch data in different levels of granularity. Double-clicking on any file, function, or line will open the corresponding source file and place the insertion point on the appropriate function (if such a link can be resolved).</para>
+ <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="CachegrindOptions.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>The
- <emphasis role="bold">
- <emphasis role="italic">Cachegrind Options</emphasis>
- </emphasis> tab allows you to configure the following Cachegrind options:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Profile Cache Accesses/Misses</emphasis>
- </emphasis> is identical to the Cachegrind command-line option <code>--cache-sim=</code>, which specifies whether or not to collect cache accesses and miss counts. This option is enabled by default.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">
- <emphasis role="italic">Profile Branch Instructions/Mispredictions</emphasis>
- </emphasis> is identical to the Cachegrind command-line option <code>--branch-sim=</code>, wich specifies whether or not to collect branch instruction and misprediction counts. This option is disabled by default.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>The options inside the <u>Manually Set Cache Specifications</u> box allow you to configure the size, associativity, and line size of the following caches:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">l1</emphasis> (level 1 instruction) cache
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">D1</emphasis> (level 1 data) cache
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">L2</emphasis> (level 2) cache
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>For more information about each Cachegrind option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</para>
- </section>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="CachegrindOutput.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
</section>
- <section id="Special_Cases">
- <title>Special Cases</title>
- <section id="Encountering_Errors">
- <title>Encountering Errors</title>
- <para>If the profiled application contains any errors or if any Valgrind options you selected result in an error, these errors will be reported in the
- <emphasis role="italic">Core Messages</emphasis> pane of the Valgrind View. The Memcheck tool outputs all of its profile results on this pane.
+ <section id="Configuring_a_Cachegrind_Profile_Run">
+ <title>Configuring a Cachegrind Profile Run</title>
+ <para>To configure a Massif profile run, navigate to <u>Profile As</u> > <u>Profile Configurations</u> to access the
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Configurations</emphasis>
+ </emphasis> menu. In the
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab, navigate further to
+ <emphasis role="bold">
+ <emphasis role="italic">Cachegrind Options</emphasis>
+ </emphasis>.
- <mediaobject>
- <imageobject>
- <imagedata fileref="ValgrindSegfault.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>For other tools, it is possible to switch between the Core Messages pane and the tool's output in the Valgrind view menu.
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="CachegrindOptions.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>The
+ <emphasis role="bold">
+ <emphasis role="italic">Cachegrind Options</emphasis>
+ </emphasis> tab allows you to configure the following Cachegrind options:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Cache Accesses/Misses</emphasis>
+ </emphasis> is identical to the Cachegrind command-line option <code>--cache-sim=</code>, which specifies whether or not to collect cache accesses and miss counts. This option is enabled by default.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">
+ <emphasis role="italic">Profile Branch Instructions/Mispredictions</emphasis>
+ </emphasis> is identical to the Cachegrind command-line option <code>--branch-sim=</code>, wich specifies whether or not to collect branch instruction and misprediction counts. This option is disabled by default.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>The options inside the <u>Manually Set Cache Specifications</u> box allow you to configure the size, associativity, and line size of the following caches:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">l1</emphasis> (level 1 instruction) cache
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">D1</emphasis> (level 1 data) cache
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">L2</emphasis> (level 2) cache
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>For more information about each Cachegrind option in the Valgrind plug-in for Eclipse, refer to <code>man valgrind</code>.</para>
+ </section>
+ </chapter>
+ <chapter id="Special_Cases">
+ <title>Special Cases</title>
+ <section id="Encountering_Errors">
+ <title>Encountering Errors</title>
+ <para>If the profiled application contains any errors or if any Valgrind options you selected result in an error, these errors will be reported in the
+ <emphasis role="italic">Core Messages</emphasis> pane of the Valgrind View. The Memcheck tool outputs all of its profile results on this pane.
- <mediaobject>
- <imageobject>
- <imagedata fileref="SwitchCoreTool.png"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
- <section id="Profiling_Child_Processes">
- <title>Profiling Child Processes</title>
- <para>To profile child processes during a profile run, enable the
- <emphasis role="bold">
- <emphasis role="italic">Trace children on exec</emphasis>
- </emphasis> option in the
- <emphasis role="bold">
- <emphasis role="italic">General Options</emphasis>
- </emphasis> tab (of the
- <emphasis role="bold">
- <emphasis role="italic">Valgrind Options</emphasis>
- </emphasis> tab). Memcheck's results will list the process ID (PID) for each reported error in the Valgrind view.
- </para>
- <para>Massif, on the other hand, will present each process separately and allow you to switch between processes with the <u>Select Process ID</u> dropdown icon (
- <mediaobject>
- <imageobject>
- <imagedata fileref="Thread.gif"/>
- </imageobject>
- </mediaobject> ) in the Valgrind view toolbar.
- </para>
- <para>Cachegrind will report each PID separately as a top-level element in its output tree.</para>
- </section>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="ValgrindSegfault.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>For other tools, it is possible to switch between the Core Messages pane and the tool's output in the Valgrind view menu.
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="SwitchCoreTool.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </section>
+ <section id="Profiling_Child_Processes">
+ <title>Profiling Child Processes</title>
+ <para>To profile child processes during a profile run, enable the
+ <emphasis role="bold">
+ <emphasis role="italic">Trace children on exec</emphasis>
+ </emphasis> option in the
+ <emphasis role="bold">
+ <emphasis role="italic">General Options</emphasis>
+ </emphasis> tab (of the
+ <emphasis role="bold">
+ <emphasis role="italic">Valgrind Options</emphasis>
+ </emphasis> tab). Memcheck's results will list the process ID (PID) for each reported error in the Valgrind view.
+ </para>
+ <para>Massif, on the other hand, will present each process separately and allow you to switch between processes with the <u>Select Process ID</u> dropdown icon (
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Thread.gif"/>
+ </imageobject>
+ </mediaobject> ) in the Valgrind view toolbar.
+ </para>
+ <para>Cachegrind will report each PID separately as a top-level element in its output tree.</para>
</section>
</chapter>
<chapter id="Updating_This_Document">

Back to the top