diff --git a/NEWS b/NEWS index 4fcc62e70..b252bf7ce 100644 --- a/NEWS +++ b/NEWS @@ -69,6 +69,8 @@ Release 3.5.0 (???) produced, but each leak report will describe fewer leaked blocks. - The documentation for the leak checker has also been improved. +* XXX: Atomic instructions are now handled properly... + * The format of some (non-XML) stack trace entries has changed a little. Previously there were six possible forms: diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 4f4c37c05..9e937eb16 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -809,11 +809,10 @@ instructions. To do this, you just need to assemble your .s files with assembly-level debug -information. You can use gcc --S to compile C/C++ programs to assembly code, and then -gcc -g on the assembly code files to -achieve this. You can then profile and annotate the assembly code source -files in the same way as C/C++ source files. +information. You can use compile with the to compile C/C++ +programs to assembly code, and then assemble the assembly code files with + to achieve this. You can then profile and annotate the +assembly code source files in the same way as C/C++ source files. @@ -1037,7 +1036,7 @@ cg_annotate issues warnings. the counts from each entry. The reason for this is that although the debug info - output by gcc indicates the switch from + output by GCC indicates the switch from bar.c to foo.h, it doesn't indicate the name of the function in foo.h, so Valgrind keeps using the old @@ -1065,8 +1064,8 @@ cg_annotate issues warnings. which case you'll get a warning message explaining that annotations for the file might be incorrect. - If you are using gcc 3.1 or later, this is most likely - irrelevant, since gcc switched to using the more modern DWARF2 + If you are using GCC 3.1 or later, this is most likely + irrelevant, since GCC switched to using the more modern DWARF2 format by default at version 3.1. DWARF2 does not have any such limitations on line numbers. diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml index 7d50fd470..07f3f1a5d 100644 --- a/docs/xml/FAQ.xml +++ b/docs/xml/FAQ.xml @@ -171,6 +171,28 @@ collect2: ld returned 1 exit status Memcheck may issue a warning just before this happens, but it might not if the jump happens to land in addressable memory. + Another possibility is that Valgrind does not handle the + instruction. If you are using an older Valgrind, a newer version might + handle the instruction. However, all instruction sets have some + obscure, rarely used instructions. Also, on amd64 there are an almost + limitless number of combinations of redundant instruction prefixes, many + of them undocumented but accepted by CPUs. So Valgrind will still have + decoding failures from time to time. If this happens, please file a bug + report. + + + + + + My program fails to start, and this message is printed: + + + + One possibility is that your program has a bug and erroneously + jumps to a non-code address, in which case you'll get a SIGILL signal. + Memcheck may issue a warning just before this happens, but it might not + if the jump happens to land in addressable memory. + Another possibility is that Valgrind does not handle the instruction. If you are using an older Valgrind, a newer version might handle the instruction. However, all instruction sets have some @@ -242,30 +264,30 @@ collect2: ld returned 1 exit status memory as still reachable. The behaviour not to free pools at the exit() could be called a bug of the library though. - Using gcc, you can force the STL to use malloc and to free + Using GCC, you can force the STL to use malloc and to free memory as soon as possible by globally disabling memory caching. Beware! Doing so will probably slow down your program, sometimes drastically. - With gcc 2.91, 2.95, 3.0 and 3.1, compile all source using + With GCC 2.91, 2.95, 3.0 and 3.1, compile all source using the STL with -D__USE_MALLOC. Beware! This was - removed from gcc starting with version 3.3. + removed from GCC starting with version 3.3. - With gcc 3.2.2 and later, you should export the + With GCC 3.2.2 and later, you should export the environment variable GLIBCPP_FORCE_NEW before running your program. - With gcc 3.4 and later, that variable has changed name to + With GCC 3.4 and later, that variable has changed name to GLIBCXX_FORCE_NEW. There are other ways to disable memory pooling: using the malloc_alloc template with your objects (not - portable, but should work for gcc) or even writing your own memory + portable, but should work for GCC) or even writing your own memory allocators. But all this goes beyond the scope of this FAQ. Start by reading Valgrind is designed to be as non-intrusive as possible. It works directly with existing executables. You don't need to recompile, relink, -or otherwise modify, the program to be checked. +or otherwise modify the program to be checked. -Simply put -valgrind --tool=tool_name -at the start of the command line normally used to run the program. For -example, if want to run the command -ls -l using the heavyweight -memory-checking tool Memcheck, issue the command: +You invoke Valgrind like this: + + +The most important option is which dictates +which Valgrind tool to run. For example, if want to run the command +ls -l using the memory-checking tool +Memcheck, issue this command: -Memcheck is the default, so if you want to use it you can +However, Memcheck is the default, so if you want to use it you can omit the flag. Regardless of which tool is in use, Valgrind takes control of your @@ -58,27 +60,23 @@ code. tools. At one end of the scale, Memcheck adds code to check every memory access and every value computed, making it run 10-50 times slower than natively. -At the other end of the spectrum, the ultra-trivial "none" tool -(also referred to as Nulgrind) adds no instrumentation at all -and causes in total -"only" about a 4 times slowdown. +At the other end of the spectrum, the minimal tool, called Nulgrind, +adds no instrumentation at all and causes in total "only" about a 4 times +slowdown. Valgrind simulates every single instruction your program executes. Because of this, the active tool checks, or profiles, not only the code -in your application but also in all supporting dynamically-linked -(.so-format) libraries, including the -GNU C library, the X client libraries, Qt, if you work with KDE, and so -on. +in your application but also in all supporting dynamically-linked libraries, +including the C library, graphical libraries, and so on. If you're using an error-detection tool, Valgrind may -detect errors in libraries, for example the GNU C or X11 +detect errors in system libraries, for example the GNU C or X11 libraries, which you have to use. You might not be interested in these errors, since you probably have no control over that code. Therefore, Valgrind allows you to selectively suppress errors, by recording them in a suppressions file which is read when Valgrind starts up. The build -mechanism attempts to select suppressions which give reasonable -behaviour for the C library -and X11 client library versions detected on your machine. +mechanism selects default suppressions which give reasonable +behaviour for the OS and libraries detected on your machine. To make it easier to write suppressions, you can use the option. This tells Valgrind to print out a suppression for each reported error, which you can then @@ -109,7 +107,7 @@ around large C++ apps. For example, debugging OpenOffice.org with Memcheck is a bit easier when using this flag. You don't have to do this, but doing so helps Valgrind produce more accurate and less confusing error reports. Chances are you're set up like this -already, if you intended to debug your program with GNU gdb, or some +already, if you intended to debug your program with GNU GDB, or some other debugger. If you are planning to use Memcheck: On rare @@ -128,25 +126,24 @@ should compile your code with because it can identify some or all of the problems that Valgrind can miss at the higher optimisation levels. (Using is also a good idea in general.) All other tools (as far as we know) are -unaffected by optimisation level. +unaffected by optimisation level, and for profiling tools like Cachegrind it +is better to compile your program at its normal optimisation level. Valgrind understands both the older "stabs" debugging format, used -by gcc versions prior to 3.1, and the newer DWARF2 and DWARF3 formats -used by gcc +by GCC versions prior to 3.1, and the newer DWARF2 and DWARF3 formats +used by GCC 3.1 and later. We continue to develop our debug-info readers, although the majority of effort will naturally enough go into the newer DWARF2/3 reader. -When you're ready to roll, just run your application as you -would normally, but place -valgrind --tool=tool_name in front of -your usual command-line invocation. Note that you should run the real +When you're ready to roll, run Valgrind as described above. +Note that you should run the real (machine-code) executable here. If your application is started by, for -example, a shell or perl script, you'll need to modify it to invoke +example, a shell or Perl script, you'll need to modify it to invoke Valgrind on the real executables. Running such scripts directly under Valgrind will result in you getting error reports pertaining to -/bin/sh, -/usr/bin/perl, or whatever interpreter +/bin/sh, +/usr/bin/perl, or whatever interpreter you're using. This may not be what you want and can be confusing. You can force the issue by giving the flag , but confusion is still @@ -232,12 +229,13 @@ re-run, passing the flag to Valgrind. A second risk. It seems likely that people will write more sophisticated listeners in the fullness of time. - valgrind-listener can accept simultaneous connections from up - to 50 Valgrinded processes. In front of each line of output it - prints the current number of active connections in round - brackets. + valgrind-listener can accept + simultaneous connections from up to 50 Valgrinded processes. In front + of each line of output it prints the current number of active + connections in round brackets. - valgrind-listener accepts two command-line flags: + valgrind-listener accepts two + command-line flags: or : @@ -293,13 +291,13 @@ message is written to the commentary. Here's an example from Memcheck: This message says that the program did an illegal 4-byte read of address 0xBFFFF74C, which, as far as Memcheck can tell, is not a valid -stack address, nor corresponds to any current malloc'd or free'd -blocks. The read is happening at line 45 of +stack address, nor corresponds to any current heap blocks or recently freed +heap blocks. The read is happening at line 45 of bogon.cpp, called from line 66 of the same file, -etc. For errors associated with an identified malloc'd/free'd block, -for example reading free'd memory, Valgrind reports not only the -location where the error happened, but also where the associated block -was malloc'd/free'd. +etc. For errors associated with an identified (current or freed) heap block, +for example reading freed memory, Valgrind reports not only the +location where the error happened, but also where the associated heap block +was allocated/freed. Valgrind remembers all error reports. When an error is detected, it is compared against old reports, to see if it is a duplicate. If so, @@ -313,10 +311,9 @@ counts. This makes it easy to see which errors have occurred most frequently. Errors are reported before the associated operation actually -happens. If you're using a tool (eg. Memcheck) which does -address checking, and your program attempts to read from address zero, -the tool will emit a message to this effect, and the program will then -duly die with a segmentation fault. +happens. For example, if you're using Memcheck and your program attempts to +read from address zero, Memcheck will emit a message to this effect, and +your program will then likely die with a segmentation fault. In general, you should try and fix errors in the order that they are reported. Not doing so can be confusing. For example, a program @@ -348,9 +345,9 @@ since it may have a bad effect on performance. Suppressing errors -The error-checking tools detect numerous problems in the base -libraries, such as the GNU C library, and the X11 client libraries, -which come pre-installed on your GNU/Linux system. You can't easily fix +The error-checking tools detect numerous problems in the system +libraries, such as the C library, +which come pre-installed with your OS. You can't easily fix these, but you don't want to see these errors (and yes, there are many!) So Valgrind reads a list of errors to suppress at startup. A default suppression file is created by the @@ -561,14 +558,8 @@ to malloc.. The tools also accept tool-specific flags, which are documented separately for each tool. -You invoke Valgrind like this: - - - Valgrind's default settings succeed in giving reasonable behaviour -in most cases. We group the available options by rough -categories. +in most cases. We group the available options by rough categories. Tool-selection option @@ -579,10 +570,10 @@ categories. - + - Run the Valgrind tool called name, + Run the Valgrind tool called toolname, e.g. Memcheck, Cachegrind, etc. @@ -662,25 +653,14 @@ categories. - - - - - - Run the Valgrind tool called toolname, - e.g. Memcheck, Cachegrind, etc. - - - When enabled, Valgrind will trace into sub-processes - initiated via the exec system call. This can be - confusing and isn't usually what you want, so it is disabled by - default. + initiated via the exec system call. This is + necessary for multi-process programs. Note that Valgrind does trace into the child of a fork (it would be difficult not to, since @@ -825,63 +805,52 @@ that can report errors, e.g. Memcheck, but not Cachegrind. - When enabled, output will be in XML format. This is aimed - at making life easier for tools that consume Valgrind's output - as input, such as GUI front ends. Currently this option works - with Memcheck, Helgrind and Ptrcheck. The output format is - specified in the - file + When enabled, the important parts of the output (e.g. tool error + messages) will be in XML format rather than plain text. Furthermore, + the XML output will be sent to a different output channel than the + plain text output. Therefore, you also must use one of + , or + to specify where the XML is to be sent. + + + Less important messages will still be printed in plain text, but + because the XML output and plain text output are sent to different + output channels (the destination of the plain text output is still + controlled by , + and ) this should not cause problems. + + + This option is aimed at making life easier for tools that consume + Valgrind's output as input, such as GUI front ends. Currently this + option works with Memcheck, Helgrind and Ptrcheck. The output format + is specified in the file docs/internals/xml-output-protocol4.txt in the source tree for Valgrind 3.5.0 or later. + + The recommended flags for a GUI to pass, when requesting + XML output, are: to enable XML output, + to send the XML output to a (presumably + GUI-selected) file, to send the plain + text output to a second GUI-selected file, + , and + to restrict the plain text output to critical + error messages created by Valgrind itself. For example, failure to + read a specified suppressions file counts as a critical error message. + In this way, for a successful run the text output file will be empty. + But if it isn't empty, then it will contain important information + which the GUI user should be made aware + of. - - - Specifies that Valgrind should send its XML output to the - specified file descriptor. By default, this is disabled. To - use XML output, you need to give to - tell the tool you want XML output. You also need to use one of - , - or to specify where the XML is to - be sent. If you request XML output but do not specify a - destination for it, Valgrind will refuse to start up. - - Note that XML output is sent on a different channel (file - descriptor) to normal text output. It is entirely legitimate to - select XML output, use one - of , - or to specify where it should be - sent, and at the same time use one of - , - or to specify where any residual - text messages should be sent. - - The recommended flags for a GUI to pass, when requesting - XML output, are: to enable XML - output, - to send the XML output to a - (presumably GUI-selected) file, to - send the text output to a second GUI-selected file, - and to restrict the text output to critical - error messages created by Valgrind itself. For example, failure - to read a specified suppressions file counts as a critical error - message. In this way, for a successful run the text output file - will be empty. But if it isn't empty, then it will contain - important information which the GUI user should be made aware - of. - - Note that GUIs are strongly recommended to also - specify . - - - + specified file descriptor. It must be used in conjunction with + . @@ -891,11 +860,11 @@ that can report errors, e.g. Memcheck, but not Cachegrind. Specifies that Valgrind should send its XML output - to the specified file. Any - or sequences appearing in the filename are - expanded in exactly the same way as they are - for . See the description - of for details. + to the specified file. It must be used in conjunction with + . Any or + sequences appearing in the filename are expanded + in exactly the same way as they are for . + See the description of for details. @@ -906,10 +875,10 @@ that can report errors, e.g. Memcheck, but not Cachegrind. Specifies that Valgrind should send its XML output the - specified port at the specified IP address. This option behaves - identically to , except that it - specifies the destination for XML output rather than for text - output. See the description of + specified port at the specified IP address. It must be used in + conjunction with . The form of the argument + is the same as that used by . + See the description of for further details. @@ -940,8 +909,8 @@ that can report errors, e.g. Memcheck, but not Cachegrind. mentioned in suppressions files should be in their mangled form. Valgrind does not demangle function names when searching for applicable suppressions, because to do otherwise would make - suppressions file contents dependent on the state of Valgrind's - demangling machinery, and would also be slow and pointless. + suppression file contents dependent on the state of Valgrind's + demangling machinery, and also slow down suppression matching. @@ -950,14 +919,11 @@ that can report errors, e.g. Memcheck, but not Cachegrind. - By default, Valgrind shows twelve levels of function call - names to help you identify program locations. You can change that - number with this option. This can help in determining the - program's location in deeply-nested call chains. Note that errors - are commoned up using only the top four function locations (the - place in the current function, and that of its three immediate - callers). So this doesn't affect the total number of errors - reported. + Specifies the maximum number of entries shown in stack traces + that identify program locations. Note that errors are commoned up + using only the top four function locations (the place in the current + function, and that of its three immediate callers). So this doesn't + affect the total number of errors reported. The maximum value for this is 50. Note that higher settings will make Valgrind run a bit more slowly and take a bit more @@ -1000,18 +966,18 @@ that can report errors, e.g. Memcheck, but not Cachegrind. By default, stack traces for errors do not show any - functions that appear beneath main() + functions that appear beneath main because most of the time it's uninteresting C library stuff and/or - gobbledygook. Alternatively, if main() is not + gobbledygook. Alternatively, if main is not present in the stack trace, stack traces will not show any functions - below main()-like functions such as glibc's - __libc_start_main()). Furthermore, if - main()-like functions are present in the trace, - they are normalised as "(below main)", in order to make the output - more deterministic. + below main-like functions such as glibc's + __libc_start_main. Furthermore, if + main-like functions are present in the trace, + they are normalised as (below main), in order to + make the output more deterministic. If this option is enabled, all stack trace entries will be - shown and main()-like functions will not be + shown and main-like functions will not be normalised. @@ -1034,7 +1000,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. When set to yes, Valgrind will pause after every error shown and print the line: - ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ---- + ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ---- The prompt's behaviour is the same as for the option (see below). @@ -1079,7 +1045,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. When enabled, Valgrind will pause after every error shown and print the line: - ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ---- + ---- Attach to debugger ? --- [Return/N/n/Y/y/C/c] ---- Pressing Ret, or N Ret or n Ret, causes Valgrind not to start a debugger @@ -1103,7 +1069,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. Specify the debugger to use with the command. The default debugger is - gdb. This option is a template that is expanded by Valgrind at + GDB. This option is a template that is expanded by Valgrind at runtime. %f is replaced with the executable's file name and %p is replaced by the process ID of the executable. @@ -1148,9 +1114,9 @@ that can report errors, e.g. Memcheck, but not Cachegrind. This flag is only relevant when running Valgrind on - MacOS X. + Mac OS X. - MacOS X uses a deferred debug information (debuginfo) + Mac OS X uses a deferred debug information (debuginfo) linking scheme. When object files containing debuginfo are linked into a .dylib or an executable, the debuginfo is not copied into the final file. @@ -1183,13 +1149,14 @@ that can report errors, e.g. Memcheck, but not Cachegrind. Valgrind will not attempt to run dsymutil on any executable or library in - /usr, - /bin, - /sbin, - /opt, - /sw, - /System or - /Library + /usr/, + /bin/, + /sbin/, + /opt/, + /sw/, + /System/, + /Library/ or + /Applications/ since dsymutil will always fail in such situations. It fails both because the debuginfo for such pre-installed system components is not available anywhere, @@ -1199,7 +1166,9 @@ that can report errors, e.g. Memcheck, but not Cachegrind. Be careful when using , since it will cause pre-existing .dSYM - directories to be silently deleted and re-created. + directories to be silently deleted and re-created. Also note the + dsymutil is quite slow, sometimes + excessively so. @@ -1299,27 +1268,28 @@ that can report errors, e.g. Memcheck, but not Cachegrind. - -<computeroutput>malloc()</computeroutput>-related Options + +<computeroutput>malloc</computeroutput>-related Options For tools that use their own version of -malloc() (e.g. Memcheck and +malloc (e.g. Memcheck and Massif), the following options apply. - + - By default Valgrind's malloc(), - realloc(), etc, return 8-byte aligned - addresses. This is standard for most processors. However, some - programs might assume that malloc() et al - return 16-byte or more aligned memory. The supplied value must be - between 8 and 4096 inclusive, and must be a power of two. + By default Valgrind's malloc, + realloc, etc, return a block whose starting + address is 8-byte aligned or 16-byte aligned (the value depends on the + platform and matches the platform default). This option allows you to + specify a different alignment. The supplied value must be greater + than or equal to the default, less than or equal to 4096, and must be + a power of two. @@ -1344,6 +1314,8 @@ need to use these. + This flag is only relevant when running Valgrind on Linux. + The GNU C library (libc.so), which is used by all programs, may allocate memory for its own uses. Usually it doesn't bother to free that memory when the program @@ -1411,10 +1383,10 @@ need to use these. need it. Currently known variants are: - Support the sys_broc system - call on x86. This is for running on BProc, which is a minor - variant of standard Linux which is sometimes used for building - clusters. + Support the + sys_broc system call on x86. This is for + running on BProc, which is a minor variant of standard Linux which + is sometimes used for building clusters. @@ -1437,21 +1409,34 @@ need to use these. This option controls Valgrind's detection of self-modifying - code. Valgrind can do no detection, detect self-modifying code on - the stack, or detect self-modifying code anywhere. Note that the - default option will catch the vast majority of cases, as far as we - know. Running with all will slow Valgrind down - greatly. Running with none will rarely - speed things up, since very little code gets put on the stack for - most programs. + code. If no checking is done, if a program executes some code, then + overwrites it with new code, and executes the new code, Valgrind will + continue to execute the translations it made for the old code. This + will likely lead to incorrect behaviour and/or crashes. + + Valgrind has three levels of self-modifying code detection: + no detection, detect self-modifying code on the stack (which used by + GCC to implement nested functions), or detect self-modifying code + everywhere. Note that the default option will catch the vast majority + of cases. The main case it will not catch is programs such as JIT + compilers that dynamically generate code and + subsequently overwrite part or all of it. Running with + all will slow Valgrind down greatly. Running with + none will rarely speed things up, since very little + code gets put on the stack for most programs. The + VALGRIND_DISCARD_TRANSLATIONS client request is + an alternative to that requires more + effort but is much faster; see for more details. Some architectures (including ppc32 and ppc64) require programs which create code at runtime to flush the instruction cache in between code generation and first use. Valgrind observes and honours such instructions. Hence, on ppc32/Linux and ppc64/Linux, Valgrind always provides complete, transparent - support for self-modifying code. It is only on x86/Linux - and amd64/Linux that you need to use this flag. + support for self-modifying code. It is only on platforms such as + x86/Linux, AMD64/Linux and x86/Darwin that you need to use this + flag. @@ -1499,16 +1484,15 @@ command-line options. Options processed later override those processed earlier; for example, options in ./.valgrindrc will take precedence over those in -~/.valgrindrc. The first two -are particularly useful for setting the default tool to -use. +~/.valgrindrc. Please note that the ./.valgrindrc file is ignored if it is marked as world writeable or not owned -by the current user. This is because the .valgrindrc can contain options -that are potentially harmful or can be used by a local attacker to -execute code under your user account. +by the current user. This is because the +./.valgrindrc can contain options that are +potentially harmful or can be used by a local attacker to execute code under +your user account. Any tool-specific options put in @@ -1537,17 +1521,12 @@ don't understand Support for Threads -Valgrind supports programs which use POSIX pthreads. -Getting this to work was technically challenging but it now works -well enough for significant threaded applications to run. - -The main thing to point out is that although Valgrind works -with the standard Linux threads library (eg. NPTL or LinuxThreads), it -serialises execution so that only one thread is running at a time. This -approach avoids the horrible implementation problems of implementing a +The main thing to point out with respect to multithreaded programs is +that your program will use the native threading library, but Valgrind +serialises execution so that only one (kernel) thread is running at a time. +This approach avoids the horrible implementation problems of implementing a truly multiprocessor version of Valgrind, but it does mean that threaded -apps run only on one CPU, even if you have a multiprocessor -machine. +apps run only on one CPU, even if you have a multiprocessor machine. Valgrind schedules your program's threads in a round-robin fashion, with all threads having equal priority. It switches threads @@ -1556,22 +1535,13 @@ instructions), which means you'll get a much finer interleaving of thread executions than when run natively. This in itself may cause your program to behave differently if you have some kind of concurrency, critical race, locking, or similar, bugs. In that case -you might consider using Valgrind's Helgrind tool to track them down. +you might consider using the tools Helgrind and/or DRD to track them +down. -Your program will use the native -libpthread, but not all of its facilities -will work. In particular, synchronisation of processes via shared-memory -segments will not work. This relies on special atomic instruction sequences -which Valgrind does not emulate in a way which works between processes. -Unfortunately there's no way for Valgrind to warn when this is happening, -and such calls will mostly work. Only when there's a race will -it fail. - - -Valgrind also supports direct use of the -clone() system call, -futex() and so on. -clone() is supported where either +On Linux, Valgrind also supports direct use of the +clone system call, +futex and so on. +clone is supported where either everything is shared (a thread) or nothing is shared (fork-like); partial sharing will fail. Again, any use of atomic instruction sequences in shared memory between processes will not work reliably. @@ -1595,7 +1565,7 @@ to use . If your program dies as a result of a fatal core-dumping signal, Valgrind will generate its own core file (vgcore.NNNNN) containing your program's -state. You may use this core file for post-mortem debugging with gdb or +state. You may use this core file for post-mortem debugging with GDB or similar. (Note: it will not generate a core if your core dump size limit is 0.) At the time of writing the core dumps do not include all the floating point register information. @@ -1627,7 +1597,7 @@ with make regtest. There are five options (in addition to the usual - which affect how Valgrind is built: + which affect how Valgrind is built: @@ -1648,14 +1618,6 @@ with make regtest. override the automatic test. - - - Specifies the path to the underlying VEX dynamic-translation - library. By default this is taken to be in the VEX directory off - the root of the source tree. - - - @@ -1707,10 +1669,9 @@ plans to disable them. If one of them breaks, please mail us! If you get an assertion failure in m_mallocfree.c, this may have happened because -your program wrote off the end of a malloc'd block, or before its -beginning. Valgrind hopefully will have emitted a proper message to that -effect before dying in this way. This is a known problem which -we should fix. +your program wrote off the end of a heap block, or before its +beginning, thus corrupting head metadata. Valgrind hopefully will have +emitted a message to that effect before dying in this way. Read the for more advice about common problems, crashes, etc. @@ -1725,18 +1686,19 @@ crashes, etc. The following list of limitations seems long. However, most programs actually work fine. -Valgrind will run Linux ELF binaries, on a kernel 2.4.X or 2.6.X -system, on the x86, amd64, ppc32 and ppc64 architectures, subject to the -following constraints: +Valgrind will run programs on the supported platforms +subject to the following constraints: On x86 and amd64, there is no support for 3DNow! instructions. If the translator encounters these, Valgrind will generate a SIGILL when the instruction is executed. Apart from that, on x86 and amd64, - essentially all instructions are supported, up to and including SSE3. + essentially all instructions are supported, up to and including SSSE3. + + On ppc32 and ppc64, almost all integer, floating point and Altivec instructions are supported. Specifically: integer and FP insns that are mandatory for PowerPC, the "General-purpose optional" group (fsqrt, fsqrts, @@ -1744,13 +1706,6 @@ following constraints: the Altivec (also known as VMX) SIMD instruction set, are supported. - - Atomic instruction sequences are not properly supported, in the - sense that their atomicity is not preserved. This will affect any - use of synchronization via memory shared between processes. They - will appear to work, but fail sporadically. - - If your program does its own memory management, rather than using malloc/new/free/delete, it should still work, but Memcheck's @@ -1796,11 +1751,12 @@ following constraints: the trampolines GCC uses to implemented nested functions. If you regenerate code somewhere other than the stack, you will need to use the flag, and Valgrind will run more - slowly than normal. + slowly than normal. Or you can add client requests that tell Valgrind + when your program has overwritten code. - As of version 3.0.0, Valgrind has the following limitations + Valgrind has the following limitations in its implementation of x86/AMD64 floating point relative to IEEE754. @@ -1860,7 +1816,7 @@ following constraints: - As of version 3.0.0, Valgrind has the following limitations in + Valgrind has the following limitations in its implementation of x86/AMD64 SSE2 FP arithmetic, relative to IEEE754. @@ -1873,7 +1829,7 @@ following constraints: - As of version 3.2.0, Valgrind has the following limitations + Valgrind has the following limitations in its implementation of PPC32 and PPC64 floating point arithmetic, relative to IEEE754. @@ -1951,7 +1907,7 @@ sewardj@phoenix:~/newmat10$ ~/Valgrind-6/valgrind -v ./bogon ==25832== For a detailed leak analysis, rerun with: --leak-check=yes ]]> -The GCC folks fixed this about a week before gcc-3.0 +The GCC folks fixed this about a week before GCC 3.0 shipped. @@ -1960,7 +1916,7 @@ shipped. Warning Messages You Might See -Most of these only appear if you run in verbose mode +Some of these only appear if you run in verbose mode (enabled by ): diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml index 569d05e67..1d1e42ab4 100644 --- a/docs/xml/manual-intro.xml +++ b/docs/xml/manual-intro.xml @@ -27,7 +27,7 @@ and without disturbing the existing structure. Cachegrind is a cache and branch-prediction - profiler. It can help you make your programs run faster. + profiler. It helps you make your programs run faster. @@ -38,7 +38,7 @@ and without disturbing the existing structure. Helgrind is a thread error detector. - It can help you make your multi-threaded programs more correct. + It helps you make your multi-threaded programs more correct. @@ -49,7 +49,7 @@ and without disturbing the existing structure. - Massif is a heap profiler. It can help you + Massif is a heap profiler. It helps you make your programs use less memory. @@ -117,8 +117,8 @@ it supports. Then, each tool has its own chapter in this manual. You only need to read the documentation for the core and for the tool(s) you actually use, although you may find it helpful to be at least a little bit familiar with what all tools do. If you're new to all this, you probably -want to run the Memcheck tool. The final chapter explains how to write a -new tool. +want to run the Memcheck tool and you might find the useful. Be aware that the core understands some command line flags, and the tools have their own flags which they know about. This means @@ -126,8 +126,6 @@ there is no central place describing all the flags that are accepted -- you have to read the flags documentation both for and for the tool you want to use. -The manual is quite big and complex. If you want to start using -Valgrind more quickly, read . diff --git a/docs/xml/manual-writing-tools.xml b/docs/xml/manual-writing-tools.xml index 002e77b75..e579d7be8 100644 --- a/docs/xml/manual-writing-tools.xml +++ b/docs/xml/manual-writing-tools.xml @@ -225,7 +225,7 @@ a tool assertion fails. Others have other uses. be left untouched (they default to False). They determine whether a tool can do various things such as: record, report and suppress errors; process command line options; wrap system calls; -record extra information about malloc'd blocks, etc. +record extra information about heap blocks, etc. For example, if a tool wants the core's help in recording and reporting errors, it must call @@ -240,13 +240,13 @@ all the needs. Third, the tool can indicate which events in core it wants to be notified about, using the functions VG_(track_*)(). -These include things such as blocks of memory being malloc'd, the stack +These include things such as heap blocks being allocated, the stack pointer changing, a mutex being locked, etc. If a tool wants to know about this, it should provide a pointer to a function, which will be called when that event happens. -For example, if the tool want to be notified when a new block of -memory is malloc'd, it should call +For example, if the tool want to be notified when a new heap block +is allocated, it should call VG_(track_new_mem_heap)() with an appropriate function pointer, and the assigned function will be called each time this happens. diff --git a/drd/docs/drd-manual.xml b/drd/docs/drd-manual.xml index 3052b4f0d..996e121cf 100644 --- a/drd/docs/drd-manual.xml +++ b/drd/docs/drd-manual.xml @@ -75,7 +75,7 @@ Some examples of multithreaded programming paradigms are: is well suited for computational intensive applications. As an example, an open source image processing software package is using OpenMP to maximize performance on systems with multiple CPU - cores. The gcc compiler supports the + cores. GCC supports the OpenMP standard from version 4.2.0 on. @@ -88,7 +88,7 @@ Some examples of multithreaded programming paradigms are: is a so-called optimistic approach. There is a prototype of the Intel C Compiler (icc) available that supports STM. Research about the addition of STM support - to gcc is ongoing. + to GCC is ongoing. @@ -1205,8 +1205,8 @@ with a thread checking tool. -DRD supports OpenMP shared-memory programs generated by gcc. The gcc -compiler supports OpenMP since version 4.2.0. Gcc's runtime support +DRD supports OpenMP shared-memory programs generated by GCC. GCC +supports OpenMP since version 4.2.0. GCC's runtime support for OpenMP programs is provided by a library called libgomp. The synchronization primitives implemented in this library use Linux' futex system call directly, unless the @@ -1214,9 +1214,9 @@ library has been configured with the --disable-linux-futex flag. DRD only supports libgomp libraries that have been configured with this flag and in which symbol information is present. For most Linux distributions this -means that you will have to recompile gcc. See also the script +means that you will have to recompile GCC. See also the script drd/scripts/download-and-build-gcc in the -Valgrind source tree for an example of how to compile gcc. You will +Valgrind source tree for an example of how to compile GCC. You will also have to make sure that the newly compiled libgomp.so library is loaded when OpenMP programs are started. This is possible by adding a line similar to the @@ -1266,14 +1266,14 @@ declared at omp_matinv.c:160, in frame #0 of thread 1 ]]> In the above output the function name gj.omp_fn.0 -has been generated by gcc from the function name +has been generated by GCC from the function name gj. The allocation context information shows that the data race has been caused by modifying the variable k. -Note: for gcc versions before 4.4.0, no allocation context information is -shown. With these gcc versions the most usable information in the above output +Note: for GCC versions before 4.4.0, no allocation context information is +shown. With these GCC versions the most usable information in the above output is the source file name and the line number where the data race has been detected (omp_matinv.c:203). @@ -1673,8 +1673,8 @@ approach for managing thread names is as follows: - If you compile the DRD source code yourself, you need gcc 3.0 or - later. Gcc 2.95 is not supported. + If you compile the DRD source code yourself, you need GCC 3.0 or + later. GCC 2.95 is not supported. diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index f73d05a46..2b2389899 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -748,11 +748,11 @@ of false data-race errors. the futex syscall, which causes total chaos since in Helgrind since it cannot "see" those. Fortunately, this can be solved using a configuration-time - flag (for gcc). Rebuild gcc from source, and configure using + flag (for GCC). Rebuild GCC from source, and configure using --disable-linux-futex. This makes libgomp.so use the standard POSIX threading primitives instead. Note that this was tested - using gcc-4.2.3 and has not been re-tested using more recent gcc + using GCC 4.2.3 and has not been re-tested using more recent GCC versions. We would appreciate hearing about any successes or failures with more recent versions. @@ -1096,7 +1096,7 @@ some time. when provided with unbounded storage for conflicting access info. This should be investigated. - Document races caused by gcc's thread-unsafe code + Document races caused by GCC's thread-unsafe code generation for speculative stores. In the interim see http://gcc.gnu.org/ml/gcc/2007-10/msg00266.html diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index 665c9e2d2..28934c7df 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -535,7 +535,7 @@ file, which will almost certainly make it unreadable by ms_print. If heap profiling is enabled, gives the number of administrative bytes per block to use. This should be an estimate of the average, since it may vary. For example, the allocator used by - glibc requires somewhere between 4 to + glibc on Linux 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 account for this. diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 7bf574185..4474818ea 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -129,9 +129,6 @@ difficult-to-diagnose crashes. nonsensical. Memcheck checks for and rejects this combination at startup. - Origin tracking is a new feature, introduced in Valgrind - version 3.4.0. - @@ -180,7 +177,7 @@ difficult-to-diagnose crashes. or some such large number. - Note that the setting + Note that the setting does not affect Memcheck's ability to find leaks. It only changes how the results are presented. @@ -217,17 +214,17 @@ difficult-to-diagnose crashes. When enabled, assume that reads and writes some small - distance below the stack pointer are due to bugs in gcc 2.96, and + 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 ancient + default. Note that GCC 2.96 is the default compiler on some ancient 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. + recent GCC in which this bug is fixed. You may also need to use this flag when working with - gcc/g++ 3.X or 4.X on 32-bit PowerPC Linux. This is because - gcc/g++ generates code which occasionally accesses below the + GCC 3.X or 4.X on 32-bit PowerPC Linux. This is because + GCC generates code which occasionally accesses below the stack pointer, particularly for floating-point to/from integer conversions. This is in violation of the 32-bit PowerPC ELF specification, which makes no provision for locations below the @@ -336,16 +333,16 @@ 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 +the block was freed. Likewise, if it should turn out to be just off +the end of a heap 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. +block was allocated. 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. +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 @@ -402,11 +399,10 @@ complains. 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. + The contents of heap blocks (allocated with + malloc, new, or a similar + function) before you (or a constructor) write something there. + @@ -438,7 +434,7 @@ 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 +make sense of the address freed. 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. @@ -563,7 +559,7 @@ call. ]]> ... because the program has (a) tried to write uninitialised junk -from the malloc'd block to the standard output, and (b) passed an +from the heap 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 @@ -1015,12 +1011,12 @@ to generate truly appalling code for accessing arrays of struct S's on some architectures. So s1 occupies 8 bytes, yet only 5 of them will -be initialised. For the assignment s2 = s1, gcc +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 behaviour described above -is necessary. This allows gcc to copy +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. @@ -1580,11 +1576,10 @@ the same mpicc you use to build the MPI application you want to debug. By default, Valgrind tries mpicc, but you can specify a different one by using the configure-time flag -. Currently the +. Currently the wrappers are only buildable with mpiccs which are based on GNU -gcc or Intel's -icc. +GCC or Intel's C++ Compiler. Check that the configure script prints a line like this: