نام (NAME)

perf-list - فهرست کردن تمامی انواع نمادین رویدادها

خلاصه دستور (SYNOPSIS)

perf list [<options>]
            [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]

توضیحات (DESCRIPTION)

این دستور انواع رویدادهای نمادینی را نمایش می‌دهد که می‌توان آن‌ها را در دستورهای گوناگون perf با گزینهٔ -e انتخاب کرد.

گزینه‌ها (OPTIONS)

-d, --desc

--no-desc

-v, --long-desc

--debug

--details

--deprecated

--unit

-j, --json

-o, --output=

تغییردهنده‌های رویداد (EVENT MODIFIERS)

رویدادها می‌توانند با افزودن یک دونقطه و یک یا چند تغییردهنده، به‌صورت اختیاری یک تغییردهنده داشته باشند. تغییردهنده‌ها به کاربر امکان می‌دهند رویدادهایی که شمارش می‌شوند را محدود کند. تغییردهنده‌های زیر وجود دارند:

u - شمارش در فضای کاربری (user-space)
k - شمارش در هسته (kernel)
h - شمارش در هایپروایزر (hypervisor)
I - شمارش در زمان غیربیکار (non-idle)
G - شمارش در مهمان (در مهمان‌های KVM)
H - شمارش در میزبان (خارج از مهمان‌های KVM)
p - سطح دقت (precise level)
P - استفاده از حداکثر سطح دقت شناسایی‌شده
S - خواندن مقدار نمونه (PERF_SAMPLE_READ)
D - سنجاق کردن رویداد به PMU
W - گروه ضعیف است و در صورت غیرقابل‌زمان‌بندی بودن به حالت غیرگروهی بازمی‌گردد،
e - گروه یا رویداد انحصاری هستند و PMU را به اشتراک نمی‌گذارند
b - استفاده از تجمیع BPF (نگاه کنید به perf stat --bpf-counters)
R - مقدار تأخیر بازنشستگی (retire latency) رویداد
X - عدم گروه‌بندی مجدد رویداد برای تطابق با PMUها

تغییردهندهٔ p می‌تواند برای تعیین میزان دقت نشانی دستورالعمل استفاده شود. تغییردهندهٔ p می‌تواند چندین بار مشخص شود:

0 - مقدار SAMPLE_IP می‌تواند لغزش (skid) اختیاری داشته باشد
1 - مقدار SAMPLE_IP باید لغزش ثابت داشته باشد
2 - برای SAMPLE_IP درخواست شده که لغزش ۰ داشته باشد
3 - مقدار SAMPLE_IP باید لغزش ۰ داشته باشد، یا از تصادفی‌سازی برای جلوگیری
    از اثرات سایه‌اندازی نمونه (sample shadowing) استفاده کند.

برای سامانه‌های Intel نمونه‌برداری دقیق رویداد با PEBS پیاده‌سازی شده است که تا سطح دقت ۲، و برای برخی موارد خاص تا سطح دقت ۳ را پشتیبانی می‌کند.

در سامانه‌های AMD این قابلیت با استفاده از IBS OP (تا سطح دقت ۲) پیاده‌سازی شده است. بر خلاف Intel PEBS که سطوحی از دقت را فراهم می‌کند، PMU هستهٔ AMD ذاتاً غیردقیق است و IBS ذاتاً دقیق است. (یعنی ibs_op//، ibs_op//p، ibs_op//pp و ibs_op//ppp همگی یکسان هستند). تغییردهندهٔ precise با انواع رویداد 0x76 (cpu-cycles، کلاک‌های متوقف‌نشدهٔ CPU) و 0xC1 (micro-ops retired) کار می‌کند. هر دو رویداد به نمونه‌برداری اجرای IBS (یا IBS op) به‌ترتیب با تنظیم بیت کنترل شمارندهٔ IBS Op (IbsOpCntCtl) نگاشت می‌شوند (بخش Core Complex (CCX) → Processor x86 Core → Instruction Based Sampling (IBS) از [AMD Processor Programming Reference (PPR)] مرتبط با خانواده، مدل و stepping پردازندهٔ مورد استفاده را ببینید).

Manual Volume 2: System Programming, 13.3 Instruction-Based Sampling). مثال‌هایی برای استفاده از IBS:

