المعطيات¶

تسمح المعطيات pid وcpu بتحديد العملية ووحدة المعالجة المركزية المراد مراقبتها:

pid == 0 وcpu == -1

يقيس هذا العملية/الخيط المستدعي على أي وحدة معالجة مركزية.

pid == 0 وcpu >= 0

يقيس هذا العملية/الخيط المستدعي فقط عند تشغيلها على وحدة المعالجة المركزية المحددة.

pid > 0 وcpu == -1

يقيس هذا العملية/الخيط المحدد على أي وحدة معالجة مركزية.

pid > 0 وcpu >= 0

يقيس هذا العملية/الخيط المحدد فقط عند تشغيلها على وحدة المعالجة المركزية المحددة.

pid == -1 وcpu >= 0

يقيس هذا جميع العمليات/الخيوط على وحدة المعالجة المركزية المحددة. يتطلب هذا صلاحية CAP_PERFMON (منذ لينكس 5.8) أو CAP_SYS_ADMIN أو قيمة أقل من 1 في الملف /proc/sys/kernel/perf_event_paranoid.

pid == -1 وcpu == -1

هذا الإعداد غير صالح وسيعيد خطأ.

عندما تكون قيمة pid أكبر من الصفر، فإن الإذن بإجراء هذا الاستدعاء للنظام تحكمه صلاحية CAP_PERFMON (منذ لينكس 5.9) وفحص وضع وصول ptrace PTRACE_MODE_READ_REALCREDS في إصدارات لينكس القديمة؛ انظر ptrace(2).

يسمح المعطى group_fd بإنشاء مجموعات أحداث. تحتوي مجموعة الأحداث على حدث واحد يكون هو قائد المجموعة. يُنشأ القائد أولاً مع تعيين group_fd = -1. تُنشأ بقية أعضاء المجموعة باستدعاءات perf_event_open() لاحقة مع تعيين group_fd ليكون واصف الملف لقائد المجموعة. (يُنشأ الحدث المنفرد مع تعيين group_fd = -1 ويُعد مجموعة من عضو واحد فقط.) تُجدول مجموعة الأحداث على وحدة المعالجة المركزية كوحدة واحدة: لن توضع على وحدة المعالجة إلا إذا أمكن وضع جميع أحداث المجموعة عليها. وهذا يعني أن قيم الأحداث الأعضاء يمكن مقارنتها بشكل ذي معنى —جمعها، أو قسمتها (للحصول على نسب)، وما إلى ذلك— مع بعضها البعض، لأنها عدت أحداثاً لنفس المجموعة من التعليمات المنفذة.

يُشكَّل المعطى flags بدمج صفر أو أكثر من القيم التالية باستخدام معامل OR المنطقي:

PERF_FLAG_FD_CLOEXEC (منذ لينكس 3.14)

يُفعل هذا العلم خاصية الغلق عند التنفيذ (close-on-exec) لواصف ملف الحدث المنشأ، بحيث يُغلق واصف الملف آلياً عند استدعاء execve(2). إن ضبط أعلام الغلق عند التنفيذ وقت الإنشاء، بدلاً من القيام بذلك لاحقًا عبر fcntl(2)، يتجنب ظروف السباق المحتملة حيث يستدعي خيط الاستدعاء perf_event_open() و fcntl(2) في نفس الوقت الذي يستدعي فيه خيط آخر fork(2) ثم execve(2).

PERF_FLAG_FD_NO_GROUP

يخبر هذا العلم الحدث بتجاهل معلمة group_fd باستثناء غرض إعداد إعادة توجيه المخرجات باستخدام علم PERF_FLAG_FD_OUTPUT.

PERF_FLAG_FD_OUTPUT (معطل منذ لينكس 2.6.35)

يعيد هذا العلم توجيه مخرجات العينات للحدث ليتم تضمينها بدلاً من ذلك في مخبأ mmap للحدث المحدد بواسطة group_fd.

PERF_FLAG_PID_CGROUP (منذ لينكس 2.6.39)

يفعل هذا العلم مراقبة النظام بالكامل لكل حاوية. الحاوية هي تجريد يعزل مجموعة من الموارد للتحكم الدقيق (وحدات المعالجة، والذاكرة، إلخ). في هذا الوضع، يُقاس الحدث فقط إذا كان الخيط الذي يعمل على وحدة المعالجة المراقبة ينتمي إلى الحاوية المخصصة (cgroup). تُحدد cgroup بتمرير واصف ملف مفتوح على دليلها في نظام ملفات cgroupfs. على سبيل المثال، إذا كانت cgroup المراد مراقبتها تسمى test، فيجب تمرير واصف ملف مفتوح على /dev/cgroup/test (بافتراض أن cgroupfs موصول على /dev/cgroup) كمعلمة pid. تتوفر مراقبة cgroup فقط لأحداث النظام بالكامل، وبالتالي قد تتطلب صلاحيات إضافية.

توفر بنية perf_event_attr معلومات ضبط مفصلة للحدث الجاري إنشاؤه.

struct perf_event_attr {


    __u32 type;                 /* نوع الحدث */


    __u32 size;                 /* حجم بنية السمات */


    __u64 config;               /* الضبط الخاص بالنوع */


    union {


        __u64 sample_period;    /* فترة أخذ العينات */


        __u64 sample_freq;      /* تردد أخذ العينات */


    };


    __u64 sample_type;  /* يحدد القيم المضمنة في العينة */


    __u64 read_format;  /* يحدد القيم المعادة في القراءة */


    __u64 disabled       : 1,   /* معطل مبدئياً */


          inherit        : 1,   /* يرثه الأبناء */


          pinned         : 1,   /* يجب أن يكون دائماً على وحدة مراقبة الأداء (PMU) */


          exclusive      : 1,   /* المجموعة الوحيدة على PMU */


          exclude_user   : 1,   /* لا تحسب المستخدم */


          exclude_kernel : 1,   /* لا تحسب النواة */


          exclude_hv     : 1,   /* لا تحسب المراقب الفائق */


          exclude_idle   : 1,   /* لا تحسب عند الخمول */


          mmap           : 1,   /* تضمين بيانات mmap */


          comm           : 1,   /* تضمين بيانات comm */


          freq           : 1,   /* استخدام التردد وليس الفترة */


          inherit_stat   : 1,   /* عد لكل مهمة */


          enable_on_exec : 1,   /* التنفيذ التالي يفعله */


          task           : 1,   /* تتبع التفريع/الخروج */


          watermark      : 1,   /* علامة الاستيقاظ المائية */


          precise_ip     : 2,   /* قيد الانزلاق */


          mmap_data      : 1,   /* بيانات mmap غير التنفيذية */


          sample_id_all  : 1,   /* معرف العينة لجميع الأحداث */


          exclude_host   : 1,   /* لا تحسب في المضيف */


          exclude_guest  : 1,   /* لا تحسب في الضيف */


          exclude_callchain_kernel : 1,


                                /* استثناء سلاسل استدعاء النواة */


          exclude_callchain_user   : 1,


                                /* استثناء سلاسل استدعاء المستخدم */


          mmap2          :  1,  /* تضمين mmap مع بيانات inode */


