Changes between Initial Version and Version 1 of CallgrindFormat

Timestamp:

07/26/09 07:13:19 (13 years ago)

Author:

cotto

Comment:

initial version

CallgrindFormat

@@ +1 @@
+= 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:
+{{{
+#!c
+#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.
+
+{{{
+#!sh
+# 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.