'\" t
.\"     Title: perf-kvm
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 09/04/2026
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: Persian
.\"
.TH "PERF\-KVM" "1" "09/04/2026" "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-kvm \- ابزاری برای ردیابی و سنجش سیستم‌عامل مهمان kvm
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIperf kvm\fR [\-\-host] [\-\-guest] [\-\-guestmount=<path>
        [\-\-guestkallsyms=<path> \-\-guestmodules=<path> | \-\-guestvmlinux=<path>]]
        {top|record|report|diff|buildid\-list} [<options>]
\fIperf kvm\fR [\-\-host] [\-\-guest] [\-\-guestkallsyms=<path> \-\-guestmodules=<path>
        | \-\-guestvmlinux=<path>] {top|record|report|diff|buildid\-list|stat} [<options>]
\*(Aqperf kvm stat [record|report|live] [<options>]
.fi
.SH "توضیحات (DESCRIPTION)"
.sp
چندین حالت مختلف برای دستور perf kvm وجود دارد:
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm [options] top <command>\*(Aq برای تولید و نمایش بی‌درنگ
نمایهٔ شمارنده‌های کارایی سیستم‌عامل مهمان برای یک بار کاری دلخواه\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm record <command>\*(Aq برای ضبط نمایهٔ شمارنده‌های کارایی
یک بار کاری دلخواه و ذخیرهٔ آن در یک فایل دادهٔ perf\&. رفتار پیش‌فرض
دستور perf kvm به‌صورت \-\-guest تعیین شده است؛ بنابراین اگر هیچ‌کدام از گزینه‌های
\-\-host یا \-\-guest داده نشوند، نام فایل دادهٔ perf برابر با perf\&.data\&.guest خواهد بود\&.
اگر \-\-host داده شود، نام فایل داده perf\&.data\&.kvm خواهد بود\&. اگر می‌خواهید
داده‌ها در perf\&.data\&.host ذخیره شوند، لطفاً \-\-host \-\-no\-guest را مشخص کنید\&.
این رفتارها در زیر نشان داده شده‌اند:
  Default(\*(Aq\*(Aq)         \->  perf\&.data\&.guest
  \-\-host              \->  perf\&.data\&.kvm
  \-\-guest             \->  perf\&.data\&.guest
  \-\-host \-\-guest      \->  perf\&.data\&.kvm
  \-\-host \-\-no\-guest   \->  perf\&.data\&.host
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm report\*(Aq برای نمایش اطلاعات نمایهٔ شمارنده‌های کارایی
ضبط‌شده از طریق perf kvm record\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm diff\*(Aq برای نمایش تفاوت کارایی بین دو فایل perf\&.data
ضبط‌شده توسط perf record\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm buildid\-list\*(Aq برای نمایش buildidهای پیداشده در یک فایل دادهٔ perf،
تا سایر ابزارها بتوانند بسته‌هایی با جدول نمادهای منطبق را برای استفاده
توسط perf report دریافت کنند\&. از آنجا که buildid از مسیر /sys/kernel/notes
در سیستم‌عامل خوانده می‌شود، اگر می‌خواهید buildid را برای مهمان فهرست کنید،
لطفاً مطمئن شوید که فایل دادهٔ perf شما با گزینهٔ \-\-guestmount در perf kvm record
ضبط شده باشد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm stat <command>\*(Aq برای اجرای یک دستور و جمع‌آوری آمار
شمارنده‌های کارایی\&.
به‌ویژه، دستور \*(Aqperf kvm stat record/report\*(Aq یک تحلیل آماری از رویدادهای KVM
تولید می‌کند\&. در حال حاضر، رویدادهای vmexit، mmio (فقط x86) و ioport
(فقط x86) پشتیبانی می‌شوند\&. دستور \*(Aqperf kvm stat record <command>\*(Aq
رویدادهای kvm و رویدادهای میان شروع و پایان <command> را ضبط می‌کند\&.
همچنین این دستور فایلی تولید می‌کند که حاوی نتایج ردیابی رویدادهای kvm است\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm stat report\*(Aq داده‌های آماری را گزارش می‌دهد که شامل
sampleهای رویداد رسیدگی‌شده، percent_sample، time، percent_time، max_t، min_t و mean_t است\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
دستور \*(Aqperf kvm stat live\*(Aq داده‌های آماری را در حالت زنده گزارش می‌دهد (مشابه
record + report اما با به‌روزرسانی زندهٔ داده‌های آماری در یک نرخ نمایش مشخص)\&.
.fi
.if n \{\
.RE
.\}.SH "گزینه‌ها (OPTIONS)"
.PP
\-i, \-\-input=<path>
.RS 4
نام فایل ورودی برای زیرفرمان‌های
\fIreport\fR،
\fIdiff\fR
و
\fIbuildid\-list\fR\&.
.RE
.PP
\-o, \-\-output=<path>
.RS 4
نام فایل خروجی برای زیرفرمان
\fIrecord\fR\&.
با
\fIreport\fR
کار نمی‌کند، هنگام استفاده از
\fIreport\fR
کافی است خروجی را به یک فایل هدایت کنید\&.
.RE
.PP
\-\-host
.RS 4
جمع‌آوری پروفایل کارایی سمت میزبان (host)\&.
.RE
.PP
\-\-guest
.RS 4
جمع‌آوری پروفایل کارایی سمت مهمان (guest)\&.
.RE
.PP
\-\-guestmount=<path>
.RS 4
دایرکتوری نقطهٔ اتصال سیستم‌فایل ریشهٔ سیستم‌عامل مهمان\&. کاربران دایرکتوری‌های ریشهٔ سیستم‌عامل مهمان را از طریق یک روش دسترسی به سیستم‌فایل مشخص، معمولاً sshfs، در <path> متصل می‌کنند\&. برای نمونه، راه‌اندازی ۲ سیستم‌عامل مهمان که pid یکی 8888 و دیگری 9999 است:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-guestkallsyms=<path>
.RS 4
رونوشت فایل /proc/kallsyms سیستم‌عامل مهمان\&. دستور perf آن را برای دریافت نمادهای هستهٔ مهمان می‌خواند\&. کاربران آن را از سیستم‌عامل مهمان کپی می‌کنند\&.
.RE
.PP
\-\-guestmodules=<path>
.RS 4
رونوشت فایل /proc/modules سیستم‌عامل مهمان\&. دستور perf آن را برای دریافت اطلاعات ماژول‌های هستهٔ مهمان می‌خواند\&. کاربران آن را از سیستم‌عامل مهمان کپی می‌کنند\&.
.RE
.PP
\-\-guestvmlinux=<path>
.RS 4
فایل vmlinux هستهٔ سیستم‌عامل مهمان\&.
.RE
.PP
\-\-guest\-code
.RS 4
مشخص می‌کند که کد مهمان در فرایند ناظر (hypervisor) قابل یافتن است، که در برنامه‌های آزمایشی KVM یک حالت رایج است\&.
.RE
.PP
\-\-stdio
.RS 4
استفاده از رابط stdio\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
توضیحات بیشتر (نمایش خطاهای باز کردن شمارنده و غیره)\&.
.RE
.SH "گزینه‌های گزارش آماری (STAT REPORT OPTIONS)"
.PP
\-\-vcpu=<value>
.RS 4
تحلیل رویدادهایی که روی این vcpu رخ می‌دهند\&. (پیش‌فرض: تمام vcpuها)
.RE
.PP
\-\-event=<value>
.RS 4
رویدادی که باید تحلیل شود\&. مقادیر ممکن: vmexit، mmio (فقط در x86)، ioport (فقط در x86)\&. (پیش‌فرض: vmexit)
.RE
.PP
\-k, \-\-key=<value>
.RS 4
کلید مرتب‌سازی\&. مقادیر ممکن: sample (پیش‌فرض، مرتب‌سازی بر اساس تعداد نمونه‌ها)، percent_sample (مرتب‌سازی بر اساس درصد نمونه)، time (مرتب‌سازی بر اساس میانگین زمان)، precent_time (مرتب‌سازی بر اساس درصد زمان)، max_t (مرتب‌سازی بر اساس بیشینهٔ زمان)، min_t (مرتب‌سازی بر اساس کمینهٔ زمان)، mean_t (مرتب‌سازی بر اساس میانگین زمان)\&.
.RE
.PP
\-p, \-\-pid=
.RS 4
تحلیل رویدادها فقط برای شناسه(های) فرایند داده‌شده (فهرست جداشده با کاما)\&.
.RE.SH "گزینه‌های STAT LIVE (STAT LIVE OPTIONS)"
.PP
\-d, \-\-display
.RS 4
زمان بین به‌روزرسانی‌های نمایش بر حسب ثانیه\&.
.RE
.PP
\-m, \-\-mmap\-pages=
.RS 4
تعداد صفحات داده mmap (باید توانی از دو باشد) یا تعیین اندازه بر حسب بایت همراه با نویسه یکای پیوست‌شده \- B/K/M/G\&. این اندازه به نزدیک‌ترین مقدار صفحه که توانی از دو باشد به بالا گرد می‌شود\&.
.RE
.PP
\-a, \-\-all\-cpus
.RS 4
جمع‌آوری در سطح سراسر سیستم از تمام CPUها\&.
.RE
.PP
\-p, \-\-pid=
.RS 4
تحلیل رویدادها تنها برای شناسه(های) فرایند داده‌شده (فهرست جداشده با ویرگول)\&.
.RE
.PP
\-\-vcpu=<value>
.RS 4
تحلیل رویدادهایی که روی این vcpu رخ می‌دهند\&. (پیش‌فرض: تمام vcpuها)
.RE
.PP
\-\-event=<value>
.RS 4
رویدادی که باید تحلیل شود\&. مقادیر ممکن: vmexit، mmio (فقط x86)، ioport (فقط x86)\&. (پیش‌فرض: vmexit)
.RE
.PP
\-k, \-\-key=<value>
.RS 4
کلید مرتب‌سازی\&. مقادیر ممکن: sample (پیش‌فرض، مرتب‌سازی بر اساس تعداد نمونه‌ها)، time (مرتب‌سازی بر اساس میانگین زمان)\&.
.RE
.PP
\-\-duration=<value>
.RS 4
نمایش رویدادهایی به جز HLT (فقط x86) یا حالت Wait (فقط s390) که بیش از duration میکروثانیه طول می‌کشند\&.
.RE
.PP
\-\-proc\-map\-timeout
.RS 4
هنگام پردازش ریسه‌های از پیش موجود در /proc/XXX/mmap، ممکن است زمان زیادی صرف شود، زیرا ممکن است فایل بسیار حجیم باشد\&. در چنین مواردی به یک وقفه زمانی (timeout) نیاز است\&. این گزینه حد وقفه زمانی را تنظیم می‌کند\&. مقدار پیش‌فرض ۵۰۰ میلی‌ثانیه (500 ms) است\&.
.RE
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBperf-top\fR(1), \fBperf-record\fR(1), \fBperf-report\fR(1), \fBperf-diff\fR(1), \fBperf-buildid-list\fR(1), \fBperf-stat\fR(1)