*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> pixie (1)              



NAME    [Toc]    [Back]

       pixie - Instruction-counting profiler for optimization and

SYNOPSIS    [Toc]    [Back]

       pixie  [-pthread   |  -threads]  [pixie-option...]  [profoption...]
 program [argument...]

       pixie  -stats  dstride  [pixie-option...]  program  [argument...]

       See the start of the OPTIONS section below for details  of
       pixie options that may be essential for the correct execution
 of the program.

       Alternatively, for compatibility with earlier  Tru64  UNIX
       releases:   pixie   program  [-[no]quiet]  [-bbaddrs name]
       [-bbcounts name] [-[no]pids] [-o file]

       The atom -tool pixie interface  is  still  available,  for
       compatibility  with  earlier  releases. However, it is now
       undocumented, and it will be retired in a future  release.

DESCRIPTION    [Toc]    [Back]

       See  prof_intro(1)  for an introduction to the application
       performance tuning tools provided with Tru64 UNIX.

       The pixie command creates an  instrumented  version  of  a
       program  (program.pixie)  that  produces  a profile of the
       number of times each instruction  was  executed  during  a
       test  run of the instrumented program. If you specify program
 arguments (argument...)  or  -run,  the  instrumented
       program is executed too.

       If  you  specify  -display or any of the prof-options, the
       pixie command runs the instrumented program and then  runs
       the prof tool (with any specified prof-options) to display
       the profile or to save it in a choice of output file  formats.

       If  you omit the program name, a usage message is printed.

OPERANDS    [Toc]    [Back]

       File name of a fully linked call-shared or nonshared  executable
  to  be  profiled. This program should be compiled
       with the -g or -gn option (n>=1) to obtain  more  complete
       profiling  information.  If the default symbol table level
       (-g0) is used, line number information,  static  procedure
       names,  and file names are unavailable. Inlined procedures
       are always profiled as part of their callers, so test-coverage
  analysis  and  procedure-call  profiles may be more
       useful if inlining is disabled.Programs that are  stripped
       or are optimized by spike or cc -om are not supported.  An
       argument needed by the instrumented program to execute the
       procedures,  lines, and instructions of interest. Multiple
       arguments can be specified. They imply  -run  if  any  are
       specified,  and  they  can be replaced by -run if they are
       not otherwise needed.