          comm_exec      :  1,  /* وسم أحداث comm الناتجة عن التنفيذ */


          use_clockid    :  1,  /* استخدام clockid لحقول الوقت */


          context_switch :  1,  /* بيانات تبديل السياق */


          write_backward :  1,  /* كتابة المخبأ الحلقي من النهاية إلى البداية */


          namespaces     :  1,  /* تضمين بيانات مساحات الأسماء */


          ksymbol        :  1,  /* تضمين أحداث ksymbol */


          bpf_event      :  1,  /* تضمين أحداث bpf */


          aux_output     :  1,  /* توليد سجلات AUX بدلاً من الأحداث */


          cgroup         :  1,  /* تضمين أحداث cgroup */


          text_poke      :  1,  /* تضمين أحداث تعديل النص */


          build_id       :  1,  /* استخدام معرف البناء في أحداث mmap2 */


          inherit_thread :  1,  /* يرث الأبناء فقط إذا استُخدم CLONE_THREAD */


          remove_on_exec :  1,  /* يُزال الحدث من المهمة عند التنفيذ */


          sigtrap        :  1,  /* إرسال SIGTRAP متزامن عند الحدث */


          __reserved_1   : 26;


    union {


        __u32 wakeup_events;    /* الاستيقاظ كل n حدث */


        __u32 wakeup_watermark; /* البايتات قبل الاستيقاظ */


    };


    __u32     bp_type;          /* نوع نقطة التوقف */


    union {


        __u64 bp_addr;          /* عنوان نقطة التوقف */


        __u64 kprobe_func;      /* لـ perf_kprobe */


        __u64 uprobe_path;      /* لـ perf_uprobe */


        __u64 config1;          /* امتداد لـ config */


    };


    union {


        __u64 bp_len;           /* حجم نقطة التوقف */


        __u64 kprobe_addr;      /* مع kprobe_func == NULL */


        __u64 probe_offset;     /* لـ perf_[k,u]probe */


        __u64 config2;          /* امتداد لـ config1 */


    };


    __u64 branch_sample_type;   /* نوع عينة التفرع */


    __u64 sample_regs_user;     /* سجلات المستخدم لتفريغها عند العينات */


    __u32 sample_stack_user;    /* حجم المكدس لتفريغه عند العينات */


    __s32 clockid;              /* الساعة المستخدمة لحقول الوقت */


    __u64 sample_regs_intr;     /* السجلات لتفريغها عند العينات */


    __u32 aux_watermark;        /* بايتات aux قبل الاستيقاظ */


    __u16 sample_max_stack;     /* أقصى عدد من الإطارات في سلسلة الاستدعاء */


    __u16 __reserved_2;         /* موازاة إلى u64 */


    __u32 aux_sample_size;      /* أقصى حجم لعينة aux */


    __u32 __reserved_3;         /* موازاة إلى u64 */


    __u64 sig_data;             /* بيانات المستخدم لـ sigtrap */
};

وُصفت حقول بنية perf_event_attr بمزيد من التفصيل أدناه:

type

يحدد هذا الحقل نوع الحدث العام. ويأخذ إحدى القيم التالية:

size

حجم بنية perf_event_attr للتوافقية الأمامية والخلفية. اضبط هذا باستخدام sizeof(struct perf_event_attr) للسماح للنواة برؤية حجم البنية وقت التصريف.

عُيّن التعريف ذو الصلة PERF_ATTR_SIZE_VER0 إلى 64؛ وكان هذا حجم أول بنية نُشرت. وPERF_ATTR_SIZE_VER1 هو 72، ويقابل إضافة نقاط التوقف في لينكس 2.6.33. وPERF_ATTR_SIZE_VER2 هو 80 ويقابل إضافة أخذ عينات التفرع في لينكس 3.4. وPERF_ATTR_SIZE_VER3 هو 96 ويقابل إضافة sample_regs_user و sample_stack_user في لينكس 3.7. وPERF_ATTR_SIZE_VER4 هو 104 ويقابل إضافة sample_regs_intr في لينكس 3.19. وPERF_ATTR_SIZE_VER5 هو 112 ويقابل إضافة aux_watermark في لينكس 4.1.

config

يحدد هذا الحدث الذي تريده، بالاشتراك مع حقل type. كما تُؤخذ الحقول config1 وconfig2 في الاعتبار في الحالات التي لا يكفي فيها 64 بتاً لتحديد الحدث بشكل كامل. يعتمد ترميز هذه الحقول على نوع الحدث.

توجد طرق متنوعة لضبط حقل config تعتمد على قيمة حقل type الموصوف سابقاً. وفيما يلي الإعدادات المختلفة الممكنة لـ config مقسمة حسب type.

إذا كان type هو PERF_TYPE_HARDWARE، فإننا نقيس أحد أحداث وحدة المعالجة المركزية العتادية الموحدة. ليست كل هذه الأحداث متاحة في جميع المنصات. اضبط config على أحد الخيارات التالية:

إذا كان type هو PERF_TYPE_SOFTWARE، فإننا نقيس أحداث البرمجيات التي توفرها النواة. اضبط config على أحد الخيارات التالية:

config = (perf_hw_cache_id) |


         (perf_hw_cache_op_id << 8) |


         (perf_hw_cache_op_result_id << 16);

kprobe_func

uprobe_path

kprobe_addr

probe_offset

تصف هذه الحقول kprobe/uprobe لوحدات PMU الديناميكية kprobe و uprobe. بالنسبة لـ kprobe: استخدم kprobe_func و probe_offset، أو استخدم kprobe_addr واترك kprobe_func كـ NULL. بالنسبة لـ uprobe: استخدم uprobe_path و probe_offset.

sample_period

sample_freq

حدث "أخذ العينات" هو حدث يولد إشعار تجاوز السعة كل N من الأحداث، حيث تُعطى N بواسطة sample_period. يكون لحدث أخذ العينات sample_period أكبر من 0. وعند حدوث تجاوز للسعة، تُسجل البيانات المطلوبة في ذاكرة mmap الوسيطة. يتحكم الحقل sample_type في البيانات التي تُسجل عند كل تجاوز للسعة.

يمكن استخدام sample_freq إذا كنت ترغب في استخدام التردد بدلاً من الفترة. في هذه الحالة، تضبط علامة freq. ستقوم النواة بضبط فترة أخذ العينات لمحاولة تحقيق المعدل المطلوب. معدل الضبط هو تكة المؤقت.

sample_type

تحدد البتات المختلفة في هذا الحقل القيم التي يجب تضمينها في العينة. ستُسجل في ذاكرة وسيطة حلقية، وهي متاحة لمساحة المستخدم باستخدام mmap(2). الترتيب الذي تُحفظ به القيم في العينة موثق في القسم الفرعي تخطيط MMAP أدناه؛ وليس ترتيب enum perf_event_sample_format.

union perf_sample_weight {


    u64  full;           /* PERF_SAMPLE_WEIGHT */


    struct {             /* PERF_SAMPLE_WEIGHT_STRUCT */


        u32  var1_dw;


        u16  var2_w;


        u16  var3_w;


    };
};

read_format

يحدد هذا الحقل تنسيق البيانات التي يعيدها read(2) في واصف ملف perf_event_open().

disabled

