Updated docs with all the changes that I'm aware of that happened since
Donna converted them to XML.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3173 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/AUTHORS b/AUTHORS
index 725f462..6b7100b 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,22 +1,21 @@
-Julian Seward, jseward@acm.org, was the original author, creating the
+Julian Seward was the original author, creating the
dynamic translation framework, memcheck stuff, and the
signal/syscall/threads support gunk.
-Nicholas Nethercote, njn25@cam.ac.uk, did the core/tool
-generalisation, and wrote Cachegrind and some of the other tools, and
-tons of other stuff, including code generation improvments.
+Nicholas Nethercote did the core/tool generalisation, and wrote
+Cachegrind and some of the other tools, and tons of other stuff.
-Jeremy Fitzhardinge, jeremy@goop.org, wrote Helgrind, and lots of
-syscall/signal simulation stuff, including a complete redesign of how
-syscalls and signals are handled. Also code generation improvements.
+Jeremy Fitzhardinge wrote Helgrind, and lots of syscall/signal
+simulation stuff, including a complete redesign of how syscalls and
+signals are handled. Also code generation improvements.
-Tom Hughes, thh@cyberscience.com, did a vast number of bug fixes, and
-helped out with support for more recent Linux/glibc versions.
+Tom Hughes did a vast number of bug fixes, and helped out with support
+for more recent Linux/glibc versions.
-Robert Walsh, rjwalsh@durables.org, added file descriptor leakage
-checking, new library interception machinery, support for client
-allocation pools, and minor other tweakage.
+Robert Walsh added file descriptor leakage checking, new library
+interception machinery, support for client allocation pools, and minor
+other tweakage.
readelf's dwarf2 source line reader, written by Nick Clifton, was
modified to be used in Valgrind by Daniel Berlin.
diff --git a/cachegrind/docs/cg-tech-docs.xml b/cachegrind/docs/cg-tech-docs.xml
index 210dee0..bc49a7a 100644
--- a/cachegrind/docs/cg-tech-docs.xml
+++ b/cachegrind/docs/cg-tech-docs.xml
@@ -9,6 +9,9 @@
<sect1 id="cg-tech-docs.profiling" xreflabel="Cache profiling">
<title>Cache profiling</title>
+<para>[Note: this document is now very old, and a lot of its contents are out
+of date, and misleading.]</para>
+
<para>Valgrind is a very nice platform for doing cache profiling
and other kinds of simulation, because it converts horrible x86
instructions into nice clean RISC-like UCode. For example, for
diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml
index 6ed8eea..06da30a 100644
--- a/docs/xml/manual-core.xml
+++ b/docs/xml/manual-core.xml
@@ -336,7 +336,7 @@
stop your program and fix it, because Valgrind won't tell you
anything else useful after this. Note that the 300/30000 limits
apply after suppressed errors are removed. These limits are
-defined in <filename>vg_include.h</filename> and can be increased
+defined in <filename>core.h</filename> and can be increased
if necessary.</para>
<para>To avoid this cutoff you can use the
diff --git a/docs/xml/writing-tools.xml b/docs/xml/writing-tools.xml
index b8b8aff..aaf1d9b 100644
--- a/docs/xml/writing-tools.xml
+++ b/docs/xml/writing-tools.xml
@@ -291,7 +291,7 @@
dynamic linker's <computeroutput>LD_PRELOAD</computeroutput>
variable. Any functions defined in the tool that share the name
with a function defined in core (such as the instrumentation
-function <computeroutput>SK_(instrument)()</computeroutput>)
+function <computeroutput>TL_(instrument)()</computeroutput>)
override the core's definition. Thus the core can call the
necessary tool functions.</para>
@@ -373,7 +373,7 @@
trying to understand this file, at least a little; you might
have to do more complicated things with it later on. In
particular, the name of the
- <computeroutput>vgskin_foobar_so_SOURCES</computeroutput>
+ <computeroutput>vgtool_foobar_so_SOURCES</computeroutput>
variable determines the name of the tool's shared object, which
determines what name must be passed to the
<computeroutput>--tool</computeroutput> option to use the
@@ -384,7 +384,7 @@
<para>Copy <filename>none/nl_main.c</filename> into
<computeroutput>foobar/</computeroutput>, renaming it as
<filename>fb_main.c</filename>. Edit it by changing the lines
- in <computeroutput>SK_(pre_clo_init)()</computeroutput> to
+ in <computeroutput>TL_(pre_clo_init)()</computeroutput> to
something appropriate for the tool. These fields are used in
the startup message, except for
<computeroutput>bug_reports_to</computeroutput> which is used
@@ -413,7 +413,7 @@
<para>It should automake, configure and compile without
errors, putting copies of the tool's shared object
- <computeroutput>vgskin_foobar.so</computeroutput> in
+ <computeroutput>vgtool_foobar.so</computeroutput> in
<computeroutput>foobar/</computeroutput> and
<computeroutput>inst/lib/valgrind/</computeroutput>.</para>
</listitem>
@@ -459,16 +459,16 @@
<para>A tool must define at least these four functions:</para>
<programlisting><![CDATA[
- SK_(pre_clo_init)()
- SK_(post_clo_init)()
- SK_(instrument)()
- SK_(fini)()]]></programlisting>
+ TL_(pre_clo_init)()
+ TL_(post_clo_init)()
+ TL_(instrument)()
+ TL_(fini)()]]></programlisting>
<para>Also, it must use the macro
<computeroutput>VG_DETERMINE_INTERFACE_VERSION</computeroutput>
exactly once in its source code. If it doesn't, you will get a
link error involving
-<computeroutput>VG_(skin_interface_major_version)</computeroutput>.
+<computeroutput>VG_(tool_interface_major_version)</computeroutput>.
This macro is used to ensure the core/tool interface used by the
core and a plugged-in tool are binary compatible.</para>
@@ -484,8 +484,8 @@
<title>Initialisation</title>
<para>Most of the initialisation should be done in
-<computeroutput>SK_(pre_clo_init)()</computeroutput>. Only use
-<computeroutput>SK_(post_clo_init)()</computeroutput> if a tool
+<computeroutput>TL_(pre_clo_init)()</computeroutput>. Only use
+<computeroutput>TL_(post_clo_init)()</computeroutput> if a tool
provides command line options and must do some initialisation
after option processing takes place
(<computeroutput>"clo"</computeroutput> stands for "command line
@@ -497,7 +497,7 @@
compulsory, some aren't. Some are used when constructing the
startup message,
<computeroutput>detail_bug_reports_to</computeroutput> is used if
-<computeroutput>VG_(skin_panic)()</computeroutput> is ever
+<computeroutput>VG_(tool_panic)()</computeroutput> is ever
called, or a tool assertion fails. Others have other uses.</para>
<para>Second, various "needs" can be set for a tool, using the
@@ -510,7 +510,7 @@
<para>For example, if a tool wants the core's help in recording
and reporting errors, it must set the
-<computeroutput>skin_errors</computeroutput> need to
+<computeroutput>tool_errors</computeroutput> need to
<computeroutput>True</computeroutput>, and then provide
definitions of six functions for comparing errors, printing out
errors, reading suppressions from a suppressions file, etc.
@@ -518,7 +518,7 @@
than doing error handling from scratch because the core is doing
most of the work. See the type
<computeroutput>VgNeeds</computeroutput> in
-<filename>include/vg_skin.h</filename> for full details of all
+<filename>include/tool.h</filename> for full details of all
the needs.</para>
<para>Third, the tool can indicate which events in core it wants
@@ -538,7 +538,7 @@
<para>More information about "details", "needs" and "trackable
events" can be found in
-<filename>include/vg_skin.h</filename>.</para>
+<filename>include/tool.h</filename>.</para>
</sect2>
@@ -547,7 +547,7 @@
<sect2 id="writing-tools.instr" xreflabel="Instrumentation">
<title>Instrumentation</title>
-<para><computeroutput>SK_(instrument)()</computeroutput> is the
+<para><computeroutput>TL_(instrument)()</computeroutput> is the
interesting one. It allows you to instrument
<emphasis>UCode</emphasis>, which is Valgrind's RISC-like
intermediate language. UCode is described in
@@ -587,7 +587,7 @@
important points, but there are undoubtedly many others that I
should note but haven't thought of.</para>
-<para>The file <filename>include/vg_skin.h</filename> contains
+<para>The file <filename>include/tool.h</filename> contains
all the types, macros, functions, etc. that a tool should
(hopefully) need, and is the only <filename>.h</filename> file a
tool should need to
@@ -597,23 +597,23 @@
C library (there are deep reasons for this, trust us). Valgrind
provides an implementation of a reasonable subset of the C
library, details of which are in
-<filename>vg_skin.h</filename>.</para>
+<filename>tool.h</filename>.</para>
<para>Similarly, when writing a tool, you shouldn't need to look
at any of the code in Valgrind's core. Although it might be
useful sometimes to help understand something.</para>
-<para><filename>vg_skin.h</filename> has a reasonable amount of
+<para><filename>tool.h</filename> has a reasonable amount of
documentation in it that should hopefully be enough to get you
going. But ultimately, the tools distributed (Memcheck,
Addrcheck, Cachegrind, Lackey, etc.) are probably the best
documentation of all, for the moment.</para>
<para>Note that the <computeroutput>VG_</computeroutput> and
-<computeroutput>SK_</computeroutput> macros are used heavily.
+<computeroutput>TL_</computeroutput> macros are used heavily.
These just prepend longer strings in front of names to avoid
potential namespace clashes. We strongly recommend using the
-<computeroutput>SK_</computeroutput> macro for any global
+<computeroutput>TL_</computeroutput> macro for any global
functions and variables in your tool, or writing a similar
macro.</para>
@@ -703,7 +703,7 @@
<para>If you just want to know whether a program point has been
reached, using the <computeroutput>OINK</computeroutput> macro
-(in <filename>include/vg_skin.h</filename>) can be easier than
+(in <filename>include/tool.h</filename>) can be easier than
using GDB.</para>
<para>The other debugging command line options can be useful too
@@ -1136,7 +1136,7 @@
<computeroutput>VGP_POPCC</computeroutput> macros to record time
spent doing certain things. New profiling event numbers must not
overlap with the core profiling event numbers. See
-<filename>include/vg_skin.h</filename> for details and Memcheck
+<filename>include/tool.h</filename> for details and Memcheck
for an example.</para>
</sect2>
diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml
index b540bf8..b8186f1 100644
--- a/memcheck/docs/mc-manual.xml
+++ b/memcheck/docs/mc-manual.xml
@@ -421,43 +421,56 @@
<title>Passing system call parameters with inadequate read/write
permissions</title>
-<para>Memcheck checks all parameters to system calls. If a
-system call needs to read from a buffer provided by your program,
-Memcheck checks that the entire buffer is addressible and has
-valid data, ie, it is readable. And if the system call needs to
-write to a user-supplied buffer, Memcheck checks that the buffer
-is addressible. After the system call, Memcheck updates its
-administrative information to precisely reflect any changes in
-memory permissions caused by the system call.</para>
+<para>Memcheck checks all parameters to system calls, i.e:
+<itemizedlist>
+ <listitem><para>It checks all the direct parameters
+ themselves.</para></listitem>
+ <listitem><para>Also, if a system call needs to read from a buffer provided
+ by your program, Memcheck checks that the entire buffer is addressible and
+ has valid data, ie, it is readable.</para></listitem>
+ <listitem><para>Also, if the system call needs to write to a user-supplied
+ buffer, Memcheck checks that the buffer is addressible.</para></listitem>
+</itemizedlist>
+</para>
-<para>Here's an example of a system call with an invalid
-parameter:</para>
-<programlisting><![CDATA[
-#include <stdlib.h>
-#include <unistd.h>
-int main( void )
-{
- char* arr = malloc(10);
- (void) write( 1 /* stdout */, arr, 10 );
- return 0;
-}]]></programlisting>
+<para>After the system call, Memcheck updates its tracked information to
+precisely reflect any changes in memory permissions caused by the system call.
+</para>
-<para>You get this complaint ...</para>
+<para>Here's an example of two system calls with invalid parameters:</para>
<programlisting><![CDATA[
-Syscall param write(buf) contains uninitialised or unaddressable byte(s)
- at 0x4035E072: __libc_write
- by 0x402A6E5E: __libc_start_main (libc-start.c:129)
- by 0x80483B1: (within tests/badwrite)
- by <bogus frame pointer> ???
- Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
- at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
- by 0x80484A0: main (tests/badwrite.c:6)
- by 0x402A6E5E: __libc_start_main (libc-start.c:129)
- by 0x80483B1: (within tests/badwrite)
+ #include <stdlib.h>
+ #include <unistd.h>
+ int main( void )
+ {
+ char* arr = malloc(10);
+ int* arr2 = malloc(sizeof(int));
+ write( 1 /* stdout */, arr, 10 );
+ exit(arr2[0]);
+ }
]]></programlisting>
-<para>... because the program has tried to write uninitialised
-junk from the malloc'd block to the standard output.</para>
+<para>You get these complaints ...</para>
+<programlisting><![CDATA[
+ Syscall param write(buf) points to uninitialised byte(s)
+ at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so)
+ by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so)
+ by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out)
+ Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd
+ at 0x259852B0: malloc (vg_replace_malloc.c:130)
+ by 0x80483F1: main (a.c:5)
+
+ Syscall param exit(error_code) contains uninitialised byte(s)
+ at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so)
+ by 0x8048426: main (a.c:8)
+]]></programlisting>
+
+<para>... because the program has (a) tried to write uninitialised junk from
+the malloc'd block to the standard output, and (b) passed an uninitialised
+value to <computeroutput>exit</computeroutput>. Note that the first error
+refers to the memory pointed to by <computeroutput>buf</computeroutput> (not
+<computeroutput>buf</computeroutput> itself), but the second error refers to
+the argument <computeroutput>error_code</computeroutput> itself.</para>
</sect2>
diff --git a/memcheck/docs/mc-tech-docs.xml b/memcheck/docs/mc-tech-docs.xml
index 492902c..cf37f31 100644
--- a/memcheck/docs/mc-tech-docs.xml
+++ b/memcheck/docs/mc-tech-docs.xml
@@ -22,7 +22,8 @@
<para>You may need to read this document several times, and
carefully. Some important things, I only say once.</para>
-
+<para>[Note: this document is now very old, and a lot of its contents are out
+of date, and misleading.]</para>
<sect2 id="mc-tech-docs.history" xreflabel="History">