profile.pl  -  a  Perl  script  to run profile experiments
       using pfmon


SYNOPSIS

       profile.pl [-n name] -c <cpulist> [-x <bitmask>] [-s skip]
       [-no_dplace] \
                  [-E  event]  [-N  number] [-S tmpfile] [-O pro­
       file] [-P prog] \
                  [-K] [-T seconds] [-L pidlist] [command] [args]


DESCRIPTION

       profile.pl  is a Perl script that provides a simple way to
       do procedure-level profiling of a program on a Linux  IA64
       system.   Symbol  information is required to be present in
       the program text -- profile.pl  does  not  produce  useful
       output on programs that have been processed by strip.

       While  profile.pl  is  designed to work with the SGI Altix
       3000 system, the only real dependency  profile.pl  has  on
       that  system is that profile.pl will use dplace to control
       binding of processes to processors.

       profile.pl will also work on Linux  IA64  systems  without
       dplace.    (See   below  under  Using  profile.pl  without
       dplace.)

       The simplest way to use profile.pl is as follows:

            profile.pl -c0-3 test_program

       In this case, it is assumed that the test_program  uses  4
       processes.   The  4  processes will be bound to processors
       0-3 (via dplace) and the program will  be  profiled  under
       control  of  pfmon.   The profile event will be CPU_CYCLES
       and the PMU will be set up to generate  approximately  100
       interrupts  per  second  (this  is  the  default event and
       rate).

       One can specify all of the normal dplace options  to  pro­
       file.pl.  Except for the -c option, they are not parsed by
       profile.pl and are merely handed along to dplace.  The  -c
       option  is  parsed so that profile.pl can tell pfmon which
       processors to monitor.  (The -c option must thus be speci­
       fied even if dplace is not used or available.)

       The  profile.pl  script  will  create  a  map  file (using
       makemap.pl) for test_program and  put  it  into  test_pro­
       gram.map.   The  profile  samples  themselves will go into
       sample.out.   The  analyzed  profile  will  go  into  pro­
       file.out.  (All of the names can be modified using options
       to profile.pl.)  The map file will not  be  created  again
       until it is deleted or test_program is updated.

       specify the "-x 6" option as well (to get dplace to ignore
       the  two  shepherd  processes that the OpenMP library cre­
       ates):

       profile.pl -c0-3 -x 6 test_program

       Program arguments can be supplied as follows:

       profile.pl -c0-3 test_program arg1 arg2 arg3 etc

       To make input or output redirection apply to  test_program
       only,  you  need  to put quotes around the program name as
       follows:

       profile.pl -c0-3 'test_program <input >output'

       otherwise the redirection applies to  profile.pl  instead,
       which is probably not what you wanted.

       profile.pl requires that pfmon, makemap.pl, and analyze.pl
       are all accessible in the current search path.

       profile.pl assumes that the file named System.map  in  the
       current  working  directory  is the correct System.map for
       the currently running kernel and will (by default) produce
       a  kernel  profile  as well as a profile for test_program.
       If there is no System.map  file  in  the  current  working
       directory,  then profile observations from the kernel will
       be thrown away during profile analysis.