perf record -a -e cpu-cycles:p ...    # use ibs op counting cycles
perf record -a -e r076:p ...          # same as -e cpu-cycles:p
perf record -a -e r0C1:p ...          # use ibs op counting micro-ops

حتی زمانی که یک رویداد در حال حاضر به‌صورت نمادین در perf در دسترس نباشد، می‌توان آن را به شیوه‌ای ویژه و متناسب با هر پردازنده کدگذاری کرد.

برای نمونه در پردازنده‌های x86، مقدار N یک مقدار هگزادسیمال است که کدگذاری خام ثبات را طبق چیدمان MSRهای IA32_PERFEVTSELx (نگاه کنید به [Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3B: System Programming Guide] شکل 30-1 چیدمان MSRهای IA32_PERFEVTSELx) یا MSRهای PERF_CTL متعلق به AMD (نگاه کنید به بخش Core Complex (CCX) → Processor x86 Core → MSR Registers در [AMD Processor Programming Reference (PPR)] متناسب با خانواده، مدل و stepping پردازنده مورد استفاده) نشان می‌دهد.

نکته: در ثبات‌های شمارنده x86 تنها فیلدهای بیتی زیر قابل تنظیم هستند: event،‏ umask،‏ edge،‏ inv،‏ cmask. به‌ویژه، پرچم‌های guest/host only و OS/user mode باید با استفاده از EVENT MODIFIERS تنظیم شوند.

مثال:

اگر اسناد Intel برای یک Core i7 QM720 رویدادی را به این شکل شرح دهند:

Event  Umask  Event Mask
Num.   Value  Mnemonic    Description                        Comment

A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
                          delivered by loop stream detector  invert to count
                                                             cycles

می‌توان از کدگذاری خام 0x1A8 استفاده کرد:

perf stat -e r1a8 -a sleep 1
perf record -e r1a8 ...

همچنین امکان استفاده از نحو pmu وجود دارد:

perf record -e r1a8 -a sleep 1
perf record -e cpu/r1a8/ ...
perf record -e cpu/r0x1a8/ ...

برخی پردازنده‌ها، مانند پردازنده‌های AMD، از کدهای رویداد و unit maskهای بزرگ‌تر از یک بایت پشتیبانی می‌کنند. در چنین مواردی، بیت‌های متناظر با پارامترهای پیکربندی رویداد را می‌توان با دستور زیر مشاهده کرد:

cat /sys/bus/event_source/devices/<pmu>/format/<config>

مثال:

اگر اسناد AMD برای یک پردازنده EPYC 7713 رویدادی را این‌گونه شرح دهند:

Event  Umask  Event Mask
Num.   Value  Mnemonic                        Description

28FH     03H  op_cache_hit_miss.op_cache_hit  Counts Op Cache micro-tag
                                              hit events.

نمی‌توان از کدگذاری خام 0x0328F استفاده کرد زیرا همان‌طور که با دستور زیر مشاهده می‌شود، نیم‌بایت (nibble) بالایی بیت‌های EventSelect باید از طریق بیت‌های 32-35 مشخص شوند:

cat /sys/bus/event_source/devices/cpu/format/event

در عوض باید از کدگذاری خام 0x20000038F استفاده شود:

perf stat -e r20000038f -a sleep 1
perf record -e r20000038f ...

همچنین امکان استفاده از نحو pmu وجود دارد:

perf record -e r20000038f -a sleep 1
perf record -e cpu/r20000038f/ ...
perf record -e cpu/r0x20000038f/ ...

