pfmon - user interface to IPF Performance Monitoring Unit


SYNOPSIS

       pfmon  [-h | --help] [-V | --version] [-l[regex] | --show-
              event-list[=regex]]   [-i   <event>   |    --event-
              info=event]
              [-u  |  --user-level]  [-k  | --kernel-level] [-e |
              --events=ev1,ev2,...]   [-I  |  --info]   [--debug]
              [--verbose]
              [--outfile=filename]  [--append] [--overflow-block]
              [--system-wide] [--cpu-mask=0xn]
              [-S format | --smpl-output-info=format] [-t secs  |
              --session-timeout=secs] [--smpl-outfile=filename]
              [--smpl-entries=val]             [--long-smpl-peri­
              ods=val1,val2,...]              [--short-smpl-peri­
              ods=val1,val2,...]
              [--compact-smpl-output] [--raw-trace-file] [--with-
              header]      [--aggregate-results]       [--tigger-
              address=addr]
              [--priv-levels=lvl1,lvl2,...]  [--show-time] [--us-
              counter-format] [--eu-counter-format]
              [--hex-counter-format]   [--smpl-output-format=fmt]
              [--long-show-events[=regex]    [--symbol-file=file­
              name]
              [--sysmap-file=filename] [--check-events-only]
              [--smpl-periods-random=mask1:seed1,...]


DESCRIPTION

       pfmon is a performance monitoring  tool  that  provides  a
       user-level  interface  to  the Performance Monitoring Unit
       (PMU) built into the Itanium 2 [TM] (IPF) processor  chip.

       pfmon can be used to count or sample PMU events for unmod­
       ified binaries in its per-process mode and it can also  be
       used  to  run  system-wide monitoring sessions.  Pfmon can
       monitor activities happening at  the  user  and/or  kernel
       level for both type of sessions.  These counts and samples
       can be used to optimize program  performance  on  the  IPF
       processor.

       In per-process mode, pfmon can only monitor the first pro­
       cess (task).  Subsequent processes or threads  created  by
       that initial process will not be monitored.

       pfmon  can run on any IPF CPU model and provides the mini­
       mal features mandated by the architecture but it also pro­
       vides model specific extensions.  For instance, on Itanium
       2 pfmon has support for the EAR and BTB features.

       pfmon is based on a generic helper library  called  libpfm
       which  is  included  in  this package.  The library is not
       specific to pfmon and can be used directly by  other  pro­
       grams  as  is  demonstrated  in  the  set of examples also

       a  modular  architecture  which makes it easier to support
       new PMU models as they become available.


FURTHER DETAILS

       Further details on pfmon can be found in the  users  guide
       at /usr/share/doc/pfmon-1.1/pfmon_usersguide.txt.

       Further details on libpfm can be found on the man page for
       libpfm.

       Further details on the Itanium  2  PMU  can  be  found  in
       "Intel  Itanium 2 Processor Referenece Manual for Software
       Development and Optimization," available as  a  .pdf  file
       from www.intel.com.


OPTIONS

       -h, --help
              display the list of supported options

       -V, --version
              display pfmon version information

       -l[regex], --show-event-list[=regex]
              show list of supported events by host PMU

       -i <event>, --event-info=event
              get information about a particular event.

       -u, --user-level
              monitor  at  the  user  level for all events.  Per-
              event setting is possible with --priv-levels

       -k, --kernel-level
              monitor at the kernel level for all  events.   Per-
              event setting is possible with --priv-levels

       -e, --events=ev1,ev2,...
              select  events to monitor. There should be no space
              between the events.The number of  events  that  you
              can  specify  is  dependent  on  the underlying PMU
              model. Four events is typical.

       -I,--info
              list the compiled in PMU models supported by  pfmon
              and  detected  host  PMU as well as sampling output
              formats.

       --debug
              enable debug prints.

       --verbose
              print more information during execution.

              print counts in a file

       --append
              when used with --outfile, will  open  the  file  in
              append mode.

       --overflow-block
              do  not  block  the  monitored  program on overflow
              notifications (per process mode only).

       --system-wide
              create a system wide  monitoring  session.  Default
              session type is per process.

       --cpu-mask=0xn
              bitmask  indicating  on  which  CPU to start system
              wide monitoring. When this option is not specified,
              pfmon will monitor on all CPUs.

       -S format, --smpl-output-info=format
              display information about a sampling output format.

       -t secs, --session-timeout=secs
              duration of the session in seconds. In per  process
              mode,  the  process  will get killed if the timeout
              expires.

       --smpl-outfile=filename
              save sampling results in a file.

       --smpl-entries=val
              size of the sampling buffer in  number  of  entries
              default=2048).

       --long-smpl-periods=val1,val2,...
              set  sampling  periods  for  each  event after user
              level notification.

       --short-smpl-periods=val1,val2,...
              set sampling period for each event.

       --compact-smpl-output
              enable compact output for sampling results.

       --raw-trace-file
              enable raw output for sampling results.

       --with-header
              generate a machine description header with results.

       --aggregate-results
              aggregate  counts  and sampling buffer outputs when
              running system wide monitoring on multiple CPUs.

              start monitoring only when execution  reaches  addr
              (code) for the first time.

       --priv-levels=lvl1,lvl2,...
              set  privilege level per event. lvl can be any of u
              (user), k( kernel), uk (kernel & user). Unspecified
              events,  will get global setting which is user only
              by default.

       --show-time
              show real,user, and system time  for  the  executed
              command.

       --us-counter-format
              print counters using commas (1,024).

       --eu-counter-format
              print counters using points (1.024).

       --hex-counter-format
              print counters in hexadecimal (0x400).

       --smpl-output-format=fmt
              select  fmt  as  sampling  output format, use -L to
              list formats.  There is no default format,  so  you
              need  to  specify one each time you enable sampling
              via --long-smpl-periods or --short-smpl-periods.

       --long-show-events[=regex]
              display detailed information about matching  events
              in a single (easy grep)

       --symbol-file=filename
              use the ELF archive filename to look for symbols

       --sysmap-file=filename
              use the System.map filename to look for symbols

       --check-events-only
              check  that the event combination is valid and exit
              (no measurement)

       --smpl-periods-random=mask1:seed1,...
              apply randomization  to  long  and  short  periods.
              This  is  used to avoid sampling defects that occur
              if  some  system  process  has  the   same   period
              (exactly) as the long or short sampling intervales.
              (Note for: Altix 3000 see Bugs.)


DIAGNOSTICS

       The kernel perfmon susbsystem upon which pfmon depends  is
       built  into  the  Altix  3000 Linux Kernel by default (the
       option CONFIG_PERFMON is enabled is enabled  by  default).

       will fail with the message  "host  kernel  does  not  have
       perfmon support".

       If someone on the system has already started a system-wide
       performance monitoring session,  then  attempts  to  start
       another  system-wide session will result in the additional
       sessions failing with the error:  "concurrent  conflicting
       monitoring  session is present in your system".  Sometimes
       this error occurs because the previous monitoring  session
       did  not  close  down completely.  Try " killall pfmon" in
       this case to terminate the previous monitoring session.

       Numerous other diagnostics related to the specific  events
       and syntatic and semantic errors of the command invocation
       are also provided.


BUGS

       The --smpl-periods-random  option  requires  a  2.4.20  or
       later  kernel  and  is  not currently supported on the SGI
       Altix 3000 system.


SEE ALSO

       /usr/share/doc/pfmon-2.0/pfmon_usersguide.txt,    man    1
       libpfm

       man libpfm


AUTHOR

       Stephane  Eranian (eranian@hpl.hp.com) at Hewlett-Packard.


Man(1) output converted with man2html