[f0091e]: doc / oprofile.1.in  Maximize  Restore  History

Download this file

428 lines (421 with data), 11.9 kB

.TH OPROFILE 1 "@DATE@" "oprofile @VERSION@"
.UC 4
.SH NAME
oprofile \- a sytem-wide profiler
.SH SYNOPSIS
.br
.B opcontrol
[
.I options
]
.br
.B oprofpp
[
.I options
]
[ sample-file ] [ binary ]
.br
.B op_to_source
[
.I options
]
.br
.B op_time
[
.I options
]
[ samples-files-directory ]
.br
.B op_merge
[
.I options
]
[ samples-filenames or binary-filename]
.br
.B op_help
[ event-name ]
.br
.B oprof_convert
.br
.SH DESCRIPTION
oprofile is a profiling system for x86 systems running Linux 2.2/2.4. Profiling runs
transparently during the background, and profile data can be collected at any time. oprofile
makes use of the hardware performance counters provided on Intel P6, and AMD Athlon family processors,
and can use the RTC for profiling on othe x86 processor types.
In the following description, options that begin with ctrX- define a logical counter
number in the range 0-3 (0-1 for Intel processors, which only have two counters).
See the HTML documentation for further details.

.SH COMMONS OPTIONS
All utilities share the following options
.TP
.BI "--help -? --usage"
Show help message
.br
.TP
.BI "--version -v"
show version
.br
.SH OPTIONS
.br
.B opcontrol options
.br
.TP
.BI "--list-events"
Show available events for the hardware counters
.br
.TP
.BI "--init"
Loads the OProfile module if required and makes the OProfile driver
interface available.
.br
.TP
.BI "--setup"
Followed by list options for profiling set up. List of options
saved in /home/root/.oprofile/daemonrc.
.br
.TP
.BI "--start-daemon"
Start the oprofile daemon without starting profiling. Not available
in 2.2/2.4 kernels.
.br
.TP
.BI "--start"
Start data collection with either arguments provided by --setup
of information saved in /home/root/.oprofile/daemonrc.
.br
.TP
.BI "--dump"
Force a flush of the collected profiling data to the daemon.
.br
.TP
.BI "--stop"
Stop data collection.
.br
.TP
.BI "--shutdown"
Stop data collection and remove daemon.
.br
.TP
.BI "--reset"
Clears out data from current session, but leaves saved sessions.
.br
.TP
.BI "--save=" sessionname
Save data from current session to sessionname.
.br
.TP
.BI "--deinit"
Shuts down daemon. Unload the oprofile module and oprofilefs.
.br
.TP
.BI "--buffer-size=" num
Number of samples in kernel buffer.
.br
.TP
.BI "--ctrN-event=" name
Set counter N to measure symbolic event name.
.br
.TP
.BI "--ctrN-count=" val
Number of events between samples for counter N.
.br
.TP
.BI "--ctrN-unit-mask=" val
Set unit mask for counter N (e.g. --ctr0-unit-mask=0xf)
.br
.TP
.BI "--ctrN-kernel="[0|1]
Whether to count kernel events for counter N.
.br
.TP
.BI "--pid-filter=" pid
Only profile process pid  (only available for 2.4 version).
.br
.TP
.BI "--pgrp-filter=" pgrp
Only profile process tty group pgrp (only avilable for 2.4 version)
.br
.TP
.BI "--separate-samples"
Separate samples for each distinct application shared library.
.br
.TP
.BI "--vmlinux=" file
vmlinux kernel image.
.br
.TP
.BI "--verbose"
Be verbose in the daemon log.
.br
.TP
.BI "--kernel-range=" start,end
kernel range vma address in hexadecimal.
.TP
.br
.B oprofpp options
.br
.TP
.BI "--samples-file " filename ", -f "filename
image sample file
.br
.TP
.BI "--image-file " filename ", -i "filename
image file
.br
.TP
.BI "--list-symbols -l"
list samples by symbol
.br
.TP
.BI "--dump-gprof-file " filename ", -g "filename
dump gprof format file
.br
.TP
.BI "--list-symbol " name ", -s "name
give detailed samples for the symbol name
.br
.TP
.BI "--list-all-symbols-details -L"
give detailed samples for all symbols
.br
.TP
.BI "--output-linenr-info -o"
output filename:linenr info for all samples, usable only with --list-all-symbols-details, --list-symbol and --list-symbols
.br
.TP
.BI "--demangle -d"
demangle GNU C++ symbol names
.br
.TP
.BI "--counter " counter_nr ", -c "counter_nr
which counter to use
.br
.TP
.BI "--verbose -V"
verbose output
.br
.TP
.BI "--exclude-symbol " symbol ", -e "symbol
exclude list of comma separated symbol
.br
.TP
.BI "--show-shared-libs -k"
Show the details for each shared lib which belongs to one application. This option is useful only if you have profiled with --separate-samples option and you specify on the oprofpp command line either --list-symbols or --list-all-symbols-details.
.br
.TP
.BI "--reverse -r"
Sort the entries in reverse (only with -l)
.br
.TP
.BI "--output-format " vsSpPqQnlLiIh ", -t " vsSpPqQnlLiIdh
Specify the output format where a single format char is a field intended for: 'v' vma, 's' nr samples, 'S' nr cumulated samples, 'p' percent samples, 'P' cumulated percent samples, 'n' symbol name, 'l' source file name and line nr, 'L' ditto as 'l' but with basename of source file name, 'i' image name, 'I' ditto as 'i' but with base name of image name, 'd' details for each samples for the selected symbols and 'h' for the header itself. 'q','Q' are identical to 'p', 'P' but the percentage are relative to the total number of symbols. This option is not available with --dump-gprof-file.
.br
.TP
.BI "--session " session-name
Specify the session name you want to use, session-name can be an absolute path
where samples reside or a session name relative to samples files base directory. If you specify a samples filename with an absolute path this option is ignored
.TP
.br
.B op_to_source options
.br
.TP
.BI "--samples-file " filename ", -f "filename
image sample file
.br
.TP
.BI "--image-file " filename ", -i "filename
image file
.br
.TP
.BI "--demangle -d"
demangle GNU C++ symbol names
.br
.TP
.BI "--assembly -a"
output assembly code
.br
.TP
.BI "--source-dir " base_directory
if you request for annotated source this option give the base directory where
come the source file. All source file outside this base directory are ignored
.br
.TP
.BI "--output-dir " base_directory
output base directory where annotated source file are generated. If you do not
specify --source-dir neither --output-dir annotated source file go to stdout
.br
.TP
.BI "--output " patterns
if you request for annotated source this option give a list of patterns separated by "," so only source filename that match one of this pattern are output.
.br
.TP
.BI "--no-output " patterns
filename matched by the --output option can be filtered by one of the patterns given with this option.
.br
.TP
.BI "--source-with-assembly -s"
output assembly mixed with source file
.br
.TP
.BI "--until-more-than-samples " percent_nr ", -m "percent_nr
output source files until the amount of samples in these files reach percent_nr samples
.br
.TP
.BI "--with-more-than-samples " percent_nr ", -w "percent_nr
output source files which contains more than percent_nr samples
.br
.TP
.BI "--sort-by-counter " counter_nr ", -c "counter_nr
which counter to use for sorting purposes
.br
.TP
.BI "--verbose -V"
verbose output
.br
.TP
.BI "--exclude-symbol " symbol ", -e "symbol
exclude list of comma separated symbol
.br
.TP
.BI "--include-symbol " symbol ", -y "symbol
include list of comma separated symbol
.br
.TP
.BI "--session " session-name
Specify the session name you want to use, session-name can be an absolute path
where samples reside or a session name relative to samples files base directory. If you specify a samples
filename with an absolute path this option is ignored
.TP
.br
.TP
.BI "--objdump-params " 'params' ", -o "'params'
pass the comma separated additional parameters to objdump. Check the objdump man page
to see what options objdump accept e.g. -o '--disassembler-options=intel' to get Intel assembly syntax instead of att syntax.
This option can be used only with --assembly or --source-with-assembly
.br
.TP
.B op_time options [image_name [image_names]]
.br
.TP
.BI "--use-counter " counter_nr ", -c "counter_nr
which counter to use for sorting purposes
.TP
.br
.BI "--show-shared-libs -k"
Show the details for each shared lib which belongs to one application. This option is usefull only if you have profiled with --separate-samples option
.TP
.br
.BI "--list-symbols -l"
Show details for each symbols in each profiled files
.TP
.br
.BI "--demangle -d"
demangle GNU C++ symbol names
.br
.TP
.BI "--show-image-name -n"
show the image name when specifying --list-symbols
.br
.TP
.BI "--output-format " vsSpPnlLiIeEh ", -t " vsSpPnlLiIeEh
Specify the output format where a single format char is a field intended for: 'v' vma, 's' nr samples, 'S' nr cumulated samples, 'p' percent samples, 'P' cumulated percent samples, 'n' symbol name, 'l' source file name and line nr, 'L' ditto as 'l' but with basename of source file name, 'i' image name, 'I' ditto as 'i' but with base name of image name, 'e' application name, 'E' basename of application name 'e' and 'E' are useless unless you profile with --separate-samples, 'd' details for each samples for the selected symbols and 'h' for the header itself. This option is available only with --list-symbols
.br
.TP
.BI "--reverse -r"
sort output by increasing count of samples rather by decreasing count of samples
.br
.TP
.BI "--path " path name list ',' separated ", -p " path name list ',' separated
Specify an alternate list of pathname to locate image file. This is usefull if your samples files name does not match the image file name such as module loaded at boot time through a ram disk
.br
.TP
.BI "--recursive-path " path_list ',' separated ", -P " path_list ',' separated
Same as --path but retrieve recursively the image file name in the path list
.TP
.br
.BI "--session " session-name
Specify the session name you want to use, session-name can be an absolute path
where samples reside or a session name relative to samples files base directory
.TP
.br
.B op_merge options
.br
.TP
.BI "--use-counter " counter_nr ", -c "counter_nr
which counter to use for selecting filenames purposes

