From: Josef Weidendorfer Date: Fri, 26 Jun 2015 14:05:33 +0000 (+0000) Subject: Complete/Fix Callgrind format specification. X-Git-Tag: svn/VALGRIND_3_11_0~285 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9cd0f4e2119e8e1b1d878c98ac32512daae0f76d;p=thirdparty%2Fvalgrind.git Complete/Fix Callgrind format specification. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@15358 --- diff --git a/callgrind/docs/cl-format.xml b/callgrind/docs/cl-format.xml index 4426b6ac7c..00b0a52be9 100644 --- a/callgrind/docs/cl-format.xml +++ b/callgrind/docs/cl-format.xml @@ -103,7 +103,7 @@ file also can contain association specifications. These look similar to position specifications, but consist of two lines. For calls, the format looks like - calls=(Call Count) (Destination position) + calls=(Call Count) (Target position) (Source position) (Inclusive cost of call) @@ -327,7 +327,7 @@ for "Ir and "Dr". ProfileDataFile := FormatVersion? Creator? PartData* -FormatVersion := "version:" Space* Number "\n" +FormatVersion := "version: 1\n" Creator := "creator:" NoNewLineChar* "\n" PartData := (HeaderLine "\n")+ (BodyLine "\n")+ HeaderLine := (empty line) @@ -351,22 +351,23 @@ for "Ir and "Dr". BodyLine := (empty line) | ('#' NoNewLineChar*) | CostLine - | PositionSpecification - | AssociationSpecification + | PositionSpec + | CallSpec + | UncondJumpSpec + | CondJumpSpec CostLine := SubPositionList Costs? SubPositionList := (SubPosition+ Space+)+ SubPosition := Number | "+" Number | "-" Number | "*" Costs := (Number Space+)+ -PositionSpecification := Position "=" Space* PositionName +PositionSpec := Position "=" Space* PositionName Position := CostPosition | CalledPosition CostPosition := "ob" | "fl" | "fi" | "fe" | "fn" CalledPosition := " "cob" | "cfi" | "cfl" | "cfn" PositionName := ( "(" Number ")" )? (Space* NoNewLineChar* )? -AssociationSpecification := CallSpecification - | JumpSpecification -CallSpecification := CallLine "\n" CostLine +CallSpec := CallLine "\n" CostLine CallLine := "calls=" Space* Number Space+ SubPositionList -JumpSpecification := ... +UncondJumpSpec := "jump=" Space* Number Space+ SubPositionList +CondJumpSpec := "jcnd=" Space* Number Space+ Number Space+ SubPositionList Space := " " | "\t" Number := HexNumber | (Digit)+ Digit := "0" | ... | "9" @@ -382,11 +383,15 @@ for "Ir and "Dr". Description of Header Lines -The header has an arbitrary number of lines of the format -"key: value". Possible key values for the header are: +As given in the grammar, a profile data file starts with basic information + such as 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. - +Basic information in the first lines of a profile data file, + optionally, allowed to appear only once: + version: number [Callgrind] This is used to distinguish future profile data formats. A @@ -395,6 +400,19 @@ for "Ir and "Dr". is assumed. Otherwise, this has to be the first header line. + + creator: string [Callgrind] + This is an arbitrary string to denote the creator of this file. + Optional. + + + + +The header for each part has an arbitrary number of lines of the format +"key: value". Possible key values for the header are: + + + pid: process id [Callgrind] Optional. This specifies the process ID of the supervised application @@ -441,33 +459,18 @@ for "Ir and "Dr". responsible for the events raised. Note that the mapping of "instr" and "line" positions are given by the debugging line information produced by the compiler. - This field is optional. If not specified, "line" is supposed - only. + This header line is optional, defaulting to "positions: + line" if not specified. events: event type abbreviations [Cachegrind] - A list of short names of the event types logged in this file. - The order is the same as in cost lines. The first event type is the - second or third number in a cost line, depending on the value of - "positions". Callgrind does not add additional cost types. Specify - exactly once. - Cost types from original Cachegrind are: - - - Ir: Instruction read access - - - I1mr: Instruction Level 1 read cache miss - - - ILmr: Instruction last-level read cache miss - - - ... - - - + A list of short names of the event types logged in this + file. Arbitrary short names are allowed. The order given + specifies the required order in cost lines within the body of + this part. Thus, the first event type is the second or third number + in a cost line, depending on the value of "positions". + Required to appear for each header part exactly once. @@ -491,9 +494,19 @@ for "Ir and "Dr". Description of Body Lines -There exist lines -spec=position. The values for position -specifications are arbitrary strings. When starting with "(" and a +The regular body line is a cost line consisting of one or two +position numbers (depending on "positions:" header line, see above) +and an array of cost numbers. A position number either is a +line numbers into a source file or an instruction address within binary +code, with source/binary file names specified as position names (see +below). The cost numbers get mapped to event types in the same order +as specified in the "events:" header line. If less numbers than event +types are given, the costs default to zero for the remaining event +types. + +Further, there exist lines +spec=position name. A position name +is an arbitrary string. If it starts with "(" and a digit, it's a string in compressed format. Otherwise it's the real position string. This allows for file and symbol names as position strings, as these never start with "(" + digit. @@ -558,26 +571,30 @@ optional. lines. + + +The last type of body line provides specific costs not just +related to one position as regular cost lines. It starts with specific +strings similar to position name specifications. + + + - calls= [Callgrind] - The number of nonrecursive calls which are responsible for the - cost specified by the next call cost line. This is the cost spent - inside of the called function. - After "calls=" there MUST be a cost line. This is the cost - spent in the called function. The first number is the source line - from where the call happened. + calls=count target-position [Callgrind] + Call executed "count" times to "target-position". + After a "calls=" line there MUST be a cost line. This provides the source position + of the call and the cost spent in the called function in total. - jump=count target position [Callgrind] - Unconditional jump, executed count times, to the given target - position. + jump=count target-position [Callgrind] + Unconditional jump, executed "count" times, to "target-position". - jcnd=exe.count jumpcount target position [Callgrind] - Conditional jump, executed exe.count times with jumpcount - jumps to the given target position. + jcnd=exe-count jump-count target-position [Callgrind] + Conditional jump, executed "exe-count" times with "jump-count" jumps + happening (rest is fall-through) to "target-position".