From: Nicholas Nethercote Date: Fri, 7 Aug 2009 05:40:26 +0000 (+0000) Subject: Minor changes to Callgrind file format docs. X-Git-Tag: svn/VALGRIND_3_5_0~114 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0278a4c81a6d545ccfd7a30df85f7f1d95b43b4f;p=thirdparty%2Fvalgrind.git Minor changes to Callgrind file format docs. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10736 --- diff --git a/callgrind/docs/cl-format.xml b/callgrind/docs/cl-format.xml index f997aa8e44..fd86b33378 100644 --- a/callgrind/docs/cl-format.xml +++ b/callgrind/docs/cl-format.xml @@ -71,18 +71,21 @@ to "line", which means that the first number of a cost line is always a line number. Thus, the first cost line specifies that in line 15 of source file -"file.f" there is code belonging to function "main". While running, 90 CPU -cycles passed by, and 2 of the 14 instructions executed were floating point -operations. Similarly, the next line specifies that there were 12 instructions -executed in the context of function "main" which can be related to line 16 in -file "file.f", taking 20 CPU cycles. If a cost line specifies less event counts -than given in the "events" line, the rest is assumed to be zero. I.e., there -was no floating point instruction executed relating to line 16. +file.f there is code belonging to function +main. While running, 90 CPU cycles passed by, and 2 of +the 14 instructions executed were floating point operations. Similarly, the +next line specifies that there were 12 instructions executed in the context +of function main which can be related to line 16 in +file file.f, taking 20 CPU cycles. If a cost line +specifies less event counts than given in the "events" line, the rest is +assumed to be zero. I.e. there was no floating point instruction executed +relating to line 16. Note that regular cost lines always give self (also called exclusive) cost of code at a given position. If you specify multiple cost lines for the same position, these will be summed up. On the other hand, in the example above -there is no specification of how many times function "main" actually was +there is no specification of how many times function +main actually was called: profile data only contains sums. @@ -118,9 +121,11 @@ reference below for details. Extended Example -The following example shows 3 functions, "main", "func1", and -"func2". Function "main" calls "func1" once and "func2" 3 times. "func1" calls -"func2" 2 times. +The following example shows 3 functions, main, +func1, and func2. Function +main calls func1 once and +func2 3 times. func1 calls +func2 2 times. events: Instructions fl=file1.c @@ -145,14 +150,18 @@ fl=file2.c fn=func2 20 700 -One can see that in "main" only code from line 16 is executed where also -the other functions are called. Inclusive cost of "main" is 820, which is the -sum of self cost 20 and costs spent in the calls: 400 for the single call to -"func1" and 400 as sum for the three calls to "func2". +One can see that in main only code from line 16 +is executed where also the other functions are called. Inclusive cost of +main is 820, which is the sum of self cost 20 and costs +spent in the calls: 400 for the single call to func1 +and 400 as sum for the three calls to func2. -Function "func1" is located in "file1.c", the same as "main". Therefore, -a "cfl=" specification for the call to "func1" is not needed. The function -"func1" only consists of code at line 51 of "file1.c", where "func2" is called. +Function func1 is located in +file1.c, the same as main. +Therefore, a "cfl=" specification for the call to func1 +is not needed. The function func1 only consists of code +at line 51 of file1.c, where func2 +is called. @@ -227,7 +236,7 @@ fn=(1) If a Callgrind data file should hold costs for each assembler instruction of a program, you specify subposition "instr" in the "positions:" header line, and each cost line has to include the address of some instruction. Addresses -are allowed to have a size of 64bit to support 64bit architectures. Thus, +are allowed to have a size of 64 bits to support 64-bit architectures. Thus, repeating similar, long addresses for almost every line in the data file can enlarge the file size quite significantly, and motivates for subposition compression: instead of every cost line starting with @@ -378,7 +387,7 @@ for "Ir and "Dr". 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 - Cachegrinds format. It is optional; if not appearing, version 1 + Cachegrind's format. It is optional; if not appearing, version 1 is supposed. Otherwise, this has to be the first header line.