Add information about gcc 3.0 basic block profiling.

p4raw-id: //depot/perl@11366

3 files changed, 117 insertions, 26 deletions

diff --git a/Makefile.SH b/Makefile.SH
index 80bcc3405d..2df7ac8c6d 100644
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -504,7 +504,7 @@ miniperl: $& miniperlmain$(OBJ_EXT) $(LIBPERL) opmini$(OBJ_EXT)
 
 perl: $& perlmain$(OBJ_EXT) $(LIBPERL) $(DYNALOADER) $(static_ext) ext.libs $(PERLEXPORT)
 	-@rm -f miniperl.xok
-	$(SHRPENV) $(LDLIBPTH) $(CC) -o perl$(PERL_SUFFIX) $(PERL_PROFILING) $(CLDFLAGS) $(CCDLFLAGS) perlmain$(OBJ_EXT) $(DYNALOADER) $(static_ext) $(LLIBPERL) `cat ext.libs` $(libs)
+	$(SHRPENV) $(LDLIBPTH) $(CC) -o perl$(PERL_SUFFIX) $(PERL_PROFILE_LDFLAGS) $(CLDFLAGS) $(CCDLFLAGS) perlmain$(OBJ_EXT) $(DYNALOADER) $(static_ext) $(LLIBPERL) `cat ext.libs` $(libs)
 
 # Purify/Quantify Perls.
 
@@ -568,9 +568,26 @@ perl.gprof.config: config.sh
 
 perl.gprof: /usr/bin/gprof perl.gprof.config
 	@-rm -f perl
-	$(MAKE) PERL_SUFFIX=.gprof PERL_PROFILING=-pg perl
+	$(MAKE) PERL_SUFFIX=.gprof PERL_PROFILE_LDFLAGS=-pg perl
 	@echo "Now you may run perl.gprof and then run gprof perl.gprof."
 
+# Gcov Perl
+
+perl.config.gcov:
+	@echo "To build perl.gcov you must use gcc 3.0 or newer, checking..."
+	@echo "Checking gccversion in config.sh..."
+	@grep "^gccversion="      config.sh
+	@grep "^gccversion='[3-9]\." config.sh >/dev/null || exit 1
+	@echo "To build perl.gcov you must Configure -Dccflags=-fprofile-arcs -ftest-coverage, checking..."
+	@echo "Checking ccflags='-fprofile-arcs -ftest-coverage' in config.sh..."
+	@grep "^ccflags="      config.sh
+	@grep "^ccflags='.*-fprofile-arcs -ftest-coverage.*'" config.sh >/dev/null || exit 1
+
+perl.gcov: perl.config.gcov
+	@-rm -f perl
+	$(MAKE) PERL_SUFFIX=.gcov PERL_PROFILE_LDFLAGS='' perl
+	@echo "Now you may run perl.gcov and then run gcov some.c."
+
 # Microperl.  This is just a convenience thing if one happens to
 # build also the full Perl and therefore the real big Makefile:
 # usually one should manually explicitly issue the below command.
diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 64c69ad96e..f44036d3c2 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1686,7 +1686,8 @@ DEC OSF/1).
 
 When building Perl, you must first run Configure with -Doptimize=-g
 and -Uusemymalloc flags, after that you can use the make targets
-"perl.third" and "test.third".
+"perl.third" and "test.third".  (What is required is that Perl must be
+compiled using the C<-g> flag, you may need to re-Configure.)
 
 The short story is that with "atom" you can instrument the Perl
 executable to create a new executable called F<perl.third>.  When the
@@ -1731,16 +1732,47 @@ need to do too, if you don't want to see the "global leaks":
 
 	PERL_DESTRUCT_LEVEL=2 ./perl.third t/foo/bar.t
 
+=head2 Profiling
+
+Depending on your platform there are various of profiling Perl.
+
+There are two commonly used techniques of profiling executables:
+E<statistical time-sampling> and E<basic-block counting>.
+
+The first method takes periodically samples of the CPU program
+counter, and since the program counter can be correlated with the code
+generated for functions, we get a statistical view of in which
+functions the program is spending its time.  The caveats are that very
+small/fast functions have lower probability of showing up in the
+profile, and that periodically interrupting the program (this is
+usually done rather frequently, in the scale of milliseconds) imposes
+an additional overhead that may skew the results.  The first problem
+can be alleviated by running the code for longer (in general this is a
+good idea for profiling), the second problem is usually kept in guard
+by the profiling tools themselves.
+
+The second method divides up the generated code into E<basic blocks>.
+Basic blocks are sections of code that are entered only in the
+beginning and exited only at the end.  For example, a conditional jump
+starts a basic block.  Basic block profiling usually works by
+E<instrumenting> the code by adding E<enter basic block #nnnn>
+book-keeping code to the generated code.  During the execution of the
+code the basic block counters are then updated appropriately.  The
+caveat is that the added extra code can skew the results: again, the
+profiling tools usually try to factor their own effects out of the
+results.
+
 =head2 Gprof Profiling
 
-gprof is a profiling tool available in many UNIX platforms.
-The profiling is based on statistical time-sampling; this means that
-some routines, especially those executing really fast, may be missed.
+gprof is a profiling tool available in many UNIX platforms,
+it uses F<statistical time-sampling>.
 
 You can build a profiled version of perl called "perl.gprof" by
