Home | History | Annotate | only in /toolchain/binutils/binutils-2.25/gprof
Up to higher level directory
NameDateSize
.gdbinit21-Oct-20167
.gitignore21-Oct-201684
aarch64.c21-Oct-20163.2K
aclocal.m421-Oct-201635.4K
alpha.c21-Oct-20165.4K
basic_blocks.c21-Oct-201614.6K
basic_blocks.h21-Oct-20161.4K
bb_exit_func.c21-Oct-20162.6K
bbconv.pl21-Oct-20161.8K
bsd_callg_bl.m21-Oct-20163.4K
call_graph.c21-Oct-20163.9K
call_graph.h21-Oct-20161K
cg_arcs.c21-Oct-201618.4K
cg_arcs.h21-Oct-20161.9K
cg_dfn.c21-Oct-20167.5K
cg_dfn.h21-Oct-20161.1K
cg_print.c21-Oct-201634.1K
cg_print.h21-Oct-20161.1K
ChangeLog21-Oct-20161.8K
ChangeLog-200421-Oct-20163.2K
ChangeLog-200521-Oct-20164.5K
ChangeLog-200621-Oct-20163.8K
ChangeLog-200721-Oct-20167.2K
ChangeLog-200821-Oct-20163.1K
ChangeLog-200921-Oct-20166.4K
ChangeLog-201021-Oct-20162.6K
ChangeLog-201121-Oct-20162.3K
ChangeLog-201221-Oct-20162.1K
ChangeLog-201321-Oct-20161.5K
ChangeLog-920321-Oct-201669.5K
configure21-Oct-2016421.4K
configure.ac21-Oct-20162.4K
corefile.c21-Oct-201624.7K
corefile.h21-Oct-20161.6K
dep-in.sed21-Oct-2016257
fdl.texi21-Oct-201623K
flat_bl.m21-Oct-20161.2K
fsf_callg_bl.m21-Oct-20163.6K
gconfig.in21-Oct-20163K
gen-c-prog.awk21-Oct-2016648
gmon.h21-Oct-20164.8K
gmon_io.c21-Oct-201617K
gmon_io.h21-Oct-20161.6K
gmon_out.h21-Oct-20161.5K
gprof.c21-Oct-201616.2K
gprof.h21-Oct-20164.6K
gprof.texi21-Oct-201690.7K
hertz.c21-Oct-20162.4K
hertz.h21-Oct-20161.1K
hist.c21-Oct-201620.6K
hist.h21-Oct-20162K
i386.c21-Oct-20163.2K
MAINTAINERS21-Oct-2016259
Makefile.am21-Oct-20163.6K
Makefile.in21-Oct-201637.2K
mips.c21-Oct-20163.6K
po/21-Oct-2016
README21-Oct-201617.2K
search_list.c21-Oct-20161.5K
search_list.h21-Oct-20161.4K
source.c21-Oct-20165.9K
source.h21-Oct-20162.3K
sparc.c21-Oct-20163.1K
stamp-h.in21-Oct-201610
sym_ids.c21-Oct-20169.2K
sym_ids.h21-Oct-20161.3K
symtab.c21-Oct-20167K
symtab.h21-Oct-20164.2K
tahoe.c21-Oct-20169K
TEST21-Oct-2016278
TODO21-Oct-20163.6K
utils.c21-Oct-20163.2K
utils.h21-Oct-2016955
vax.c21-Oct-20169.1K

README

      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