From: Nicholas Nethercote Date: Fri, 7 Aug 2009 07:44:31 +0000 (+0000) Subject: - Documented callgrind_{annotate,control} in the Callgrind manual chapter X-Git-Tag: svn/VALGRIND_3_5_0~108 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a5bcb4c0ddc897230c91da884818fedc10e5ad10;p=thirdparty%2Fvalgrind.git - Documented callgrind_{annotate,control} in the Callgrind manual chapter and created man pages for them. Renamed the XML files in the process for consistency. - Inlined cg-entities.xml into vg-entities.xml. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10742 --- diff --git a/callgrind/Makefile.am b/callgrind/Makefile.am index 12455820ee..a580e520fe 100644 --- a/callgrind/Makefile.am +++ b/callgrind/Makefile.am @@ -1,11 +1,10 @@ include $(top_srcdir)/Makefile.tool.am EXTRA_DIST = \ - docs/cl-entities.xml \ + docs/callgrind_annotate-manpage.xml \ + docs/callgrind_control-manpage.xml \ docs/cl-manual.xml \ - docs/cl-format.xml \ - docs/man-annotate.xml \ - docs/man-control.xml + docs/cl-format.xml #---------------------------------------------------------------------------- # Headers, etc diff --git a/callgrind/callgrind_annotate.in b/callgrind/callgrind_annotate.in index 5c762e24e7..60ecde0bab 100644 --- a/callgrind/callgrind_annotate.in +++ b/callgrind/callgrind_annotate.in @@ -200,7 +200,7 @@ usage: callgrind_annotate [options] [data-file [source-files]] options for the user, with defaults in [ ], are: -h --help show this message - -v --version show version + --version show version --show=A,B,C only show figures for events A,B,C [all] --sort=A,B,C sort columns by events A,B,C [event column order] --threshold=<0--100> percentage of counts (of primary sort event) we @@ -232,7 +232,7 @@ sub process_cmd_line() if ($arg =~ /^-/) { # --version - if ($arg =~ /^-v$|^--version$/) { + if ($arg =~ /^--version$/) { die("callgrind_annotate-$version\n"); # --show=A,B,C diff --git a/callgrind/docs/callgrind_annotate-manpage.xml b/callgrind/docs/callgrind_annotate-manpage.xml new file mode 100644 index 0000000000..42323168d5 --- /dev/null +++ b/callgrind/docs/callgrind_annotate-manpage.xml @@ -0,0 +1,71 @@ + + %vg-entities; ]> + + + + + + Callgrind Annotate + 1 + Release &rel-version; + + + + callgrind_annotate + post-processing tool for the Valgrind tool Callgrind + + + + + callgrind_annotate + options + source-files + + + + + +Description + +callgrind_annotate takes an output file produced by +the Valgrind tool Callgrind and prints the information in an easy-to-read form. + + + + + + +Options + + + + + + + +See Also + + +valgrind(1), +&vg-docs-path; or +&vg-docs-url;. + + + + + + + +Author + +Josef Weidendorfer <&cl-email;>. + +This manual page was written by +Philipp Frauenfelder <pfrauenf@debian.org>. + + + + diff --git a/callgrind/docs/callgrind_control-manpage.xml b/callgrind/docs/callgrind_control-manpage.xml new file mode 100644 index 0000000000..2b5a2bd750 --- /dev/null +++ b/callgrind/docs/callgrind_control-manpage.xml @@ -0,0 +1,72 @@ + + %vg-entities; ]> + + + + + Callgrind Control + 1 + Release &rel-version; + + + + callgrind_control + observe and control programs being run by the Valgrind tool + Callgrind + + + + + callgrind_control + options + pid/program-name + + + + + +Description + + +callgrind_control controls programs being run by the +Valgrind tool Callgrind. When a pid/program name +argument is not specified, all applications currently being run by Callgrind +on this system will be used for actions given by the specified option(s). +The default action is to give some brief information about the applications +being run by Callgrind. + + + + + +Options + + + + + + +See Also + + +valgrind(1), +&vg-docs-path; or +&vg-docs-url;. + + + + + + +Author + +Josef Weidendorfer <&cl-email;>. + + + + + + + diff --git a/callgrind/docs/cl-entities.xml b/callgrind/docs/cl-entities.xml deleted file mode 100644 index f5c98b5904..0000000000 --- a/callgrind/docs/cl-entities.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - diff --git a/callgrind/docs/cl-format.xml b/callgrind/docs/cl-format.xml index fd86b33378..97b3543cb1 100644 --- a/callgrind/docs/cl-format.xml +++ b/callgrind/docs/cl-format.xml @@ -1,7 +1,7 @@ %cl-entities; ]> +[ %vg-entities; ]> Callgrind Format Specification diff --git a/callgrind/docs/cl-manual.xml b/callgrind/docs/cl-manual.xml index 21ebc27365..d4180b3878 100644 --- a/callgrind/docs/cl-manual.xml +++ b/callgrind/docs/cl-manual.xml @@ -1,7 +1,7 @@ %cl-entities; ]> +[ %vg-entities; ]> Callgrind: a call-graph generating cache profiler @@ -33,12 +33,9 @@ of the profiling, two command line tools are provided: This command reads in the profile data, and prints a sorted lists of functions, optionally with source annotation. - + For graphical visualization of the data, try - KCachegrind, which is a KDE/Qt based + KCachegrind, which is a KDE/Qt based GUI that makes it easy to navigate the large amount of data that Callgrind produces. @@ -53,9 +50,6 @@ of the profiling, two command line tools are provided: 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. - @@ -172,7 +166,7 @@ on heuristics to detect calls and returns. For better call graph browsing experience, it is highly recommended - to use KCachegrind. + to use KCachegrind. If your code has a significant fraction of its cost in cycles (sets of functions calling each other in a recursive manner), you have to @@ -262,7 +256,7 @@ callgrind.out.pid.part-threa must be actively running for detection of the dump command. So, for a GUI application, resize the window, or for a server, send a request. - If you are using KCachegrind + If you are using KCachegrind for browsing of profile information, you can use the toolbar button Force dump. This will request a dump and trigger a reload after the dump is written. @@ -489,8 +483,8 @@ callgrind.out.pid.part-threa - -Command line option reference + +Callgrind Options In the following, options are grouped into classes. @@ -515,6 +509,7 @@ parameter signature. These options influence the name and format of the profile data files. + @@ -609,6 +604,7 @@ be executed. For interactive control use callgrind_control. + @@ -652,6 +648,7 @@ be executed. For interactive control use + . + @@ -761,6 +759,7 @@ Also see . + . + @@ -883,12 +883,14 @@ Also see . --> + Cache simulation options + @@ -1004,6 +1006,7 @@ Also see . + @@ -1094,4 +1097,181 @@ their arguments. + + + +callgrind_annotate Options + + + + + + + + Show summary of options. + + + + + + + Show version of callgrind_annotate. + + + + + + + + + Only show figures for events A,B,C. + + + + + + + + + Sort columns by events A,B,C [event column order]. + + + + + + + + + Percentage of counts (of primary sort event) we are + interested in. + + + + + + + + + Annotate all source files containing functions that helped + reach the event count threshold. + + + + + + + + + Print N lines of context before and after annotated + lines. + + + + + + + + + Add subroutine costs to functions calls. + + + + + + + + + Print for each function their callers, the called functions + or both. + + + + + + + + + Add to the list of directories to search + for source files. + + + + + + + + + + + + + +callgrind_control Options + + + + + + + + Show summary of options. + + + + + + + Show version of callgrind_control. + + + + + + + Show statistics. + + + + + + + Show stack trace. + + + + + + + Only show figures for events A,B,C. + + + + + + + Zero cost counters. + + + + + + + Request the dumping of profile information. Optionally, a + string can be specified which is written into the dump as part of + the Trigger reason. This can be used to distinguish multiple dumps. + + + + + + + Kill. + + + + + + + + diff --git a/callgrind/docs/man-annotate.xml b/callgrind/docs/man-annotate.xml deleted file mode 100644 index ddb9a60913..0000000000 --- a/callgrind/docs/man-annotate.xml +++ /dev/null @@ -1,163 +0,0 @@ - - %cl-entities; ]> - - - - - - Callgrind Annotate - 1 - May 13, 2003 - - - - callgrind_annotate - produces human readable ASCII output from profile - information in callgrind.out.<pid> files - - - - - callgrind_annotate - options - source-files - - - - - -Description - -This manual page documents briefly the -callgrind_annotate command. This manual page was -written for the Debian distribution because the original program does -not have a manual page. - - - - - -Options - -This program follows the usual GNU command line syntax, with long -options starting with two dashes ('--'). A summary of options is -included below. - - - - - - - Show summary of options. - - - - - - - Show version of callgrind_annotate. - - - - - - - - - only show figures for events A,B,C - - - - - - - - - sort columns by events A,B,C [event column order] - - - - - - - - - percentage of counts (of primary sort event) we are - interested in - - - - - - - - - annotate all source files containing functions that helped - reach the event count threshold - - - - - - - - - print N lines of context before and after annotated - lines - - - - - - - - - add subroutine costs to functions calls - - - - - - - - - print for each function their callers, the called functions - or both - - - - - - - - - add <dir> to the list of directories to search for source - files - - - - - - - - - -See Also - -&cl-doc-path; - - - - - -Author - -This manual page was written by -Philipp Frauenfelder <pfrauenf@debian.org>, for the Debian -GNU/Linux system (but may be used by others). - - - - diff --git a/callgrind/docs/man-control.xml b/callgrind/docs/man-control.xml deleted file mode 100644 index 119e17786b..0000000000 --- a/callgrind/docs/man-control.xml +++ /dev/null @@ -1,132 +0,0 @@ - - %cl-entities; ]> - - - - - Callgrind Control - 1 - October, 2005 - - - - callgrind_control - observe and control applications currently running under - supervision of callgrind - - - - - callgrind_control - options - pid/program-name - - - - - -Description - -This manual page documents briefly the -callgrind_control command. When not specifying a -pid/program name argument, all applications run -by callgrind on this system will be used for actions given by the -specified option(s). The default action is to give short information -for the applications run by callgrind. - - - - - -Options - -This program follows the usual GNU command line syntax, with long -options starting with two dashes ("--"). A summary of options is -included below. - - - - - - - Show summary of options. - - - - - - - Show version of callgrind_control. - - - - - - - Show statistics - - - - - - - Show stack trace - - - - - - - Only show figures for events A,B,C - - - - - - - Zero cost counters - - - - - - - Request the dumping of profile information. Optionally, a - string can be specified which is written into the dump as part of - the Trigger reason. This can be used to distinguish multiple dumps. - - - - - - - Kill - - - - - - - - - -See Also - -&cl-doc-path; - - - - - -Author - -This manual page was written by Josef Weidendorfer <&cl-email;>. - - - - - - - diff --git a/docs/xml/manpages-index.xml b/docs/xml/manpages-index.xml index 60aacf3ca7..889bb8fa62 100644 --- a/docs/xml/manpages-index.xml +++ b/docs/xml/manpages-index.xml @@ -11,6 +11,14 @@ + + + + + + diff --git a/docs/xml/valgrind-manpage.xml b/docs/xml/valgrind-manpage.xml index d1988db421..1bd5681856 100644 --- a/docs/xml/valgrind-manpage.xml +++ b/docs/xml/valgrind-manpage.xml @@ -222,6 +222,8 @@ system: &vg-docs-path;, or online: See Also +callgrind_annotate(1), +callgrind_control(1), ms_print(1), &vg-docs-path; or &vg-docs-url;. @@ -233,9 +235,10 @@ ms_print(1), Author -This manpage written by Andres Roldan <aroldan@debian.org>, -Robert Walsh <rjwalsh@durables.org>, and the Valgrind -developers. +The Valgrind developers. + +This manpage was written by Andres Roldan <aroldan@debian.org> +and the Valgrind developers. diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml index 5da7c013a4..e713bfb4ac 100644 --- a/docs/xml/vg-entities.xml +++ b/docs/xml/vg-entities.xml @@ -1,6 +1,7 @@ + @@ -20,3 +21,6 @@ + + +