Introduction

Callgrind's output format is very general because it's targeted by a number of different tools. This page describes Callgrind's output format as it pertains to PIR-level profiling for Parrot.

Terms

• Process under test - This is the process of the program being profiled, i.e. a PIR program of some sort.
• Profile - This refers to the output file containing profiling information for the process under test.

Format Description

The format consists of a header and a body. The header consists of several key value pairs which describe the purpose of the profile. KCachegrind ignores lines it doesn't know about. In the example below, this feature is used to add comments to an example profile. See the bottom of this page for information about how this example was generated.

Example

Example C Code

The following C code was used to generate a (nearly) trivial profile:

#include <stdio.h>
#include <valgrind/callgrind.h>

void func1();
void func2();
void func3();

int main() {
    CALLGRIND_START_INSTRUMENTATION;
    func1();
    func2();
    func3();
    CALLGRIND_STOP_INSTRUMENTATION;
}

void func1() {
    int i;
    for (i = 0; i < 1000000; i++);
}

void func2() {
    int i;
    for (i = 0; i < 1000000; i++);
    func1();
}

void func3() {
    int i;
    for (i = 0; i < 1000000; i++);
    func2();
    func1();
}

The program was compiled and profiled as follows:

gcc callgrind_test.c -g -o callgrind_test
valgrind --tool=callgrind --compress-strings=no --compress-pos=no --instr-atstart=no ./callgrind_test

Annotated Header from the Profile of above C Code

The above valgrind invocation produced a profile in callgrind.out.PID, where PID is the process ID of the process under test. Below is the header of the profile, annotated with a description of the purpose of each line.

# version of the Callgrind format
version: 1

# what created this profile, informational only
creator: 3.4.1-Debian

# PID of the process under test
pid: 5751

# the full CLI invocation that started the process under test
cmd:  ./callgrind_test

# used when multiple dumps are produced, starts from 1 and increments
part: 1

# parameters used for the cache simulator; not relevant for function profiling
desc: I1 cache:
desc: D1 cache:
desc: L2 cache:

# not really sure
desc: Timerange: Basic block 0 - 7000029

# Why did the process under test stop?  (informational only)
desc: Trigger: Program termination

# (optional) what do positions mean?
# "line" - (default) positions are line numbers in a file
# "instr" - positions are offsets in a binary representing instructions
positions: line

# (required) event types logged by this file
# "Ir" - instruction read access
# "I1mr" - instruction L1 read cache miss
# "I2mr" - instruction L2 read cache miss
events: Ir

# (recommended) the total number of events covered by this profile
# This is intended to allow postprocessing tools to know the total cost in advance.
# "totals" appears at the end of the file and has the same value.
summary: 21000073

Annotated Body from the Profile of above C Code

This space for rent.