			PCT Frequently Asked Questions

0. What is the status of this document?

   A lot of this material pre-dates the dbctl generation of collectors which
   has very modest system requirements and very powerful capabilities.
   I've updated it a little, but mostly this document and others in the doc/
   directory remain more useful in explaining the very low overhead library
   collectors.

1. What does PCT do?

   PCT collects and analyzes periodic sampling traces of program executions.

   This is an easy to implement profiling strategy that often yields all the
   information needed to optimize a program, or to decide that it cannot be
   fruitfully optimized.  It is also a very low overhead mechanism.

2. How do I get started using PCT?

   On some OS's, you can just take any program or even shell script, compiled
   with (or less usefully without -g, but not stripped), and simply go:

      $ profile myprogram

   If you must re-link your binaries, the simplest mode of operation is to
   simply include /usr/lib/itimer.o (or wherever it is) on the link line.
   An alternative is to use /usr/lib/profil.o if your system doesn't support
   itimers, though profil.o cannot to profile usage of shared library code.
   You can then enable/disable profile data collection by the presence/absence
   of the PCT environment variable.  So a three-liner usage example is:

      $ gcc foo.c /usr/lib/itimer.o
      $ PCT='' ./a.out
      $ pct line /tmp/pct/ct/a.out.*/*

   Provided 'myprogram' runs a "large" number of time quanta (usually 10 ms,
   though this can be fruitfully shrunken) this will yields a most informative
   breakdown of where 'myprogram' caused CPU time to be spent on the system.

   More details about various command line filters are/will be documented in
   separate man pages/documentation files.  Documentation of the library
   facility is/will be in the man page for pct_on()/pct_off().

3. What does "pct" or "PCT" stand for?

   Personally, and for the paper, I go with Profile Collection Toolkit.
   As with most such questions, "whatever you like" is a fine answer, too.
   There are several useful, if ambiguous/degenerate, mnuemonics I had in mind.

   The 'flat' nature of the profile generated suggests "Per CenT".  This is
   reinforced by the literal output of profile formatting modules.  "PC Timing"
   also sort of falls into this category.

   The style of data collection suggests "PC Timer", since a PC sampling timer
   goes off at specified intervals.

   The style of data collected suggests "Program/Profile CounTs/CounTers" or
   "Program Counter Times".  Or "PC Times" or "Pc CTs", using the common cts
   abbreviation for counts.  Etc, etc.  I've even heard "PC Tracer/Tracker".

   The style of report generation suggests "Program Counting Toolkit/Toolbox",
   "Profile Collection Toolkit" and several other variants.  "Profiling with
   Chuck's Toolkit" is even a possibility. :-)

   The plethora of suggested meanings of PCT which all end up being in the
   right vague meaning space made it seem like a good name.  All programs,
   environment variables, and output files all have "pct" as a substring.
   So there's a lot of chances to memorize the abbreviation...

4. What system requirements does PCT have?

   PCT works, in some mode, on almost any Unix-like system.  It has more or
   less functionality on various specific systems.  On some systems, actually
   changing source code in main() might be necessary.  On others LD_PRELOAD can
   be used to just switch on PC counting.  Tweaking "arch.h" may be necessary
   to get things to compile/work for your particular system.  On most, dbctl-
   based collection will just work for a single process or even a process tree,
   but may impose significant real-time overhead at high sampling rates.

   PCT is most useful on Linux, FreeBSD, OpenBSD, and others for which both
   LD_PRELOAD and libitimer.so work.  All you need to do is set up $PCT and
   $LD_PRELOAD to track time in all program texts, shared libraries, and
   the kernel for entire process subtrees.  Well, getting kernel profiling on
   may be a bit of a trick (a reboot or maybe recompiling and rebooting might
   be needed).

   Using information in /proc or from 'ldd' and the working LD_PRELOAD, PCT
   can enable profiling (note in a totally retroactive fashion) on any
   dynamically-linked executable and trace through any shared libraries loaded
   on startup.  The utility of PC data may be poor for objects that have no
   symbols/debugging data.  [ Some very simple hacks to the Linux/*BSD kernels
   could also allow time spent in dynamically loadable modules to be tracked,
   but that is future work.  Some kernel or libc hacks could also allow a trap
   of the mprotect() call to dynamically add regions to the profiling system. ]

   Some PCT report generation scripts also require standard Unix utilities like
   'nm', 'sed' and 'grep'.  addr2line from the GNU binutils is very useful, but
   adb/gdb may be a substitute.  'nm -n' should be available on most systems,
   too.  Etc.  It's usually pretty obvious what is missing when it's not there.
   The scripts are quite short and easy to understand and modify.

5. Why do I get unresolved symbol errors when I use LD_PRELOAD=libprofil.so?

   Most likely you forgot to link your binary with "-Wl,-export-dynamic" or the
   equivalent for your OS.

   To know which region of virtual memory corresponds to your program text,
   libprofil.so must access the addresses of symbols which bound the text segment.
   Ordinarily 'ld' does not export the main text symbol table to shared
   libraries.  This is what -export-dynamic reverses.

   It would be nice if this could be made a gcc/ld default?  Hmm.

6. Why does my program take much more real-time to run when I enable PCT?

   The problem may be that the counter file resides on a network file system.
   Try using something like "PCT=o/tmp/test.pct".

   What is happening is that at each timer interrupt (every 1 ms .. 10 ms), the
   kernel updates one of the counters.  This can cause your program to sleep
   for 0.1 .. 10 ms, if the kernel must wait for the write to complete.  More
   recent network filesystems allow asynchronous updates and will likely be
   less suceptible to this effect.  Nevertheless, local filesystems like /tmp
   are always safe.

7. Is there a GNU/FSF/X Emacs mode for PCT output?

   Actually, grep mode just works when addr2line/line number data is available.
   Just run 'pct' instead of grep.  Depending on which grep mode we're talking
   about you might need pct ... | awk '{print $2 " " $1}'.
   
   When line number debugging data is not around, it would be nice to have a
   TAGS-like warping to function definitions.  This would probably have to rely
   on TAGS being around.  Anyways we aren't there yet....

8. Is there a Vim Tags or syntax mode for PCT output?

   Not yet, but it should not be very different from existing modes.
   As usual, volunteer work is highly appreciated...

9. Does PCT depend on C/C++/Scheme/Lisp/Ada/Java/Your Favorite Language.../?

   No.  Well, not exactly.  PCT can be used with any system that provides some
   way to map program counters to source locations.  This is usually synonymous
   with any language system that emits true object code and provides "source
   level debugging".

10. What is the history of PCT?  Is it based on any other package?

   PCT was inspired by a package called 'bprof' for Linux by Bas de Bakker,
   but not even one line of code is borrowed.  I had been using/hacking/porting
   bprof for going on 3 years.  I was continually annoyed at his use of C++,
   especially STL dependencies, inappropriate sbrk() usage, bad error checking,
   lack of portability, and many other limitations.

   I accrued a list of ideas for the ultimate profiling package.  I had a slow
   program to do congestion-based flow classification that I wanted to profile
   more.  Rather than apply bprof again, I took a break from hacking on that
   and wrote up the basic library-package in one very intense week of hacking.

   Debugger-based sampling occurred to me early on, but at first all I had were
   some gdb scripts.  Steve Bauer mostly figured out a clever fork following
   protocol, and did almost all the initial hacking on the config parser/dbctl.

11. What is the PCT copyright?  Can I use it free of charge?

   PCT is Copyright (C) Charles L. Blake, 2000, 2001, 2002.  You can use it
   free of charge.  It would be payment enough if every program in the world
   ran just a little bit faster.  You cannot, however, claim credit in any way,
   charge to redistribute the toolkit itself unless such distributions are also
   available for free via FTP or HTTP.  You cannot change it and redistribute
   it unless you make your changes available to people.  Standard GPL-like
   rules.  I may just put all this under a GPL.