-invoking the make target "perl.gprof".  Running the profiled version
-of Perl will create an output file called F<gmon.out> is created which
-contains the profiling data collected during the execution.
+invoking the make target "perl.gprof"  (What is required is that Perl
+must be compiled using the C<-pg> flag, you may need to re-Configure).
+Running the profiled version of Perl will create an output file called
+F<gmon.out> is created which contains the profiling data collected
+during the execution.
 
 The gprof tool can then display the collected data in various ways.
 Usually gprof understands the following options:
@@ -1777,21 +1809,59 @@ Display routines that have zero usage.
 For more detailed explanation of the available commands and output
 formats, see your own local documentation of gprof.
 
+=head2 GCC gcov Profiling
+
+Starting from GCC 3.0 E<basic block profiling> is officially available
+for the GNU CC.
+
+You can build a profiled version of perl called F<perl.gcov> by
+invoking the make target "perl.gcov" (what is required that Perl must
+be compiled using gcc with the flags C<-fprofile-arcs
+-ftest-coverage>, you may need to re-Configure).
+
+Running the profiled version of Perl will cause profile output to be
+generated.  For each source file an accompanying ".da" file will be
+created.
+
+To display the results you use the "gcov" utility (which should
+be installed if you have gcc 3.0 or newer installed).  F<gcov> is
+run on source code files, like this
+
+    gcov sv.c
+
+which will cause F<sv.c.gcov> to be created.  The F<.gcov> files
+contain the source code annotated with relative frequencies of
+execution indicated by "#" markers.
+
+Useful options of F<gcov> include C<-b> which will summarise the
+basic block, branch, and function call coverage, and C<-c> which
+instead of relative frequencies will use the actual counts.  For
+more information on the use of F<gcov> and basic block profiling
+with gcc, see the latest GNU CC manual, as of GCC 3.0 see
+
+    http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html
+
+and its section titled "8. gcov: a Test Coverage Program"
+
+    http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132
+
 =head2 Pixie Profiling
 
-Pixie is a profiling tool available on IRIX and Tru64
-(aka Digital UNIX aka DEC OSF/1) platforms.  Pixie does its profiling
-using "basic-block counting".  A basic block is a program region that
-is entered only at the beginning and exited only at the end.
+Pixie is a profiling tool available on IRIX and Tru64 (aka Digital
+UNIX aka DEC OSF/1) platforms.  Pixie does its profiling using
+E<basic-block counting>.
 
 You can build a profiled version of perl called F<perl.pixie> by
-invoking the make target "perl.pixie" (in Tru64 a file called
-F<perl.Addrs> will also be silently created, this file contains the
-addresses of the basic blocks).  Running the profiled version of Perl
-will create a new file called "perl.Counts" which contains the counts
-for the basic block for that particular program execution.
+invoking the make target "perl.pixie" (what is required is that Perl
+must be compiled using the C<-g> flag, you may need to re-Configure).
+
+In Tru64 a file called F<perl.Addrs> will also be silently created,
+this file contains the addresses of the basic blocks.  Running the
+profiled version of Perl will create a new file called "perl.Counts"
+which contains the counts for the basic block for that particular
+program execution.
 
-To display the results you must use the "prof" utility.  The exact
+To display the results you use the F<prof> utility.  The exact
 incantation depends on your operating system, "prof perl.Counts" in
 IRIX, and "prof -pixie -all -L. perl" in Tru64.
 
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index c906397762..54814683e1 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -2198,8 +2198,7 @@ chcp, dataset access, OS/390, z/OS iconv, locales
 
 attributes, attrs, autouse, base, blib, bytes, charnames, constant,
 diagnostics, fields, filetest, integer, less, locale, open, ops, overload,
-re, sigtrap, strict, subs, unicode::distinct, utf8, vars, warnings,
-warnings::register
+re, sigtrap, strict, subs, utf8, vars, warnings, warnings::register
 
 =item Standard Modules
 
@@ -2239,10 +2238,11 @@ Pod::Usage, SDBM_File, Safe, Search::Dict, SelectSaver, SelfLoader, Shell,
 Socket, Storable, Switch, Symbol, Term::ANSIColor, Term::Cap,
 Term::Complete, Term::ReadLine, Test, Test::Harness, Test::More,
 Test::Simple, Text::Abbrev, Text::Balanced, Text::ParseWords,
-Text::Soundex, Text::Tabs, Text::Wrap, Tie::Array, Tie::Handle, Tie::Hash,
-Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::Local, Time::gmtime,
-Time::localtime, Time::tm, UNIVERSAL, UnicodeCD, User::grent, User::pwent,
-Win32
+Text::Soundex, Text::Tabs, Text::Wrap, Thread, Thread::Queue,
+Thread::Semaphore, Thread::Signal, Thread::Specific, Tie::Array,
+Tie::Handle, Tie::Hash, Tie::RefHash, Tie::Scalar, Tie::SubstrHash,
+Time::Local, Time::gmtime, Time::localtime, Time::tm, UNIVERSAL, UnicodeCD,
+User::grent, User::pwent, Win32
 
 =item Extension Modules
 
@@ -4515,10 +4515,14 @@ DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug
 
 =item PERL_DESTRUCT_LEVEL
 
+=item Profiling
+
 =item Gprof Profiling
 
 -a, -b, -e routine, -f routine, -s, -z
 
+=item GCC gcov Profiling
+
 =item Pixie Profiling
 
 -h, -l, -p[rocedures], -h[eavy], -i[nvocations], -l[ines], -testcoverage,
@@ -6186,7 +6190,7 @@ Buildtype.bat, SetNWBld.bat, MPKBuild.bat
 
 =item Acknowledgements
 
-=item Author
+=item Authors
 
 =item Date