diff options
Diffstat (limited to 'tools/perf/Documentation/perf-kvm.txt')
| -rw-r--r-- | tools/perf/Documentation/perf-kvm.txt | 132 |
1 files changed, 95 insertions, 37 deletions
diff --git a/tools/perf/Documentation/perf-kvm.txt b/tools/perf/Documentation/perf-kvm.txt index 326f2cb333cb..c26524d38f47 100644 --- a/tools/perf/Documentation/perf-kvm.txt +++ b/tools/perf/Documentation/perf-kvm.txt @@ -10,9 +10,10 @@ SYNOPSIS [verse] 'perf kvm' [--host] [--guest] [--guestmount=<path> [--guestkallsyms=<path> --guestmodules=<path> | --guestvmlinux=<path>]] - {top|record|report|diff|buildid-list} + {top|record|report|diff|buildid-list} [<options>] 'perf kvm' [--host] [--guest] [--guestkallsyms=<path> --guestmodules=<path> - | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} + | --guestvmlinux=<path>] {top|record|report|diff|buildid-list|stat} [<options>] +'perf kvm stat [record|report|live] [<options>] DESCRIPTION ----------- @@ -23,10 +24,17 @@ There are a couple of variants of perf kvm: of an arbitrary workload. 'perf kvm record <command>' to record the performance counter profile - of an arbitrary workload and save it into a perf data file. If both - --host and --guest are input, the perf data file name is perf.data.kvm. - If there is no --host but --guest, the file name is perf.data.guest. - If there is no --guest but --host, the file name is perf.data.host. + of an arbitrary workload and save it into a perf data file. We set the + default behavior of perf kvm as --guest, so if neither --host nor --guest + is input, the perf data file name is perf.data.guest. If --host is input, + the perf data file name is perf.data.kvm. If you want to record data into + perf.data.host, please input --host --no-guest. The behaviors are shown as + following: + Default('') -> perf.data.guest + --host -> perf.data.kvm + --guest -> perf.data.guest + --host --guest -> perf.data.kvm + --host --no-guest -> perf.data.host 'perf kvm report' to display the performance counter profile information recorded via perf kvm record. @@ -36,63 +44,113 @@ There are a couple of variants of perf kvm: 'perf kvm buildid-list' to display the buildids found in a perf data file, so that other tools can be used to fetch packages with matching symbol tables - for use by perf report. + for use by perf report. As buildid is read from /sys/kernel/notes in os, then + if you want to list the buildid for guest, please make sure your perf data file + was captured with --guestmount in perf kvm record. 'perf kvm stat <command>' to run a command and gather performance counter statistics. Especially, perf 'kvm stat record/report' generates a statistical analysis - of KVM events. Currently, vmexit, mmio and ioport events are supported. - 'perf kvm stat record <command>' records kvm events and the events between - start and end <command>. + of KVM events. Currently, vmexit, mmio (x86 only) and ioport (x86 only) + events are supported. 'perf kvm stat record <command>' records kvm events + and the events between start and end <command>. And this command produces a file which contains tracing results of kvm events. 'perf kvm stat report' reports statistical data which includes events - handled time, samples, and so on. + handled sample, percent_sample, time, percent_time, max_t, min_t, mean_t. + + 'perf kvm stat live' reports statistical data in a live mode (similar to + record + report but with statistical data updated live at a given display + rate). OPTIONS ------- -i:: ---input=:: - Input file name. +--input=<path>:: + Input file name, for the 'report', 'diff' and 'buildid-list' subcommands. -o:: ---output:: - Output file name. ---host=:: +--output=<path>:: + Output file name, for the 'record' subcommand. Doesn't work with 'report', + just redirect the output to a file when using 'report'. +--host:: Collect host side performance profile. ---guest=:: +--guest:: Collect guest side performance profile. ---guestmount=<path>:: - Guest os root file system mount directory. Users mounts guest os - root directories under <path> by a specific filesystem access method, - typically, sshfs. For example, start 2 guest os. The one's pid is 8888 - and the other's is 9999. - #mkdir ~/guestmount; cd ~/guestmount - #sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/ - #sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/ - #perf kvm --host --guest --guestmount=~/guestmount top ---guestkallsyms=<path>:: - Guest os /proc/kallsyms file copy. 'perf' kvm' reads it to get guest - kernel symbols. Users copy it out from guest os. ---guestmodules=<path>:: - Guest os /proc/modules file copy. 'perf' kvm' reads it to get guest - kernel module information. Users copy it out from guest os. ---guestvmlinux=<path>:: - Guest os kernel vmlinux. + +:GMEXAMPLECMD: kvm --host --guest +:GMEXAMPLESUBCMD: top +include::guest-files.txt[] + +--stdio:: Use the stdio interface. + +-v:: +--verbose:: + Be more verbose (show counter open errors, etc). STAT REPORT OPTIONS ------------------- --vcpu=<value>:: - analyze events which occures on this vcpu. (default: all vcpus) + analyze events which occur on this vcpu. (default: all vcpus) + +--event=<value>:: + event to be analyzed. Possible values: vmexit, mmio (x86 only), + ioport (x86 only). (default: vmexit) +-k:: +--key=<value>:: + Sorting key. Possible values: sample (default, sort by samples + number), percent_sample (sort by sample percentage), time + (sort by average time), precent_time (sort by time percentage), + max_t (sort by maximum time), min_t (sort by minimum time), mean_t + (sort by mean time). +-p:: +--pid=:: + Analyze events only for given process ID(s) (comma separated list). + +STAT LIVE OPTIONS +----------------- +-d:: +--display:: + Time in seconds between display updates + +-m:: +--mmap-pages=:: + Number of mmap data pages (must be a power of two) or size + specification in bytes with appended unit character - B/K/M/G. + The size is rounded up to the nearest power-of-two page value. + +-a:: +--all-cpus:: + System-wide collection from all CPUs. + +-p:: +--pid=:: + Analyze events only for given process ID(s) (comma separated list). + +--vcpu=<value>:: + analyze events which occur on this vcpu. (default: all vcpus) ---events=<value>:: - events to be analyzed. Possible values: vmexit, mmio, ioport. + +--event=<value>:: + event to be analyzed. Possible values: vmexit, + mmio (x86 only), ioport (x86 only). (default: vmexit) + -k:: --key=<value>:: Sorting key. Possible values: sample (default, sort by samples number), time (sort by average time). +--duration=<value>:: + Show events other than HLT (x86 only) or Wait state (s390 only) + that take longer than duration usecs. + +--proc-map-timeout:: + When processing pre-existing threads /proc/XXX/mmap, it may take + a long time, because the file may be huge. A time out is needed + in such cases. + This option sets the time out limit. The default value is 500 ms. + SEE ALSO -------- linkperf:perf-top[1], linkperf:perf-record[1], linkperf:perf-report[1], |