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)