From: Julian Seward Date: Tue, 15 Nov 2005 20:56:23 +0000 (+0000) Subject: Complete documentation trawl for 3.1.0. X-Git-Tag: svn/VALGRIND_3_1_0~95 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d07dbe4a5206f4f1e761eecd5788e611bf4921da;p=thirdparty%2Fvalgrind.git Complete documentation trawl for 3.1.0. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5137 --- diff --git a/addrcheck/docs/ac-manual.xml b/addrcheck/docs/ac-manual.xml index bf55c371ba..d5108d031b 100644 --- a/addrcheck/docs/ac-manual.xml +++ b/addrcheck/docs/ac-manual.xml @@ -9,6 +9,9 @@ --tool=addrcheck on the Valgrind command line. +Note: Addrcheck does not work in Valgrind 3.1.0. We may +reinstate it in later releases. + Kinds of bugs that Addrcheck can find @@ -16,7 +19,7 @@ command line. described in Section 3. It is identical in every way to Memcheck, except for one important detail: it does not do the undefined-value checks that Memcheck does. This means Addrcheck -is about twice as fast as Memcheck, and uses less memory. +is faster than Memcheck, and uses less memory. Addrcheck can detect the following errors: @@ -42,14 +45,11 @@ Addrcheck can detect the following errors: memcpy() and related functions - - Some misuses of the POSIX pthreads API - -Rather than duplicate much of the Memcheck docs here -(a.k.a. since I am a lazy b'stard), users of Addrcheck are +Rather than duplicate much of the Memcheck docs here, +users of Addrcheck are advised to read . Some important points: @@ -98,13 +98,6 @@ or not that location may validly be addressed. Addrcheck has a memory overhead of one bit per byte of used address space. In contrast, Memcheck has an overhead of nine bits per byte. -Due to lazyness on the part of the implementor (Julian), -error messages from Addrcheck do not distinguish reads from -writes. So it will say, for example, "Invalid memory access of -size 4", whereas Memcheck would have said whether the access is a -read or a write. This could easily be remedied, if anyone is -particularly bothered. - Addrcheck is quite pleasant to use. It's faster than Memcheck, and the lack of valid-value checks has another side effect: the errors it does report are relatively easy to track @@ -112,20 +105,6 @@ down, compared to the tedious and often confusing search sometimes needed to find the cause of uninitialised-value errors reported by Memcheck. -Because it is faster and lighter than Memcheck, our hope is -that Addrcheck is more suitable for less-intrusive, larger scale -testing than is viable with Memcheck. As of mid-November 2002, -we have experimented with running the KDE-3.1 desktop on -Addrcheck (the entire process tree, starting from -startkde). Running on a 512MB, -1.7 GHz P4, the result is nearly usable. The ultimate aim is -that is fast and unintrusive enough that (eg) KDE sessions may be -unintrusively monitored for addressing errors whilst people do -real work with their KDE desktop. - -Addrcheck is a new experiment in the Valgrind world. We'd -be interested to hear your feedback on it. - diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 88b93e8078..52f630098f 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -288,9 +288,9 @@ file: -Note that older versions of Cachegrind used a log file -named cachegrind.out (i.e. no -.pid suffix). The suffix serves +The .pid suffix +on the output file name +serves two purposes. Firstly, it means you don't have to rename old log files that you don't want to overwrite. Secondly, and more importantly, it allows correct profiling with the @@ -605,7 +605,7 @@ for distinguishing between an event which cannot happen, and one which can but did not. Sometimes only a small section of a source file is -executed. To minimise uninteresting output, Valgrind only shows +executed. To minimise uninteresting output, Cachegrind only shows annotated lines and lines within a small distance of annotated lines. Gaps are marked with the line numbers so you know which part of a file the shown code comes from, eg: @@ -761,7 +761,7 @@ way as for C/C++ programs. - -I=<dir>, + -I<dir>, --include=<dir> [default: empty string] Adds a directory to the list in which to search for @@ -955,13 +955,13 @@ shortcomings: - Valgrind's custom threads implementation will schedule - threads differently to the standard one. This could warp the - results for threaded programs. + Valgrind will schedule + threads differently from how they would be when running natively. + This could warp the results for threaded programs. - The instructions bts, + The x86/amd64 instructions bts, btr and btc will incorrectly be counted as doing a data read if both the arguments are @@ -973,7 +973,7 @@ shortcomings: - FPU instructions with data sizes of 28 and 108 bytes + x86/amd64 FPU instructions with data sizes of 28 and 108 bytes (e.g. fsave) are treated as though they only access 16 bytes. These instructions seem to be rare so hopefully this won't affect accuracy much. diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml index 390085b4e9..2e1b8974fb 100644 --- a/docs/xml/FAQ.xml +++ b/docs/xml/FAQ.xml @@ -7,7 +7,7 @@ Valgrind FAQ Valgrind Frequently Asked Questions - August 2005 + November 2005 Valgrind Developers @@ -102,21 +102,8 @@ Programs run OK on Valgrind, but at exit produce a bunch - of errors a bit like this: - -==20755== Invalid read of size 4 -==20755== at 0x40281C8A: _nl_unload_locale (loadlocale.c:238) -==20755== by 0x4028179D: free_mem (findlocale.c:257) -==20755== by 0x402E0962: __libc_freeres (set-freeres.c:34) -==20755== by 0x40048DCC: vgPlain___libc_freeres_wrapper (vg_clientfuncs.c:585) -==20755== Address 0x40CC304C is 8 bytes inside a block of size 380 free'd -==20755== at 0x400484C9: free (vg_clientfuncs.c:180) -==20755== by 0x40281CBA: _nl_unload_locale (loadlocale.c:246) -==20755== by 0x40281218: free_mem (setlocale.c:461) -==20755== by 0x402E0962: __libc_freeres (set-freeres.c:34) - - - and then die with a segmentation fault. + of errors involving __libc_freeres() + and then die with a segmentation fault. When the program exits, Valgrind runs the procedure @@ -223,30 +210,6 @@ Valgrind behaves unexpectedly - - - My threaded server process runs unbelievably slowly on - Valgrind. So slowly, in fact, that at first I thought it had - completely locked up. - - - We are not completely sure about this, but one - possibility is that laptops with power management fool - Valgrind's timekeeping mechanism, which is (somewhat in error) - based on the x86 RDTSC instruction. A "fix" which is claimed - to work is to run some other cpu-intensive process at the same - time, so that the laptop's power-management clock-slowing does - not kick in. We would be interested in hearing more feedback - on this. - - Another possible cause is that versions prior to 1.9.6 - did not support threading on glibc 2.3.X systems well. - Hopefully the situation is much improved with 1.9.6 and later - versions. - - - - My program uses the C++ STL and string classes. Valgrind diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index 385b60a9cf..efea0124c2 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -8,7 +8,10 @@ Helgrind is a Valgrind tool for detecting data races in C and C++ programs that use the Pthreads library. -To use this tool, you specify +Note: Helgrind does not work in Valgrind 3.1.0. We hope +to reinstate in version 3.2.0. + +To use this tool, you must specify --tool=helgrind on the Valgrind command line. diff --git a/lackey/docs/lk-manual.xml b/lackey/docs/lk-manual.xml index c911f16cfc..d97100641e 100644 --- a/lackey/docs/lk-manual.xml +++ b/lackey/docs/lk-manual.xml @@ -5,6 +5,11 @@ Lackey: a very simple profiler + +To use this tool, you must specify +--tool=lackey on the Valgrind +command line. + Lackey is a simple Valgrind tool that does some basic program measurement. It adds quite a lot of simple instrumentation to the program's code. It is primarily intended diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index 6fd765bbb1..e9e0eb99fd 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -28,8 +28,8 @@ memory, this provides the following benefits: It can speed up your program -- a smaller - program will interact better with your machine's caches, - avoid paging, and so on. + program will interact better with your machine's caches and + avoid paging. If your program uses lots of memory, it will reduce the chance that it exhausts your machine's swap @@ -188,7 +188,7 @@ a PostScript viewer. hp2ps to convert the raw data into the PostScript graph. It's distributed with Massif, but came originally from the -Glasgow Haskell +Glasgow Haskell Compiler. You shouldn't need to worry about this at all. However, if the graph creation fails for any reason, Massif will tell you, and will leave behind a file named diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 06b9d459f9..226eaacfd2 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -5,9 +5,10 @@ Memcheck: a heavyweight memory checker -To use this tool, you must specify +To use this tool, you may specify --tool=memcheck on the Valgrind -command line. +command line. You don't have to, though, since Memcheck is the default +tool. C) or delete (C++), that memory is not immediately made available for re-allocation. Instead it is marked inaccessible and placed - in a queue of freed blocks. The purpose is to delay the + in a queue of freed blocks. The purpose is to defer + as long as possible + the point at which freed-up memory comes back into circulation. This increases the chance that Memcheck will be able to detect invalid accesses to blocks for some significant period of time after they have been freed. This flag specifies the maximum total size, in bytes, - of the blocks in the queue. The default value is one million + of the blocks in the queue. The default value is five million bytes. Increasing this increases the total amount of memory used by Memcheck but may detect invalid uses of freed blocks which would otherwise go undetected. @@ -142,16 +145,11 @@ Memcheck can detect the following problems: distance below the stack pointer are due to bugs in gcc 2.96, and does not report them. The "small distance" is 256 bytes by default. Note that gcc 2.96 is the default compiler - on some popular Linux distributions (RedHat 7.X, Mandrake) - and so you may well need to use this flag. Do not use it if + on some older Linux distributions (RedHat 7.X) + and so you may need to use this flag. Do not use it if you do not have to, as it can cause real errors to be - overlooked. Another option is to use a gcc/g++ which does - not generate accesses below the stack pointer. 2.95.3 seems - to be a good choice in this respect. - Unfortunately (27 Feb 02) it looks like g++ 3.0.4 has a - similar bug, so you may need to issue this flag if you use - 3.0.4. A while later (early Apr 02) this is confirmed as a - scheduling bug in g++-3.0.4. + overlooked. A better alternative is to use a more recent gcc/g++ in which + this bug is fixed. @@ -186,7 +184,7 @@ Memcheck can detect the following problems: Explanation of error messages from Memcheck Despite considerable sophistication under the hood, -Memcheck can only really detect two kinds of errors, use of +Memcheck can only really detect two kinds of errors: use of illegal addresses, and use of undefined values. Nevertheless, this is enough to help you discover all sorts of memory-management nasties in your code. This section presents a @@ -230,7 +228,7 @@ Actually the address is on the stack, but, for some reason, this is not a valid stack address -- it is below the stack pointer and that isn't allowed. In this particular case it's probably caused by gcc generating invalid -code, a known bug in various versions of gcc. +code, a known bug in some ancient versions of gcc. Note that Memcheck only tells you that your program is about to access memory at an illegal address. It can't stop the @@ -270,7 +268,7 @@ int main() }]]> It is important to understand that your program can copy -around junk (uninitialised) data to its heart's content. +around junk (uninitialised) data as much as it likes. Memcheck observes this and keeps track of the data, but does not complain. A complaint is issued only when your program attempts to make use of uninitialised data. In this example, x is @@ -347,10 +345,6 @@ Mismatched free() / delete / delete [] by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272) ]]> -The following was told to me be the KDE 3 developers. I -didn't know any of it myself. They also implemented the check -itself. - In C++ it's important to deallocate memory in a way compatible with how it was allocated. The deal is: @@ -384,8 +378,8 @@ to the KDE folks "it's amazing how many C++ programmers don't know this". Pascal Massimino adds the following clarification: -delete[] must be called -associated with a new[] because +delete[] must be used for +objects allocated by new[] because the compiler stores the size of the array and the pointer-to-member to the destructor of the array's content just before the pointer actually returned. This implies a @@ -402,7 +396,7 @@ variable-sized overhead in what's returned by Passing system call parameters with inadequate read/write permissions -Memcheck checks all parameters to system calls, i.e: +Memcheck checks all parameters to system calls: It checks all the direct parameters themselves. @@ -517,8 +511,8 @@ Each block fits into one of the three following categories. Still reachable: A pointer to the start of the block is found. This usually indicates programming - sloppiness; since the block is still pointed at, the - programmer could, at least in principle, free'd it before + sloppiness. Since the block is still pointed at, the + programmer could, at least in principle, free it before program exit. Because these are very common and arguably not a problem, Memcheck won't report such blocks unless --show-reachable=yes is @@ -558,7 +552,8 @@ programs do not have any leaked or dubious blocks at exit. by 0x........: mk (leak-tree.c:11) by 0x........: main (leak-tree.c:39) -88 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14 +88 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost + in loss record 13 of 14 at 0x........: malloc (vg_replace_malloc.c:...) by 0x........: mk (leak-tree.c:11) by 0x........: main (leak-tree.c:25) @@ -572,7 +567,7 @@ indirect leak is a block which is only pointed to by other leaked blocks. Both kinds of leak are bad. The precise area of memory in which Memcheck searches for -pointers is: all naturally-aligned 4-byte words for which all A +pointers is: all naturally-aligned machine-word-sized words for which all A bits indicate addressibility and all V bits indicated that the stored value is actually valid. @@ -702,7 +697,7 @@ bitmap. In short, each bit in the system has an associated V bit, which follows it around everywhere, even inside the CPU. Yes, -all the CPU's registers (integer, floating point, and condition +all the CPU's registers (integer, floating point, vector and condition registers) have their own V bit vectors. Copying values around does not cause Memcheck to check for, @@ -861,7 +856,7 @@ bits, only consult them. When doing system calls, A bits are changed appropriately. For example, mmap() magically makes files - appear in the process's address space, so the A bits must be + appear in the process' address space, so the A bits must be updated if mmap() succeeds. @@ -956,13 +951,14 @@ follows: Memcheck intercepts calls to malloc, calloc, realloc, -valloc, memalign, free, new and delete. The behaviour you get +valloc, memalign, free, new, new[], delete and delete[]. +The behaviour you get is: - malloc/new: the returned memory is marked as + malloc/new/new[]: the returned memory is marked as addressible but not having valid values. This means you have to write on it before you can read it. @@ -985,9 +981,10 @@ is: - free/delete: you may only pass to free a pointer - previously issued to you by malloc/calloc/realloc, or the - value NULL. Otherwise, Valgrind complains. If the pointer is + free/delete/delete[]: you may only pass to these + functions a pointer + previously issued to you by the corresponding allocation function. + Otherwise, Valgrind complains. If the pointer is indeed valid, Valgrind marks the entire area it points at as unaddressible, and places the block in the freed-blocks-queue. The aim is to defer as long as possible @@ -1084,7 +1081,8 @@ arguments. you to get and set the V (validity) bits for an address range. You should probably only set V bits that you have got with VALGRIND_GET_VBITS. - Only for those who really know what they are doing. + Only for those who really know what they are doing. Note: currently + disabled in Valgrind 3.1.0.