تحدد بتة disabled ما إذا كان العداد سيبدأ معطلاً أم مفعلاً. إذا عُطل، يمكن تفعيل الحدث لاحقًا بواسطة ioctl(2) أو prctl(2) أو enable_on_exec.

عند إنشاء مجموعة أحداث، يُهيأ قائد المجموعة عادةً مع ضبط disabled على 1، وتُهيأ أي أحداث تابعة مع ضبط disabled على 0. وبالرغم من كون disabled بقيمة 0، لن تبدأ الأحداث التابعة حتى يُفعل قائد المجموعة.

inherit

تحدد بتة inherit وجوب قيام هذا العداد بعد أحداث المهام التابعة بالإضافة إلى المهمة المحددة. ينطبق هذا فقط على التوابع الجدد، وليس على أي توابع موجودين وقت إنشاء العداد (ولا على أي توابع جدد لتوابع موجودين).

لا تعمل الوراثة (Inherit) مع بعض تركيبات قيم read_format، مثل PERF_FORMAT_GROUP. بالإضافة إلى ذلك، فإن استخدامها مع cpu == -1 يمنع إنشاء مخزن mmap الدائري المستخدم لتسجيل الأحداث غير المتزامنة في نمط أخذ العينات.

pinned

تحدد بتة pinned وجوب بقاء العداد دائماً على المعالج إن أمكن ذلك. تنطبق فقط على العدادات العتادية وعلى قادة المجموعات فقط. إذا تعذر وضع عداد مثبت على المعالج (مثلاً لعدم كفاية العدادات العتادية أو بسبب تعارض مع حدث آخر)، ينتقل العداد إلى حالة 'خطأ'، حيث تعيد عمليات القراءة نهاية الملف (أي يعيد read(2) القيمة 0) حتى يُفعل العداد أو يُعطل لاحقًا.

exclusive

تحدد بتة exclusive أنه عندما تكون مجموعة هذا العداد على المعالج، يجب أن تكون هي المجموعة الوحيدة التي تستخدم عدادات المعالج. قد يسمح هذا مستقبلاً لبرامج المراقبة بدعم ميزات وحدة مراقبة الأداء (PMU) التي تتطلب العمل بمفردها حتى لا تشوش على العدادات العتادية الأخرى.

لاحظ أن العديد من المواقف غير المتوقعة قد تمنع الأحداث التي ضُبطت فيها بتة exclusive من العمل نهائياً. يتضمن ذلك أي مستخدمين يشغلون قياساً على مستوى النظام، بالإضافة إلى أي استخدام للنواة لعدادات الأداء (بما في ذلك واجهة مؤقت مراقب NMI المفعلة عادةً).

exclude_user

إذا ضُبطت هذه البتة، يستثني العد الأحداث التي تقع في مساحة المستخدم.

exclude_kernel

إذا ضُبطت هذه البتة، يستثني العد الأحداث التي تقع في مساحة النواة.

exclude_hv

إذا ضُبطت هذه البتة، يستثني العد الأحداث التي تقع في مشرف الأجهزة الافتراضية (hypervisor). هذا مخصص أساساً لوحدات مراقبة الأداء (PMUs) التي تدعم ذلك ذاتياً (مثل POWER). يلزم دعم إضافي للتعامل مع قياسات مشرف الأجهزة الافتراضية في معظم الأجهزة.

exclude_idle

إذا ضُبطت، لا يُعد عندما يشغل المعالج مهمة الخمول. برغم أنه يمكن تفعيل هذا حالياً لأي نوع حدث، إلا أنه يُتجاهل لجميع الأحداث باستثناء الأحداث البرمجية.

mmap

تفعل بتة mmap توليد عينات PERF_RECORD_MMAP لكل استدعاء mmap(2) يكون فيه PROT_EXEC مضبوطاً. يسمح هذا للأدوات بملاحظة التعليمات البرمجية التنفيذية الجديدة التي تُربط ببرنامج ما (مثل المكتبات المشتركة الديناميكية) بحيث يمكن ربط العناوين بالتعليمات البرمجية الأصلية.

comm

تفعل بتة comm تتبع اسم أمر العملية كما يُعدل بواسطة استدعاءات النظام execve(2) و prctl(PR_SET_NAME) بالإضافة إلى الكتابة في /proc/self/comm. إذا ضُبط علم comm_exec أيضًا بنجاح (ممكن منذ لينكس 3.16)، يمكن استخدام العلم المتنوع PERF_RECORD_MISC_COMM_EXEC للتمييز بين حالة execve(2) والحالات الأخرى.

freq

إذا ضُبطت هذه البتة، يُستخدم sample_frequency وليس sample_period عند إعداد فاصل أخذ العينات الزمني.

inherit_stat

تفعل هذه البتة حفظ أعداد الأحداث عند تبديل السياق للمهام الموروثة. لا يكون لهذا معنى إلا إذا كان حقل inherit مضبوطاً.

enable_on_exec

إذا ضُبطت هذه البتة، يُفعل العداد آلياً بعد استدعاء execve(2).

task

إذا ضُبطت هذه البتة، تُدرج إشعارات التفريع/الخروج في المخزن الدائري.

watermark

إذا ضُبطت، يقع إشعار فيض عند تجاوز حدود wakeup_watermark. وإلا، تقع إشعارات الفيض بعد عينات wakeup_events.

precise_ip (منذ لينكس 2.6.35)

يتحكم هذا في مقدار الانزلاق (skid). الانزلاق هو عدد التعليمات المنفذة بين وقوع حدث مهم وتمكن النواة من التوقف وتسجيل الحدث. الانزلاق الأصغر أفضل ويسمح بتقرير أكثر دقة عن أي الأحداث يقابل أي التعليمات، ولكن غالباً ما يكون العتاد محدوداً في مدى صغر هذا المقدار.

القيم الممكنة لهذا الحقل هي كالتالي:

mmap_data (منذ لينكس 2.6.36)

هذا هو نظير حقل mmap. يفعل توليد عينات PERF_RECORD_MMAP لاستدعاءات mmap(2) التي ليس فيها PROT_EXEC مضبوطاً (على سبيل المثال البيانات وذاكرة SysV المشتركة).

sample_id_all (منذ لينكس 2.6.38)

إذا ضُبطت، يمكن بالإضافة إلى ذلك تضمين TID و TIME و ID و STREAM_ID و CPU في السجلات التي ليست من نوع PERF_RECORD_SAMPLE إذا اختير sample_type المقابل.

إذا حدد PERF_SAMPLE_IDENTIFIER، تُدرج قيمة ID إضافية كآخر قيمة لتسهيل تحليل تدفق السجلات. قد يؤدي هذا إلى ظهور قيمة id مرتين.

يوصف التخطيط بهذه البنية الوهمية:

struct sample_id {


    { u32 pid, tid; }   /* if PERF_SAMPLE_TID set */


    { u64 time;     }   /* if PERF_SAMPLE_TIME set */


    { u64 id;       }   /* if PERF_SAMPLE_ID set */


    { u64 stream_id;}   /* if PERF_SAMPLE_STREAM_ID set  */


    { u32 cpu, res; }   /* if PERF_SAMPLE_CPU set */


