3. Callgrind Format Specification
This chapter describes the Callgrind Profile Format, Version 1.
A synonymous name is "Calltree Profile Format". These names actually mean the same since Callgrind was previously
named Calltree.
The format description is meant for the user to be able to understand the file contents; but more important, it is given
for authors of measurement or visualization tools to be able to write and read this format.
3.1. Overview
The profile data format is ASCII based. It is written by Callgrind, and it is upwards compatible to the format used by
Cachegrind (ie. Cachegrind uses a subset). It can be read by callgrind_annotate and KCachegrind.
This chapter gives on overview of format features and examples. For detailed syntax, look at the format reference.
3.1.1. Basic Structure
Each file has a header part of an arbitrary number of lines of the format "key: value". The lines with key "positions" and
"events" define the meaning of cost lines in the second part of the file: the value of "positions" is a list of subpositions,
and the value of "events" is a list of event type names. Cost lines consist of subpositions followed by 64-bit counters
for the events, in the order specified by the "positions" and "events" header line.
The "events" header line is always required in contrast to the optional line for "positions", which defaults to "line", i.e.
a line number of some source file. In addition, the second part of the file contains position specifications of the form
"spec=name". "spec" can be e.g. "fn" for a function name or "fl" for a file name. Cost lines are always related to the
function/file specifications given directly before.
3.1.2. Simple Example
The event names in the following example are quite arbitrary, and are not related to event names used by Callgrind.
Especially, cycle counts matching real processors probably will never be generated by any Valgrind tools, as these are
bound to simulations of simple machine models for acceptable slowdown. However, any profiling tool could use the
format described in this chapter.
events: Cycles Instructions Flops
fl=file.f
fn=main
15 90 14 2
16 20 12
The above example gives profile information for event types "Cycles", "Instructions", and "Flops". Thus, cost lines
give the number of CPU cycles passed by, number of executed instructions, and number of floating point operations
executed while running code corresponding to some source position. As there is no line specifying the value of
"positions", it defaults to "line", which means that the first number of a cost line is always a line number.
Thus, the first cost line specifies that in line 15 of source file
file.f
there is code belonging to function
main
. While
running, 90 CPU cycles passed by, and 2 of the 14 instructions executed were floating point operations. Similarly, the
next line specifies that there were 12 instructions executed in the context of function
main
which can be related to
9
