'\" t
.\"     Title: perf-inject
.\"    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: English
.\"
.TH "PERF\-INJECT" "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-inject \- فیلتری برای تقویت جریان رویدادها با اطلاعات تکمیلی
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIperf inject <options>\fR
.fi
.SH "توضیحات (DESCRIPTION)"
.sp
دستور perf\-inject یک جریان رویداد perf\-record را می‌خواند و آن را مجدداً به stdout هدایت می‌کند\&. در هر نقطه‌ای کد پردازش می‌تواند رویدادهای دیگری را به جریان رویداد تزریق کند \- در این مورد build\-idها (گزینهٔ \-b) خوانده شده و در صورت نیاز به جریان رویداد تزریق می‌شوند\&.
.sp
شناسه‌های ساخت (Build\-idها) تنها نخستین استفاده از perf\-inject هستند \- بالقوه هر چیزی که برای تقویت جریان رویدادها با اطلاعات تکمیلی به پردازش در فضای کاربری نیاز دارد، می‌تواند از این قابلیت بهره ببرد\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\-b, \-\-build\-ids
.RS 4
تزریق build\-idهای DSOهایی که در نمونه‌ها رخ داده‌اند به جریان خروجی\&. این بدان معناست که برای یافتن DSOها باید همهٔ رکوردهای SAMPLE پردازش شوند\&.
.RE
.PP
\-\-buildid\-all
.RS 4
تزریق build\-idهای همهٔ DSOها به جریان خروجی صرف‌نظر از رخداد در نمونه‌ها، و چشم‌پوشی از پردازش SAMPLE\&.
.RE
.PP
\-\-known\-build\-ids=
.RS 4
بازنویسی و جایگزین کردن build\-idهای تزریقی با استفاده از این جفت‌های build\-id و مسیر جدا شده با کاما\&. از
\m[blue]\fBfile://filename\fR\m[]
برای خواندن این جفت‌ها از یک فایل (که می‌تواند توسط perf buildid\-list ایجاد شده باشد) پشتیبانی می‌کند\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
نمایش جزئیات بیشتر خروجی\&.
.RE
.PP
\-i, \-\-input=
.RS 4
نام فایل ورودی\&. (پیش‌فرض: stdin)
.RE
.PP
\-o, \-\-output=
.RS 4
نام فایل خروجی\&. (پیش‌فرض: stdout)
.RE
.PP
\-s, \-\-sched\-stat
.RS 4
ادغام sched_stat و sched_switch برای دریافت رویدادهای مربوط به محل و مدت زمان خوابیدن تسک‌ها\&. رویداد sched_switch شامل یک زنجیره فراخوانی (callchain) از محل به خواب رفتن تسک است و sched_stat شامل یک برش زمانی (timeslice) از مدت زمان خوابیدن تسک است\&.
.RE
.PP
\-k, \-\-vmlinux=<file>
.RS 4
مسیر فایل vmlinux
.RE
.PP
\-\-ignore\-vmlinux
.RS 4
نادیده گرفتن فایل‌های vmlinux\&.
.RE
.PP
\-\-kallsyms=<file>
.RS 4
مسیر فایل kallsyms
.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       سنتز آخرین مدخل‌های انشعاب (last branch) (استفاده همراه با i یا x)
L       سنتز آخرین مدخل‌های انشعاب روی رکوردهای رویداد موجود
s       صرف‌نظر کردن از تعداد اولیهٔ مشخصی از رویدادها
q       رمزگشایی سریع‌تر (با جزئیات کمتر)
A       تقریب IPC
Z       ترجیح بر نادیده گرفتن برچسب‌های زمانی (رمزگشایی اصطلاحاً "timeless")
T       استفاده از رد برچسب زمانی به‌عنوان زمان هسته
.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
همچنین می‌توان تعداد مدخل‌های آخرین انشعاب (پیش‌فرض ۶۴، حداکثر ۱۰۲۴) را برای
رویدادهای دستورالعمل‌ها (instructions) یا تراکنش‌ها (transactions) مشخص کرد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
مشابه گزینه‌های g و l، اندازه را می‌توان برای گزینه‌های G و L نیز تعیین کرد\&.
در x86، توجه داشته باشید که در صورت ثبت داده‌ها با PEBS بزرگ، گزینه‌های G و L عملکرد
ضعیفی دارند\&. برای جزئیات به صفحه راهنمای 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
.\}
.RE
.PP
\-\-strip
.RS 4
همراه با \-\-itrace برای حذف رویدادهای سنتز‌نشده (non\-synthesized) به کار می‌رود\&.
.RE
.PP
\-j, \-\-jit
.RS 4
پردازش فایل‌های jitdump با تزریق رکوردهای mmap متناظر با توابع کامپایل‌شده درجا (jitted)\&. این گزینه همچنین تصاویر ELF را برای هر تابع jitted یافت‌شده در فایل‌های jitdump ثبت‌شده در فایل ورودی perf\&.data ایجاد می‌کند\&. در صورتی که محیطی با زمان‌های اجرای JIT مانند Java، DART یا V8 را پایش می‌کنید، از این گزینه استفاده کنید\&.
.RE
.PP
\-f, \-\-force
.RS 4
شکایتی نکن، انجام بده\&.
.RE
.PP
\-\-vm\-time\-correlation[=OPTIONS]
.RS 4
برخی معماری‌ها ممکن است داده‌های ناحیه AUX را ضبط کنند که شامل برچسب‌های زمانی متأثر از مجازی‌سازی است\&. این گزینه آن برچسب‌های زمانی را درجا به‌روزرسانی می‌کند تا با برچسب‌های زمانی میزبان (host) همبستگی داشته باشند\&. به‌روزرسانی درجا بدین معناست که فایل خروجی مشخص نمی‌شود و در عوض فایل ورودی تغییر می‌یابد\&. گزینه‌ها مختص هر معماری هستند، با این استثنا که ممکن است با "dry\-run" آغاز شوند که باعث می‌شود فایل بدون به‌روزرسانی پردازش شود\&. در حال حاضر این گزینه فقط توسط Intel PT پشتیبانی می‌شود؛ مراجعه کنید به
\fBperf-intel-pt\fR(1)
.RE
.PP
\-\-guest\-data=<path>,<pid>[,<time offset>[,<time scale>]]
.RS 4
درج رویدادها از یک فایل perf\&.data که در یک ماشین مجازی ثبت شده، هم‌زمان با فایلی که در میزبان ضبط می‌شده است\&. شناسه فرایند (PID) فرایند ناظر مجازی‌سازی (hypervisor) QEMU باید ارائه شود، و احتمالاً به اختلاف زمان (time offset) و مقیاس زمان (time scale یا ضریب) برای تبدیل برچسب‌های زمانی مهمان به برچسب‌های زمانی میزبان نیاز خواهد بود\&. به عنوان مثال، در x86 می‌توان TSC Offset و Multiplier را برای یک ماشین مجازی که از گزینه خط فرمان لینوکس no\-kvmclock استفاده می‌کند فراهم کرد\&. در حال حاضر فقط رویدادهای mmap، mmap2، comm، task، context_switch، ksymbol و text_poke و همچنین اطلاعات build ID درج می‌شوند\&. گزینه QEMU با نام \-name debug\-threads=on مورد نیاز است تا بتوان از نام نخ‌ها برای تشخیص اینکه کدام نخ کدام VCPU را اجرا می‌کند بهره برد\&. توجه داشته باشید که به نظر می‌رسد libvirt به‌طور پیش‌فرض از این گزینه استفاده می‌کند\&. هنگام استفاده از perf record در مهمان، باید گزینه \-\-sample\-identifier استفاده شود، و همچنین گزینه‌های \-\-buildid\-all و \-\-switch\-events نیز ممکن است مفید باشند\&.
.RE
.PP
\-\-convert\-callchain
.RS 4
تجزیه زنجیره‌های فراخوانی DWARF و تبدیل آن‌ها به زنجیره‌های فراخوانی معمول\&. این کار همچنین داده‌های پشته و ثبات‌ها (registers) را از نمونه‌ها حذف می‌کند\&. این عمل باعث از دست رفتن مدخل‌های زنجیره فراخوانی درخط (inlined) خواهد شد\&.
.RE
.PP
\-\-guestmount=<path>
.RS 4
دایرکتوری نقطه اتصال (mount) سیستم‌فایل ریشه سیستم‌عامل مهمان\&. کاربران دایرکتوری‌های ریشه سیستم‌عامل مهمان را تحت <path> با یک روش دسترسی ویژه به سیستم‌فایل، معمولاً sshfs متصل می‌کنند\&. به عنوان مثال، اجرای ۲ سیستم‌عامل مهمان که pid یکی ۸۸۸۸ و دیگری ۹۹۹۹ است:
.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 inject \-\-guestmount=~/guestmount 
.fi
.if n \{\
.RE
.\}
.RE.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBperf-record\fR(1), \fBperf-report\fR(1), \fBperf-archive\fR(1), \fBperf-intel-pt\fR(1)