Re: Update gprof documentation

[Daniel Jacobowitz <drow at mvista dot com>]

On Wed, Oct 29, 2003 at 06:12:03PM +0000, Nick Clifton wrote:
> Hi Guys,
> 
>   At the request of RMS I am applying this patch to the gprof
>   documentation.

Thanks.  This patch is not entirely correct, though.  I know I should
conclude this message with a patch if I'm going to complain, but I
don't have time today - so here's just some comments.

> 2003-10-29  Nick Clifton  <nickc@redhat.com>
> 
> 	* gprof.texi: Apply patch supplied by Eric S Raymond via RMS.
> 	(Compiling): Mention that -pg must be passed to both the compiler
> 	and the linker.
> 	Mention that -a is now deprecated.
> 	(How do I?): Add an entry describing how to get more information
> 	about program hotspots.
> 
> Index: gprof/gprof.texi
> ===================================================================
> RCS file: /cvs/src/src/gprof/gprof.texi,v
> retrieving revision 1.10
> diff -c -3 -p -r1.10 gprof.texi
> *** gprof/gprof.texi	30 Jul 2002 07:02:54 -0000	1.10
> --- gprof/gprof.texi	29 Oct 2003 18:19:35 -0000
> *************** This manual describes the @sc{gnu} profi
> *** 53,61 ****
>   can use it to determine which parts of a program are taking most of the
>   execution time.  We assume that you know how to write, compile, and
>   execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
>   
>   @vskip 0pt plus 1filll
> ! Copyright @copyright{} 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
>   
>         Permission is granted to copy, distribute and/or modify this document
>         under the terms of the GNU Free Documentation License, Version 1.1
> --- 53,62 ----
>   can use it to determine which parts of a program are taking most of the
>   execution time.  We assume that you know how to write, compile, and
>   execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
> + Eric S. Raymond made some minor corrections and additions in 2003.
>   
>   @vskip 0pt plus 1filll
> ! Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2003 Free Software Foundation, Inc.
>   
>         Permission is granted to copy, distribute and/or modify this document
>         under the terms of the GNU Free Documentation License, Version 1.1
> *************** The @samp{-pg} option also works with a 
> *** 278,283 ****
> --- 279,292 ----
>   cc -o myprog myprog.c utils.c -g -pg
>   @end example
>   
> + Note: The @samp{-pg} option must be part of your compilation options
> + as well as your link options.  If it is not, when you run @code{gprof}
> + you will get no profile report and an error message like this:
> + 
> + @example
> + gprof: gmon.out file is missing call-graph data
> + @end example
> + 
>   If you run the linker @code{ld} directly instead of through a compiler
>   such as @code{cc}, you may have to specify a profiling startup file
>   @file{gcrt0.o} as the first input file instead of the usual startup

Well, that's half true.  If you compile without -pg but link with -pg
(or compile and link without, and call monstartup!), you can still get
time sampling information:

drow@nevyn:~/prof% gcc -c proftest.c             
drow@nevyn:~/prof% gcc -pg proftest.o -o proftest
drow@nevyn:~/prof% ./proftest                    
drow@nevyn:~/prof% gprof proftest                
gprof: gmon.out file is missing call-graph data
drow@nevyn:~/prof% gprof -Q proftest | head      
Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total           
 time   seconds   seconds    calls  Ts/call  Ts/call  name    
 44.12      0.07     0.07                             zazLoop
 35.29      0.14     0.06                             main
 20.59      0.17     0.04                             bazMillion

 %         the percentage of the total running time of the


GDB even supports profiling itself via "maint set profile" with no
compilation options.  The results are still useful.

> *************** nonce, the estimated figures are usually
> *** 1627,1632 ****
> --- 1639,1652 ----
>   @chapter Answers to Common Questions
>   
>   @table @asis
> + @item How can I get more exact information about hot spots in my program?
> + 
> + Looking at the per-line call counts only tells part of the story.
> + Because @code{gprof} can only report call times and counts by function,
> + the best way to get finer-grained information on where the program
> + is spending its time is to re-factor large functions into sequences
> + of calls to smaller ones.
> + 

... which can create hot spots due to function call overhead; a number
of GDB functions show up as terrible hot points in gprof but aren't
even on the list in a non-intrusive profiler like oprofile.  Function
calls with -pg are not cheap.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer