'\" t
.\"     Title: perf-top
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 06/24/2012
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF_3.2\-TOP" "1" "06/24/2012" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-top \- System profiling tool\&.
.SH "SYNOPSIS"
.sp
.nf
\fIperf top\fR [\-e <EVENT> | \-\-event=EVENT] [<options>]
.fi
.SH "DESCRIPTION"
.sp
This command generates and displays a performance counter profile in real time\&.
.SH "OPTIONS"
.PP
\-a, \-\-all\-cpus
.RS 4
System\-wide collection\&. (default)
.RE
.PP
\-c <count>, \-\-count=<count>
.RS 4
Event period to sample\&.
.RE
.PP
\-C <cpu\-list>, \-\-cpu=<cpu>
.RS 4
Monitor only on the list of CPUs provided\&. Multiple CPUs can be provided as a comma\-separated list with no space: 0,1\&. Ranges of CPUs are specified with \-: 0\-2\&. Default is to monitor all CPUS\&.
.RE
.PP
\-d <seconds>, \-\-delay=<seconds>
.RS 4
Number of seconds to delay between refreshes\&.
.RE
.PP
\-e <event>, \-\-event=<event>
.RS 4
Select the PMU event\&. Selection can be a symbolic event name (use
\fIperf list\fR
to list all events) or a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a hexadecimal event descriptor\&.
.RE
.PP
\-E <entries>, \-\-entries=<entries>
.RS 4
Display this many functions\&.
.RE
.PP
\-f <count>, \-\-count\-filter=<count>
.RS 4
Only display functions with more events than this\&.
.RE
.PP
\-g, \-\-group
.RS 4
Put the counters into a counter group\&.
.RE
.PP
\-F <freq>, \-\-freq=<freq>
.RS 4
Profile at this frequency\&.
.RE
.PP
\-i, \-\-inherit
.RS 4
Child tasks inherit counters, only makes sens with \-p option\&.
.RE
.PP
\-k <path>, \-\-vmlinux=<path>
.RS 4
Path to vmlinux\&. Required for annotation functionality\&.
.RE
.PP
\-m <pages>, \-\-mmap\-pages=<pages>
.RS 4
Number of mmapped data pages\&.
.RE
.PP
\-p <pid>, \-\-pid=<pid>
.RS 4
Profile events on existing Process ID\&.
.RE
.PP
\-t <tid>, \-\-tid=<tid>
.RS 4
Profile events on existing thread ID\&.
.RE
.PP
\-r <priority>, \-\-realtime=<priority>
.RS 4
Collect data with this RT SCHED_FIFO priority\&.
.RE
.PP
\-s <symbol>, \-\-sym\-annotate=<symbol>
.RS 4
Annotate this symbol\&.
.RE
.PP
\-K, \-\-hide_kernel_symbols
.RS 4
Hide kernel symbols\&.
.RE
.PP
\-U, \-\-hide_user_symbols
.RS 4
Hide user symbols\&.
.RE
.PP
\-D, \-\-dump\-symtab
.RS 4
Dump the symbol table used for profiling\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose (show counter open errors, etc)\&.
.RE
.PP
\-z, \-\-zero
.RS 4
Zero history across display updates\&.
.RE
.PP
\-s, \-\-sort
.RS 4
Sort by key(s): pid, comm, dso, symbol, parent
.RE
.PP
\-n, \-\-show\-nr\-samples
.RS 4
Show a column with the number of samples\&.
.RE
.PP
\-\-show\-total\-period
.RS 4
Show a column with the sum of periods\&.
.RE
.PP
\-\-dsos
.RS 4
Only consider symbols in these dsos\&.
.RE
.PP
\-\-comms
.RS 4
Only consider symbols in these comms\&.
.RE
.PP
\-\-symbols
.RS 4
Only consider these symbols\&.
.RE
.PP
\-M, \-\-disassembler\-style=
.RS 4
Set disassembler style for objdump\&.
.RE
.PP
\-\-source
.RS 4
Interleave source code with assembly code\&. Enabled by default, disable with \-\-no\-source\&.
.RE
.PP
\-\-asm\-raw
.RS 4
Show raw instruction encoding of assembly instructions\&.
.RE
.PP
\-G [type,min,order], \-\-call\-graph
.RS 4
Display call chains using type, min percent threshold and order\&. type can be either:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
flat: single column, linear exposure of call chains\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
graph: use a graph tree, displaying absolute overhead rates\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
fractal: like graph, but displays relative rates\&. Each branch of the tree is considered as a new profiled object\&.
.sp
.if n \{\
.RS 4
.\}
.nf
order can be either:
\- callee: callee based call graph\&.
\- caller: inverted caller based call graph\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Default: fractal,0\&.5,callee\&.
.fi
.if n \{\
.RE
.\}
.RE
.RE
.SH "INTERACTIVE PROMPTING KEYS"
.PP
[d]
.RS 4
Display refresh delay\&.
.RE
.PP
[e]
.RS 4
Number of entries to display\&.
.RE
.PP
[E]
.RS 4
Event to display when multiple counters are active\&.
.RE
.PP
[f]
.RS 4
Profile display filter (>= hit count)\&.
.RE
.PP
[F]
.RS 4
Annotation display filter (>= % of total)\&.
.RE
.PP
[s]
.RS 4
Annotate symbol\&.
.RE
.PP
[S]
.RS 4
Stop annotation, return to full profile display\&.
.RE
.PP
[z]
.RS 4
Toggle event count zeroing across display updates\&.
.RE
.PP
[qQ]
.RS 4
Quit\&.
.RE
.sp
Pressing any unmapped key displays a menu, and prompts for input\&.
.SH "SEE ALSO"
.sp
\fBperf_3.2-stat\fR(1), \fBperf_3.2-list\fR(1)