From 4e495edf4ae3ca9d4afd1bd3f271d712636cbc9e Mon Sep 17 00:00:00 2001 From: Nicholas Nethercote Date: Mon, 10 Aug 2009 01:29:14 +0000 Subject: [PATCH] Make "option" terminology consistent some more. Also tweaked the mempool Memcheck section a little. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10759 --- cachegrind/docs/cg-manual.xml | 12 ++-- callgrind/docs/cl-manual.xml | 41 ++++++----- coregrind/m_main.c | 2 +- drd/docs/drd-manual.xml | 10 +-- exp-bbv/docs/bbv-manual.xml | 6 +- exp-ptrcheck/docs/pc-manual.xml | 8 +-- helgrind/docs/hg-manual.xml | 10 +-- lackey/docs/lk-manual.xml | 6 +- massif/docs/ms-manual.xml | 12 ++-- memcheck/docs/mc-manual.xml | 117 +++++++++++++++++--------------- 10 files changed, 113 insertions(+), 111 deletions(-) diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 88db94e75a..ed6021757f 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -90,7 +90,7 @@ executed per line, which can be useful for traditional profiling. First off, as for normal Valgrind use, you probably want to compile with debugging info (the - flag). But by contrast with + option). But by contrast with normal Valgrind use, you probably do want to turn optimisation on, since you should profile your program as it will be normally run. @@ -151,7 +151,7 @@ not Branch prediction statistics are not collected by default. -To do so, add the flag . +To do so, add the option . @@ -703,8 +703,8 @@ fail these checks. - -Cachegrind Options + +Cachegrind Command-line Options Cachegrind-specific options are: @@ -790,8 +790,8 @@ fail these checks. - -cg_annotate Options + +cg_annotate Command-line Options diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 818237af9c..7e43bfa44c 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -46,10 +46,10 @@ of the profiling, two command line tools are provided: callgrind_control This command enables you to interactively observe and control - the status of currently running applications, without stopping - the application. You can - get statistics information as well as the current stack trace, and - you can request zeroing of counters or dumping of profile data. + the status of a program currently running under Callgrind's control, + without stopping the program. You can get statistics information as + well as the current stack trace, and you can request zeroing of counters + or dumping of profile data. @@ -105,7 +105,7 @@ on heuristics to detect calls and returns. Basic Usage As with Cachegrind, you probably want to compile with debugging info - (the flag) and with optimization turned on. + (the option) and with optimization turned on. To start a profile run for a program, execute: valgrind --tool=callgrind [callgrind options] your-program [program options] @@ -476,15 +476,15 @@ callgrind.out.pid.part-threa intermingled, which almost certainly is not what you want. You will be able to control the new child independently from - the parent via callgrind_control. + the parent via callgrind_control. - -Callgrind Options + +Callgrind Command-line Options In the following, options are grouped into classes. @@ -600,8 +600,7 @@ These options influence the name and format of the profile data files. These options specify when actions relating to event counts are to -be executed. For interactive control use -callgrind_control. +be executed. For interactive control use callgrind_control. @@ -716,7 +715,7 @@ Also see . Collection state can be toggled at entry and exit of a given function with the option . If you - use this flag, collection + use this option, collection state should be disabled at the beginning. Note that the specification of implicitly sets @@ -1104,8 +1103,8 @@ their arguments. - -callgrind_annotate Options + +callgrind_annotate Command-line Options @@ -1210,16 +1209,14 @@ their arguments. - -Description and options of callgrind_control + +callgrind_control Command-line Options -The command callgrind_control allows to control - programs being run by the Valgrind tool Callgrind. By default, it acts - on all programs detected to be run by the current user via Callgrind. - It is possible to limit the actions to specified Callgrind runs by - providing a list of pids or program names as argument. - The default action is to give some brief information about the applications - being run by Callgrind. +By default, callgrind_control acts on all programs run by the + current user under Callgrind. It is possible to limit the actions to + specified Callgrind runs by providing a list of pids or program names as + argument. The default action is to give some brief information about the + applications being run under Callgrind. diff --git a/coregrind/m_main.c b/coregrind/m_main.c index edaf9193a7..75c6944ca7 100644 --- a/coregrind/m_main.c +++ b/coregrind/m_main.c @@ -1123,7 +1123,7 @@ static void print_preamble ( Bool logging_to_fd, VexArchInfo vex_archinfo; if (!logging_to_fd) VG_(message)(Vg_DebugMsg, "\n"); - VG_(message)(Vg_DebugMsg, "Valgrind flags:\n"); + VG_(message)(Vg_DebugMsg, "Valgrind options:\n"); for (i = 0; i < VG_(sizeXA)( VG_(args_for_valgrind) ); i++) { VG_(message)(Vg_DebugMsg, " %s\n", diff --git a/drd/docs/drd-manual.xml b/drd/docs/drd-manual.xml index 01690fe178..d9d5f358c4 100644 --- a/drd/docs/drd-manual.xml +++ b/drd/docs/drd-manual.xml @@ -315,8 +315,8 @@ DRD is based on the happens-before algorithm. Using DRD - -Command Line Options + +DRD Command-line Options The following command-line options are available for controlling the behavior of the DRD tool itself: @@ -1211,8 +1211,8 @@ 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 library has been configured with the ---disable-linux-futex flag. DRD only supports -libgomp libraries that have been configured with this flag and in +--disable-linux-futex option. DRD only supports +libgomp libraries that have been configured with this option and in which symbol information is present. For most Linux distributions this means that you will have to recompile GCC. See also the script drd/scripts/download-and-build-gcc in the @@ -1416,7 +1416,7 @@ The following information may be helpful when using DRD: - Compile with flag instead of + Compile with option instead of . This will reduce the amount of generated code, may reduce the amount of debug info and will speed up DRD's processing of the client program. For more information, diff --git a/exp-bbv/docs/bbv-manual.xml b/exp-bbv/docs/bbv-manual.xml index 93a4392125..f6ba05439b 100644 --- a/exp-bbv/docs/bbv-manual.xml +++ b/exp-bbv/docs/bbv-manual.xml @@ -110,10 +110,10 @@ command line. - -BBV Command Line Options + +BBV Command-line Options - BBV-specific options are: + BBV-specific command-line options are: diff --git a/exp-ptrcheck/docs/pc-manual.xml b/exp-ptrcheck/docs/pc-manual.xml index e9a2137764..01c549e069 100644 --- a/exp-ptrcheck/docs/pc-manual.xml +++ b/exp-ptrcheck/docs/pc-manual.xml @@ -46,10 +46,10 @@ known, is entirely novel. - -Ptrcheck Options + +Ptrcheck Command-line Options -Ptrcheck-specific options are: +Ptrcheck-specific command-line options are: @@ -89,7 +89,7 @@ known, is entirely novel. 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 + at all possible, such code should be fixed. This option should be used only as a last resort. diff --git a/helgrind/docs/hg-manual.xml b/helgrind/docs/hg-manual.xml index 24c284a8d0..d45664bccb 100644 --- a/helgrind/docs/hg-manual.xml +++ b/helgrind/docs/hg-manual.xml @@ -351,7 +351,7 @@ program. However, it does require Helgrind to spend considerable extra time and memory at program startup to read the relevant debug info. Hence this facility is disabled by default. To enable it, you need - to give the --read-var-info=yes flag to + to give the --read-var-info=yes option to Helgrind. @@ -745,7 +745,7 @@ of false data-race errors. instructions and 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 + option (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 @@ -938,8 +938,8 @@ unlock(mx) unlock(mx) - -Helgrind Options + +Helgrind Command-line Options The following end-user options are available: @@ -1000,7 +1000,7 @@ unlock(mx) unlock(mx) for every single memory access made by the program. Historical information on not recently accessed locations is periodically discarded, to free up space in the cache. - This flag controls the size of the cache, in terms of the + This option controls the size of the cache, in terms of the number of different memory addresses for which conflicting access information is stored. If you find that Helgrind is showing race errors with only one stack instead of diff --git a/lackey/docs/lk-manual.xml b/lackey/docs/lk-manual.xml index e497eeebb5..a5c7bbd327 100644 --- a/lackey/docs/lk-manual.xml +++ b/lackey/docs/lk-manual.xml @@ -23,10 +23,10 @@ performance. - -Lackey Options + +Lackey Command-line Options -Lackey-specific options are: +Lackey-specific command-line options are: diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index e9f34474ba..7e7cf450cc 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -53,7 +53,7 @@ which parts of your program are responsible for allocating the heap memory. Using Massif and ms_print First off, as for the other Valgrind tools, you should compile with -debugging info (the flag). It shouldn't +debugging info (the option). It shouldn't matter much what optimisation level you compile your program with, as this is unlikely to affect the heap memory usage. @@ -606,10 +606,10 @@ in a particular column, which makes following the allocation chains easier. - -Massif Options + +Massif Command-line Options -Massif-specific options are: +Massif-specific command-line options are: @@ -824,8 +824,8 @@ way. - -ms_print Options + +ms_print Command-line Options ms_print's options are: diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml index 8a3da0d171..d5be024f96 100644 --- a/memcheck/docs/mc-manual.xml +++ b/memcheck/docs/mc-manual.xml @@ -167,7 +167,7 @@ and it is at this point that Memcheck complains. To see information on the sources of uninitialised data in your -program, use the flag. This +program, use the option. This makes Memcheck run more slowly, but can make it much easier to track down the root causes of uninitialised value errors. @@ -574,9 +574,9 @@ two examples show. - -Command-line flags specific to Memcheck + +Memcheck Command-Line Options @@ -720,7 +720,7 @@ two examples show. 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 + at all possible, such code should be fixed. This option should be used only as a last resort. @@ -742,7 +742,7 @@ two examples show. 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 + This option specifies the maximum total size, in bytes, of the blocks in the queue. The default value is ten million bytes. Increasing this increases the total amount of memory used by Memcheck but may detect invalid uses of freed @@ -760,11 +760,11 @@ two examples show. does not report them. The "small distance" is 256 bytes by 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 + option. 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 in which this bug is fixed. - You may also need to use this flag when working with + You may also need to use this option when working with 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 @@ -796,7 +796,7 @@ two examples show. by calloc, with the specified byte. This can be useful when trying to shake out obscure memory corruption problems. The allocated area is still - regarded by Memcheck as undefined -- this flag only affects its + regarded by Memcheck as undefined -- this option only affects its contents. @@ -812,7 +812,7 @@ two examples show. delete, etc, with the specified byte value. This can be useful when trying to shake out obscure memory corruption problems. The freed area is still - regarded by Memcheck as not valid for access -- this flag only + regarded by Memcheck as not valid for access -- this option only affects its contents. @@ -1173,7 +1173,7 @@ follows: 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. + details of the option for details. @@ -1343,11 +1343,12 @@ arguments. Memory Pools: describing and working with custom allocators Some programs use custom memory allocators, often for performance -reasons. Left to itself, Memcheck is unable to "understand" the -behaviour of custom allocation schemes and so may miss errors and -leaks in your program. What this section describes is a way to give -Memcheck enough of a description of your custom allocator that it can -make at least some sense of what is happening. +reasons. Left to itself, Memcheck is unable to understand the +behaviour of custom allocation schemes as well as it understands the +standard allocators, and so may miss errors and leaks in your program. What +this section describes is a way to give Memcheck enough of a description of +your custom allocator that it can make at least some sense of what is +happening. There are many different sorts of custom allocator, so Memcheck attempts to reason about them using a loose, abstract model. We @@ -1433,12 +1434,12 @@ inform Memcheck about changes to the state of a mempool: VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed): - This request registers the address "pool" as the anchor address - for a memory pool. It also provides a size "rzB", specifying how - large the redzones placed around chunks allocated from the pool - should be. Finally, it provides an "is_zeroed" flag that specifies - whether the pool's chunks are zeroed (more precisely: defined) - when allocated. + This request registers the address pool as the anchor + address for a memory pool. It also provides a size + rzB, specifying how large the redzones placed around + chunks allocated from the pool should be. Finally, it provides an + is_zeroed argument that specifies whether the pool's + chunks are zeroed (more precisely: defined) when allocated. Upon completion of this request, no chunks are associated with the @@ -1459,44 +1460,47 @@ inform Memcheck about changes to the state of a mempool: VALGRIND_MEMPOOL_ALLOC(pool, addr, size): - This request informs Memcheck that a "size"-byte chunk has been - allocated at "addr", and associates the chunk with the specified - "pool". If the pool was created with nonzero "rzB" redzones, Memcheck - will mark the "rzB" bytes before and after the chunk as NOACCESS. If - the pool was created with the "is_zeroed" flag set, Memcheck will mark - the chunk as DEFINED, otherwise Memcheck will mark the chunk as - UNDEFINED. + This request informs Memcheck that a size-byte chunk + has been allocated at addr, and associates the chunk with the + specified + pool. If the pool was created with nonzero + rzB redzones, Memcheck will mark the + rzB bytes before and after the chunk as NOACCESS. If + the pool was created with the is_zeroed argument set, + Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark + the chunk as UNDEFINED. VALGRIND_MEMPOOL_FREE(pool, addr): - This request informs Memcheck that the chunk at "addr" should no - longer be considered allocated. Memcheck will mark the chunk - associated with "addr" as NOACCESS, and delete its record of the - chunk's existence. + This request informs Memcheck that the chunk at addr + should no longer be considered allocated. Memcheck will mark the chunk + associated with addr as NOACCESS, and delete its + record of the chunk's existence. VALGRIND_MEMPOOL_TRIM(pool, addr, size): - This request "trims" the chunks associated with "pool". The request - only operates on chunks associated with "pool". Trimming is formally - defined as: + This request trims the chunks associated with pool. + The request only operates on chunks associated with + pool. Trimming is formally defined as: - All chunks entirely inside the range [addr,addr+size) are - preserved. + All chunks entirely inside the range + addr..(addr+size-1) are preserved. - All chunks entirely outside the range [addr,addr+size) are - discarded, as though VALGRIND_MEMPOOL_FREE - was called on them. + All chunks entirely outside the range + addr..(addr+size-1) are discarded, as though + VALGRIND_MEMPOOL_FREE was called on them. All other chunks must intersect with the range - [addr,addr+size); areas outside the intersection are marked as - NOACCESS, as though they had been independently freed with + addr..(addr+size-1); areas outside the + intersection are marked as NOACCESS, as though they had been + independently freed with VALGRIND_MEMPOOL_FREE. @@ -1508,9 +1512,9 @@ inform Memcheck about changes to the state of a mempool: VALGRIND_MOVE_MEMPOOL(poolA, poolB): This request informs Memcheck that the pool previously anchored at - address "poolA" has moved to anchor address "poolB". This is a - rare request, typically only needed if you - realloc the header of a mempool. + address poolA has moved to anchor address + poolB. This is a rare request, typically only needed + if you realloc the header of a mempool. No memory-status bits are altered by this request. @@ -1518,11 +1522,12 @@ inform Memcheck about changes to the state of a mempool: VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB, size): This request informs Memcheck that the chunk - previously allocated at address "addrA" within "pool" has been - moved and/or resized, and should be changed to cover the region - [addrB,addrB+size). This is a rare request, typically only needed - if you realloc a superblock or wish to - extend a chunk without changing its memory-status bits. + previously allocated at address addrA within + pool has been moved and/or resized, and should be + changed to cover the region addrB..(addrB+size-1). This + is a rare request, typically only needed if you + realloc a superblock or wish to extend a chunk + without changing its memory-status bits. No memory-status bits are altered by this request. @@ -1531,10 +1536,10 @@ inform Memcheck about changes to the state of a mempool: VALGRIND_MEMPOOL_EXISTS(pool): This request informs the caller whether or not Memcheck is currently - tracking a mempool at anchor address "pool". It evaluates to 1 when - there is a mempool associated with that address, 0 otherwise. This is a - rare request, only useful in circumstances when client code might have - lost track of the set of active mempools. + tracking a mempool at anchor address pool. It + evaluates to 1 when there is a mempool associated with that address, 0 + otherwise. This is a rare request, only useful in circumstances when + client code might have lost track of the set of active mempools. @@ -1585,7 +1590,7 @@ Valgrind's configure script will look for a suitable 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 +different one by using the configure-time option . Currently the wrappers are only buildable with mpiccs which are based on GNU -- 2.47.3