unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



pixie(1)							     pixie(1)



NAME

  pixie	- Instruction-counting profiler	for optimization and coverage-
  analysis

SYNOPSIS

  pixie	[-pthread  | -threads] [pixie-option...] [prof-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

  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	pro-
  gram 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

  program
      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	pro-
      cedure 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.

  argument
      An argument needed by the	instrumented program to	execute	the pro-
      cedures, 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

  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 prof-
  options.)

  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


  Some or all of these options may be needed to	prevent	the instrumented pro-
  gram malfunctioning:

  -pthread
      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.

  -fork
      Specify -fork if the program calls any variant of	fork(2). It is not
      usually needed if	the subprocesses also call any variant of exec(2).
      The -fork	option ensures that forked multi-threaded programs are pro-
      filed in a thread-safe way, and it produces separate profiling data
      files for	the forked subprocesses, including the process id in their
      file names as if -pids was specified. Failure to use -fork might lead
      to deadlock in the forked	child processes.

      For compatibility	with earlier releases, a default level of fork sup-
      port is provided if the executable is non-shared or if libc.so is
      instrumented. However, this approach can lead to deadlock	and will be
      retired in a future release, so specifying -fork is recommended.

  -heapbase addr
      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.

  -sigdump signal
      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 -sig-
      dump TERM. Chose a signal	that the program does not use for another
      purpose.

  -E proc
      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.

  File Generating Options


  -quiet
      Prevents informational and progress messages from	being printed.

  -v  Prints the command lines used to instrument the program and to execute
      the instrumented program.

  -output file
      Names the	instrumented program file instead of the default
      program.pixie.

  -dirname path
      Specifies	the directory to which the instrumented	program	writes the
      profiling	data file(s) for each test run.	 The default is	the current
      directory.

  -pids
      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.

  -threads
      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 thread-safe profiling.If -sigdump is needed,
      -pthread is recommended instead of -threads, to avoid possible syn-
      chronization problems.

  Shared-Library Profiling Options


  -all
      Profiles all the shared libraries	in addition to the program's execut-
      able.

  -excobj lib
      If -all was specified, does not profile the shared library lib. Can be
      repeated,	to exclude multiple libraries.

  -incobj lib
      Profiles the shared library lib. Can be repeated to include multiple
      libraries.

  -Lpath
      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


  -run
      Executes the instrumented	program, even if no arguments are specified.
      By default, the program is just instrumented for later execution.

  -version
      Prints the tool's	version	number.

  -display
      Executes the instrumented	program, and runs prof with default options
      on the resulting .Counts file(s).

  prof-option
      Executes the instrumented	program, and runs prof on the resulting
      .Counts file(s). The following prof options are supported:

      -asm
	  Reports the profile as an annotated disassembly.

      -exclude proc
	  Excludes procedure proc from the profile, but	totals all pro-
	  cedures.

      -feedback	file
	  Generates file for cc	-feedback optimization.

      -heavy
	  Reports the lines that executed the most instructions.

      -invocations
	  Reports the callers of each procedure	executed.

      -lines
	  Reports the profile per source line within each procedure.

      -merge file
	  Merges all .Counts files into	file.

      -numbers
	  Prints each procedure's starting line	number.

      -only proc
	  Includes only	procedure proc in the profile, but totals all pro-
	  cedures.

      -Only proc
	  Includes only	procedure proc in the profile and in the total.

      -procedures
	  Profiles the instructions executed in	each procedure and the calls
	  to procedures.

      -quit n [[cum]%]
	  Truncates the	report after n lines or	after (cumulative) n percent
	  of the whole.

      -testcoverage
	  Reports lines	that were not executed.

      -totals
	  Profiles the whole executable	and any	shared libraries.

      -truecycles n
	  Estimates cycles, assuming cached memory (n=0-2).

      -update
	  Updates the original program executable (program) with the profil-
	  ing information, for use in future cc	-feedback program command(s).

      -zero
	  Reports procedures that were never called.

  Compatibility	Options


  This syntax (option names and	options	after program name) is recognized
  only if no other options and no program arguments are	specified, for compa-
  tibility with	DIGITAL	UNIX V3	and V4 systems:

  -[no]quiet
      [Permits]	or suppresses messages summarizing the binary-to-binary
      translation process. Default: -noquiet.

  -bbaddrs name
      Specifies	the name of the	basic block addresses file. Default:
      program.Addrs.

  -bbcounts name
      Specifies	the name of the	basic block counts file. Default:
      program.Counts.

  -[no]pids
      [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.

  -o file
      Specifies	the name of the	instrumented program. The default is to
      remove any leading directory names from program and append .pixie.

EXAMPLES

   1.  The pixie command can be	used to	instrument an executable program, run
       the instrumented	executable, and	store the resulting profiling infor-
       mation in the original executable. This process provides	profile-
       directed	feedback for the optimization phases of	future compiling and
       linking.	For example:
	    cc -non_shared -o program -feedback	program	-O3 *.c
	    pixie -update program
	    cc -non_shared -o program -feedback	program	-om -O3	*.c

       Forshared libraries, a similar technique	that records the profile in a
       separate	feedback file can be used. For example:
	    cc -o libexample.so	-shared	-g1 -O3	lib*.c
	    cc -o exerciser -O3	exerciser.c -L.	-lexample
	    pixie -L. -incobj libexample.so -run exerciser
	    prof -pixie	-feedback libexample.fb	libexample.so \
	      exerciser.Counts
	    cc -cord -feedback libexample.fb -o	libexample.so -shared \
	      -g1 -O3 lib*.c


   2.  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	cov-
       erage 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

  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 costs.

  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 Ver-
  sion 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 else-
  where, for example in	a disk partition with more space.

RESTRICTIONS

  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 instruc-
  tions, 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 pro-
  grams	executing on multiple processors that have different cycle speeds.
  The hiprof, uprofile,	and cc -p/-pg profilers	provide	better CPU-time	pro-
  files.

  The procedures in system libraries that are used by the POSIX	threads	pack-
  age are not profiled in multi-threaded programs.

  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 .Addrs and .Counts files
  are each several percent of the size of the program's	text segment.

FILES

  program.pixie
      Instrumented version of program produced by pixie

  program.Addrs
      Instruction-addresses file (for prof and optimizers) produced by pixie

  program.Counts[.pid][.sequence]
      Instruction-counts file produced by program.pixie

  lib*.so.instrumented-executable
      Instrumented shared libraries produced by	pixie

  .pixie.pid
      Temporary	file created and deleted in the	current	and -dirname path
      directories.

SEE ALSO

  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