OP_VISUALISE(1) 														   OP_VISUALISE(1)

NAME

       op_visualise - graphically display and annotate	 oprofile sample files

SYNOPSIS

       op_visualise  [	-Sdirectory ] [ --samples-directory=directory ] [ -Bdirectory ] [ --binaries-directory=directory ] [ -sfile ] [ --samples-
       file=file ] [ -bfile ] [ --executable=file ] [ -ifile ] [ --initialisation-file=file ] [ -h ] [ --help ]

DESCRIPTION

       op_visualise is a tool that helps you visualise and interpret the data that oprofile collects.  Specifically, it:

       o Graphically represents, and allows interaction with, the oprofile sample count histogram.

       o Allows the histogram to be captured in various formats (such as Postscript).

       o Displays information relevant to selected addresses.  "OPTIONS DESCRIPTIONS"

       -S, --samples-directory=
	 Specifies the directory containing the oprofile samples.  Defaults to /var/lib/oprofile/samples.

       -B, --binaries-directory=
	 Specifies the root directory used to locate the executable file associated with a given sample file.  This defaults to / (root).   If	it
	 is set to any other directory name, that name is prepended to the filename associated with the sample file.  For example, if the option

	 -B /home/moller/bin-archive

	 is  specified	and  the  executable being sampled is /bin/bash, op_visualise will look for /home/moller/bin-archive/bin/bash.	This is to
	 allow multiple copies of executables to be archived for comparison and analysis.

       -s, --samples-file=
	 Specifies the oprofile sample file to be displayed.  The file is located as usual, that is, either absolutely, if it starts with a ``/'',
	 or  with  respect  to	the  current working directory otherwise.  op_visualise does not use the directory specified by the -S, --samples-
	 directory= option (or its default) to locate the sample file.	(The use of the --samples-directory= is described in the section  describ-
	 ing the Set Sample Dir...(C-d) menu.)

       -s, --executable=
	 Specifies  the  executable  file  against  which to apply the samples file.  Like the samples file this file is located as usual, without
	 respect to the directory specified by the -B, --binaries-directory= option (or its default), the use of which is described in the section
	 describing the Open Sample...(C-s) menu.

       -i, --initialisation-file=
	 Specifies  the  name of an initialisation file that can be used to set any of the above options.  The initialisation file consists of one
	 or more text lines in the form of:

	 tag : value

	 where tag is one of:

	 samples-directory

	 binaries-directory

	 samples-file

	 executable

	 and value is the value to be associated with that tag.

MAIN MENU

       The following is a description of the operations available under the main op_visualise menu.

   FILE MENU (M-F)
   SET	    SAMPLE DIR...(C-D)
       Opens a standard file selection dialog allowing you to select the directory containing oprofile	samples.   (See  the  description  of  the
       --samples-directory option above.)

   SET EXECUTABLES	ROOT...(C-R)
       Opens  a  standard  file  selection dialog allowing you to select the executable's root directory.  (See the description of the --binaries-
       directory option above.)

   OPEN      SAMPLE...(C-S)
       Opens a file selection dialog allowing you to select the an oprofile sample file to display.  The initial directory displayed  is  the  one
       identified by either the --samples-directory option or the Set Sample Dir...(C-d) menu.

       After a file is selected, another dialog will be presented asking if the corresponding binary file should be opened as well.

   SELECT      BINARY...(C-B)
       Opens a file selection dialog allowing you to select the an executable file to display.	The initial directory displayed is the one identi-
       fied by either the --binaries-directory option or the Set Executables Root...(C-r) menu.

       After a file is selected, another dialog will be presented asking if the corresponding samples file should be opened as well.

   PRINT      CHART...(C-P)
       Opens a dialog that allows you to capture the current histogram as an image in any of a number of formats, such as Postscript or GIF.  (The
       exact  options  will vary depending on what capabilities are installed; if no plot capabilities are installed, this menu will not be avail-
       able.)

   QUIT (C-Q)
       Exit op_visualise.

   HELP MENU (M-H)
   USAGE
       Displays this manual.

   ABOUT
       Displays copyright and contact information.

BUTTONS

   SAMPLES
       The Samples button is a shortcut to the Open Sample...(C-s) menu.  It is associated with a text label identifying the selected file.

   EXECUTABLES
       The Samples button is a shortcut to the Select Binary...(C-b) menu.  It is associated with a text label identifying the selected file.

TOOLBAR

       The toolbar allows you to display data of various types.

   FUNCTIONS
       The Functions button (denoted by a ``{}'' glyph) opens a dialog listing the functions that  make  up  the  executable  currently  selected.
       Selecting a function name will narrow the histogram display to include just that function.  (The button produces useful results only if the
       selected executable contains debugging information.)

   FILES
       The Files button (denoted by a ``File'' glyph) opens a dialog listing the files	that  compose  the  source  of	the  executable  currently
       selected.   Selecting a file name will narrow the histogram display to include just that file.  (The button produces useful results only if
       the selected executable contains debugging information.)

   SYSTEM
       The System button (denoted by a ``Filesystem'' glyph) opens a dialog listing the executables for  which	samples  exist	in  the  currently
       selected  samples  directory.   (Future	versions  of op_visualise may allow selection of any of the list entries to specify a samples/exe-
       cutable pair.)

STATUS LINE

       The status line displays errors or information relevant to the executable address associated with the current location of  the  pointer	in
       the histogram window.

HISTOGRAM WINDOW

       The  histogram  window  graphically  depicts the number of oprofile sample hits associated with each address contained in the selected exe-
       cutable.  As the pointer is moved within this window, the status line will show such information as the number of hits, the function  name,
       and  the  file  name  and line number associated with the address corresponding to the location of the pointer.	(The precise nature of the
       information presented depends on what is available in the executable.)

       The pointer buttons may be used to select the scope of the histogram.  Button 1 will zoom in by a factor of 2 around the current  location,
       button 3 will similarly zoom out, and button 2 will return the scope to encompass the entire executable.

								 14 February 2003						   OP_VISUALISE(1)