diff options
Diffstat (limited to 'gprof/README')
| -rw-r--r-- | gprof/README | 442 |
1 files changed, 0 insertions, 442 deletions
diff --git a/gprof/README b/gprof/README deleted file mode 100644 index 8fe2da8a5ae..00000000000 --- a/gprof/README +++ /dev/null @@ -1,442 +0,0 @@ - README for GPROF - -This is the GNU profiler. It is distributed with other "binary -utilities" which should be in ../binutils. See ../binutils/README for -more general notes, including where to send bug reports. - -This file documents the changes and new features available with this -version of GNU gprof. - -* New Features - - o Long options - - o Supports generalized file format, without breaking backward compatibility: - new file format supports basic-block execution counts and non-realtime - histograms (see below) - - o Supports profiling at the line level: flat profiles, call-graph profiles, - and execution-counts can all be displayed at a level that identifies - individual lines rather than just functions - - o Test-coverage support (similar to Sun tcov program): source files - can be annotated with the number of times a function was invoked - or with the number of times each basic-block in a function was - executed - - o Generalized histograms: not just execution-time, but arbitrary - histograms are support (for example, performance counter based - profiles) - - o Powerful mechanism to select data to be included/excluded from - analysis and/or output - - o Support for DEC OSF/1 v3.0 - - o Full cross-platform profiling support: gprof uses BFD to support - arbitrary, non-native object file formats and non-native byte-orders - (this feature has not been tested yet) - - o In the call-graph function index, static function names are now - printed together with the filename in which the function was defined - (required bfd_find_nearest_line() support and symbolic debugging - information to be present in the executable file) - - o Major overhaul of source code (compiles cleanly with -Wall, etc.) - -* Supported Platforms - -The current version is known to work on: - - o DEC OSF/1 v3.0 - All features supported. - - o SunOS 4.1.x - All features supported. - - o Solaris 2.3 - Line-level profiling unsupported because bfd_find_nearest_line() - is not fully implemented for Elf binaries. - - o HP-UX 9.01 - Line-level profiling unsupported because bfd_find_nearest_line() - is not fully implemented for SOM binaries. - -* Detailed Description - -** User Interface Changes - -The command-line interface is backwards compatible with earlier -versions of GNU gprof and Berkeley gprof. The only exception is -the option to delete arcs from the call graph. The old syntax -was: - - -k fromname toname - -while the new syntax is: - - -k fromname/toname - -This change was necessary to be compatible with long-option parsing. -Also, "fromname" and "toname" can now be arbitrary symspecs rather -than just function names (see below for an explanation of symspecs). -For example, option "-k gprof.c/" suppresses all arcs due to calls out -of file "gprof.c". - -*** Sym Specs - -It is often necessary to apply gprof only to specific parts of a -program. GNU gprof has a simple but powerful mechanism to achieve -this. So called {\em symspecs\/} provide the foundation for this -mechanism. A symspec selects the parts of a profiled program to which -an operation should be applied to. The syntax of a symspec is -simple: - - filename_containing_a_dot - | funcname_not_containing_a_dot - | linenumber - | ( [ any_filename ] `:' ( any_funcname | linenumber ) ) - -Here are some examples: - - main.c Selects everything in file "main.c"---the - dot in the string tells gprof to interpret - the string as a filename, rather than as - a function name. To select a file whose - name does contain a dot, a trailing colon - should be specified. For example, "odd:" is - interpreted as the file named "odd". - - main Selects all functions named "main". Notice - that there may be multiple instances of the - same function name because some of the - definitions may be local (i.e., static). - Unless a function name is unique in a program, - you must use the colon notation explained - below to specify a function from a specific - source file. Sometimes, functionnames contain - dots. In such cases, it is necessary to - add a leading colon to the name. For example, - ":.mul" selects function ".mul". - - main.c:main Selects function "main" in file "main.c". - - main.c:134 Selects line 134 in file "main.c". - -IMPLEMENTATION NOTE: The source code uses the type sym_id for symspecs. -At some point, this probably ought to be changed to "sym_spec" to make -reading the code easier. - -*** Long options - -GNU gprof now supports long options. The following is a list of all -supported options. Options that are listed without description -operate in the same manner as the corresponding option in older -versions of gprof. - -Short Form: Long Form: ------------ ---------- --l --line - Request profiling at the line-level rather - than just at the function level. Source - lines are identified by symbols of the form: - - func (file:line) - - where "func" is the function name, "file" is the - file name and "line" is the line-number that - corresponds to the line. - - To work properly, the binary must contain symbolic - debugging information. This means that the source - have to be translated with option "-g" specified. - Functions for which there is no symbolic debugging - information available are treated as if "--line" - had not been specified. However, the line number - printed with such symbols is usually incorrect - and should be ignored. - --a --no-static --A[symspec] --annotated-source[=symspec] - Request output in the form of annotated source - files. If "symspec" is specified, print output only - for symbols selected by "symspec". If the option - is specified multiple times, annotated output is - generated for the union of all symspecs. - - Examples: - - -A Prints annotated source for all - source files. - -Agprof.c Prints annotated source for file - gprof.c. - -Afoobar Prints annotated source for files - containing a function named "foobar". - The entire file will be printed, but - only the function itself will be - annotated with profile data. - --J[symspec] --no-annotated-source[=symspec] - Suppress annotated source output. If specified - without argument, annotated output is suppressed - completely. With an argument, annotated output - is suppressed only for the symbols selected by - "symspec". If the option is specified multiple - times, annotated output is suppressed for the - union of all symspecs. This option has lower - precedence than --annotated-source - --p[symspec] --flat-profile[=symspec] - Request output in the form of a flat profile - (unless any other output-style option is specified, - this option is turned on by default). If - "symspec" is specified, include only symbols - selected by "symspec" in flat profile. If the - option is specified multiple times, the flat - profile includes symbols selected by the union - of all symspecs. - --P[symspec] --no-flat-profile[=symspec] - Suppress output in the flat profile. If given - without an argument, the flat profile is suppressed - completely. If "symspec" is specified, suppress - the selected symbols in the flat profile. If the - option is specified multiple times, the union of - the selected symbols is suppressed. This option - has lower precedence than --flat-profile. - --q[symspec] --graph[=symspec] - Request output in the form of a call-graph - (unless any other output-style option is specified, - this option is turned on by default). If "symspec" - is specified, include only symbols selected by - "symspec" in the call-graph. If the option is - specified multiple times, the call-graph includes - symbols selected by the union of all symspecs. - --Q[symspec] --no-graph[=symspec] - Suppress output in the call-graph. If given without - an argument, the call-graph is suppressed completely. - With a "symspec", suppress the selected symbols - from the call-graph. If the option is specified - multiple times, the union of the selected symbols - is suppressed. This option has lower precedence - than --graph. - --C[symspec] --exec-counts[=symspec] - Request output in the form of execution counts. - If "symspec" is present, include only symbols - selected by "symspec" in the execution count - listing. If the option is specified multiple - times, the execution count listing includes - symbols selected by the union of all symspecs. - --Z[symspec] --no-exec-counts[=symspec] - Suppress output in the execution count listing. - If given without an argument, the listing is - suppressed completely. With a "symspec", suppress - the selected symbols from the call-graph. If the - option is specified multiple times, the union of - the selected symbols is suppressed. This option - has lower precedence than --exec-counts. - --i --file-info - Print information about the profile files that - are read. The information consists of the - number and types of records present in the - profile file. Currently, a profile file can - contain any number and any combination of histogram, - call-graph, or basic-block count records. - --s --sum - --x --all-lines - This option affects annotated source output only. - By default, only the lines at the beginning of - a basic-block are annotated. If this option is - specified, every line in a basic-block is annotated - by repeating the annotation for the first line. - This option is identical to tcov's "-a". - --I dirs --directory-path=dirs - This option affects annotated source output only. - Specifies the list of directories to be searched - for source files. The argument "dirs" is a colon - separated list of directories. By default, gprof - searches for source files relative to the current - working directory only. - --z --display-unused-functions - --m num --min-count=num - This option affects annotated source and execution - count output only. Symbols that are executed - less than "num" times are suppressed. For annotated - source output, suppressed symbols are marked - by five hash-marks (#####). In an execution count - output, suppressed symbols do not appear at all. - --L --print-path - Normally, source filenames are printed with the path - component suppressed. With this option, gprof - can be forced to print the full pathname of - source filenames. The full pathname is determined - from symbolic debugging information in the image file - and is relative to the directory in which the compiler - was invoked. - --y --separate-files - This option affects annotated source output only. - Normally, gprof prints annotated source files - to standard-output. If this option is specified, - annotated source for a file named "path/filename" - is generated in the file "filename-ann". That is, - annotated output is {\em always\/} generated in - gprof's current working directory. Care has to - be taken if a program consists of files that have - identical filenames, but distinct paths. - --c --static-call-graph - --t num --table-length=num - This option affects annotated source output only. - After annotating a source file, gprof generates - an execution count summary consisting of a table - of lines with the top execution counts. By - default, this table is ten entries long. - This option can be used to change the table length - or, by specifying an argument value of 0, it can be - suppressed completely. - --n symspec --time=symspec - Only symbols selected by "symspec" are considered - in total and percentage time computations. - However, this option does not affect percentage time - computation for the flat profile. - If the option is specified multiple times, the union - of all selected symbols is used in time computations. - --N --no-time=symspec - Exclude the symbols selected by "symspec" from - total and percentage time computations. - However, this option does not affect percentage time - computation for the flat profile. - This option is ignored if any --time options are - specified. - --w num --width=num - Sets the output line width. Currently, this option - affects the printing of the call-graph function index - only. - --e <no long form---for backwards compatibility only> --E <no long form---for backwards compatibility only> --f <no long form---for backwards compatibility only> --F <no long form---for backwards compatibility only> --k <no long form---for backwards compatibility only> --b --brief --dnum --debug[=num] - --h --help - Prints a usage message. - --O name --file-format=name - Selects the format of the profile data files. - Recognized formats are "auto", "bsd", "magic", - and "prof". The last one is not yet supported. - Format "auto" attempts to detect the file format - automatically (this is the default behavior). - It attempts to read the profile data files as - "magic" files and if this fails, falls back to - the "bsd" format. "bsd" forces gprof to read - the data files in the BSD format. "magic" forces - gprof to read the data files in the "magic" format. - --T --traditional --v --version - -** File Format Changes - -The old BSD-derived format used for profile data does not contain a -magic cookie that allows to check whether a data file really is a -gprof file. Furthermore, it does not provide a version number, thus -rendering changes to the file format almost impossible. GNU gprof -uses a new file format that provides these features. For backward -compatibility, GNU gprof continues to support the old BSD-derived -format, but not all features are supported with it. For example, -basic-block execution counts cannot be accommodated by the old file -format. - -The new file format is defined in header file \file{gmon_out.h}. It -consists of a header containing the magic cookie and a version number, -as well as some spare bytes available for future extensions. All data -in a profile data file is in the native format of the host on which -the profile was collected. GNU gprof adapts automatically to the -byte-order in use. - -In the new file format, the header is followed by a sequence of -records. Currently, there are three different record types: histogram -records, call-graph arc records, and basic-block execution count -records. Each file can contain any number of each record type. When -reading a file, GNU gprof will ensure records of the same type are -compatible with each other and compute the union of all records. For -example, for basic-block execution counts, the union is simply the sum -of all execution counts for each basic-block. - -*** Histogram Records - -Histogram records consist of a header that is followed by an array of -bins. The header contains the text-segment range that the histogram -spans, the size of the histogram in bytes (unlike in the old BSD -format, this does not include the size of the header), the rate of the -profiling clock, and the physical dimension that the bin counts -represent after being scaled by the profiling clock rate. The -physical dimension is specified in two parts: a long name of up to 15 -characters and a single character abbreviation. For example, a -histogram representing real-time would specify the long name as -"seconds" and the abbreviation as "s". This feature is useful for -architectures that support performance monitor hardware (which, -fortunately, is becoming increasingly common). For example, under DEC -OSF/1, the "uprofile" command can be used to produce a histogram of, -say, instruction cache misses. In this case, the dimension in the -histogram header could be set to "i-cache misses" and the abbreviation -could be set to "1" (because it is simply a count, not a physical -dimension). Also, the profiling rate would have to be set to 1 in -this case. - -Histogram bins are 16-bit numbers and each bin represent an equal -amount of text-space. For example, if the text-segment is one -thousand bytes long and if there are ten bins in the histogram, each -bin represents one hundred bytes. - - -*** Call-Graph Records - -Call-graph records have a format that is identical to the one used in -the BSD-derived file format. It consists of an arc in the call graph -and a count indicating the number of times the arc was traversed -during program execution. Arcs are specified by a pair of addresses: -the first must be within caller's function and the second must be -within the callee's function. When performing profiling at the -function level, these addresses can point anywhere within the -respective function. However, when profiling at the line-level, it is -better if the addresses are as close to the call-site/entry-point as -possible. This will ensure that the line-level call-graph is able to -identify exactly which line of source code performed calls to a -function. - -*** Basic-Block Execution Count Records - -Basic-block execution count records consist of a header followed by a -sequence of address/count pairs. The header simply specifies the -length of the sequence. In an address/count pair, the address -identifies a basic-block and the count specifies the number of times -that basic-block was executed. Any address within the basic-address can -be used. - -IMPLEMENTATION NOTE: gcc -a can be used to instrument a program to -record basic-block execution counts. However, the __bb_exit_func() -that is currently present in libgcc2.c does not generate a gmon.out -file in a suitable format. This should be fixed for future releases -of gcc. In the meantime, contact davidm@cs.arizona.edu for a version -of __bb_exit_func() to is appropriate. |