OPTIONS    [Toc]    [Back]

       Options can be abbreviated to three characters, except the
       prof-options,  which  can  be  abbreviated (usually to one
       character) as in a prof  command.  For  example,  -qui  is
       interpreted as -quiet and -exc is -excobj, but -q is -quit
       and -e is -exclude. (See the -display option for the  supported

       For options that specify a procedure name (proc), C++ procedures
 can omit the argument type list, though this  will
       match  all overloaded procedures with that name. To select
       a specific procedure, specify the  full  symbol  name  (as
       printed  by  the  nm  command).  Symbol  names  containing
       spaces, *, and so on must be quoted.

   Essential Options    [Toc]    [Back]
       Some or all of these options may be needed to prevent  the
       instrumented  program  malfunctioning: Specify -pthread if
       the program or any of  its  libraries  calls  pthread_create(3)--for  example  if  it  was compiled with either the
       -pthread option or the -threads compatibility option. This
       will make the collection of profile data thread-safe.  The
       -fork option is maintained for compatibility with  earlier
       releases. By default, pixie now profiles subprocesses that
       do not call exec(2), and produces separate profiling  data
       files  for  the forked subprocesses, including the process
       id in their file names as  if  -pids  was  specified.   By
       default  the  pixie  code running in the program's process
       allocates memory for its own use at  address  38000000000.
       If the program needs to use memory between 38000000000 and
       3ff00000000, specify  the  hexadecimal  address  that  the
       pixie  code  should  use.   Specify  -sigdump to force the
       instrumented program to write the current profile data  to
       its  file(s)  on receipt of the named signal.  By default,
       the program writes the profiling data  file(s)  only  when
       the process terminates, but some processes never terminate
       normally, so this option lets you generate the file(s)  on
       demand. After a file is written, the instruction-counts of
       the profile are all set to zero, so by  sending  two  signals,
 any interval of a test run can be profiled, with the
       second signal's file(s) overwriting the first.  For  example,
  to  use  the  default kill pid command to signal the
       program, specify -sigdump TERM. Chose a  signal  that  the
       program  does  not  use  for  another  purpose.   Does not
       instrument the procedure proc, and excludes  its  instruction
  execution  count from the total for the program--for
       example, to exclude uninteresting procedures or procedures
       (such  as non-standard assembly code) that instrumentation
       would interfere with. If you tell  pixie  to  display  the
       profile, prof's -Exclude option is implied.

   Profiling Statistics Options    [Toc]    [Back]
       By default, pixie profiles the program as if -stats icount
       is specified; that is,  it  counts  how  many  times  each
       instruction is executed.

              The  alternative -stats dstride option analyzes the
              program's data access patterns, so that the resulting
  file  can  be  used  by spike(1) to drive data
              prefetch optimizations.  Only the -lite, -heapbase,
              -v, -output, -version, and -run options can be used
              with this kind of profiling.

   File Generating Options    [Toc]    [Back]
       Prevents informational and progress  messages  from  being
       printed.   Prints the command lines used to instrument the
       program and to execute the  instrumented  program.   Names
       the  instrumented program file instead of the default program.pixie.
  Specifies the directory to which the  instrumented
  program writes the profiling data file(s) for each
       test run. The default is the current directory.  Adds  the
       process-id  of  the instrumented program's test run to the
       name of the profiling data file produced  (that  is,  program.Counts.pid).
  By  default,  the  file  is  named program.Counts.
  When profiling a threaded  program,  specify
       -threads to produce a separate profile for each pthread in
       the    program.    The    files     are     named     program.Counts[.pid].sequence,
  where  sequence is the thread
       sequence  number  assigned   by   pthread_create(3).   The
       -threads  option  implies  the -pthread option for threadsafe
 profiling.If -sigdump is needed, -pthread  is  recommended
 instead of -threads, to avoid possible synchronization
 problems.  Modifies the -stats dstride option to profile
  faster but potentially less accurately.  It may help
       programs that cannot tolerate being  slowed  down  by  the
       profiling  code, but it may also reduce the amount of profile-directed
 optimization that is possible.

   Shared-Library Profiling Options    [Toc]    [Back]
       Profiles all the shared libraries in addition to the  program's
  executable.   If -all was specified, does not profile
 the shared library lib. Can be repeated,  to  exclude
       multiple  libraries.  Profiles the shared library lib. Can
       be repeated to include multiple libraries.   Searches  for
       shared-libraries  in  the named directory before searching
       the default directories. Can be repeated to make a  search
       path. Use the same options that were used when linking the
       program with ld.

   Execution Control Options    [Toc]    [Back]
       Prints the tool's version number.   Executes  the  instrumented
  program,  even  if  no arguments are specified. By
       default, the program is just instrumented for later execution.
   Executes  the  instrumented program, and runs prof
       with default options on the resulting  file(s).   Executes
       the  instrumented  program, and runs prof on the resulting
       file(s). The following prof options are supported: Reports
       the  profile as an annotated disassembly.  Excludes procedure
 proc from the profile,  but  totals  all  procedures.
       Generates file for cc -feedback optimization.  Reports the
       lines that executed the most  instructions.   Reports  the
       callers  of  each procedure executed.  Reports the profile
       per source line within each procedure.  Merges  all  files
       into  file.  Prints each procedure's starting line number.
       Includes only procedure proc in the  profile,  but  totals
       all  procedures.  Includes only procedure proc in the profile
 and in the total.  Profiles the instructions executed
       in  each procedure and the calls to procedures.  Truncates
       the report after n lines or after (cumulative)  n  percent
       of the whole.  Reports lines that were not executed.  Profiles
 the  whole  executable  and  any  shared  libraries.
       Estimates cycles, assuming cached memory (n=0-2).  Updates
       the original program executable (program) with the profiling
  information,  for  use in future cc -feedback program
       command(s).  Reports procedures that were never called.

   Compatibility Options    [Toc]    [Back]
       This syntax (option names and options after program  name)
       is  recognized  only  if  no  other options and no program
       arguments are specified, for  compatibility  with  DIGITAL
       UNIX  V3  and V4 systems: [Permits] or suppresses messages
       summarizing  the  binary-to-binary  translation   process.
       Default:  -noquiet.  Specifies the name of the basic block
       addresses file.  Default:  program.Addrs.   Specifies  the
       name  of  the  basic  block  counts  file.  Default:  program.Counts.
  [Disables] or enables the  addition  of  the
       process-id  number  to  the  filename  of  the basic block
       counts file. This is useful for collecting data for multiple
  invocations  of  the  instrumented  program. Default:
       -nopids.  Specifies the name of the instrumented  program.
       The  default is to remove any leading directory names from
       program and append

EXAMPLES    [Toc]    [Back]

       The pixie command can be used to instrument an  executable
       program,  run  the  instrumented executable, and store the
       resulting profiling information in a feedback  file.  This
       process  provides  profile-directed feedback for the optimization
 phases of future compiling and linking. For example:
  cc  -o  program -O3 *.c pixie -run program spike -fb
       program program

              See prof_intro(1) for additional  techniques.   The
              profile  produced  by the pixie command can also be
              used to verify that the test data has exercised all
              the  code-paths  that need to be most heavily optimized
 or tested. For example,  to  check  the  test
              coverage  for all the code in a multi-threaded program:
 cc -g1 -pthread -L.  -o  program  *.c  -lapp1
              -lapp2 pixie -pthread -L. -all -t program

NOTES    [Toc]    [Back]

       If   pixie   finds   any  previously  instrumented  shared
       libraries in the working directory, it will reuse them  if
       they  meet current requirements, to reduce re-instrumentation

       The prof command can also print  various  reports  showing
       how many times each instruction, source-line, or procedure
       was executed, but the cc -p, cc -pg, hiprof,  or  uprofile
       commands  can  produce  more accurate performance profiles
       because they reflect the effects of memory-access  delays.

       The  format of the data files produced by pixie changed in
       DIGITAL UNIX Version 4.0. To convert the data files to the
       industry-standard  format, use the pdtostd command, at the
       expense of losing profiles for shared libraries.

       Temporary instrumentation files are created in /tmp.   Set
       the  TMPDIR  environment variable to a different directory
       to create the files elsewhere, for example in a disk  partition
 with more space.

RESTRICTIONS    [Toc]    [Back]

       Although  the displayed profiles indicate units of cycles,
       they are not the actual number of cycles used by the  program,
 because they assume perfect memory access (for example,
 zero cache misses and access time). By  default,  the
       units are counts of instructions executed. With the -truecycles
 0|1|2 option, they reflect  the  number  of  cycles
       needed  by the particular instructions, but still assuming
       perfect memory.

       The total time in seconds that prof reports is inaccurate,
       because  memory access delays are not included and because
       pixie cannot account for programs  executing  on  multiple
       processors  that have different cycle speeds.  The hiprof,
       uprofile, and cc -p/-pg profilers provide better  CPU-time

       The  procedures  in  system libraries that are used by the
       POSIX threads package are not profiled  in  multi-threaded

       Approximate  performance estimates are as follows but will
       vary according to the application and  the  machine's  CPU
       count,  type,  and  clock  rate. The pixie instrumentation
       takes ~2s per Mb of program file on a 500-MHz EV6  (21264)
       Alpha  system,  using ~10 Mb of memory plus another ~15 Mb
       per Mb of the largest file.  The  instrumented  files  are
       ~2.5  times  the  size  of  the originals, plus ~0.5 Mb of
       pixie code. Non-threaded programs run  ~10  times  slower;
       threaded  programs may run ~20 times slower, or ~100 times
       slower with per-thread profiling.  The sizes of the  pixie
       and files are each several percent of the size of the program's
 text segment.

FILES    [Toc]    [Back]

       Instrumented version of program produced by pixie Instruction-addresses
  file (for prof and optimizers) produced by
       pixie Instruction-counts file  produced  by  program.pixie
       Instrumented  shared libraries produced by pixie Temporary
       file created and deleted in the current and -dirname  path

SEE ALSO    [Toc]    [Back]

       Introduction: prof_intro(1)

       atom(1),  cc(1),  dxprof(1),  fork(2), hiprof(1), kill(1),
       ld(1),  pdtostd(1),  prof(1),   pthread(3),   uprofile(1).
       (dxprof is available as an option.)

       Programmer's Guide

[ Back ]
 Similar pages
Name OS Title
prf IRIX operating system profiler
profiler IRIX UNIX system profiler
third Tru64 Third Degree: heap usage and leak profiler, and
hiprof Tru64 CPU-time and page-fault call-graph profiler for performance analysis
sema_init FreeBSD kernel counting semaphore
sema_wait FreeBSD kernel counting semaphore
sema FreeBSD kernel counting semaphore
sema_value FreeBSD kernel counting semaphore
sema_trywait FreeBSD kernel counting semaphore
sema_timedwait FreeBSD kernel counting semaphore
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service