From: Julian Seward Date: Wed, 23 Oct 2013 22:38:41 +0000 (+0000) Subject: Documentation updates for 3.9.0. X-Git-Tag: svn/VALGRIND_3_9_0~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5b2f9713514cebd0afc17a29a51ecc502119c56b;p=thirdparty%2Fvalgrind.git Documentation updates for 3.9.0. git-svn-id: svn://svn.valgrind.org/valgrind/branches/VALGRIND_3_9_BRANCH@13690 --- diff --git a/AUTHORS b/AUTHORS index e38c95a9b3..71f35aad6f 100644 --- a/AUTHORS +++ b/AUTHORS @@ -74,7 +74,10 @@ port. Dragos Tatulea modified the arm-android port so it also works on x86-android. -Jakub Jelinek helped out with the AVX support. +Jakub Jelinek helped out extensively with the AVX and AVX2 support. + +Mark Wielaard fixed a bunch of bugs and acts as our Fedora/RHEL +liaison. Many, many people sent bug reports, patches, and helpful feedback. diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index 4a80448510..28f7a86c46 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -1019,6 +1019,69 @@ that can report errors, e.g. Memcheck, but not Cachegrind. + + + + + + + + + Stack-scanning support is available only on ARM + targets. + + These flags enable and control stack unwinding by stack + scanning. When the normal stack unwinding mechanisms -- usage + of Dwarf CFI records, and frame-pointer following -- fail, stack + scanning may be able to recover a stack trace. + + Note that stack scanning is an imprecise, heuristic + mechanism that may give very misleading results, or none at all. + It should be used only in emergencies, when normal unwinding + fails, and it is important to nevertheless have stack + traces. + + Stack scanning is a simple technique: the unwinder reads + words from the stack, and tries to guess which of them might be + return addresses, by checking to see if they point just after + ARM or Thumb call instructions. If so, the word is added to the + backtrace. + + The main danger occurs when a function call returns, + leaving its return address exposed, and a new function is + called, but the new function does not overwrite the old address. + The result of this is that the backtrace may contain entries for + functions which have already returned, and so be very + confusing. + + A second limitation of this implementation is that it will + scan only the page (4KB, normally) containing the starting stack + pointer. If the stack frames are large, this may result in only + a few (or not even any) being present in the trace. Also, if + you are unlucky and have an initial stack pointer near the end + of its containing page, the scan may miss all interesting + frames. + + By default stack scanning is disabled. The normal use + case is to ask for it when a stack trace would otherwise be very + short. So, to enable it, + use --unw-stack-scan-thresh=number. + This requests Valgrind to try using stack scanning to "extend" + stack traces which contain fewer + than number frames. + + If stack scanning does take place, it will only generate + at most the number of frames specified + by --unw-stack-scan-frames. + Typically, stack scanning generates so many garbage entries that + this value is set to a low value (5) by default. In no case + will a stack trace larger than the value specified + by --num-callers be + created. + + + @@ -1057,17 +1120,19 @@ that can report errors, e.g. Memcheck, but not Cachegrind. is given. The default can always be explicitly overridden by giving this option. - When enabled a warning message will be printed with some - diagnostics whenever some instruction is encountered that valgrind - cannot decode or translate before the program is given a SIGILL signal. + When enabled, a warning message will be printed, along with some + diagnostics, whenever an instruction is encountered that Valgrind + cannot decode or translate, before the program is given a SIGILL signal. Often an illegal instruction indicates a bug in the program or missing - support for the particular instruction in Valgrind. But some programs + support for the particular instruction in Valgrind. But some programs do deliberately try to execute an instruction that might be missing - and trap the SIGILL signal to detect processor features. + and trap the SIGILL signal to detect processor features. Using + this flag makes it possible to avoid the diagnostic output + that you would otherwise get in such cases. - + @@ -1173,6 +1238,83 @@ that can report errors, e.g. Memcheck, but not Cachegrind. + + + + + + This is a new, experimental, feature introduced in version + 3.9.0. + + In some scenarios it may be convenient to read debuginfo + from objects stored on a different machine. With this flag, + Valgrind will query a debuginfo server running + on ipaddr and listening on + port port, if it cannot find + the debuginfo object in the local filesystem. + + The debuginfo server must accept TCP connections on + port port. The debuginfo + server is contained in the source + file auxprogs/valgrind-di-server.c. + It will only serve from the directory it is started + in. port defaults to 1500 in + both client and server if not specified. + + If Valgrind looks for the debuginfo for + /w/x/y/zz.so by using the + debuginfo server, it will strip the pathname components and + merely request zz.so on the + server. That in turn will look only in its current working + directory for a matching debuginfo object. + + The debuginfo data is transmitted in small fragments (8 + KB) as requested by Valgrind. Each block is compressed using + LZO to reduce transmission time. The implementation has been + tuned for best performance over a single-stage 802.11g (WiFi) + network link. + + Note that checks for matching primary vs debug objects, + using GNU debuglink CRC scheme, are performed even when using + the debuginfo server. To disable such checking, you need to + also specify + --allow-mismatched-debuginfo=yes. + + + By default the Valgrind build system will + build valgrind-di-server for + the target platform, which is almost certainly not what you + want. So far we have been unable to find out how to get + automake/autoconf to build it for the build platform. If + you want to use it, you will have to recompile it by hand using + the command shown at the top + of auxprogs/valgrind-di-server.c. + + + + + + + + + When reading debuginfo from separate debuginfo objects, + Valgrind will by default check that the main and debuginfo + objects match, using the GNU debuglink mechanism. This + guarantees that it does not read debuginfo from out of date + debuginfo objects, and also ensures that Valgrind can't crash as + a result of mismatches. + + This check can be overridden using + --allow-mismatched-debuginfo=yes. + This may be useful when the debuginfo and main objects have not + been split in the proper way. Be careful when using this, + though: it disables all consistency checking, and Valgrind has + been observed to crash when the main and debuginfo objects don't + match. + + + @@ -1824,14 +1966,16 @@ need to use them. - Some recursive algorithms (such as balanced binary tree - implementations) have the property to create many different - stack traces, containing cycles of calls. A cycle is defined by - two identical program counters separated by 0 or more other - program counters. Valgrind might then use a lot of memory to - record these stack traces, containing repeated uninteresting - recursive calls instead of more interesting information such as - the function that has initiated the recursive call. + Some recursive algorithms, for example balanced binary + tree implementations, create many different stack traces, each + containing cycles of calls. A cycle is defined as two identical + program counter values separated by zero or more other program + counter values. Valgrind may then use a lot of memory to store + all these stack traces. This is a poor use of memory + considering that such stack traces contain repeated + uninteresting recursive calls instead of more interesting + information such as the function that has initiated the + recursive call. The option instructs Valgrind to detect and merge recursive call cycles @@ -1843,27 +1987,29 @@ need to use them. The value 0 (the default) causes no recursive call merging. A value of 1 will cause stack traces of simple recursive algorithms (for example, a factorial implementation) to be collapsed. - A value of 2 will usually be needed to collapsed stack traces produced - by recursive algorithms such as binary trees, quick sort, ... + A value of 2 will usually be needed to collapse stack traces produced + by recursive algorithms such as binary trees, quick sort, etc. Higher values might be needed for more complex recursive algorithms. - Note: recursive calls are detected based on program counters. - The cycles are not detected based on function names. + Note: recursive calls are detected by analysis of program + counter values. They are not detected by looking at function + names. - + Valgrind translates and instruments your program's machine code in small fragments. The translations are stored in a translation cache that is divided into a number of sections (sectors). If the cache is full, the sector containing the - oldest translations is emptied and recycled. If these old + oldest translations is emptied and reused. If these old translations are needed again, Valgrind must re-translate and - re-instrument the corresponding program code, which is + re-instrument the corresponding machine code, which is expensive. If the "executed instructions" working set of a program is big, increasing the number of sectors may improve performance by reducing the number of re-translations needed. diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml index 29a337f40e..1433d06027 100644 --- a/docs/xml/vg-entities.xml +++ b/docs/xml/vg-entities.xml @@ -2,12 +2,12 @@ - + - - + + diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 304407e4f2..b5276a46aa 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -604,10 +604,10 @@ more details about how a block is still reachable. The option controls the set of leak kinds to show -if is specified. +when is specified. -The of leak kinds is specified by -using one of the following forms: +The of leak kinds is specified +in one of the following ways: a comma separated list of one or more of @@ -617,7 +617,7 @@ using one of the following forms: to specify the complete set (all leak kinds). - is the empty set. + for the empty set. @@ -627,12 +627,13 @@ using one of the following forms: . -To also show the reachable and indirectly lost blocks in addition to the definitely -and possibly lost blocks, you can use . -To only show the reachable and indirectly lost blocks, use -. -The reachable and indirectly lost blocks will then be presented as the following -two examples show. +To also show the reachable and indirectly lost blocks in +addition to the definitely and possibly lost blocks, you can +use . To only show the +reachable and indirectly lost blocks, use +. The reachable +and indirectly lost blocks will then be presented as shown in +the following two examples. ]]> Because there are different kinds of leaks with different -severities, an interesting question is this: which leaks should be +severities, an interesting question is: which leaks should be counted as true "errors" and which should not? @@ -716,8 +717,8 @@ is - Specifies the leak kinds to show in a full leak search by - using one of the following forms: + Specifies the leak kinds to show in a full leak search, in + one of the following ways: a comma separated list of one or more of @@ -729,7 +730,7 @@ is . - is the empty set. + for the empty set. @@ -755,10 +756,11 @@ is - Specifies the leak check heuristics to use during leak search - to discover interior pointers with which a block should be considered - as reachable. The heuristic set is specified by using one of the - following forms: + Specifies the set of leak check heuristics to be used + during + leak searches. The heuristics control which interior pointers + to a block cause it to be considered as reachable. + The heuristic set is specified in one of the following ways: a comma separated list of one or more of @@ -771,7 +773,7 @@ is . - is the empty set. + for the empty set. @@ -886,8 +888,8 @@ is - Controls how Memcheck handles word-sized, - word-aligned loads from addresses for which some bytes are + Controls how Memcheck handles 32-, 64-, 128- and 256-bit + naturally aligned loads from addresses for which some bytes are addressable and others are not. When yes, such loads do not produce an address error. Instead, loaded bytes originating from illegal addresses are marked as uninitialised, and @@ -915,46 +917,47 @@ is free'd blocks. - With alloc-then-free, the malloc stack - trace is recorded at allocation time. The block contains a - reference to this allocation stack trace. When the block is - freed, the block will then reference the free stack trace. So, - a 'use after free' error will only report the free stack trace. + With alloc-then-free, a stack trace is + recorded at allocation time, and is associated with the block. + When the block is freed, a second stack trace is recorded, and + this replaces the allocation stack trace. As a result, any "use + after free" errors relating to this block can only show a stack + trace for where the block was freed. - With alloc-and-free, both the malloc - and the free stack trace (for freed block) are recorded and - referenced by the block. A 'use after free' error will report - the free stack trace, followed by the stack trace where this - block was allocated. Compared - to alloc-then-free, this value very slightly - increases Valgrind memory use as the block contains two references - instead of one. + With alloc-and-free, both allocation + and the deallocation stack traces for the block are stored. + Hence a "use after free" error will + show both, which may make the error easier to diagnose. + Compared to alloc-then-free, this setting + slightly increases Valgrind's memory use as the block contains two + references instead of one. - With alloc, only the malloc stack trace - is recorded (and reported). With free, only - the free stack trace is recorded (and reported). These values - somewhat decrease Valgrind memory and cpu usage. They can be - useful depending on the error types you are searching for and - the level of details you need to analyse them. For example, if - you are only interested in memory leak errors, it is sufficient - to record the allocation stack traces. + With alloc, only the allocation stack + trace is recorded (and reported). With free, + only the deallocation stack trace is recorded (and reported). + These values somewhat decrease Valgrind's memory and cpu usage. + They can be useful depending on the error types you are + searching for and the level of detail you need to analyse + them. For example, if you are only interested in memory leak + errors, it is sufficient to record the allocation stack traces. With none, no stack traces are recorded for malloc and free operations. If your program allocates a lot - of blocks and/or from many different stack traces, this can - significantly decrease cpu and/or memory. Of course, very little - details will be reported for errors related to heap blocks. + of blocks and/or allocates/frees from many different stack + traces, this can significantly decrease cpu and/or memory + required. Of course, few details will be reported for errors + related to heap blocks. - Note that once a stack trace is recorded, Valgrind keeps - the stack trace in memory even if not referenced anymore by - any block. Some programs (for example, recursive algorithms) - can generate a huge number of stack traces. If Valgrind uses too + Note that once a stack trace is recorded, Valgrind keeps + the stack trace in memory even if it is not referenced by any + block. Some programs (for example, recursive algorithms) can + generate a huge number of stack traces. If Valgrind uses too much memory in such circumstances, you can reduce the memory - usage with the options --keep-stacktraces + required with the options --keep-stacktraces and/or by using a smaller value for the option --num-callers.