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

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

*

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

*

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

*

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

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

Opens a standard file selection dialog allowing you to select the directory containing oprofile samples. (See the description of the --samples-directory option above.)

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

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.

Opens a file selection dialog allowing you to select the an executable file to display. The initial directory displayed is the one identified 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.

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 available.)

Exit op_visualise.

Displays this manual.

Displays copyright and contact information.

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

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

The toolbar allows you to display data of various types.

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

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

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/executable pair.)

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

The histogram window graphically depicts the number of oprofile sample hits associated with each address contained in the selected executable. 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.