Home | History | Annotate | Download | only in docs
      1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
      2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
      3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
      4 [ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
      5 
      6 <chapter id="cl-manual" xreflabel="Callgrind Manual">
      7 <title>Callgrind: a call-graph generating cache and branch prediction profiler</title>
      8 
      9 
     10 <para>To use this tool, you must specify
     11 <option>--tool=callgrind</option> on the
     12 Valgrind command line.</para>
     13 
     14 <sect1 id="cl-manual.use" xreflabel="Overview">
     15 <title>Overview</title>
     16 
     17 <para>Callgrind is a profiling tool that records the call history among
     18 functions in a program's run as a call-graph.
     19 By default, the collected data consists of
     20 the number of instructions executed, their relationship
     21 to source lines, the caller/callee relationship between functions,
     22 and the numbers of such calls.
     23 Optionally, cache simulation and/or branch prediction (similar to Cachegrind)
     24 can produce further information about the runtime behavior of an application.
     25 </para>
     26 
     27 <para>The profile data is written out to a file at program
     28 termination. For presentation of the data, and interactive control
     29 of the profiling, two command line tools are provided:</para>
     30 <variablelist>
     31   <varlistentry>
     32   <term><command>callgrind_annotate</command></term>
     33   <listitem>
     34     <para>This command reads in the profile data, and prints a
     35     sorted lists of functions, optionally with source annotation.</para>
     36 
     37     <para>For graphical visualization of the data, try
     38     <ulink url="&cl-gui-url;">KCachegrind</ulink>, which is a KDE/Qt based
     39     GUI that makes it easy to navigate the large amount of data that
     40     Callgrind produces.</para>
     41 
     42   </listitem>
     43   </varlistentry>
     44 
     45   <varlistentry>
     46   <term><command>callgrind_control</command></term>
     47   <listitem>
     48     <para>This command enables you to interactively observe and control 
     49     the status of a program currently running under Callgrind's control,
     50     without stopping the program.  You can get statistics information as
     51     well as the current stack trace, and you can request zeroing of counters
     52     or dumping of profile data.</para>
     53   </listitem>
     54   </varlistentry>
     55 </variablelist>
     56 
     57   <sect2 id="cl-manual.functionality" xreflabel="Functionality">
     58   <title>Functionality</title>
     59 
     60 <para>Cachegrind collects flat profile data: event counts (data reads,
     61 cache misses, etc.) are attributed directly to the function they
     62 occurred in.  This cost attribution mechanism is
     63 called <emphasis>self</emphasis> or <emphasis>exclusive</emphasis>
     64 attribution.</para>
     65 
     66 <para>Callgrind extends this functionality by propagating costs
     67 across function call boundaries.  If function <function>foo</function> calls
     68 <function>bar</function>, the costs from <function>bar</function> are added into
     69 <function>foo</function>'s costs.  When applied to the program as a whole,
     70 this builds up a picture of so called <emphasis>inclusive</emphasis>
     71 costs, that is, where the cost of each function includes the costs of
     72 all functions it called, directly or indirectly.</para>
     73 
     74 <para>As an example, the inclusive cost of
     75 <function>main</function> should be almost 100 percent
     76 of the total program cost.  Because of costs arising before 
     77 <function>main</function> is run, such as
     78 initialization of the run time linker and construction of global C++
     79 objects, the inclusive cost of <function>main</function>
     80 is not exactly 100 percent of the total program cost.</para>
     81 
     82 <para>Together with the call graph, this allows you to find the
     83 specific call chains starting from
     84 <function>main</function> in which the majority of the
     85 program's costs occur.  Caller/callee cost attribution is also useful
     86 for profiling functions called from multiple call sites, and where
     87 optimization opportunities depend on changing code in the callers, in
     88 particular by reducing the call count.</para>
     89 
     90 <para>Callgrind's cache simulation is based on that of Cachegrind.
     91 Read the documentation for <xref linkend="cg-manual"/> first.  The material
     92 below describes the features supported in addition to Cachegrind's
     93 features.</para>
     94 
     95 <para>Callgrind's ability to detect function calls and returns depends
     96 on the instruction set of the platform it is run on.  It works best
     97 on x86 and amd64, and unfortunately currently does not work so well
     98 on PowerPC code.  This is because there are no explicit call or return
     99 instructions in the PowerPC instruction set, so Callgrind has to rely
    100 on heuristics to detect calls and returns.</para>
    101 
    102   </sect2>
    103 
    104   <sect2 id="cl-manual.basics" xreflabel="Basic Usage">
    105   <title>Basic Usage</title>
    106 
    107   <para>As with Cachegrind, you probably want to compile with debugging info
    108   (the <option>-g</option> option) and with optimization turned on.</para>
    109 
    110   <para>To start a profile run for a program, execute:
    111   <screen>valgrind --tool=callgrind [callgrind options] your-program [program options]</screen>
    112   </para>
    113 
    114   <para>While the simulation is running, you can observe execution with:
    115   <screen>callgrind_control -b</screen>
    116   This will print out the current backtrace. To annotate the backtrace with
    117   event counts, run
    118   <screen>callgrind_control -e -b</screen>
    119   </para>
    120 
    121   <para>After program termination, a profile data file named 
    122   <computeroutput>callgrind.out.&lt;pid&gt;</computeroutput>
    123   is generated, where <emphasis>pid</emphasis> is the process ID 
    124   of the program being profiled.
    125   The data file contains information about the calls made in the
    126   program among the functions executed, together with 
    127   <command>Instruction Read</command> (Ir) event counts.</para>
    128 
    129   <para>To generate a function-by-function summary from the profile
    130   data file, use
    131   <screen>callgrind_annotate [options] callgrind.out.&lt;pid&gt;</screen>
    132   This summary is similar to the output you get from a Cachegrind
    133   run with cg_annotate: the list
    134   of functions is ordered by exclusive cost of functions, which also
    135   are the ones that are shown.
    136   Important for the additional features of Callgrind are
    137   the following two options:</para>
    138 
    139   <itemizedlist>
    140     <listitem>
    141       <para><option>--inclusive=yes</option>: Instead of using
    142       exclusive cost of functions as sorting order, use and show
    143       inclusive cost.</para>
    144     </listitem>
    145 
    146     <listitem>
    147       <para><option>--tree=both</option>: Interleave into the
    148       top level list of functions, information on the callers and the callees
    149       of each function. In these lines, which represents executed
    150       calls, the cost gives the number of events spent in the call.
    151       Indented, above each function, there is the list of callers,
    152       and below, the list of callees. The sum of events in calls to
    153       a given function (caller lines), as well as the sum of events in
    154       calls from the function (callee lines) together with the self
    155       cost, gives the total inclusive cost of the function.</para>
    156      </listitem>
    157   </itemizedlist>
    158 
    159   <para>Use <option>--auto=yes</option> to get annotated source code
    160   for all relevant functions for which the source can be found. In
    161   addition to source annotation as produced by
    162   <computeroutput>cg_annotate</computeroutput>, you will see the
    163   annotated call sites with call counts. For all other options, 
    164   consult the (Cachegrind) documentation for
    165   <computeroutput>cg_annotate</computeroutput>.
    166   </para>
    167 
    168   <para>For better call graph browsing experience, it is highly recommended
    169   to use <ulink url="&cl-gui-url;">KCachegrind</ulink>.
    170   If your code
    171   has a significant fraction of its cost in <emphasis>cycles</emphasis> (sets
    172   of functions calling each other in a recursive manner), you have to
    173   use KCachegrind, as <computeroutput>callgrind_annotate</computeroutput>
    174   currently does not do any cycle detection, which is important to get correct
    175   results in this case.</para>
    176 
    177   <para>If you are additionally interested in measuring the 
    178   cache behavior of your program, use Callgrind with the option
    179   <option><xref linkend="clopt.cache-sim"/>=yes</option>. For
    180   branch prediction simulation, use <option><xref linkend="clopt.branch-sim"/>=yes</option>.
    181   Expect a further slow down approximately by a factor of 2.</para>
    182 
    183   <para>If the program section you want to profile is somewhere in the
    184   middle of the run, it is beneficial to 
    185   <emphasis>fast forward</emphasis> to this section without any 
    186   profiling, and then enable profiling.  This is achieved by using
    187   the command line option
    188   <option><xref linkend="opt.instr-atstart"/>=no</option> 
    189   and running, in a shell:
    190   <computeroutput>callgrind_control -i on</computeroutput> just before the 
    191   interesting code section is executed. To exactly specify
    192   the code position where profiling should start, use the client request
    193   <computeroutput><xref linkend="cr.start-instr"/></computeroutput>.</para>
    194 
    195   <para>If you want to be able to see assembly code level annotation, specify
    196   <option><xref linkend="opt.dump-instr"/>=yes</option>. This will produce
    197   profile data at instruction granularity. Note that the resulting profile
    198   data
    199   can only be viewed with KCachegrind. For assembly annotation, it also is
    200   interesting to see more details of the control flow inside of functions,
    201   i.e. (conditional) jumps. This will be collected by further specifying
    202   <option><xref linkend="opt.collect-jumps"/>=yes</option>.</para>
    203 
    204   </sect2>
    205 
    206 </sect1>
    207 
    208 <sect1 id="cl-manual.usage" xreflabel="Advanced Usage">
    209 <title>Advanced Usage</title>
    210 
    211   <sect2 id="cl-manual.dumps" 
    212          xreflabel="Multiple dumps from one program run">
    213   <title>Multiple profiling dumps from one program run</title>
    214 
    215   <para>Sometimes you are not interested in characteristics of a full 
    216   program run, but only of a small part of it, for example execution of one
    217   algorithm.  If there are multiple algorithms, or one algorithm 
    218   running with different input data, it may even be useful to get different
    219   profile information for different parts of a single program run.</para>
    220 
    221   <para>Profile data files have names of the form
    222 <screen>
    223 callgrind.out.<emphasis>pid</emphasis>.<emphasis>part</emphasis>-<emphasis>threadID</emphasis>
    224 </screen>
    225   </para>
    226   <para>where <emphasis>pid</emphasis> is the PID of the running 
    227   program, <emphasis>part</emphasis> is a number incremented on each
    228   dump (".part" is skipped for the dump at program termination), and 
    229   <emphasis>threadID</emphasis> is a thread identification 
    230   ("-threadID" is only used if you request dumps of individual 
    231   threads with <option><xref linkend="opt.separate-threads"/>=yes</option>).</para>
    232 
    233   <para>There are different ways to generate multiple profile dumps 
    234   while a program is running under Callgrind's supervision.  Nevertheless,
    235   all methods trigger the same action, which is "dump all profile 
    236   information since the last dump or program start, and zero cost 
    237   counters afterwards".  To allow for zeroing cost counters without
    238   dumping, there is a second action "zero all cost counters now". 
    239   The different methods are:</para>
    240   <itemizedlist>
    241 
    242     <listitem>
    243       <para><command>Dump on program termination.</command>
    244       This method is the standard way and doesn't need any special
    245       action on your part.</para>
    246     </listitem>
    247 
    248     <listitem>
    249       <para><command>Spontaneous, interactive dumping.</command> Use
    250       <screen>callgrind_control -d [hint [PID/Name]]</screen> to 
    251       request the dumping of profile information of the supervised
    252       application with PID or Name.  <emphasis>hint</emphasis> is an
    253       arbitrary string you can optionally specify to later be able to
    254       distinguish profile dumps.  The control program will not terminate
    255       before the dump is completely written.  Note that the application
    256       must be actively running for detection of the dump command. So,
    257       for a GUI application, resize the window, or for a server, send a
    258       request.</para>
    259       <para>If you are using <ulink url="&cl-gui-url;">KCachegrind</ulink>
    260       for browsing of profile information, you can use the toolbar
    261       button <command>Force dump</command>. This will request a dump
    262       and trigger a reload after the dump is written.</para>
    263     </listitem>
    264 
    265     <listitem>
    266       <para><command>Periodic dumping after execution of a specified
    267       number of basic blocks</command>. For this, use the command line
    268       option <option><xref linkend="opt.dump-every-bb"/>=count</option>.
    269       </para>
    270     </listitem>
    271 
    272     <listitem>
    273       <para><command>Dumping at enter/leave of specified functions.</command>
    274       Use the
    275       option <option><xref linkend="opt.dump-before"/>=function</option>
    276       and <option><xref linkend="opt.dump-after"/>=function</option>.
    277       To zero cost counters before entering a function, use
    278       <option><xref linkend="opt.zero-before"/>=function</option>.</para>
    279       <para>You can specify these options multiple times for different
    280       functions. Function specifications support wildcards: e.g. use
    281       <option><xref linkend="opt.dump-before"/>='foo*'</option> to
    282       generate dumps before entering any function starting with 
    283       <emphasis>foo</emphasis>.</para>
    284     </listitem>
    285 
    286     <listitem>
    287       <para><command>Program controlled dumping.</command>
    288       Insert
    289       <computeroutput><xref linkend="cr.dump-stats"/>;</computeroutput>
    290       at the position in your code where you want a profile dump to happen. Use 
    291       <computeroutput><xref linkend="cr.zero-stats"/>;</computeroutput> to only 
    292       zero profile counters.
    293       See <xref linkend="cl-manual.clientrequests"/> for more information on
    294       Callgrind specific client requests.</para>
    295     </listitem>
    296   </itemizedlist>
    297 
    298   <para>If you are running a multi-threaded application and specify the
    299   command line option <option><xref linkend="opt.separate-threads"/>=yes</option>, 
    300   every thread will be profiled on its own and will create its own
    301   profile dump. Thus, the last two methods will only generate one dump
    302   of the currently running thread. With the other methods, you will get
    303   multiple dumps (one for each thread) on a dump request.</para>
    304 
    305   </sect2>
    306 
    307 
    308 
    309   <sect2 id="cl-manual.limits" 
    310          xreflabel="Limiting range of event collection">
    311   <title>Limiting the range of collected events</title>
    312 
    313   <para>For aggregating events (function enter/leave,
    314   instruction execution, memory access) into event numbers,
    315   first, the events must be recognizable by Callgrind, and second,
    316   the collection state must be enabled.</para>
    317 
    318   <para>Event collection is only possible if <emphasis>instrumentation</emphasis>
    319   for program code is enabled. This is the default, but for faster
    320   execution (identical to <computeroutput>valgrind --tool=none</computeroutput>),
    321   it can be disabled until the program reaches a state in which
    322   you want to start collecting profiling data.  
    323   Callgrind can start without instrumentation
    324   by specifying option <option><xref linkend="opt.instr-atstart"/>=no</option>.
    325   Instrumentation can be enabled interactively
    326   with: <screen>callgrind_control -i on</screen>
    327   and off by specifying "off" instead of "on".
    328   Furthermore, instrumentation state can be programatically changed with
    329   the macros <computeroutput><xref linkend="cr.start-instr"/>;</computeroutput>
    330   and <computeroutput><xref linkend="cr.stop-instr"/>;</computeroutput>.
    331   </para>
    332   
    333   <para>In addition to enabling instrumentation, you must also enable
    334   event collection for the parts of your program you are interested in.
    335   By default, event collection is enabled everywhere.
    336   You can limit collection to a specific function
    337   by using 
    338   <option><xref linkend="opt.toggle-collect"/>=function</option>. 
    339   This will toggle the collection state on entering and leaving
    340   the specified functions.
    341   When this option is in effect, the default collection state
    342   at program start is "off".  Only events happening while running
    343   inside of the given function will be collected. Recursive
    344   calls of the given function do not trigger any action.</para>
    345 
    346   <para>It is important to note that with instrumentation disabled, the
    347   cache simulator cannot see any memory access events, and thus, any
    348   simulated cache state will be frozen and wrong without instrumentation.
    349   Therefore, to get useful cache events (hits/misses) after switching on
    350   instrumentation, the cache first must warm up,
    351   probably leading to many <emphasis>cold misses</emphasis>
    352   which would not have happened in reality. If you do not want to see these,
    353   start event collection a few million instructions after you have enabled
    354   instrumentation.</para>
    355 
    356   </sect2>
    357 
    358   <sect2 id="cl-manual.busevents" xreflabel="Counting global bus events">
    359   <title>Counting global bus events</title>
    360 
    361   <para>For access to shared data among threads in a multithreaded
    362   code, synchronization is required to avoid raced conditions.
    363   Synchronization primitives are usually implemented via atomic instructions.
    364   However, excessive use of such instructions can lead to performance
    365   issues.</para>
    366 
    367   <para>To enable analysis of this problem, Callgrind optionally can count
    368   the number of atomic instructions executed. More precisely, for x86/x86_64,
    369   these are instructions using a lock prefix. For architectures supporting
    370   LL/SC, these are the number of SC instructions executed. For both, the term
    371   "global bus events" is used.</para>
    372 
    373   <para>The short name of the event type used for global bus events is "Ge".
    374   To count global bus events, use <option><xref linkend="clopt.collect-bus"/>=yes</option>.
    375   </para>
    376   </sect2>
    377 
    378   <sect2 id="cl-manual.cycles" xreflabel="Avoiding cycles">
    379   <title>Avoiding cycles</title>
    380 
    381   <para>Informally speaking, a cycle is a group of functions which
    382   call each other in a recursive way.</para>
    383 
    384   <para>Formally speaking, a cycle is a nonempty set S of functions,
    385   such that for every pair of functions F and G in S, it is possible
    386   to call from F to G (possibly via intermediate functions) and also
    387   from G to F.  Furthermore, S must be maximal -- that is, be the
    388   largest set of functions satisfying this property.  For example, if
    389   a third function H is called from inside S and calls back into S,
    390   then H is also part of the cycle and should be included in S.</para>
    391 
    392   <para>Recursion is quite usual in programs, and therefore, cycles
    393   sometimes appear in the call graph output of Callgrind. However,
    394   the title of this chapter should raise two questions: What is bad
    395   about cycles which makes you want to avoid them? And: How can
    396   cycles be avoided without changing program code?</para>
    397 
    398   <para>Cycles are not bad in itself, but tend to make performance
    399   analysis of your code harder. This is because inclusive costs
    400   for calls inside of a cycle are meaningless. The definition of
    401   inclusive cost, i.e. self cost of a function plus inclusive cost
    402   of its callees, needs a topological order among functions. For
    403   cycles, this does not hold true: callees of a function in a cycle include
    404   the function itself. Therefore, KCachegrind does cycle detection
    405   and skips visualization of any inclusive cost for calls inside
    406   of cycles. Further, all functions in a cycle are collapsed into artifical
    407   functions called like <computeroutput>Cycle 1</computeroutput>.</para>
    408 
    409   <para>Now, when a program exposes really big cycles (as is
    410   true for some GUI code, or in general code using event or callback based
    411   programming style), you lose the nice property to let you pinpoint
    412   the bottlenecks by following call chains from
    413   <function>main</function>, guided via
    414   inclusive cost. In addition, KCachegrind loses its ability to show
    415   interesting parts of the call graph, as it uses inclusive costs to
    416   cut off uninteresting areas.</para>
    417 
    418   <para>Despite the meaningless of inclusive costs in cycles, the big
    419   drawback for visualization motivates the possibility to temporarily
    420   switch off cycle detection in KCachegrind, which can lead to
    421   misguiding visualization. However, often cycles appear because of
    422   unlucky superposition of independent call chains in a way that
    423   the profile result will see a cycle. Neglecting uninteresting
    424   calls with very small measured inclusive cost would break these
    425   cycles. In such cases, incorrect handling of cycles by not detecting
    426   them still gives meaningful profiling visualization.</para>
    427 
    428   <para>It has to be noted that currently, <command>callgrind_annotate</command>
    429   does not do any cycle detection at all. For program executions with function
    430   recursion, it e.g. can print nonsense inclusive costs way above 100%.</para>
    431 
    432   <para>After describing why cycles are bad for profiling, it is worth
    433   talking about cycle avoidance. The key insight here is that symbols in
    434   the profile data do not have to exactly match the symbols found in the
    435   program. Instead, the symbol name could encode additional information
    436   from the current execution context such as recursion level of the
    437   current function, or even some part of the call chain leading to the
    438   function. While encoding of additional information into symbols is
    439   quite capable of avoiding cycles, it has to be used carefully to not cause
    440   symbol explosion. The latter imposes large memory requirement for Callgrind
    441   with possible out-of-memory conditions, and big profile data files.</para>
    442 
    443   <para>A further possibility to avoid cycles in Callgrind's profile data
    444   output is to simply leave out given functions in the call graph. Of course, this
    445   also skips any call information from and to an ignored function, and thus can
    446   break a cycle. Candidates for this typically are dispatcher functions in event
    447   driven code. The option to ignore calls to a function is
    448   <option><xref linkend="opt.fn-skip"/>=function</option>. Aside from
    449   possibly breaking cycles, this is used in Callgrind to skip
    450   trampoline functions in the PLT sections
    451   for calls to functions in shared libraries. You can see the difference
    452   if you profile with <option><xref linkend="opt.skip-plt"/>=no</option>.
    453   If a call is ignored, its cost events will be propagated to the
    454   enclosing function.</para>
    455 
    456   <para>If you have a recursive function, you can distinguish the first
    457   10 recursion levels by specifying
    458   <option><xref linkend="opt.separate-recs-num"/>=function</option>.  
    459   Or for all functions with 
    460   <option><xref linkend="opt.separate-recs"/>=10</option>, but this will 
    461   give you much bigger profile data files.  In the profile data, you will see
    462   the recursion levels of "func" as the different functions with names
    463   "func", "func'2", "func'3" and so on.</para>
    464 
    465   <para>If you have call chains "A &gt; B &gt; C" and "A &gt; C &gt; B"
    466   in your program, you usually get a "false" cycle "B &lt;&gt; C". Use 
    467   <option><xref linkend="opt.separate-callers-num"/>=B</option> 
    468   <option><xref linkend="opt.separate-callers-num"/>=C</option>,
    469   and functions "B" and "C" will be treated as different functions 
    470   depending on the direct caller. Using the apostrophe for appending 
    471   this "context" to the function name, you get "A &gt; B'A &gt; C'B" 
    472   and "A &gt; C'A &gt; B'C", and there will be no cycle. Use 
    473   <option><xref linkend="opt.separate-callers"/>=2</option> to get a 2-caller 
    474   dependency for all functions.  Note that doing this will increase
    475   the size of profile data files.</para>
    476 
    477   </sect2>
    478 
    479   <sect2 id="cl-manual.forkingprograms" xreflabel="Forking Programs">
    480   <title>Forking Programs</title>
    481 
    482   <para>If your program forks, the child will inherit all the profiling
    483   data that has been gathered for the parent. To start with empty profile
    484   counter values in the child, the client request
    485   <computeroutput><xref linkend="cr.zero-stats"/>;</computeroutput>
    486   can be inserted into code to be executed by the child, directly after
    487   <computeroutput>fork</computeroutput>.</para>
    488 
    489   <para>However, you will have to make sure that the output file format string
    490   (controlled by <option>--callgrind-out-file</option>) does contain
    491   <option>%p</option> (which is true by default). Otherwise, the
    492   outputs from the parent and child will overwrite each other or will be
    493   intermingled, which almost certainly is not what you want.</para>
    494 
    495   <para>You will be able to control the new child independently from
    496   the parent via callgrind_control.</para>
    497 
    498   </sect2>
    499 
    500 </sect1>
    501 
    502 
    503 <sect1 id="cl-manual.options" xreflabel="Callgrind Command-line Options">
    504 <title>Callgrind Command-line Options</title>
    505 
    506 <para>
    507 In the following, options are grouped into classes.
    508 </para>
    509 <para>
    510 Some options allow the specification of a function/symbol name, such as
    511 <option><xref linkend="opt.dump-before"/>=function</option>, or
    512 <option><xref linkend="opt.fn-skip"/>=function</option>. All these options
    513 can be specified multiple times for different functions.
    514 In addition, the function specifications actually are patterns by supporting
    515 the use of wildcards '*' (zero or more arbitrary characters) and '?'
    516 (exactly one arbitrary character), similar to file name globbing in the
    517 shell. This feature is important especially for C++, as without wildcard
    518 usage, the function would have to be specified in full extent, including
    519 parameter signature. </para>
    520 
    521 <sect2 id="cl-manual.options.creation" 
    522        xreflabel="Dump creation options">
    523 <title>Dump creation options</title>
    524 
    525 <para>
    526 These options influence the name and format of the profile data files.
    527 </para>
    528 
    529 <!-- start of xi:include in the manpage -->
    530 <variablelist id="cl.opts.list.creation">
    531 
    532   <varlistentry id="opt.callgrind-out-file" xreflabel="--callgrind-out-file">
    533     <term>
    534       <option><![CDATA[--callgrind-out-file=<file> ]]></option>
    535     </term>
    536     <listitem>
    537       <para>Write the profile data to
    538             <computeroutput>file</computeroutput> rather than to the default
    539             output file,
    540             <computeroutput>callgrind.out.&lt;pid&gt;</computeroutput>.  The
    541             <option>%p</option> and <option>%q</option> format specifiers
    542             can be used to embed the process ID and/or the contents of an
    543             environment variable in the name, as is the case for the core
    544             option <option><xref linkend="opt.log-file"/></option>.
    545             When multiple dumps are made, the file name
    546             is modified further; see below.</para> 
    547     </listitem>
    548   </varlistentry>
    549 
    550   <varlistentry id="opt.dump-line" xreflabel="--dump-line">
    551     <term>
    552       <option><![CDATA[--dump-line=<no|yes> [default: yes] ]]></option>
    553     </term>
    554     <listitem>
    555       <para>This specifies that event counting should be performed at
    556       source line granularity. This allows source annotation for sources
    557       which are compiled with debug information
    558       (<option>-g</option>).</para>
    559   </listitem>
    560   </varlistentry>
    561 
    562   <varlistentry id="opt.dump-instr" xreflabel="--dump-instr">
    563     <term>
    564       <option><![CDATA[--dump-instr=<no|yes> [default: no] ]]></option>
    565     </term>
    566     <listitem>
    567       <para>This specifies that event counting should be performed at
    568       per-instruction granularity.
    569       This allows for assembly code
    570       annotation.  Currently the results can only be 
    571       displayed by KCachegrind.</para>
    572   </listitem>
    573   </varlistentry>
    574 
    575   <varlistentry id="opt.compress-strings" xreflabel="--compress-strings">
    576     <term>
    577       <option><![CDATA[--compress-strings=<no|yes> [default: yes] ]]></option>
    578     </term>
    579     <listitem>
    580       <para>This option influences the output format of the profile data.
    581       It specifies whether strings (file and function names) should be
    582       identified by numbers. This shrinks the file, 
    583       but makes it more difficult
    584       for humans to read (which is not recommended in any case).</para>
    585     </listitem>
    586   </varlistentry>
    587 
    588   <varlistentry id="opt.compress-pos" xreflabel="--compress-pos">
    589     <term>
    590       <option><![CDATA[--compress-pos=<no|yes> [default: yes] ]]></option>
    591     </term>
    592     <listitem>
    593       <para>This option influences the output format of the profile data.
    594       It specifies whether numerical positions are always specified as absolute
    595       values or are allowed to be relative to previous numbers.
    596       This shrinks the file size.</para>
    597     </listitem>
    598   </varlistentry>
    599 
    600   <varlistentry id="opt.combine-dumps" xreflabel="--combine-dumps">
    601     <term>
    602       <option><![CDATA[--combine-dumps=<no|yes> [default: no] ]]></option>
    603     </term>
    604     <listitem>
    605       <para>When enabled, when multiple profile data parts are to be
    606       generated these parts are appended to the same output file.
    607       Not recommended.</para>
    608   </listitem>
    609   </varlistentry>
    610 
    611 </variablelist>
    612 </sect2>
    613 
    614 <sect2 id="cl-manual.options.activity" 
    615        xreflabel="Activity options">
    616 <title>Activity options</title>
    617 
    618 <para>
    619 These options specify when actions relating to event counts are to
    620 be executed. For interactive control use callgrind_control.
    621 </para>
    622 
    623 <!-- start of xi:include in the manpage -->
    624 <variablelist id="cl.opts.list.activity">
    625 
    626   <varlistentry id="opt.dump-every-bb" xreflabel="--dump-every-bb">
    627     <term>
    628       <option><![CDATA[--dump-every-bb=<count> [default: 0, never] ]]></option>
    629     </term>
    630     <listitem>
    631       <para>Dump profile data every <option>count</option> basic blocks.
    632       Whether a dump is needed is only checked when Valgrind's internal
    633       scheduler is run. Therefore, the minimum setting useful is about 100000.
    634       The count is a 64-bit value to make long dump periods possible.
    635       </para>
    636     </listitem>
    637   </varlistentry>
    638 
    639   <varlistentry id="opt.dump-before" xreflabel="--dump-before">
    640     <term>
    641       <option><![CDATA[--dump-before=<function> ]]></option>
    642     </term>
    643     <listitem>
    644       <para>Dump when entering <option>function</option>.</para>
    645     </listitem>
    646   </varlistentry>
    647 
    648   <varlistentry id="opt.zero-before" xreflabel="--zero-before">
    649     <term>
    650       <option><![CDATA[--zero-before=<function> ]]></option>
    651     </term>
    652     <listitem>
    653       <para>Zero all costs when entering <option>function</option>.</para>
    654     </listitem>
    655   </varlistentry>
    656 
    657   <varlistentry id="opt.dump-after" xreflabel="--dump-after">
    658     <term>
    659       <option><![CDATA[--dump-after=<function> ]]></option>
    660     </term>
    661     <listitem>
    662       <para>Dump when leaving <option>function</option>.</para>
    663     </listitem>
    664   </varlistentry>
    665 
    666 </variablelist>
    667 <!-- end of xi:include in the manpage -->
    668 </sect2>
    669 
    670 <sect2 id="cl-manual.options.collection"
    671        xreflabel="Data collection options">
    672 <title>Data collection options</title>
    673 
    674 <para>
    675 These options specify when events are to be aggregated into event counts.
    676 Also see <xref linkend="cl-manual.limits"/>.</para>
    677 
    678 <!-- start of xi:include in the manpage -->
    679 <variablelist id="cl.opts.list.collection">
    680 
    681   <varlistentry id="opt.instr-atstart" xreflabel="--instr-atstart">
    682     <term>
    683       <option><![CDATA[--instr-atstart=<yes|no> [default: yes] ]]></option>
    684     </term>
    685     <listitem>
    686       <para>Specify if you want Callgrind to start simulation and
    687       profiling from the beginning of the program.  
    688       When set to <computeroutput>no</computeroutput>, 
    689       Callgrind will not be able
    690       to collect any information, including calls, but it will have at
    691       most a slowdown of around 4, which is the minimum Valgrind
    692       overhead.  Instrumentation can be interactively enabled via
    693       <computeroutput>callgrind_control -i on</computeroutput>.</para>
    694       <para>Note that the resulting call graph will most probably not
    695       contain <function>main</function>, but will contain all the
    696       functions executed after instrumentation was enabled.
    697       Instrumentation can also programatically enabled/disabled. See the
    698       Callgrind include file
    699       <computeroutput>callgrind.h</computeroutput> for the macro
    700       you have to use in your source code.</para> <para>For cache
    701       simulation, results will be less accurate when switching on
    702       instrumentation later in the program run, as the simulator starts
    703       with an empty cache at that moment.  Switch on event collection
    704       later to cope with this error.</para>
    705     </listitem>
    706   </varlistentry>
    707   
    708   <varlistentry id="opt.collect-atstart" xreflabel="--collect-atstart">
    709     <term>
    710       <option><![CDATA[--collect-atstart=<yes|no> [default: yes] ]]></option>
    711     </term>
    712     <listitem>
    713       <para>Specify whether event collection is enabled at beginning
    714       of the profile run.</para>
    715       <para>To only look at parts of your program, you have two
    716       possibilities:</para>
    717       <orderedlist>
    718       <listitem>
    719         <para>Zero event counters before entering the program part you
    720         want to profile, and dump the event counters to a file after
    721         leaving that program part.</para>
    722         </listitem>
    723         <listitem>
    724           <para>Switch on/off collection state as needed to only see
    725           event counters happening while inside of the program part you
    726           want to profile.</para>
    727         </listitem>
    728       </orderedlist>
    729       <para>The second option can be used if the program part you want to
    730       profile is called many times. Option 1, i.e. creating a lot of
    731       dumps is not practical here.</para> 
    732       <para>Collection state can be
    733       toggled at entry and exit of a given function with the
    734       option <option><xref linkend="opt.toggle-collect"/></option>.  If you
    735       use this option, collection
    736       state should be disabled at the beginning.  Note that the
    737       specification of <option>--toggle-collect</option>
    738       implicitly sets
    739       <option>--collect-state=no</option>.</para>
    740       <para>Collection state can be toggled also by inserting the client request
    741       <computeroutput>
    742       <!-- commented out because it causes broken links in the man page
    743       <xref linkend="cr.toggle-collect"/>;
    744       -->
    745       CALLGRIND_TOGGLE_COLLECT
    746       ;</computeroutput>
    747       at the needed code positions.</para>
    748     </listitem>
    749   </varlistentry>
    750 
    751   <varlistentry id="opt.toggle-collect" xreflabel="--toggle-collect">
    752     <term>
    753       <option><![CDATA[--toggle-collect=<function> ]]></option>
    754     </term>
    755     <listitem>
    756       <para>Toggle collection on entry/exit of <option>function</option>.</para>
    757     </listitem>
    758   </varlistentry>
    759 
    760   <varlistentry id="opt.collect-jumps" xreflabel="--collect-jumps">
    761     <term>
    762       <option><![CDATA[--collect-jumps=<no|yes> [default: no] ]]></option>
    763     </term>
    764     <listitem>
    765       <para>This specifies whether information for (conditional) jumps
    766       should be collected.  As above, callgrind_annotate currently is not
    767       able to show you the data.  You have to use KCachegrind to get jump
    768       arrows in the annotated code.</para>
    769     </listitem>
    770   </varlistentry>
    771 
    772   <varlistentry id="opt.collect-systime" xreflabel="--collect-systime">
    773     <term>
    774       <option><![CDATA[--collect-systime=<no|yes> [default: no] ]]></option>
    775     </term>
    776     <listitem>
    777       <para>This specifies whether information for system call times
    778       should be collected.</para>
    779     </listitem>
    780   </varlistentry>
    781 
    782   <varlistentry id="clopt.collect-bus" xreflabel="--collect-bus">
    783     <term>
    784       <option><![CDATA[--collect-bus=<no|yes> [default: no] ]]></option>
    785     </term>
    786     <listitem>
    787       <para>This specifies whether the number of global bus events executed
    788       should be collected. The event type "Ge" is used for these events.</para>
    789     </listitem>
    790   </varlistentry>
    791 
    792 </variablelist>
    793 <!-- end of xi:include in the manpage -->
    794 </sect2>
    795 
    796 <sect2 id="cl-manual.options.separation"
    797        xreflabel="Cost entity separation options">
    798 <title>Cost entity separation options</title>
    799 
    800 <para>
    801 These options specify how event counts should be attributed to execution
    802 contexts.
    803 For example, they specify whether the recursion level or the
    804 call chain leading to a function should be taken into account, 
    805 and whether the thread ID should be considered.
    806 Also see <xref linkend="cl-manual.cycles"/>.</para>
    807 
    808 <!-- start of xi:include in the manpage -->
    809 <variablelist id="cmd-options.separation">
    810 
    811   <varlistentry id="opt.separate-threads" xreflabel="--separate-threads">
    812     <term>
    813       <option><![CDATA[--separate-threads=<no|yes> [default: no] ]]></option>
    814     </term>
    815     <listitem>
    816       <para>This option specifies whether profile data should be generated
    817       separately for every thread. If yes, the file names get "-threadID"
    818       appended.</para>
    819     </listitem>
    820   </varlistentry>
    821 
    822   <varlistentry id="opt.separate-callers" xreflabel="--separate-callers">
    823     <term>
    824       <option><![CDATA[--separate-callers=<callers> [default: 0] ]]></option>
    825     </term>
    826     <listitem>
    827       <para>Separate contexts by at most &lt;callers&gt; functions in the
    828       call chain. See <xref linkend="cl-manual.cycles"/>.</para>
    829     </listitem>
    830   </varlistentry>
    831 
    832   <varlistentry id="opt.separate-callers-num" xreflabel="--separate-callers2">
    833     <term>
    834       <option><![CDATA[--separate-callers<number>=<function> ]]></option>
    835     </term>
    836     <listitem>
    837       <para>Separate <option>number</option> callers for <option>function</option>.
    838       See <xref linkend="cl-manual.cycles"/>.</para>
    839     </listitem>
    840   </varlistentry>
    841 
    842   <varlistentry id="opt.separate-recs" xreflabel="--separate-recs">
    843     <term>
    844       <option><![CDATA[--separate-recs=<level> [default: 2] ]]></option>
    845     </term>
    846     <listitem>
    847       <para>Separate function recursions by at most <option>level</option> levels.
    848       See <xref linkend="cl-manual.cycles"/>.</para>
    849     </listitem>
    850   </varlistentry>
    851 
    852   <varlistentry id="opt.separate-recs-num" xreflabel="--separate-recs10">
    853     <term>
    854       <option><![CDATA[--separate-recs<number>=<function> ]]></option>
    855     </term>
    856     <listitem>
    857       <para>Separate <option>number</option> recursions for <option>function</option>.
    858       See <xref linkend="cl-manual.cycles"/>.</para>
    859     </listitem>
    860   </varlistentry>
    861 
    862   <varlistentry id="opt.skip-plt" xreflabel="--skip-plt">
    863     <term>
    864       <option><![CDATA[--skip-plt=<no|yes> [default: yes] ]]></option>
    865     </term>
    866     <listitem>
    867       <para>Ignore calls to/from PLT sections.</para>
    868     </listitem>
    869   </varlistentry>
    870   
    871   <varlistentry id="opt.skip-direct-rec" xreflabel="--skip-direct-rec">
    872     <term>
    873       <option><![CDATA[--skip-direct-rec=<no|yes> [default: yes] ]]></option>
    874     </term>
    875     <listitem>
    876       <para>Ignore direct recursions.</para>
    877     </listitem>
    878   </varlistentry>
    879   
    880   <varlistentry id="opt.fn-skip" xreflabel="--fn-skip">
    881     <term>
    882       <option><![CDATA[--fn-skip=<function> ]]></option>
    883     </term>
    884     <listitem>
    885       <para>Ignore calls to/from a given function.  E.g. if you have a
    886       call chain A &gt; B &gt; C, and you specify function B to be
    887       ignored, you will only see A &gt; C.</para>
    888       <para>This is very convenient to skip functions handling callback
    889       behaviour.  For example, with the signal/slot mechanism in the
    890       Qt graphics library, you only want
    891       to see the function emitting a signal to call the slots connected
    892       to that signal. First, determine the real call chain to see the
    893       functions needed to be skipped, then use this option.</para>
    894     </listitem>
    895   </varlistentry>
    896   
    897 <!-- 
    898     commenting out as it is only enabled with CLG_EXPERIMENTAL.  (Nb: I had to
    899     insert a space between the double dash to avoid XML comment problems.)
    900 
    901   <varlistentry id="opt.fn-group">
    902     <term>
    903       <option><![CDATA[- -fn-group<number>=<function> ]]></option>
    904     </term>
    905     <listitem>
    906       <para>Put a function into a separate group. This influences the
    907       context name for cycle avoidance. All functions inside such a
    908       group are treated as being the same for context name building, which
    909       resembles the call chain leading to a context. By specifying function
    910       groups with this option, you can shorten the context name, as functions
    911       in the same group will not appear in sequence in the name. </para>
    912     </listitem>
    913   </varlistentry>
    914 --> 
    915 
    916 </variablelist>
    917 <!-- end of xi:include in the manpage -->
    918 </sect2>
    919 
    920 
    921 <sect2 id="cl-manual.options.simulation"
    922        xreflabel="Simulation options">
    923 <title>Simulation options</title>
    924 
    925 <!-- start of xi:include in the manpage -->
    926 <variablelist id="cl.opts.list.simulation">
    927 
    928   <varlistentry id="clopt.cache-sim" xreflabel="--cache-sim">
    929     <term>
    930       <option><![CDATA[--cache-sim=<yes|no> [default: no] ]]></option>
    931     </term>
    932     <listitem>
    933       <para>Specify if you want to do full cache simulation.  By default,
    934       only instruction read accesses will be counted ("Ir").
    935       With cache simulation, further event counters are enabled:
    936       Cache misses on instruction reads ("I1mr"/"ILmr"),
    937       data read accesses ("Dr") and related cache misses ("D1mr"/"DLmr"),
    938       data write accesses ("Dw") and related cache misses ("D1mw"/"DLmw").
    939       For more information, see <xref linkend="cg-manual"/>.
    940       </para>
    941     </listitem>
    942   </varlistentry>
    943 
    944   <varlistentry id="clopt.branch-sim" xreflabel="--branch-sim">
    945     <term>
    946       <option><![CDATA[--branch-sim=<yes|no> [default: no] ]]></option>
    947     </term>
    948     <listitem>
    949       <para>Specify if you want to do branch prediction simulation.
    950       Further event counters are enabled: Number of executed conditional
    951       branches and related predictor misses ("Bc"/"Bcm"), executed indirect
    952       jumps and related misses of the jump address predictor ("Bi"/"Bim").
    953       </para>
    954     </listitem>
    955   </varlistentry>
    956 
    957 </variablelist>
    958 <!-- end of xi:include in the manpage -->
    959 </sect2>
    960 
    961 
    962 <sect2 id="cl-manual.options.cachesimulation"
    963        xreflabel="Cache simulation options">
    964 <title>Cache simulation options</title>
    965 
    966 <!-- start of xi:include in the manpage -->
    967 <variablelist id="cl.opts.list.cachesimulation">
    968 
    969   <varlistentry id="opt.simulate-wb" xreflabel="--simulate-wb">
    970     <term>
    971       <option><![CDATA[--simulate-wb=<yes|no> [default: no] ]]></option>
    972     </term>
    973     <listitem>
    974       <para>Specify whether write-back behavior should be simulated, allowing
    975       to distinguish LL caches misses with and without write backs.
    976       The cache model of Cachegrind/Callgrind does not specify write-through
    977       vs. write-back behavior, and this also is not relevant for the number
    978       of generated miss counts. However, with explicit write-back simulation
    979       it can be decided whether a miss triggers not only the loading of a new
    980       cache line, but also if a write back of a dirty cache line had to take
    981       place before. The new dirty miss events are ILdmr, DLdmr, and DLdmw,
    982       for misses because of instruction read, data read, and data write,
    983       respectively. As they produce two memory transactions, they should
    984       account for a doubled time estimation in relation to a normal miss.
    985       </para>
    986     </listitem>
    987   </varlistentry>
    988 
    989   <varlistentry id="opt.simulate-hwpref" xreflabel="--simulate-hwpref">
    990     <term>
    991       <option><![CDATA[--simulate-hwpref=<yes|no> [default: no] ]]></option>
    992     </term>
    993     <listitem>
    994       <para>Specify whether simulation of a hardware prefetcher should be
    995       added which is able to detect stream access in the second level cache
    996       by comparing accesses to separate to each page.
    997       As the simulation can not decide about any timing issues of prefetching,
    998       it is assumed that any hardware prefetch triggered succeeds before a
    999       real access is done. Thus, this gives a best-case scenario by covering
   1000       all possible stream accesses.</para>
   1001     </listitem>
   1002   </varlistentry>
   1003 
   1004   <varlistentry id="opt.cacheuse" xreflabel="--cacheuse">
   1005     <term>
   1006       <option><![CDATA[--cacheuse=<yes|no> [default: no] ]]></option>
   1007     </term>
   1008     <listitem>
   1009       <para>Specify whether cache line use should be collected. For every
   1010       cache line, from loading to it being evicted, the number of accesses
   1011       as well as the number of actually used bytes is determined. This
   1012       behavior is related to the code which triggered loading of the cache
   1013       line. In contrast to miss counters, which shows the position where
   1014       the symptoms of bad cache behavior (i.e. latencies) happens, the
   1015       use counters try to pinpoint at the reason (i.e. the code with the
   1016       bad access behavior). The new counters are defined in a way such
   1017       that worse behavior results in higher cost.
   1018       AcCost1 and AcCost2 are counters showing bad temporal locality
   1019       for L1 and LL caches, respectively. This is done by summing up
   1020       reciprocal values of the numbers of accesses of each cache line,
   1021       multiplied by 1000 (as only integer costs are allowed). E.g. for
   1022       a given source line with 5 read accesses, a value of 5000 AcCost
   1023       means that for every access, a new cache line was loaded and directly
   1024       evicted afterwards without further accesses. Similarly, SpLoss1/2
   1025       shows bad spatial locality for L1 and LL caches, respectively. It
   1026       gives the <emphasis>spatial loss</emphasis> count of bytes which
   1027       were loaded into cache but never accessed. It pinpoints at code
   1028       accessing data in a way such that cache space is wasted. This hints
   1029       at bad layout of data structures in memory. Assuming a cache line
   1030       size of 64 bytes and 100 L1 misses for a given source line, the
   1031       loading of 6400 bytes into L1 was triggered. If SpLoss1 shows a
   1032       value of 3200 for this line, this means that half of the loaded data was
   1033       never used, or using a better data layout, only half of the cache
   1034       space would have been needed.
   1035       Please note that for cache line use counters, it currently is
   1036       not possible to provide meaningful inclusive costs. Therefore,
   1037       inclusive cost of these counters should be ignored.
   1038       </para>
   1039     </listitem>
   1040   </varlistentry>
   1041 
   1042   <varlistentry id="opt.I1" xreflabel="--I1">
   1043     <term>
   1044       <option><![CDATA[--I1=<size>,<associativity>,<line size> ]]></option>
   1045     </term>
   1046     <listitem>
   1047       <para>Specify the size, associativity and line size of the level 1
   1048       instruction cache.  </para>
   1049     </listitem>
   1050   </varlistentry>
   1051 
   1052   <varlistentry id="opt.D1" xreflabel="--D1">
   1053     <term>
   1054       <option><![CDATA[--D1=<size>,<associativity>,<line size> ]]></option>
   1055     </term>
   1056     <listitem>
   1057       <para>Specify the size, associativity and line size of the level 1
   1058       data cache.</para>
   1059     </listitem>
   1060   </varlistentry>
   1061 
   1062   <varlistentry id="opt.LL" xreflabel="--LL">
   1063     <term>
   1064       <option><![CDATA[--LL=<size>,<associativity>,<line size> ]]></option>
   1065     </term>
   1066     <listitem>
   1067       <para>Specify the size, associativity and line size of the last-level
   1068       cache.</para>
   1069     </listitem>
   1070   </varlistentry>
   1071 </variablelist>
   1072 <!-- end of xi:include in the manpage -->
   1073 
   1074 </sect2>
   1075 
   1076 </sect1>
   1077 
   1078 <sect1 id="cl-manual.monitor-commands" xreflabel="Callgrind Monitor Commands">
   1079 <title>Callgrind Monitor Commands</title>
   1080 <para>The Callgrind tool provides monitor commands handled by the Valgrind
   1081 gdbserver (see <xref linkend="manual-core-adv.gdbserver-commandhandling"/>).
   1082 </para>
   1083 
   1084 <itemizedlist>
   1085   <listitem>
   1086     <para><varname>dump [&lt;dump_hint&gt;]</varname> requests to dump the
   1087     profile data. </para>
   1088   </listitem>
   1089 
   1090   <listitem>
   1091     <para><varname>zero</varname> requests to zero the profile data
   1092     counters. </para>
   1093   </listitem>
   1094 
   1095   <listitem>
   1096     <para><varname>instrumentation [on|off]</varname> requests to set 
   1097     (if parameter on/off is given) or get the current instrumentation state.
   1098     </para>
   1099   </listitem>
   1100 
   1101   <listitem>
   1102     <para><varname>status</varname> requests to print out some status
   1103     information.</para>
   1104   </listitem>
   1105 
   1106 </itemizedlist>
   1107 </sect1>
   1108 
   1109 <sect1 id="cl-manual.clientrequests" xreflabel="Client request reference">
   1110 <title>Callgrind specific client requests</title>
   1111 
   1112 <para>Callgrind provides the following specific client requests in
   1113 <filename>callgrind.h</filename>.  See that file for the exact details of
   1114 their arguments.</para>
   1115 
   1116 <variablelist id="cl.clientrequests.list">
   1117   
   1118   <varlistentry id="cr.dump-stats" xreflabel="CALLGRIND_DUMP_STATS">
   1119     <term>
   1120       <computeroutput>CALLGRIND_DUMP_STATS</computeroutput>
   1121     </term>
   1122     <listitem>
   1123       <para>Force generation of a profile dump at specified position
   1124       in code, for the current thread only. Written counters will be reset
   1125       to zero.</para>
   1126     </listitem>
   1127   </varlistentry>
   1128 
   1129   <varlistentry id="cr.dump-stats-at" xreflabel="CALLGRIND_DUMP_STATS_AT">
   1130     <term>
   1131       <computeroutput>CALLGRIND_DUMP_STATS_AT(string)</computeroutput>
   1132     </term>
   1133     <listitem>
   1134       <para>Same as <computeroutput>CALLGRIND_DUMP_STATS</computeroutput>,
   1135       but allows to specify a string to be able to distinguish profile
   1136       dumps.</para>
   1137     </listitem>
   1138   </varlistentry>
   1139 
   1140   <varlistentry id="cr.zero-stats" xreflabel="CALLGRIND_ZERO_STATS">
   1141     <term>
   1142       <computeroutput>CALLGRIND_ZERO_STATS</computeroutput>
   1143     </term>
   1144     <listitem>
   1145       <para>Reset the profile counters for the current thread to zero.</para>
   1146     </listitem>
   1147   </varlistentry>
   1148 
   1149   <varlistentry id="cr.toggle-collect" xreflabel="CALLGRIND_TOGGLE_COLLECT">
   1150     <term>
   1151       <computeroutput>CALLGRIND_TOGGLE_COLLECT</computeroutput>
   1152     </term>
   1153     <listitem>
   1154       <para>Toggle the collection state. This allows to ignore events
   1155       with regard to profile counters. See also options
   1156       <option><xref linkend="opt.collect-atstart"/></option> and
   1157       <option><xref linkend="opt.toggle-collect"/></option>.</para>
   1158     </listitem>
   1159   </varlistentry>
   1160 
   1161   <varlistentry id="cr.start-instr" xreflabel="CALLGRIND_START_INSTRUMENTATION">
   1162     <term>
   1163       <computeroutput>CALLGRIND_START_INSTRUMENTATION</computeroutput>
   1164     </term>
   1165     <listitem>
   1166       <para>Start full Callgrind instrumentation if not already enabled.
   1167       When cache simulation is done, this will flush the simulated cache
   1168       and lead to an artifical cache warmup phase afterwards with
   1169       cache misses which would not have happened in reality.  See also
   1170       option <option><xref linkend="opt.instr-atstart"/></option>.</para>
   1171     </listitem>
   1172   </varlistentry>
   1173 
   1174   <varlistentry id="cr.stop-instr" xreflabel="CALLGRIND_STOP_INSTRUMENTATION">
   1175     <term>
   1176       <computeroutput>CALLGRIND_STOP_INSTRUMENTATION</computeroutput>
   1177     </term>
   1178     <listitem>
   1179       <para>Stop full Callgrind instrumentation if not already disabled.
   1180       This flushes Valgrinds translation cache, and does no additional
   1181       instrumentation afterwards: it effectivly will run at the same
   1182       speed as Nulgrind, i.e. at minimal slowdown. Use this to
   1183       speed up the Callgrind run for uninteresting code parts. Use
   1184       <computeroutput><xref linkend="cr.start-instr"/></computeroutput> to
   1185       enable instrumentation again.  See also option
   1186       <option><xref linkend="opt.instr-atstart"/></option>.</para>
   1187     </listitem>
   1188   </varlistentry>
   1189 
   1190 </variablelist>
   1191 
   1192 </sect1>
   1193 
   1194 
   1195 
   1196 <sect1 id="cl-manual.callgrind_annotate-options" xreflabel="callgrind_annotate Command-line Options">
   1197 <title>callgrind_annotate Command-line Options</title>
   1198 
   1199 <!-- start of xi:include in the manpage -->
   1200 <variablelist id="callgrind_annotate.opts.list">
   1201 
   1202   <varlistentry>
   1203     <term><option>-h --help</option></term>
   1204     <listitem>
   1205       <para>Show summary of options.</para>
   1206     </listitem>
   1207   </varlistentry>
   1208 
   1209   <varlistentry>
   1210     <term><option>--version</option></term>
   1211     <listitem>
   1212       <para>Show version of callgrind_annotate.</para>
   1213     </listitem>
   1214   </varlistentry>
   1215 
   1216   <varlistentry>
   1217     <term>
   1218       <option>--show=A,B,C [default: all]</option>
   1219     </term>
   1220     <listitem>
   1221       <para>Only show figures for events A,B,C.</para>
   1222     </listitem>
   1223   </varlistentry>
   1224 
   1225   <varlistentry>
   1226     <term>
   1227       <option>--sort=A,B,C</option>
   1228     </term>
   1229     <listitem>
   1230       <para>Sort columns by events A,B,C [event column order].</para>
   1231     </listitem>
   1232   </varlistentry>
   1233 
   1234   <varlistentry>
   1235     <term>
   1236       <option><![CDATA[--threshold=<0--100> [default: 99%] ]]></option>
   1237     </term>
   1238     <listitem>
   1239       <para>Percentage of counts (of primary sort event) we are 
   1240       interested in.</para>
   1241     </listitem>
   1242   </varlistentry>
   1243 
   1244   <varlistentry>
   1245     <term>
   1246       <option><![CDATA[--auto=<yes|no> [default: no] ]]></option>
   1247     </term>
   1248     <listitem>
   1249       <para>Annotate all source files containing functions that helped 
   1250       reach the event count threshold.</para>
   1251     </listitem>
   1252   </varlistentry>
   1253 
   1254   <varlistentry>
   1255     <term>
   1256       <option>--context=N [default: 8] </option>
   1257     </term>
   1258     <listitem>
   1259       <para>Print N lines of context before and after annotated 
   1260       lines.</para>
   1261     </listitem>
   1262   </varlistentry>
   1263 
   1264   <varlistentry>
   1265     <term>
   1266       <option><![CDATA[--inclusive=<yes|no> [default: no] ]]></option>
   1267     </term>
   1268     <listitem>
   1269       <para>Add subroutine costs to functions calls.</para>
   1270     </listitem>
   1271   </varlistentry>
   1272 
   1273   <varlistentry>
   1274     <term>
   1275       <option><![CDATA[--tree=<none|caller|calling|both> [default: none] ]]></option>
   1276     </term>
   1277     <listitem>
   1278       <para>Print for each function their callers, the called functions 
   1279       or both.</para>
   1280     </listitem>
   1281   </varlistentry>
   1282 
   1283   <varlistentry>
   1284     <term>
   1285       <option><![CDATA[-I, --include=<dir> ]]></option>
   1286     </term>
   1287     <listitem>
   1288       <para>Add <option>dir</option> to the list of directories to search
   1289       for source files.</para>
   1290   </listitem>
   1291   </varlistentry>
   1292 
   1293 </variablelist>
   1294 <!-- end of xi:include in the manpage -->
   1295 
   1296 
   1297 </sect1>
   1298 
   1299 
   1300 
   1301 
   1302 <sect1 id="cl-manual.callgrind_control-options" xreflabel="callgrind_control Command-line Options">
   1303 <title>callgrind_control Command-line Options</title>
   1304 
   1305 <para>By default, callgrind_control acts on all programs run by the
   1306   current user under Callgrind.  It is possible to limit the actions to
   1307   specified Callgrind runs by providing a list of pids or program names as
   1308   argument.  The default action is to give some brief information about the
   1309   applications being run under Callgrind.</para>
   1310 
   1311 <!-- start of xi:include in the manpage -->
   1312 <variablelist id="callgrind_control.opts.list">
   1313 
   1314   <varlistentry>
   1315     <term><option>-h --help</option></term>
   1316     <listitem>
   1317       <para>Show a short description, usage, and summary of options.</para>
   1318     </listitem>
   1319   </varlistentry>
   1320 
   1321   <varlistentry>
   1322     <term><option>--version</option></term>
   1323     <listitem>
   1324       <para>Show version of callgrind_control.</para>
   1325     </listitem>
   1326   </varlistentry>
   1327 
   1328   <varlistentry>
   1329     <term><option>-l --long</option></term>
   1330     <listitem>
   1331       <para>Show also the working directory, in addition to the brief
   1332       information given by default.
   1333       </para>
   1334     </listitem>
   1335   </varlistentry>
   1336 
   1337   <varlistentry>
   1338     <term><option>-s --stat</option></term>
   1339     <listitem>
   1340       <para>Show statistics information about active Callgrind runs.</para>
   1341     </listitem>
   1342   </varlistentry>
   1343 
   1344   <varlistentry>
   1345     <term><option>-b --back</option></term>
   1346     <listitem>
   1347       <para>Show stack/back traces of each thread in active Callgrind runs. For
   1348       each active function in the stack trace, also the number of invocations
   1349       since program start (or last dump) is shown. This option can be
   1350       combined with -e to show inclusive cost of active functions.</para>
   1351     </listitem>
   1352   </varlistentry>
   1353 
   1354   <varlistentry>
   1355     <term><option><![CDATA[-e [A,B,...] ]]></option> (default: all)</term>
   1356     <listitem>
   1357       <para>Show the current per-thread, exclusive cost values of event
   1358       counters. If no explicit event names are given, figures for all event
   1359       types which are collected in the given Callgrind run are
   1360       shown. Otherwise, only figures for event types A, B, ... are shown. If
   1361       this option is combined with -b, inclusive cost for the functions of
   1362       each active stack frame is provided, too.
   1363       </para>
   1364     </listitem>
   1365   </varlistentry>
   1366 
   1367   <varlistentry>
   1368     <term><option><![CDATA[--dump[=<desc>] ]]></option> (default: no description)</term>
   1369     <listitem>
   1370       <para>Request the dumping of profile information. Optionally, a 
   1371       description can be specified which is written into the dump as part of
   1372       the information giving the reason which triggered the dump action. This
   1373       can be used to distinguish multiple dumps.</para>
   1374     </listitem>
   1375   </varlistentry>
   1376 
   1377   <varlistentry>
   1378     <term><option>-z --zero</option></term>
   1379     <listitem>
   1380       <para>Zero all event counters.</para>
   1381     </listitem>
   1382   </varlistentry>
   1383 
   1384   <varlistentry>
   1385     <term><option>-k --kill</option></term>
   1386     <listitem>
   1387       <para>Force a Callgrind run to be terminated.</para>
   1388     </listitem>
   1389   </varlistentry>
   1390 
   1391   <varlistentry>
   1392     <term><option><![CDATA[--instr=<on|off>]]></option></term>
   1393     <listitem>
   1394       <para>Switch instrumentation mode on or off. If a Callgrind run has
   1395       instrumentation disabled, no simulation is done and no events are
   1396       counted. This is useful to skip uninteresting program parts, as there
   1397       is much less slowdown (same as with the Valgrind tool "none"). See also
   1398       the Callgrind option <option>--instr-atstart</option>.</para>
   1399     </listitem>
   1400   </varlistentry>
   1401 
   1402   <varlistentry>
   1403     <term><option><![CDATA[-w=<dir>]]></option></term>
   1404     <listitem>
   1405       <para>Specify the startup directory of an active Callgrind run. On some
   1406       systems, active Callgrind runs can not be detected. To be able to
   1407       control these, the failed auto-detection can be worked around by
   1408       specifying the directory where a Callgrind run was started.</para>
   1409     </listitem>
   1410   </varlistentry>
   1411 </variablelist>
   1412 <!-- end of xi:include in the manpage -->
   1413 
   1414 </sect1>
   1415 
   1416 </chapter>
   1417