OPTIONS

       Lowercase letter options are options  to  dplace  or  some
       other program that profile.pl calls; uppercase options are
       options to profile.pl.

       -c, -s, -n, -s, -p
              are all options as for dplace.  Of  these,  the  -c
              option  is  the  only option that is parsed by pro­
              file.pl.  (This is how profile.pl determines  which
              CPU's  to  profile).   The other dplace options are
              just handed through to dplace.  The  -p  option  is
              unimplemented in dplace or profile.pl at present.

       -c <cpulist>
              The  cpulist  is specified as a comma separate list
              of cpu ranges, e. g.: -c0,3-5,7,9,13-20.  These are
              absolute  cpu numbers (not relative to an enclosing
              cpuset.  See BUGS).

       -no_dplace
              Do not use dplace, even if it  is  present  on  the
              system.   (You  still need to specify the -c option
              to tell profile.pl which CPU's to profile.)

              is the event name  (as  specified  to  pfmon).   It
              defaults to CPU_CYCLES.  Use pfmon -l to get a list
              of events supported on this processor.

       -N number
              gives the number of events/profile  tick.   If  the
              event  being  measured is CPU_CYCLES, the number of
              events/profile tick defaults to 10000*cpuMHz  which
              implies   100   samples  per  second.   (cpuMHz  is
              obtained  from  /proc/cpuinfo)  The  default   only
              applies  to CPU_CYCLES; you must explicitly specify
              the number of events/profile tick if you  use  some
              other event.

              The  number of profile_ticks/second is the recipro­
              cal of the number of  events/profile_tick  as  fol­
              lows:

                profile_ticks/second   =   (event_rate/second)  /
              (events/profile_tick).

              So, if your event is CPU_CYCLES, and you specify  a
              value of '-N 10000000' on a 1 GHZ machine, then the
              profile_tick rate is 100 Hz:

                profile_ticks/second   =   (1000000000   Hz)    /
              (10000000) = 100 Hz.

              For  other  events,  you will need to determine the
              event_rate/second for your  application,  and  then
              determine  a events/profile_tick value that gives a
              reasonable number of profile_ticks/second.  Use  of
              pfmon in event counting mode can help in estimating
              the event_rate/second for your application.

       -S tmpfile
              gives  the  file  name  for  the  profile  samples.
              Defaults to sample.out.

       -O profile
              gives  the  file  name  for  the  analyzed profile.
              Defaults to profile.out.

       -P program
              If first word of command is not the program to pro­
              file,  use this option to specify the program name.

       -K     keep the separate per cpu sample files  around  and
              produce  a  separate  profile  report for each cpu.
              The file names for the intermediate files are based
              on  the  default  name  or as specified with the -S
              flag.  The file names for the profile results files
              are  based  on  the default name or as specified by

              in the file with suffix 'cpu.NN'.

       -T secs
              Run a timed profile experiment for the given number
              of seconds.  profile.pl will not  run  the  command
              under  control  of  pfmon.  (It is assumed the user
              will run the command  manually.)   The  program  to
              profile  is  either  given as the first word of the
              command or is specified by the -P option.

       -L pidlist
              pidlist is a comma separated list of  process  id's
              (containing  no blanks) This list will be passed to
              the profile analyzer and will restrict profiling to
              these process id's.  This is normally used with the
              -T option.

       'command'
              is the program  to  be  profiled.   Unless  the  -T
              option is specified, command will be run under con­
              trol of pfmon.  It will also be run under dplace if
              dplace   is   available   on  the  system  and  the
              -no_dplace option is not specified.  Command starts
              with  the first nonoption word on the command line.
              Use quotes around command to have input  or  output
              redirection apply only to the command.


NOTES

       The  above options allow you to profile on any performance
       monitor event that makes sense (e.  g.  IA64_INST_RETIRED,
       L3_MISSES,  L3_LINES_REPLACED,  L3_REFERENCES).   You will
       have to figure out, by trial  and  error,  what  value  to
       specify  for samples/tick (the -N option) to get a reason­
       able number of ticks per second for your application.

       profile.pl uses the following subsidiary scripts to create
       the  profile:  makemap.pl and analyze.pl.  makemap.pl cre­
       ates the map file  used  to  map  addresses  to  procedure
       names.   analyze.pl uses the map file and the profile sam­
       ples to create the actual profile.  In certain cases,  you
       may  wish  to  call  these  scripts directly.  See the man
       pages for these other scripts for further  information  on
       how to do this.


Using profile.pl without dplace

       pfmon  profiles everything that runs on each measured pro­
       cessor.  Use of the -c argument to profile.pl causes pfmon
       to  only  measure  those  processors.  However, profile.pl
       itself has no control of what runs  on  those  processors.
       Instead,  it  uses dplace (if it is present on the system)
       to bind processes to processors.  Implicit in  the  design
       of  profile.pl  is  the  assumption that only the measured
       program  runs  on  the  measured  processors  during   the


       However,  on a Linux IA64 system without dplace, there are
       two possible problems: (1) profile.pl has  no  idea  which
       processors your program will run on, and (2) the rule that
       only one particular program and process runs on each  pro­
       cessor  may  be violated.  To solve (1) in this case, pro­
       file.pl will tell pfmon to measure all of the  processors.
       However, your program may not use all of the processors in
       the system, or there may be periods of time when processes
       other  than the ones you wish to measure can be running on
       the measured processors.  As a result, the profile may  be
       nonsensical  (ticks  for  other programs, with a different
       map file will be mixed in with those of the measured  pro­
       gram,  and interpreted according to the program.map file).
       To get around this problem, you can tell analyze.pl  which
       process id's you want it to use (these are the process ids
       for the program you wish to measure) as follows:

            analyze.pl program.map sample.out PID1 PID2 PID3 etc
        or  analyze.pl program.map sample.out PID1,PID2,PID3,etc

       You can determine the process id's either by examining the
       sample.out file (the process id's are in the second column
       and the CPU numbers are in the third column -- it is  usu­
       ally  good  enough to use the most common process id's) or
       you can modify your test program to  print  out  the  PIDs
       (call  getpid()  and  print out the result, hopefully only
       once per process).

       If you are running a timed experiment,  (e.  g.  you  will
       start  the  processes  to be measured "by hand" instead of
       having profile.pl start them for you), then you can  some­
       times come up with the list of process id's before you run
       profile.pl (e. g. by running "top" in another  window  and
       writing  the process id's down by hand).  In this case you
       can specify the pid list to profile.pl with the -L option.
       All  that  happens  in  this  case is that the pid list is
       given to the analyzer during the analysis phase.

       An example of this might go something like the following:

       (1)    start up the program to be measured (we assume this
              will run for a long time)

       (2)    Manually get the list of process id's somehow.

       (3)    Run  profile.pl  to  do the measurement for 60 sec­
              onds, let us say:
              profile.pl -T 60 -P program_foo -L  pid,pid,pid  -O
              try1

       (4)    Repeat   the   above  for  a  different  60  second


       (5)    Terminate the test programs.


FILES

       /usr/bin/pfmon
       /usr/local/bin/profile.pl
       /usr/local/bin/makemap.pl
       /usr/local/bin/analyze.pl
       /usr/bin/dplace
       /proc/cpuinfo


BUGS

       Since profile.pl invokes pfmon in a way that causes  pfmon
       to create ASCII output files, the output files can grow to
       be quite large (gigabytes in size) if  an  event  rate  of
       1,000  HZ  is  specified and the profile is allowed to run
       for tens of minutes.  For such long  runs,  either  reduce
       the  event rate or run the program manually and use the -T
       option of profile.pl to run a profile that is shorter than
       the  entire run time of the program.  One can run multiple
       such experiments during the program run  and  use  the  -O
       option to name the profile output files appropriately.

       makemap.pl  is  normally  called by profile.pl; in certain
       cases profile.pl can't determine where the binary  of  the
       program  is,  or  doesn't  notice that the binary bas been
       modified and that makemap.pl needs to be rerun.  In  those
       cases, makemap.pl needs to be run manually.

       On  the  Altix  3000,  pfmon  is  NOT  currently cpumemset
       enabled.  So if you actually have an enclosing  cpumemset,
       then  pfmon  and dplace will be using different processors
       number.  So, for the moment, only use profile.pl when  the
       enclosing cpumemset is the default, global set.

       The  -N option has caused much confusion.  This is NOT the
       number of profile_ticks/second.  Rather it is the recipro­
       cal  of  the  number  of profile_ticks/second as discussed
       above.


SEE ALSO

       pfmon, makemap.pl, analyze.pl, dplace.


Man(1) output converted with man2html