برای دستیابی به این جزئیات باید به اسناد اختصاصی پردازنده مراجعه کنید. به برخی از آن‌ها در بخش «همچنین ببینید (SEE ALSO)» در زیر اشاره شده است..SH "واحدهای PMU دلخواه (ARBITRARY PMUS)"

دستور perf همچنین از یک نحو (syntax) گسترش‌یافته برای تعیین پارامترهای خام به واحدهای PMU پشتیبانی می‌کند. استفاده از این قابلیت معمولاً نیازمند جستجوی رویداد مورد نظر در مستندات ارائه‌شده توسط سازندهٔ CPU است.

واحدهای PMU در دسترس و پارامترهای خام آن‌ها را می‌توان با دستور زیر فهرست کرد:

ls /sys/bus/event_source/devices/*/format

برای نمونه رویداد خام "LSD.UOPS" مربوط به PMU هسته در بالا می‌تواند به این صورت مشخص شود:

perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...

یا با استفاده از نحو نام گسترش‌یافته

perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...

واحدهای PMU به ازای سوکت (PER SOCKET PMUS)

برخی از واحدهای PMU به یک هسته وابسته نیستند، بلکه با کل یک سوکت CPU در ارتباط هستند. رویدادهای این PMUها عموماً قابل نمونه‌برداری نیستند، و تنها می‌توان آن‌ها را به‌صورت سراسری با perf stat -a شمارش کرد. آن‌ها می‌توانند به یک CPU منطقی مقید شوند، اما تمام پردازنده‌های موجود در همان سوکت را اندازه‌گیری خواهند کرد.

این مثال پهنای باند حافظه را در هر ثانیه بر روی نخستین کنترل‌کنندهٔ حافظه در سوکت 0 از یک سیستم Intel Xeon اندازه‌گیری می‌کند:

perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...

هر کنترل‌کنندهٔ حافظه PMU ویژهٔ خود را دارد. اندازه‌گیری پهنای باند کل سیستم مستلزم مشخص کردن تمام PMUهای imc (خروجی perf list را ببینید) و جمع بستن مقادیر با یکدیگر است. برای ساده‌سازی تعریف چندین رویداد، تطبیق پیشوند و الگوهای سراسری (glob) در نام PMU پشتیبانی می‌شود، همچنین پیشوند uncore_ هنگام انجام تطبیق نادیده گرفته می‌شود. بنابراین دستور بالا را می‌توان با استفاده از نحوهای زیر برای تمام کنترل‌کننده‌های حافظه گسترش داد:

perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...

این مثال توان مصرفی مجموع هسته‌ها را در هر ثانیه اندازه‌گیری می‌کند:

perf stat -I 1000 -e power/energy-cores/  -a

محدودیت‌های دسترسی (ACCESS RESTRICTIONS)

برای کاربران غیر ریشه (non-root) عموماً تنها رویدادهای PMU تعویض زمینه شده (context-switched) در دسترس هستند. این موارد معمولاً تنها شامل رویدادهای موجود در PMU پردازنده (cpu)، رویدادهای از پیش تعریف‌شده مانند cycles و instructions، و برخی رویدادهای نرم‌افزاری می‌شود.

سایر واحدهای PMU و اندازه‌گیری‌های سراسری معمولاً مختص کاربر ریشه (root) هستند. برخی از توصیف‌کننده‌های رویداد، مانند "any" نیز فقط مختص کاربر ریشه هستند.

این محدودیت را می‌توان با تنظیم sysctl با عنوان kernel.perf_event_paranoid بر روی -1 لغو کرد، که به کاربران غیر ریشه اجازه می‌دهد از این رویدادها استفاده کنند.

برای دسترسی به رویدادهای نقاط ردگیری (tracepoint)، دستور perf نیازمند دسترسی خواندن به /sys/kernel/tracing است، حتی زمانی که perf_event_paranoid در یک حالت سهل‌گیرانه‌تر تنظیم شده باشد.

رویدادهای ابزار/HWMON (TOOL/HWMON EVENTS)

برخی از رویدادها PMU مرتبطی ندارند و در عوض مقادیری را می‌خوانند که بدون فراخوانی perf_event_open در دسترس نرم‌افزار قرار دارند. از آنجا که این رویدادها از نمونه‌برداری پشتیبانی نمی‌کنند، در عمل تنها توسط ابزارهایی مانند perf stat قابل خواندن هستند.

رویدادهای ابزار (Tool events) زمان‌ها و پارامترهای مشخصی از سیستم را ارائه می‌دهند. نمونه‌های آن شامل duration_time، user_time، system_time و num_cpus_online است.

رویدادهای Hwmon دسترسی آسانی به داده‌های sysfs مربوط به hwmon، که معمولاً در /sys/class/hwmon قرار دارند، فراهم می‌کنند. این اطلاعات شامل دماها، سرعت فن‌ها و میزان مصرف انرژی است.

ردیابی (TRACING)

برخی از PMUها قابلیت‌های پیشرفتهٔ ردیابی سخت‌افزاری مانند Intel PT را کنترل می‌کنند که امکان ردیابی اجرای برنامه با سربار کم (low overhead) را فراهم می‌سازد. این موارد در سند جداگانهٔ intel-pt.txt شرح داده شده‌اند.

رویدادهای پارامتردار (PARAMETERIZED EVENTS)

برخی از رویدادهای PMU که توسط perf-list فهرست می‌شوند با علامت ? نمایش داده خواهند شد. برای نمونه:

hv_gpci/dtbp_ptitc,phys_processor_idx=?/

این بدان معناست که هنگام مشخص کردن به عنوان یک رویداد، باید مقداری نیز برای ? تعیین شود. برای نمونه:

perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...

همچنین امکان افزودن توصیف‌کننده‌های اضافی به یک رویداد وجود دارد:

percore:

مجموع شمارش رویدادها را برای تمام رشته‌های سخت‌افزاری در یک هسته محاسبه می‌کند، برای مثال:
  perf stat -e cpu/event=0,umask=0x3,percore=1/

cpu:

یک CPU یا بازه‌ای از CPUها را برای باز کردن رویداد روی آن‌ها مشخص می‌کند.
همچنین ممکن است به یک PMU برای کپی کردن ماسک CPU از آن ارجاع دهد. مقدار
می‌تواند برای مشخص کردن باز شدن رویداد روی چندین CPU تکرار شود.

مثال ۱: برای باز کردن رویداد instructions روی CPUهای 0 و 2، و
رویداد cycles روی CPUهای 1 و 2:
  perf stat -e instructions/cpu=0,cpu=2/,cycles/cpu=1-2/ -a sleep 1

مثال ۲: برای باز کردن رویداد uncore با نام data_read روی CPU 0 و
رویداد uncore با نام data_write روی CPU 1:
  perf stat -e data_read/cpu=0/,data_write/cpu=1/ -a sleep 1

مثال ۳: برای باز کردن رویداد نرم‌افزاری msr/tsc/ فقط روی CPUهایی
که با موارد مربوط به PMU با نام cpu_core مطابقت دارند:
  perf stat -e msr/tsc,cpu=cpu_core/ -a sleep 1

گروه‌های رویداد (EVENT GROUPS)

ابزار perf از تسهیم زمانی (multiplexing) رویدادها پشتیبانی می‌کند، زمانی که تعداد رویدادهای فعال از تعداد شمارنده‌های کارایی سخت‌افزاری فراتر رود. تسهیم می‌تواند هنگام تغییر نمایه اجرای بار کاری، خطاهایی در اندازه‌گیری ایجاد کند.

هنگامی که متریک‌ها با استفاده از فرمول‌هایی بر اساس شمارش رویدادها محاسبه می‌شوند، اطمینان از اینکه برخی رویدادها همیشه به‌صورت یک گروه همراه با هم اندازه‌گیری شوند برای به حداقل رساندن خطاهای تسهیم مفید است. گروه‌های رویداد را می‌توان با استفاده از { } مشخص کرد.

perf stat -e '{instructions,cycles}' ...

تعداد شمارنده‌های کارایی در دسترس به CPU بستگی دارد. یک گروه نمی‌تواند حاوی رویدادهایی بیش از شمارنده‌های موجود باشد. برای مثال پردازنده‌های Intel Core معمولاً چهار شمارنده کارایی عمومی برای هسته دارند، به‌علاوه سه شمارنده ثابت برای instructions، cycles و ref-cycles. برخی از رویدادهای خاص محدودیت‌هایی در مورد شمارنده‌ای که می‌توانند روی آن زمان‌بندی شوند دارند، و ممکن است از چندین نمونه در یک گروه واحد پشتیبانی نکنند. هنگامی که رویدادهای بیش از حدی در گروه مشخص شوند، برخی از آن‌ها اندازه‌گیری نخواهند شد.

رویدادهای سنجاق‌شدهٔ سراسری (Globally pinned) می‌توانند تعداد شمارنده‌های در دسترس برای سایر گروه‌ها را محدود کنند. در سامانه‌های x86، ناظر NMI watchdog به‌طور پیش‌فرض یک شمارنده را پین می‌کند. watchdog را می‌توان با دسترسی ریشه (root) به این صورت غیرفعال کرد:

echo 0 > /proc/sys/kernel/nmi_watchdog

رویدادهای مربوط به چندین PMU مختلف را نمی‌توان در یک گروه ترکیب کرد، به‌استثنای مواردی خاص برای رویدادهای نرم‌افزاری.

نمونه‌برداری پیشرو (LEADER SAMPLING)

ابزار perf همچنین از نمونه‌برداری گروهی پیشرو با استفاده از مشخص‌کننده :S پشتیبانی می‌کند.

perf record -e '{cycles,instructions}:S' ...
perf report --group

به‌طور معمول تمام رویدادها در یک گروه رویداد نمونه‌برداری می‌شوند، اما با :S تنها رویداد نخست (پیشرو یا leader) نمونه‌برداری می‌کند، و صرفاً مقادیر سایر رویدادها را در گروه می‌خواند.

با این حال، در مورد رویدادهای ناحیه AUX (مانند Intel PT یا CoreSight)، رویداد ناحیه AUX باید پیشرو باشد، بنابراین در این حالت رویداد دوم نمونه‌برداری می‌کند، نه رویداد اول.

گزینه‌ها (OPTIONS)

بدون گزینه‌ها، تمام رویدادهای شناخته‌شده فهرست خواهند شد.

برای محدود کردن فهرست از موارد زیر استفاده کنید:

می‌توان یک یا چند نوع را هم‌زمان استفاده کرد، که رویدادهای مربوط به انواع مشخص‌شده را فهرست می‌کند.

پشتیبانی از قالب خام:

پشتیبانی از بارگذاری خودکار شمارنده اینتل (INTEL AUTO COUNTER RELOAD SUPPORT)

پشتیبانی از قابلیت Intel Auto Counter Reload در ابزارهای perf

قابلیت بارگذاری خودکار شمارنده (Auto counter reload) سازوکاری برای نرم‌افزار فراهم می‌کند تا در صورت پشتیبانی سخت‌افزار، مشخص کند که شمارنده‌های خاصی هنگام سرریز شمارنده‌های برگزیده به طور خودکار بازنشانی شوند. با گرفتن یک نمونه تنها در صورتی که نرخ یک رویداد از آستانه خاصی نسبت به نرخ رویدادی دیگر فراتر رود، این ویژگی به نرم‌افزار اجازه می‌دهد تا بر اساس نرخ نسبی دو یا چند رویداد نمونه‌برداری کند. برای فعال‌سازی این مورد، کاربر باید برای هر رویداد مرتبط یک عبارت دوره نمونه‌برداری (sample period) و یک بیت‌ماسک ("acr_mask") ارائه دهد که مشخص می‌کند در صورت فراتر رفتن از دوره نمونه‌برداری تعیین‌شده برای آن رویداد، کدام شمارنده‌ها در گروه رویداد باید بازنشانی شوند.

برای مثال، اگر کاربر بخواهد سناریویی را بسنجد که در آن IPC > 2 است، گروه رویداد ممکن است شبیه به عبارت زیر باشد:

perf record -e {cpu_atom/instructions,period=200000,acr_mask=0x2/, \
cpu_atom/cycles,period=100000,acr_mask=0x3/} -- true

در این حالت، اگر شمارنده "instructions" از دوره نمونه‌برداری 200000 فراتر رود، شمارنده دوم، یعنی "cycles"، بازنشانی شده و نمونه‌برداری انجام می‌شود. اگر شمارنده "cycles" زودتر فراتر رود، هر دو شمارنده موجود در گروه بازنشانی خواهند شد. بدین ترتیب، تنها برای مواردی که IPC > 2 باشد نمونه‌برداری صورت خواهد گرفت.

عبارت acr_mask یک مقدار هگزادسیمال است که بیت‌ماسکی از رویدادهای موجود در گروه را نشان می‌دهد که هنگام فراتر رفتن از دوره تعیین‌شده باید بازنشانی شوند. در مثال بالا، به "instructions" مقدار acr_mask برابر با 0x2 اختصاص داده شده است؛ به این معنی که تنها رویداد دوم در گروه بازنشانی شده و نمونه‌برداری برای رویداد اول انجام می‌شود. به "cycles" مقدار acr_mask برابر با 0x3 اختصاص یافته است؛ به این معنی که اگر دوره نمونه‌برداری آن زودتر به پایان برسد، هر دو شمارنده رویداد بازنشانی خواهند شد.

عبارت رویداد RATIO-TO-PREV (RATIO-TO-PREV EVENT TERM)

برای ساده‌سازی این فرآیند، عبارت رویداد "ratio-to-prev" ارائه شده است که در کنار عبارت دوره نمونه‌برداری n یا گزینه -c/--count به کار می‌رود. این امر به کاربران امکان می‌دهد نرخ نسبی مورد نظر بین رویدادها را به صورت یک نسبت تعیین کنند. توجه: هر دو رویداد مقایسه‌شده باید متعلق به یک PMU یکسان باشند.

دستور فوق سپس به صورت زیر درخواهد آمد:

perf record -e {cpu_atom/instructions/, \
cpu_atom/cycles,period=100000,ratio-to-prev=0.5/} -- true

عبارت ratio-to-prev نسبت رویداد دارای این عبارت را نسبت به رویداد قبلی در گروه نشان می‌دهد، که همواره برابر با ۱ در نظر گرفته می‌شود و در این مثال نشان‌دهنده نسبت 1:0.5 یا 2:1 است.

به عنوان مثال، برای نمونه‌برداری در حالتی که IPC < 2 باشد، ترتیب رویدادها باید جابه‌جا شود:

perf record -e {cpu_atom/cycles/, \
cpu_atom/instructions,period=200000,ratio-to-prev=2.0/} -- true

همچنین ببینید (SEE ALSO)

perf-stat(1), perf-top(1), perf-record(1), Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3B: System Programming Guide[1], AMD Processor Programming Reference (PPR)[2].SH "نکات (NOTES)"

1.

راهنمای توسعه‌دهنده نرم‌افزار معماری‌های Intel® 64 و IA-32، جلد 3B: راهنمای برنامه‌نویسی سیستم

2.

مرجع برنامه‌نویسی پردازنده AMD (PPR)