From: Nicholas Nethercote Date: Sat, 12 Mar 2005 22:14:42 +0000 (+0000) Subject: Documentation update. This should bring the core of the documentation X-Git-Tag: svn/VALGRIND_3_0_0~997 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6c7e08a8f5734728410a7e3131120102f0dc0f04;p=thirdparty%2Fvalgrind.git Documentation update. This should bring the core of the documentation up to date with reality. Please give this a proofread. I ran out of steam at memcheck/docs/mc_techdocs.html, which is even more hopelessly out of date. I will note that cacheprof.org is some kind of dental insurance company now... MERGED, PAINFULLY, FROM CVS HEAD git-svn-id: svn://svn.valgrind.org/valgrind/trunk@3321 --- diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index f072e4c613..b9f9587168 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -194,7 +194,10 @@ places: helpful when valgrinding a whole tree of processes at once, since it means that each process writes to its own logfile, rather than the result being jumbled up in one big - logfile. + logfile. If filename.pid12345 already + exists, then it will name new files + filename.pid12345.1 and so on. + If you want to specify precisely the file name to use, without the trailing @@ -292,9 +295,7 @@ error message is written to the commentary. For example: ==25832== Invalid read of size 4 ==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45) ==25832== by 0x80487AF: main (bogon.cpp:66) -==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129) -==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon) -==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]> +==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd]]> This message says that the program did an illegal 4-byte read of address 0xBFFFF74C, which, as far as Memcheck can tell, @@ -585,7 +586,7 @@ categories. --help-debug Same as --help, but also lists debugging options which usually are only of use - to developers. + to Valgrind's developers. @@ -866,10 +867,10 @@ Addrcheck), the following options apply. [default: 8] By default Valgrind's malloc, - realloc, etc, return 4-byte - aligned addresses. These are suitable for any accesses on + realloc, etc, return 8-byte + aligned addresses. This is standard for x86 processors. Some programs might however assume that - malloc et al return 8- or + malloc et al return 16- or more aligned memory. The supplied value must be between 4 and 4096 inclusive, and must be a power of two. @@ -962,9 +963,31 @@ Addrcheck), the following options apply. some device drivers with a large number of strange ioctl commands becomes very tiresome. + ioctl-mmap + Some ioctl requests can mmap new memory into your + process address space. If Valgrind doesn't know about these mappings, + it could put new mappings over them, and/or complain bitterly when + your program uses them. This option makes Valgrind scan the address + space for new mappings after each unknown ioctl has finished. You may + also need to run with + --pointercheck=no if the ioctl + decides to place the mapping out of the client's usual address space. + + + + --pointercheck=yes [default] + --pointercheck=no + This option make Valgrind generate a check on every memory + reference to make sure it is within the client's part of the + address space. This prevents stray writes from damaging + Valgrind itself. On x86, this uses the CPU's segmentation + machinery, and has almost no performance cost; there's almost + never a reason to turn it off. + + @@ -985,7 +1008,10 @@ Nevertheless: When enabled, each x86 insn is translated separately into instrumented code. When disabled, translation is done on a per-basic-block basis, giving much better - translations. + translations. This option is very useful if your program expects + precise exceptions (if it, for example, inspects or modifies register + state from within a signal handler). + @@ -1148,18 +1174,31 @@ custom checks. Clients need to include a header file to make this work. Which header file depends on which client requests you use. Some client requests are handled by the core, and are defined in the -header file valgrind.h. Tool-specific +header file valgrind/valgrind.h. Tool-specific header files are named after the tool, e.g. -memcheck.h. All header files can be found -in the include directory of wherever Valgrind +valgrind/memcheck.h. All header files can be found +in the include/valgrind directory of wherever Valgrind was installed. The macros in these header files have the magical property that they generate code in-line which Valgrind can spot. However, the code does nothing when not run on Valgrind, so you -are not forced to run your program on Valgrind just because you -use the macros in this file. Also, you are not required to link -your program with any extra supporting libraries. +are not forced to run your program under Valgrind just because you +use the macros in this file. Also, you are not required to link your +program with any extra supporting libraries. + +The code left in your binary has negligible performance impact. +However, if you really wish to compile out the client requests, you can +compile with -DNVALGRIND (analogous to +-DNDEBUG's effect on +assert()). + + +You are encouraged to copy the valgrind/*.h headers +into your project's include directory, so your program doesn't have a +compile-time dependency on Valgrind being installed. The Valgrind headers, +unlike the rest of the code, is under a BSD-style license so you may include +them without worrying about license incompatibility. Here is a brief description of the macros available in valgrind.h, which work with more than one @@ -1172,7 +1211,9 @@ tool-specific macros). RUNNING_ON_VALGRIND: returns 1 if running on Valgrind, 0 if running on the - real CPU. + real CPU. If you are running Valgrind under itself, it will return the + number of layers of Valgrind emulation we're running under. + @@ -1326,8 +1367,8 @@ in your client if you include a tool-specific header. - -Support for POSIX Pthreads + +Support for Threads Valgrind supports programs which use POSIX pthreads. Getting this to work was technically challenging but it all works @@ -1346,6 +1387,24 @@ implementing a truly multiprocessor version of Valgrind, but it does mean that threaded apps run only on one CPU, even if you have a multiprocessor machine. +Your program will use the native +libpthread, but not all of its facilities +will work. In particular, process-shared synchronization WILL NOT +WORK. They rely on special atomic instruction sequences which +Valgrind does not emulate in a way which works between processes. +Unfortunately there's no way for Valgrind to warn when this is happening, +and such calls will mostly work; it's only when there's a race will it fail. + + +Valgrind also supports direct use of the +clone() system call, +futex() and so on. +clone() is supported where either +everything is shared (a thread) or nothing is shared (fork-like); partial +sharing will fail. Again, any use of atomic instruction sequences in shared +memory between processes will not work. + + Valgrind schedules your threads in a round-robin fashion, with all threads having equal priority. It switches threads every 50000 basic blocks (typically around 300000 x86 @@ -1403,19 +1462,20 @@ Mozilla-0.9.2.1 and Galeon-0.11.3, both as supplied with RedHat Handling of Signals -Valgrind provides suitable handling of signals, so, -provided you stick to POSIX stuff, you should be ok. Basic -sigaction() and sigprocmask() are handled. Signal handlers may -return in the normal way or do longjmp(); both should work ok. -As specified by POSIX, a signal is blocked in its own handler. -Default actions for signals should work as before. Etc, -etc. - -Under the hood, dealing with signals is a real pain, and -Valgrind's simulation leaves much to be desired. If your program -does way-strange stuff with signals, bad things may happen. If -so, let us know. We don't promise to fix it, but we'd at least -like to be aware of it. +Valgrind has a fairly complete signal implementation. It should be +able to cope with any valid use of signals. + +If you're using signals in clever ways (for example, catching +SIGSEGV, modifying page state and restarting the instruction), you're +probably relying on precise exceptions. In this case, you will need +to use --single-step=yes. + +If your program dies as a result of a fatal core-dumping signal, +Valgrind will generate its own core file +(vgcore.pidNNNNN) containing your program's +state. You may use this core file for post-mortem debugging with gdb or +similar. (Note: it will not generate a core if your core dump size limit is +0.) @@ -1429,10 +1489,31 @@ like to be aware of it. make, make install mechanism, and we have attempted to ensure that it works on machines with kernel 2.4 or 2.6 and glibc -2.2.X or 2.3.X. I don't think there is much else to say. There -are no options apart from the usual ---prefix that you should give to -./configure. +2.2.X or 2.3.X. + +There are two options (in addition to the usual +--prefix= which affect how Valgrind is built: + + + --enable-pie + >PIE stands for "position-independent executable". This is + enabled by default if your toolchain supports it. PIE allows Valgrind + to place itself as high as possible in memory, giving your program as + much address space as possible. It also allows Valgrind to run under + itself. If PIE is disabled, Valgrind loads at a default address which + is suitable for most systems. This is also useful for debugging + Valgrind itself. + + + + --enable-tls + TLS (Thread Local Storage) is a relatively new mechanism which + requires compiler, linker and kernel support. Valgrind automatically test + if TLS is supported and enable this option. Sometimes it cannot test for + TLS, so this option allows you to override the automatic test. + + + The configure script tests the version of the X server currently indicated by the current @@ -1503,13 +1584,9 @@ the following constraints: - Pthreads support is improving, but there are still - significant limitations in that department. See the section - above on Pthreads. Note that your program must be dynamically - linked against libpthread.so, so that - Valgrind can substitute its own implementation at program - startup time. If you're statically linked against it, things - will fail badly. + Atomic instruction sequences are not supported, which will affect + any use of synchronization objects being shared between processes. They + will appear to work, but fail sporadically. @@ -1605,19 +1682,10 @@ the following constraints: - Known platform-specific limitations, as of release 1.0.0: + Known platform-specific limitations, as of release 2.4.0: - On Red Hat 7.3, there have been reports of link errors - (at program start time) for threaded programs using - __pthread_clock_gettime and - __pthread_clock_settime. - This appears to be due to - /lib/librt-2.2.5.so needing - them. Unfortunately I do not understand enough about this - problem to fix it properly, and I can't reproduce it on my - test RedHat 7.3 system. Please mail me if you have more - information / understanding. + (none) @@ -1637,44 +1705,41 @@ found . Getting started -Valgrind is compiled into a shared object, valgrind.so. -The shell script valgrind sets the LD_PRELOAD environment -variable to point to valgrind.so. This causes the .so to be -loaded as an extra library to any subsequently executed -dynamically-linked ELF binary, viz, the program you want to -debug. - -The dynamic linker allows each .so in the process image to -have an initialisation function which is run before main(). It -also allows each .so to have a finalisation function run after -main() exits. - -When valgrind.so's initialisation function is called by the -dynamic linker, the synthetic CPU to starts up. The real CPU -remains locked in valgrind.so for the entire rest of the program, -but the synthetic CPU returns from the initialisation function. -Startup of the program now continues as usual -- the dynamic -linker calls all the other .so's initialisation routines, and -eventually runs main(). This all runs on the synthetic CPU, not -the real one, but the client program cannot tell the -difference. - -Eventually main() exits, so the synthetic CPU calls -valgrind.so's finalisation function. Valgrind detects this, and -uses it as its cue to exit. It prints summaries of all errors -detected, possibly checks for memory leaks, and then exits the -finalisation routine, but now on the real CPU. The synthetic CPU -has now lost control -- permanently -- so the program exits back -to the OS on the real CPU, just as it would have done -anyway. - -On entry, Valgrind switches stacks, so it runs on its own -stack. On exit, it switches back. This means that the client -program continues to run on its own stack, so we can switch back -and forth between running it on the simulated and real CPUs -without difficulty. This was an important design decision, -because it makes it easy (well, significantly less difficult) to -debug the synthetic CPU. +Valgrind is compiled into two executables: +valgrind, and +stage2. +valgrind is a statically-linked executable +which loads at the normal address (0x8048000). +stage2 is a normal dynamically-linked +executable; it is either linked to load at a high address (0xb8000000) or is +a Position Independent Executable. + +Valgrind (also known as stage1): + + Decides where to load stage2. + Pads the address space with + mmap, leaving holes only where stage2 + should load. + Loads stage2 in the same manner as + execve() would, but + "manually". + Jumps to the start of stage2. + + +Once stage2 is loaded, it uses +dlopen() to load the tool, unmaps all +traces of stage1, initializes the client's state, and starts the synthetic +CPU. + +Each thread runs in its own kernel thread, and loops in +VG_(schedule) as it runs. When the thread +terminates, VG_(schedule) returns. Once +all the threads have terminated, Valgrind as a whole exits. + +Each thread also has two stacks. One is the client's stack, which +is manipulated with the client's instructions. The other is +Valgrind's internal stack, which is used by all Valgrind's code on +behalf of that thread. It is important to not get them confused. @@ -1775,11 +1840,10 @@ details. Signals -All system calls to sigaction() and sigprocmask() are -intercepted. If the client program is trying to set a signal -handler, Valgrind makes a note of the handler address and which -signal it is for. Valgrind then arranges for the same signal to -be delivered to its own handler. +All signal-related system calls are intercepted. If the client +program is trying to set a signal handler, Valgrind makes a note of the +handler address and which signal it is for. Valgrind then arranges for the +same signal to be delivered to its own handler. When such a signal arrives, Valgrind's own handler catches it, and notes the fact. At a convenient safe point in execution, @@ -1842,9 +1906,7 @@ sewardj@phoenix:~/newmat10$ ==25832== Invalid read of size 4 ==25832== at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45) ==25832== by 0x80487AF: main (bogon.cpp:66) -==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129) -==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon) -==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd +==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd ==25832== ==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0) ==25832== malloc/free: in use at exit: 0 bytes in 0 blocks. diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml index 844774b1d0..d0da42f437 100644 --- a/docs/xml/manual-intro.xml +++ b/docs/xml/manual-intro.xml @@ -154,14 +154,13 @@ platform: Linux on x86s. Valgrind uses the standard Unix ./configure, make, make install mechanism, and we have attempted to -ensure that it works on machines with kernel 2.2 or 2.4 and glibc -2.1.X, 2.2.X or 2.3.1. This should cover the vast majority of -modern Linux installations. Note that glibc-2.3.2+, with the -NPTL (Native Posix Threads Library) package won't work. We hope -to be able to fix this, but it won't be easy. +ensure that it works on machines with kernel 2.4 or 2.6 and glibc +2.1.X--2.3.X. Valgrind is licensed under the , -version 2. Some of the PThreads test cases, +version 2. The valgrind/*.h headers are +distributed under a BSD-style license, so you may include them in your code +without worrying about license conflicts. Some of the PThreads test cases, pth_*.c, are taken from "Pthreads Programming" by Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index b8186f1b80..c7fdaa5718 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -211,7 +211,7 @@ Invalid read of size 4 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9) by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326) by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621) - Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd + Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd ]]> This happens when your program reads or writes memory at a @@ -260,7 +260,6 @@ Conditional jump or move depends on uninitialised value(s) at 0x402DFA94: _IO_vfprintf (_itoa.h:49) by 0x402E8476: _IO_printf (printf.c:36) by 0x8048472: main (tests/manuel1.c:8) - by 0x402A6E5E: __libc_start_main (libc-start.c:129) ]]> An uninitialised-value use error is reported when your @@ -314,13 +313,9 @@ Memcheck complains. Invalid free() at 0x4004FFDF: free (vg_clientmalloc.c:577) by 0x80484C7: main (tests/doublefree.c:10) - by 0x402A6E5E: __libc_start_main (libc-start.c:129) - by 0x80483B1: (within tests/doublefree) - Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd + Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd at 0x4004FFDF: free (vg_clientmalloc.c:577) by 0x80484C7: main (tests/doublefree.c:10) - by 0x402A6E5E: __libc_start_main (libc-start.c:129) - by 0x80483B1: (within tests/doublefree) ]]> Memcheck keeps track of the blocks allocated by your @@ -350,7 +345,7 @@ Mismatched free() / delete / delete [] by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149) by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60) by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44) - Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd + Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152) by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314) by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416) @@ -496,8 +491,6 @@ overlap. Memcheck checks for this. ==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21) ==27492== at 0x40026CDC: memcpy (mc_replace_strmem.c:71) ==27492== by 0x804865A: main (overlap.c:40) -==27492== by 0x40246335: __libc_start_main (../sysdeps/generic/libc-start.c:129) -==27492== by 0x8048470: (within /auto/homes/njn25/grind/head6/memcheck/tests/overlap) ==27492== ]]> diff --git a/memcheck/docs/mc-tech-docs.xml b/memcheck/docs/mc-tech-docs.xml index cf37f314a6..be1b852dd0 100644 --- a/memcheck/docs/mc-tech-docs.xml +++ b/memcheck/docs/mc-tech-docs.xml @@ -34,8 +34,8 @@ it has been under contemplation for a very long time, perhaps seriously for about five years. Somewhat over two years ago, I started working on the x86 code generator for the Glasgow Haskell Compiler (http://www.haskell.org/ghc), gaining familiarity with -x86 internals on the way. I then did Cacheprof -(http://www.cacheprof.org), gaining further x86 experience. Some +x86 internals on the way. I then did Cacheprof, +gaining further x86 experience. Some time around Feb 2000 I started experimenting with a user-space x86 interpreter for x86-Linux. This worked, but it was clear that a JIT-based scheme would be necessary to give reasonable