diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 1b37a50ea..c1377b63a 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -8,7 +8,7 @@ Cachegrind: a cache and branch-prediction profiler To use this tool, you must specify ---tool=cachegrind on the + on the Valgrind command line. @@ -55,7 +55,7 @@ instruction executed, you can find out how many instructions are executed per line, which can be useful for traditional profiling. Branch profiling is not enabled by default. To use it, you must -additionally specify --branch-sim=yes +additionally specify on the command line. @@ -64,7 +64,7 @@ on the command line. First off, as for normal Valgrind use, you probably want to compile with debugging info (the --g flag). But by contrast with + flag). 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. @@ -83,7 +83,7 @@ be normally run. Branch prediction statistics are not collected by default. To do so, add the flag - --branch-sim=yes. + . This step should be done every time you want to collect @@ -98,7 +98,7 @@ be normally run. files to annotate can be specified manually, or manually on the command line, or "interesting" source files can be annotated automatically with the - --auto=yes option. You can + option. You can annotate C/C++ files or assembly language files equally easily. @@ -175,9 +175,9 @@ Cachegrind will fall back to using a default configuration (that of a model 3/4 Athlon). Cachegrind will tell you if this happens. You can manually specify one, two or all three levels (I1/D1/L2) of the cache from the command line using the ---I1, ---D1 and ---L2 options. +, + and + options. For cache parameters to be valid for simulation, the number of sets (with associativity being the number of cache lines in each set) has to be a power of two. @@ -186,9 +186,9 @@ each set) has to be a power of two. Cachegrind cannot automatically determine the cache configuration, so you will need to specify it with the ---I1, ---D1 and ---L2 options. +, + and + options. Other noteworthy behaviour: @@ -356,7 +356,7 @@ file: To use an output file name other than the default cachegrind.out, - use the --cachegrind-out-file + use the switch. @@ -371,7 +371,7 @@ file: on the output file name serves two purposes. Firstly, it means you don't have to rename old log files that you don't want to overwrite. Secondly, and more importantly, it allows correct profiling with the ---trace-children=yes option of + option of programs that spawn child processes. @@ -465,8 +465,8 @@ configuration, or failing that, via defaults). Enables or disables collection of branch instruction and misprediction counts. By default this is disabled as it slows Cachegrind down by approximately 25%. Note that you - cannot specify --cache-sim=no - and --branch-sim=no + cannot specify + and together, as that would leave Cachegrind with no information to collect. @@ -615,7 +615,7 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function Events shown: the events shown, which is a subset of the events gathered. This can be adjusted with the - --show option. + option. @@ -626,12 +626,12 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function Ir counts, they will then be sorted by I1mr counts, and so on. This order can be adjusted with the - --sort option. + option. Note that this dictates the order the functions appear. It is not the order in which the columns appear; that is dictated by the "events shown" line (and can - be changed with the --show + be changed with the option). @@ -644,7 +644,7 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function Ir is chosen as the threshold event since it is the primary sort event. The threshold can be adjusted with the - --threshold + option. @@ -655,7 +655,7 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function Auto-annotation: whether auto-annotation was requested - via the --auto=yes + via the option. In this case no. @@ -676,7 +676,7 @@ instructions that write to memory). The name and/or function name could not be determined from debugging information. If most of the entries have the form ???:??? the program probably -wasn't compiled with -g. If any +wasn't compiled with . If any code was invalidated (either due to self-modifying code or unloading of shared objects) its counts are aggregated into a single cost centre written as @@ -688,7 +688,7 @@ and from libraries (eg. getc.c) There are two ways to annotate source files -- by choosing them manually, or with the ---auto=yes option. To do it + option. To do it manually, just specify the filenames as additional arguments to cg_annotate. For example, the output from running cg_annotate <filename> @@ -736,7 +736,7 @@ terminal is clearly useful.) (User-annotated source) as having been chosen manually for annotation. If the file was found in one of the directories specified with the --I / --include option, the directory +/ option, the directory and file are both given. Each line is annotated with its event counts. Events not @@ -757,7 +757,7 @@ part of a file the shown code comes from, eg: (figures and code for line 878)]]> The amount of context to show around annotated lines is -controlled by the --context +controlled by the option. To get automatic annotation, run @@ -765,8 +765,8 @@ option. cg_annotate will automatically annotate every source file it can find that is mentioned in the function-by-function summary. Therefore, the files chosen for auto-annotation are affected by -the --sort and ---threshold options. Each +the and + options. Each source file is clearly marked (Auto-annotated source) as being chosen automatically. Any files that could not be found are mentioned at the end of the @@ -785,9 +785,9 @@ usually compiled with debugging information, but the source files are often not present on a system. If a file is chosen for annotation both manually and automatically, it is marked as User-annotated -source. Use the -I / ---include option to tell Valgrind where to look -for source files if the filenames found from the debugging +source. Use the +/ option to tell Valgrind where +to look for source files if the filenames found from the debugging information aren't specific enough. Beware that cg_annotate can take some time to digest large @@ -839,27 +839,25 @@ cg_annotate. - -h, --help - -v, --version + + Help and version, as usual. - --sort=A,B,C [default: + [default: order in cachegrind.out.<pid>] Specifies the events upon which the sorting of the function-by-function entries will be based. Useful if you want to concentrate on eg. I cache misses - (--sort=I1mr,I2mr), or D - cache misses - (--sort=D1mr,D2mr), or L2 - misses - (--sort=D2mr,I2mr). + (), or D cache misses + (), or L2 misses + (). - --show=A,B,C [default: + [default: all, using order in cachegrind.out.<pid>] Specifies which events to show (and the column @@ -869,7 +867,7 @@ cg_annotate. - --threshold=X + [default: 99%] Sets the threshold for the function-by-function summary. Functions are shown that account for more than X% @@ -878,24 +876,23 @@ cg_annotate. Note: thresholds can be set for more than one of the events by appending any events for the - --sort option with a colon + option with a colon and a number (no spaces, though). E.g. if you want to see the functions that cover 99% of L2 read misses and 99% of L2 write misses, use this option: - --sort=D2mr:99,D2mw:99 + - --auto=no [default] - --auto=yes + [default] + When enabled, automatically annotates every file that is mentioned in the function-by-function summary that can be found. Also gives a list of those that couldn't be found. - --context=N [default: - 8] + [default: 8] Print N lines of context before and after each annotated line. Avoids printing large sections of source files that were not executed. Use a large number @@ -903,9 +900,8 @@ cg_annotate. - -I<dir>, - --include=<dir> [default: empty - string] + + [default: empty string] Adds a directory to the list in which to search for files. Multiple -I/--include options can be given to add multiple directories. @@ -1046,7 +1042,7 @@ cg_annotate issues warnings. If you compile some files with - -g and some without, some + and some without, some events that take place in a file without debug info could be attributed to the last line of a file with debug info (whichever one gets placed before the non-debug-info file in diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 2f3d9f65d..43104bd36 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -8,7 +8,7 @@ To use this tool, you must specify ---tool=callgrind on the + on the Valgrind command line. @@ -61,7 +61,7 @@ of the profiling, two command line tools are provided: To use Callgrind, you must specify ---tool=callgrind on the Valgrind + on the Valgrind command line. @@ -498,8 +498,7 @@ callgrind.out.pid.part-threa Command line option reference -In the following, options are grouped into classes, in the same order as -the output of callgrind --help. +In the following, options are grouped into classes. Some options allow the specification of a function/symbol name, such as @@ -513,30 +512,6 @@ shell. This feature is important especially for C++, as without wildcard usage, the function would have to be specified in full extent, including parameter signature. - -Miscellaneous options - - - - - - - Show summary of options. This is a short version of this - manual section. - - - - - - - Show version of callgrind. - - - - - - Dump creation options @@ -750,9 +725,9 @@ Also see . option . If you use this flag, collection state should be switched off at the beginning. Note that the - specification of --toggle-collect + specification of implicitly sets - --collect-state=no. + . Collection state can be toggled also by inserting the client request ; at the needed code positions. diff --git a/callgrind/docs/man-annotate.xml b/callgrind/docs/man-annotate.xml index 529ec78b3..ddb9a6091 100644 --- a/callgrind/docs/man-annotate.xml +++ b/callgrind/docs/man-annotate.xml @@ -48,7 +48,7 @@ included below. - + Show summary of options. diff --git a/callgrind/docs/man-control.xml b/callgrind/docs/man-control.xml index ca3edde6e..119e17786 100644 --- a/callgrind/docs/man-control.xml +++ b/callgrind/docs/man-control.xml @@ -49,7 +49,7 @@ included below. - + Show summary of options. diff --git a/docs/xml/manual-core-adv.xml b/docs/xml/manual-core-adv.xml index fcbe03768..021019689 100644 --- a/docs/xml/manual-core-adv.xml +++ b/docs/xml/manual-core-adv.xml @@ -56,8 +56,8 @@ program with any extra supporting libraries. on x86, amd64, ppc32 and ppc64, the overhead is 6 simple integer instructions and is probably undetectable except in tight loops. However, if you really wish to compile out the client requests, you can -compile with -DNVALGRIND (analogous to --DNDEBUG's effect on +compile with (analogous to +'s effect on assert()). @@ -103,7 +103,7 @@ tool-specific macros). once. Alternatively, for transparent self-modifying-code support, - use--smc-check=all, or run + use, or run on ppc32/Linux or ppc64/Linux. @@ -504,7 +504,7 @@ will honour only the first one. Figuring out what's going on given the dynamic nature of wrapping can be difficult. The ---trace-redir=yes flag makes + flag makes this possible by showing the complete state of the redirection subsystem after every @@ -536,10 +536,10 @@ sections. The active binding set is (conceptually) recomputed from the specifications, and all known symbol names, following any change to the specification set. ---trace-redir=yes shows the contents + shows the contents of both sets following any such event. --v prints a line of text each + prints a line of text each time an active specification is used for the first time. Hence for maximum debugging effectiveness you will need to use both @@ -555,7 +555,7 @@ However, to make the implementation more robust, the two kinds of interception (wrapping vs replacement) are treated differently. ---trace-redir=yes shows + shows specifications and bindings for both replacement and wrapper functions. To differentiate the two, replacement bindings are printed using diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index 584304333..e9e2c7690 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -113,20 +113,20 @@ already, if you intended to debug your program with GNU gdb, or some other debugger. If you are planning to use Memcheck: On rare -occasions, compiler optimisations (at -O2 -and above, and sometimes -O1) have been +occasions, compiler optimisations (at +and above, and sometimes ) have been observed to generate code which fools Memcheck into wrongly reporting uninitialised value errors, or missing uninitialised value errors. We have looked in detail into fixing this, and unfortunately the result is that doing so would give a further significant slowdown in what is already a slow tool. So the best solution is to turn off optimisation altogether. Since this often makes things unmanageably slow, a reasonable compromise is to use --O. This gets you the majority of the +. This gets you the majority of the benefits of higher optimisation levels whilst keeping relatively small the chances of false positives or false negatives from Memcheck. Also, you -should compile your code with -Wall because +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 -Wall +higher optimisation levels. (Using is also a good idea in general.) All other tools (as far as we know) are unaffected by optimisation level. @@ -631,7 +631,7 @@ categories. - + , Run silently, and only print error messages. Useful if you are running regression tests or have some other automated test @@ -640,7 +640,7 @@ categories. - + , Be more verbose. Gives extra information on various aspects of your program, such as: the shared objects loaded, the @@ -1525,7 +1525,7 @@ following entry in ~/.valgrindrc: run. Without the memcheck: part, this will cause problems if you select other tools that don't understand ---leak-check=yes. +. @@ -1589,7 +1589,7 @@ able to cope with any POSIX-compliant use of signals. If you're using signals in clever ways (for example, catching SIGSEGV, modifying page state and restarting the instruction), you're probably relying on precise exceptions. In this case, you will need -to use --vex-iropt-precise-memory-exns=yes. +to use . If your program dies as a result of a fatal core-dumping signal, @@ -1961,7 +1961,7 @@ shipped. Warning Messages You Might See Most of these only appear if you run in verbose mode -(enabled by -v): +(enabled by ): diff --git a/docs/xml/quick-start-guide.xml b/docs/xml/quick-start-guide.xml index 465df3d10..8035216a4 100644 --- a/docs/xml/quick-start-guide.xml +++ b/docs/xml/quick-start-guide.xml @@ -44,13 +44,13 @@ documentation of Memcheck and the other tools, please read the User Manual. Compile your program with to include debugging information so that Memcheck's error messages include exact line -numbers. Using -O0 is also a good +numbers. Using is also a good idea, if you can tolerate the slowdown. With --O1 line numbers in error messages can + line numbers in error messages can be inaccurate, although generally speaking running Memcheck on code compiled -at -O1 works fairly well. +at works fairly well. Use of --O2 and above is not recommended as + and above is not recommended as Memcheck occasionally reports uninitialised-value errors which don't really exist. diff --git a/docs/xml/xml_help.txt b/docs/xml/xml_help.txt index ae71a6f98..7290d3eb6 100644 --- a/docs/xml/xml_help.txt +++ b/docs/xml/xml_help.txt @@ -17,8 +17,12 @@ xml to html markup transformations: --> 
          --> 
- --> 
-        --> 
+