From: Bart Van Assche <bvanassche@acm.org>
Date: Thu, 12 Jun 2008 15:20:42 +0000 (+0000)
Subject: Started converting README.txt into drd-manual.xml.
X-Git-Tag: svn/VALGRIND_3_4_0~477
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cb6843170663cf8804508b0a047fd2504473355c;p=thirdparty%2Fvalgrind.git

Started converting README.txt into drd-manual.xml.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8227
---

diff --git a/exp-drd/docs/Makefile.am b/exp-drd/docs/Makefile.am
index bec1ba22f8..9d6f5f4778 100644
--- a/exp-drd/docs/Makefile.am
+++ b/exp-drd/docs/Makefile.am
@@ -1 +1 @@
-EXTRA_DIST = README.txt
+EXTRA_DIST = drd-manual.xml
diff --git a/exp-drd/docs/drd-manual.xml b/exp-drd/docs/drd-manual.xml
new file mode 100644
index 0000000000..049c91d7de
--- /dev/null
+++ b/exp-drd/docs/drd-manual.xml
@@ -0,0 +1,125 @@
+<?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"
+[ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
+
+
+<chapter id="drd-manual" xreflabel="DRD: a thread error detector">
+  <title>DRD: a thread error detector</title>
+
+<para>To use this tool, you must specify
+<computeroutput>--tool=exp-drd</computeroutput>
+on the Valgrind command line.</para>
+
+<sect1 id="drd-manual.overview" xreflabel="Overview">
+<title>Overview</title>
+
+<para>
+DRD is a Valgrind tool for detecting errors in multithreaded C and C++
+programs that use the POSIX threading primitives, also known as
+pthreads. POSIX threads is the most widely available threading library
+on Unix systems.
+</para>
+
+<para>
+The next section provides
+<link linkend="drd-manual.multithreading">
+background information about multithreading</link>.
+</para>
+
+<para>
+DRD can detect two classes of errors, which are discussed in detail:
+</para>
+
+<orderedlist>
+ <listitem>
+  <para><link linkend="drd-manual.api-checks">
+        Misuses of the POSIX threads API.</link></para>
+ </listitem>
+ <listitem>
+  <para><link linkend="drd-manual.data-races">
+        Data races -- accessing memory without adequate locking.
+        </link></para>
+ </listitem>
+</orderedlist>
+
+<para>Then there is a
+<link linkend="drd-manual.options">summary of command-line
+options.</link>
+</para>
+
+<para>Finally, there is a section about the current
+<link linkend="drd-manual.limitations">limitations</link>
+of DRD.
+</para>
+
+</sect1>
+
+
+<sect1 id="drd-manual.multithreading" xreflabel="Multithreading">
+<title>Multithreaded Programming</title>
+</sect1>
+
+
+<sect1 id="drd-manual.api-checks" xreflabel="API Checks">
+<title>Detected errors: Misuses of the POSIX threads API</title>
+</sect1>
+
+
+<sect1 id="drd-manual.data-races" xreflabel="Data Races">
+<title>Detected errors: Data Races</title>
+</sect1>
+
+
+<sect1 id="drd-manual.options" xreflabel="DRD Options">
+<title>DRD Options</title>
+
+<para>The following end-user options are available:</para>
+
+<!-- start of xi:include in the manpage -->
+<variablelist id="drd.opts.list">
+</variablelist>
+<!-- end of xi:include in the manpage -->
+
+<!-- start of xi:include in the manpage -->
+<para>In addition, the following debugging options are available for
+DRD:</para>
+<variablelist id="drd.debugopts.list">
+</variablelist>
+<!-- end of xi:include in the manpage -->
+
+</sect1>
+
+<sect1 id="drd-manual.limitations" xreflabel="Limitations">
+<title>DRD Limitations</title>
+
+<para>DRD currently has the following limitations:</para>
+
+<itemizedlist>
+  <listitem><para>DRD has only been tested on the Linux operating
+  system, and not on any of the other operating systems supported by
+  Valgrind.</para>
+  </listitem>
+  <listitem><para>Of the two POSIX threads implementations for Linux,
+  only the NPTL (Native POSIX Thread Library) is supported. The older
+  LinuxThreads library is not supported.</para>
+  </listitem>
+  <listitem><para>When running DRD on a PowerPC CPU, DRD will report
+  false positives on atomic operations. See also <ulink
+  url="http://bugs.kde.org/show_bug.cgi?id=162354">bug 162354</ulink>.
+  </para></listitem>
+  <listitem><para>DRD, just like memcheck, will refuse to
+  start on Linux distributions where all symbol information has been
+  removed from ld.so. This is e.g. the case for openSUSE 10.3 -- see
+  also <ulink
+  url="http://bugzilla.novell.com/show_bug.cgi?id=396197">bug 396197</ulink>.
+  </para></listitem>
+  <listitem><para>If you compile the DRD sourcecode yourself, you need
+  gcc 3.0 or later. gcc 2.95 is not supported.</para>
+  </listitem>
+
+</itemizedlist>
+
+</sect1>
+
+</chapter>