.SH USAGE
Setup and start the profiler with the provided
.B opcontrol
shell script. You are required to specify vmlinux, as well as specify a counter event and value, e.g. :
.PP
.I opcontrol --setup --vmlinux=/sys/vmlinux --ctr0-event=CPU_CLK_UNHALTED --ctr0-count=600000
.PP
If you are using a machine that doesn't support the performance counters, you can use the RTC driver instead, e.g. :
.PP
.I opcontrol --setup --vmlinux=/sys/vmlinux --rtc-value=128
.PP
Then actually start profiling with :
.PP
.I opcontrol --start
.PP
Profiles will be collected every ten minutes. You can force a collection at any time :
.PP
.I opcontrol --dump
.PP
Stopping profiling is done using
.PP
.I opcontrol --shutdown
.PP
which also flush all samples to disk.
.PP
As an alternative you can use the
.B oprof_start
gui to start the profiler. See the HTML documentation for further details
.PP
You can then collect profiles for any binary or shared library by using
.B oprofpp
to read the sample file :
.PP
.I oprofpp -l /lib/libc-2.1.92.so
.PP
or by using :
.B op_to_source
.PP
.I op_to_source -i /lib/libc-2.1.92.so
.PP
.B op_time
utility can be usefull to get an overall of all profiled applications.
.PP
.B op_merge
utility can be usefull to merge samples files which belongs to the same binary image
.PP
.SH ENVIRONMENT
No environment variables are recognised by oprofile.

.SH FILES
.TP
.I $HOME/.oprofile/
Configuration files
.TP
.I /var/lib/oprofile/oprofiled.log
The user-space daemon logfile.
.TP
.I /var/lib/oprofile/opdev, /var/lib/oprofile/ophashmapdev, /var/lib/oprofile/opnotedev
The device files for communication with the kernel module.
.TP
.I /var/lib/oprofile/samples/
The location of the generated sample files.

.SH VERSION
.TP
This man page is current for @PACKAGE@-@VERSION@.

.SH SEE ALSO
.BR gprof(1),
.BR readprofile(1),
.BR "Intel IA32 Architecture Developer's Manual, Volume 3"

.SH COPYRIGHT
oprofile is Copyright (C) 1998-2002 University of Manchester, UK, John Levon,
and others.
figurine is released under the GNU General Public License, Version 2,
or (at your option) any later version.
.SH AUTHORS
John Levon <levon@movementarian.org> is the primary author. See the documentation
for other contributors.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

JavaScript is required for this form.





No, thanks