|
From: <sv...@va...> - 2007-09-11 15:07:18
|
Author: sewardj Date: 2007-09-11 16:07:20 +0100 (Tue, 11 Sep 2007) New Revision: 6821 Log: Add docs (start with Helgrind's for now) Added: branches/THRCHECK/thrcheck/docs/tc-manual.xml Added: branches/THRCHECK/thrcheck/docs/tc-manual.xml =================================================================== --- branches/THRCHECK/thrcheck/docs/tc-manual.xml (rev 0) +++ branches/THRCHECK/thrcheck/docs/tc-manual.xml 2007-09-11 15:07:20 UTC (rev 6821) @@ -0,0 +1,106 @@ +<?xml version="1.0"?> <!-- -*- sgml -*- --> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + + +<chapter id="hg-manual" xreflabel="Helgrind: a data-race detector"> + <title>Helgrind: a data-race detector</title> + +<para>To use this tool, you must specify +<computeroutput>--tool=helgrind</computeroutput> on the Valgrind +command line.</para> + +<para>Note: Helgrind does not work in Valgrind 3.1.0. We hope +to reinstate in version 3.2.0.</para> + + +<sect1 id="hg-manual.data-races" xreflabel="Data Races"> +<title>Data Races</title> + +<para>Helgrind is a valgrind tool for detecting data races in C and C++ +programs that use the Pthreads library.</para> + +<para>It uses the Eraser algorithm described in: + + <address>Eraser: A Dynamic Data Race Detector for Multithreaded Programs + Stefan Savage, Michael Burrows, Greg Nelson, Patrick Sobalvarro and Thomas Anderson + ACM Transactions on Computer Systems, 15(4):391-411 + November 1997. + </address> +</para> + +<para>We also incorporate significant improvements from this paper: + + <address>Runtime Checking of Multithreaded Applications with Visual Threads + Jerry J. Harrow, Jr. + Proceedings of the 7th International SPIN Workshop on Model Checking of Software + Stanford, California, USA + August 2000 + LNCS 1885, pp331--342 + K. Havelund, J. Penix, and W. Visser, editors. + </address> +</para> + +</sect1> + + +<sect1 id="hg-manual.what-does" xreflabel="What Helgrind Does"> +<title>What Helgrind Does</title> + +<para>Basically what Helgrind does is to look for memory +locations which are accessed by more than one thread. For each +such location, Helgrind records which of the program's +(pthread_mutex_)locks were held by the accessing thread at the +time of the access. The hope is to discover that there is indeed +at least one lock which is used by all threads to protect that +location. If no such lock can be found, then there is +(apparently) no consistent locking strategy being applied for +that location, and so a possible data race might result.</para> + +<para>Helgrind also allows for "thread segment lifetimes". If +the execution of two threads cannot overlap -- for example, if +your main thread waits on another thread with a +<computeroutput>pthread_join()</computeroutput> operation -- they +can both access the same variable without holding a lock.</para> + +<para>There's a lot of other sophistication in Helgrind, aimed at +reducing the number of false reports, and at producing useful +error reports. We hope to have more documentation one +day ... </para> + +</sect1> + + + +<sect1 id="hg-manual.options" xreflabel="Helgrind Options"> +<title>Helgrind Options</title> + +<para>Helgrind-specific options are:</para> + +<!-- start of xi:include in the manpage --> +<variablelist id="hg.opts.list"> + + <varlistentry id="opt.private-stacks" xreflabel="--private-stacks"> + <term> + <option><![CDATA[--private-stacks=<yes|no> [default: no] ]]></option> + </term> + <listitem> + <para>Assume thread stacks are used privately.</para> + </listitem> + </varlistentry> + + <varlistentry id="opt.show-last-access" xreflabel="--show-last-access"> + <term> + <option><![CDATA[--show-last-access=<yes|some|no> [default: no] ]]></option> + </term> + <listitem> + <para>Show location of last word access on error.</para> + </listitem> + </varlistentry> + +</variablelist> +<!-- end of xi:include in the manpage --> + +</sect1> + +</chapter> |