    { u64 id;       }   /* if PERF_SAMPLE_IDENTIFIER set */
};
    

exclude_host (منذ لينكس 3.2)

عند إجراء قياسات تتضمن عمليات تشغل مثيلات الأجهزة الافتراضية (أي التي نفذت KVM_RUN ioctl(2))، لا تُقاس إلا الأحداث التي تقع داخل مثيلة ضيف. لا يكون لهذا معنى إلا خارج الضيوف؛ هذا الإعداد لا يغير الأعداد المجموعة داخل الضيف. حالياً، هذه الوظيفة مقتصرة على x86 فقط.

exclude_guest (منذ لينكس 3.2)

عند إجراء قياسات تتضمن عمليات تشغل مثيلات الأجهزة الافتراضية (أي التي نفذت KVM_RUN ioctl(2))، لا تُقاس الأحداث التي تقع داخل مثيلات الضيف. لا يكون لهذا معنى إلا خارج الضيوف؛ هذا الإعداد لا يغير الأعداد المجموعة داخل الضيف. حالياً، هذه الوظيفة مقتصرة على x86 فقط.

exclude_callchain_kernel (منذ لينكس 3.7)

لا تُدرج تسلسلات استدعاء النواة.

exclude_callchain_user (منذ لينكس 3.7)

لا تُدرج تسلسلات استدعاء المستخدم.

mmap2 (منذ لينكس 3.16)

ولّد سجل mmap تنفيذيًّا ممتدًّا يحتوي على معلومات إضافية كافية لتمييز التعيينات المشتركة بشكل فريد. يجب أيضًا ضبط علم mmap ليعمل هذا.

comm_exec (منذ لينكس 3.16)

هذا علم لاكتشاف الميزات فحسب، ولا يغير سلوك النواة. إذا ضُبط هذا العلم بنجاح، فعند تمكين comm، سيُضبط علم PERF_RECORD_MISC_COMM_EXEC في حقل misc لترويسة سجل comm إذا كان حدث إعادة التسمية المُبلغ عنه ناتجًا عن استدعاء execve(2). يتيح هذا للأدوات التمييز بين الأنواع المختلفة لإعادة تسمية العمليات.

use_clockid (منذ لينكس 4.1)

يسمح هذا باختيار أي ساعة لينكس داخلية تُستخدم عند توليد الطوابع الزمنية عبر حقل clockid. يمكن أن يسهل هذا ربط أوقات عينات الأداء (perf) بالطوابع الزمنية التي تولدها أدوات أخرى.

context_switch (منذ لينكس 4.3)

يُمكّن هذا توليد سجلات PERF_RECORD_SWITCH عند حدوث تبديل سياق. كما يُمكّن توليد سجلات PERF_RECORD_SWITCH_CPU_WIDE عند أخذ العينات في وضع CPU-wide. هذه الوظيفة هي إضافة إلى نقاط التتبع (tracepoint) وأحداث البرمجيات الموجودة لقياس تبديلات السياق. ميزة هذه الطريقة هي أنها ستعطي معلومات كاملة حتى مع إعدادات perf_event_paranoid الصارمة.

write_backward (منذ لينكس 4.6)

يؤدي هذا إلى كتابة المخزن المؤقت الحلقي (ring buffer) من النهاية إلى البداية. هذا لدعم القراءة من مخزن مؤقت حلقي قابل للكتابة فوقه.

namespaces (منذ لينكس 4.11)

يُمكّن هذا توليد سجلات PERF_RECORD_NAMESPACES عندما تدخل مهمة ما في مساحة أسماء جديدة. كل مساحة أسماء لها مزيج من أرقام الأجهزة وأرقام العقد الفهرسية (inode).

ksymbol (منذ لينكس 5.0)

يُمكّن هذا توليد سجلات PERF_RECORD_KSYMBOL عند تسجيل رموز نواة جديدة أو إلغاء تسجيلها. يُستخدم هذا لتحليل وظائف النواة الديناميكية مثل eBPF.

bpf_event (منذ لينكس 5.0)

يُمكّن هذا توليد سجلات PERF_RECORD_BPF_EVENT عند تحميل برنامج eBPF أو إلغاء تحميله.

aux_output (منذ لينكس 5.4)

يسمح هذا للأحداث العادية (غير AUX) بتوليد بيانات لأحداث AUX إذا كان العتاد يدعم ذلك.

cgroup (منذ لينكس 5.7)

يُمكّن هذا توليد سجلات PERF_RECORD_CGROUP عند إنشاء (وتنشيط) مجموعة تحكم (cgroup) جديدة.

text_poke (منذ لينكس 5.8)

يُمكّن هذا توليد سجلات PERF_RECORD_TEXT_POKE عندما يطرأ تغيير على نص النواة (أي الكود المتمور أو المعدل ذاتيًّا).

build_id (منذ لينكس 5.12)

يغير هذا محتويات PERF_RECORD_MMAP2 لتحتوي على معرف بناء (build-id) بدلًا من أرقام الأجهزة والعقد الفهرسية (inode).

inherit_thread (منذ لينكس 5.13)

يعطل هذا توريث الحدث لعملية فرعية. فقط الخيوط الجديدة في نفس العملية (التي تُنسخ باستخدام CLONE_THREAD) هي من سيرث الحدث.

remove_on_exec (منذ لينكس 5.13)

يغلق هذا الحدث عندما يبدأ صورة عملية جديدة بواسطة execve(2).

sigtrap (منذ لينكس 5.13)

يُمكّن هذا تسليم إشارة SIGTRAP المتزامنة عند فيض الحدث.

wakeup_events

wakeup_watermark

تحدد هذه الوحدة (union) عدد العينات (wakeup_events) أو البايتات (wakeup_watermark) التي تحدث قبل حدوث إشعار بالفيض. ويُختار أيهما يُستخدم بواسطة علم بت watermark.

يعد wakeup_events أنواع سجلات PERF_RECORD_SAMPLE فقط. لتلقي إشعار بالفيض لجميع أنواع PERF_RECORD اختر watermark واضبط wakeup_watermark على 1.

قبل لينكس 3.0، كان ضبط wakeup_events على 0 يؤدي لعدم وجود إشعارات فيض؛ النوى الأحدث تعامل 0 معاملة 1.

bp_type (منذ لينكس 2.6.33)

يختار هذا نوع نقطة التوقف. وهو واحد من:

bp_addr (منذ لينكس 2.6.33)

هذا هو عنوان نقطة التوقف. بالنسبة لنقاط توقف التنفيذ، هذا هو عنوان الذاكرة للتعليمة المعنية؛ بالنسبة لنقاط توقف القراءة والكتابة، فهو عنوان الذاكرة لموقع الذاكرة المعني.

config1 (منذ لينكس 2.6.39)

يُستخدم config1 لضبط الأحداث التي تحتاج إلى سجل إضافي أو التي لا تتناسب مع حقل config العادي. تستخدم أحداث OFFCORE_EVENTS الخام على معالجات Nehalem/Westmere/SandyBridge هذا الحقل في نواة لينكس 3.3 والإصدارات الأحدث.

bp_len (منذ لينكس 2.6.33)

