From: Josef Weidendorfer Date: Tue, 4 Dec 2007 10:09:24 +0000 (+0000) Subject: Update old (and wrong) parts of callgrind documentation. X-Git-Tag: svn/VALGRIND_3_3_0~20 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=094c96388c03b1c46140773e4183e8fc4177add6;p=thirdparty%2Fvalgrind.git Update old (and wrong) parts of callgrind documentation. This obviously was already wrong in 3.2.x :-( * Old --fn-recursion=... / --fn-caller=... options are called --separate-recs=... / --separate-callers=... since quite some time for consistency with e.g. --separate-threads=yes. Error noted from bug 153335. * Function specifications support wildcards since quite some time; specification of a prefix only does not work, but the full function has to match. This was needed to allow to specify 'foo' without also specifying 'foo1'. * The script 'callgrind' does not exist since merging into valgrind. * Rename callgrind from being a 'heavyweight' to a 'call graph' profiler, similar to the description in the quick start overview. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7272 --- diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index d8a34b21ea..9d638ad8e8 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -4,13 +4,13 @@ [ %cl-entities; ]> -Callgrind: a heavyweight profiler +Callgrind: a call graph profiler Overview -Callgrind is profiling tool that can +Callgrind is a profiling tool that can construct a call graph for a program's run. By default, the collected data consists of the number of instructions executed, their relationship @@ -65,7 +65,7 @@ command line. Cachegrind collects flat profile data: event counts (data reads, cache misses, etc.) are attributed directly to the function they -occurred in. This simple cost attribution mechanism is sometimes +occurred in. This cost attribution mechanism is called self or exclusive attribution. @@ -115,7 +115,7 @@ on heuristics to detect calls and returns. (the -g flag), but with optimization turned on. To start a profile run for a program, execute: - callgrind [callgrind options] your-program [program options] + valgrind --tool=callgrind [callgrind options] your-program [program options] While the simulation is running, you can observe execution with @@ -277,16 +277,17 @@ callgrind.out.pid.part-threa - Dumping at enter/leave of all functions whose name - starts with funcprefix. Use the - option - and . + Dumping at enter/leave of specified functions. + Use the + option + and . To zero cost counters before entering a function, use - . - The prefix method for specifying function names was chosen to - ease the use with C++: you don't have to specify full - signatures. You can specify these options multiple - times for different function prefixes. + . + You can specify these options multiple times for different + functions. Function specifications support wildcards: eg. use + to + generate dumps before entering any function starting with + foo. @@ -344,17 +345,15 @@ callgrind.out.pid.part-threa In addition to enabling instrumentation, you must also enable event collection for the parts of your program you are interested in. By default, event collection is enabled everywhere. - You can limit collection to specific function(s) + You can limit collection to a specific function by using - . + . This will toggle the collection state on entering and leaving the specified functions. When this option is in effect, the default collection state at program start is "off". Only events happening while running - inside of functions starting with funcprefix will - be collected. Recursive - calls of functions with funcprefix do not trigger - any action. + inside of the given function will be collected. Recursive + calls of the given function do not trigger any action. It is important to note that with instrumentation switched off, the cache simulator cannot see any memory access events, and thus, any @@ -441,7 +440,7 @@ callgrind.out.pid.part-threa also skips any call information from and to an ignored function, and thus can break a cycle. Candidates for this typically are dispatcher functions in event driven code. The option to ignore calls to a function is - . Aside from + . Aside from possibly breaking cycles, this is used in Callgrind to skip trampoline functions in the PLT sections for calls to functions in shared libraries. You can see the difference @@ -451,22 +450,22 @@ callgrind.out.pid.part-threa If you have a recursive function, you can distinguish the first 10 recursion levels by specifying - . + . Or for all functions with - , but this will + , but this will give you much bigger profile data files. In the profile data, you will see the recursion levels of "func" as the different functions with names "func", "func'2", "func'3" and so on. If you have call chains "A > B > C" and "A > C > B" in your program, you usually get a "false" cycle "B <> C". Use - - , + + , and functions "B" and "C" will be treated as different functions depending on the direct caller. Using the apostrophe for appending this "context" to the function name, you get "A > B'A > C'B" and "A > C'A > B'C", and there will be no cycle. Use - to get a 2-caller + to get a 2-caller dependency for all functions. Note that doing this will increase the size of profile data files. @@ -479,9 +478,20 @@ callgrind.out.pid.part-threa Command line option reference -In the following, options are grouped into classes, in same order as -the output as callgrind --help. +In the following, options are grouped into classes, in the same order as +the output of callgrind --help. + +Some options allow the specification of a function/symbol name, such as +, or +. All these options +can be specified multiple times for different functions. +In addition, the function specifications actually are patterns by supporting +the use of wildcards '*' (zero or more arbitrary characters) and '?' +(exactly one arbitrary character), similar to file name globbing in the +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. @@ -626,28 +636,28 @@ be executed. For interactive control use - + - Dump when entering a function starting with <prefix> + Dump when entering <function> - + - Zero all costs when entering a function starting with <prefix> + Zero all costs when entering <function> - + - Dump when leaving a function starting with <prefix> + Dump when leaving <function> @@ -735,12 +745,10 @@ Also see . - + - Toggle collection on entry/exit of a function whose name - starts with - <prefix>. + Toggle collection on entry/exit of <function>. @@ -784,9 +792,9 @@ Also see . - + - + Separate function recursions by at most <level> levels. @@ -794,9 +802,9 @@ Also see . - + - + Separate contexts by at most <callers> functions in the @@ -844,9 +852,9 @@ Also see . - + - + Separate <number> recursions for <function>. @@ -854,9 +862,9 @@ Also see . - + - + Separate <number> callers for <function>.