Download Valgrind Documentation

Callgrind: a call-graph generating cache and branch prediction profiler
• Spontaneous, interactive dumping. Use
callgrind_control -d [hint [PID/Name]]
to request the dumping of profile information of the supervised application with PID or Name. hint is an arbitrary
string you can optionally specify to later be able to distinguish profile dumps. The control program will not
terminate before the dump is completely written. Note that the application 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 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.
• Periodic dumping after execution of a specified number of basic blocks. For this, use the command line option
--dump-every-bb=count.
• Dumping at enter/leave of specified functions.
Use the option --dump-before=function
and --dump-after=function.
To zero cost counters before entering a function, use
--zero-before=function.
You can specify these options multiple times for different functions. Function specifications support wildcards: e.g.
use --dump-before=’foo*’ to generate dumps before entering any function starting with foo.
• Program controlled dumping. Insert CALLGRIND_DUMP_STATS; at the position in your code where you want
a profile dump to happen. Use CALLGRIND_ZERO_STATS; to only zero profile counters. See Client request
reference for more information on Callgrind specific client requests.
If you are running a multi-threaded application and specify the command line option --separate-threads=yes,
every thread will be profiled on its own and will create its own profile dump. Thus, the last two methods will only
generate one dump of the currently running thread. With the other methods, you will get multiple dumps (one for each
thread) on a dump request.
6.2.2. Limiting the range of collected events
For aggregating events (function enter/leave, instruction execution, memory access) into event numbers, first, the
events must be recognizable by Callgrind, and second, the collection state must be enabled.
Event collection is only possible if instrumentation for program code is enabled. This is the default, but for
faster execution (identical to valgrind --tool=none), it can be disabled until the program reaches a state in
which you want to start collecting profiling data. Callgrind can start without instrumentation by specifying option
--instr-atstart=no. Instrumentation can be enabled interactively with:
callgrind_control -i on
and off by specifying "off" instead of "on". Furthermore, instrumentation state can be programatically changed with
the macros CALLGRIND_START_INSTRUMENTATION; and CALLGRIND_STOP_INSTRUMENTATION;.
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 a specific function by
using --toggle-collect=function. 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 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 disabled, the cache simulator cannot see any memory access events,
and thus, any simulated cache state will be frozen and wrong without instrumentation. Therefore, to get useful cache
events (hits/misses) after switching on instrumentation, the cache first must warm up, probably leading to many cold
74