bp_len هو حجم نقطة التوقف التي تُقاس إذا كان type هو PERF_TYPE_BREAKPOINT. الخيارات هي HW_BREAKPOINT_LEN_1، و HW_BREAKPOINT_LEN_2، و HW_BREAKPOINT_LEN_4، و HW_BREAKPOINT_LEN_8. لنقطة توقف تنفيذ، اضبط هذا على sizeof(long).

config2 (منذ لينكس 2.6.39)

config2 هو امتداد إضافي لحقل config1.

branch_sample_type (منذ لينكس 3.4)

إذا مُكّن PERF_SAMPLE_BRANCH_STACK، فهذا يحدد الفروع التي يجب تضمينها في سجل الفروع.

الجزء الأول من القيمة هو مستوى الامتياز، وهو مزيج من إحدى القيم المدرجة أدناه. إذا لم يضبط المستخدم مستوى الامتياز صراحةً، فستستخدم النواة مستوى امتياز الحدث. لا يلزم تطابق مستويات امتياز الحدث والفرع.

sample_regs_user (منذ لينكس 3.7)

يحدد قناع البتات هذا مجموعة سجلات وحدة المعالجة المركزية الخاصة بالمستخدم لتفريغها عند أخذ العينات. تخطيط قناع السجلات خاص بالبنية المعمارية وموصوف في ملف ترويسة النواة arch/ARCH/include/uapi/asm/perf_regs.h.

sample_stack_user (منذ لينكس 3.7)

يحدد هذا حجم مكدس المستخدم المراد تفريغه إذا حُدد PERF_SAMPLE_STACK_USER.

clockid (منذ لينكس 4.1)

إذا ضُبط use_clockid، يختار هذا الحقل أي مؤقت لينكس داخلي سيُستخدم للطوابع الزمنية. المؤقتات المتاحة مُعرفة في linux/time.h، مع دعم CLOCK_MONOTONIC و CLOCK_MONOTONIC_RAW و CLOCK_REALTIME و CLOCK_BOOTTIME و CLOCK_TAI حاليًا.

aux_watermark (منذ لينكس 4.1)

يحدد هذا مقدار البيانات المطلوبة لإطلاق عينة PERF_RECORD_AUX.

sample_max_stack (منذ لينكس 4.8)

عندما يتضمن sample_type القيمة PERF_SAMPLE_CALLCHAIN، يحدد هذا الحقل عدد إطارات المكدس التي سيُبلغ عنها عند توليد سلسلة الاستدعاءات.

aux_sample_size (منذ لينكس 5.5)

عند ضبط علامة PERF_SAMPLE_AUX، حدد الحجم المطلوب لبيانات AUX. لاحظ أنه قد يتم الحصول على بيانات أصغر من الحجم المحدد.

sig_data (منذ لينكس 5.13)

ستُنسخ هذه البيانات إلى معالج إشارات المستخدم (عبر si_perf في siginfo_t) لإزالة اللبس حول أي حدث أطلق الإشارة.

قراءة النتائج¶

بمجرد فتح واصف ملف perf_event_open()، يمكن قراءة قيم الأحداث من واصف الملف. القيم الموجودة هناك يحددها حقل read_format في بنية attr عند وقت الفتح.

إذا حاولت القراءة في مخزن مؤقت ليس كبيرًا بما يكفي لاحتواء البيانات، فستنتج الخطأ ENOSPC.

إليك تخطيط البيانات التي تعيدها عملية القراءة:

•

إذا حُدد PERF_FORMAT_GROUP للسماح بقراءة جميع الأحداث في مجموعة دفعة واحدة:

struct read_format {


    u64 nr;            /* عدد الأحداث */


    u64 time_enabled;  /* إذا حُدد PERF_FORMAT_TOTAL_TIME_ENABLED */


    u64 time_running;  /* إذا حُدد PERF_FORMAT_TOTAL_TIME_RUNNING */


    struct {


        u64 value;     /* قيمة الحدث */


        u64 id;        /* إذا حُدد PERF_FORMAT_ID */


        u64 lost;      /* إذا حُدد PERF_FORMAT_LOST */


    } values[nr];
};
    

•

إذا لم يُحدد PERF_FORMAT_GROUP:

struct read_format {


    u64 value;         /* قيمة الحدث */


    u64 time_enabled;  /* إذا حُدد PERF_FORMAT_TOTAL_TIME_ENABLED */


    u64 time_running;  /* إذا حُدد PERF_FORMAT_TOTAL_TIME_RUNNING */


    u64 id;            /* إذا حُدد PERF_FORMAT_ID */


    u64 lost;          /* إذا حُدد PERF_FORMAT_LOST */
};
    

القيم المقروءة هي كما يلي:

nr

عدد الأحداث في واصف الملف هذا. متاح فقط إذا حُدد PERF_FORMAT_GROUP.

time_enabled

time_running

إجمالي الوقت الذي كان فيه الحدث مُمكنًا وقيد التشغيل. عادة ما تكون هذه القيم متماثلة. يحدث تعدد الإرسال (Multiplexing) إذا كان عدد الأحداث أكثر من عدد فتحات عداد PMU المتاحة. في هذه الحالة، تعمل الأحداث لجزء من الوقت فقط، ويمكن استخدام قيم time_enabled و time_running لقياس قيمة تقديرية للعدد.

value

قيمة غير موقعة بطول 64 بت تحتوي على نتيجة العداد.

id

قيمة فريدة عالميًا لهذا الحدث المعين؛ تظهر فقط إذا حُدد PERF_FORMAT_ID في read_format.

lost

عدد العينات المفقودة لهذا الحدث؛ تظهر فقط إذا حُدد PERF_FORMAT_LOST في read_format.

تخطيط MMAP¶

عند استخدام perf_event_open() في وضع أخذ العينات، تُسجل الأحداث غير المتزامنة (مثل تجاوز العداد أو تتبع mmap لـ PROT_EXEC) في مخزن حلقي مؤقت. يُنشأ هذا المخزن الحلقي المؤقت ويُوصَل إليه عبر mmap(2).

يجب أن يكون حجم mmap هو 1+2^n صفحة، حيث تكون الصفحة الأولى صفحة بيانات وصفية (struct perf_event_mmap_page) تحتوي على معلومات متنوعة مثل مكان رأس المخزن الحلقي المؤقت.

قبل لينكس 2.6.39، كانت هناك علة تعني أنه يجب عليك تخصيص مخزن حلقي مؤقت لـ mmap عند أخذ العينات حتى لو لم تكن تخطط للوصول إليه.

بنية أول صفحة بيانات وصفية لـ mmap هي كما يلي:

struct perf_event_mmap_page {


    __u32 version;        /* رقم إصدار هذه البنية */


    __u32 compat_version; /* أدنى إصدار تتوافق معه */


    __u32 lock;           /* قفل تسلسلي (seqlock) للمزامنة */


    __u32 index;          /* معرف عداد العتاد */


    __s64 offset;         /* يُضاف إلى قيمة عداد العتاد */


    __u64 time_enabled;   /* وقت نشاط الحدث */


    __u64 time_running;   /* وقت وجود الحدث على وحدة المعالجة المركزية */


    union {


        __u64   capabilities;


        struct {


            __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,


                  cap_bit0_is_deprecated : 1,


