From: Josef Weidendorfer Date: Tue, 10 Jan 2017 20:21:21 +0000 (+0000) Subject: Add a format marker to callgrind files X-Git-Tag: svn/VALGRIND_3_13_0~225 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=db860c7cdce8765f8c4ec28127860c8e97ba34ab;p=thirdparty%2Fvalgrind.git 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. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@16196 --- diff --git a/NEWS b/NEWS index d3126e7f9b..b684a300d1 100644 --- a/NEWS +++ b/NEWS @@ -63,6 +63,11 @@ X86/MacOSX 10.11/12, AMD64/MacOSX 10.11/12 and TILEGX/Linux. 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" diff --git a/callgrind/docs/cl-format.xml b/callgrind/docs/cl-format.xml index 182b199b59..77fe5dfdf6 100644 --- a/callgrind/docs/cl-format.xml +++ b/callgrind/docs/cl-format.xml @@ -6,10 +6,7 @@ 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. +This chapter describes the Callgrind Format, Version 1. 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 @@ For detailed syntax, look at the format reference. Basic Structure +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. + 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 @@ 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 +# callgrind format +events: Cycles Instructions Flops fl=file.f fn=main 15 90 14 2 @@ -130,7 +132,9 @@ reference below for details. main calls func1 once and func2 3 times. func1 calls func2 2 times. -events: Instructions + +# callgrind format +events: Instructions fl=file1.c fn=main @@ -186,8 +190,9 @@ integer ID to a name, and "spec=(ID)" to reference a previously defined ID 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. -With string compression, the example from 1.4 looks like this: -events: Instructions +With string compression, the example from above looks like this: +# callgrind format +events: Instructions fl=(1) file1.c fn=(1) main @@ -216,7 +221,8 @@ the meaning of subsequent cost lines or associations, they can appear 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 -events: Instructions +# callgrind format +events: Instructions # define file ID mapping fl=(1) file1.c @@ -256,7 +262,8 @@ prefixed by "-"), any relative specification is non-ambiguous; additionally, absolute and relative subposition specifications can be mixed freely. Assume the following example (subpositions can always be specified as hexadecimal numbers, beginning with "0x"): -positions: instr line +# callgrind format +positions: instr line events: ticks fn=func @@ -265,7 +272,8 @@ fn=func 0x80001238 91 6 With subposition compression, this looks like -positions: instr line +# callgrind format +positions: instr line events: ticks fn=func @@ -326,7 +334,8 @@ for "Ir and "Dr". Grammar -ProfileDataFile := FormatVersion? Creator? PartData* +ProfileDataFile := FormatSpec? FormatVersion? Creator? PartData* +FormatSpec := "# callgrind format\n" FormatVersion := "version: 1\n" Creator := "creator:" NoNewLineChar* "\n" PartData := (HeaderLine "\n")+ (BodyLine "\n")+ @@ -379,7 +388,7 @@ for "Ir and "Dr". 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. @@ -395,12 +404,24 @@ for "Ir and "Dr". Basic information in the first lines of a profile data file: + + # callgrind format [Callgrind] + 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. + + version: number [Callgrind] 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. + 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). diff --git a/callgrind/dump.c b/callgrind/dump.c index 8907995e55..b688ba853f 100644 --- a/callgrind/dump.c +++ b/callgrind/dump.c @@ -1215,6 +1215,9 @@ static VgFile *new_dumpfile(int tid, const HChar* trigger) if (!appending) { + /* callgrind format specification, has to be on 1st line */ + VG_(fprintf)(fp, "# callgrind format\n"); + /* version */ VG_(fprintf)(fp, "version: 1\n"); diff --git a/coregrind/m_xtree.c b/coregrind/m_xtree.c index 760cd34a99..1d94ded831 100644 --- a/coregrind/m_xtree.c +++ b/coregrind/m_xtree.c @@ -442,6 +442,7 @@ void VG_(XT_callgrind_print) 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)());