'\" t .\" Title: perf-annotate .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 09/04/2026 .\" Manual: perf Manual .\" Source: perf .\" Language: Persian .\" .TH "PERF\-ANNOTATE" "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-annotate \- خواندن perf\&.data (ایجاد شده توسط perf record) و نمایش کد حاشیه‌نویسی‌شده .SH "خلاصه دستور (SYNOPSIS)" .sp .nf \fIperf annotate\fR [\-i | \-\-input=file] [symbol_name] .fi .SH "توضیحات (DESCRIPTION)" .sp این دستور فایل ورودی را می‌خواند و نسخه‌ای حاشیه‌نویسی‌شده از کد را نمایش می‌دهد\&. اگر فایل شیء دارای نمادهای اشکال‌زدایی (debug symbols) باشد، کد منبع در کنار کد اسمبلی نمایش داده خواهد شد\&. .sp اگر اطلاعات اشکال‌زدایی در فایل شیء موجود نباشد، کد اسمبلی حاشیه‌نویسی‌شده نمایش داده می‌شود\&. .SH "گزینه‌ها (OPTIONS)" .PP \-i, \-\-input= .RS 4 نام فایل ورودی\&. (پیش‌فرض: perf\&.data مگر اینکه stdin یک fifo باشد) .RE .PP \-d, \-\-dsos= .RS 4 تنها نمادهای موجود در این dsoها را در نظر بگیر\&. .RE .PP \-s, \-\-symbol= .RS 4 نمادی که باید حاشیه‌نویسی شود\&. .RE .PP \-f, \-\-force .RS 4 اعتبارسنجی مالکیت انجام نشود\&. .RE .PP \-v, \-\-verbose .RS 4 ارائه توضیحات بیشتر\&. (نمایش آدرس نماد و غیره) .RE .PP \-q, \-\-quiet .RS 4 هیچ هشدار یا پیامی نمایش داده نشود\&. (غیرفعال کردن \-v) .RE .PP \-n, \-\-show\-nr\-samples .RS 4 نمایش تعداد نمونه‌ها برای هر نماد\&. .RE .PP \-D, \-\-dump\-raw\-trace .RS 4 تخلیه داده‌های ردیابی خام در قالب ASCII\&. .RE .PP \-k, \-\-vmlinux= .RS 4 مسیر فایل vmlinux\&. .RE .PP \-\-ignore\-vmlinux .RS 4 نادیده گرفتن فایل‌های vmlinux\&. .RE .PP \-\-itrace .RS 4 گزینه‌هایی برای رمزگشایی داده‌های ردیابی دستورالعمل (instruction tracing)\&. گزینه‌ها عبارتند از: .sp .if n \{\ .RS 4 .\} .nf i تولید رویدادهای instructions y تولید رویدادهای cycles b تولید رویدادهای branches c تولید رویدادهای branches (فقط calls) r تولید رویدادهای branches (فقط returns) x تولید رویدادهای transactions w تولید رویدادهای ptwrite p تولید رویدادهای power (شامل رویدادهای PSB برای Intel PT) o تولید سایر رویدادهای ضبط‌شده بر اثر استفاده از aux\-output (به perf record مراجعه کنید) I تولید رویدادهای وقفه یا مشابه آن (ناهمگام) (مانند Intel PT Event Trace) e تولید رویدادهای error d ایجاد یک گزارش اشکال‌زدایی (debug log) f تولید رویدادهای حافظه پنهان سطح اول (first level cache) m تولید رویدادهای حافظه پنهان سطح آخر (last level cache) M تولید رویدادهای حافظه (memory) t تولید رویدادهای TLB a تولید رویدادهای دسترسی از راه دور (remote access) g تولید یک زنجیره فراخوانی (همراه با i یا x استفاده شود) G تولید یک زنجیره فراخوانی روی رکوردهای رویداد موجود l تولید ورودی‌های آخرین شاخه (همراه با i یا x استفاده شود) L تولید ورودی‌های آخرین شاخه روی رکوردهای رویداد موجود s رد کردن تعداد اولیه‌ای از رویدادها q رمزگشایی سریع‌تر (با جزئیات کمتر) A تقریب زدن IPC Z ترجیح دادن نادیده گرفتن برچسب‌های زمانی (رمزگشایی به‌اصطلاح "timeless") T استفاده از برچسب زمانی ردیابی به عنوان زمان هسته (kernel time) .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf حالت پیش‌فرض شامل تمام رویدادها است، یعنی معادل با \-\-itrace=iybxwpe، به جز برای perf script که در آن به صورت \-\-itrace=ce است .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf علاوه بر این، دوره (پیش‌فرض 100000، به جز برای perf script که در آن 1 است) برای رویدادهای instructions را می‌توان برحسب واحدهای زیر مشخص کرد: .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf i دستورالعمل‌ها (instructions) t تیک‌ها (ticks) ms میلی‌ثانیه (milliseconds) us میکروثانیه (microseconds) ns نانوثانیه (nanoseconds) (پیش‌فرض) .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf همچنین اندازه زنجیره فراخوانی (پیش‌فرض 16، حداکثر 1024) برای رویدادهای instructions یا transactions می‌تواند مشخص شود\&. .fi .if n \{\ .RE .\}.sp .if n \{\ .RS 4 .\} .nf همچنین می‌توان تعداد مدخل‌های آخرین شاخه (پیش‌فرض 64، حداکثر 1024) را برای رویدادهای instructions یا transactions مشخص کرد\&. .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf مشابه گزینه‌های g و l، می‌توان اندازه را برای گزینه‌های G و L نیز مشخص کرد\&. در x86، توجه داشته باشید که G و L هنگامی که داده‌ها با PEBS بزرگ ثبت شده باشند، عملکرد ضعیفی دارند\&. برای جزئیات به صفحه راهنمای linkperf:perf\-intel\-pt[1] مراجعه کنید\&. .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf همچنین این امکان وجود دارد که رویدادهای تولیدشده در ابتدا (instructions، branches، transactions، ptwrite، power) نادیده گرفته شوند\&. این برای نادیده گرفتن کدهای مقداردهی اولیه مفید است\&. .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf \-\-itrace=i0nss1000000 .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf یک میلیون دستورالعمل نخست را نادیده می‌گیرد\&. .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf گزینه \*(Aqe\*(Aq می‌تواند با پرچم‌هایی دنبال شود که بر گزارش شدن یا نشدن خطاها اثر می‌گذارند\&. هر پرچم باید با \*(Aq+\*(Aq یا \*(Aq\-\*(Aq همراه باشد\&. این پرچم‌ها عبارتند از: o سرریز (overflow) l از دست رفتن داده‌های ردگیری (trace data lost) .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf در صورت پشتیبانی، گزینه \*(Aqd\*(Aq می‌تواند با پرچم‌هایی همراه شود که بر ثبت شدن یا نشدن پیام‌های اشکال‌زدایی اثر می‌گذارند\&. هر پرچم باید با \*(Aq+\*(Aq یا \*(Aq\-\*(Aq همراه باشد\&. این پرچم‌ها عبارتند از: a همه رویدادهای perf e خروجی فقط هنگام بروز خطا (اندازه قابل پیکربندی \- ارجاع به linkperf:perf\-config[1]) o خروجی به stdout .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf در صورت پشتیبانی، گزینه \*(Aqq\*(Aq می‌تواند برای افزایش اثر تکرار شود\&. .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf برای غیرفعال کردن کامل رمزگشایی، از \-\-no\-itrace استفاده کنید\&. .fi .if n \{\ .RE .\} .RE .PP \-m, \-\-modules .RS 4 بارگذاری نمادهای ماژول\&. هشدار: فقط با \-k و هسته زنده (LIVE kernel) استفاده شود\&. .RE .PP \-l, \-\-print\-line .RS 4 چاپ خطوط منطبق در کد منبع (ممکن است کند باشد)\&. .RE .PP \-P, \-\-full\-paths .RS 4 نام مسیرهای نمایش‌داده‌شده کوتاه نشوند\&. .RE .PP \-\-stdio .RS 4 استفاده از رابط کاربری stdio\&. .RE .PP \-\-stdio2 .RS 4 استفاده از رابط کاربری stdio2، غیرتعاملی، با قالب‌بندی TUI\&. .RE .PP \-\-stdio\-color= .RS 4 \fIalways\fR، \fInever\fR یا \fIauto\fR؛ که امکان پیکربندی خروجی رنگی را علاوه بر "color\&.ui" در \&.perfconfig از طریق خط فرمان فراهم می‌کند\&. برای تولید رنگ حتی در زمان هدایت خروجی به یک لوله (pipe) یا فایل، از \fI\-\-stdio\-color always\fR استفاده کنید\&. استفاده از \fI\-\-stdio\-color\fR به‌تنهایی، معادل استفاده از \fIalways\fR\& است\&. .RE .PP \-\-tui .RS 4 استفاده از رابط کاربری TUI\&. استفاده از \-\-tui نیازمند یک tty است؛ اگر tty موجود نباشد، مانند زمان هدایت خروجی به دستورهای دیگر، از رابط stdio استفاده می‌شود\&. این رابط با تمرکز بر خط دارای بیشترین نمونه‌ها شروع به کار می‌کند؛ کلیدهای TAB/UNTAB میان خطوط با نمونه‌های بیشتر جابه‌جا می‌شوند\&. .RE .PP \-\-gtk .RS 4 استفاده از رابط کاربری GTK\&. .RE .PP \-C, \-\-cpu= .RS 4 تنها نمونه‌های مربوط به فهرست پردازنده‌های (CPUs) ارائه‌شده گزارش شوند\&. چندین پردازنده را می‌توان به صورت فهرستی جداشده با کاما و بدون فاصله مشخص کرد: 0,1\&. بازه‌های پردازنده با \- مشخص می‌شوند: 0\-2\&. حالت پیش‌فرض، گزارش نمونه‌ها روی تمام پردازنده‌ها است\&. .RE .PP \-\-asm\-raw .RS 4 نمایش کدگذاری خام دستورالعمل‌های اسمبلی\&. .RE .PP \-\-show\-total\-period .RS 4 نمایش ستونی از مجموع دوره‌ها (periods)\&. .RE .PP \-\-source .RS 4 درهم‌آمیزی کد منبع با کد اسمبلی\&. به طور پیش‌فرض فعال است، برای غیرفعال کردن از \-\-no\-source استفاده کنید\&. .RE .PP \-\-symfs= .RS 4 جستجوی فایل‌های حاوی نمادها به صورت نسبی نسبت به این دایرکتوری\&. چینش اختیاری (layout) می‌تواند \fIhierarchy\fR (پیش‌فرض، تطابق با مسیر کامل) یا \fIflat\fR (تنها تطابق با نام پایه) باشد\&. این گزینه زمانی مفید است که فایل‌های اشکال‌زدایی در یک ساختار دایرکتوری مسطح ذخیره شده باشند\&. .RE.PP \-M, \-\-disassembler\-style= .RS 4 تنظیم سبک واسرهم‌ساز (disassembler) برای objdump\&. .RE .PP \-\-addr2line= .RS 4 مسیر باینری addr2line\&. .RE .PP \-\-objdump= .RS 4 مسیر باینری objdump\&. .RE .PP \-\-prefix=PREFIX, \-\-prefix\-strip=N .RS 4 حذف N جزء نخست از نام مسیر فایل‌های منبع در فایل‌های اجرایی و افزودن PREFIX\&. این قابلیت امکان نمایش کد منبع کامپایل‌شده روی سیستم‌هایی با ساختار فایل‌سیستم متفاوت را فراهم می‌کند\&. .RE .PP \-\-skip\-missing .RS 4 رد کردن نمادهایی که امکان حاشیه‌نویسی آن‌ها وجود ندارد\&. .RE .PP \-\-group .RS 4 نمایش اطلاعات گروه رویداد در کنار هم .RE .PP \-\-demangle .RS 4 برگرداندن نام نمادها (demangle) به شکل خوانا برای انسان\&. این ویژگی به‌طور پیش‌فرض فعال است؛ با \-\-no\-demangle غیرفعال می‌شود\&. .RE .PP \-\-demangle\-kernel .RS 4 برگرداندن نام نمادهای هسته به شکل خوانا برای انسان (برای هسته‌های C++)\&. .RE .PP \-\-percent\-type .RS 4 تنظیم نوع درصد حاشیه‌نویسی از میان گزینه‌های زیر: global\-period، local\-period، global\-hits، local\-hits .sp .if n \{\ .RS 4 .\} .nf کلیدواژه‌های local/global مشخص می‌کنند که درصد در حوزهٔ تابع (local) محاسبه شود یا در کل داده‌ها (global)\&. کلیدواژه‌های period/hits پایه‌ای را که درصد بر مبنای آن محاسبه می‌شود تعیین می‌کنند \- دورهٔ نمونه‌ها یا تعداد نمونه‌ها (hits)\&. .fi .if n \{\ .RE .\} .RE .PP \-\-percent\-limit .RS 4 عدم نمایش توابعی که سربار (overhead) آن‌ها در stdio یا stdio2 کمتر از این درصد است (پیش‌فرض: 0)\&. توجه داشته باشید که این موضوع دربارهٔ انتخاب توابع جهت نمایش است، نه خطوط درون تابع\&. .RE .PP \-\-data\-type[=TYPE_NAME] .RS 4 نمایش حاشیه‌نویسی نوع داده به‌جای کد\&. این گزینه با استفاده از اطلاعات اشکال‌زدایی DWARF نوع دادهٔ نمونه‌ها را (اگر دستورالعمل‌های دسترسی به حافظه باشند) استنتاج می‌کند\&. این گزینه می‌تواند یک آرگومان اختیاری برای نام نوع داده دریافت کند\&. در این صورت حاشیه‌نویسی فقط برای آن نوع نمایش داده می‌شود؛ در غیر این صورت تمامی انواع داده‌های یافته‌شده نشان داده خواهند شد\&. .RE .PP \-\-type\-stat .RS 4 نمایش آمار برای حاشیه‌نویسی نوع داده\&. .RE .PP \-\-skip\-empty .RS 4 عدم نمایش رویدادهای خالی (یا ساختگی)\&. .RE .PP \-\-code\-with\-type .RS 4 نمایش اطلاعات نوع داده در حاشیه‌نویسی کد (تنها برای دستورالعمل‌های حافظه)\&. .RE.SH "همچنین ببینید (SEE ALSO)" .sp \fBperf-record\fR(1), \fBperf-report\fR(1)