                  cap_user_rdpmc         : 1,


                  cap_user_time          : 1,


                  cap_user_time_zero     : 1,


        };


    };


    __u16 pmc_width;


    __u16 time_shift;


    __u32 time_mult;


    __u64 time_offset;


    __u64 __reserved[120];   /* حشو حتى 1 كيلوبايت */


    __u64 data_head;         /* الرأس في قسم البيانات */


    __u64 data_tail;         /* الذيل المكتوب من مساحة المستخدم */


    __u64 data_offset;       /* مكان بدء المخزن المؤقت */


    __u64 data_size;         /* حجم مخزن البيانات المؤقت */


    __u64 aux_head;


    __u64 aux_tail;


    __u64 aux_offset;


    __u64 aux_size;
}

تصف القائمة التالية الحقول في بنية perf_event_mmap_page بمزيد من التفصيل:

الإصدار

رقم إصدار هذه البنية.

إصدار_التوافق

أدنى إصدار تتوافق معه هذه البنية.

القفل

قفل تسلسلي (seqlock) للمزامنة.

index

معرف فريد لعدادات العتاد.

offset

عند استخدام rdpmc للقراءات، يجب إضافة قيمة offset هذه إلى القيمة التي تعيدها rdpmc للحصول على إجمالي عدد الأحداث الحالي.

time_enabled

الوقت الذي كان فيه الحدث نشطًا.

time_running

الوقت الذي كان فيه الحدث قيد التشغيل.

cap_usr_time / cap_usr_rdpmc / cap_bit0 (منذ لينكس 3.4)

وُجدت علة في تعريف cap_usr_time و cap_usr_rdpmc من لينكس 3.4 حتى لينكس 3.11. عُرّف كلا البتين للإشارة إلى الموقع نفسه، لذا كان من المستحيل معرفة ما إذا كان قد ضُبط cap_usr_time أو cap_usr_rdpmc فعليًا.

بدءًا من لينكس 3.12، غُيرت أسماؤها إلى cap_bit0 وينبغي عليك استخدام حقول cap_user_time و cap_user_rdpmc بدلًا منها.

cap_bit0_is_deprecated (منذ لينكس 3.12)

إذا ضُبط هذا البت، فإنه يشير إلى أن النواة تدعم بتات cap_user_time و cap_user_rdpmc المفصولة بشكل سليم.

إذا لم يُضبط، فإنه يشير إلى نواة قديمة حيث ترتبط cap_usr_time و cap_usr_rdpmc بالبت نفسه وبالتالي يجب استخدام كلتا الميزتين بحذر.

cap_user_rdpmc (منذ لينكس 3.12)

إذا كان العتاد يدعم قراءة عدادات الأداء من مساحة المستخدم دون استدعاء نظام (هذه هي تعليمة "rdpmc" على x86)، فيمكن استخدام الشيفرة التالية لإجراء القراءة:

u32 seq, time_mult, time_shift, idx, width;
u64 count, enabled, running;
u64 cyc, time_offset;
do {


    seq = pc->lock;


    barrier();


    enabled = pc->time_enabled;


    running = pc->time_running;


    if (pc->cap_usr_time && enabled != running) {


        cyc = rdtsc();


        time_offset = pc->time_offset;


        time_mult   = pc->time_mult;


        time_shift  = pc->time_shift;


    }


    idx = pc->index;


    count = pc->offset;


    if (pc->cap_usr_rdpmc && idx) {


        width = pc->pmc_width;


        count += rdpmc(idx - 1);


    }


    barrier();
} while (pc->lock != seq);
    

cap_user_time (منذ لينكس 3.12)

يشير هذا البت إلى أن العتاد يحتوي على عداد طابع زمني ثابت لا يتوقف (TSC على x86).

cap_user_time_zero (منذ لينكس 3.12)

يشير إلى وجود time_zero الذي يسمح بربط قيم الطابع الزمني بساعة العتاد.

pmc_width

في حال وجود cap_usr_rdpmc، يوفر هذا الحقل عرض البت للقيمة المقروءة باستخدام rdpmc أو تعليمة مكافئة. يمكن استخدام هذا لتوسيع إشارة النتيجة مثل:

pmc <<= 64 - pmc_width;
pmc >>= 64 - pmc_width;  // إزاحة يمين مع إشارة
count += pmc;
    

time_shift

time_mult

time_offset

في حال وجود cap_usr_time، يمكن استخدام هذه الحقول لحساب فارق الوقت منذ time_enabled (بالنانوثانية) باستخدام rdtsc أو ما شابه.

u64 quot, rem;
u64 delta;
quot  = cyc >> time_shift;
rem   = cyc & (((u64)1 << time_shift) - 1);
delta = time_offset + quot * time_mult +


        ((rem * time_mult) >> time_shift);
    

حيث تُقرأ time_offset و time_mult و time_shift و cyc في حلقة seqcount الموضحة أعلاه. يمكن بعد ذلك إضافة هذا الفارق (delta) إلى الوقت المُمكّن (enabled) والمشغل المحتمل (running) (إذا وُجد idx)، مما يحسن القياس:

enabled += delta;
if (idx)


    running += delta;
quot  = count / running;
rem   = count % running;
count = quot * enabled + (rem * enabled) / running;
    

time_zero (منذ لينكس 3.12)

إذا ضُبط cap_usr_time_zero، فيمكن حساب ساعة العتاد (عداد الطابع الزمني TSC على x86) من قيم time_zero و time_mult و time_shift:

time = timestamp - time_zero;
quot = time / time_mult;
rem  = time % time_mult;
cyc  = (quot << time_shift) + (rem << time_shift) / time_mult;
    

والعكس صحيح:

quot = cyc >> time_shift;
rem  = cyc & (((u64)1 << time_shift) - 1);
timestamp = time_zero + quot * time_mult +


            ((rem * time_mult) >> time_shift);
    

data_head

يشير هذا إلى رأس قسم البيانات. تزداد القيمة باستمرار، ولا تلتف. يجب لف القيمة يدويًا بحجم وسيط mmap قبل الوصول إلى العينات.

في المنصات التي تدعم SMP، بعد قراءة قيمة data_head، يجب على مساحة المستخدم إصدار rmb().

data_tail

عندما يكون الربط PROT_WRITE، يجب كتابة قيمة data_tail بواسطة مساحة المستخدم لتعكس آخر بيانات وُصل إليها. في هذه الحالة، لن تكتب النواة فوق البيانات غير المقروءة.

data_offset (منذ لينكس 4.1)

يحتوي على إزاحة الموقع في وسيط mmap حيث تبدأ بيانات عينة الأداء.

data_size (منذ لينكس 4.1)

يحتوي على حجم منطقة عينة الأداء داخل وسيط mmap.

aux_head

aux_tail

aux_offset

aux_size (منذ لينكس 4.1)

تسمح منطقة AUX بإجراء mmap(2) لوسيط عينة منفصل لتدفقات البيانات ذات النطاق الترددي العالي (منفصل عن وسيط عينة الأداء الرئيس). من الأمثلة على تدفقات النطاق الترددي العالي دعم تتبع التعليمات، كما هو موجود في معالجات Intel الأحدث.

