-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.
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>
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
<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
<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>
<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>
<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
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
<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.
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
<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>
<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
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
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>
<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
<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>
<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>Here's an example of a system call with an invalid
-parameter:</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>After the system call, Memcheck updates its tracked information to
+precisely reflect any changes in memory permissions caused by the system call.
+</para>
+
+<para>Here's an example of two system calls with invalid parameters:</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>
+ #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>You get this complaint ...</para>
+<para>You get these complaints ...</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)
+ 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 tried to write uninitialised
-junk from the malloc'd block to the standard output.</para>
+<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>
projects / thirdparty / valgrind.git / commitdiff
