From: Nicholas Nethercote Date: Tue, 4 Aug 2009 05:59:46 +0000 (+0000) Subject: Overhaul Massif's manual, and a few minor related things. X-Git-Tag: svn/VALGRIND_3_5_0~144 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=74c920d72909ae9f34a6c71338fa88d39f94f893;p=thirdparty%2Fvalgrind.git Overhaul Massif's manual, and a few minor related things. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10706 --- diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 9e937eb161..fa3ca342ed 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -441,8 +441,7 @@ configuration, or failing that, via defaults). and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core - option . See here for details. + option . diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 43104bd368..aa8543ff52 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -534,8 +534,7 @@ These options influence the name and format of the profile data files. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core - option . See here for details. + option . When multiple dumps are made, the file name is modified further; see below. diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml index 28934c7df0..3e9d1c75a2 100644 --- a/massif/docs/ms-manual.xml +++ b/massif/docs/ms-manual.xml @@ -61,7 +61,7 @@ is unlikely to affect the heap memory usage. Then, to gather heap profiling information about the program prog, type: The program will execute (slowly). Upon completion, no summary @@ -74,7 +74,7 @@ data is written to a file. By default, this file is called the ms_print script. If the output file's name is massif.out.12345, type: +ms_print massif.out.12345]]> ms_print will produce (a) a graph showing the memory consumption over the program's execution, and (b) detailed information about the responsible @@ -257,7 +257,7 @@ deallocate heap memory, Massif will not record a peak snapshot. Some more details about the peak: the peak is determined by looking at every allocation, i.e. it is not just the peak among -the regular snapshots. However, recording the true peak is expensive, and +the regular snapshots. However, recording the true peak can be expensive, and so by default Massif records a peak whose size is within 1% of the size of the true peak. See the description of the option below for more @@ -350,12 +350,11 @@ a small amount of information is recorded for each one: option. Second, allocators often round up the number of bytes asked for to a - larger number. By default, if N bytes are asked for, Massif rounds N up - to the nearest multiple of 8 that is equal to or greater than N. This is - typical behaviour for allocators, and is required to ensure that elements - within the block are suitably aligned. The rounding size can be changed - with the option, although it - cannot be less than 8, and must be a power of two. + larger number, usually 8 or 16. This is required to ensure that elements + within the block are suitably aligned. If N bytes are asked for, Massif + rounds N up to the nearest multiple of the value specified by the + option. + The size of the stack(s). By default, stack profiling is off as it slows Massif down greatly. Therefore, the stack column is zero @@ -377,7 +376,7 @@ indicates all heap allocation functions such as malloc and C++ new. All heap allocations go through these functions, and so all 9,000 useful bytes (which is 99.21% of all allocated bytes) go through them. But how were malloc and new -called? At this point, every allocation so far has been due to line 21 +called? At this point, every allocation so far has been due to line 20 inside main, hence the second line in the tree. The indicates that main (line 20) called malloc. @@ -407,9 +406,9 @@ inside main, hence the second line in the tree. The ]]> The first four snapshots are similar to the previous ones. But then -the global allocation peak is reached, and a detailed snapshot is taken. -Its allocation tree shows that 20,000B of useful heap memory has been -allocated, and the lines and arrows indicate that this is from three +the global allocation peak is reached, and a detailed snapshot (number 14) +is taken. Its allocation tree shows that 20,000B of useful heap memory has +been allocated, and the lines and arrows indicate that this is from three different code locations: line 20, which is responsible for 10,000B (49.74%); line 5, which is responsible for 8,000B (39.79%); and line 10, which is responsible for 2,000B (9.95%). @@ -529,16 +528,16 @@ 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 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. + 15 bytes per block, depending on various factors. That allocator also + requires admin space for freed blocks, but Massif cannot + account for this. @@ -550,9 +549,9 @@ file, which will almost certainly make it unreadable by ms_print. Specifies whether stack profiling should be done. This option slows Massif down greatly, and so is off by default. Note that Massif assumes that the main stack has size zero at start-up. This is not - true, but measuring the actual stack size is not easy, and it reflects - the size of the part of the main stack that a user program actually - has control over. + true, but doing otherwise accurately is difficult. Furthermore, + starting at zero better indicates the size of the part of the main + stack that a user program actually has control over. @@ -580,11 +579,11 @@ file, which will almost certainly make it unreadable by ms_print. This option can be specified multiple times on the command line, to name multiple functions. - Note that overloaded C++ names must be written in full. Single - quotes may be necessary to prevent the shell from breaking them up. - For example: + Note that C++ names are demangled. Note also that overloaded + C++ names must be written in full. Single quotes may be necessary to + prevent the shell from breaking them up. For example: @@ -597,7 +596,7 @@ file, which will almost certainly make it unreadable by ms_print. Any direct heap allocation (i.e. a call to malloc, new, etc, or a call - to a function name in a + to a function named by an option) that occurs in a function specified by this option will be ignored. This is mostly useful for testing purposes. This option can be specified multiple times on the command line, to name multiple @@ -611,8 +610,8 @@ file, which will almost certainly make it unreadable by ms_print. realloc. - Note that overloaded C++ names must be written in full, as for - above. + The rules for writing C++ function names are the same as + for above. @@ -623,9 +622,9 @@ file, which will almost certainly make it unreadable by ms_print. The significance threshold for heap allocations, as a - percentage. Allocation tree entries that account for less than this - will be aggregated. Note that this should be specified in tandem with - ms_print's option of the same name. + percentage of total memory size. Allocation tree entries that account + for less than this will be aggregated. Note that this should be + specified in tandem with ms_print's option of the same name. @@ -647,7 +646,7 @@ file, which will almost certainly make it unreadable by ms_print. - + The time unit used for the profiling. There are three @@ -692,21 +691,11 @@ file, which will almost certainly make it unreadable by ms_print. and format specifiers can be used to embed the process ID and/or the contents of an environment variable in the name, as is the case for the core option - . See for details. + . - - - - - - The minimum alignment (and thus size) of heap blocks. - - - @@ -731,7 +720,7 @@ file, which will almost certainly make it unreadable by ms_print. - + Show the version number. @@ -750,7 +739,7 @@ file, which will almost certainly make it unreadable by ms_print. - + Width of the graph, in columns. @@ -759,7 +748,7 @@ file, which will almost certainly make it unreadable by ms_print. - + Height of the graph, in rows. @@ -775,9 +764,9 @@ file, which will almost certainly make it unreadable by ms_print. Massif's file format is plain text (i.e. not binary) and deliberately easy to read for both humans and machines. Nonetheless, the exact format is not described here. This is because the format is currently very -Massif-specific. We plan to make the format more general, and thus suitable -for possible use with other tools. Once this has been done, the format will -be documented here. +Massif-specific. In the future we hope to make the format more general, and +thus suitable for possible use with other tools. Once this has been done, +the format will be documented here. diff --git a/massif/ms_main.c b/massif/ms_main.c index 2b41fb7d32..ff4ace5953 100644 --- a/massif/ms_main.c +++ b/massif/ms_main.c @@ -49,7 +49,7 @@ // identified? [hmm, could make getting the name of alloc-fns more // difficult] [could dump full names to file, truncate in ms_print] // - make --show-below-main=no work -// - Options like --alloc-fn='operator new(unsigned, std::nothrow_t const&)' +// - Options like --alloc-fn='operator new(unsigned, std::nothrow_t const&)' // don't work in a .valgrindrc file or in $VALGRIND_OPTS. // m_commandline.c:add_args_from_string() needs to respect single quotes. // - With --stack=yes, want to add a stack trace for detailed snapshots so @@ -446,7 +446,7 @@ static void ms_print_usage(void) { VG_(printf)( " --heap=no|yes profile heap blocks [yes]\n" -" --heap-admin= average admin bytes per heap block;\n" +" --heap-admin= average admin bytes per heap block;\n" " ignored if --heap=no [8]\n" " --stacks=no|yes profile stack(s) [no]\n" " --depth= depth of contexts [30]\n" diff --git a/massif/ms_print.in b/massif/ms_print.in index 05b7782570..76f72aa670 100755 --- a/massif/ms_print.in +++ b/massif/ms_print.in @@ -66,10 +66,10 @@ usage: ms_print [options] options for the user, with defaults in [ ], are: -h --help show this message - -v --version show version + --version show version --threshold= significance threshold, in percent [$threshold] - --x= graph width, in columns; min=4, max=1000 [72] - --y= graph height, in rows; min=4, max=1000 [20] + --x=<4..1000> graph width, in columns [72] + --y=<4..1000> graph height, in rows [20] ms_print is Copyright (C) 2007-2007 Nicholas Nethercote. and licensed under the GNU General Public License, version 2. @@ -107,7 +107,7 @@ sub process_cmd_line() if ($arg =~ /^-/) { # --version - if ($arg =~ /^-v$|^--version$/) { + if ($arg =~ /^--version$/) { die("ms_print-$version\n"); # --threshold=X (tolerates a trailing '%')