لإعداد منطقة AUX، يجب أولاً ضبط aux_offset بإزاحة أكبر من data_offset+data_size ويجب ضبط aux_size على حجم الوسيط المطلوب. يجب أن تكون الإزاحة والحجم المطلوبان متحاذيين مع الصفحة، ويجب أن يكون الحجم من مضاعفات القوة اثنين. تُمرر هذه القيم بعد ذلك إلى mmap لربط وسيط AUX. تُدرج الصفحات في وسيط AUX كجزء من حد الموارد RLIMIT_MEMLOCK (انظر setrlimit(2))، وأيضًا كجزء من مخصص perf_event_mlock_kb.

بشكل مبدئي، سيُبتر وسيط AUX إذا لم يتسع في المساحة المتاحة في الوسيط الدائري. إذا رُبط وسيط AUX كوسيط للقراءة فقط، فسيعمل في وضع الوسيط الدائري حيث تُستبدل البيانات القديمة ببيانات جديدة. في وضع الكتابة فوق البيانات، قد لا يكون من الممكن استنتاج أين بدأت البيانات الجديدة، وتكون مهمة المستهلك تعطيل القياس أثناء القراءة لتجنب سباقات البيانات المحتملة.

تتبع مؤشرات الوسيط الدائري aux_head و aux_tail السلوك نفسه وقواعد الترتيب الخاصة بـ data_head و data_tail الموصوفة سابقًا.

صفحات الوسيط الدائري 2^n التالية لها التخطيط الموصوف أدناه.

إذا ضُبط perf_event_attr.sample_id_all، فستحتوي جميع أنواع الأحداث على حقول sample_type المحددة المتعلقة بمكان/زمان (هوية) وقوع الحدث (TID, TIME, ID, CPU, STREAM_ID) الموضحة في PERF_RECORD_SAMPLE أدناه، وسيُخزن مباشرة بعد perf_event_header والحقول الموجودة بالفعل للحقول الحالية، أي في نهاية الحمولة. يسمح هذا بدعم ملف perf.data أحدث بواسطة أدوات perf قديمة، مع تجاهل الحقول الاختيارية الجديدة.

تبدأ قيم mmap بترويسة:

struct perf_event_header {


    __u32   type;


    __u16   misc;


    __u16   size;
};

أدناه، نصف حقول perf_event_header بمزيد من التفصيل. لسهولة القراءة، تُعرض الحقول ذات الأوصاف الأقصر أولاً.

size

يشير هذا إلى حجم السجل.

misc

يحتوي الحقل misc على معلومات إضافية حول العينة.

يمكن تحديد وضع وحدة المعالجة المركزية من هذه القيمة عن طريق القناع بـ PERF_RECORD_MISC_CPUMODE_MASK والبحث عن أحد ما يلي (لاحظ أن هذه ليست أقنعة بتات، يمكن ضبط واحد فقط في كل مرة):

type

قيمة type هي واحدة مما يلي. تعتمد القيم في السجل المقابل (الذي يلي الترويسة) على type المحدد كما هو موضح.

التعامل مع الطفح¶

يمكن ضبط الأحداث للإشعار عند تجاوز عتبة معينة، مما يشير إلى حدوث طفح. يمكن التقاط حالات الطفح من خلال مراقبة واصف ملف الحدث باستخدام poll(2)، أو select(2)، أو epoll(7). بدلاً من ذلك، يمكن التقاط أحداث الطفح عبر معالج إشارات، من خلال تمكين إشارات الدخل/الخرج على واصف الملف؛ انظر مناقشة عمليتي F_SETOWN و F_SETSIG في fcntl(2).

لا تُولَّد حالات الطفح إلا بواسطة أحداث أخذ العينات (يجب أن تكون قيمة sample_period غير صفرية).

توجد طريقتان لتوليد إشعارات الطفح.

الأولى هي ضبط قيمة wakeup_events أو wakeup_watermark التي ستعمل إذا كُتب عدد معين من العينات أو البايتات في المخزن المؤقت الحلقي لـ mmap. في هذه الحالة، يُشار إلى POLL_IN.

الطريقة الأخرى هي استخدام ioctl PERF_EVENT_IOC_REFRESH. يضيف هذا الـ ioctl إلى عداد يتناقص في كل مرة يطفح فيها الحدث. عندما تكون القيمة غير صفرية، يُشار إلى POLL_IN، ولكن بمجرد وصول العداد إلى 0، يُشار إلى POLL_HUP ويُعطَّل الحدث الأساسي.

تؤدي عملية تنشيط متصدر مجموعة أحداث إلى تنشيط جميع الأشقاء، كما أن التنشيط باستخدام المعامل 0 يتيح حاليًا عمليات تنشيط غير محدودة؛ هذه السلوكيات غير مدعومة ولا ينبغي الاعتماد عليها.

بدءًا من لينكس 3.18، يُشار إلى POLL_HUP إذا كان الحدث الذي تُجرى مراقبته مرتبطًا بعملية مختلفة وخرجت تلك العملية.

تعليمة rdpmc¶

بدءًا من لينكس 3.4 على x86، يمكنك استخدام تعليمة rdpmc للحصول على قراءات ذات زمن وصول منخفض دون الحاجة إلى الدخول إلى النواة. لاحظ أن استخدام rdpmc ليس بالضرورة أسرع من الطرق الأخرى لقراءة قيم الأحداث.

يمكن اكتشاف دعم ذلك من خلال حقل cap_usr_rdpmc في صفحة mmap؛ يمكن العثور على وثائق حول كيفية حساب قيم الأحداث في ذلك القسم.

في الأصل، عندما كان دعم rdpmc مُمكَّنًا، كان بإمكان أي عملية (ليس فقط تلك التي لديها حدث perf نشط) استخدام تعليمة rdpmc للوصول إلى العدادات. بدءًا من لينكس 4.0، لا يُسمح بدعم rdpmc إلا إذا كان هناك حدث مُمكَّن حاليًا في سياق العملية. لاستعادة السلوك القديم، اكتب القيمة 2 في /sys/devices/cpu/rdpmc.

استدعاءات ioctl لـ perf_event¶

تعمل استدعاءات ioctl المتنوعة على واصفات ملفات perf_event_open():

PERF_EVENT_IOC_ENABLE

يُمكِّن هذا الحدث الفردي أو مجموعة الأحداث المحددة بواسطة وسيط واصف الملف.

إذا ضُبطت بتة PERF_IOC_FLAG_GROUP في وسيط ioctl، فستُمكَّن جميع الأحداث في المجموعة، حتى لو لم يكن الحدث المحدد هو متصدر المجموعة (ولكن انظر قسم العيوب BUGS).

PERF_EVENT_IOC_DISABLE

يُعطِّل هذا العداد الفردي أو مجموعة الأحداث المحددة بواسطة وسيط واصف الملف.

يؤدي تمكين أو تعطيل متصدر المجموعة إلى تمكين أو تعطيل المجموعة بأكملها؛ أي أنه أثناء تعطيل متصدر المجموعة، لن يقوم أي من العدادات في المجموعة بالعد. يؤثر تمكين أو تعطيل عضو في مجموعة غير المتصدر على ذلك العداد فقط؛ حيث يؤدي تعطيل عضو غير متصدر إلى إيقاف ذلك العداد عن العد ولكنه لا يؤثر على أي عداد آخر.

