Valgrind: r16196 - in /trunk: NEWS callgrind/docs/cl-format.xml callgrind/dump.c coregrind/m_xtree.c

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
Report Content as Inappropriate

Valgrind: r16196 - in /trunk: NEWS callgrind/docs/cl-format.xml callgrind/dump.c coregrind/m_xtree.c

Author: weidendo
Date: Tue Jan 10 20:21:21 2017
New Revision: 16196

Add a format marker to callgrind files

KCachegrind currently uses a quick format detection before
actually loading a file, and checks for a line starting with
"events:" in the first 2kB for that. This obviously is fragile,
as shown by an internal bug report by Philippe: before the
"events" line, Callgrind puts a "cmd:" line with the command
line. If this is very long, the detection fails and the file
does not get loaded at all.

While KCachegrind would not need to have this quick format
check at all, it is useful if multiple input format filters
get supported at some point, to automatically select the
correct filter.

Further, for the "file" command, for file managers and
desktop environments, having an unique way to detect a
file format is important.

It is not too late to fix this issue for the callgrind format.


Modified: trunk/NEWS
--- trunk/NEWS (original)
+++ trunk/NEWS Tue Jan 10 20:21:21 2017
@@ -63,6 +63,11 @@
   are caused by the inner guest program (such as an inner regtest).
   See README_DEVELOPERS for more info.
+* To allow fast detection of callgrind files in desktop environments
+  and file managers, the format was extended to have an optional
+  first line uniquely identifying the format ("# callgrind format").
+  Callgrind creates this line now (also the new xtree functionality).
 * ==================== FIXED BUGS ====================
 The following bugs have been fixed or resolved.  Note that "n-i-bz"

Modified: trunk/callgrind/docs/cl-format.xml
--- trunk/callgrind/docs/cl-format.xml (original)
+++ trunk/callgrind/docs/cl-format.xml Tue Jan 10 20:21:21 2017
@@ -6,10 +6,7 @@
 <chapter id="cl-format" xreflabel="Callgrind Format Specification">
 <title>Callgrind Format Specification</title>
-<para>This chapter describes the Callgrind Profile Format, Version 1.</para>
-<para>A synonymous name is "Calltree Profile Format". These names actually mean
-the same since Callgrind was previously named Calltree.</para>
+<para>This chapter describes the Callgrind Format, Version 1.</para>
 <para>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
@@ -29,6 +26,10 @@
 <sect2 id="cl-format.overview.basics" xreflabel="Basic Structure">
 <title>Basic Structure</title>
+<para>To uniquely specify that a file is a callgrind profile, it
+should add "# callgrind format" as first line. This is optional but
+recommended for easy format detection.</para>
 <para>Each file has a header part of an arbitrary number of lines of the
 format "key: value". After the header, lines specifying profile costs
 follow. Everywhere, comments on own lines starting with '#' are allowed.
@@ -58,7 +59,8 @@
 However, any profiling tool could use the format described in this chapter.</para>
-<screen>events: Cycles Instructions Flops
+<screen># callgrind format
+events: Cycles Instructions Flops
 15 90 14 2
@@ -130,7 +132,9 @@
 <function>main</function> calls <function>func1</function> once and
 <function>func2</function> 3 times. <function>func1</function> calls
 <function>func2</function> 2 times.
-<screen>events: Instructions
+<screen># callgrind format
+events: Instructions
@@ -186,8 +190,9 @@
 mapping. There is a separate ID mapping for each position specification,
 i.e. you can use ID 1 for both a file name and a symbol name.</para>
-<para>With string compression, the example from 1.4 looks like this:
-<screen>events: Instructions
+<para>With string compression, the example from above looks like this:
+<screen># callgrind format
+events: Instructions
 fl=(1) file1.c
 fn=(1) main
@@ -216,7 +221,8 @@
 everywhere in the file without any negative consequence. Especially, you can
 define name compression mappings directly after the header, and before any cost
 lines. Thus, the above example can also be written as
-<screen>events: Instructions
+<screen># callgrind format
+events: Instructions
 # define file ID mapping
 fl=(1) file1.c
@@ -256,7 +262,8 @@
 absolute and relative subposition specifications can be mixed freely.
 Assume the following example (subpositions can always be specified
 as hexadecimal numbers, beginning with "0x"):
-<screen>positions: instr line
+<screen># callgrind format
+positions: instr line
 events: ticks
@@ -265,7 +272,8 @@
 0x80001238 91 6</screen></para>
 <para>With subposition compression, this looks like
-<screen>positions: instr line
+<screen># callgrind format
+positions: instr line
 events: ticks
@@ -326,7 +334,8 @@
-<screen>ProfileDataFile := FormatVersion? Creator? PartData*</screen>
+<screen>ProfileDataFile := FormatSpec? FormatVersion? Creator? PartData*</screen>
+<screen>FormatSpec := "# callgrind format\n"</screen>
 <screen>FormatVersion := "version: 1\n"</screen>
 <screen>Creator := "creator:" NoNewLineChar* "\n"</screen>
 <screen>PartData := (HeaderLine "\n")+ (BodyLine "\n")+</screen>
@@ -379,7 +388,7 @@
 <para>A profile data file ("ProfileDataFile") starts with basic information
-  such as the version and creator information, and then has a list of parts, where
+  such as a format marker, the version and creator information, and then has a list of parts, where
   each part has its own header and body. Parts typically are different threads
   and/or time spans/phases within a profiled application run.</para>
@@ -396,11 +405,23 @@
+    <para><computeroutput># callgrind format</computeroutput> [Callgrind]</para>
+    <para>This line specifies that the file is a callgrind profile,
+      and it has to be the first line. It was added late to the
+      format (with Valgrind 3.13) and is optional, as all readers also
+      should work with older callgrind profiles not including this line.
+      However, generation of this line is recommended to allow desktop
+      environments and file managers to uniquely detect the format.</para>
+  </listitem>
+  <listitem>
     <para><computeroutput>version: number</computeroutput> [Callgrind]</para>
     <para>This is used to distinguish future profile data formats.  A
     major version of 0 or 1 is supposed to be upwards compatible with
     Cachegrind's format.  It is optional; if not appearing, version 1
-    is assumed.  Otherwise, this has to be the first header line.</para>
+    is assumed.  Otherwise, it has to follow directly after the format
+    specification (i.e. be the first line if the optional format
+    specification is skipped).</para>

Modified: trunk/callgrind/dump.c
--- trunk/callgrind/dump.c (original)
+++ trunk/callgrind/dump.c Tue Jan 10 20:21:21 2017
@@ -1215,6 +1215,9 @@
     if (!appending) {
+ /* callgrind format specification, has to be on 1st line */
+ VG_(fprintf)(fp, "# callgrind format\n");
  /* version */
  VG_(fprintf)(fp, "version: 1\n");

Modified: trunk/coregrind/m_xtree.c
--- trunk/coregrind/m_xtree.c (original)
+++ trunk/coregrind/m_xtree.c Tue Jan 10 20:21:21 2017
@@ -442,6 +442,7 @@
    filename_ddpa = VG_(newDedupPA)(16000, 1, xt->alloc_fn,
                                    "XT_callgrind_print.fl", xt->free_fn);
+   FP("# callgrind format\n");
    FP("version: 1\n");
    FP("creator: xtree-1\n");
    FP("pid: %d\n", VG_(getpid)());

Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today. http://sdm.link/xeonphi
Valgrind-developers mailing list
[hidden email]