1 README for GPROF 2 3 This is the GNU profiler. It is distributed with other "binary 4 utilities" which should be in ../binutils. See ../binutils/README for 5 more general notes, including where to send bug reports. 6 7 This file documents the changes and new features available with this 8 version of GNU gprof. 9 10 * New Features 11 12 o Long options 13 14 o Supports generalized file format, without breaking backward compatibility: 15 new file format supports basic-block execution counts and non-realtime 16 histograms (see below) 17 18 o Supports profiling at the line level: flat profiles, call-graph profiles, 19 and execution-counts can all be displayed at a level that identifies 20 individual lines rather than just functions 21 22 o Test-coverage support (similar to Sun tcov program): source files 23 can be annotated with the number of times a function was invoked 24 or with the number of times each basic-block in a function was 25 executed 26 27 o Generalized histograms: not just execution-time, but arbitrary 28 histograms are support (for example, performance counter based 29 profiles) 30 31 o Powerful mechanism to select data to be included/excluded from 32 analysis and/or output 33 34 o Support for DEC OSF/1 v3.0 35 36 o Full cross-platform profiling support: gprof uses BFD to support 37 arbitrary, non-native object file formats and non-native byte-orders 38 (this feature has not been tested yet) 39 40 o In the call-graph function index, static function names are now 41 printed together with the filename in which the function was defined 42 (required bfd_find_nearest_line() support and symbolic debugging 43 information to be present in the executable file) 44 45 o Major overhaul of source code (compiles cleanly with -Wall, etc.) 46 47 * Supported Platforms 48 49 The current version is known to work on: 50 51 o DEC OSF/1 v3.0 52 All features supported. 53 54 o SunOS 4.1.x 55 All features supported. 56 57 o Solaris 2.3 58 Line-level profiling unsupported because bfd_find_nearest_line() 59 is not fully implemented for Elf binaries. 60 61 o HP-UX 9.01 62 Line-level profiling unsupported because bfd_find_nearest_line() 63 is not fully implemented for SOM binaries. 64 65 * Detailed Description 66 67 ** User Interface Changes 68 69 The command-line interface is backwards compatible with earlier 70 versions of GNU gprof and Berkeley gprof. The only exception is 71 the option to delete arcs from the call graph. The old syntax 72 was: 73 74 -k fromname toname 75 76 while the new syntax is: 77 78 -k fromname/toname 79 80 This change was necessary to be compatible with long-option parsing. 81 Also, "fromname" and "toname" can now be arbitrary symspecs rather 82 than just function names (see below for an explanation of symspecs). 83 For example, option "-k gprof.c/" suppresses all arcs due to calls out 84 of file "gprof.c". 85 86 *** Sym Specs 87 88 It is often necessary to apply gprof only to specific parts of a 89 program. GNU gprof has a simple but powerful mechanism to achieve 90 this. So called {\em symspecs\/} provide the foundation for this 91 mechanism. A symspec selects the parts of a profiled program to which 92 an operation should be applied to. The syntax of a symspec is 93 simple: 94 95 filename_containing_a_dot 96 | funcname_not_containing_a_dot 97 | linenumber 98 | ( [ any_filename ] `:' ( any_funcname | linenumber ) ) 99 100 Here are some examples: 101 102 main.c Selects everything in file "main.c"---the 103 dot in the string tells gprof to interpret 104 the string as a filename, rather than as 105 a function name. To select a file whose 106 name does contain a dot, a trailing colon 107 should be specified. For example, "odd:" is 108 interpreted as the file named "odd". 109 110 main Selects all functions named "main". Notice 111 that there may be multiple instances of the 112 same function name because some of the 113 definitions may be local (i.e., static). 114 Unless a function name is unique in a program, 115 you must use the colon notation explained 116 below to specify a function from a specific 117 source file. Sometimes, functionnames contain 118 dots. In such cases, it is necessary to 119 add a leading colon to the name. For example, 120 ":.mul" selects function ".mul". 121 122 main.c:main Selects function "main" in file "main.c". 123 124 main.c:134 Selects line 134 in file "main.c". 125 126 IMPLEMENTATION NOTE: The source code uses the type sym_id for symspecs. 127 At some point, this probably ought to be changed to "sym_spec" to make 128 reading the code easier. 129 130 *** Long options 131 132 GNU gprof now supports long options. The following is a list of all 133 supported options. Options that are listed without description 134 operate in the same manner as the corresponding option in older 135 versions of gprof. 136 137 Short Form: Long Form: 138 ----------- ---------- 139 -l --line 140 Request profiling at the line-level rather 141 than just at the function level. Source 142 lines are identified by symbols of the form: 143 144 func (file:line) 145 146 where "func" is the function name, "file" is the 147 file name and "line" is the line-number that 148 corresponds to the line. 149 150 To work properly, the binary must contain symbolic 151 debugging information. This means that the source 152 have to be translated with option "-g" specified. 153 Functions for which there is no symbolic debugging 154 information available are treated as if "--line" 155 had not been specified. However, the line number 156 printed with such symbols is usually incorrect 157 and should be ignored. 158 159 -a --no-static 160 -A[symspec] --annotated-source[=symspec] 161 Request output in the form of annotated source 162 files. If "symspec" is specified, print output only 163 for symbols selected by "symspec". If the option 164 is specified multiple times, annotated output is 165 generated for the union of all symspecs. 166 167 Examples: 168 169 -A Prints annotated source for all 170 source files. 171 -Agprof.c Prints annotated source for file 172 gprof.c. 173 -Afoobar Prints annotated source for files 174 containing a function named "foobar". 175 The entire file will be printed, but 176 only the function itself will be 177 annotated with profile data. 178 179 -J[symspec] --no-annotated-source[=symspec] 180 Suppress annotated source output. If specified 181 without argument, annotated output is suppressed 182 completely. With an argument, annotated output 183 is suppressed only for the symbols selected by 184 "symspec". If the option is specified multiple 185 times, annotated output is suppressed for the 186 union of all symspecs. This option has lower 187 precedence than --annotated-source 188 189 -p[symspec] --flat-profile[=symspec] 190 Request output in the form of a flat profile 191 (unless any other output-style option is specified, 192 this option is turned on by default). If 193 "symspec" is specified, include only symbols 194 selected by "symspec" in flat profile. If the 195 option is specified multiple times, the flat 196 profile includes symbols selected by the union 197 of all symspecs. 198 199 -P[symspec] --no-flat-profile[=symspec] 200 Suppress output in the flat profile. If given 201 without an argument, the flat profile is suppressed 202 completely. If "symspec" is specified, suppress 203 the selected symbols in the flat profile. If the 204 option is specified multiple times, the union of 205 the selected symbols is suppressed. This option 206 has lower precedence than --flat-profile. 207 208 -q[symspec] --graph[=symspec] 209 Request output in the form of a call-graph 210 (unless any other output-style option is specified, 211 this option is turned on by default). If "symspec" 212 is specified, include only symbols selected by 213 "symspec" in the call-graph. If the option is 214 specified multiple times, the call-graph includes 215 symbols selected by the union of all symspecs. 216 217 -Q[symspec] --no-graph[=symspec] 218 Suppress output in the call-graph. If given without 219 an argument, the call-graph is suppressed completely. 220 With a "symspec", suppress the selected symbols 221 from the call-graph. If the option is specified 222 multiple times, the union of the selected symbols 223 is suppressed. This option has lower precedence 224 than --graph. 225 226 -C[symspec] --exec-counts[=symspec] 227 Request output in the form of execution counts. 228 If "symspec" is present, include only symbols 229 selected by "symspec" in the execution count 230 listing. If the option is specified multiple 231 times, the execution count listing includes 232 symbols selected by the union of all symspecs. 233 234 -Z[symspec] --no-exec-counts[=symspec] 235 Suppress output in the execution count listing. 236 If given without an argument, the listing is 237 suppressed completely. With a "symspec", suppress 238 the selected symbols from the call-graph. If the 239 option is specified multiple times, the union of 240 the selected symbols is suppressed. This option 241 has lower precedence than --exec-counts. 242 243 -i --file-info 244 Print information about the profile files that 245 are read. The information consists of the 246 number and types of records present in the 247 profile file. Currently, a profile file can 248 contain any number and any combination of histogram, 249 call-graph, or basic-block count records. 250 251 -s --sum 252 253 -x --all-lines 254 This option affects annotated source output only. 255 By default, only the lines at the beginning of 256 a basic-block are annotated. If this option is 257 specified, every line in a basic-block is annotated 258 by repeating the annotation for the first line. 259 This option is identical to tcov's "-a". 260 261 -I dirs --directory-path=dirs 262 This option affects annotated source output only. 263 Specifies the list of directories to be searched 264 for source files. The argument "dirs" is a colon 265 separated list of directories. By default, gprof 266 searches for source files relative to the current 267 working directory only. 268 269 -z --display-unused-functions 270 271 -m num --min-count=num 272 This option affects annotated source and execution 273 count output only. Symbols that are executed 274 less than "num" times are suppressed. For annotated 275 source output, suppressed symbols are marked 276 by five hash-marks (#####). In an execution count 277 output, suppressed symbols do not appear at all. 278 279 -L --print-path 280 Normally, source filenames are printed with the path 281 component suppressed. With this option, gprof 282 can be forced to print the full pathname of 283 source filenames. The full pathname is determined 284 from symbolic debugging information in the image file 285 and is relative to the directory in which the compiler 286 was invoked. 287 288 -y --separate-files 289 This option affects annotated source output only. 290 Normally, gprof prints annotated source files 291 to standard-output. If this option is specified, 292 annotated source for a file named "path/filename" 293 is generated in the file "filename-ann". That is, 294 annotated output is {\em always\/} generated in 295 gprof's current working directory. Care has to 296 be taken if a program consists of files that have 297 identical filenames, but distinct paths. 298 299 -c --static-call-graph 300 301 -t num --table-length=num 302 This option affects annotated source output only. 303 After annotating a source file, gprof generates 304 an execution count summary consisting of a table 305 of lines with the top execution counts. By 306 default, this table is ten entries long. 307 This option can be used to change the table length 308 or, by specifying an argument value of 0, it can be 309 suppressed completely. 310 311 -n symspec --time=symspec 312 Only symbols selected by "symspec" are considered 313 in total and percentage time computations. 314 However, this option does not affect percentage time 315 computation for the flat profile. 316 If the option is specified multiple times, the union 317 of all selected symbols is used in time computations. 318 319 -N --no-time=symspec 320 Exclude the symbols selected by "symspec" from 321 total and percentage time computations. 322 However, this option does not affect percentage time 323 computation for the flat profile. 324 This option is ignored if any --time options are 325 specified. 326 327 -w num --width=num 328 Sets the output line width. Currently, this option 329 affects the printing of the call-graph function index 330 only. 331 332 -e <no long form---for backwards compatibility only> 333 -E <no long form---for backwards compatibility only> 334 -f <no long form---for backwards compatibility only> 335 -F <no long form---for backwards compatibility only> 336 -k <no long form---for backwards compatibility only> 337 -b --brief 338 -dnum --debug[=num] 339 340 -h --help 341 Prints a usage message. 342 343 -O name --file-format=name 344 Selects the format of the profile data files. 345 Recognized formats are "auto", "bsd", "magic", 346 and "prof". The last one is not yet supported. 347 Format "auto" attempts to detect the file format 348 automatically (this is the default behavior). 349 It attempts to read the profile data files as 350 "magic" files and if this fails, falls back to 351 the "bsd" format. "bsd" forces gprof to read 352 the data files in the BSD format. "magic" forces 353 gprof to read the data files in the "magic" format. 354 355 -T --traditional 356 -v --version 357 358 ** File Format Changes 359 360 The old BSD-derived format used for profile data does not contain a 361 magic cookie that allows to check whether a data file really is a 362 gprof file. Furthermore, it does not provide a version number, thus 363 rendering changes to the file format almost impossible. GNU gprof 364 uses a new file format that provides these features. For backward 365 compatibility, GNU gprof continues to support the old BSD-derived 366 format, but not all features are supported with it. For example, 367 basic-block execution counts cannot be accommodated by the old file 368 format. 369 370 The new file format is defined in header file \file{gmon_out.h}. It 371 consists of a header containing the magic cookie and a version number, 372 as well as some spare bytes available for future extensions. All data 373 in a profile data file is in the native format of the host on which 374 the profile was collected. GNU gprof adapts automatically to the 375 byte-order in use. 376 377 In the new file format, the header is followed by a sequence of 378 records. Currently, there are three different record types: histogram 379 records, call-graph arc records, and basic-block execution count 380 records. Each file can contain any number of each record type. When 381 reading a file, GNU gprof will ensure records of the same type are 382 compatible with each other and compute the union of all records. For 383 example, for basic-block execution counts, the union is simply the sum 384 of all execution counts for each basic-block. 385 386 *** Histogram Records 387 388 Histogram records consist of a header that is followed by an array of 389 bins. The header contains the text-segment range that the histogram 390 spans, the size of the histogram in bytes (unlike in the old BSD 391 format, this does not include the size of the header), the rate of the 392 profiling clock, and the physical dimension that the bin counts 393 represent after being scaled by the profiling clock rate. The 394 physical dimension is specified in two parts: a long name of up to 15 395 characters and a single character abbreviation. For example, a 396 histogram representing real-time would specify the long name as 397 "seconds" and the abbreviation as "s". This feature is useful for 398 architectures that support performance monitor hardware (which, 399 fortunately, is becoming increasingly common). For example, under DEC 400 OSF/1, the "uprofile" command can be used to produce a histogram of, 401 say, instruction cache misses. In this case, the dimension in the 402 histogram header could be set to "i-cache misses" and the abbreviation 403 could be set to "1" (because it is simply a count, not a physical 404 dimension). Also, the profiling rate would have to be set to 1 in 405 this case. 406 407 Histogram bins are 16-bit numbers and each bin represent an equal 408 amount of text-space. For example, if the text-segment is one 409 thousand bytes long and if there are ten bins in the histogram, each 410 bin represents one hundred bytes. 411 412 413 *** Call-Graph Records 414 415 Call-graph records have a format that is identical to the one used in 416 the BSD-derived file format. It consists of an arc in the call graph 417 and a count indicating the number of times the arc was traversed 418 during program execution. Arcs are specified by a pair of addresses: 419 the first must be within caller's function and the second must be 420 within the callee's function. When performing profiling at the 421 function level, these addresses can point anywhere within the 422 respective function. However, when profiling at the line-level, it is 423 better if the addresses are as close to the call-site/entry-point as 424 possible. This will ensure that the line-level call-graph is able to 425 identify exactly which line of source code performed calls to a 426 function. 427 428 *** Basic-Block Execution Count Records 429 430 Basic-block execution count records consist of a header followed by a 431 sequence of address/count pairs. The header simply specifies the 432 length of the sequence. In an address/count pair, the address 433 identifies a basic-block and the count specifies the number of times 434 that basic-block was executed. Any address within the basic-address can 435 be used. 436 437 IMPLEMENTATION NOTE: gcc -a can be used to instrument a program to 438 record basic-block execution counts. However, the __bb_exit_func() 439 that is currently present in libgcc2.c does not generate a gmon.out 440 file in a suitable format. This should be fixed for future releases 441 of gcc. In the meantime, contact davidm (a] cs.arizona.edu for a version 442 of __bb_exit_func() to is appropriate. 443 445 Copyright (C) 2012-2014 Free Software Foundation, Inc. 446 447 Copying and distribution of this file, with or without modification, 448 are permitted in any medium without royalty provided the copyright 449 notice and this notice are preserved. 450