إذا ضُبطت بتة PERF_IOC_FLAG_GROUP في وسيط ioctl، فستُعطَّل جميع الأحداث في المجموعة، حتى لو لم يكن الحدث المحدد هو متصدر المجموعة (ولكن انظر قسم العيوب BUGS).

PERF_EVENT_IOC_REFRESH

يمكن لعدادات الطفح غير الموروثة استخدام هذا لتمكين عداد لعدد من حالات الطفح المحددة بواسطة الوسيط، وبعد ذلك يُعطَّل. تضيف الاستدعاءات اللاحقة لهذا الـ ioctl قيمة الوسيط إلى العدد الحالي. سيحدث إشعار طفح مع ضبط POLL_IN عند كل طفح حتى يصل العدد إلى 0؛ وعندما يحدث ذلك، يُرسل إشعار مع ضبط POLL_HUP ويُعطَّل الحدث. يُعد استخدام وسيط بقيمة 0 سلوكًا غير محدد.

PERF_EVENT_IOC_RESET

تُصفَّر قيمة عداد الأحداث المحدد بواسطة وسيط واصف الملف. يصفر هذا القيم فقط؛ ولا توجد طريقة لتصفير قيم تعدد الإرسال time_enabled أو time_running.

إذا ضُبطت بتة PERF_IOC_FLAG_GROUP في وسيط ioctl، فستُصفر كل الأحداث في المجموعة، حتى لو لم يكن الحدث المحدد هو قائد المجموعة (لكن انظر قسم العلل BUGS).

PERF_EVENT_IOC_PERIOD

يحدث هذا فترة التجاوز (overflow) للحدث.

بدءًا من لينكس 3.7 (على ARM) ولينكس 3.14 (بقية المعماريات الأخرى)، تسري الفترة الجديدة فورًا. أما في نويات النواة الأقدم، فلم تكن الفترة الجديدة تسري إلا بعد حدوث التجاوز التالي.

الوسيط هو مؤشر إلى قيمة 64 بت تحتوي على الفترة الجديدة المطلوبة.

قبل لينكس 2.6.36، كان ioctl هذا يفشل دائمًا بسبب علة في النواة.

PERF_EVENT_IOC_SET_OUTPUT

يخبر هذا النواة بإرسال إشعارات الأحداث إلى واصف الملف المحدد بدلًا من الواصف المبدئي. يجب أن تكون جميع واصفات الملفات على وحدة المعالجة المركزية ذاتها.

يحدد الوسيط واصف الملف المطلوب، أو -1 إذا وجب تجاهل المخرجات.

PERF_EVENT_IOC_SET_FILTER (منذ لينكس 2.6.33)

يضيف هذا مرشح ftrace إلى هذا الحدث.

الوسيط هو مؤشر إلى مرشح ftrace المطلوب.

PERF_EVENT_IOC_ID (منذ لينكس 3.12)

يعيد هذا قيمة معرف الحدث لواصف ملف الحدث المعطى.

الوسيط هو مؤشر إلى عدد صحيح غير موقع بطول 64 بت لحفظ النتيجة.

PERF_EVENT_IOC_SET_BPF (منذ لينكس 4.1)

يسمح هذا بربط برنامج مرشح حزم بيركلي (BPF) بحدث نقطة تتبع kprobe موجود. تحتاج إلى امتيازات CAP_PERFMON (منذ لينكس 5.8) أو CAP_SYS_ADMIN لاستخدام ioctl هذا.

الوسيط هو واصف ملف برنامج BPF أُنشئ عبر استدعاء نظام bpf(2) سابق.

PERF_EVENT_IOC_PAUSE_OUTPUT (منذ لينكس 4.7)

يسمح هذا بإيقاف واستئناف المخزن الحلقي (ring-buffer) للحدث. لا يمنع المخزن الحلقي المتوقف مؤقتًا توليد العينات، ولكنه يطرحها ببساطة. تُعتبر العينات المطروحة مفقودة، وتتسبب في توليد عينة PERF_RECORD_LOST عندما يكون ذلك ممكنًا. قد تظل إشارة التجاوز تنطلق بسبب العينة المطروحة حتى لو ظل المخزن الحلقي فارغًا.

الوسيط هو عدد صحيح غير موقع بطول 32 بت. تؤدي القيمة غير الصفرية إلى إيقاف المخزن الحلقي مؤقتًا، بينما تستأنفه القيمة الصفرية.

PERF_EVENT_MODIFY_ATTRIBUTES (منذ لينكس 4.17)

يسمح هذا بتعديل حدث موجود دون العبء الإضافي لإغلاق وفتح حدث جديد. هذا مدعوم حاليًا لأحداث نقاط التوقف (breakpoint events) فقط.

الوسيط هو مؤشر إلى بنية perf_event_attr تحتوي على إعدادات الحدث المحدثة.

PERF_EVENT_IOC_QUERY_BPF (منذ لينكس 4.16)

يسمح هذا بالاستعلام عن برامج مرشح حزم بيركلي (BPF) المربوطة بنقطة تتبع kprobe موجودة. يمكنك ربط برنامج BPF واحد فقط لكل حدث، ولكن يمكن أن يكون لديك أحداث متعددة مربوطة بنقطة تتبع واحدة. يعيد الاستعلام عن هذه القيمة في حدث نقطة تتبع واحد معرفات جميع برامج BPF في جميع الأحداث المربوطة بنقطة التتبع تلك. تحتاج إلى امتيازات CAP_PERFMON (منذ لينكس 5.8) أو CAP_SYS_ADMIN لاستخدام ioctl هذا.

الوسيط هو مؤشر إلى بنية

struct perf_event_query_bpf {


    __u32    ids_len;


    __u32    prog_cnt;


    __u32    ids[0];
};
    

يشير حقل ids_len إلى عدد المعرفات التي يمكن أن يتسع لها مصفوفة ids الموفرة. تملأ النواة قيمة prog_cnt بعدد برامج BPF المربوطة. تُملأ مصفوفة ids بمعرف كل برنامج BPF مربوط. إذا كان هناك عدد من البرامج أكبر مما يتسع له المصفوفة، فستعيد النواة ENOSPC وسيشير ids_len إلى عدد معرفات البرامج التي نُسخت بنجاح.

استخدام prctl(2)¶

يمكن للعملية تفعيل أو تعطيل جميع مجموعات الأحداث المفتوحة حاليًا باستخدام عمليتي prctl(2) هما PR_TASK_PERF_EVENTS_ENABLE و PR_TASK_PERF_EVENTS_DISABLE. ينطبق هذا فقط على الأحداث التي أنشأها المستدعِي محليًا. ولا ينطبق على الأحداث التي أنشأتها عمليات أخرى مرتبطة بالعملية المستدعِية أو الأحداث الموروثة من عملية أب. تُفعل وتُعطل قادة المجموعات فقط، وليس أي أعضاء آخرين في المجموعات.

ملفات الإعداد المتعلقة بـ perf_event¶

ملفات في /proc/sys/kernel/

ملفات في /sys/bus/event_source/devices/