diff --git a/addrcheck/docs/ac-manual.xml b/addrcheck/docs/ac-manual.xml index ff3b4ffdd..8ba188e17 100644 --- a/addrcheck/docs/ac-manual.xml +++ b/addrcheck/docs/ac-manual.xml @@ -2,25 +2,24 @@ + Addrcheck: a lightweight memory checker To use this tool, you must specify ---tool=addrcheck on the Valgrind -command line. + on the Valgrind command line. -Note: Addrcheck does not work in Valgrind 3.1.0. We may -reinstate it in later releases. +Note: Addrcheck does not work in Valgrind 3.1.0. We may reinstate +it in later releases. Kinds of bugs that Addrcheck can find -Addrcheck is a simplified version of the Memcheck tool -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 faster than Memcheck, and uses less memory. -Addrcheck can detect the following errors: +Addrcheck is a simplified version of the Memcheck tool 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 faster than Memcheck, and uses +less memory. Addrcheck can detect the following errors: @@ -33,7 +32,7 @@ Addrcheck can detect the following errors: Reading/writing inappropriate areas on the stack - Memory leaks -- where pointers to malloc'd blocks are lost + Memory leaks - where pointers to malloc'd blocks are lost forever @@ -48,61 +47,56 @@ Addrcheck can detect the following errors: -Rather than duplicate much of the Memcheck docs here, -users of Addrcheck are advised to read . -Some important points: +Rather than duplicate much of the Memcheck docs here, users of +Addrcheck are advised to read . Some +important points: Addrcheck is exactly like Memcheck, except that all the - value-definedness tracking machinery has been removed. - Therefore, the Memcheck documentation which discusses - definedess ("V-bits") is irrelevant. The stuff on - addressibility ("A-bits") is still relevant. + value-definedness tracking machinery has been removed. Therefore, + the Memcheck documentation which discusses definedess ("V-bits") is + irrelevant. The stuff on addressibility ("A-bits") is still + relevant. - Addrcheck accepts the same command-line flags as - Memcheck, with the exception of ... (to be filled in). + Addrcheck accepts the same command-line flags as Memcheck, + with the exception of ... (to be filled in). Like Memcheck, Addrcheck will do memory leak checking - (internally, the same code does leak checking for both - tools). The only difference is how the two tools decide - which memory locations to consider when searching for - pointers to blocks. Memcheck will only consider 4-byte - aligned locations which are validly addressible and which - hold defined values. Addrcheck does not track definedness - and so cannot apply the last, "defined value", - criteria. + (internally, the same code does leak checking for both tools). The + only difference is how the two tools decide which memory locations + to consider when searching for pointers to blocks. Memcheck will + only consider 4-byte aligned locations which are validly addressible + and which hold defined values. Addrcheck does not track definedness + and so cannot apply the last, "defined value", criteria. - The result is that Addrcheck's leak checker may - "discover" pointers to blocks that Memcheck would not. So it - is possible that Memcheck could (correctly) conclude that a - block is leaked, yet Addrcheck would not conclude - that. + The result is that Addrcheck's leak checker may "discover" + pointers to blocks that Memcheck would not. So it is possible that + Memcheck could (correctly) conclude that a block is leaked, yet + Addrcheck would not conclude that. - Whether or not this has any effect in practice is - unknown. I suspect not, but that is mere speculation at this - stage. + Whether or not this has any effect in practice is unknown. I + suspect not, but that is mere speculation at this stage. -Addrcheck is, therefore, a fine-grained address checker. -All it really does is check each memory reference to say whether -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. +Addrcheck is, therefore, a fine-grained address checker. All it +really does is check each memory reference to say whether 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. -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 -down, compared to the tedious and often confusing search -sometimes needed to find the cause of uninitialised-value errors -reported by Memcheck. +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 down, compared to the +tedious and often confusing search sometimes needed to find the cause of +uninitialised-value errors reported by Memcheck. diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 5b3f47968..2e49b147d 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -2,6 +2,7 @@ + Cachegrind: a cache profiler @@ -302,28 +303,54 @@ programs that spawn child processes. Cachegrind options + +Manually specifies the I1/D1/L2 cache +configuration, where size and +line_size are measured in bytes. The three items +must be comma-separated, but with no spaces, eg: + valgrind --tool=cachegrind --I1=65535,2,64 + +You can specify one, two or three of the I1/D1/L2 caches. Any level not +manually specified will be simulated using the configuration found in +the normal way (via the CPUID instruction for automagic cache +configuration, or failing that, via defaults). + Cache-simulation specific options are: -,, ---D1=,, ---L2=,, + -[default: uses CPUID for automagic cache configuration]]]> + + + + + + Specify the size, associativity and line size of the level 1 + instruction cache. + + -Manually specifies the I1/D1/L2 cache configuration, where -size and -line_size are measured in bytes. -The three items must be comma-separated, but with no spaces, -eg: + + + + + + Specify the size, associativity and line size of the level 1 + data cache. + + - + + + + + + Specify the size, associativity and line size of the level 2 + cache. + + -You can specify one, two or three of the I1/D1/L2 caches. -Any level not manually specified will be simulated using the -configuration found in the normal way (via the CPUID instruction, -or failing that, via defaults). + + @@ -338,10 +365,10 @@ wide if possible, as the output lines can be quite long. To get a function-by-function summary, run cg_annotate --pid in a directory -containing a cachegrind.out.pid -file. The --pid is required so that -cg_annotate knows which log file -to use when several are present. +containing a cachegrind.out.pid file. The +--pid is required so that +cg_annotate knows which log file to use +when several are present. The output looks like this: @@ -501,8 +528,7 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function Then follows summary statistics for the whole program. These are similar to the summary provided when running -valgrind ---tool=cachegrind. +valgrind --tool=cachegrind. Then follows function-by-function statistics. Each function is identified by a diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index c8257206d..2db084a8a 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -559,9 +559,10 @@ categories. Basic Options -These options work with all tools. + +These options work with all tools. - + @@ -743,6 +744,7 @@ categories. + @@ -750,10 +752,11 @@ categories. Error-related options -These options are used by all tools that can report -errors, e.g. Memcheck, but not Cachegrind. + +These options are used by all tools +that can report errors, e.g. Memcheck, but not Cachegrind. - + @@ -1011,6 +1014,7 @@ errors, e.g. Memcheck, but not Cachegrind. + @@ -1018,11 +1022,12 @@ errors, e.g. Memcheck, but not Cachegrind. <computeroutput>malloc()</computeroutput>-related Options -For tools that use their own version of + +For tools that use their own version of malloc() (e.g. Memcheck and Addrcheck), the following options apply. - + @@ -1039,6 +1044,7 @@ Addrcheck), the following options apply. + @@ -1046,11 +1052,12 @@ Addrcheck), the following options apply. Uncommon Options -These options apply to all tools, as they affect certain obscure -workings of the Valgrind core. Most people won't need to use -these. + +These options apply to all tools, as they +affect certain obscure workings of the Valgrind core. Most people won't +need to use these. - + @@ -1161,6 +1168,7 @@ these. + @@ -1168,10 +1176,12 @@ these. Debugging Valgrind Options -There are also some options for debugging Valgrind itself. -You shouldn't need to use them in the normal run of things. If you -wish to see the list, use the --help-debug -option. + +There are also some options for debugging +Valgrind itself. You shouldn't need to use them in the normal run of +things. If you wish to see the list, use the + option. + diff --git a/docs/xml/valgrind-manpage.xml b/docs/xml/valgrind-manpage.xml index 4ea3ac074..e86ebb37d 100644 --- a/docs/xml/valgrind-manpage.xml +++ b/docs/xml/valgrind-manpage.xml @@ -112,9 +112,10 @@ leaks. Basic Options -These options work with all tools. + - @@ -124,10 +125,10 @@ leaks. Error-Related Options -These options are used by all tools that can report errors, -e.g. Memcheck, but not Cachegrind. + - @@ -137,11 +138,10 @@ e.g. Memcheck, but not Cachegrind. malloc()-related Options -For tools that use their own version of -malloc() (e.g. Memcheck and Addrcheck), the -following options apply. + - @@ -151,11 +151,11 @@ following options apply. Uncommon Options -These options apply to all tools, as they affect certain obscure -workings of the Valgrind core. Most people won't need to use -these. - + + @@ -165,9 +165,8 @@ these. Debugging Valgrind Options -There are also some options for debugging Valgrind itself. You -shouldn't need to use them in the normal run of things. If you wish to -see the list, use the option. + @@ -176,7 +175,8 @@ see the list, use the option. Memcheck Options - @@ -186,10 +186,12 @@ see the list, use the option. Cachegrind Options - - @@ -199,7 +201,8 @@ see the list, use the option. Massif Options - @@ -209,7 +212,8 @@ see the list, use the option. Helgrind Options - @@ -219,7 +223,8 @@ see the list, use the option. Lackey Options - diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index efea0124c..3f4cabb5c 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -1,19 +1,24 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + Helgrind: a data-race detector -Helgrind is a Valgrind tool for detecting data races in C -and C++ programs that use the Pthreads library. +To use this tool, you must specify +--tool=helgrind on the Valgrind +command line. 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. + + +Data Races + +Helgrind is a valgrind tool for detecting data races in C and C++ +programs that use the Pthreads library. It uses the Eraser algorithm described in: @@ -36,6 +41,12 @@ command line. + + + + +What Helgrind Does + Basically what Helgrind does is to look for memory locations which are accessed by more than one thread. For each such location, Helgrind records which of the program's @@ -55,6 +66,41 @@ can both access the same variable without holding a lock. There's a lot of other sophistication in Helgrind, aimed at reducing the number of false reports, and at producing useful error reports. We hope to have more documentation one -day... +day ... + + + + + + +Helgrind Options + +Helgrind-specific options are: + + + + + + + + + + Assume thread stacks are used privately. + + + + + + + + + Show location of last word access on error. + + + + + + + diff --git a/lackey/docs/lk-manual.xml b/lackey/docs/lk-manual.xml index d97100641..6bec5ea6a 100644 --- a/lackey/docs/lk-manual.xml +++ b/lackey/docs/lk-manual.xml @@ -10,10 +10,14 @@ --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 -to be of use as an example tool. + + +Overview + +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 to be of use as an example +tool. It measures and reports: @@ -84,4 +88,38 @@ sophisticated job of the instrumentation, but that would undermine its role as a simple example tool. Hence we have chosen not to do so. + + + + +Lackey Options + +Lackey-specific options are: + + + + + + + + + + Count calls to <name>. + + + + + + + + + Count loads, stores and alu ops. + + + + + + + + diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index e9e0eb99f..e177a58ed 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -1,6 +1,7 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + Massif: a heap profiler @@ -9,6 +10,7 @@ --tool=massif on the Valgrind command line. + Heap profiling @@ -393,73 +395,93 @@ please let us know. - -Massif options + +Massif Options Massif-specific options are: - + + - - --heap=no - --heap=yes [default] - When enabled, profile heap usage in detail. Without - it, the massif.pid.txt or - massif.pid.html will be very - short. - + + + + + + When enabled, profile heap usage in detail. Without it, the + massif.pid.txt or + massif.pid.html will be very short. + + - - --heap-admin=n - [default: 8] - The number of admin bytes per block to use. This can - only be an estimate of the average, since it may vary. The - allocator used by glibc - requires somewhere between 4--15 bytes per block, depending - on various factors. It also requires admin space for freed - blocks, although Massif does not count this. - + + + + + + The number of admin bytes per block to use. This can only + be an estimate of the average, since it may vary. The allocator + used by glibc requires somewhere + between 4 to 15 bytes per block, depending on various factors. It + also requires admin space for freed blocks, although + massif does not count this. + + - - --stacks=no - --stacks=yes [default] - When enabled, include stack(s) in the profile. - Threaded programs can have multiple stacks. - + + + + + + When enabled, include stack(s) in the profile. Threaded + programs can have multiple stacks. + + - - --depth=n - [default: 3] - Depth of call chains to present in the detailed heap - information. Increasing it will give more information, but - Massif will run the program more slowly, using more memory, - and produce a bigger .txt / - .hp file. - + + + + + + Depth of call chains to present in the detailed heap + information. Increasing it will give more information, but + massif will run the program more slowly, + using more memory, and produce a bigger + massif.pid.txt or + massif.pid.hp file. + + - - --alloc-fn=name - Specify a function that allocates memory. This is - useful for functions that are wrappers to - malloc(), which can fill up - the context information uselessly (and give very - uninformative bands on the graph). Functions specified will - be ignored in contexts, i.e. treated as though they were - malloc(). This option can - be specified multiple times on the command line, to name - multiple functions. - + + + + + + Specify a function that allocates memory. This is useful + for functions that are wrappers to malloc(), + which can fill up the context information uselessly (and give very + uninformative bands on the graph). Functions specified will be + ignored in contexts, i.e. treated as though they were + malloc(). This option can be specified + multiple times on the command line, to name multiple + functions. + + - - --format=text [default] - --format=html - Produce the detailed heap information in text or HTML - format. The file suffix used will be either - .txt or - .html. - + + + + + + Produce the detailed heap information in text or HTML + format. The file suffix used will be either + .txt or .html. + + - + + + diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index ae761485d..1d6f8dacb 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -1,24 +1,24 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + Memcheck: a heavyweight memory checker -To use this tool, you may specify ---tool=memcheck on the Valgrind -command line. You don't have to, though, since Memcheck is the default -tool. +To use this tool, you may specify +on the Valgrind command line. You don't have to, though, since Memcheck +is the default tool. Kinds of bugs that Memcheck can find -Memcheck is Valgrind's heavyweight memory checking -tool. All reads and writes of memory are checked, and -calls to malloc/new/free/delete are intercepted. As a result, -Memcheck can detect the following problems: +Memcheck is Valgrind's heavyweight memory checking tool. All +reads and writes of memory are checked, and calls to +malloc/new/free/delete are intercepted. As a result, Memcheck can detect +the following problems: @@ -34,7 +34,7 @@ Memcheck can detect the following problems: Reading/writing inappropriate areas on the stack - Memory leaks -- where pointers to malloc'd blocks are + Memory leaks - where pointers to malloc'd blocks are lost forever @@ -44,7 +44,7 @@ Memcheck can detect the following problems: Overlapping src and dst pointers in - memcpy() and related + memcpy() and related functions @@ -57,122 +57,137 @@ Memcheck can detect the following problems: xreflabel="Command-line flags specific to Memcheck"> Command-line flags specific to Memcheck - - - --leak-check=no - --leak-check=summary [default] - --leak-check=full - When enabled, search for memory leaks when the client - program finishes. A memory leak means a malloc'd block, - which has not yet been free'd, but to which no pointer can be - found. Such a block can never be free'd by the program, - since no pointer to it exists. If set to - summary, it says how many leaks occurred. - If set to all, it gives details of each - individual leak. + + - + + + + + + When enabled, search for memory leaks when the client + program finishes. A memory leak means a malloc'd block, which has + not yet been free'd, but to which no pointer can be found. Such a + block can never be free'd by the program, since no pointer to it + exists. If set to summary, it says how many + leaks occurred. If set to full or + yes, it gives details of each individual + leak. + + - - --show-reachable=no - [default] - --show-reachable=yes - When disabled, the memory leak detector only shows - blocks for which it cannot find a pointer to at all, or it - can only find a pointer to the middle of. These blocks are - prime candidates for memory leaks. When enabled, the leak - detector also reports on blocks which it could find a pointer - to. Your program could, at least in principle, have freed - such blocks before exit. Contrast this to blocks for which - no pointer, or only an interior pointer could be found: they - are more likely to indicate memory leaks, because you do not - actually have a pointer to the start of the block which you - can hand to free, even if - you wanted to. - + + + + + + When disabled, the memory leak detector only shows blocks + for which it cannot find a pointer to at all, or it can only find + a pointer to the middle of. These blocks are prime candidates for + memory leaks. When enabled, the leak detector also reports on + blocks which it could find a pointer to. Your program could, at + least in principle, have freed such blocks before exit. Contrast + this to blocks for which no pointer, or only an interior pointer + could be found: they are more likely to indicate memory leaks, + because you do not actually have a pointer to the start of the + block which you can hand to free, even if you + wanted to. + + - - --leak-resolution=low - [default] - --leak-resolution=med - --leak-resolution=high - When doing leak checking, determines how willing - Memcheck is to consider different backtraces to be the same. - When set to low, the - default, only the first two entries need match. When - med, four entries have to - match. When high, all - entries need to match. - For hardcore leak debugging, you probably want to use - --leak-resolution=high - together with - --num-callers=40 or some - such large number. Note however that this can give an - overwhelming amount of information, which is why the defaults - are 4 callers and low-resolution matching. - Note that the - --leak-resolution= setting - does not affect Memcheck's ability to find leaks. It only - changes how the results are presented. - + + + + + + When doing leak checking, determines how willing + memcheck is to consider different backtraces to + be the same. When set to low, only the first + two entries need match. When med, four entries + have to match. When high, all entries need to + match. - - --freelist-vol=<number> - [default: 5000000] - When the client program releases memory using free (in - 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 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 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. - + For hardcore leak debugging, you probably want to use + together with + or some such large number. Note + however that this can give an overwhelming amount of information, + which is why the defaults are 4 callers and low-resolution + matching. - - --workaround-gcc296-bugs=no - [default] - --workaround-gcc296-bugs=yes - When enabled, assume that reads and writes some small - 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 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. A better alternative is to use a more recent gcc/g++ in - which this bug is fixed. - + Note that the setting + does not affect memcheck's ability to find + leaks. It only changes how the results are presented. + + - - --partial-loads-ok=yes - - --partial-loads-ok=no[default] - - Controls how Memcheck handles word-sized, word-aligned loads from - addresses for which some bytes are addressible and others are - not. When yes, - such loads do not elicit an address error. - Instead, the loaded V bytes corresponding to the illegal - addresses indicate Undefined, and those corresponding to - legal addresses are loaded from shadow memory, as usual. - When no(the default), - loads from partially invalid addresses are treated the same as - loads from completely invalid addresses: an illegal-address error - is issued, and the resulting V bytes indicate valid data. - Note that code that behaves in this way is in violation of - the the ISO C/C++ standards, and should be considered broken. - If at all possible, such code should be fixed. This flag should - be used only as a last resort. - - + + + + + + When the client program releases memory using + free (in 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 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 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. + + + + + + + + + When enabled, assume that reads and writes some small + 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 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. A better alternative is to use a more + recent gcc/g++ in which this bug is fixed. + + + + + + + + + Controls how memcheck handles word-sized, + word-aligned loads from addresses for which some bytes are + addressible and others are not. When yes, such + loads do not elicit an address error. Instead, the loaded V bytes + corresponding to the illegal addresses indicate Undefined, and + those corresponding to legal addresses are loaded from shadow + memory, as usual. + + When no, loads from partially invalid + addresses are treated the same as loads from completely invalid + addresses: an illegal-address error is issued, and the resulting V + bytes indicate valid data. + + Note that code that behaves in this way is in violation of + the the ISO C/C++ standards, and should be considered broken. If + at all possible, such code should be fixed. This flag should be + used only as a last resort. + + + + + - @@ -180,14 +195,13 @@ Memcheck can detect the following problems: xreflabel="Explanation of error messages from Memcheck"> Explanation of error messages from Memcheck -Despite considerable sophistication under the hood, -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 -quick summary of what error messages mean. The precise behaviour -of the error-checking machinery is described in . +Despite considerable sophistication under the hood, 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 quick summary of what error messages mean. The +precise behaviour of the error-checking machinery is described in +. -This happens when your program reads or writes memory at a -place which Memcheck reckons it shouldn't. In this example, the -program did a 4-byte read at address 0xBFFFF0E0, somewhere within -the system-supplied library libpng.so.2.1.0.9, which was called -from somewhere else in the same library, called from line 326 of -qpngio.cpp, and so on. +This happens when your program reads or writes memory at a place +which Memcheck reckons it shouldn't. In this example, the program did a +4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied +library libpng.so.2.1.0.9, which was called from somewhere else in the +same library, called from line 326 of qpngio.cpp, +and so on. -Memcheck tries to establish what the illegal address might -relate to, since that's often useful. So, if it points into a -block of memory which has already been freed, you'll be informed -of this, and also where the block was free'd at. Likewise, if it -should turn out to be just off the end of a malloc'd block, a -common result of off-by-one-errors in array subscripting, you'll -be informed of this fact, and also where the block was -malloc'd. +Memcheck tries to establish what the illegal address might relate +to, since that's often useful. So, if it points into a block of memory +which has already been freed, you'll be informed of this, and also where +the block was free'd at. Likewise, if it should turn out to be just off +the end of a malloc'd block, a common result of off-by-one-errors in +array subscripting, you'll be informed of this fact, and also where the +block was malloc'd. -In this example, Memcheck can't identify the address. -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 +In this example, Memcheck can't identify the address. 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 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 -access from happening. So, if your program makes an access which -normally would result in a segmentation fault, you program will -still suffer the same fate -- but you will get a message from -Memcheck immediately prior to this. In this particular example, -reading junk on the stack is non-fatal, and the program stays -alive. +Note that Memcheck only tells you that your program is about to +access memory at an illegal address. It can't stop the access from +happening. So, if your program makes an access which normally would +result in a segmentation fault, you program will still suffer the same +fate -- but you will get a message from Memcheck immediately prior to +this. In this particular example, reading junk on the stack is +non-fatal, and the program stays alive. @@ -252,11 +263,11 @@ Conditional jump or move depends on uninitialised value(s) by 0x8048472: main (tests/manuel1.c:8) ]]> -An uninitialised-value use error is reported when your -program uses a value which hasn't been initialised -- in other -words, is undefined. Here, the undefined value is used somewhere -inside the printf() machinery of the C library. This error was -reported when running the following small program: +An uninitialised-value use error is reported when your program +uses a value which hasn't been initialised -- in other words, is +undefined. Here, the undefined value is used somewhere inside the +printf() machinery of the C library. This error was reported when +running the following small program: -It is important to understand that your program can copy -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 -uninitialised. Memcheck observes the value being passed to -_IO_printf and thence to +It is important to understand that your program can copy 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 uninitialised. Memcheck observes the value +being passed to _IO_printf and thence to _IO_vfprintf, but makes no comment. However, -_IO_vfprintf has to examine the value of x so it can turn it into -the corresponding ASCII string, and it is at this point that -Memcheck complains. +_IO_vfprintf has to examine the value of x so it can turn it into the +corresponding ASCII string, and it is at this point that Memcheck +complains. Sources of uninitialised data tend to be: - Local variables in procedures which have not been - initialised, as in the example above. + Local variables in procedures which have not been initialised, + as in the example above. - The contents of malloc'd blocks, before you write - something there. In C++, the new operator is a wrapper round - malloc, so if you create an object with new, its fields will - be uninitialised until you (or the constructor) fill them in, - which is only Right and Proper. + The contents of malloc'd blocks, before you write something + there. In C++, the new operator is a wrapper round malloc, so if + you create an object with new, its fields will be uninitialised + until you (or the constructor) fill them in, which is only Right and + Proper. @@ -308,14 +318,13 @@ Invalid free() by 0x80484C7: main (tests/doublefree.c:10) ]]> -Memcheck keeps track of the blocks allocated by your -program with malloc/new, so it can know exactly whether or not -the argument to free/delete is legitimate or not. Here, this -test program has freed the same block twice. As with the illegal -read/write errors, Memcheck attempts to make sense of the address -free'd. If, as here, the address is one which has previously -been freed, you wil be told that -- making duplicate frees of the -same block easy to spot. +Memcheck keeps track of the blocks allocated by your program with +malloc/new, so it can know exactly whether or not the argument to +free/delete is legitimate or not. Here, this test program has freed the +same block twice. As with the illegal read/write errors, Memcheck +attempts to make sense of the address free'd. If, as here, the address +is one which has previously been freed, you wil be told that -- making +duplicate frees of the same block easy to spot. @@ -327,8 +336,8 @@ function"> function In the following example, a block allocated with -new[] has wrongly been -deallocated with free: +new[] has wrongly been deallocated with +free: -In C++ it's important to deallocate -memory in a way compatible with how it was allocated. The deal -is: +In C++ it's important to deallocate memory in a +way compatible with how it was allocated. The deal is: If allocated with - malloc, - calloc, - realloc, - valloc or - memalign, you must - deallocate with free. + malloc, + calloc, + realloc, + valloc or + memalign, you must + deallocate with free. - If allocated with - new[], you must deallocate - with delete[]. + If allocated with new[], you must + deallocate with delete[]. - If allocated with new, - you must deallocate with - delete. + If allocated with new, you must deallocate + with delete. -The worst thing is that on Linux apparently it doesn't -matter if you do muddle these up, and it all seems to work ok, -but the same program may then crash on a different platform, -Solaris for example. So it's best to fix it properly. According -to the KDE folks "it's amazing how many C++ programmers don't -know this". +The worst thing is that on Linux apparently it doesn't matter if +you do muddle these up, and it all seems to work ok, but the same +program may then crash on a different platform, Solaris for example. So +it's best to fix it properly. According to the KDE folks "it's amazing +how many C++ programmers don't know this". Pascal Massimino adds the following clarification: -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 -variable-sized overhead in what's returned by -new or -new[]. +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 +variable-sized overhead in what's returned by new +or new[]. + @@ -395,19 +399,24 @@ permissions Memcheck checks all parameters to system calls: - It checks all the direct parameters - themselves. - 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. - Also, if the system call needs to write to a user-supplied - buffer, Memcheck checks that the buffer is addressible. + + It checks all the direct parameters themselves. + + + 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. + + + Also, 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 tracked information to -precisely reflect any changes in memory permissions caused by the system call. - +precisely reflect any changes in memory permissions caused by the system +call. Here's an example of two system calls with invalid parameters: -... 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 exit. Note that the first error -refers to the memory pointed to by buf (not -buf itself), but the second error refers to -the argument error_code itself. +... 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 exit. Note that the first +error refers to the memory pointed to by +buf (not +buf itself), but the second error +refers to the argument error_code +itself. @@ -453,15 +464,14 @@ the argument error_code itself. The following C library functions copy some data from one memory block to another (or something similar): -memcpy(), -strcpy(), -strncpy(), -strcat(), -strncat(). -The blocks pointed to by their -src and -dst pointers aren't allowed to -overlap. Memcheck checks for this. +memcpy(), +strcpy(), +strncpy(), +strcat(), +strncat(). +The blocks pointed to by their src and +dst pointers aren't allowed to overlap. +Memcheck checks for this. For example: ==27492== ]]> -You don't want the two blocks to overlap because one of -them could get partially trashed by the copying. +You don't want the two blocks to overlap because one of them could +get partially trashed by the copying. You might think that Memcheck is being overly pedantic reporting -this in the case where dst is less -than src. For example, the obvious way -to implement memcpy() is by copying -from the first byte to the last. However, the optimisation guides of -some architectures recommend copying from the last byte down to the first. -Also, some implementations of memcpy() -zero dst before copying, because zeroing -the destination's cache line(s) can improve performance. +this in the case where dst is less than +src. For example, the obvious way to +implement memcpy() is by copying from the first +byte to the last. However, the optimisation guides of some +architectures recommend copying from the last byte down to the first. +Also, some implementations of memcpy() zero +dst before copying, because zeroing the +destination's cache line(s) can improve performance. -The moral of the story is: if you want to write truly portable code, -don't make any assumptions about the language implementation. +The moral of the story is: if you want to write truly portable +code, don't make any assumptions about the language +implementation. @@ -493,54 +504,51 @@ don't make any assumptions about the language implementation. Memory leak detection -Memcheck keeps track of all memory blocks issued in -response to calls to malloc/calloc/realloc/new. So when the -program exits, it knows which blocks have not been freed. +Memcheck keeps track of all memory blocks issued in response to +calls to malloc/calloc/realloc/new. So when the program exits, it knows +which blocks have not been freed. -If --leak-check is set -appropriately, for each remaining block, Memcheck scans the entire -address space of the process, looking for pointers to the block. -Each block fits into one of the three following categories. +If is set appropriately, for each +remaining block, Memcheck scans the entire address space of the process, +looking for pointers to the block. 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 it before - program exit. Because these are very common and arguably + 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 + 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 - specified. + is specified. - Possibly lost, or "dubious": A pointer to the - interior of the block is found. The pointer might originally - have pointed to the start and have been moved along, or it - might be entirely unrelated. Memcheck deems such a block as - "dubious", because it's unclear whether or not a pointer to it - still exists. + Possibly lost, or "dubious": A pointer to the interior of the + block is found. The pointer might originally have pointed to the + start and have been moved along, or it might be entirely unrelated. + Memcheck deems such a block as "dubious", because it's unclear + whether or not a pointer to it still exists. - Definitely lost, or "leaked": The worst - outcome is that no pointer to the block can be found. The - block is classified as "leaked", because the programmer could - not possibly have freed it at program exit, since no pointer - to it exists. This is likely a symptom of having lost the - pointer at some earlier point in the program. + Definitely lost, or "leaked": The worst outcome is that no + pointer to the block can be found. The block is classified as + "leaked", because the programmer could not possibly have freed it at + program exit, since no pointer to it exists. This is likely a + symptom of having lost the pointer at some earlier point in the + program. -For each block mentioned, Memcheck will also tell you where -the block was allocated. It cannot tell you how or why the -pointer to a leaked block has been lost; you have to work that -out for yourself. In general, you should attempt to ensure your -programs do not have any leaked or dubious blocks at exit. +For each block mentioned, Memcheck will also tell you where the +block was allocated. It cannot tell you how or why the pointer to a +leaked block has been lost; you have to work that out for yourself. In +general, you should attempt to ensure your programs do not have any +leaked or dubious blocks at exit. For example: by 0x........: main (leak-tree.c:25) ]]> -The first message describes a simple case of a single 8 byte -block that has been definitely lost. The second case -mentions both "direct" and "indirect" leaks. The distinction is -that a direct leak is a block which has no pointers to it. An -indirect leak is a block which is only pointed to by other leaked -blocks. Both kinds of leak are bad. +The first message describes a simple case of a single 8 byte block +that has been definitely lost. The second case mentions both "direct" +and "indirect" leaks. The distinction is that a direct leak is a block +which has no pointers to it. An 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 machine-word-sized words for which all A -bits indicate addressibility and all V bits indicated that the -stored value is actually valid. +The precise area of memory in which Memcheck searches for 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. @@ -592,70 +599,68 @@ Memcheck,Addrcheck:suppression_type]]> - Value1, - Value2, - Value4, - Value8, - Value16, + Value1, + Value2, + Value4, + Value8, + Value16, meaning an uninitialised-value error when using a value of 1, 2, 4, 8 or 16 bytes. - Or: Cond (or its old - name, Value0), meaning use + Or: Cond (or its old + name, Value0), meaning use of an uninitialised CPU condition code. - Or: Addr1, - Addr2, - Addr4, - Addr8, - Addr16, + Or: Addr1, + Addr2, + Addr4, + Addr8, + Addr16, meaning an invalid address during a memory access of 1, 2, 4, 8 or 16 bytes respectively. - Or: Param, meaning an + Or: Param, meaning an invalid system call parameter error. - Or: Free, meaning an + Or: Free, meaning an invalid or mismatching free. - Or: Overlap, meaning a + Or: Overlap, meaning a src / dst overlap in - memcpy() or a similar - function. + memcpy() or a similar function. - Or: Leak, meaning + Or: Leak, meaning a memory leak. -The extra information line: for Param errors, is the name -of the offending system call parameter. No other error kinds -have this extra line. +The extra information line: for Param errors, is the name of the +offending system call parameter. No other error kinds have this extra +line. -The first line of the calling context: for Value and Addr -errors, it is either the name of the function in which the error -occurred, or, failing that, the full path of the .so file or -executable containing the error location. For Free errors, is -the name of the function doing the freeing (eg, -free, -__builtin_vec_delete, etc). For -Overlap errors, is the name of the function with the overlapping -arguments (eg. memcpy(), -strcpy(), etc). +The first line of the calling context: for Value and Addr errors, +it is either the name of the function in which the error occurred, or, +failing that, the full path of the .so file or executable containing the +error location. For Free errors, is the name of the function doing the +freeing (eg, free, +__builtin_vec_delete, etc). For Overlap errors, is +the name of the function with the overlapping arguments (eg. +memcpy(), strcpy(), +etc). Lastly, there's the rest of the calling context. @@ -674,35 +679,32 @@ what and how Memcheck is checking. Valid-value (V) bits -It is simplest to think of Memcheck implementing a -synthetic CPU which is identical to a real CPU, except -for one crucial detail. Every bit (literally) of data processed, -stored and handled by the real CPU has, in the synthetic CPU, an -associated "valid-value" bit, which says whether or not the -accompanying bit has a legitimate value. In the discussions -which follow, this bit is referred to as the V (valid-value) +It is simplest to think of Memcheck implementing a synthetic CPU +which is identical to a real CPU, except for one crucial detail. Every +bit (literally) of data processed, stored and handled by the real CPU +has, in the synthetic CPU, an associated "valid-value" bit, which says +whether or not the accompanying bit has a legitimate value. In the +discussions which follow, this bit is referred to as the V (valid-value) bit. -Each byte in the system therefore has a 8 V bits which -follow it wherever it goes. For example, when the CPU loads a -word-size item (4 bytes) from memory, it also loads the -corresponding 32 V bits from a bitmap which stores the V bits for -the process' entire address space. If the CPU should later write -the whole or some part of that value to memory at a different -address, the relevant V bits will be stored back in the V-bit -bitmap. +Each byte in the system therefore has a 8 V bits which follow it +wherever it goes. For example, when the CPU loads a word-size item (4 +bytes) from memory, it also loads the corresponding 32 V bits from a +bitmap which stores the V bits for the process' entire address space. +If the CPU should later write the whole or some part of that value to +memory at a different address, the relevant V bits will be stored back +in the V-bit 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, vector and condition -registers) have their own V bit vectors. +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, vector and condition registers) have +their own V bit vectors. -Copying values around does not cause Memcheck to check for, -or report on, errors. However, when a value is used in a way -which might conceivably affect the outcome of your program's -computation, the associated V bits are immediately checked. If -any of these indicate that the value is undefined, an error is -reported. +Copying values around does not cause Memcheck to check for, or +report on, errors. However, when a value is used in a way which might +conceivably affect the outcome of your program's computation, the +associated V bits are immediately checked. If any of these indicate +that the value is undefined, an error is reported. Here's an (admittedly nonsensical) example: -Memcheck emits no complaints about this, since it merely -copies uninitialised values from -a[] into -b[], and doesn't use them in any -way. However, if the loop is changed to: +Memcheck emits no complaints about this, since it merely copies +uninitialised values from a[] into +b[], and doesn't use them in any way. However, if +the loop is changed to: then Valgrind will complain, at the -if, that the condition depends -on uninitialised values. Note that it doesn't -complain at the j += a[i];, -since at that point the undefinedness is not "observable". It's -only when a decision has to be made as to whether or not to do -the printf -- an observable -action of your program -- that Memcheck complains. +if, that the condition depends on +uninitialised values. Note that it doesn't complain +at the j += a[i];, since at that point the +undefinedness is not "observable". It's only when a decision has to be +made as to whether or not to do the printf -- an +observable action of your program -- that Memcheck complains. -Most low level operations, such as adds, cause Memcheck to -use the V bits for the operands to calculate the V bits for the result. -Even if the result is partially or wholly undefined, it does not +Most low level operations, such as adds, cause Memcheck to use the +V bits for the operands to calculate the V bits for the result. Even if +the result is partially or wholly undefined, it does not complain. -Checks on definedness only occur in three places: when a -value is used to generate a memory address, when control -flow decision needs to be made, and when a system call is -detected, Valgrind checks definedness of parameters as -required. +Checks on definedness only occur in three places: when a value is +used to generate a memory address, when control flow decision needs to +be made, and when a system call is detected, Valgrind checks definedness +of parameters as required. If a check should detect undefinedness, an error message is -issued. The resulting value is subsequently regarded as -well-defined. To do otherwise would give long chains of error -messages. In effect, we say that undefined values are -non-infectious. +issued. The resulting value is subsequently regarded as well-defined. +To do otherwise would give long chains of error messages. In effect, we +say that undefined values are non-infectious. -This sounds overcomplicated. Why not just check all reads -from memory, and complain if an undefined value is loaded into a -CPU register? Well, that doesn't work well, because perfectly -legitimate C programs routinely copy uninitialised values around -in memory, and we don't want endless complaints about that. -Here's the canonical example. Consider a struct like -this: +This sounds overcomplicated. Why not just check all reads from +memory, and complain if an undefined value is loaded into a CPU +register? Well, that doesn't work well, because perfectly legitimate C +programs routinely copy uninitialised values around in memory, and we +don't want endless complaints about that. Here's the canonical example. +Consider a struct like this: -The question to ask is: how large is struct -S, in bytes? An -int is 4 bytes and a -char one byte, so perhaps a -struct S occupies 5 bytes? -Wrong. All (non-toy) compilers we know of will round the size of -struct S up to a whole number of -words, in this case 8 bytes. Not doing this forces compilers to -generate truly appalling code for subscripting arrays of -struct S's. +The question to ask is: how large is struct S, +in bytes? An int is 4 bytes and a +char one byte, so perhaps a struct +S occupies 5 bytes? Wrong. All (non-toy) compilers we know +of will round the size of struct S up to a whole +number of words, in this case 8 bytes. Not doing this forces compilers +to generate truly appalling code for subscripting arrays of +struct S's. -So s1 occupies 8 bytes, -yet only 5 of them will be initialised. For the assignment -s2 = s1, gcc generates code to -copy all 8 bytes wholesale into -s2 without regard for their -meaning. If Memcheck simply checked values as they came out of -memory, it would yelp every time a structure assignment like this -happened. So the more complicated semantics described above is -necessary. This allows gcc to copy -s1 into -s2 any way it likes, and a -warning will only be emitted if the uninitialised values are -later used. +So s1 occupies 8 bytes, yet only 5 of them will +be initialised. For the assignment s2 = s1, gcc +generates code to copy all 8 bytes wholesale into s2 +without regard for their meaning. If Memcheck simply checked values as +they came out of memory, it would yelp every time a structure assignment +like this happened. So the more complicated semantics described above +is necessary. This allows gcc to copy +s1 into s2 any way it likes, and a +warning will only be emitted if the uninitialised values are later +used. @@ -798,27 +790,23 @@ later used. Valid-address (A) bits -Notice that the previous subsection describes how the -validity of values is established and maintained without having -to say whether the program does or does not have the right to -access any particular memory location. We now consider the -latter issue. +Notice that the previous subsection describes how the validity of +values is established and maintained without having to say whether the +program does or does not have the right to access any particular memory +location. We now consider the latter issue. -As described above, every bit in memory or in the CPU has -an associated valid-value (V) bit. In -addition, all bytes in memory, but not in the CPU, have an -associated valid-address (A) bit. This -indicates whether or not the program can legitimately read or -write that location. It does not give any indication of the -validity or the data at that location -- that's the job of the -V bits -- only whether or not the location may -be accessed. +As described above, every bit in memory or in the CPU has an +associated valid-value (V) bit. In addition, all bytes in memory, but +not in the CPU, have an associated valid-address (A) bit. This +indicates whether or not the program can legitimately read or write that +location. It does not give any indication of the validity or the data +at that location -- that's the job of the V bits -- only whether or not +the location may be accessed. -Every time your program reads or writes memory, Memcheck -checks the A bits associated with the address. -If any of them indicate an invalid address, an error is emitted. -Note that the reads and writes themselves do not change the A -bits, only consult them. +Every time your program reads or writes memory, Memcheck checks +the A bits associated with the address. If any of them indicate an +invalid address, an error is emitted. Note that the reads and writes +themselves do not change the A bits, only consult them. So how do the A bits get set/cleared? Like this: @@ -829,38 +817,36 @@ bits, only consult them. - When the program does malloc/new, the A bits for - exactly the area allocated, and not a byte more, are marked - as accessible. Upon freeing the area the A bits are changed - to indicate inaccessibility. + When the program does malloc/new, the A bits for exactly the + area allocated, and not a byte more, are marked as accessible. Upon + freeing the area the A bits are changed to indicate + inaccessibility. - When the stack pointer register - (SP) moves up or down, - A bits are set. The rule is that the area - from SP up to the base of the stack is - marked as accessible, and below SP is - inaccessible. (If that sounds illogical, bear in mind that - the stack grows down, not up, on almost all Unix systems, - including GNU/Linux.) Tracking SP like - this has the useful side-effect that the section of stack - used by a function for local variables etc is automatically - marked accessible on function entry and inaccessible on - exit. + When the stack pointer register (SP) moves + up or down, A bits are set. The rule is that the area from + SP up to the base of the stack is marked as + accessible, and below SP is inaccessible. (If + that sounds illogical, bear in mind that the stack grows down, not + up, on almost all Unix systems, including GNU/Linux.) Tracking + SP like this has the useful side-effect that the + section of stack used by a function for local variables etc is + automatically marked accessible on function entry and inaccessible + on exit. - When doing system calls, A bits are changed - appropriately. For example, mmap() magically makes files - appear in the process' address space, so the A bits must be - updated if mmap() succeeds. + When doing system calls, A bits are changed appropriately. + For example, mmap() magically makes files appear in the process' + address space, so the A bits must be updated if mmap() + succeeds. - Optionally, your program can tell Valgrind about such - changes explicitly, using the client request mechanism - described above. + Optionally, your program can tell Valgrind about such changes + explicitly, using the client request mechanism described + above. @@ -876,118 +862,108 @@ follows: - Each byte in memory has 8 associated - V (valid-value) bits, saying whether or - not the byte has a defined value, and a single - A (valid-address) bit, saying whether or - not the program currently has the right to read/write that - address. + Each byte in memory has 8 associated V (valid-value) bits, + saying whether or not the byte has a defined value, and a single A + (valid-address) bit, saying whether or not the program currently has + the right to read/write that address. - When memory is read or written, the relevant - A bits are consulted. If they indicate an - invalid address, Valgrind emits an Invalid read or Invalid - write error. + When memory is read or written, the relevant A bits are + consulted. If they indicate an invalid address, Valgrind emits an + Invalid read or Invalid write error. - When memory is read into the CPU's registers, - the relevant V bits are fetched from - memory and stored in the simulated CPU. They are not - consulted. + When memory is read into the CPU's registers, the relevant V + bits are fetched from memory and stored in the simulated CPU. They + are not consulted. - When a register is written out to memory, the - V bits for that register are written back - to memory too. + When a register is written out to memory, the V bits for that + register are written back to memory too. - When values in CPU registers are used to - generate a memory address, or to determine the outcome of a - conditional branch, the V bits for those - values are checked, and an error emitted if any of them are - undefined. + When values in CPU registers are used to generate a memory + address, or to determine the outcome of a conditional branch, the V + bits for those values are checked, and an error emitted if any of + them are undefined. - When values in CPU registers are used for any - other purpose, Valgrind computes the V bits for the result, - but does not check them. + When values in CPU registers are used for any other purpose, + Valgrind computes the V bits for the result, but does not check + them. - One the V bits for a value in the - CPU have been checked, they are then set to indicate - validity. This avoids long chains of errors. + One the V bits for a value in the CPU have been checked, they + are then set to indicate validity. This avoids long chains of + errors. - When values are loaded from memory, valgrind checks the - A bits for that location and issues an illegal-address - warning if needed. In that case, the V bits loaded are - forced to indicate Valid, despite the location being invalid. - This apparently strange choice reduces the amount of - confusing information presented to the user. It avoids the - unpleasant phenomenon in which memory is read from a place - which is both unaddressible and contains invalid values, and, - as a result, you get not only an invalid-address (read/write) - error, but also a potentially large set of - uninitialised-value errors, one for every time the value is - used. - There is a hazy boundary case to do with multi-byte - loads from addresses which are partially valid and partially - invalid. See details of the flag - --partial-loads-ok for - details. + When values are loaded from memory, valgrind checks the A bits + for that location and issues an illegal-address warning if needed. + In that case, the V bits loaded are forced to indicate Valid, + despite the location being invalid. + + This apparently strange choice reduces the amount of confusing + information presented to the user. It avoids the unpleasant + phenomenon in which memory is read from a place which is both + unaddressible and contains invalid values, and, as a result, you get + not only an invalid-address (read/write) error, but also a + potentially large set of uninitialised-value errors, one for every + time the value is used. + + There is a hazy boundary case to do with multi-byte loads from + addresses which are partially valid and partially invalid. See + details of the flag for details. + -Memcheck intercepts calls to malloc, calloc, realloc, -valloc, memalign, free, new, new[], delete and delete[]. -The behaviour you get +Memcheck intercepts calls to malloc, calloc, realloc, valloc, +memalign, free, new, new[], delete and delete[]. The behaviour you get is: - 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. + 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. - calloc: returned memory is marked both addressible and - valid, since calloc() clears the area to zero. + calloc: returned memory is marked both addressible and valid, + since calloc() clears the area to zero. - realloc: if the new size is larger than the old, the - new section is addressible but invalid, as with - malloc. + realloc: if the new size is larger than the old, the new + section is addressible but invalid, as with malloc. - If the new size is smaller, the dropped-off section is - marked as unaddressible. You may only pass to realloc a - pointer previously issued to you by malloc/calloc/realloc. + If the new size is smaller, the dropped-off section is marked + as unaddressible. You may only pass to realloc a pointer previously + issued to you by malloc/calloc/realloc. - 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 - reallocation of this block. Until that happens, all attempts - to access it will elicit an invalid-address error, as you - would hope. + 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 reallocation of this block. Until that happens, + all attempts to access it will elicit an invalid-address error, as + you would hope. @@ -1008,9 +984,9 @@ arguments. - VALGRIND_MAKE_NOACCESS, - VALGRIND_MAKE_WRITABLE and - VALGRIND_MAKE_READABLE. + VALGRIND_MAKE_NOACCESS, + VALGRIND_MAKE_WRITABLE and + VALGRIND_MAKE_READABLE. These mark address ranges as completely inaccessible, accessible but containing undefined data, and accessible and containing defined data, respectively. Subsequent errors may @@ -1020,66 +996,61 @@ arguments. - VALGRIND_DISCARD: At - some point you may want Valgrind to stop reporting errors in - terms of the blocks defined by the previous three macros. To - do this, the above macros return a small-integer "block - handle". You can pass this block handle to - VALGRIND_DISCARD. After - doing so, Valgrind will no longer be able to relate - addressing errors to the user-defined block associated with - the handle. The permissions settings associated with the - handle remain in place; this just affects how errors are - reported, not whether they are reported. Returns 1 for an - invalid handle and 0 for a valid handle (although passing - invalid handles is harmless). Always returns 0 when not run + VALGRIND_DISCARD: At some point you may + want Valgrind to stop reporting errors in terms of the blocks + defined by the previous three macros. To do this, the above macros + return a small-integer "block handle". You can pass this block + handle to VALGRIND_DISCARD. After doing so, + Valgrind will no longer be able to relate addressing errors to the + user-defined block associated with the handle. The permissions + settings associated with the handle remain in place; this just + affects how errors are reported, not whether they are reported. + Returns 1 for an invalid handle and 0 for a valid handle (although + passing invalid handles is harmless). Always returns 0 when not run on Valgrind. - VALGRIND_CHECK_WRITABLE - and VALGRIND_CHECK_READABLE: - check immediately whether or not the given address range has - the relevant property, and if not, print an error message. - Also, for the convenience of the client, returns zero if the - relevant property holds; otherwise, the returned value is the - address of the first byte for which the property is not true. - Always returns 0 when not run on Valgrind. + VALGRIND_CHECK_WRITABLE and + VALGRIND_CHECK_READABLE: check immediately + whether or not the given address range has the relevant property, + and if not, print an error message. Also, for the convenience of + the client, returns zero if the relevant property holds; otherwise, + the returned value is the address of the first byte for which the + property is not true. Always returns 0 when not run on + Valgrind. - VALGRIND_CHECK_DEFINED: - a quick and easy way to find out whether Valgrind thinks a - particular variable (lvalue, to be precise) is addressible - and defined. Prints an error message if not. Returns no - value. + VALGRIND_CHECK_DEFINED: a quick and easy + way to find out whether Valgrind thinks a particular variable + (lvalue, to be precise) is addressible and defined. Prints an error + message if not. Returns no value. - VALGRIND_DO_LEAK_CHECK: - run the memory leak detector right now. Returns no value. I - guess this could be used to incrementally check for leaks - between arbitrary places in the program's execution. - Warning: not properly tested! + VALGRIND_DO_LEAK_CHECK: run the memory leak + detector right now. Returns no value. I guess this could be used + to incrementally check for leaks between arbitrary places in the + program's execution. Warning: not properly tested! - VALGRIND_COUNT_LEAKS: - fills in the four arguments with the number of bytes of - memory found by the previous leak check to be leaked, - dubious, reachable and suppressed. Again, useful in test - harness code, after calling - VALGRIND_DO_LEAK_CHECK. + VALGRIND_COUNT_LEAKS: fills in the four + arguments with the number of bytes of memory found by the previous + leak check to be leaked, dubious, reachable and suppressed. Again, + useful in test harness code, after calling + VALGRIND_DO_LEAK_CHECK. - VALGRIND_GET_VBITS and - VALGRIND_SET_VBITS: allow - 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. Note: currently - disabled in Valgrind 3.1.0. + VALGRIND_GET_VBITS and + VALGRIND_SET_VBITS: allow 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. Note: currently disabled in Valgrind + 3.1.0. diff --git a/memcheck/docs/mc-tech-docs.xml b/memcheck/docs/mc-tech-docs.xml index 31a23c969..cebe61326 100644 --- a/memcheck/docs/mc-tech-docs.xml +++ b/memcheck/docs/mc-tech-docs.xml @@ -1,6 +1,7 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + @@ -12,66 +13,61 @@ Introduction -This document contains a detailed, highly-technical -description of the internals of Valgrind. This is not the user -manual; if you are an end-user of Valgrind, you do not want to -read this. Conversely, if you really are a hacker-type and want -to know how it works, I assume that you have read the user manual -thoroughly. +This document contains a detailed, highly-technical description of +the internals of Valgrind. This is not the user manual; if you are an +end-user of Valgrind, you do not want to read this. Conversely, if you +really are a hacker-type and want to know how it works, I assume that +you have read the user manual thoroughly. -You may need to read this document several times, and -carefully. Some important things, I only say once. +You may need to read this document several times, and carefully. +Some important things, I only say once. -[Note: this document is now very old, and a lot of its contents are out -of date, and misleading.] +[Note: this document is now very old, and a lot of its contents +are out of date, and misleading.] History -Valgrind came into public view in late Feb 2002. However, -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, -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 -performance for Valgrind. Design work for the JITter started in -earnest in Oct 2000, and by early 2001 I had an x86-to-x86 -dynamic translator which could run quite large programs. This -translator was in a sense pointless, since it did not do any -instrumentation or checking. +Valgrind came into public view in late Feb 2002. However, 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, 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 performance for +Valgrind. Design work for the JITter started in earnest in Oct 2000, +and by early 2001 I had an x86-to-x86 dynamic translator which could run +quite large programs. This translator was in a sense pointless, since +it did not do any instrumentation or checking. -Most of the rest of 2001 was taken up designing and -implementing the instrumentation scheme. The main difficulty, -which consumed a lot of effort, was to design a scheme which did -not generate large numbers of false uninitialised-value warnings. -By late 2001 a satisfactory scheme had been arrived at, and I -started to test it on ever-larger programs, with an eventual eye -to making it work well enough so that it was helpful to folks -debugging the upcoming version 3 of KDE. I've used KDE since -before version 1.0, and wanted to Valgrind to be an indirect -contribution to the KDE 3 development effort. At the start of -Feb 02 the kde-core-devel crew started using it, and gave a huge -amount of helpful feedback and patches in the space of three -weeks. Snapshot 20020306 is the result. +Most of the rest of 2001 was taken up designing and implementing +the instrumentation scheme. The main difficulty, which consumed a lot +of effort, was to design a scheme which did not generate large numbers +of false uninitialised-value warnings. By late 2001 a satisfactory +scheme had been arrived at, and I started to test it on ever-larger +programs, with an eventual eye to making it work well enough so that it +was helpful to folks debugging the upcoming version 3 of KDE. I've used +KDE since before version 1.0, and wanted to Valgrind to be an indirect +contribution to the KDE 3 development effort. At the start of Feb 02 +the kde-core-devel crew started using it, and gave a huge amount of +helpful feedback and patches in the space of three weeks. Snapshot +20020306 is the result. -In the best Unix tradition, or perhaps in the spirit of -Fred Brooks' depressing-but-completely-accurate epitaph "build -one to throw away; you will anyway", much of Valgrind is a second -or third rendition of the initial idea. The instrumentation -machinery (vg_translate.c, -vg_memory.c) and core CPU simulation -(vg_to_ucode.c, -vg_from_ucode.c) have had three redesigns -and rewrites; the register allocator, low-level memory manager +In the best Unix tradition, or perhaps in the spirit of Fred +Brooks' depressing-but-completely-accurate epitaph "build one to throw +away; you will anyway", much of Valgrind is a second or third rendition +of the initial idea. The instrumentation machinery +(vg_translate.c, vg_memory.c) +and core CPU simulation (vg_to_ucode.c, +vg_from_ucode.c) have had three redesigns and +rewrites; the register allocator, low-level memory manager (vg_malloc2.c) and symbol table reader -(vg_symtab2.c) are on the second rewrite. -In a sense, this document serves to record some of the knowledge -gained as a result. +(vg_symtab2.c) are on the second rewrite. In a +sense, this document serves to record some of the knowledge gained as a +result. @@ -84,11 +80,11 @@ gained as a result. valgrinq.so, of which more later. The valgrind shell script adds valgrind.so to the -LD_PRELOAD list of extra -libraries to be loaded with any dynamically linked library. This -is a standard trick, one which I assume the -LD_PRELOAD mechanism was -developed to support. +LD_PRELOAD list of extra libraries to +be loaded with any dynamically linked library. This is a standard +trick, one which I assume the +LD_PRELOAD mechanism was developed to +support. valgrind.so is linked with the -z initfirst flag, which @@ -101,7 +97,7 @@ return from this initialisation function. So the normal startup actions, orchestrated by the dynamic linker ld.so, continue as usual, except on the synthetic CPU, not the real one. Eventually -main is run and returns, and +main is run and returns, and then the finalisation code of the shared objects is run, presumably in inverse order to which they were initialised. Remember, this is still all happening on the simulated CPU. @@ -111,14 +107,14 @@ CPU, prints any error summaries and/or does leak detection, and returns from the initialisation code on the real CPU. At this point, in effect the real and synthetic CPUs have merged back into one, Valgrind has lost control of the program, and the -program finally exit()s back to +program finally exit()s back to the kernel in the usual way. The normal course of activity, once Valgrind has started up, is as follows. Valgrind never runs any part of your program (usually referred to as the "client"), not a single byte of it, directly. Instead it uses function -VG_(translate) to translate +VG_(translate) to translate basic blocks (BBs, straight-line sequences of code) into instrumented translations, and those are run instead. The translations are stored in the translation cache (TC), @@ -130,7 +126,7 @@ direct-map cache for fast lookups in TT; it usually achieves a hit rate of around 98% and facilitates an orig-to-trans lookup in 4 x86 insns, which is not bad. -Function VG_(dispatch) in +Function VG_(dispatch) in vg_dispatch.S is the heart of the JIT dispatcher. Once a translated code address has been found, it is executed simply by an x86 call @@ -141,19 +137,19 @@ does a ret, taking it back to the dispatch loop, with, interestingly, zero branch mispredictions. The address requested in %eax is looked up first in -VG_(tt_fast), and, if not found, +VG_(tt_fast), and, if not found, by calling C helper -VG_(search_transtab). If there +VG_(search_transtab). If there is still no translation available, -VG_(dispatch) exits back to the +VG_(dispatch) exits back to the top-level C dispatcher -VG_(toploop), which arranges for -VG_(translate) to make a new +VG_(toploop), which arranges for +VG_(translate) to make a new translation. All fairly unsurprising, really. There are various complexities described below. The translator, orchestrated by -VG_(translate), is complicated +VG_(translate), is complicated but entirely self-contained. It is described in great detail in subsequent sections. Translations are stored in TC, with TT tracking administrative information. The translations are @@ -168,7 +164,7 @@ new translations is expensive, so it is worth having a large TC to minimise the (capacity) miss rate. The dispatcher, -VG_(dispatch), receives hints +VG_(dispatch), receives hints from the translations which allow it to cheaply spot all control transfers corresponding to x86 call and @@ -178,24 +174,24 @@ this in order to spot some special events: Calls to - VG_(shutdown). This is + VG_(shutdown). This is Valgrind's cue to exit. NOTE: actually this is done a different way; it should be cleaned up. Returns of system call handlers, to the return address - VG_(signalreturn_bogusRA). + VG_(signalreturn_bogusRA). The signal simulator needs to know when a signal handler is returning, so we spot jumps (returns) to this address. - Calls to vg_trap_here. - All malloc, - free, etc calls that the + Calls to vg_trap_here. + All malloc, + free, etc calls that the client program makes are eventually routed to a call to - vg_trap_here, and Valgrind + vg_trap_here, and Valgrind does its own special thing with these calls. In effect this provides a trapdoor, by which Valgrind can intercept certain calls on the simulated CPU, run the call as it sees fit @@ -207,24 +203,24 @@ this in order to spot some special events: Valgrind intercepts the client's -malloc, -free, etc, calls, so that it can +malloc, +free, etc, calls, so that it can store additional information. Each block -malloc'd by the client gives +malloc'd by the client gives rise to a shadow block in which Valgrind stores the call stack at -the time of the malloc call. -When the client calls free, +the time of the malloc call. +When the client calls free, Valgrind tries to find the shadow block corresponding to the -address passed to free, and +address passed to free, and emits an error message if none can be found. If it is found, the block is placed on the freed blocks queue vg_freed_list, it is marked as inaccessible, and its shadow block now records the call stack at -the time of the free call. +the time of the free call. Keeping free'd blocks in this queue allows Valgrind to spot all (presumably invalid) accesses to them. However, once the volume of blocks in the free queue -exceeds VG_(clo_freelist_vol), +exceeds VG_(clo_freelist_vol), blocks are finally removed from the queue. Keeping track of A and @@ -236,7 +232,7 @@ in a way which is reasonably fast and reasonably space efficient. The 4G address space is divided up into 64K sections, each covering 64Kb of address space. Given a 32-bit address, the top 16 bits are used to select one of the 65536 entries in -VG_(primary_map). The resulting +VG_(primary_map). The resulting "secondary" (SecMap) holds A and V bits for the 64k of address space chunk corresponding to the lower 16 bits of the address. @@ -257,7 +253,7 @@ How can you figure out where in your simulator the bug is? Valgrind's answer is: cheat. Valgrind is designed so that it is possible to switch back to running the client program on the real CPU at any point. Using the ---stop-after= flag, you can ask + flag, you can ask Valgrind to run just some number of basic blocks, and then run the rest of the way on the real CPU. If you are searching for a bug in the simulated CPU, you can use this to do a binary search, @@ -271,7 +267,7 @@ regardless of whether it is running on the real or simulated CPU. This means that Valgrind can't do pointer swizzling -- well, no great loss -- and it can't run on the same stack as the client -- again, no great loss. Valgrind operates on its own stack, -VG_(stack), which it switches to +VG_(stack), which it switches to at startup, temporarily switching back to the client's stack when doing system calls for the client. @@ -299,8 +295,8 @@ transition inside a sighandler and still have things working, but in practice that's not much of a restriction. Valgrind's implementation of -malloc, -free, etc, (in +malloc, +free, etc, (in vg_clientmalloc.c, not the low-level stuff in vg_malloc2.c) is somewhat complicated by the need to handle switching back at arbitrary points. It does @@ -341,7 +337,7 @@ result: Aside from the assertions, valgrind contains various sets of internal sanity checks, which get run at varying frequencies during normal operation. - VG_(do_sanity_checks) runs + VG_(do_sanity_checks) runs every 1000 basic blocks, which means 500 to 2000 times/second for typical machines at present. It checks that Valgrind hasn't overrun its private stack, and does some simple checks @@ -359,7 +355,7 @@ result: The symbol table reader(s): various checks to ensure uniqueness of mappings; see - VG_(read_symbols) for a + VG_(read_symbols) for a start. Is permanently engaged. @@ -381,9 +377,9 @@ result: The JITter parses x86 basic blocks into sequences of UCode instructions. It then sanity checks each one - with VG_(saneUInstr) and + with VG_(saneUInstr) and sanity checks the sequence as a whole with - VG_(saneUCodeBlock). + VG_(saneUCodeBlock). This stuff is engaged by default, and has caught some way-obscure bugs in the simulated CPU machinery in its time. @@ -391,14 +387,14 @@ result: The system call wrapper does - VG_(first_and_last_secondaries_look_plausible) + VG_(first_and_last_secondaries_look_plausible) after every syscall; this is known to pick up bugs in the syscall wrappers. Engaged by default. The main dispatch loop, in - VG_(dispatch), checks + VG_(dispatch), checks that translations do not set %ebp to any value different from @@ -455,8 +451,8 @@ result: valgrind.so | grep " T ", which shows you all the globally exported text symbols. They should all have an approved prefix, except for those like - malloc, - free, etc, which we + malloc, + free, etc, which we deliberately want to shadow and take precedence over the same names exported from glibc.so, so that valgrind can intercept those calls easily. Similarly, @@ -905,24 +901,24 @@ stages, coordinated by transformation passes, all on straight-line blocks of UCode (type UCodeBlock). Steps 2 and 4 are optimisation passes and can be disabled for debugging purposes, -with --optimise=no and ---cleanup=no respectively. +with and + respectively. Valgrind can also run in a no-instrumentation mode, given ---instrument=no. This is useful +. This is useful for debugging the JITter quickly without having to deal with the complexity of the instrumentation mechanism too. In this mode, steps 3 and 4 are omitted. These flags combine, so that ---instrument=no together with ---optimise=no means only steps + together with + means only steps 1, 5 and 6 are used. ---single-step=yes causes each + causes each x86 instruction to be treated as a single basic block. The translations are terrible but this is sometimes instructive. -The --stop-after=N flag +The flag switches back to the real CPU after N basic blocks. It also re-JITs the final basic block executed and prints the debugging info diff --git a/none/docs/nl-manual.xml b/none/docs/nl-manual.xml index 384773ec0..2cd06e465 100644 --- a/none/docs/nl-manual.xml +++ b/none/docs/nl-manual.xml @@ -2,9 +2,10 @@ + -Nulgrind: the ``null'' tool +Nulgrind: the "null" tool A tool that does not very much at all Nulgrind is the minimal tool for Valgrind. It does no @@ -12,11 +13,10 @@ initialisation or finalisation, and adds no instrumentation to the program's code. It is mainly of use for Valgrind's developers for debugging and regression testing. -Nonetheless you can run programs with Nulgrind. They will -run roughly 5 times more slowly than normal, for no useful -effect. Note that you need to use the option ---tool=none to run Nulgrind -(ie. not --tool=nulgrind). +Nonetheless you can run programs with Nulgrind. They will run +roughly 5 times more slowly than normal, for no useful effect. Note +that you need to use the option to run +Nulgrind (ie. not ).