.\" -*- coding: UTF-8 -*- .\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH BPF\-HELPERS 7 "27 أكتوبر 2025" "لينكس v7.0" .SH الاسم .\" Copyright (C) All BPF authors and contributors from 2014 to present. مساعدات\-BPF \- قائمة دوال eBPF المساعدة . .\" See git log include/uapi/linux/bpf.h in kernel tree for details. . . .\" SPDX-License-Identifier: Linux-man-pages-copyleft . . .\" Please do not edit this file. It was generated from the documentation . .\" located in file include/uapi/linux/bpf.h of the Linux kernel sources . .\" (helpers description), and from scripts/bpf_doc.py in the same . .\" repository (header and footer). . .SH الوصف .sp يتكون نظام مرشح حزم بيركلي الموسع (eBPF) الفرعي من برامج مكتوبة بلغة شبه تجميعية، تُربط لاحقاً بإحدى خطافات النواة المتعددة وتُشغل كرد فعل لأحداث معينة. يختلف هذا الإطار عن نظام BPF "التقليدي" القديم (أو "cBPF") في عدة جوانب، أحدها هو القدرة على استدعاء دوال خاصة (أو "مساعدات") من داخل برنامج. تقتصر هذه الدوال على قائمة بيضاء من المساعدات المعرفة في النواة. .sp تستخدم برامج eBPF هذه المساعدات للتفاعل مع النظام، أو مع السياق الذي تعمل فيه. على سبيل المثال، يمكن استخدامها لطباعة رسائل تنقيح، أو الحصول على الوقت منذ إقلاع النظام، أو التفاعل مع خرائط eBPF، أو التلاعب بحزم الشبكة. وبما أن هناك عدة أنواع لبرامج eBPF، ولأنها لا تعمل في السياق نفسه، فإن كل نوع برنامج يمكنه فقط استدعاء مجموعة فرعية من تلك المساعدات. .sp نظراً لاتفاقيات eBPF، لا يمكن للمساعد أن يمتلك أكثر من خمسة وسائط. .sp داخلياً، تستدعي برامج eBPF دوال المساعدة المجمعة مباشرة دون الحاجة إلى أي واجهة دوال أجنبية. ونتيجة لذلك، لا يسبب استدعاء المساعدات أي عبء إضافي، مما يوفر أداءً ممتازاً. .sp هذا المستند محاولة لسرد وتوثيق المساعدات المتاحة لمطوري eBPF. رُتبت ترتيباً زمنياً (أقدم المساعدات في النواة بالأعلى). .SH المساعدات .INDENT 0.0 .TP \fBvoid *bpf_map_lookup_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أجرِ بحثاً في \fImap\fP عن مدخلة مرتبطة بـ \fIkey\fP\&. .TP \fBالقيمة المعادة\fP قيمة الخريطة المرتبطة بـ \fIkey\fP، أو \fBNULL\fP إذا لم تُعثر على أي مدخلة. .UNINDENT .TP \fBlong bpf_map_update_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB, const void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أضف أو حدّث قيمة المدخلة المرتبطة بـ \fIkey\fP في \fImap\fP بالقيمة \fIvalue\fP\&. تكون الـ \fIflags\fP واحدة مما يلي: .INDENT 7.0 .TP \fBBPF_NOEXIST\fP يجب ألا تكون المدخلة لـ \fIkey\fP موجودة في الخريطة. .TP \fBBPF_EXIST\fP يجب أن تكون المدخلة لـ \fIkey\fP موجودة بالفعل في الخريطة. .TP \fBBPF_ANY\fP لا يوجد شرط على وجود المدخلة لـ \fIkey\fP\&. .UNINDENT .sp لا يمكن استخدام قيمة الراية \fBBPF_NOEXIST\fP للخرائط من الأنواع \fBBPF_MAP_TYPE_ARRAY\fP أو \fBBPF_MAP_TYPE_PERCPU_ARRAY\fP (جميع العناصر موجودة دائماً)، سيعيد المساعد خطأً. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_map_delete_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احذف المدخلة ذات المفتاح \fIkey\fP من \fImap\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_probe_read(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لبرامج التتبع، حاول بأمان قراءة \fIsize\fP بايت من عنوان مساحة النواة \fIunsafe_ptr\fP وخزّن البيانات في \fIdst\fP\&. .sp بشكل عام، استخدم \fBbpf_probe_read_user\fP() أو \fBbpf_probe_read_kernel\fP() بدلاً من ذلك. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu64 bpf_ktime_get_ns(void)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد الوقت المنقضي منذ إقلاع النظام، بالنانوثانية. لا يشمل الوقت الذي عُلق فيه النظام. انظر: \fBclock_gettime\fP(\fBCLOCK_MONOTONIC\fP) .TP \fBالقيمة المعادة\fP الـ \fIktime\fP الحالي\&. .UNINDENT .TP \fBlong bpf_trace_printk(const char *\fP\fIfmt\fP\fB, u32 \fP\fIfmt_size\fP\fB, ...)\fP .INDENT 7.0 .TP \fBالوصف\fP هذا المساعد هو وسيلة "شبيهة بـ printk()" للتنقيح. يطبع رسالة معرفة بتنسيق \fIfmt\fP (بحجم \fIfmt_size\fP) إلى الملف \fI/sys/kernel/tracing/trace\fP من TraceFS، إذا كان متاحاً. يمكنه أخذ ما يصل إلى ثلاثة وسائط \fBu64\fP إضافية (كمساعد eBPF، يقتصر إجمالي عدد الوسائط على خمسة). .sp في كل مرة يُستدعى فيها المساعد، يلحق سطراً بالتتبع. تُهمل الأسطر بينما يكون \fI/sys/kernel/tracing/trace\fP مفتوحاً، استخدم \fI/sys/kernel/tracing/trace_pipe\fP لتجنب ذلك. تنسيق التتبع قابل للتخصيص، ويعتمد المخرج الدقيق الذي ستحصل عليه على الخيارات المحددة في \fI/sys/kernel/tracing/trace_options\fP (انظر أيضاً ملف \fIREADME\fP في الدليل نفسه). ومع ذلك، فإنه عادة ما يكون افتراضياً كالتالي: .INDENT 7.0 .INDENT 3.5 .sp .EX telnet\-470 [001] .N.. 419421.045894: 0x00000001: .EE .UNINDENT .UNINDENT .sp فيما سبق: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBtelnet\fP هو اسم المهمة الحالية. .IP \(bu 2 \fB470\fP هو معرف العملية (PID) للمهمة الحالية. .IP \(bu 2 \fB001\fP هو رقم وحدة المعالجة المركزية التي تعمل عليها المهمة. .IP \(bu 2 في \fB\&.N..\fP، يشير كل حرف إلى مجموعة من الخيارات (ما إذا كانت irqs ممكنة، خيارات الجدولة، ما إذا كانت hard/softirqs تعمل، مستوى preempt_disabled على التوالي). تعني \fBN\fP أن \fBTIF_NEED_RESCHED\fP و \fBPREEMPT_NEED_RESCHED\fP مضبوطان. .IP \(bu 2 \fB419421.045894\fP هو ختم زمني. .IP \(bu 2 \fB0x00000001\fP هي قيمة وهمية يستخدمها BPF لسجل مؤشر التعليمات. .IP \(bu 2 \fB\fP هي الرسالة المنسقة بـ \fIfmt\fP\&. .UNINDENT .UNINDENT .UNINDENT .sp محددات التحويل التي يدعمها \fIfmt\fP مشابهة، لكنها محدودة أكثر مما هي عليه في printk(). وهي \fB%d\fP و \fB%i\fP و \fB%u\fP و \fB%x\fP و \fB%ld\fP و \fB%li\fP و \fB%lu\fP و \fB%lx\fP و \fB%lld\fP و \fB%lli\fP و \fB%llu\fP و \fB%llx\fP و \fB%p\fP و \fB%s\fP\&. لا يتوفر أي معدل (حجم الحقل، الحشو بالأصفار، إلخ)، و سيعيد المساعد \fB\-EINVAL\fP (لكن لن يطبع شيئاً) إذا واجه محدداً غير معروف. .sp أيضاً، لاحظ أن \fBbpf_trace_printk\fP() بطيئة، ويجب استخدامها فقط لأغراض التنقيح. لهذا السبب، تُطبع كتلة تنبيه (تمتد لعدة أسطر) في سجلات النواة وتذكر أنه لا ينبغي استخدام المساعد "للاستخدام في الإنتاج" في المرة الأولى التي يُستخدم فيها هذا المساعد (أو بمزيد من الدقة، عند تخصيص مخازن \fBtrace_printk\fP() المؤقتة). لتمرير القيم إلى مساحة المستخدم، يفضل استخدام أحداث perf. .TP \fBالقيمة المعادة\fP عدد البايتات المكتوبة في المخزن المؤقت، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu32 bpf_get_prandom_u32(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على رقم عشوائي زائف. .sp من وجهة نظر أمنية، يستخدم هذا المساعد حالته الداخلية العشوائية الزائفة الخاصة به، ولا يمكن استخدامه لاستنتاج بذرة الدوال العشوائية الأخرى في النواة. ومع ذلك، من الضروري ملاحظة أن المولد الذي يستخدمه المساعد ليس آمناً تشفيرياً. .TP \fBالقيمة المعادة\fP قيمة غير موقعة عشوائية بطول 32 بت. .UNINDENT .TP \fBu32 bpf_get_smp_processor_id(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على معرف معالج SMP (تعدد المعالجة المتماثل). لاحظ أن جميع البرامج تعمل مع تعطيل الهجرة، مما يعني أن معرف معالج SMP مستقر طوال فترة تنفيذ البرنامج. .TP \fBالقيمة المعادة\fP معرف SMP للمعالج الذي يشغل البرنامج. .UNINDENT .TP \fBlong bpf_skb_store_bytes(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, const void *\fP\fIfrom\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP خزّن \fIlen\fP بايت من العنوان \fIfrom\fP في الحزمة المرتبطة بـ \fIskb\fP، عند الإزاحة \fIoffset\fP\&. الـ \fIflags\fP هي مزيج من القيم التالية: .INDENT 7.0 .TP \fBBPF_F_RECOMPUTE_CSUM\fP حدّث \fIskb\fP\fB\->csum\fP آلياً بعد تخزين البايتات. .TP \fBBPF_F_INVALIDATE_HASH\fP اضبط \fIskb\fP\fB\->hash\fP و \fIskb\fP\fB\->swhash\fP و \fIskb\fP\fB\->l4hash\fP على 0. .UNINDENT .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_l3_csum_replace(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, u64 \fP\fIfrom\fP\fB, u64 \fP\fIto\fP\fB, u64 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد حساب مجموع فحص الطبقة 3 (مثل IP) للحزمة المرتبطة بـ \fIskb\fP\&. الحساب تراكمي، لذا يجب أن يعرف المساعد القيمة السابقة لحقل الترويسة الذي عُدل (\fIfrom\fP)، والقيمة الجديدة لهذا الحقل (\fIto\fP)، وعدد البايتات (2 أو 4) لهذا الحقل، المخزنة في \fIsize\fP\&. بدلاً من ذلك، يمكن تخزين الفرق بين القيمتين السابقة والجديدة لحقل الترويسة في \fIto\fP، بضبط \fIfrom\fP و \fIsize\fP على 0. لكلا الطريقتين، تشير \fIoffset\fP إلى موقع مجموع فحص IP داخل الحزمة. .sp يعمل هذا المساعد بالاشتراك مع \fBbpf_csum_diff\fP()، والتي لا تحدث مجموع الفحص في مكانه، ولكنها توفر مرونة أكبر ويمكنها التعامل مع أحجام أكبر من 2 أو 4 لمجموع الفحص المراد تحديثه. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_l4_csum_replace(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, u64 \fP\fIfrom\fP\fB, u64 \fP\fIto\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد حساب مجموع فحص الطبقة 4 (مثل TCP أو UDP أو ICMP) للحزمة المرتبطة بـ \fIskb\fP\&. الحساب تراكمي، لذا يجب أن يعرف المساعد القيمة السابقة لحقل الترويسة الذي عُدل (\fIfrom\fP)، والقيمة الجديدة لهذا الحقل (\fIto\fP)، وعدد البايتات (2 أو 4) لهذا الحقل، المخزنة في البتات الأربعة الدنيا من \fIflags\fP\&. بدلاً من ذلك، يمكن تخزين الفرق بين القيمتين السابقة والجديدة لحقل الترويسة في \fIto\fP، بضبط \fIfrom\fP والبتات الأربعة الدنيا من \fIflags\fP على 0. لكلا الطريقتين، تشير \fIoffset\fP إلى موقع مجموع فحص IP داخل الحزمة. بالإضافة إلى حجم الحقل، يمكن إضافة (أو المنطقية bitwise OR) رايات فعلية إلى \fIflags\fP. مع \fBBPF_F_MARK_MANGLED_0\fP، يُترك مجموع الفحص الصفري دون مساس (ما لم تُضف \fBBPF_F_MARK_ENFORCE\fP أيضاً)، وبالنسبة للتحديثات التي تؤدي إلى مجموع فحص صفري، تُضبط القيمة على \fBCSUM_MANGLED_0\fP بدلاً من ذلك. تشير الراية \fBBPF_F_PSEUDO_HDR\fP إلى أن حقل الترويسة المعدل هو جزء من الترويسة الوهمية. يجب ضبط الراية \fBBPF_F_IPV6\fP لحزم IPv6. .sp يعمل هذا المساعد بالاشتراك مع \fBbpf_csum_diff\fP()، والتي لا تحدث مجموع الفحص في مكانه، ولكنها توفر مرونة أكبر ويمكنها التعامل مع أحجام أكبر من 2 أو 4 لمجموع الفحص المراد تحديثه. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_tail_call(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fIprog_array_map\fP\fB, u32 \fP\fIindex\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد الخاص لإطلاق "نداء ذيلي"، أو بعبارة أخرى، للقفز إلى برنامج eBPF آخر. يُستخدم إطار المكدس نفسه (لكن القيم الموجودة في المكدس وفي السجلات للمستدعِي لا يمكن للمستدعَى الوصول إليها). تسمح هذه الآلية بتسلسل البرامج، إما لرفع الحد الأقصى لعدد تعليمات eBPF المتاحة، أو لتنفيذ برامج معينة في كتل شرطية. لأسباب أمنية، هناك حد أقصى لعدد النداءات الذيلية المتعاقبة التي يمكن إجراؤها. .sp عند استدعاء هذا المساعد، يحاول البرنامج القفز إلى برنامج يُشار إليه في الفهرس \fIindex\fP في \fIprog_array_map\fP، وهي خريطة خاصة من النوع \fBBPF_MAP_TYPE_PROG_ARRAY\fP، ويمرر \fIctx\fP، وهو مؤشر للسياق. .sp إذا نجح النداء، تشغل النواة فوراً التعليمات الأولى للبرنامج الجديد. هذا ليس استدعاء دالة، ولا يعود أبداً إلى البرنامج السابق. إذا فشل النداء، فلن يكون للمساعد أي تأثير، و يستمر المستدعِي في تشغيل تعليماته اللاحقة. يمكن أن يفشل النداء إذا كان برنامج الوجهة للقفز غير موجود (أي أن \fIindex\fP أكبر من عدد المدخلات في \fIprog_array_map\fP)، أو إذا وصل إلى الحد الأقصى لعدد النداءات الذيلية لسلسلة البرامج هذه. هذا الحد معرف في النواة بواسطة الماكرو \fBMAX_TAIL_CALL_CNT\fP (لا يمكن لمساحة المستخدم الوصول إليه)، وهو مضبوط حالياً على 33. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_clone_redirect(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIifindex\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استنسخ الحزمة المرتبطة بـ \fIskb\fP وأعد توجيهها إلى جهاز شبكة آخر ذو الفهرس \fIifindex\fP\&. يمكن استخدام كل من واجهات الدخول (ingress) والخروج (egress) لإعادة التوجيه. تُستخدم القيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز (يُختار مسار الدخول إذا كانت الراية موجودة، ومسار الخروج بخلاف ذلك). هذه هي الراية الوحيدة المدعومة حالياً. .sp بالمقارنة مع المساعد \fBbpf_redirect\fP()، فإن \fBbpf_clone_redirect\fP() تتحمل التكلفة المرتبطة بمضاعفة مخزن الحزمة المؤقت، ولكن يمكن تنفيذ ذلك خارج برنامج eBPF. وعلى العكس من ذلك، فإن \fBbpf_redirect\fP() أكثر كفاءة، ولكنها تُعالج من خلال رمز إجراء حيث يحدث إعادة التوجيه فقط بعد عودة برنامج eBPF. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. يشير الخطأ الموجب إلى إسقاط محتمل أو ازدحام في الجهاز المستهدف. لا تُعرف أكواد الخطأ الموجبة المعينة. .UNINDENT .TP \fBu64 bpf_get_current_pid_tgid(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على pid و tgid الحاليين. .TP \fBالقيمة المعادة\fP عدد صحيح بطول 64 بت يحتوي على tgid و pid الحاليين، ويُنشأ كالتالي: \fIcurrent_task\fP\fB\->tgid << 32 |\fP \fIcurrent_task\fP\fB\->pid\fP\&. .UNINDENT .TP \fBu64 bpf_get_current_uid_gid(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على uid و gid الحاليين. .TP \fBالقيمة المعادة\fP عدد صحيح بطول 64 بت يحتوي على GID و UID الحاليين، ويُنشأ كالتالي: \fIcurrent_gid\fP \fB<< 32 |\fP \fIcurrent_uid\fP\&. .UNINDENT .TP \fBlong bpf_get_current_comm(void *\fP\fIbuf\fP\fB, u32 \fP\fIsize_of_buf\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP انسخ سمة \fBcomm\fP للمهمة الحالية إلى \fIbuf\fP بحجم \fIsize_of_buf\fP\&. تحتوي سمة \fBcomm\fP على اسم الملف التنفيذي (باستثناء المسار) للمهمة الحالية. يجب أن يكون \fIsize_of_buf\fP موجباً تماماً. عند النجاح، يتأكد المساعد من أن \fIbuf\fP ينتهي بـ NUL. عند الفشل، يملأ بالأصفار. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu32 bpf_get_cgroup_classid(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استرجع الـ classid للمهمة الحالية، أي لمجموعة net_cls cgroup التي تنتمي إليها \fIskb\fP. .sp يمكن استخدام هذا المساعد في مسار خروج (egress) الـ TC، وليس في الدخول (ingress). .sp توفر net_cls cgroup واجهة لوسم حزم الشبكة بناءً على معرف يوفره المستخدم لجميع الزيارات القادمة من المهام المنتمية إلى الـ cgroup ذات الصلة. انظر أيضاً توثيق النواة ذو الصلة، المتاح من مصادر لينكس في الملف \fIDocumentation/admin\-guide/cgroup\-v1/net_cls.rst\fP\&. .sp نواة لينكس لديها نسختان من الـ cgroups: هناك cgroups v1 و cgroups v2. كلاهما متاح للمستخدمين، الذين يمكنهم استخدام مزيج منهما، ولكن لاحظ أن net_cls cgroup هي لـ cgroup v1 فقط. وهذا يجعلها غير متوافقة مع برامج BPF التي تعمل على cgroups، وهي ميزة خاصة بـ cgroup\-v2 فقط (يمكن للمقبس أن يحمل بيانات لنسخة واحدة فقط من cgroups في المرة الواحدة). .sp يتوفر هذا المساعد فقط إذا جُمعت النواة مع ضبط خيار تكوين \fBCONFIG_CGROUP_NET_CLASSID\fP على "\fBy\fP" أو "\fBm\fP". .TP \fBالقيمة المعادة\fP الـ classid، أو 0 للـ classid المبدئي غير المضبوط. .UNINDENT .TP \fBlong bpf_skb_vlan_push(struct sk_buff *\fP\fIskb\fP\fB, __be16 \fP\fIvlan_proto\fP\fB, u16 \fP\fIvlan_tci\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ادفع \fIvlan_tci\fP (معلومات التحكم في وسم VLAN) من البروتوكول \fIvlan_proto\fP إلى الحزمة المرتبطة بـ \fIskb\fP، ثم حدّث مجموع الفحص. لاحظ أنه إذا كان \fIvlan_proto\fP مختلفاً عن \fBETH_P_8021Q\fP و \fBETH_P_8021AD\fP، فإنه يُعتبر \fBETH_P_8021Q\fP\&. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_vlan_pop(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اسحب ترويسة VLAN من الحزمة المرتبطة بـ \fIskb\fP\&. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_get_tunnel_key(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_tunnel_key *\fP\fIkey\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP جلب بيانات النفق الوصفية (metadata). تأخذ هذه الدالة المساعدة مؤشرًا \fIkey\fP إلى \fBstruct bpf_tunnel_key\fP فارغ ذي حجم \fBsize\fP، حيث سيُملأ ببيانات النفق الوصفية للحزمة المرتبطة بـ \fIskb\fP\&. يمكن ضبط الـ \fIflags\fP على \fBBPF_F_TUNINFO_IPV6\fP، مما يشير إلى أن النفق يعتمد على بروتوكول IPv6 بدلاً من IPv4. .sp إن الـ \fBstruct bpf_tunnel_key\fP هو كائن يعمم المعاملات الرئيسة المستخدمة في بروتوكولات الأنفاق المختلفة في هيكل واحد. بهذه الطريقة، يمكن استخدامه لاتخاذ قرار بسهولة بناءً على محتويات ترويسة التغليف، "الملخصة" في هذا الهيكل. وعلى وجه الخصوص، فإنه يحمل عنوان IP للطرف البعيد (IPv4 أو IPv6، حسب الحالة) في \fIkey\fP\fB\->remote_ipv4\fP أو \fIkey\fP\fB\->remote_ipv6\fP\&. كما يكشف هذا الهيكل عن \fIkey\fP\fB\->tunnel_id\fP، والذي يُربط عمومًا بـ VNI (مُعرف الشبكة الافتراضية)، مما يجعله قابلاً للبرمجة جنبًا إلى جنب مع الدالة المساعدة \fBbpf_skb_set_tunnel_key\fP(). .sp لنتخيل أن الكود التالي هو جزء من برنامج متصل بواجهة دخول TC، على أحد طرفي نفق GRE، ومن المفترض أن يقوم بتصفية جميع الرسائل القادمة من أطراف بعيدة بعنوان IPv4 غير 10.0.0.1: .INDENT 7.0 .INDENT 3.5 .sp .EX int ret; struct bpf_tunnel_key key = {}; ret = bpf_skb_get_tunnel_key(skb, &key, sizeof(key), 0); if (ret < 0) return TC_ACT_SHOT; // إسقاط الحزمة if (key.remote_ipv4 != 0x0a000001) return TC_ACT_SHOT; // إسقاط الحزمة return TC_ACT_OK; // قبول الحزمة .EE .UNINDENT .UNINDENT .sp يمكن أيضًا استخدام هذه الواجهة مع جميع أجهزة التغليف التي يمكنها العمل في وضع "جمع البيانات الوصفية": فبدلاً من وجود جهاز شبكة واحد لكل إعداد محدد، يتطلب وضع "جمع البيانات الوصفية" جهازًا واحدًا فقط حيث يمكن استخراج الإعدادات من هذه الدالة المساعدة. .sp يمكن استخدام هذا مع أنفاق مختلفة مثل VXLan أو Geneve أو GRE أو IP in IP (IPIP). .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_set_tunnel_key(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_tunnel_key *\fP\fIkey\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ملء بيانات النفق الوصفية للحزمة المرتبطة بـ \fIskb.\fP تُضبط بيانات النفق الوصفية وفقًا لمحتويات \fIkey\fP ذات الحجم \fIsize\fP\&. يمكن ضبط الـ \fIflags\fP على مزيج من القيم التالية: .INDENT 7.0 .TP \fBBPF_F_TUNINFO_IPV6\fP يشير إلى أن النفق يعتمد على بروتوكول IPv6 بدلاً من IPv4. .TP \fBBPF_F_ZERO_CSUM_TX\fP لحزم IPv4، أضف علامة إلى بيانات النفق الوصفية تشير إلى وجوب تخطي حساب مجموع التحقق (checksum) وضبطه على أصفار. .TP \fBBPF_F_DONT_FRAGMENT\fP أضف علامة إلى بيانات النفق الوصفية تشير إلى أنه لا ينبغي تجزئة الحزمة. .TP \fBBPF_F_SEQ_NUMBER\fP أضف علامة إلى بيانات النفق الوصفية تشير إلى وجوب إضافة رقم تسلسلي إلى ترويسة النفق قبل إرسال الحزمة. أضيفت هذه العلامة لتغليف GRE، ولكن قد تُستخدم مع بروتوكولات أخرى في المستقبل. .TP \fBBPF_F_NO_TUNNEL_KEY\fP أضف علامة إلى بيانات النفق الوصفية تشير إلى أنه لا ينبغي تعيين مفتاح نفق في ترويسة النفق الناتجة. .UNINDENT .sp فيما يلي استخدام نموذجي في مسار الإرسال: .INDENT 7.0 .INDENT 3.5 .sp .EX struct bpf_tunnel_key key; ملء المفتاح ... bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0); bpf_clone_redirect(skb, vxlan_dev_ifindex, 0); .EE .UNINDENT .UNINDENT .sp انظر أيضًا وصف الدالة المساعدة \fBbpf_skb_get_tunnel_key\fP() لمزيد من المعلومات. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu64 bpf_perf_event_read(struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP قراءة قيمة عداد أحداث الأداء (perf event). تعتمد هذه الدالة المساعدة على خريطة \fImap\fP من نوع \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. تُحدد طبيعة عداد أحداث الأداء عندما تُحدث \fImap\fP بواصفات ملفات أحداث الأداء. الـ \fImap\fP هي مصفوفة حجمها هو عدد المعالجات المتاحة، وكل خلية تحتوي على قيمة تتعلق بمعالج واحد. القيمة المطلوب جلبها يُشار إليها بواسطة \fIflags\fP، التي تحتوي على فهرس المعالج المطلوب البحث عنه، مقنعًا بـ \fBBPF_F_INDEX_MASK\fP\&. بدلاً من ذلك، يمكن ضبط \fIflags\fP على \fBBPF_F_CURRENT_CPU\fP للإشارة إلى وجوب جلب قيمة المعالج الحالي. .sp لاحظ أنه قبل الإصدار 4.13 من لينكس، يمكن جلب أحداث الأداء العتادية فقط. .sp كن على علم أيضًا أن الدالة المساعدة الأحدث \fBbpf_perf_event_read_value\fP() يُوصى بها عمومًا بدلاً من \fBbpf_perf_event_read\fP(). فالأخيرة بها بعض عيوب واجهة التطبيق الثنائية (ABI) حيث تُستخدم قيمة الخطأ والعداد كرمز إرجاع (وهو أمر خاطئ لأن النطاقات قد تتداخل). تم إصلاح هذه المشكلة في \fBbpf_perf_event_read_value\fP()، والتي توفر في الوقت نفسه ميزات أكثر من واجهة \fBbpf_perf_event_read\fP(). يرجى الرجوع إلى وصف \fBbpf_perf_event_read_value\fP() للحصول على التفاصيل. .TP \fBالقيمة المعادة\fP قيمة عداد أحداث الأداء المقروءة من الخريطة، أو رمز خطأ سالب في حالة الفشل. .UNINDENT .TP \fBlong bpf_redirect(u32 \fP\fIifindex\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إعادة توجيه الحزمة إلى جهاز شبكة آخر بالفهرس \fIifindex\fP\&. تشبه هذه الدالة المساعدة إلى حد ما \fBbpf_clone_redirect\fP()، باستثناء أنه لا يتم استنساخ الحزمة، مما يوفر أداءً أفضل. .sp باستثناء XDP، يمكن استخدام واجهتي الدخول والخروج لإعادة التوجيه. تُستخدم قيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز بينهما (يُختار مسار الدخول في حالة وجود العلامة، ومسار الخروج بخلاف ذلك). حاليًا، يدعم XDP فقط إعادة التوجيه إلى واجهة الخروج، ولا يقبل أي علامات على الإطلاق. .sp يمكن أيضًا تحقيق نفس التأثير باستخدام \fBbpf_redirect_map\fP() الأكثر عمومية، والتي تستخدم خريطة BPF لتخزين هدف إعادة التوجيه بدلاً من تقديمه مباشرةً إلى الدالة المساعدة. .TP \fBالقيمة المعادة\fP بالنسبة لـ XDP، تعيد الدالة المساعدة \fBXDP_REDIRECT\fP عند النجاح أو \fBXDP_ABORTED\fP عند الخطأ. بالنسبة لأنواع البرامج الأخرى، تكون القيم \fBTC_ACT_REDIRECT\fP عند النجاح أو \fBTC_ACT_SHOT\fP عند الخطأ. .UNINDENT .TP \fBu32 bpf_get_route_realm(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP جلب المجال (realm) أو المسار، أي حقل \fBtclassid\fP للوجهة لـ \fIskb\fP\&. المعرف الذي جُلب هو وسم يوفره المستخدم، يشبه ذاك المستخدم مع net_cls cgroup (انظر وصف الدالة المساعدة \fBbpf_get_cgroup_classid\fP())، ولكن هنا يحمل هذا الوسم مسار (إدخال وجهة)، وليس مهمة. .sp يعمل جلب هذا المعرف مع خطاف خروج clsact TC (انظر أيضًا \fBtc\-bpf(8)\fP)، أو بدلاً من ذلك على qdiscs الخروج التقليدية المصنفة، ولكن ليس على مسار دخول TC. في حالة خطاف خروج clsact TC، فإن هذا له ميزة أنه، داخليًا، لم يتم إسقاط إدخال الوجهة بعد في مسار الإرسال. لذلك، لا يحتاج إدخال الوجهة إلى الإبقاء عليه اصطناعيًا عبر \fBnetif_keep_dst\fP() لـ qdisc مصنف حتى يتم تحرير \fIskb\fP. .sp هذه الدالة المساعدة متاحة فقط إذا جُمعت النواة مع خيار الإعداد \fBCONFIG_IP_ROUTE_CLASSID\fP. .TP \fBالقيمة المعادة\fP مجال المسار للحزمة المرتبطة بـ \fIskb\fP، أو 0 إذا لم يُعثر على أي منها. .UNINDENT .TP \fBlong bpf_perf_event_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP كتابة كتلة \fIdata\fP خام في حدث أداء BPF خاص تحتفظ به \fImap\fP من نوع \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. يجب أن يحتوي حدث الأداء هذا على السمات التالية: \fBPERF_SAMPLE_RAW\fP كـ \fBsample_type\fP، و \fBPERF_TYPE_SOFTWARE\fP كـ \fBtype\fP، و \fBPERF_COUNT_SW_BPF_OUTPUT\fP كـ \fBconfig\fP\&. .sp تُستخدم الـ \fIflags\fP للإشارة إلى الفهرس في \fImap\fP الذي يجب وضع القيمة فيه، مقنعًا بـ \fBBPF_F_INDEX_MASK\fP\&. بدلاً من ذلك، يمكن ضبط \fIflags\fP على \fBBPF_F_CURRENT_CPU\fP للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي. .sp القيمة المراد كتابتها، ذات الحجم \fIsize\fP، تُمرر عبر مكدس eBPF ويؤشر إليها بـ \fIdata\fP\&. .sp يجب أيضًا تمرير سياق البرنامج \fIctx\fP إلى الدالة المساعدة. .sp في فضاء المستخدم، يحتاج البرنامج الذي يرغب في قراءة القيم إلى استدعاء \fBperf_event_open\fP() على حدث الأداء (إما لمعالج واحد أو لجميع المعالجات) وتخزين واصف الملف في الـ \fImap\fP\&. يجب القيام بذلك قبل أن يتمكن برنامج eBPF من إرسال البيانات إليه. يتوفر مثال في الملف \fIsamples/bpf/trace_output_user.c\fP في شجرة مصادر نواة لينكس (نظيره في برنامج eBPF موجود في \fIsamples/bpf/trace_output.bpf.c\fP). .sp تحقق \fBbpf_perf_event_output\fP() أداءً أفضل من \fBbpf_trace_printk\fP() لمشاركة البيانات مع فضاء المستخدم، وهي مناسبة أكثر بكثير لتدفق البيانات من برامج eBPF. .sp لاحظ أن هذه الدالة المساعدة لا تقتصر على حالات استخدام التتبع ويمكن استخدامها مع البرامج المتصلة بـ TC أو XDP أيضًا، حيث تسمح بتمرير البيانات إلى مستمعي فضاء المستخدم. يمكن أن تكون البيانات: .INDENT 7.0 .IP \(bu 2 هياكل (structs) مخصصة فقط، .IP \(bu 2 حمولة الحزمة فقط، أو .IP \(bu 2 مزيج من الاثنين. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_load_bytes(const void *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP وُفرت هذه الدالة المساعدة كطريقة سهلة لتحميل البيانات من حزمة. يمكن استخدامها لتحميل \fIlen\fP من البايتات من الإزاحة \fIoffset\fP من الحزمة المرتبطة بـ \fIskb\fP، إلى المخزن المؤقت الذي يشير إليه \fIto\fP\&. .sp منذ إصدار لينكس 4.7، استُبدل استخدام هذه الدالة المساعدة في الغالب بـ "الوصول المباشر للحزمة"، مما يتيح معالجة بيانات الحزمة باستخدام \fIskb\fP\fB\->data\fP و \fIskb\fP\fB\->data_end\fP اللذين يشيران على التوالي إلى أول بايت من بيانات الحزمة وإلى البايت الذي يلي آخر بايت من بيانات الحزمة. ومع ذلك، فإنها تظل مفيدة إذا رغب المرء في قراءة كميات كبيرة من البيانات مرة واحدة من حزمة إلى مكدس eBPF. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_get_stackid(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP السير في مكدس مستخدم أو مكدس نواة وإعادة معرفه. لتحقيق ذلك، تحتاج الدالة المساعدة إلى \fIctx\fP، وهو مؤشر إلى السياق الذي يتم تنفيذ برنامج التتبع عليه، ومؤشر إلى \fImap\fP من نوع \fBBPF_MAP_TYPE_STACK_TRACE\fP\&. .sp الوسيط الأخير، \fIflags\fP، يحمل عدد إطارات المكدس التي يجب تخطيها (من 0 إلى 255)، مقنعًا بـ \fBBPF_F_SKIP_FIELD_MASK\fP\&. يمكن استخدام البتات التالية لضبط مزيج من العلامات التالية: .INDENT 7.0 .TP \fBBPF_F_USER_STACK\fP جمع مكدس فضاء المستخدم بدلاً من مكدس النواة. .TP \fBBPF_F_FAST_STACK_CMP\fP مقارنة المكدسات عن طريق التجزئة (hash) فقط. .TP \fBBPF_F_REUSE_STACKID\fP إذا تم تجزئة مكدسين مختلفين إلى نفس الـ \fIstackid\fP، فتخلص من القديم. .UNINDENT .sp معرف المكدس الذي جُلب هو مقبض عدد صحيح بطول 32 بت يمكن دمجه لاحقًا مع بيانات أخرى (بما في ذلك معرفات المكدس الأخرى) واستخدامه كمفتاح في الخرائط. يمكن أن يكون هذا مفيدًا لإنشاء مجموعة متنوعة من الرسوم البيانية (مثل الرسوم البيانية اللهبية flame graphs أو رسوم بيانية خارج المعالج off\-cpu graphs). .sp للسير في مكدس، تعد هذه الدالة المساعدة تحسينًا لـ \fBbpf_probe_read\fP()، التي يمكن استخدامها مع الحلقات المفرودة ولكنها ليست فعالة وتستهلك الكثير من تعليمات eBPF. بدلاً من ذلك، يمكن لـ \fBbpf_get_stackid\fP() جمع ما يصل إلى \fBPERF_MAX_STACK_DEPTH\fP من إطارات النواة والمستخدم على حد سواء. لاحظ أنه يمكن التحكم في هذا الحد باستخدام برنامج \fBsysctl\fP، وأنه ينبغي زيادته يدويًا من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج جافا). للقيام بذلك، استخدم: .INDENT 7.0 .INDENT 3.5 .sp .EX # sysctl kernel.perf_event_max_stack=<القيمة الجديدة> .EE .UNINDENT .UNINDENT .TP \fBالقيمة المعادة\fP معرف المكدس الموجب أو صفر عند النجاح، أو خطأ سالب في حالة الفشل. .UNINDENT .TP \fBs64 bpf_csum_diff(__be32 *\fP\fIfrom\fP\fB, u32 \fP\fIfrom_size\fP\fB, __be32 *\fP\fIto\fP\fB, u32 \fP\fIto_size\fP\fB, __wsum \fP\fIseed\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حساب فرق مجموع التحقق، من المخزن المؤقت الخام الذي يشير إليه \fIfrom\fP، وبطول \fIfrom_size\fP (الذي يجب أن يكون من مضاعفات 4)، باتجاه المخزن المؤقت الخام الذي يشير إليه \fIto\fP، وبحجم \fIto_size\fP (نفس الملاحظة). يمكن إضافة \fIseed\fP اختيارية إلى القيمة (يمكن تسلسل هذا، فقد تأتي البذرة من استدعاء سابق للدالة المساعدة). .sp هذا مرن بما يكفي لاستخدامه بعدة طرق: .INDENT 7.0 .IP \(bu 2 عندما تكون \fIfrom_size\fP == 0، و \fIto_size\fP > 0 وضبط \fIseed\fP على مجموع التحقق، يمكن استخدامها عند دفع بيانات جديدة. .IP \(bu 2 عندما تكون \fIfrom_size\fP > 0، و \fIto_size\fP == 0 وضبط \fIseed\fP على مجموع التحقق، يمكن استخدامها عند إزالة بيانات من حزمة. .IP \(bu 2 عندما تكون \fIfrom_size\fP > 0، و \fIto_size\fP > 0 وضبط \fIseed\fP على 0، يمكن استخدامها لحساب الفرق. لاحظ أن \fIfrom_size\fP و \fIto_size\fP لا يلزم أن يكونا متساويين. .UNINDENT .sp يمكن استخدام هذه الدالة المساعدة بالاشتراك مع \fBbpf_l3_csum_replace\fP() و \fBbpf_l4_csum_replace\fP()، حيث يمكن تزويدهما بالفرق المحسوب باستخدام \fBbpf_csum_diff\fP(). .TP \fBالقيمة المعادة\fP نتيجة مجموع التحقق، أو رمز خطأ سالب في حالة الفشل. .UNINDENT .TP \fBlong bpf_skb_get_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP جلب بيانات خيارات النفق الوصفية للحزمة المرتبطة بـ \fIskb\fP، وتخزين بيانات خيارات النفق الخام في المخزن المؤقت \fIopt\fP ذي الحجم \fIsize\fP\&. .sp يمكن استخدام هذه الدالة المساعدة مع أجهزة التغليف التي يمكنها العمل في وضع "جمع البيانات الوصفية" (يرجى الرجوع إلى الملاحظة ذات الصلة في وصف \fBbpf_skb_get_tunnel_key\fP() لمزيد من التفاصيل). من الأمثلة المحددة حيث يمكن استخدام ذلك، بالاشتراك مع بروتوكول تغليف Geneve، حيث يسمح بدفع (باستخدام الدالة المساعدة \fBbpf_skb_get_tunnel_opt\fP()) وجلب TLVs (ترويسات النوع\-الطول\-القيمة) العشوائية من برنامج eBPF. يتيح ذلك التخصيص الكامل لهذه الترويسات. .TP \fBالقيمة المعادة\fP حجم بيانات الخيار التي جُلبت. .UNINDENT .TP \fBlong bpf_skb_set_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ضبط بيانات خيارات النفق الوصفية للحزمة المرتبطة بـ \fIskb\fP لتكون بيانات الخيار الواردة في المخزن المؤقت الخام \fIopt\fP ذي الحجم \fIsize\fP\&. .sp انظر أيضًا وصف الدالة المساعدة \fBbpf_skb_get_tunnel_opt\fP() لمزيد من المعلومات. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_change_proto(struct sk_buff *\fP\fIskb\fP\fB, __be16 \fP\fIproto\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تغيير بروتوكول \fIskb\fP إلى \fIproto\fP\&. المدعوم حاليًا هو الانتقال من IPv4 إلى IPv6، ومن IPv6 إلى IPv4. تتولى الدالة المساعدة العمل الأساس للانتقال، بما في ذلك تغيير حجم مخزن المقبس المؤقت. يُتوقع من برنامج eBPF ملء الترويسات الجديدة، إن وجدت، عبر \fBskb_store_bytes\fP() وإعادة حساب مجموع التحقق باستخدام \fBbpf_l3_csum_replace\fP() و \fBbpf_l4_csum_replace\fP(). الحالة الرئيسة لهذه الدالة المساعدة هي تنفيذ عمليات NAT64 من برنامج eBPF. .sp داخليًا، وُسم نوع GSO بأنه مريب (dodgy) بحيث تُفحص الترويسات وتُعاد حساب الأجزاء بواسطة محرك GSO/GRO. كما كُيف حجم هدف GSO أيضًا. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_change_type(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fItype\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تغيير نوع الحزمة للحزمة المرتبطة بـ \fIskb\fP\&. يتلخص هذا في ضبط \fIskb\fP\fB\->pkt_type\fP على \fItype\fP، باستثناء أن برنامج eBPF ليس لديه وصول للكتابة إلى \fIskb\fP\fB\->pkt_type\fP بخلاف هذه الدالة المساعدة. يسمح استخدام دالة مساعدة هنا بالتعامل السلس مع الأخطاء. .sp حالة الاستخدام الرئيسة هي تغيير الـ \fIskb*s القادمة إلى **PACKET_HOST*\fP بطريقة برمجية بدلاً من الاضطرار إلى إعادة التدوير عبر \fBredirect\fP(..., \fBBPF_F_INGRESS\fP)، على سبيل المثال. .sp لاحظ أن \fItype\fP يسمح بقيم معينة فقط. في الوقت الحالي، هي: .INDENT 7.0 .TP \fBPACKET_HOST\fP الحزمة مخصصة لنا. .TP \fBPACKET_BROADCAST\fP إرسال الحزمة للجميع. .TP \fBPACKET_MULTICAST\fP إرسال الحزمة لمجموعة. .TP \fBPACKET_OTHERHOST\fP إرسال الحزمة لشخص آخر. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_under_cgroup(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32 \fP\fIindex\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP التحقق مما إذا كانت \fIskb\fP سليلًا لـ cgroup2 التي تحتفظ بها \fImap\fP من نوع \fBBPF_MAP_TYPE_CGROUP_ARRAY\fP، عند \fIindex\fP\&. .TP \fBالقيمة المعادة\fP تعتمد قيمة الإرجاع على نتيجة الاختبار، ويمكن أن تكون: .INDENT 7.0 .IP \(bu 2 0، إذا فشل \fIskb\fP في اختبار سليل cgroup2. .IP \(bu 2 1، إذا اجتاز \fIskb\fP اختبار سليل cgroup2. .IP \(bu 2 رمز خطأ سالب، في حال حدوث خطأ. .UNINDENT .UNINDENT .TP \fBu32 bpf_get_hash_recalc(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استعد خبيئة الحزمة، \fIskb\fP\fB\->hash\fP\&. إذا لم تكن مضبوطة، لا سيما إذا مُسحت الخبيئة بسبب التلاعب، فأعد حساب هذه الخبيئة. يمكن إجراء عمليات الوصول اللاحقة للخبيئة مباشرة عبر \fIskb\fP\fB\->hash\fP\&. .sp استدعاء ()\fBbpf_set_hash_invalid\fP، أو تغيير نموذج حزمة أولي باستخدام ()\fBbpf_skb_change_proto\fP، أو استدعاء ()\fBbpf_skb_store_bytes\fP مع \fBBPF_F_INVALIDATE_HASH\fP هي إجراءات عرضة لمسح الخبيئة ولتحفيز حساب جديد عند الاستدعاء التالي لـ ()\fBbpf_get_hash_recalc\fP. .TP \fBالقيمة المعادة\fP الخبيئة ذات 32 بت. .UNINDENT .TP \fBu64 bpf_get_current_task(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على المهمة الحالية. .TP \fBالقيمة المعادة\fP مؤشر إلى بنية المهمة الحالية. .UNINDENT .TP \fBlong bpf_probe_write_user(void *\fP\fIdst\fP\fB, const void *\fP\fIsrc\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حاول بطريقة آمنة كتابة عدد \fIlen\fP من البايتات من المخزن المؤقت \fIsrc\fP إلى \fIdst\fP في الذاكرة. يعمل هذا فقط مع الخيوط التي تكون في سياق المستخدم، ويجب أن يكون \fIdst\fP عنواناً صحيحاً في مساحة المستخدم. .sp يجب ألا يُستخدم هذا المساعد لتنفيذ أي نوع من آليات الأمان بسبب هجمات TOC\-TOU، بل يُستخدم بدلاً من ذلك لتنقيح وتحويل والتلاعب بتنفيذ العمليات شبه التعاونية. .sp ضع في حسبانك أن هذه الميزة مخصصة للتجارب، وهي تنطوي على خطر إيقاف النظام والبرامج المشغلة. لذلك، عند وصل برنامج eBPF يستخدم هذا المساعد، يُطبع تحذير يتضمن معرف العملية (PID) واسم العملية في سجلات النواة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_current_task_under_cgroup(struct bpf_map *\fP\fImap\fP\fB, u32 \fP\fIindex\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحقق مما إذا كان المسبار يُشغّل في سياق مجموعة فرعية معينة من هيكلية cgroup2. مجموعة cgroup2 المطلوب اختبارها محفوظة في \fImap\fP من نوع \fBBPF_MAP_TYPE_CGROUP_ARRAY\fP، عند الـ \fIindex\fP\&. .TP \fBالقيمة المعادة\fP تعتمد قيمة الإرجاع على نتيجة الاختبار، ويمكن أن تكون: .INDENT 7.0 .IP \(bu 2 1، إذا كانت المهمة الحالية تنتمي إلى cgroup2. .IP \(bu 2 0، إذا كانت المهمة الحالية لا تنتمي إلى cgroup2. .IP \(bu 2 رمز خطأ سالب، في حال حدوث خطأ. .UNINDENT .UNINDENT .TP \fBlong bpf_skb_change_tail(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد ضبط حجم (تقليص أو تنمية) الحزمة المرتبطة بـ \fIskb\fP إلى الطول \fIlen\fP الجديد\&. تُحجز الـ \fIflags\fP للاستخدام المستقبلي، ويجب تركها عند الصفر. .sp الفكرة الأساسية هي أن المساعد يقوم بالعمل المطلوب لتغيير حجم الحزمة، ثم يعيد برنامج eBPF كتابة الباقي عبر مساعدين مثل ()\fBbpf_skb_store_bytes\fP و ()\fBbpf_l3_csum_replace\fP و ()\fBbpf_l3_csum_replace\fP وغيرها. هذا المساعد هو أداة للمسار البطيء مخصصة للردود برسائل التحكم. ولأنه يستهدف المسار البطيء، يمكن للمساعد نفسه أن يكون بطيئاً: فهو يقوم بـ خطيّة (linearize) وإلغاء الاستنساخ (unclone) وإسقاط التفريغات (offloads) من الـ \fIskb\fP بشكل ضمني. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_pull_data(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اسحب البيانات غير الخطية في حالة كون \fIskb\fP غير خطي ولم تكن كامل الـ \fIlen\fP جزءاً من القسم الخطي. اجعل عدد \fIlen\fP بايت من \fIskb\fP قابلة للقراءة والكتابة. إذا مُررت قيمة صفر لـ \fIlen\fP، فستُجعل جميع البايتات في الجزء الخطي من \fIskb\fP قابلة للقراءة والكتابة. .sp هذا المساعد مطلوب فقط للقراءة والكتابة مع الوصول المباشر للحزمة. .sp بالنسبة للوصول المباشر للحزمة، فإن اختبار أن الإزاحات للوصول تقع ضمن حدود الحزمة (اختبار على \fIskb\fP\fB\->data_end\fP) معرض للفشل إذا كانت الإزاحات غير صحيحة، أو إذا كانت البيانات المطلوبة في أجزاء غير خطية من الـ \fIskb\fP\&. عند الفشل يمكن للبرنامج الخروج ببساطة، أو في حالة وجود مخزن مؤقت غير خطي، استخدم مساعداً لإتاحة البيانات. المساعد ()\fBbpf_skb_load_bytes\fP هو حل أول للوصول إلى البيانات. والحل الآخر يتمثل في استخدام \fBbpf_skb_pull_data\fP لسحب الأجزاء غير الخطية مرة واحدة، ثم إعادة الاختبار والوصول إلى البيانات في النهاية. .sp في الوقت نفسه، يضمن هذا أيضاً أن الـ \fIskb\fP غير مستنسخ، وهو شرط ضروري للكتابة المباشرة. وبما أن هذا يجب أن يكون ثابتاً لـ جزء الكتابة فقط، فإن الفاحص (verifier) يكتشف عمليات الكتابة ويضيف تمهيداً (prologue) يستدعي ()\fBbpf_skb_pull_data\fP لإلغاء استنساخ \fIskb\fP فعلياً من البداية في حال كان مستنسخاً بالفعل. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBs64 bpf_csum_update(struct sk_buff *\fP\fIskb\fP\fB, __wsum \fP\fIcsum\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أضف مجموع التدقيق \fIcsum\fP إلى \fIskb\fP\fB\->csum\fP في حال قام التعريف بتزويد مجموع تدقيق لكامل الحزمة في ذلك الحقل. أعِد خطأً خلاف ذلك. هذا المساعد مخصص للاستخدام مع ()\fBbpf_csum_diff\fP، لا سيما عندما يلزم تحديث مجموع التدقيق بعد كتابة البيانات في الحزمة عبر الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP مجموع التدقيق عند النجاح، أو رمز خطأ سالب في حال الفشل. .UNINDENT .TP \fBvoid bpf_set_hash_invalid(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أبطل قيمة \fIskb\fP\fB\->hash\fP الحالية\&. يمكن استخدامها بعد التلاعب بالترويسات عبر الوصول المباشر للحزمة، للإشارة إلى أن الخبيئة قديمة ولتحفيز إعادة الحساب في المرة القادمة التي تحاول فيها النواة الوصول لهذه الخبيئة أو عند استدعاء مساعد ()\fBbpf_get_hash_recalc\fP. .TP \fBالقيمة المعادة\fP void. .UNINDENT .TP \fBlong bpf_get_numa_node_id(void)\fP .INDENT 7.0 .TP \fBالوصف\fP أعِد معرف عقدة NUMA الحالية. حالة الاستخدام الرئيسة لهذا المساعد هي اختيار المقابس لعقدة NUMA المحلية، عندما يكون البرنامج موصولاً بالمقابس باستخدام خيار \fBSO_ATTACH_REUSEPORT_EBPF\fP (انظر أيضاً \fBsocket(7)\fP)، ولكن المساعد متاح أيضاً لأنواع برامج eBPF الأخرى، بشكل مشابه لـ ()\fBbpf_get_smp_processor_id\fP. .TP \fBالقيمة المعادة\fP معرف عقدة NUMA الحالية. .UNINDENT .TP \fBlong bpf_skb_change_head(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ينمي مقدمة (headroom) الحزمة المرتبطة بـ \fIskb\fP ويضبط إزاحة ترويسة MAC وفقاً لذلك، مضيفاً مساحة قدرها \fIlen\fP بايت. يقوم آلياً بتوسيع وإعادة تخصيص الذاكرة حسب الحاجة. .sp يمكن استخدام هذا المساعد على \fIskb\fP من الطبقة 3 لدفع ترويسة MAC لـ إعادة التوجيه إلى جهاز من الطبقة 2. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_xdp_adjust_head(struct xdp_buff *\fP\fIxdp_md\fP\fB, int \fP\fIdelta\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط (انقل) \fIxdp_md\fP\fB\->data\fP بمقدار \fIdelta\fP بايت. لاحظ أنه من الممكن استخدام قيمة سالبة لـ \fIdelta\fP\&. يمكن استخدام هذا المساعد لـ تحضير الحزمة لدفع الترويسات أو سحبها. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_probe_read_str(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP انسخ سلسلة نصية منتهية بـ NUL من عنوان نواة غير آمن \fIunsafe_ptr\fP إلى \fIdst\fP\&. انظر ()\fBbpf_probe_read_kernel_str\fP لمزيد من التفاصيل. .sp بشكل عام، استخدم ()\fBbpf_probe_read_user_str\fP أو ()\fBbpf_probe_read_kernel_str\fP بدلاً من ذلك. .TP \fBالقيمة المعادة\fP عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة. .UNINDENT .TP \fBu64 bpf_get_socket_cookie(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إذا كان الـ \fBstruct sk_buff\fP الذي يشير إليه \fIskb\fP له مقبس معروف، فاستعد الكعكة (التي ولدتها النواة) لهذا المقبس. إذا لم تُضبط أي كعكة بعد، فولّد كعكة جديدة. بمجرد توليدها، تظل كعكة المقبس ثابتة طوال حياة المقبس. يمكن أن يكون هذا المساعد مفيداً لمراقبة إحصائيات حركة مرور الشبكة لكل مقبس لأنه يوفر معرف مقبس عاماً يمكن افتراض فرادته. .TP \fBالقيمة المعادة\fP رقم فريد بطول 8 بايت عند النجاح، أو 0 إذا كان حقل المقبس مفقوداً داخل \fIskb\fP\&. .UNINDENT .TP \fBu64 bpf_get_socket_cookie(struct bpf_sock_addr *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يكافئ مساعد ()bpf_get_socket_cookie الذي يقبل \fIskb\fP، ولكنه يحصل على المقبس من سياق \fBstruct bpf_sock_addr\fP. .TP \fBالقيمة المعادة\fP رقم فريد بطول 8 بايت. .UNINDENT .TP \fBu64 bpf_get_socket_cookie(struct bpf_sock_ops *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يكافئ مساعد ()\fBbpf_get_socket_cookie\fP الذي يقبل \fIskb\fP، ولكنه يحصل على المقبس من سياق \fBstruct bpf_sock_ops\fP. .TP \fBالقيمة المعادة\fP رقم فريد بطول 8 بايت. .UNINDENT .TP \fBu64 bpf_get_socket_cookie(struct sock *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يكافئ مساعد ()\fBbpf_get_socket_cookie\fP الذي يقبل \fIsk\fP، ولكنه يحصل على المقبس من BTF \fBstruct sock\fP\&. يعمل هذا المساعد أيضاً للبرامج القابلة للنوم. .TP \fBالقيمة المعادة\fP رقم فريد بطول 8 بايت أو 0 إذا كان \fIsk\fP فارغاً (NULL). .UNINDENT .TP \fBu32 bpf_get_socket_uid(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على معرف المستخدم (UID) للمالك للمقبس المرتبط بـ \fIskb\fP\&. .TP \fBالقيمة المعادة\fP معرف المستخدم (UID) للمالك للمقبس المرتبط بـ \fIskb\fP\&. إذا كان المقبس \fBNULL\fP، أو إذا لم يكن مقبساً كاملاً (أي إذا كان مقبس انتظار وقت أو مقبس طلب بدلاً من ذلك)، تُعاد قيمة \fBoverflowuid\fP (لاحظ أن \fBoverflowuid\fP قد تكون أيضاً قيمة UID الفعلية للمقبس). .UNINDENT .TP \fBlong bpf_set_hash(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIhash\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط الخبيئة الكاملة لـ \fIskb\fP (اضبط الحقل \fIskb\fP\fB\->hash\fP) على القيمة \fIhash\fP\&. .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_setsockopt(void *\fP\fIbpf_socket\fP\fB, int \fP\fIlevel\fP\fB, int \fP\fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int \fP\fIoptlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حاكَ استدعاءً لـ ()\fBsetsockopt\fP على المقبس المرتبط بـ \fIbpf_socket\fP، الذي يجب أن يكون مقبساً كاملاً. يجب تحديد المستوى (\fIlevel\fP) الذي يتواجد فيه الخيار واسم الخيار \fIoptname\fP، انظر (2)\fBsetsockopt\fP لمزيد من المعلومات. يشير \fIoptval\fP إلى قيمة الخيار ذات الطول \fIoptlen\fP\&. .sp يجب أن يكون \fIbpf_socket\fP واحداً مما يلي: .INDENT 7.0 .IP \(bu 2 \fBstruct bpf_sock_ops\fP لـ \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 \fBstruct bpf_sock_addr\fP لـ \fBBPF_CGROUP_INET4_CONNECT\fP و \fBBPF_CGROUP_INET6_CONNECT\fP و \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp ينفذ هذا المساعد فعلياً مجموعة فرعية من ()\fBsetsockopt\fP\&. وهو يدعم المستويات (\fIlevel\fPs) التالية: .INDENT 7.0 .IP \(bu 2 \fBSOL_SOCKET\fP، الذي يدعم الأسماء \fIoptname\fP التالية: \fBSO_RCVBUF\fP و \fBSO_SNDBUF\fP و \fBSO_MAX_PACING_RATE\fP و \fBSO_PRIORITY\fP و \fBSO_RCVLOWAT\fP و \fBSO_MARK\fP و \fBSO_BINDTODEVICE\fP و \fBSO_KEEPALIVE\fP و \fBSO_REUSEADDR\fP و \fBSO_REUSEPORT\fP و \fBSO_BINDTOIFINDEX\fP و \fBSO_TXREHASH\fP\&. .IP \(bu 2 \fBIPPROTO_TCP\fP، الذي يدعم الأسماء \fIoptname\fP التالية: \fBTCP_CONGESTION\fP و \fBTCP_BPF_IW\fP و \fBTCP_BPF_SNDCWND_CLAMP\fP و \fBTCP_SAVE_SYN\fP و \fBTCP_KEEPIDLE\fP و \fBTCP_KEEPINTVL\fP و \fBTCP_KEEPCNT\fP و \fBTCP_SYNCNT\fP و \fBTCP_USER_TIMEOUT\fP و \fBTCP_NOTSENT_LOWAT\fP و \fBTCP_NODELAY\fP و \fBTCP_MAXSEG\fP و \fBTCP_WINDOW_CLAMP\fP و \fBTCP_THIN_LINEAR_TIMEOUTS\fP و \fBTCP_BPF_DELACK_MAX\fP و \fBTCP_BPF_RTO_MIN\fP و \fBTCP_BPF_SOCK_OPS_CB_FLAGS\fP\&. .IP \(bu 2 \fBIPPROTO_IP\fP، الذي يدعم الاسم \fIoptname\fP للقيمة \fBIP_TOS\fP\&. .IP \(bu 2 \fBIPPROTO_IPV6\fP، الذي يدعم الأسماء \fIoptname\fP التالية: \fBIPV6_TCLASS\fP و \fBIPV6_AUTOFLOWLABEL\fP\&. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_adjust_room(struct sk_buff *\fP\fIskb\fP\fB, s32 \fP\fIlen_diff\fP\fB, u32 \fP\fImode\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP نمّ أو قلص مساحة البيانات في الحزمة المرتبطة بـ \fIskb\fP بمقدار \fIlen_diff\fP، ووفقاً للوضع (\fImode\fP) المحدد\&. .sp مبدئياً، سيعيد المساعد ضبط أي مؤشر مجموع تدقيق مفرغ (offloaded) في skb إلى CHECKSUM_NONE. يمكن تجنب ذلك عبر العلامة التالية: .INDENT 7.0 .IP \(bu 2 \fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP: لا تعد ضبط بيانات مجموع التدقيق المفرغة لـ skb إلى CHECKSUM_NONE. .UNINDENT .sp هناك وضعان مدعومان في هذا الوقت: .INDENT 7.0 .IP \(bu 2 \fBBPF_ADJ_ROOM_MAC\fP: اضبط المساحة في طبقة MAC (تُضاف مساحة أو تُزال بين ترويستي الطبقة 2 والطبقة 3). .IP \(bu 2 \fBBPF_ADJ_ROOM_NET\fP: اضبط المساحة في طبقة الشبكة (تُضاف مساحة أو تُزال بين ترويستي الطبقة 3 والطبقة 4). .UNINDENT .sp العلامات التالية مدعومة في هذا الوقت: .INDENT 7.0 .IP \(bu 2 \fBBPF_F_ADJ_ROOM_FIXED_GSO\fP: لا تضبط gso_size. ضبط mss بهذه الطريقة غير مسموح به لمخططات البيانات (datagrams). .IP \(bu 2 \fBBPF_F_ADJ_ROOM_ENCAP_L3_IPV4\fP و \fBBPF_F_ADJ_ROOM_ENCAP_L3_IPV6\fP: تُحجز أي مساحة جديدة لحفظ ترويسة نفق. اضبط إزاحات skb والحقول الأخرى وفقاً لذلك. .IP \(bu 2 \fBBPF_F_ADJ_ROOM_ENCAP_L4_GRE\fP و \fBBPF_F_ADJ_ROOM_ENCAP_L4_UDP\fP: استُخدمت مع علامات ENCAP_L3 لتحديد نوع النفق بشكل أكبر. .IP \(bu 2 \fBBPF_F_ADJ_ROOM_ENCAP_L2\fP(\fIlen\fP): استُخدمت مع علامات ENCAP_L3/L4 لتحديد نوع النفق بشكل أكبر؛ \fIlen\fP هي طول ترويسة MAC الداخلية. .IP \(bu 2 \fBBPF_F_ADJ_ROOM_ENCAP_L2_ETH\fP: استُخدمت مع علامة BPF_F_ADJ_ROOM_ENCAP_L2 لـ تحديد نوع الطبقة 2 كـ إيثرنت. .IP \(bu 2 \fBBPF_F_ADJ_ROOM_DECAP_L3_IPV4\fP و \fBBPF_F_ADJ_ROOM_DECAP_L3_IPV6\fP: تشير إلى إصدار ترويسة IP الجديد بعد فك تغليف ترويسة IP الخارجية. تُستخدم عندما تكون إصدارات IP الداخلية والخارجية مختلفة. .UNINDENT .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_redirect_map(struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعِد توجيه الحزمة إلى نقطة النهاية التي تشير إليها \fImap\fP عند الفهرس \fIkey\fP\&. اعتماداً على نوعها، يمكن أن تحتوي هذه الـ \fImap\fP على مراجع لأجهزة الشبكة (لتوجيه الحزم عبر منافذ أخرى)، أو لوحدات المعالجة المركزية (لإعادة توجيه إطارات XDP إلى وحدة معالجة أخرى؛ ولكن هذا منفذ فقط لـ XDP الأصيل (بدعم من التعريف) حتى وقت كتابة هذا النص). .sp تُستخدم البتات الدنيا لـ \fIflags\fP كرمز إعادة في حال فشل البحث في الخريطة. وذلك لكي تكون القيمة المعادة واحدة من رموز إعادة برنامج XDP حتى \fBXDP_TX\fP، كما يختارها المستدعي. يمكن ضبط البتات العليا لـ \fIflags\fP على BPF_F_BROADCAST أو BPF_F_EXCLUDE_INGRESS كما هو محدد أدناه. .sp باستخدام BPF_F_BROADCAST، ستُبث الحزمة إلى جميع الواجهات في الخريطة، ومع BPF_F_EXCLUDE_INGRESS، ستُستثنى واجهة الدخول (ingress) عند القيام بالبث. .sp انظر أيضاً ()\fBbpf_redirect\fP، الذي يدعم فقط إعادة التوجيه إلى ifindex، ولكنه لا يتطلب خريطة للقيام بذلك. .TP \fBالقيمة المعادة\fP \fBXDP_REDIRECT\fP عند النجاح، أو قيمة البتات الدنيا لمعطى \fIflags\fP عند الخطأ. .UNINDENT .TP \fBlong bpf_sk_redirect_map(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32 \fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعِد توجيه الحزمة إلى المقبس الذي تشير إليه \fImap\fP (من نوع \fBBPF_MAP_TYPE_SOCKMAP\fP) عند الفهرس \fIkey\fP\&. يمكن استخدام واجهات الدخول (ingress) والخروج (egress) لإعادة التوجيه. تُستخدم القيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز (يُختار مسار الدخول إذا كانت العلامة موجودة، ومسار الخروج خلاف ذلك). هذه هي العلامة الوحيدة المدعومة حالياً. .TP \fBالقيمة المعادة\fP \fBSK_PASS\fP عند النجاح، أو \fBSK_DROP\fP عند الخطأ. .UNINDENT .TP \fBlong bpf_sock_map_update(struct bpf_sock_ops *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أضف مدخلاً إلى خريطة \fImap\fP تشير إلى المقابس، أو حدثها. يُستخدم \fIskops\fP كقيمة جديدة للمدخل المرتبط بـ \fIkey\fP\&. الـ \fIflags\fP هي واحدة مما يلي: .INDENT 7.0 .TP \fBBPF_NOEXIST\fP يجب ألا تكون المدخلة لـ \fIkey\fP موجودة في الخريطة. .TP \fBBPF_EXIST\fP يجب أن تكون المدخلة لـ \fIkey\fP موجودة بالفعل في الخريطة. .TP \fBBPF_ANY\fP لا يوجد شرط على وجود المدخلة لـ \fIkey\fP\&. .UNINDENT .sp إذا كانت الخريطة \fImap\fP تحتوي على برامج eBPF (محلل وحكم)، فسوف يَرثها المقبس الذي أُضيف. إذا كان المقبس موصولاً بالفعل ببرامج eBPF، فسيؤدي ذلك إلى حدوث خطأ. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_xdp_adjust_meta(struct xdp_buff *\fP\fIxdp_md\fP\fB, int \fP\fIdelta\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط العنوان الذي يشير إليه \fIxdp_md\fP\fB\->data_meta\fP بمقدار \fIdelta\fP (التي يمكن أن تكون موجبة أو سالبة). لاحظ أن هذه العملية تعدل العنوان المخزن في \fIxdp_md\fP\fB\->data\fP، لذا يجب تحميل الأخير فقط بعد استدعاء المساعد. .sp يعد استخدام \fIxdp_md\fP\fB\->data_meta\fP اختياريًا ولا يُشترط على البرامج استخدامه. والسبب المنطقي هو أنه عند معالجة الحزمة باستخدام XDP (على سبيل المثال كمُلح DoS)، يمكن دفع المزيد من البيانات الوصفية (meta data) معها قبل تمريرها إلى المكدس، ولإعطاء ضمان بأن برنامج eBPF وارد (ingress) متصل كمصنف TC على الجهاز نفسه يمكنه التقاط هذه البيانات لمزيد من المعالجة اللاحقة. وبما أن TC يعمل مع مخازن المقابس المؤقتة (socket buffers)، يظل من الممكن ضبط مؤشرات \fBmark\fP أو \fBpriority\fP، أو مؤشرات أخرى لمخزن المقبس المؤقت من XDP. إن وجود مساحة العمل (scratch space) هذه بشكل عام وقابل للبرمجة يتيح مرونة أكبر حيث بإمكان المستخدم تخزين أي بيانات وصفية يحتاجها. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_perf_event_read_value(struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB, struct bpf_perf_event_value *\fP\fIbuf\fP\fB, u32 \fP\fIbuf_size\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يقرأ قيمة عداد أحداث الأداء (perf event counter)، ويخزنها في \fIbuf\fP بحجم \fIbuf_size\fP\&. يعتمد هذا المساعد على \fImap\fP من نوع \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. تُحدد طبيعة عداد أحداث الأداء عند تحديث \fImap\fP بواصفات ملفات أحداث الأداء. الـ \fImap\fP هي مصفوفة حجمها هو عدد وحدات المعالجة المركزية (CPUs) المتاحة، وكل خلية تحتوي على قيمة تتعلق بوحدة معالجة مركزية واحدة. تُشار القيمة المراد جلبها بواسطة \fIflags\fP، التي تحتوي على فهرس وحدة المعالجة المركزية للبحث عنها، مغطاة بـ \fBBPF_F_INDEX_MASK\fP\&. وبدلاً من ذلك، يمكن ضبط \fIflags\fP على \fBBPF_F_CURRENT_CPU\fP للإشارة إلى وجوب جلب القيمة الخاصة بوحدة المعالجة المركزية الحالية. .sp يسلك هذا المساعد سلوكًا قريبًا من المساعد \fBbpf_perf_event_read\fP()، باستثناء أنه بدلاً من مجرد إرجاع القيمة الملحوظة، فإنه يملأ بنية \fIbuf\fP. وهذا يسمح بجلب بيانات إضافية: لا سيما أوقات التمكين والتشغيل (في \fIbuf\fP\fB\->enabled\fP و \fIbuf\fP\fB\->running\fP، على التوالي) حيث تُنسخ. وبشكل عام، يُوصى باستخدام \fBbpf_perf_event_read_value\fP() بدلاً من \fBbpf_perf_event_read\fP()، الذي يعاني من بعض مشكلات ABI ويوفر وظائف أقل. .sp تعد هذه القيم مثيرة للاهتمام، لأن عدادات وحدة مراقبة الأداء العتادية (PMU) موارد محدودة. عندما يكون هناك عدد من أحداث الأداء القائمة على PMU المفتوحة أكثر من العدادات المتاحة، ستقوم الـ نواة بمضاعفة (multiplex) هذه الأحداث بحيث يحصل كل حدث على نسبة مئوية معينة (ولكن ليس كل) وقت PMU. وفي حالة حدوث هذا التضاعف، فإن عدد العينات أو قيمة العداد لن تعكس الحالة مقارنة بما إذا لم يحدث تضاعف. وهذا يجعل المقارنة بين التشغيلات المختلفة صعبة. عادةً، يجب تطبيع (normalize) قيمة العداد قبل مقارنتها بالتجارب الأخرى. ويُجرى التطبيع المعتاد على النحو التالي. .INDENT 7.0 .INDENT 3.5 .sp .EX normalized_counter = counter * t_enabled / t_running .EE .UNINDENT .UNINDENT .sp حيث t_enabled هو وقت التمكين للحدث و t_running هو وقت التشغيل للحدث منذ آخر تطبيع. تُراكم أوقات التمكين والتشغيل منذ فتح حدث الأداء. ولتحقيق عامل قياس بين استدعاءين لبرنامج eBPF، يمكن للمستخدمين استخدام معرف وحدة المعالجة المركزية (CPU id) كمفتاح (وهو أمر نموذجي لنموذج استخدام مصفوفة perf) لتذكر القيمة السابقة وإجراء الحساب داخل برنامج eBPF. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_perf_prog_read_value(struct bpf_perf_event_data *\fP\fIctx\fP\fB, struct bpf_perf_event_value *\fP\fIbuf\fP\fB, u32 \fP\fIbuf_size\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لبرنامج eBPF متصل بحدث أداء، يجلب قيمة عداد الحدث المرتبط بـ \fIctx\fP ويخزنها في البنية التي يشير إليها \fIbuf\fP وبحجم \fIbuf_size\fP\&. تُخزن أوقات التمكين والتشغيل أيضًا في البنية (انظر وصف المساعد \fBbpf_perf_event_read_value\fP() لمزيد من التفاصيل). .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_getsockopt(void *\fP\fIbpf_socket\fP\fB, int \fP\fIlevel\fP\fB, int \fP\fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int \fP\fIoptlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يحاكي استدعاء \fBgetsockopt()\fP على المقبس المرتبط بـ \fIbpf_socket\fP، والذي يجب أن يكون مقبساً كاملاً. يجب تحديد المستوى (\fIlevel\fP) الذي يوجد فيه الخيار واسم الخيار \fIoptname\fP، انظر \fBgetsockopt(2)\fP لمزيد من المعلومات. تُخزن القيمة المجلوبة في البنية التي يشير إليها \fIopval\fP وبطول \fIoptlen\fP\&. .sp يجب أن يكون \fIbpf_socket\fP واحداً مما يلي: .INDENT 7.0 .IP \(bu 2 \fBstruct bpf_sock_ops\fP لـ \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 \fBstruct bpf_sock_addr\fP لـ \fBBPF_CGROUP_INET4_CONNECT\fP و \fBBPF_CGROUP_INET6_CONNECT\fP و \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp ينفذ هذا المساعد في الواقع مجموعة فرعية من \fBgetsockopt()\fP\&. وهو يدعم نفس مجموعة \fIoptname\fP المدعومة من قبل المساعد \fBbpf_setsockopt\fP()\&. الاستثناءات هي \fBTCP_BPF_*\fP للمساعد \fBbpf_setsockopt\fP() فقط و \fBTCP_SAVED_SYN\fP للمساعد \fBbpf_getsockopt\fP() فقط. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_override_return(struct pt_regs *\fP\fIregs\fP\fB, u64 \fP\fIrc\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم لحقن الأخطاء، ويستخدم هذا المساعد kprobes لتجاوز قيمة الإرجاع للدالة المفحوصة، ولضبطها على \fIrc\fP\&. الوسيط الأول هو السياق \fIregs\fP الذي يعمل عليه kprobe. .sp يعمل هذا المساعد عن طريق ضبط PC (عداد البرنامج) على دالة تجاوز تُشغل بدلاً من الدالة الأصلية المفحوصة. وهذا يعني أن الدالة المفحوصة لا تُشغل على الإطلاق. تعود الدالة البديلة فقط بالقيمة المطلوبة. .sp لهذا المساعد تداعيات أمنية، وبالتالي يخضع لقيود. وهو متاح فقط إذا كانت الـ نواة قد جُمعت مع خيار الضبط \fBCONFIG_BPF_KPROBE_OVERRIDE\fP، وفي هذه الحالة لا يعمل إلا على الدوال الموسومة بـ \fBALLOW_ERROR_INJECTION\fP في كود النواة. .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_sock_ops_cb_flags_set(struct bpf_sock_ops *\fP\fIbpf_sock\fP\fB, int \fP\fIargval\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يحاول ضبط قيمة حقل \fBbpf_sock_ops_cb_flags\fP لمقبس TCP الكامل المرتبط بـ \fIbpf_sock_ops\fP إلى \fIargval\fP\&. .sp الاستخدام الرئيس لهذا الحقل هو تحديد ما إذا كان ينبغي إجراء استدعاءات لبرامج eBPF من نوع \fBBPF_PROG_TYPE_SOCK_OPS\fP في نقاط مختلفة في كود TCP. يمكن لبرنامج من نفس النوع تغيير قيمته، لكل اتصال وحسب الضرورة، عند إنشاء الاتصال. يمكن الوصول إلى هذا الحقل مباشرة للقراءة، ولكن يجب استخدام هذا المساعد للتحديثات من أجل إرجاع خطأ إذا حاول برنامج eBPF ضبط رد نداء (callback) غير مدعوم في النواة الحالية. .sp \fIargval\fP هي مصفوفة أعلام يمكنها دمج هذه الأعلام: .INDENT 7.0 .IP \(bu 2 \fBBPF_SOCK_OPS_RTO_CB_FLAG\fP (مهلة إعادة الإرسال) .IP \(bu 2 \fBBPF_SOCK_OPS_RETRANS_CB_FLAG\fP (إعادة الإرسال) .IP \(bu 2 \fBBPF_SOCK_OPS_STATE_CB_FLAG\fP (تغيير حالة TCP) .IP \(bu 2 \fBBPF_SOCK_OPS_RTT_CB_FLAG\fP (كل RTT) .UNINDENT .sp لذلك، يمكن استخدام هذه الدالة لمسح علم رد نداء عن طريق ضبط البت المناسب على الصفر. على سبيل المثال لتعطيل رد نداء RTO: .INDENT 7.0 .TP \fBbpf_sock_ops_cb_flags_set(bpf_sock,\fP \fBbpf_sock\->bpf_sock_ops_cb_flags & ~BPF_SOCK_OPS_RTO_CB_FLAG)\fP .UNINDENT .sp فيما يلي بعض الأمثلة على المواضع التي يمكن فيها استدعاء مثل هذا البرنامج eBPF: .INDENT 7.0 .IP \(bu 2 عند انطلاق RTO. .IP \(bu 2 عند إعادة إرسال حزمة. .IP \(bu 2 عند انتهاء الاتصال. .IP \(bu 2 عند إرسال حزمة. .IP \(bu 2 عند استلام حزمة. .UNINDENT .TP \fBالقيمة المعادة\fP الكود \fB\-EINVAL\fP إذا لم يكن المقبس مقبس TCP كاملاً؛ وبخلاف ذلك، يُرجع رقم موجب يحتوي على البتات التي تعذر ضبطها (وهو ما يؤول إلى 0 إذا ضُبطت جميع البتات كما هو مطلوب). .UNINDENT .TP \fBlong bpf_msg_redirect_map(struct sk_msg_buff *\fP\fImsg\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32 \fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى المقبس. إذا سُمح للرسالة \fImsg\fP بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة \fBSK_PASS\fP)، فسيُعاد توجيهها إلى المقبس المشار إليه بواسطة \fImap\fP (من نوع \fBBPF_MAP_TYPE_SOCKMAP\fP) عند الفهرس \fIkey\fP\&. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، ومسار الصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً. .TP \fBالقيمة المعادة\fP \fBSK_PASS\fP عند النجاح، أو \fBSK_DROP\fP عند الخطأ. .UNINDENT .TP \fBlong bpf_msg_apply_bytes(struct sk_msg_buff *\fP\fImsg\fP\fB, u32 \fP\fIbytes\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لسياسات المقبس، يطبق حكم برنامج eBPF على الـ \fIbytes\fP (عدد البايتات) التالية من الرسالة \fImsg\fP\&. .sp على سبيل المثال، يمكن استخدام هذا المساعد في الحالات التالية: .INDENT 7.0 .IP \(bu 2 استدعاء نظام واحد \fBsendmsg\fP() أو \fBsendfile\fP() يحتوي على عدة رسائل منطقية من المفترض أن يقرأها برنامج eBPF ويصدر حكماً بشأنها. .IP \(bu 2 برنامج eBPF يهتم فقط بقراءة الـ \fIbytes\fP الأولى من \fImsg\fP\&. إذا كانت للرسالة حمولة كبيرة، فإن إعداد واستدعاء برنامج eBPF بشكل متكرر لجميع البايتات، رغم أن الحكم معروف بالفعل، سيؤدي إلى عبء غير ضروري. .UNINDENT .sp عند استدعائه من داخل برنامج eBPF، يقوم المساعد بضبط عداد داخلي في بنية BPF التحتية، يُستخدم لتطبيق الحكم الأخير على الـ \fIbytes\fP التالية. إذا كان \fIbytes\fP أصغر من البيانات الحالية التي تُعالج من استدعاء نظام \fBsendmsg\fP() أو \fBsendfile\fP()، فسيُرسل الـ \fIbytes\fP الأول وسيُعاد تشغيل برنامج eBPF مع مؤشر بداية البيانات الذي يشير إلى البايت رقم \fIbytes\fP \fB+ 1\fP\&. إذا كان \fIbytes\fP أكبر من البيانات الحالية التي تُعالج، فسيُطبق حكم eBPF على عدة استدعاءات \fBsendmsg\fP() أو \fBsendfile\fP() حتى تُستهلك \fIbytes\fP. .sp لاحظ أنه إذا أُغلق المقبس والعداد الداخلي يحمل قيمة غير صفرية، فهذه ليست مشكلة لأن البيانات لا تُخزن مؤقتاً لـ \fIbytes\fP وتُرسل فور استلامها. .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_msg_cork_bytes(struct sk_msg_buff *\fP\fImsg\fP\fB, u32 \fP\fIbytes\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لسياسات المقبس، يمنع تنفيذ برنامج حكم eBPF للرسالة \fImsg\fP حتى يُجمع \fIbytes\fP (عدد بايتات). .sp يمكن استخدام هذا عندما يحتاج المرء إلى عدد معين من البايتات قبل أن يتمكن من تعيين حكم، حتى لو امتدت البيانات عبر عدة استدعاءات \fBsendmsg\fP() أو \fBsendfile\fP(). الحالة القصوى هي قيام مستخدم باستدعاء \fBsendmsg\fP() بشكل متكرر بقطع رسائل بطول 1 بايت. من الواضح أن هذا سيء للأداء، ولكنه لا يزال صالحاً. إذا كان برنامج eBPF يحتاج \fIbytes\fP بايت للتحقق من ترويسة، يمكن استخدام هذا المساعد لمنع استدعاء برنامج eBPF مرة أخرى حتى يُجمع \fIbytes\fP بايت. .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_msg_pull_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32 \fP\fIstart\fP\fB, u32 \fP\fIend\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لسياسات المقبس، يسحب البيانات غير الخطية من مساحة المستخدم لـ \fImsg\fP ويضبط المؤشرات \fImsg\fP\fB\->data\fP و \fImsg\fP\fB\->data_end\fP على إزاحات البايت \fIstart\fP و \fIend\fP في \fImsg\fP، على التوالي. .sp إذا أُشغل برنامج من نوع \fBBPF_PROG_TYPE_SK_MSG\fP على \fImsg\fP، فيمكنه فقط تحليل البيانات التي استهلكتها مؤشرات (\fBdata\fP, \fBdata_end\fP) بالفعل. بالنسبة لخطافات \fBsendmsg\fP()، فمن المرجح أن يكون هذا هو عنصر قائمة التشتت (scatterlist) الأول. ولكن بالنسبة للاستدعاءات التي تعتمد على معالج \fBsendpage\fP (مثل \fBsendfile\fP())، سيكون هذا النطاق هو (\fB0\fP, \fB0\fP) لأن البيانات مشتركة مع مساحة المستخدم والهدف افتراضياً هو تجنب السماح لمساحة المستخدم بتعديل البيانات أثناء (أو بعد) اتخاذ حكم eBPF. يمكن استخدام هذا المساعد لسحب البيانات وضبط مؤشر البداية والنهاية على قيم معطاة. ستُنسخ البيانات إذا لزم الأمر (أي إذا لم تكن البيانات خطية وإذا لم يشر مؤشرا البداية والنهاية إلى نفس القطعة). .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_bind(struct bpf_sock_addr *\fP\fIctx\fP\fB, struct sockaddr *\fP\fIaddr\fP\fB, int \fP\fIaddr_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يربط المقبس المرتبط بـ \fIctx\fP بالعنوان الذي يشير إليه \fIaddr\fP، بطول \fIaddr_len\fP\&. يسمح هذا بإجراء اتصال صادر من عنوان IP المنشود، والذي يمكن أن يكون مفيداً على سبيل المثال عندما ينبغي لجميع العمليات داخل cgroup استخدام عنوان IP واحد على مضيف تم ضبط عناوين IP متعددة عليه. .sp يعمل هذا المساعد لمقابس IPv4 و IPv6 و TCP و UDP. يجب أن يكون النطاق (\fIaddr\fP\fB\->sa_family\fP) هو \fBAF_INET\fP (أو \fBAF_INET6\fP). ويُنصح بتمرير منفذ صفري (\fBsin_port\fP أو \fBsin6_port\fP) مما يحفز سلوكاً مشابهاً لـ IP_BIND_ADDRESS_NO_PORT ويسمح للنواة باختيار منفذ غير مستخدم بكفاءة طالما أن الرباعية (4\-tuple) فريدة. قد يؤدي تمرير منفذ غير صفري إلى تدهور الأداء. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_xdp_adjust_tail(struct xdp_buff *\fP\fIxdp_md\fP\fB, int \fP\fIdelta\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يضبط (يحرك) \fIxdp_md\fP\fB\->data_end\fP بمقدار \fIdelta\fP بايت. ومن الممكن تقليص وتوسيع ذيل الحزمة. يُجرى التقليص عبر كون \fIdelta\fP عدداً صحيحاً سالباً. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_skb_get_xfrm_state(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIindex\fP\fB, struct bpf_xfrm_state *\fP\fIxfrm_state\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب حالة XFRM (إطار عمل تحويل IP، انظر أيضاً \fBip\-xfrm(8)\fP) عند \fIindex\fP في "المسار الأمني" لـ XFRM لـ \fIskb\fP\&. .sp تُخزن القيمة المجلوبة في \fBstruct bpf_xfrm_state\fP الذي يشير إليه \fIxfrm_state\fP وبطول \fIsize\fP\&. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .sp هذا المساعد متاح فقط إذا كانت الـ نواة قد جُمعت مع خيار الضبط \fBCONFIG_XFRM\fP. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_get_stack(void *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يرجع مكدساً للمستخدم أو للنواة في مخزن مؤقت يوفره برنامج bpf. ولتحقيق ذلك، يحتاج المساعد إلى \fIctx\fP، وهو مؤشر للسياق الذي يُنفذ فيه برنامج التتبع. ولتخزين تتبع المكدس (stacktrace)، يوفر برنامج bpf \fIbuf\fP مع \fIsize\fP غير سالب\&. .sp الوسيط الأخير، \fIflags\fP، يحمل عدد أطر المكدس المراد تخطيها (من 0 إلى 255)، مغطاة بـ \fBBPF_F_SKIP_FIELD_MASK\fP\&. ويمكن استخدام البتات التالية لضبط الأعلام التالية: .INDENT 7.0 .TP \fBBPF_F_USER_STACK\fP جمع مكدس فضاء المستخدم بدلاً من مكدس النواة. .TP \fBBPF_F_USER_BUILD_ID\fP يجمع (build_id، file_offset) بدلاً من عناوين ips لمكدس المستخدم، ولا يصلح إلا إذا حُدد \fBBPF_F_USER_STACK\fP أيضاً. .sp \fIfile_offset\fP هي إزاحة بالنسبة لبداية الملف القابل للتنفيذ أو الكائن المشترك الذي يدعم vma الذي يقع فيه \fIip\fP. وهي \fIليست\fP إزاحة بالنسبة لعنوان الأساس لهذا الكائن. وبناءً عليه، يجب تعديلها بإضافة (sh_addr \- sh_offset)، حيث يمثل sh_{addr,offset} قسم الملف القابل للتنفيذ الذي يحتوي على \fIfile_offset\fP في الكائن، لكي تكون المقارنات مع st_value للرموز صالحة. .UNINDENT .sp يمكن لـ \fBbpf_get_stack\fP() جمع ما يصل إلى \fBPERF_MAX_STACK_DEPTH\fP من كل من أطر الـ نواة والمستخدم، بشرط توفر حجم مخزن مؤقت كبير بما يكفي. لاحظ أن هذا الحد يمكن التحكم فيه باستخدام برنامج \fBsysctl\fP، وأنه ينبغي زيادته يدوياً من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج Java). وللقيام بذلك، استخدم: .INDENT 7.0 .INDENT 3.5 .sp .EX # sysctl kernel.perf_event_max_stack=<القيمة الجديدة> .EE .UNINDENT .UNINDENT .TP \fBالقيمة المعادة\fP طول \fIbuf\fP المنسوخ غير السالب المساوي لـ \fIsize\fP أو أقل منه عند النجاح، أو خطأ سالب في حالة الفشل. .UNINDENT .TP \fBlong bpf_skb_load_bytes_relative(const void *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32 \fP\fIlen\fP\fB, u32 \fP\fIstart_header\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP هذا المساعد مشابه لـ \fBbpf_skb_load_bytes\fP() في أنه يوفر طريقة سهلة لتحميل \fIlen\fP بايت من \fIoffset\fP من الحزمة المرتبطة بـ \fIskb\fP، إلى المخزن المؤقت الذي يشير إليه \fIto\fP\&. والفرق عن \fBbpf_skb_load_bytes\fP() هو وجود وسيط خامس \fIstart_header\fP من أجل اختيار إزاحة أساسية للبدء منها. يمكن لـ \fIstart_header\fP أن يكون أحد: .INDENT 7.0 .TP \fBBPF_HDR_START_MAC\fP الإزاحة الأساسية لتحميل البيانات منها هي ترويسة mac لـ \fIskb\fP. .TP \fBBPF_HDR_START_NET\fP الإزاحة الأساسية لتحميل البيانات منها هي ترويسة الشبكة لـ \fIskb\fP. .UNINDENT .sp بشكل عام، تعد "الوصول المباشر للحزمة" (direct packet access) هي الطريقة المفضلة للوصول إلى بيانات الحزمة، ومع ذلك، فإن هذا المساعد مفيد بشكل خاص في مرشحات المقابس حيث لا يشير \fIskb\fP\fB\->data\fP دائماً إلى بداية ترويسة mac وحيث لا يتوفر "الوصول المباشر للحزمة". .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_fib_lookup(void *\fP\fIctx\fP\fB, struct bpf_fib_lookup *\fP\fIparams\fP\fB, int \fP\fIplen\fP\fB, u32 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يقوم بالبحث في FIB (قاعدة معلومات التوجيه) في جداول الـ نواة باستخدام المعاملات في \fIparams\fP\&. إذا نجح البحث وأظهرت النتيجة وجوب توجيه الحزمة، فسيتم البحث في جداول الجوار (neighbor tables) عن القفزة التالية (nexthop). إذا نجح ذلك (أي أظهر بحث FIB التوجيه وحُلّت القفزة التالية)، يُرجع عنوان القفزة التالية في ipv4_dst أو ipv6_dst بناءً على العائلة، ويُضبط smac على عنوان mac لجهاز الصدور، ويُضبط dmac على عنوان mac للقفزة التالية، ويُضبط rt_metric على القياس (metric) من المسار (IPv4/IPv6 فقط)، ويُضبط ifindex على فهرس جهاز القفزة التالية من بحث FIB. .sp الوسيط \fIplen\fP هو حجم البنية الممررة. والوسيط \fIflags\fP يمكن أن يكون مزيجاً من واحد أو أكثر من القيم التالية: .INDENT 7.0 .TP \fBBPF_FIB_LOOKUP_DIRECT\fP يقوم ببحث مباشر في الجدول مقابل البحث الكامل باستخدام قواعد FIB. .TP \fBBPF_FIB_LOOKUP_TBID\fP يُستخدم مع BPF_FIB_LOOKUP_DIRECT. يستخدم معرف جدول التوجيه الموجود في \fIparams\fP\->tbid لبحث fib. .TP \fBBPF_FIB_LOOKUP_OUTPUT\fP ينفذ البحث من منظور الصدور (egress) (المبدئي هو الورود ingress). .TP \fBBPF_FIB_LOOKUP_SKIP_NEIGH\fP يتخطى بحث جدول الجوار. لن يُضبط \fIparams\fP\->dmac و \fIparams\fP\->smac كمخرجات. حالة الاستخدام الشائعة هي استدعاء \fBbpf_redirect_neigh\fP() بعد إجراء \fBbpf_fib_lookup\fP(). .TP \fBBPF_FIB_LOOKUP_SRC\fP يشتق ويضبط عنوان IP المصدر في \fIparams\fP\->ipv{4,6}_src للقفزة التالية. إذا تعذر اشتقاق عنوان المصدر، يُرجع \fBBPF_FIB_LKUP_RET_NO_SRC_ADDR\fP. في هذه الحالة، لن يُضبط \fIparams\fP\->dmac و \fIparams\fP\->smac أيضاً. .TP \fBBPF_FIB_LOOKUP_MARK\fP يستخدم العلامة (mark) الموجودة في \fIparams\fP\->mark لبحث fib. لا ينبغي استخدام هذا الخيار مع BPF_FIB_LOOKUP_DIRECT، لأنه ليس له معنى إلا في عمليات البحث الكاملة. .UNINDENT .sp \fIctx\fP هو إما \fBstruct xdp_md\fP لبرامج XDP أو برامج \fBstruct sk_buff\fP tc cls_act. .TP \fBالقيمة المعادة\fP .INDENT 7.0 .IP \(bu 2 < 0 إذا كان أي وسيط إدخال غير صالح .IP \(bu 2 0 عند النجاح (تُوجه الحزمة، وجار القفزة التالية موجود) .IP \(bu 2 > 0 واحد من أكواد \fBBPF_FIB_LKUP_RET_\fP التي توضح سبب عدم توجيه الحزمة أو حاجتها للمساعدة من المكدس الكامل .UNINDENT .sp إذا فشل البحث مع BPF_FIB_LKUP_RET_FRAG_NEEDED، فهذا يعني أنه تم تجاوز MTU ويحتوي الناتج params\->mtu_result على MTU. .UNINDENT .TP \fBlong bpf_sock_hash_update(struct bpf_sock_ops *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يضيف إدخالاً إلى، أو يحدث مخرطة مقابس (sockhash) \fImap\fP تشير إلى مقابس. يُستخدم \fIskops\fP كقيمة جديدة للإدخال المرتبط بـ \fIkey\fP\&. \fIflags\fP هي واحدة من: .INDENT 7.0 .TP \fBBPF_NOEXIST\fP يجب ألا تكون المدخلة لـ \fIkey\fP موجودة في الخريطة. .TP \fBBPF_EXIST\fP يجب أن تكون المدخلة لـ \fIkey\fP موجودة بالفعل في الخريطة. .TP \fBBPF_ANY\fP لا يوجد شرط على وجود المدخلة لـ \fIkey\fP\&. .UNINDENT .sp إذا كانت الخريطة \fImap\fP تحتوي على برامج eBPF (محلل وحكم)، فسوف يَرثها المقبس الذي أُضيف. إذا كان المقبس موصولاً بالفعل ببرامج eBPF، فسيؤدي ذلك إلى حدوث خطأ. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_msg_redirect_hash(struct sk_msg_buff *\fP\fImsg\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى المقبس. إذا سُمح للرسالة \fImsg\fP بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة \fBSK_PASS\fP)، فسيُعاد توجيهها إلى المقبس المشار إليه بواسطة \fImap\fP (من نوع \fBBPF_MAP_TYPE_SOCKHASH\fP) باستخدام مفتاح المخرطة \fIkey\fP\&. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، ومسار الصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً. .TP \fBالقيمة المعادة\fP \fBSK_PASS\fP عند النجاح، أو \fBSK_DROP\fP عند الخطأ. .UNINDENT .TP \fBlong bpf_sk_redirect_hash(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى مقبس skb. إذا سُمح لـ sk_buff \fIskb\fP بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة \fBSK_PASS\fP)، فسيُعاد توجيهه إلى المقبس المشار إليه بواسطة \fImap\fP (من نوع \fBBPF_MAP_TYPE_SOCKHASH\fP) باستخدام مفتاح المخرطة \fIkey\fP\&. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة \fBBPF_F_INGRESS\fP في \fIflags\fP للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، والصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً. .TP \fBالقيمة المعادة\fP \fBSK_PASS\fP عند النجاح، أو \fBSK_DROP\fP عند الخطأ. .UNINDENT .TP \fBlong bpf_lwt_push_encap(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fItype\fP\fB, void *\fP\fIhdr\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تغليف الحزمة المرتبطة بـ \fIskb\fP داخل ترويسة بروتوكول من الطبقة الثالثة. تُوفّر هذه الترويسة في المخزن المؤقت عند العنوان \fIhdr\fP، ويكون حجمها \fIlen\fP بالبايت. يشير \fItype\fP إلى بروتوكول الترويسة ويمكن أن يكون أحد القيم التالية: .INDENT 7.0 .TP \fBBPF_LWT_ENCAP_SEG6\fP تغليف IPv6 مع ترويسة توجيه المقاطع (\fBstruct ipv6_sr_hdr\fP). تحتوي \fIhdr\fP على SRH فقط، وتُحسب ترويسة IPv6 بواسطة النواة. .TP \fBBPF_LWT_ENCAP_SEG6_INLINE\fP يعمل فقط إذا احتوت \fIskb\fP على حزمة IPv6. يُدرج ترويسة توجيه المقاطع (\fBstruct ipv6_sr_hdr\fP) داخل ترويسة IPv6. .TP \fBBPF_LWT_ENCAP_IP\fP تغليف IP ‏(GRE/GUE/IPIP/إلخ). يجب أن تكون الترويسة الخارجية IPv4 أو IPv6، متبوعة بصفر أو أكثر من الترويسات الإضافية، بما يصل إلى \fBLWT_BPF_MAX_HEADROOM\fP بايت إجمالاً في جميع الترويسات الملحقة. يرجى ملاحظة أنه إذا كانت \fBskb_is_gso\fP(\fIskb\fP) صحيحة، فلا يمكن إلحاق أكثر من ترويستين، ويجب أن تكون الترويسة الداخلية، إن وجدت، إما GRE أو UDP/GUE. .UNINDENT .sp يمكن استدعاء أنواع *\fBBPF_LWT_ENCAP_SEG6\fP بواسطة برامج BPF من النوع \fBBPF_PROG_TYPE_LWT_IN\fP؛ ويمكن استدعاء النوع \fBBPF_LWT_ENCAP_IP\fP بواسطة برامج bpf من الأنواع \fBBPF_PROG_TYPE_LWT_IN\fP و \fBBPF_PROG_TYPE_LWT_XMIT\fP\&. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_lwt_seg6_store_bytes(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, const void *\fP\fIfrom\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يخزن \fIlen\fP بايت من العنوان \fIfrom\fP في الحزمة المرتبطة بـ \fIskb\fP، عند الإزاحة \fIoffset\fP\&. يمكن تعديل الأعلام والوسم و TLVs فقط داخل ترويسة توجيه المقاطع IPv6 الخارجية القصوى من خلال هذا المساعد. .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_lwt_seg6_adjust_srh(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIoffset\fP\fB, s32 \fP\fIdelta\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ضبط الحجم المخصص لـ TLVs في ترويسة IPv6 Segment Routing الخارجية الموجودة في الحزمة المرتبطة بـ \fIskb\fP، عند الموضع \fIoffset\fP بمقدار \fIdelta\fP بايت. لا تُقبل إلا الإزاحات التي تلي الأجزاء (segments). يمكن أن تكون \fIdelta\fP موجبة (للتوسيع) أو سالبة (للتقليص). .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_lwt_seg6_action(struct sk_buff *\fP\fIskb\fP\fB, u32 \fP\fIaction\fP\fB, void *\fP\fIparam\fP\fB, u32 \fP\fIparam_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يطبق إجراء توجيه مقاطع IPv6 من النوع \fIaction\fP على الحزمة المرتبطة بـ \fIskb\fP\&. يأخذ كل إجراء معطىً محتوًى في العنوان \fIparam\fP، وبطول \fIparam_len\fP بايت. يمكن أن يكون \fIaction\fP أحد: .INDENT 7.0 .TP \fBSEG6_LOCAL_ACTION_END_X\fP إجراء End.X: نقطة نهاية مع اتصال عرضي من الطبقة الثالثة. نوع \fIparam\fP: \fBstruct in6_addr\fP\&. .TP \fBSEG6_LOCAL_ACTION_END_T\fP إجراء End.T: نقطة نهاية مع بحث في جدول IPv6 محدد. نوع \fIparam\fP: \fBint\fP\&. .TP \fBSEG6_LOCAL_ACTION_END_B6\fP إجراء End.B6: نقطة نهاية مقيدة بسياسة SRv6. نوع \fIparam\fP: \fBstruct ipv6_sr_hdr\fP\&. .TP \fBSEG6_LOCAL_ACTION_END_B6_ENCAP\fP إجراء End.B6.Encap: نقطة نهاية مقيدة بسياسة تغليف SRv6. نوع \fIparam\fP: \fBstruct ipv6_sr_hdr\fP\&. .UNINDENT .sp استدعاء هذا المساعد عرضة لتغيير مخزن الحزمة المؤقت الأساسي. لذلك، عند وقت التحميل، تُبطل جميع الفحوصات على المؤشرات التي أجراها المحقق مسبقاً ويجب إجراؤها مرة أخرى، إذا استخدم المساعد بالاشتراك مع الوصول المباشر للحزمة. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_rc_repeat(void *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ فك ترميز الأشعة تحت الحمراء (IR)، للإبلاغ عن رسالة تكرار مفتاح فُك ترميزها بنجاح. يؤخر هذا توليد حدث رفع المفتاح لحدث ضغط المفتاح المولد سابقاً. .sp تحتوي بعض بروتوكولات الأشعة تحت الحمراء مثل NEC على رسالة IR خاصة لتكرار الزر الأخير، وذلك عند الاستمرار في الضغط على الزر. .sp يجب أن تشير \fIctx\fP إلى عينة lirc كما مررت إلى البرنامج. .sp هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين \fBCONFIG_BPF_LIRC_MODE2\fP على "\fBy\fP". .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_rc_keydown(void *\fP\fIctx\fP\fB, u32 \fP\fIprotocol\fP\fB, u64 \fP\fIscancode\fP\fB, u32 \fP\fItoggle\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ فك ترميز الأشعة تحت الحمراء، للإبلاغ عن ضغطة مفتاح فُك ترميزها بنجاح مع \fIscancode\fP وقيمة \fItoggle\fP في البروتوكول \fIprotocol\fP المعطى\&. سيُترجم كود المسح (scancode) إلى كود مفتاح باستخدام خريطة مفاتيح rc، ويُبلغ عنه كحدث ضغط مفتاح إدخال. بعد فترة، يُولد حدث رفع مفتاح. يمكن تمديد هذه الفترة باستدعاء إما \fBbpf_rc_keydown\fP() مجدداً بنفس القيم، أو استدعاء \fBbpf_rc_repeat\fP(). .sp تتضمن بعض البروتوكولات بت تبديل (toggle bit)، في حال حُرر الزر وضُغط عليه مجدداً بين أكواد مسح متتالية. .sp يجب أن تشير \fIctx\fP إلى عينة lirc كما مررت إلى البرنامج. .sp \fIprotocol\fP هو رقم البروتوكول الذي فُك ترميزه (انظر \fBenum rc_proto\fP للاطلاع على بعض القيم المحددة مسبقاً). .sp هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين \fBCONFIG_BPF_LIRC_MODE2\fP على "\fBy\fP". .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBu64 bpf_skb_cgroup_id(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يرجع معرف cgroup v2 للمقبس المرتبط بـ \fIskb\fP\&. هذا مشابه تقريباً للمساعد \fBbpf_get_cgroup_classid\fP() لـ cgroup v1 من خلال توفير وسم أو معرف يمكن مطابقته أو استخدامه في عمليات البحث في الخريطة مثلاً لتنفيذ سياسة. يُكشف معرف cgroup v2 لمسار معين في التسلسل الهرمي في مساحة المستخدم من خلال واجهة برمجة تطبيقات f_handle من أجل الوصول إلى نفس المعرف المكون من 64 بت. .sp يمكن استخدام هذا المساعد في مسار خروج TC، ولكن ليس في مسار الدخول، وهو متاح فقط إذا وُزعت النواة مع خيار التكوين \fBCONFIG_SOCK_CGROUP_DATA\fP. .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBu64 bpf_get_current_cgroup_id(void)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب معرف cgroup الحالي بناءً على الـ cgroup التي تعمل المهمة الحالية ضمنها. .TP \fBالقيمة المعادة\fP عدد صحيح بطول 64 بت يحتوي على معرف cgroup الحالي بناءً على الـ cgroup التي تعمل المهمة الحالية ضمنها. .UNINDENT .TP \fBvoid *bpf_get_local_storage(void *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب المؤشر إلى منطقة التخزين المحلية. يُحدد نوع وحجم التخزين المحلي بواسطة المعطى \fImap\fP. معنى \fIflags\fP محدد لكل نوع خريطة، ويجب أن يكون 0 للتخزين المحلي لـ cgroup. .sp بناءً على نوع برنامج BPF، يمكن مشاركة منطقة تخزين محلية بين نسخ متعددة من برنامج BPF تعمل في آن واحد. .sp يجب على المستخدم الاهتمام بالمزامنة بنفسه. على سبيل المثال، باستخدام تعليمات \fBBPF_ATOMIC\fP لتغيير البيانات المشتركة. .TP \fBالقيمة المعادة\fP مؤشر إلى منطقة التخزين المحلية. .UNINDENT .TP \fBlong bpf_sk_select_reuseport(struct sk_reuseport_md *\fP\fIreuse\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يختار مقبس \fBSO_REUSEPORT\fP من خريطة \fImap\fP من النوع \fBBPF_MAP_TYPE_REUSEPORT_SOCKARRAY\fP\&. ويتحقق من أن المقبس المختار يطابق الطلب الوارد في مخزن المقبس المؤقت. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu64 bpf_skb_ancestor_cgroup_id(struct sk_buff *\fP\fIskb\fP\fB, int \fP\fIancestor_level\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يرجع معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبطة بـ \fIskb\fP عند المستوى \fIancestor_level\fP\&. تكون cgroup الجذر عند \fIancestor_level\fP صفر وكل خطوة لأسفل في التسلسل الهرمي تزيد المستوى. إذا كان \fIancestor_level\fP == مستوى cgroup المرتبطة بـ \fIskb\fP، فستكون القيمة المرجعة هي نفسها قيمة \fBbpf_skb_cgroup_id\fP(). .sp المساعد مفيد لتنفيذ سياسات بناءً على مجموعات cgroup التي تقع في مرتبة أعلى في التسلسل الهرمي من مجموعة cgroup المباشرة المرتبطة بـ \fIskb\fP\&. .sp تنسيق المعرف المرجع وقيود المساعد هي نفسها كما في \fBbpf_skb_cgroup_id\fP(). .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBstruct bpf_sock *bpf_sk_lookup_tcp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32 \fP\fItuple_size\fP\fB, u64 \fP\fInetns\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يبحث عن مقبس TCP يطابق \fItuple\fP، اختيارياً في مساحة أسماء شبكة فرعية \fInetns\fP\&. يجب فحص القيمة المرجعة، وإذا لم تكن \fBNULL\fP، تُحرر عبر \fBbpf_sk_release\fP(). .sp يجب أن تشير \fIctx\fP إلى سياق البرنامج، مثل skb أو المقبس (حسب الخطاف المستخدم). يُستخدم هذا لتحديد مساحة أسماء الشبكة الأساسية للبحث. .sp يجب أن تكون \fItuple_size\fP واحدة من: .INDENT 7.0 .TP \fBsizeof(\fP\fItuple\fP\fB\->ipv4)\fP البحث عن مقبس IPv4. .TP \fBsizeof(\fP\fItuple\fP\fB\->ipv6)\fP البحث عن مقبس IPv6. .UNINDENT .sp إذا كانت \fInetns\fP عدداً صحيحاً سالباً بطول 32 بت، فسيُستخدم جدول بحث المقبس في مساحة أسماء الشبكة المرتبطة بـ \fIctx\fP. بالنسبة لخطافات TC، هذه هي مساحة أسماء الشبكة للجهاز في skb. بالنسبة لخطافات المقبس، هذه هي مساحة أسماء الشبكة للمقبس. إذا كانت \fInetns\fP أي قيمة أخرى موقعة بطول 32 بت أكبر من أو تساوي الصفر، فإنها تحدد معرف مساحة أسماء الشبكة بالنسبة إلى مساحة أسماء الشبكة المرتبطة بـ \fIctx\fP\&. قيم \fInetns\fP خارج نطاق الأعداد الصحيحة 32 بت محجوزة للاستخدام المستقبلي. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .sp هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين \fBCONFIG_NET\fP. .TP \fBالقيمة المعادة\fP مؤشر إلى \fBstruct bpf_sock\fP، أو \fBNULL\fP في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة \fBstruct bpf_sock\fP من \fIreuse\fP\fB\->socks\fP[] باستخدام تجزئة المجموعة. .UNINDENT .TP \fBstruct bpf_sock *bpf_sk_lookup_udp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32 \fP\fItuple_size\fP\fB, u64 \fP\fInetns\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يبحث عن مقبس UDP يطابق \fItuple\fP، اختيارياً في مساحة أسماء شبكة فرعية \fInetns\fP\&. يجب فحص القيمة المرجعة، وإذا لم تكن \fBNULL\fP، تُحرر عبر \fBbpf_sk_release\fP(). .sp يجب أن تشير \fIctx\fP إلى سياق البرنامج، مثل skb أو المقبس (حسب الخطاف المستخدم). يُستخدم هذا لتحديد مساحة أسماء الشبكة الأساسية للبحث. .sp يجب أن تكون \fItuple_size\fP واحدة من: .INDENT 7.0 .TP \fBsizeof(\fP\fItuple\fP\fB\->ipv4)\fP البحث عن مقبس IPv4. .TP \fBsizeof(\fP\fItuple\fP\fB\->ipv6)\fP البحث عن مقبس IPv6. .UNINDENT .sp إذا كانت \fInetns\fP عدداً صحيحاً سالباً بطول 32 بت، فسيُستخدم جدول بحث المقبس في مساحة أسماء الشبكة المرتبطة بـ \fIctx\fP. بالنسبة لخطافات TC، هذه هي مساحة أسماء الشبكة للجهاز في skb. بالنسبة لخطافات المقبس، هذه هي مساحة أسماء الشبكة للمقبس. إذا كانت \fInetns\fP أي قيمة أخرى موقعة بطول 32 بت أكبر من أو تساوي الصفر، فإنها تحدد معرف مساحة أسماء الشبكة بالنسبة إلى مساحة أسماء الشبكة المرتبطة بـ \fIctx\fP\&. قيم \fInetns\fP خارج نطاق الأعداد الصحيحة 32 بت محجوزة للاستخدام المستقبلي. .sp جميع قيم \fIflags\fP محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر. .sp هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين \fBCONFIG_NET\fP. .TP \fBالقيمة المعادة\fP مؤشر إلى \fBstruct bpf_sock\fP، أو \fBNULL\fP في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة \fBstruct bpf_sock\fP من \fIreuse\fP\fB\->socks\fP[] باستخدام تجزئة المجموعة. .UNINDENT .TP \fBlong bpf_sk_release(void *\fP\fIsock\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يحرر المرجع الذي يحمله \fIsock\fP\&. يجب أن يكون \fIsock\fP مؤشراً غير \fBNULL\fP أُرجع من \fBbpf_sk_lookup_xxx\fP(). .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_map_push_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يدفع عنصراً \fIvalue\fP في الخريطة \fImap\fP\&. الـ \fIflags\fP هي واحدة من: .INDENT 7.0 .TP \fBBPF_EXIST\fP إذا كان الطابور/المكدس ممتلئاً، يُزال أقدم عنصر لإفساح مجال لهذا العنصر. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_map_pop_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIvalue\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يسحب عنصراً من الخريطة \fImap\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_map_peek_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIvalue\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب عنصراً من الخريطة \fImap\fP دون إزالته. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_msg_push_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32 \fP\fIstart\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لسياسات المقابس، يدرج \fIlen\fP بايت في \fImsg\fP عند الإزاحة \fIstart\fP\&. .sp إذا شُغِّل برنامج من النوع \fBBPF_PROG_TYPE_SK_MSG\fP على \fImsg\fP، فقد يرغب في إدراج بيانات وصفية أو خيارات في \fImsg\fP\&. يمكن قراءة ذلك واستخدامه لاحقاً بواسطة أي من خطافات BPF في الطبقة الأدنى. .sp قد يفشل هذا المساعد إذا كان هناك ضغط على الذاكرة (فشل malloc) وفي هذه الحالات ستتلقى برامج BPF خطأً مناسباً وسيتعين على برامج BPF معالجته. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_msg_pop_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32 \fP\fIstart\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP سيزيل \fIlen\fP بايت من \fImsg\fP بدءاً من البايت \fIstart\fP\&. قد يؤدي هذا إلى أخطاء \fBENOMEM\fP في حالات معينة إذا لزم التخصيص والنسخ بسبب امتلاء المخزن المؤقت الدائري. ومع ذلك، سيحاول المساعد تجنب إجراء التخصيص إن أمكن. يمكن أن تحدث أخطاء أخرى إذا كانت معلمات الإدخال غير صالحة إما لأن البايت \fIstart\fP ليس جزءاً صالحاً من حمولة \fImsg\fP و/أو كانت قيمة \fIpop\fP كبيرة جداً. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_rc_pointer_rel(void *\fP\fIctx\fP\fB, s32 \fP\fIrel_x\fP\fB, s32 \fP\fIrel_y\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُستخدم هذا المساعد في البرامج التي تنفذ فك ترميز الأشعة تحت الحمراء، للإبلاغ عن حركة مؤشر فُك ترميزها بنجاح. .sp يجب أن تشير \fIctx\fP إلى عينة lirc كما مررت إلى البرنامج. .sp هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين \fBCONFIG_BPF_LIRC_MODE2\fP على "\fBy\fP". .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_spin_lock(struct bpf_spin_lock *\fP\fIlock\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يستحوذ على قفل دوار (spinlock) يمثله المؤشر \fIlock\fP، والذي يُخزن كجزء من قيمة خريطة. يسمح أخذ القفل بتحديث بقية الحقول في تلك القيمة بأمان. يمكن (ويجب) تحرير القفل الدوار لاحقاً باستدعاء \fBbpf_spin_unlock\fP(\fIlock\fP). .sp تأتي الأقفال الدوارة في برامج BPF مع عدد من القيود والضوابط: .INDENT 7.0 .IP \(bu 2 كائنات \fBbpf_spin_lock\fP مسموح بها فقط داخل خرائط من الأنواع \fBBPF_MAP_TYPE_HASH\fP و \fBBPF_MAP_TYPE_ARRAY\fP (يمكن توسيع هذه القائمة في المستقبل). .IP \(bu 2 وصف BTF للخريطة إلزامي. .IP \(bu 2 يمكن لبرنامج BPF أخذ قفل واحد فقط في المرة الواحدة، حيث إن أخذ قفلين أو أكثر قد يسبب أقفالاً مميتة (dead locks). .IP \(bu 2 يُسمح بـ \fBstruct bpf_spin_lock\fP واحد فقط لكل عنصر خريطة. .IP \(bu 2 عند أخذ القفل، لا يُسمح بالاستدعاءات (سواء من BPF إلى BPF أو المساعدين). .IP \(bu 2 تعليمات \fBBPF_LD_ABS\fP و \fBBPF_LD_IND\fP غير مسموح بها داخل منطقة مقفلة بقفل دوار. .IP \(bu 2 يجب على برنامج BPF استدعاء \fBbpf_spin_unlock\fP() لتحرير القفل، في جميع مسارات التنفيذ، قبل أن يعود. .IP \(bu 2 يمكن لبرنامج BPF الوصول إلى \fBstruct bpf_spin_lock\fP فقط عبر المساعدين \fBbpf_spin_lock\fP() و \fBbpf_spin_unlock\fP(). تحميل أو تخزين بيانات في حقل \fBstruct bpf_spin_lock\fP \fIlock\fP\fB;\fP للخريطة غير مسموح به. .IP \(bu 2 لاستخدام المساعد \fBbpf_spin_lock\fP()، يجب أن يكون وصف BTF لقيمة الخريطة هيكلاً (struct) ويحتوي على حقل \fBstruct bpf_spin_lock\fP \fIanyname\fP\fB;\fP عند المستوى الأعلى. القفل المتداخل داخل هيكل آخر غير مسموح به. .IP \(bu 2 يجب أن يكون حقل \fBstruct bpf_spin_lock\fP \fIlock\fP في قيمة الخريطة محاذياً لمضاعفات 4 بايت في تلك القيمة. .IP \(bu 2 استدعاء النظام مع الأمر \fBBPF_MAP_LOOKUP_ELEM\fP لا ينسخ حقل \fBbpf_spin_lock\fP إلى مساحة المستخدم. .IP \(bu 2 استدعاء النظام مع الأمر \fBBPF_MAP_UPDATE_ELEM\fP، أو التحديث من برنامج BPF، لا يحدّث حقل \fBbpf_spin_lock\fP. .IP \(bu 2 لا يمكن أن يكون \fBbpf_spin_lock\fP على المكدس أو داخل حزمة شبكة (يمكن أن يكون فقط داخل قيم الخريطة). .IP \(bu 2 \fBbpf_spin_lock\fP متاح للجذر (root) فقط. .IP \(bu 2 لا يمكن لبرامج التتبع وبرامج تصفية المقابس استخدام \fBbpf_spin_lock\fP() بسبب عدم كفاية فحوصات الشفعة (Preemption) (ولكن قد يتغير هذا في المستقبل). .IP \(bu 2 \fBbpf_spin_lock\fP غير مسموح به في الخرائط الداخلية لـ map\-in\-map. .UNINDENT .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBlong bpf_spin_unlock(struct bpf_spin_lock *\fP\fIlock\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يحرر الـ \fIlock\fP الذي أُقفل سابقاً باستدعاء \fBbpf_spin_lock\fP(\fIlock\fP). .TP \fBالقيمة المعادة\fP 0 .UNINDENT .TP \fBstruct bpf_sock *bpf_sk_fullsock(struct bpf_sock *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب هذا المساعد مؤشراً لـ \fBstruct bpf_sock\fP بحيث يمكن الوصول إلى جميع الحقول في \fBbpf_sock\fP هذه. .TP \fBالقيمة المعادة\fP مؤشر \fBstruct bpf_sock\fP عند النجاح، أو \fBNULL\fP في حالة الفشل. .UNINDENT .TP \fBstruct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب هذا المساعد مؤشراً لـ \fBstruct bpf_tcp_sock\fP من مؤشر \fBstruct bpf_sock\fP. .TP \fBالقيمة المعادة\fP مؤشر \fBstruct bpf_tcp_sock\fP عند النجاح، أو \fBNULL\fP في حالة الفشل. .UNINDENT .TP \fBlong bpf_skb_ecn_set_ce(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يضبط حقل ECN (إشعار الازدحام الصريح) لترويسة IP على \fBCE\fP (مواجهة ازدحام) إذا كانت القيمة الحالية \fBECT\fP (نقل قادر على ECN). وإلا، لا يفعل شيئاً. يعمل مع IPv6 و IPv4. .TP \fBالقيمة المعادة\fP 1 إذا ضُبط علم \fBCE\fP (سواء من خلال استدعاء المساعد الحالي أو لأنه كان موجوداً بالفعل)، و 0 إذا لم يُضبط. .UNINDENT .TP \fBstruct bpf_sock *bpf_get_listener_sock(struct bpf_sock *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إرجاع مؤشر \fBstruct bpf_sock\fP في حالة \fBTCP_LISTEN\fP. لا حاجة لاستدعاء \fBbpf_sk_release\fP() وهو غير مسموح به. .TP \fBالقيمة المعادة\fP مؤشر \fBstruct bpf_sock\fP عند النجاح، أو \fBNULL\fP في حالة الفشل. .UNINDENT .TP \fBstruct bpf_sock *bpf_skc_lookup_tcp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32 \fP\fItuple_size\fP\fB, u64 \fP\fInetns\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يبحث عن مقبس TCP يطابق \fItuple\fP، اختيارياً في مساحة أسماء شبكة فرعية \fInetns\fP\&. يجب فحص القيمة المرجعة، وإذا لم تكن \fBNULL\fP، تُحرر عبر \fBbpf_sk_release\fP(). .sp هذه الدالة مطابقة لـ \fBbpf_sk_lookup_tcp\fP()، باستثناء أنها ترجع أيضًا مقابس الانتظار الزمني (timewait) أو الطلب (request). استخدم \fBbpf_sk_fullsock\fP() أو \fBbpf_tcp_sock\fP() للوصول إلى الهيكل الكامل. .sp هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين \fBCONFIG_NET\fP. .TP \fBالقيمة المعادة\fP مؤشر إلى \fBstruct bpf_sock\fP، أو \fBNULL\fP في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة \fBstruct bpf_sock\fP من \fIreuse\fP\fB\->socks\fP[] باستخدام تجزئة المجموعة. .UNINDENT .TP \fBlong bpf_tcp_check_syncookie(void *\fP\fIsk\fP\fB, void *\fP\fIiph\fP\fB, u32 \fP\fIiph_len\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32 \fP\fIth_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP التحقق مما إذا كان \fIiph\fP و \fIth\fP يحتويان على SYN cookie ACK صالح للمقبس المستمع في \fIsk\fP\&. .sp يشير \fIiph\fP إلى بداية ترويسة IPv4 أو IPv6، بينما يحتوي \fIiph_len\fP على \fBsizeof\fP(\fBstruct iphdr\fP) أو \fBsizeof\fP(\fBstruct ipv6hdr\fP). .sp يشير \fIth\fP إلى بداية ترويسة TCP، بينما يحتوي \fIth_len\fP على طول ترويسة TCP (على الأقل \fBsizeof\fP(\fBstruct tcphdr\fP)). .TP \fBالقيمة المعادة\fP 0 إذا كان \fIiph\fP و \fIth\fP يمثلان SYN cookie ACK صالحًا، أو قيمة خطأ سالبة خلاف ذلك. .UNINDENT .TP \fBlong bpf_sysctl_get_name(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على اسم sysctl في /proc/sys/ ونسخه إلى المخزن المؤقت \fIbuf\fP المقدم من البرنامج وبحجم \fIbuf_len\fP\&. .sp يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا. .sp إذا كانت \fIflags\fP صفرًا، يُنسخ الاسم الكامل (مثل "net/ipv4/tcp_mem"). استخدم الوسم \fBBPF_F_SYSCTL_BASE_NAME\fP لنسخ الاسم الأساسي فقط (مثل "tcp_mem"). .TP \fBالقيمة المعادة\fP عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي). .sp \fB\-E2BIG\fP إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي \fIbuf\fP في هذه الحالة على اسم مبتور). .UNINDENT .TP \fBlong bpf_sysctl_get_current_value(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على القيمة الحالية لـ sysctl كما تظهر في /proc/sys (بما في ذلك السطر الجديد، إلخ)، ونسخها كسلسلة نصية إلى المخزن المؤقت \fIbuf\fP المقدم من البرنامج وبحجم \fIbuf_len\fP\&. .sp تُنسخ القيمة بالكامل، بغض النظر عن موضع الملف الذي أصدر عنده فضاء المستخدم sys_read مثلاً. .sp يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا. .TP \fBالقيمة المعادة\fP عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي). .sp \fB\-E2BIG\fP إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي \fIbuf\fP في هذه الحالة على اسم مبتور). .sp \fB\-EINVAL\fP إذا كانت القيمة الحالية غير متاحة، مثلاً لأن sysctl غير مهيأ والقراءة ترجع \-EIO له. .UNINDENT .TP \fBlong bpf_sysctl_get_new_value(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على القيمة الجديدة التي يكتبها فضاء المستخدم إلى sysctl (قبل حدوث الكتابة الفعلية) ونسخها كسلسلة نصية إلى المخزن المؤقت \fIbuf\fP المقدم من البرنامج وبحجم \fIbuf_len\fP\&. .sp قد يكتب فضاء المستخدم قيمة جديدة عند موضع ملف أكبر من 0. .sp يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا. .TP \fBالقيمة المعادة\fP عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي). .sp \fB\-E2BIG\fP إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي \fIbuf\fP في هذه الحالة على اسم مبتور). .sp \fB\-EINVAL\fP إذا كان يجري قراءة sysctl. .UNINDENT .TP \fBlong bpf_sysctl_set_new_value(struct bpf_sysctl *\fP\fIctx\fP\fB, const char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تجاوز القيمة الجديدة التي يكتبها فضاء المستخدم إلى sysctl بالقيمة المقدمة من البرنامج في المخزن المؤقت \fIbuf\fP وبحجم \fIbuf_len\fP\&. .sp يجب أن يحتوي \fIbuf\fP على سلسلة نصية بنفس الصيغة التي يقدمها فضاء المستخدم عند الكتابة إلى sysctl. .sp قد يكتب فضاء المستخدم قيمة جديدة عند موضع ملف أكبر من 0. لتجاوز كامل قيمة sysctl، يجب ضبط موضع الملف على الصفر. .TP \fBالقيمة المعادة\fP 0 عند النجاح. .sp \fB\-E2BIG\fP إذا كان \fIbuf_len\fP كبيرًا جدًا. .sp \fB\-EINVAL\fP إذا كان يجري قراءة sysctl. .UNINDENT .TP \fBlong bpf_strtol(const char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB, u64 \fP\fIflags\fP\fB, long *\fP\fIres\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحويل الجزء الأولي من السلسلة النصية من المخزن المؤقت \fIbuf\fP ذو الحجم \fIbuf_len\fP إلى عدد صحيح طويل وفقًا للأساس المعطى وحفظ النتيجة في \fIres\fP\&. .sp قد تبدأ السلسلة النصية بمقدار تعسفي من المسافات البيضاء (كما تحددها \fBisspace\fP(3)) تليها علامة '\fB\-\fP' اختيارية واحدة. .sp تُرمّز البتات الخمسة الأقل أهمية في \fIflags\fP الأساس، والبتات الأخرى غير مستخدمة حاليًا. .sp يجب أن يكون الأساس إما 8 أو 10 أو 16 أو 0 لاكتشافه آليًا بصورة مماثلة لـ \fBstrtol\fP(3) في فضاء المستخدم. .TP \fBالقيمة المعادة\fP عدد الأحرف المستهلكة عند النجاح. يجب أن يكون موجبًا ولا يتجاوز \fIbuf_len\fP\&. .sp \fB\-EINVAL\fP إذا لم يُعثر على أرقام صالحة أو إذا قُدّم أساس غير مدعوم. .sp \fB\-ERANGE\fP إذا كانت القيمة الناتجة خارج النطاق. .UNINDENT .TP \fBlong bpf_strtoul(const char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB, u64 \fP\fIflags\fP\fB, unsigned long *\fP\fIres\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحويل الجزء الأولي من السلسلة النصية من المخزن المؤقت \fIbuf\fP ذو الحجم \fIbuf_len\fP إلى عدد صحيح طويل غير موقع وفقًا للأساس المعطى وحفظ النتيجة في \fIres\fP\&. .sp قد تبدأ السلسلة النصية بمقدار تعسفي من المسافات البيضاء (كما تحددها \fBisspace\fP(3)). .sp تُرمّز البتات الخمسة الأقل أهمية في \fIflags\fP الأساس، والبتات الأخرى غير مستخدمة حاليًا. .sp يجب أن يكون الأساس إما 8 أو 10 أو 16 أو 0 لاكتشافه آليًا بصورة مماثلة لـ \fBstrtoul\fP(3) في فضاء المستخدم. .TP \fBالقيمة المعادة\fP عدد الأحرف المستهلكة عند النجاح. يجب أن يكون موجبًا ولا يتجاوز \fIbuf_len\fP\&. .sp \fB\-EINVAL\fP إذا لم يُعثر على أرقام صالحة أو إذا قُدّم أساس غير مدعوم. .sp \fB\-ERANGE\fP إذا كانت القيمة الناتجة خارج النطاق. .UNINDENT .TP \fBvoid *bpf_sk_storage_get(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIsk\fP\fB, void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على bpf\-local\-storage من \fIsk\fP\&. .sp من الناحية المنطقية، يمكن اعتبار ذلك كأنه الحصول على قيمة من الخريطة \fImap\fP مع استخدام \fIsk\fP كـ \fBkey\fP\&. ومن هذا المنظور، لا يختلف الاستخدام كثيرًا عن \fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIsk\fP) باستثناء أن هذا المساعد يفرض أن يكون المفتاح مقبسًا كاملاً (full socket) وأن تكون الخريطة من نوع \fBBPF_MAP_TYPE_SK_STORAGE\fP أيضًا. .sp داخليًا، تُخزّن القيمة محليًا عند \fIsk\fP بدلاً من الخريطة \fImap\fP\&. تُستخدم الخريطة \fImap\fP كـ "نوع" للتخزين المحلي bpf. يتم البحث عن "نوع" التخزين المحلي (أي الخريطة) بين جميع مخازن bpf المحلية الموجودة عند \fIsk\fP\&. .sp يكون \fIsk\fP مؤشر \fBstruct sock\fP للنواة في برامج LSM. ويكون \fIsk\fP مؤشر \fBstruct bpf_sock\fP لأنواع البرامج الأخرى. .sp يمكن استخدام وسم اختياري \fIflags\fP (\fBBPF_SK_STORAGE_GET_F_CREATE\fP) بحيث يُنشأ تخزين محلي bpf جديد إذا لم يكن موجودًا. يمكن استخدام \fIvalue\fP مع \fBBPF_SK_STORAGE_GET_F_CREATE\fP لتحديد القيمة الأولية للتخزين المحلي. إذا كان \fIvalue\fP هو \fBNULL\fP، فسيُهيأ التخزين المحلي الجديد بالصفر. .TP \fBالقيمة المعادة\fP يُرجع مؤشر للتخزين المحلي bpf عند النجاح. .sp \fBNULL\fP إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة تخزين محلي bpf جديد. .UNINDENT .TP \fBlong bpf_sk_storage_delete(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حذف تخزين محلي bpf من \fIsk\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. .sp \fB\-ENOENT\fP إذا تعذر العثور على التخزين المحلي bpf. \fB\-EINVAL\fP إذا لم يكن sk مقبسًا كاملاً (على سبيل المثال request_sock). .UNINDENT .TP \fBlong bpf_send_signal(u32 \fP\fIsig\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إرسال الإشارة \fIsig\fP إلى عملية المهمة الحالية. قد تُسلم الإشارة إلى أي من خيوط (threads) هذه العملية. .TP \fBالقيمة المعادة\fP 0 عند النجاح أو وضعه في الطابور بنجاح. .sp \fB\-EBUSY\fP إذا كان طابور العمل تحت nmi ممتلئًا. .sp \fB\-EINVAL\fP إذا كانت الإشارة \fIsig\fP غير صالحة. .sp \fB\-EPERM\fP إذا لم تكن هناك صلاحية لإرسال الإشارة \fIsig\fP\&. .sp \fB\-EAGAIN\fP إذا كان بإمكان برنامج bpf المحاولة مرة أخرى. .UNINDENT .TP \fBs64 bpf_tcp_gen_syncookie(void *\fP\fIsk\fP\fB, void *\fP\fIiph\fP\fB, u32 \fP\fIiph_len\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32 \fP\fIth_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP محاولة إصدار SYN cookie للحزمة مع ترويسات IP/TCP المقابلة، \fIiph\fP و \fIth\fP، على المقبس المستمع في \fIsk\fP\&. .sp يشير \fIiph\fP إلى بداية ترويسة IPv4 أو IPv6، بينما يحتوي \fIiph_len\fP على \fBsizeof\fP(\fBstruct iphdr\fP) أو \fBsizeof\fP(\fBstruct ipv6hdr\fP). .sp يشير \fIth\fP إلى بداية ترويسة TCP، بينما يحتوي \fIth_len\fP على طول ترويسة TCP مع الخيارات (على الأقل \fBsizeof\fP(\fBstruct tcphdr\fP)). .TP \fBالقيمة المعادة\fP عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EINVAL\fP لا يمكن إصدار SYN cookie بسبب خطأ .sp \fB\-ENOENT\fP لا ينبغي إصدار SYN cookie (لا يوجد SYN flood) .sp \fB\-EOPNOTSUPP\fP تهيئة النواة لا تُفعّل SYN cookies .sp \fB\-EPROTONOSUPPORT\fP إصدار حزمة IP ليس 4 أو 6 .UNINDENT .TP \fBlong bpf_skb_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP كتابة كتلة \fIdata\fP خام في حدث أداء BPF خاص تحتفظ به \fImap\fP من نوع \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. يجب أن يحتوي حدث الأداء هذا على السمات التالية: \fBPERF_SAMPLE_RAW\fP كـ \fBsample_type\fP، و \fBPERF_TYPE_SOFTWARE\fP كـ \fBtype\fP، و \fBPERF_COUNT_SW_BPF_OUTPUT\fP كـ \fBconfig\fP\&. .sp تُستخدم الـ \fIflags\fP للإشارة إلى الفهرس في \fImap\fP الذي يجب وضع القيمة فيه، مقنعًا بـ \fBBPF_F_INDEX_MASK\fP\&. بدلاً من ذلك، يمكن ضبط \fIflags\fP على \fBBPF_F_CURRENT_CPU\fP للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي. .sp القيمة المراد كتابتها، ذات الحجم \fIsize\fP، تُمرر عبر مكدس eBPF ويؤشر إليها بـ \fIdata\fP\&. .sp تمثل \fIctx\fP مؤشرًا إلى struct sk_buff داخل النواة. .sp هذا المساعد مشابه لـ \fBbpf_perf_event_output\fP() ولكنه مقتصر على برامج bpf من نوع raw_tracepoint. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_probe_read_user(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP محاولة قراءة \fIsize\fP بايت بأمان من عنوان فضاء المستخدم \fIunsafe_ptr\fP وتخزين البيانات في \fIdst\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_probe_read_kernel(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP محاولة قراءة \fIsize\fP بايت بأمان من عنوان فضاء النواة \fIunsafe_ptr\fP وتخزين البيانات في \fIdst\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_probe_read_user_str(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP نسخ سلسلة نصية منتهية بـ NUL من عنوان مستخدم غير آمن \fIunsafe_ptr\fP إلى \fIdst\fP\&. يجب أن يتضمن \fIsize\fP بايت NUL الختامي. في حال كان طول السلسلة أصغر من \fIsize\fP، لا يُملأ الهدف بمزيد من بايتات NUL. إذا كان طول السلسلة أكبر من \fIsize\fP، فسيُنسخ \fIsize\fP\-1 بايت فقط ويُضبط البايت الأخير على NUL. .sp عند النجاح، تُرجع عدد البايتات المكتوبة، بما في ذلك حرف NUL الختامي. وهذا يجعل هذا المساعد مفيدًا في برامج التتبع لقراءة السلاسل النصية، والأهم من ذلك للحصول على طولها في وقت التشغيل. انظر القصاصة التالية: .INDENT 7.0 .INDENT 3.5 .sp .EX SEC("kprobe/sys_open") void bpf_sys_open(struct pt_regs *ctx) { char buf[PATHLEN]; // PATHLEN مُعرّف بـ 256 int res = bpf_probe_read_user_str(buf, sizeof(buf), ctx\->di); // استهلاك buf، مثلاً دفعه إلى // فضاء المستخدم عبر bpf_perf_event_output()؛ يمكننا // استخدام res (طول السلسلة) كحجم للحدث، // بعد التحقق من حدوده. } .EE .UNINDENT .UNINDENT .sp بالمقارنة، فإن استخدام المساعد \fBbpf_probe_read_user\fP() هنا بدلاً من ذلك لقراءة السلسلة سيتطلب تقدير الطول في وقت التصريف، وغالبًا ما سيؤدي ذلك إلى نسخ ذاكرة أكثر من اللازم. .sp حالة استخدام مفيدة أخرى هي عند تحليل وسائط العملية الفردية أو متغيرات البيئة الفردية بالتنقل عبر \fIcurrent\fP\fB\->mm\->arg_start\fP و \fIcurrent\fP\fB\->mm\->env_start\fP: باستخدام هذا المساعد والقيمة المرجعة، يمكن للمرء التنقل بسرعة عند الإزاحة الصحيحة لمنطقة الذاكرة. .TP \fBالقيمة المعادة\fP عند النجاح، يُرجع الطول الموجب تمامًا لسلسلة الخرج، بما في ذلك حرف NUL الختامي. وعند الخطأ، يُرجع قيمة سالبة. .UNINDENT .TP \fBlong bpf_probe_read_kernel_str(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP نسخ سلسلة نصية منتهية بـ NUL من عنوان نواة غير آمن \fIunsafe_ptr\fP إلى \fIdst\fP\&. تنطبق نفس دلالات \fBbpf_probe_read_user_str\fP(). .TP \fBالقيمة المعادة\fP عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة. .UNINDENT .TP \fBlong bpf_tcp_send_ack(void *\fP\fItp\fP\fB, u32 \fP\fIrcv_nxt\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إرسال tcp\-ack. يمثل \fItp\fP هيكل \fBtcp_sock\fP داخل النواة. ويمثل \fIrcv_nxt\fP الـ ack_seq المراد إرساله. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_send_signal_thread(u32 \fP\fIsig\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إرسال الإشارة \fIsig\fP إلى الخيط (thread) المقابل للمهمة الحالية. .TP \fBالقيمة المعادة\fP 0 عند النجاح أو وضعه في الطابور بنجاح. .sp \fB\-EBUSY\fP إذا كان طابور العمل تحت nmi ممتلئًا. .sp \fB\-EINVAL\fP إذا كانت الإشارة \fIsig\fP غير صالحة. .sp \fB\-EPERM\fP إذا لم تكن هناك صلاحية لإرسال الإشارة \fIsig\fP\&. .sp \fB\-EAGAIN\fP إذا كان بإمكان برنامج bpf المحاولة مرة أخرى. .UNINDENT .TP \fBu64 bpf_jiffies64(void)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على jiffies بـ 64 بت .TP \fBالقيمة المعادة\fP الـ jiffies بـ 64 بت .UNINDENT .TP \fBlong bpf_read_branch_records(struct bpf_perf_event_data *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP بالنسبة لبرنامج eBPF الملحق بحدث perf، استعد سجلات الفروع (\fBstruct perf_branch_entry\fP) المرتبطة بـ \fIctx\fP وخزّنها في المخزن المؤقت الذي يشير إليه \fIbuf\fP بحجم يصل إلى \fIsize\fP بايت. .TP \fBالقيمة المعادة\fP عند النجاح، عدد البايتات المكتوبة في \fIbuf\fP\&. عند الخطأ، قيمة سالبة. .sp يمكن ضبط \fIflags\fP على \fBBPF_F_GET_BRANCH_RECORDS_SIZE\fP ليعيد بدلاً من ذلك عدد البايتات المطلوبة لتخزين كافة مدخلات الفروع. إذا ضُبط هذا الوسم، فقد يكون \fIbuf\fP فارغاً (NULL). .sp \fB\-EINVAL\fP إذا كانت المعطيات غير صالحة أو إذا لم يكن \fBsize\fP من مضاعفات \fBsizeof\fP(\fBstruct perf_branch_entry\fP). .sp \fB\-ENOENT\fP إذا كانت المعمارية لا تدعم سجلات الفروع. .UNINDENT .TP \fBlong bpf_get_ns_current_pid_tgid(u64 \fP\fIdev\fP\fB, u64 \fP\fIino\fP\fB, struct bpf_pidns_info *\fP\fInsdata\fP\fB, u32 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُرجع 0 عند النجاح، وقيم \fIpid\fP و \fItgid\fP كما تُرى من \fInamespace\fP الحالي ستُرجع في \fInsdata\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو أحد ما يلي في حالة الفشل: .sp \fB\-EINVAL\fP إذا كانت dev و inum الموفرة لا تطابق dev_t ورقم inode مع nsfs للمهمة الحالية، أو إذا فقد تحويل dev إلى dev_t البتات العالية. .sp \fB\-ENOENT\fP إذا كان pidns غير موجود للمهمة الحالية. .UNINDENT .TP \fBlong bpf_xdp_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP كتابة كتلة \fIdata\fP خام في حدث أداء BPF خاص تحتفظ به \fImap\fP من نوع \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. يجب أن يحتوي حدث الأداء هذا على السمات التالية: \fBPERF_SAMPLE_RAW\fP كـ \fBsample_type\fP، و \fBPERF_TYPE_SOFTWARE\fP كـ \fBtype\fP، و \fBPERF_COUNT_SW_BPF_OUTPUT\fP كـ \fBconfig\fP\&. .sp تُستخدم الـ \fIflags\fP للإشارة إلى الفهرس في \fImap\fP الذي يجب وضع القيمة فيه، مقنعًا بـ \fBBPF_F_INDEX_MASK\fP\&. بدلاً من ذلك، يمكن ضبط \fIflags\fP على \fBBPF_F_CURRENT_CPU\fP للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي. .sp القيمة المراد كتابتها، ذات الحجم \fIsize\fP، تُمرر عبر مكدس eBPF ويؤشر إليها بـ \fIdata\fP\&. .sp \fIctx\fP هو مؤشر إلى struct xdp_buff داخل النواة. .sp هذا المساعد مشابه لـ \fBbpf_perf_eventoutput\fP() ولكنه مقصور على برامج raw_tracepoint bpf. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu64 bpf_get_netns_cookie(void *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استعد الكعكة (التي ولدتها النواة) لنطاق أسماء الشبكة الذي يرتبط به المُدخل \fIctx\fP. تظل كعكة نطاق أسماء الشبكة مستقرة طوال عمرها وتوفر معرفاً عاماً يمكن افتراض فرادته. إذا كان \fIctx\fP فارغاً (NULL)، فيعيد المساعد الكعكة لنطاق أسماء الشبكة الأولي. الكعكة نفسها مشابهة جداً لكعكة المساعد \fBbpf_get_socket_cookie\fP()، ولكن لنطاقات أسماء الشبكة بدلاً من المقابس. .TP \fBالقيمة المعادة\fP رقم مبهم بطول 8 بايت. .UNINDENT .TP \fBu64 bpf_get_current_ancestor_cgroup_id(int \fP\fIancestor_level\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبط بالمهمة الحالية عند \fIancestor_level\fP\&. يقع cgroup الجذر عند \fIancestor_level\fP صفر، وتزيد كل خطوة لأسفل في التسلسل الهرمي من المستوى. إذا كان \fIancestor_level\fP يساوي مستوى cgroup المرتبط بالمهمة الحالية، فستكون القيمة المعادة هي نفسها قيمة \fBbpf_get_current_cgroup_id\fP(). .sp هذا المساعد مفيد لتنفيذ سياسات تعتمد على cgroups التي تقع في مرتبة أعلى في التسلسل الهرمي من الـ cgroup المباشر المرتبط بالمهمة الحالية. .sp تنسيق المعرف المعاد وقيود المساعد هي نفسها في \fBbpf_get_current_cgroup_id\fP(). .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBlong bpf_sk_assign(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIsk\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP المساعد محمل بشكل زائد اعتماداً على نوع برنامج BPF. ينطبق هذا الوصف على برنامجي \fBBPF_PROG_TYPE_SCHED_CLS\fP و \fBBPF_PROG_TYPE_SCHED_ACT\fP. .sp خصّص \fIsk\fP لـ \fIskb\fP\&. عند اقترانه بإعدادات توجيه مناسبة لاستلام الحزمة نحو المقبس، سيؤدي ذلك إلى تسليم \fIskb\fP إلى المقبس المحدد. قد تتعارض عمليات إعادة التوجيه اللاحقة لـ \fIskb\fP عبر \fBbpf_redirect\fP() أو \fBbpf_clone_redirect\fP() أو طرق أخرى خارج BPF مع التسليم الناجح للمقبس. .sp هذه العملية صالحة فقط من مسار دخول (ingress) الـ TC. .sp يجب أن تكون معطاة \fIflags\fP صفراً. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل: .sp \fB\-EINVAL\fP إذا كانت \fIflags\fP المحددة غير مدعومة. .sp \fB\-ENOENT\fP إذا كان المقبس غير متاح للتخصيص. .sp \fB\-ENETUNREACH\fP إذا كان المقبس لا يمكن الوصول إليه (نطاق أسماء شبكة خاطئ). .sp \fB\-EOPNOTSUPP\fP إذا كانت العملية غير مدعومة، على سبيل المثال استدعاء من خارج دخول TC. .UNINDENT .TP \fBlong bpf_sk_assign(struct bpf_sk_lookup *\fP\fIctx\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP المساعد محمل بشكل زائد اعتماداً على نوع برنامج BPF. ينطبق هذا الوصف على برامج \fBBPF_PROG_TYPE_SK_LOOKUP\fP. .sp اختر \fIsk\fP كنتيجة للبحث عن مقبس. .sp لنجاح العملية، يجب أن يكون المقبس الممرر متوافقاً مع وصف الحزمة المقدم من الكائن \fIctx\fP. .sp يجب أن يكون بروتوكول L4‏ (\fBIPPROTO_TCP\fP أو \fBIPPROTO_UDP\fP) مطابقاً تماماً. بينما يجب أن تكون عائلة بروتوكول الإنترنت (\fBAF_INET\fP أو \fBAF_INET6\fP) متوافقة، أي أنه يمكن اختيار مقابس IPv6 التي ليست v6\-only لحزم IPv4. .sp يمكن فقط اختيار مستمعي TCP ومقابس UDP غير المتصلة. يمكن لـ \fIsk\fP أن يكون فارغاً (NULL) أيضاً لإعادة تعيين أي اختيار سابق. .sp يمكن أن تكون معطاة \fIflags\fP مزيجاً من القيم التالية: .INDENT 7.0 .IP \(bu 2 \fBBPF_SK_LOOKUP_F_REPLACE\fP لتجاوز اختيار المقبس السابق، الذي ربما قام به برنامج BPF تم تشغيله قبلنا. .IP \(bu 2 \fBBPF_SK_LOOKUP_F_NO_REUSEPORT\fP لتخطي موازنة الحمل داخل مجموعة reuseport للمقبس الذي يتم اختياره. .UNINDENT .sp عند النجاح، سيشير \fIctx\->sk\fP إلى المقبس المختار. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو رقم خطأ سالب في حالة الفشل. .INDENT 7.0 .IP \(bu 2 \fB\-EAFNOSUPPORT\fP إذا كانت عائلة المقبس (\fIsk\->family\fP) غير متوافقة مع عائلة الحزمة (\fIctx\->family\fP). .IP \(bu 2 \fB\-EEXIST\fP إذا كان المقبس قد اختير بالفعل، ربما بواسطة برنامج آخر، ولم يُحدد وسم \fBBPF_SK_LOOKUP_F_REPLACE\fP. .IP \(bu 2 \fB\-EINVAL\fP إذا حُددت أوسمة غير مدعومة. .IP \(bu 2 \fB\-EPROTOTYPE\fP إذا كان بروتوكول L4 للمقبس (\fIsk\->protocol\fP) لا يطابق بروتوكول الحزمة (\fIctx\->protocol\fP). .IP \(bu 2 \fB\-ESOCKTNOSUPPORT\fP إذا لم يكن المقبس في حالة مسموح بها (TCP مستمع أو UDP غير متصل). .UNINDENT .UNINDENT .TP \fBu64 bpf_ktime_get_boot_ns(void)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد الوقت المنقضي منذ إقلاع النظام، بالنانو ثانية. يتضمن الوقت الذي عُلق فيه النظام. انظر: \fBclock_gettime\fP(\fBCLOCK_BOOTTIME\fP) .TP \fBالقيمة المعادة\fP الـ \fIktime\fP الحالي\&. .UNINDENT .TP \fBlong bpf_seq_printf(struct seq_file *\fP\fIm\fP\fB, const char *\fP\fIfmt\fP\fB, u32 \fP\fIfmt_size\fP\fB, const void *\fP\fIdata\fP\fB, u32 \fP\fIdata_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يستخدم \fBbpf_seq_printf\fP() الدالة \fBseq_printf\fP() التابعة لـ seq_file لطباعة سلسلة التنسيق. يمثل \fIm\fP ملف seq_file. الـ \fIfmt\fP و \fIfmt_size\fP مخصصان لسلسلة التنسيق نفسها. الـ \fIdata\fP و \fIdata_len\fP هما معطيات سلسلة التنسيق. الـ \fIdata\fP عبارة عن مصفوفة \fBu64\fP وتُخزن قيم سلسلة التنسيق المقابلة في المصفوفة. بالنسبة للسلاسل والمؤشرات حيث يُوصل إلى المشار إليهم، تُخزن قيم المؤشرات فقط في مصفوفة \fIdata\fP. الـ \fIdata_len\fP هو حجم \fIdata\fP بالبايت \- ويجب أن يكون من مضاعفات 8. .sp تتطلب التنسيقات \fB%s\fP، \fB%p{i,I}{4,6}\fP قراءة ذاكرة النواة. قد تفشل قراءة ذاكرة النواة بسبب عنوان غير صالح أو عنوان صالح ولكنه يتطلب خطأً كبيراً في الذاكرة. إذا فشلت قراءة ذاكرة النواة، فستكون السلسلة الخاصة بـ \fB%s\fP سلسلة فارغة، وعنوان ip لـ \fB%p{i,I}{4,6}\fP سيكون 0. عدم إعادة خطأ لبرنامج bpf يتوافق مع ما يفعله \fBbpf_trace_printk\fP() حالياً. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل: .sp \fB\-EBUSY\fP إذا كان المخزن المؤقت لنسخ الذاكرة لكل وحدة معالجة مركزية مشغولاً، يمكن المحاولة مرة أخرى بإرجاع 1 من برنامج bpf. .sp \fB\-EINVAL\fP إذا كانت المعطيات غير صالحة، أو إذا كان \fIfmt\fP غير صالح/غير مدعوم. .sp \fB\-E2BIG\fP إذا كان \fIfmt\fP يحتوي على الكثير من محددات التنسيق. .sp \fB\-EOVERFLOW\fP إذا حدث طفحان: ستتم محاولة معالجة الكائن نفسه مرة أخرى. .UNINDENT .TP \fBlong bpf_seq_write(struct seq_file *\fP\fIm\fP\fB, const void *\fP\fIdata\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يستخدم \fBbpf_seq_write\fP() الدالة \fBseq_write\fP() التابعة لـ seq_file لكتابة البيانات. يمثل \fIm\fP ملف seq_file. يمثل \fIdata\fP و \fIlen\fP البيانات المراد كتابتها بالبايت. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل: .sp \fB\-EOVERFLOW\fP إذا حدث طفحان: ستتم محاولة معالجة الكائن نفسه مرة أخرى. .UNINDENT .TP \fBu64 bpf_sk_cgroup_id(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد معرف cgroup v2 للمقبس \fIsk\fP\&. .sp يجب أن يكون \fIsk\fP مؤشراً غير فارغ (non\-NULL) لمقبس، مثل ذاك المعاد من \fBbpf_sk_lookup_xxx\fP() أو \fBbpf_sk_fullsock\fP() وغيرهما. تنسيق المعرف المعاد هو نفسه في \fBbpf_skb_cgroup_id\fP(). .sp هذا المساعد متاح فقط إذا جُمعت النواة مع خيار التكوين \fBCONFIG_SOCK_CGROUP_DATA\fP. .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBu64 bpf_sk_ancestor_cgroup_id(void *\fP\fIsk\fP\fB, int \fP\fIancestor_level\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبط بالمقبس \fIsk\fP عند \fIancestor_level\fP\&. يقع cgroup الجذر عند \fIancestor_level\fP صفر وتزيد كل خطوة لأسفل في التسلسل الهرمي من المستوى. إذا كان \fIancestor_level\fP يساوي مستوى cgroup المرتبط بـ \fIsk\fP، فستكون القيمة المعادة هي نفسها قيمة \fBbpf_sk_cgroup_id\fP(). .sp هذا المساعد مفيد لتنفيذ سياسات تعتمد على cgroups التي تقع في مرتبة أعلى في التسلسل الهرمي من الـ cgroup المباشر المرتبط بـ \fIsk\fP\&. .sp تنسيق المعرف المعاد وقيود المساعد هي نفسها في \fBbpf_sk_cgroup_id\fP(). .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBlong bpf_ringbuf_output(void *\fP\fIringbuf\fP\fB, void *\fP\fIdata\fP\fB, u64 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP انسخ \fIsize\fP بايت من \fIdata\fP إلى مخزن حلقي \fIringbuf\fP\&. إذا حُدد \fBBPF_RB_NO_WAKEUP\fP في \fIflags\fP، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد \fBBPF_RB_FORCE_WAKEUP\fP في \fIflags\fP، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد \fB0\fP في \fIflags\fP، يُرسل إشعار تكيفي بتوفر بيانات جديدة. .sp الإشعار التكيفي هو إشعار يُرسل عندما تنجز عملية مساحة المستخدم عملها وتستهلك جميع الحمولات المتاحة. في حالة كانت عملية مساحة المستخدم لا تزال تعالج حمولة سابقة، فلا داعي للإشعار لأنها ستعالج الحمولة المضافة حديثاً آلياً. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBvoid *bpf_ringbuf_reserve(void *\fP\fIringbuf\fP\fB, u64 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احجز \fIsize\fP بايت من الحمولة في مخزن حلقي \fIringbuf\fP\&. يجب أن تكون \fIflags\fP مساوية لـ 0. .TP \fBالقيمة المعادة\fP مؤشر صالح مع توفر \fIsize\fP بايت من الذاكرة؛ وإلا فإنه NULL. .UNINDENT .TP \fBvoid bpf_ringbuf_submit(void *\fP\fIdata\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أرسل عينة المخزن الحلقي المحجوزة، والتي يشير إليها \fIdata\fP\&. إذا حُدد \fBBPF_RB_NO_WAKEUP\fP في \fIflags\fP، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد \fBBPF_RB_FORCE_WAKEUP\fP في \fIflags\fP، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد \fB0\fP في \fIflags\fP، يُرسل إشعار تكيفي بتوفر بيانات جديدة. .sp انظر \(aqbpf_ringbuf_output()\(aq لتعريف الإشعار التكيفي. .TP \fBالقيمة المعادة\fP لا شيء. ينجح دائماً. .UNINDENT .TP \fBvoid bpf_ringbuf_discard(void *\fP\fIdata\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تجاهل عينة المخزن الحلقي المحجوزة، والتي يشير إليها \fIdata\fP\&. إذا حُدد \fBBPF_RB_NO_WAKEUP\fP في \fIflags\fP، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد \fBBPF_RB_FORCE_WAKEUP\fP في \fIflags\fP، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد \fB0\fP في \fIflags\fP، يُرسل إشعار تكيفي بتوفر بيانات جديدة. .sp انظر \(aqbpf_ringbuf_output()\(aq لتعريف الإشعار التكيفي. .TP \fBالقيمة المعادة\fP لا شيء. ينجح دائماً. .UNINDENT .TP \fBu64 bpf_ringbuf_query(void *\fP\fIringbuf\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استعلم عن الخصائص المختلفة للمخزن الحلقي المقدم. ما يتم الاستعلام عنه بالضبط تحدده \fIflags\fP: .INDENT 7.0 .IP \(bu 2 \fBBPF_RB_AVAIL_DATA\fP: كمية البيانات التي لم تُستهلك بعد. .IP \(bu 2 \fBBPF_RB_RING_SIZE\fP: حجم المخزن الحلقي. .IP \(bu 2 \fBBPF_RB_CONS_POS\fP: موضع المستهلك (يمكن أن يلتف). .IP \(bu 2 \fBBPF_RB_PROD_POS\fP: موضع المنتج (المنتجين) (يمكن أن يلتف). .UNINDENT .sp البيانات المعادة هي مجرد لقطة لحظية للقيم الفعلية وقد تكون غير دقيقة، لذا يجب استخدام هذه الأداة لدعم الاستدلالات ولإعداد التقارير، وليس لإجراء حسابات صحيحة بنسبة 100%. .TP \fBالقيمة المعادة\fP القيمة المطلوبة، أو 0 إذا لم يُتعرف على \fIflags\fP. .UNINDENT .TP \fBlong bpf_csum_level(struct sk_buff *\fP\fIskb\fP\fB, u64 \fP\fIlevel\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP غيّر مستوى الاختبار التحسبي للـ skb بطبقة واحدة لأعلى أو لأسفل، أو أعد تعيينه بالكامل إلى لا شيء لجعل المكدس يقوم بالتحقق من الاختبار التحسبي. ينطبق المستوى على البروتوكولات التالية: TCP، وUDP، وGRE، وSCTP، وFCOE. على سبيل المثال، فك تغليف | ETH | IP | UDP | GUE | IP | TCP | إلى | ETH | IP | TCP | عبر مساعد \fBbpf_skb_adjust_room\fP() مع تمرير وسم \fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP سيتطلب استدعاءً واحداً لـ \fBbpf_csum_level\fP() مع \fBBPF_CSUM_LEVEL_DEC\fP نظراً لإزالة ترويسة UDP. وبالمثل، فإن تغليف الأخير في الأول يمكن أن يرافقه استدعاء مساعد لـ \fBbpf_csum_level\fP() مع \fBBPF_CSUM_LEVEL_INC\fP إذا كان لا يزال من المفترض معالجة skb في طبقات أعلى من المكدس بدلاً من مجرد الخروج عند tc. .sp هناك ثلاثة إعدادات مدعومة للمستوى في الوقت الحالي: .INDENT 7.0 .IP \(bu 2 \fBBPF_CSUM_LEVEL_INC\fP: يزيد skb\->csum_level لـ skbs التي تملك CHECKSUM_UNNECESSARY. .IP \(bu 2 \fBBPF_CSUM_LEVEL_DEC\fP: ينقص skb\->csum_level لـ skbs التي تملك CHECKSUM_UNNECESSARY. .IP \(bu 2 \fBBPF_CSUM_LEVEL_RESET\fP: يعيد تعيين skb\->csum_level إلى 0 ويضبط CHECKSUM_NONE لفرض التحقق من الاختبار التحسبي بواسطة المكدس. .IP \(bu 2 \fBBPF_CSUM_LEVEL_QUERY\fP: لا عملية، يعيد skb\->csum_level الحالي. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل. في حالة \fBBPF_CSUM_LEVEL_QUERY\fP، يُرجع skb\->csum_level الحالي أو رمز الخطأ \-EACCES في حالة عدم خضوع skb لـ CHECKSUM_UNNECESSARY. .UNINDENT .TP \fBstruct tcp6_sock *bpf_skc_to_tcp6_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل مؤشر \fIsk\fP ديناميكياً إلى مؤشر \fItcp6_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBstruct tcp_sock *bpf_skc_to_tcp_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل مؤشر \fIsk\fP ديناميكياً إلى مؤشر \fItcp_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBstruct tcp_timewait_sock *bpf_skc_to_tcp_timewait_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل مؤشر \fIsk\fP ديناميكياً إلى مؤشر \fItcp_timewait_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBstruct tcp_request_sock *bpf_skc_to_tcp_request_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل مؤشر \fIsk\fP ديناميكياً إلى مؤشر \fItcp_request_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBstruct udp6_sock *bpf_skc_to_udp6_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل مؤشر \fIsk\fP ديناميكياً إلى مؤشر \fIudp6_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBlong bpf_get_task_stack(struct task_struct *\fP\fItask\fP\fB, void *\fP\fIbuf\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إرجاع مكدس مستخدم أو مكدس نواة في المخزن المؤقت المقدم من برنامج bpf. ملاحظة: لن يُملأ مكدس المستخدم إلا إذا كانت المهمة \fItask\fP هي المهمة الحالية؛ وسترجع جميع المهام الأخرى \-EOPNOTSUPP. ولتحقيق ذلك، يحتاج المساعد إلى \fItask\fP، وهو مؤشر صالح لـ \fBstruct task_struct\fP\&. ولتخزين تتبع المكدس (stacktrace)، يقدم برنامج bpf مخزنًا \fIbuf\fP بحجم \fIsize\fP غير سالب. .sp الوسيط الأخير، \fIflags\fP، يحمل عدد أطر المكدس المراد تخطيها (من 0 إلى 255)، مغطاة بـ \fBBPF_F_SKIP_FIELD_MASK\fP\&. ويمكن استخدام البتات التالية لضبط الأعلام التالية: .INDENT 7.0 .TP \fBBPF_F_USER_STACK\fP جمع مكدس فضاء مستخدم بدلاً من مكدس نواة. يجب أن تكون المهمة \fItask\fP هي المهمة الحالية. .TP \fBBPF_F_USER_BUILD_ID\fP اجمع buildid+offset بدلاً من ips لمكدس المستخدم، وهذا صالح فقط إذا حُدد \fBBPF_F_USER_STACK\fP أيضاً. .UNINDENT .sp يمكن لـ \fBbpf_get_task_stack\fP() جمع ما يصل إلى \fBPERF_MAX_STACK_DEPTH\fP من إطارات النواة والمستخدم على حد سواء، بشرط وجود حجم مخزن مؤقت كبير كافٍ. لاحظ أنه يمكن التحكم في هذا الحد عبر برنامج \fBsysctl\fP، وأنه ينبغي زيادته يدوياً من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج Java). للقيام بذلك، استخدم: .INDENT 7.0 .INDENT 3.5 .sp .EX # sysctl kernel.perf_event_max_stack=<القيمة الجديدة> .EE .UNINDENT .UNINDENT .TP \fBالقيمة المعادة\fP طول \fIbuf\fP المنسوخ غير السالب المساوي لـ \fIsize\fP أو أقل منه عند النجاح، أو خطأ سالب في حالة الفشل. .UNINDENT .TP \fBlong bpf_load_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, void *\fP\fIsearchby_res\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحميل خيار الترويسة. دعم قراءة خيار ترويسة TCP معين لبرنامج bpf (\fBBPF_PROG_TYPE_SOCK_OPS\fP). .sp إذا كان \fIflags\fP هو 0، فسيُبحث عن الخيار من \fIskops\fP\fB\->skb_data\fP\&. يحتوي التعليق في \fBstruct bpf_sock_ops\fP على تفاصيل حول ما يحتويه skb_data تحت عمليات \fIskops\fP\fB\->op\fP المختلفة. .sp تحدد البايت الأولى من \fIsearchby_res\fP النوع الذي يُراد البحث عنه. .sp إذا كان نوع البحث نوعًا تجريبيًا (أي 253 أو 254 وفقًا للمعيار RFC6994)، فإنه يحتاج أيضًا إلى تحديد الـ "magic" الذي يكون إما 2 بايت أو 4 بايت. ثم يحتاج أيضًا إلى تحديد حجم الـ magic باستخدام البايت الثانية وهي "kind\-length" لخيار ترويسة TCP، وتتضمن "kind\-length" أيضًا أول بابتين "kind" و "kind\-length" نفسها كما يفعل خيار ترويسة TCP العادي. .sp على سبيل المثال، للبحث عن النوع التجريبي 254 مع magic بحجم 2 بايت وقيمته 0xeB9F، يجب أن يكون searchby_res هو [ 254, 4, 0xeB, 0x9F, 0, 0, .... 0 ]. .sp للبحث عن خيار مقياس النافذة القياسي (3)، يجب أن يكون \fIsearchby_res\fP هو [ 3, 0, 0, .... 0 ]. لاحظ أنه يجب أن يكون kind\-length صفرًا للخيار العادي. .sp البحث عن No\-Op (0) و End\-of\-Option\-List (1) غير مدعوم. .sp يجب أن يكون \fIlen\fP بابتين على الأقل، وهو الحد الأدنى لحجم خيار الترويسة. .sp الأعلام المدعومة: .INDENT 7.0 .IP \(bu 2 \fBBPF_LOAD_HDR_OPT_TCP_SYN\fP للبحث من حزمة saved_syn أو حزمة syn المستلمة لتوها. .UNINDENT .TP \fBالقيمة المعادة\fP > 0 عند العثور عليه، ويُنسخ خيار الترويسة إلى \fIsearchby_res\fP\&. القيمة المعادة هي الطول الإجمالي المنسوخ. عند الفشل، يُعاد رمز خطأ سالب: .sp \fB\-EINVAL\fP إذا كانت إحدى المعاملات غير صالحة. .sp \fB\-ENOMSG\fP إذا لم يُعثر على الخيار. .sp \fB\-ENOENT\fP إذا لم تكن حزمة syn متاحة عند استخدام \fBBPF_LOAD_HDR_OPT_TCP_SYN\fP. .sp \fB\-ENOSPC\fP إذا لم تتوفر مساحة كافية. نُسخ عدد \fIlen\fP من البايتات فقط. .sp \fB\-EFAULT\fP عند الفشل في تحليل خيارات الترويسة في الحزمة. .sp \fB\-EPERM\fP إذا تعذر استخدام المساعد تحت \fIskops\fP\fB\->op\fP الحالي\&. .UNINDENT .TP \fBlong bpf_store_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, const void *\fP\fIfrom\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تخزين خيار الترويسة. ستُنسخ البيانات من المخزن المؤقت \fIfrom\fP بطول \fIlen\fP إلى ترويسة TCP. .sp يجب أن يحتوي المخزن المؤقت \fIfrom\fP على الخيار بالكامل بما في ذلك النوع (kind)، وطول النوع (kind\-length)، وبيانات الخيار الفعلية. يجب أن يكون \fIlen\fP بطول kind\-length على الأقل. ليس بالضرورة أن يكون kind\-length بمحاذاة 4 بايت. ستتولى النواة الحشو (padding) وضبط قيمة المحاذاة لـ 4 بايت في th\->doff. .sp سيتحقق هذا المساعد من وجود خيارات مكررة بالبحث عن الخيار نفسه في skb الصادر. .sp لا يمكن استدعاء هذا المساعد إلا أثناء \fBBPF_SOCK_OPS_WRITE_HDR_OPT_CB\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل: .sp \fB\-EINVAL\fP إذا كانت المعامل غير صالحة. .sp \fB\-ENOSPC\fP إذا لم تتوفر مساحة كافية في الترويسة. لم يُكتب أي شيء. .sp \fB\-EEXIST\fP إذا كان الخيار موجودًا بالفعل. .sp \fB\-EFAULT\fP عند الفشل في تحليل خيارات الترويسة الموجودة. .sp \fB\-EPERM\fP إذا تعذر استخدام المساعد تحت \fIskops\fP\fB\->op\fP الحالي\&. .UNINDENT .TP \fBlong bpf_reserve_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, u32 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حجز \fIlen\fP بايت لخيار ترويسة bpf. ستُستخدم المساحة بواسطة \fBbpf_store_hdr_opt\fP() لاحقًا في \fBBPF_SOCK_OPS_WRITE_HDR_OPT_CB\fP\&. .sp إذا استُدعي \fBbpf_reserve_hdr_opt\fP() مرات متعددة، فسيُحجز إجمالي عدد البايتات. .sp لا يمكن استدعاء هذا المساعد إلا أثناء \fBBPF_SOCK_OPS_HDR_OPT_LEN_CB\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حالة الفشل: .sp \fB\-EINVAL\fP إذا كانت إحدى المعاملات غير صالحة. .sp \fB\-ENOSPC\fP إذا لم تتوفر مساحة كافية في الترويسة. .sp \fB\-EPERM\fP إذا تعذر استخدام المساعد تحت \fIskops\fP\fB\->op\fP الحالي\&. .UNINDENT .TP \fBvoid *bpf_inode_storage_get(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIinode\fP\fB, void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على bpf_local_storage من \fIinode\fP\&. .sp من الناحية المنطقية، يمكن اعتباره كالحصول على القيمة من \fImap\fP باستخدام \fIinode\fP كـ \fBمفتاح\fP\&. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن \fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIinode\fP) باستثناء أن هذا المساعد يفرض أن يكون المفتاح inode وأن تكون الخريطة أيضًا من نوع \fBBPF_MAP_TYPE_INODE_STORAGE\fP\&. .sp في الخلفية، تُخزن القيمة محليًا في \fIinode\fP بدلًا من الـ \fImap\fP\&. تُستخدم الـ \fImap\fP كـ "نوع" لـ bpf\-local\-storage. ويُبحث عن "نوع" bpf\-local\-storage (أي الـ \fImap\fP) في كافة bpf_local_storage الموجودة في \fIinode\fP\&. .sp يمكن استخدام \fIflags\fP اختيارية (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام \fIvalue\fP مع \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت \fIvalue\fP هي \fBNULL\fP، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية. .TP \fBالقيمة المعادة\fP يُعاد مؤشر bpf_local_storage عند النجاح. .sp \fBNULL\fP إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد. .UNINDENT .TP \fBint bpf_inode_storage_delete(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIinode\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حذف bpf_local_storage من \fIinode\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. .sp \fB\-ENOENT\fP إذا تعذر العثور على bpf_local_storage. .UNINDENT .TP \fBlong bpf_d_path(const struct path *\fP\fIpath\fP\fB, char *\fP\fIbuf\fP\fB, u32 \fP\fIsz\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إعادة المسار الكامل لكائن \fBstruct path\fP المعطى، والذي يجب أن يكون كائن \fIpath\fP الخاص بـ BTF للنواة. يُعاد المسار في المخزن المؤقت \fIbuf\fP المزود بحجم \fIsz\fP ويكون منتهيًا بـ NULL. .TP \fBالقيمة المعادة\fP عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة. .UNINDENT .TP \fBlong bpf_copy_from_user(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIuser_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP قراءة عدد \fIsize\fP من البايتات من عنوان مساحة المستخدم \fIuser_ptr\fP وتخزين البيانات في \fIdst\fP\&. هذا غلاف لـ \fBcopy_from_user\fP(). .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_snprintf_btf(char *\fP\fIstr\fP\fB, u32 \fP\fIstr_size\fP\fB, struct btf_ptr *\fP\fIptr\fP\fB, u32 \fP\fIbtf_ptr_size\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استخدام BTF لتخزين تمثيل نصي لـ \fIptr\fP\->ptr في \fIstr\fP، باستخدام \fIptr\fP\->type_id. يجب أن تحدد هذه القيمة النوع الذي يشير إليه \fIptr\fP\->ptr. يمكن استخدام LLVM __builtin_btf_type_id(type, 1) للبحث عن معرفات أنواع BTF في vmlinux. عبر تتبع بنية البيانات باستخدام BTF، تُخزن معلومات النوع والقيم في أول \fIstr_size\fP \- 1 بايت من \fIstr\fP\&. يُجرى نسخ آمن لبيانات المؤشر لتجنب انهيار النواة أثناء العملية. يمكن للأنواع الأصغر استخدام مساحة النصوص على المكدس؛ بينما يمكن للبرامج الأكبر استخدام بيانات الخريطة لتخزين التمثيل النصي. .sp يمكن مشاركة السلسلة لاحقًا مع مساحة المستخدم عبر bpf_perf_event_output() أو واجهات الذاكرة الحلقية (ring buffer). يجب تجنب bpf_trace_printk() لأنها تضع حدًا صغيرًا جدًا على حجم السلسلة مما يفقدها الفائدة. .sp \fIflags\fP هي مزيج من .INDENT 7.0 .TP \fBBTF_F_COMPACT\fP لا يوجد تنسيق حول معلومات النوع .TP \fBBTF_F_NONAME\fP لا توجد أسماء أو أنواع لأعضاء struct/union .TP \fBBTF_F_PTR_RAW\fP إظهار قيم المؤشر الخام (غير المموهة)؛ وهو ما يعادل محدد printk %px. .TP \fBBTF_F_ZERO\fP إظهار أعضاء struct/union ذات القيمة الصفرية؛ لا تُعرض مبدئيًا .UNINDENT .TP \fBالقيمة المعادة\fP عدد البايتات التي كُتبت (أو التي كانت ستُكتب إذا كان لابد من بتر المخرج بسبب حجم السلسلة)، أو خطأ سالب في حالات الفشل. .UNINDENT .TP \fBlong bpf_seq_printf_btf(struct seq_file *\fP\fIm\fP\fB, struct btf_ptr *\fP\fIptr\fP\fB, u32 \fP\fIptr_size\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استخدام BTF للكتابة إلى seq_write تمثيل نصي لـ \fIptr\fP\->ptr، باستخدام \fIptr\fP\->type_id كما هو الحال في bpf_snprintf_btf(). الـ \fIflags\fP مطابقة لتلك المستخدمة في bpf_snprintf_btf. .TP \fBالقيمة المعادة\fP 0 عند النجاح أو خطأ سالب في حالة الفشل. .UNINDENT .TP \fBu64 bpf_skb_cgroup_classid(struct sk_buff *\fP\fIskb\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP راجع \fBbpf_get_cgroup_classid\fP() للوصف الرئيسي. يختلف هذا المساعد عن \fBbpf_get_cgroup_classid\fP() في أن فئة net_cls الخاصة بـ cgroup v1 تُسترجع فقط من المقبس المرتبط بـ \fIskb\fP بدلًا من العملية الحالية. .TP \fBالقيمة المعادة\fP يُرجع المعرف أو 0 في حال تعذر جلب المعرف. .UNINDENT .TP \fBlong bpf_redirect_neigh(u32 \fP\fIifindex\fP\fB, struct bpf_redir_neigh *\fP\fIparams\fP\fB, int \fP\fIplen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP توجيه الحزمة إلى جهاز شبكة آخر بالفهرس \fIifindex\fP وملء عناوين L2 من النظام الفرعي المجاور. هذا المساعد مشابه نوعًا ما لـ \fBbpf_redirect\fP()، باستثناء أنه يملأ عناوين L2 أيضًا، مما يعني، داخليًا، أن المساعد يعتمد على البحث عن الجار للحصول على عنوان L2 للقفزة التالية (nexthop). .sp سيقوم المساعد بإجراء بحث FIB بناءً على ترويسة شبكة skb للحصول على عنوان القفزة التالية، ما لم يتم توفير ذلك من قبل المستدعِي في وسيطة \fIparams\fP. تشير وسيطة \fIplen\fP إلى طول \fIparams\fP ويجب ضبطها على 0 إذا كانت \fIparams\fP هي NULL. .sp وسيطة \fIflags\fP محجوزة ويجب أن تكون 0. المساعد مدعوم حاليًا فقط لأنواع برامج tc BPF، ومُفعّل لبروتوكولات IPv4 و IPv6. .TP \fBالقيمة المعادة\fP يعيد المساعد \fBTC_ACT_REDIRECT\fP عند النجاح أو \fBTC_ACT_SHOT\fP عند الخطأ. .UNINDENT .TP \fBvoid *bpf_per_cpu_ptr(const void *\fP\fIpercpu_ptr\fP\fB, u32 \fP\fIcpu\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أخذ مؤشر إلى ksym لكل معالج، \fIpercpu_ptr\fP، وإعادة مؤشر إلى متغير النواة لكل معالج على \fIcpu\fP\&. الـ ksym هو متغير خارجي (extern) مُزيّن بـ \(aq__ksym\(aq. بالنسبة لـ ksym، يوجد متغير عام (إما ساكن أو عام) مُعرّف بنفس الاسم في النواة. يكون ksym لكل معالج إذا كان المتغير العام لكل معالج. يشير المؤشر المعاد إلى المتغير العام لكل معالج على \fIcpu\fP\&. .sp يتمتع bpf_per_cpu_ptr() بنفس دلالات per_cpu_ptr() في النواة، باستثناء أن bpf_per_cpu_ptr() قد يعيد NULL. يحدث هذا إذا كان \fIcpu\fP أكبر من nr_cpu_ids. يجب على المستدعِي لـ bpf_per_cpu_ptr() التحقق من القيمة المعادة. .TP \fBالقيمة المعادة\fP مؤشر يشير إلى متغير النواة لكل معالج على \fIcpu\fP، أو NULL إذا كان \fIcpu\fP غير صالح. .UNINDENT .TP \fBvoid *bpf_this_cpu_ptr(const void *\fP\fIpercpu_ptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أخذ مؤشر إلى ksym لكل معالج، \fIpercpu_ptr\fP، وإعادة مؤشر إلى متغير النواة لكل معالج على هذا المعالج. راجع وصف \(aqksym\(aq في \fBbpf_per_cpu_ptr\fP(). .sp يتمتع bpf_this_cpu_ptr() بنفس دلالات this_cpu_ptr() في النواة. وبخلاف \fBbpf_per_cpu_ptr\fP()، فإنه لا يعيد NULL أبدًا. .TP \fBالقيمة المعادة\fP مؤشر يشير إلى متغير النواة لكل معالج على هذا المعالج. .UNINDENT .TP \fBlong bpf_redirect_peer(u32 \fP\fIifindex\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP توجيه الحزمة إلى جهاز شبكة آخر بالفهرس \fIifindex\fP\&. هذا المساعد مشابه نوعًا ما لـ \fBbpf_redirect\fP()، باستثناء أن التوجيه يحدث لجهاز النظير (peer) لـ \fIifindex\fP، ويحدث تبديل نطاق أسماء الشبكة (netns) من الدخول (ingress) إلى الدخول دون المرور عبر طابور الأعمال المؤجلة (backlog queue) للمعالج. .sp لا تُمسح \fIskb\fP\fB\->mark\fP و \fIskb\fP\fB\->tstamp\fP أثناء تبديل netns. .sp وسيطة \fIflags\fP محجوزة ويجب أن تكون 0. المساعد مدعوم حاليًا فقط لأنواع برامج tc BPF عند خطاف الدخول (ingress hook) ولأنواع الأجهزة المستهدفة veth و netkit. يجب أن يقع جهاز النظير في نطاق أسماء شبكة مختلف. .TP \fBالقيمة المعادة\fP يعيد المساعد \fBTC_ACT_REDIRECT\fP عند النجاح أو \fBTC_ACT_SHOT\fP عند الخطأ. .UNINDENT .TP \fBvoid *bpf_task_storage_get(struct bpf_map *\fP\fImap\fP\fB, struct task_struct *\fP\fItask\fP\fB, void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على bpf_local_storage من الـ \fItask\fP\&. .sp من الناحية المنطقية، يمكن اعتباره كالحصول على القيمة من \fImap\fP باستخدام \fItask\fP كـ \fBمفتاح\fP\&. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن \fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fItask\fP) باستثناء أن هذا المساعد يفرض أن يكون المفتاح task_struct وأن تكون الخريطة أيضًا من نوع \fBBPF_MAP_TYPE_TASK_STORAGE\fP\&. .sp في الخلفية، تُخزن القيمة محليًا في \fItask\fP بدلًا من الـ \fImap\fP\&. تُستخدم الـ \fImap\fP كـ "نوع" لـ bpf\-local\-storage. ويُبحث عن "نوع" bpf\-local\-storage (أي الـ \fImap\fP) في كافة bpf_local_storage الموجودة في \fItask\fP\&. .sp يمكن استخدام \fIflags\fP اختيارية (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام \fIvalue\fP مع \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت \fIvalue\fP هي \fBNULL\fP، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية. .TP \fBالقيمة المعادة\fP يُعاد مؤشر bpf_local_storage عند النجاح. .sp \fBNULL\fP إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد. .UNINDENT .TP \fBlong bpf_task_storage_delete(struct bpf_map *\fP\fImap\fP\fB, struct task_struct *\fP\fItask\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حذف bpf_local_storage من \fItask\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. .sp \fB\-ENOENT\fP إذا تعذر العثور على bpf_local_storage. .UNINDENT .TP \fBstruct task_struct *bpf_get_current_task_btf(void)\fP .INDENT 7.0 .TP \fBالوصف\fP إعادة مؤشر BTF للمهمة "الحالية". يمكن استخدام هذا المؤشر أيضًا في المساعدات التي تقبل \fIARG_PTR_TO_BTF_ID\fP من نوع \fItask_struct\fP\&. .TP \fBالقيمة المعادة\fP مؤشر للمهمة الحالية. .UNINDENT .TP \fBlong bpf_bprm_opts_set(struct linux_binprm *\fP\fIbprm\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط خيارات معينة أو امسحها في \fIbprm\fP: .sp ‏\fBBPF_F_BPRM_SECUREEXEC\fP لضبط بت التنفيذ الآمن (secureexec) الذي يضبط \fBAT_SECURE\fP auxv لـ glibc. ويُمسح البت إذا لم يُحدد العلم. .TP \fBالقيمة المعادة\fP ‏\fB\-EINVAL\fP إذا مُررت \fIflags\fP غير صالحة، وصفر فيما عدا ذلك. .UNINDENT .TP \fBu64 bpf_ktime_get_coarse_ns(void)\fP .INDENT 7.0 .TP \fBالوصف\fP أعد نسخة تقريبية من الوقت المنقضي منذ إقلاع الحاسوب، بالنانو ثانية. ولا يشمل الوقت الذي عُلق فيه الحاسوب. .sp انظر: \fBclock_gettime\fP(\fBCLOCK_MONOTONIC_COARSE\fP) .TP \fBالقيمة المعادة\fP الـ \fIktime\fP الحالي\&. .UNINDENT .TP \fBlong bpf_ima_inode_hash(struct inode *\fP\fIinode\fP\fB, void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُعيد وسم IMA المخزن لـ \fIinode\fP (إذا كان متاحًا). إذا كان الوسم أكبر من \fIsize\fP، فستُنسخ بايتات بقدر \fIsize\fP فقط إلى \fIdst\fP .TP \fBالقيمة المعادة\fP يُعاد \fBhash_algo\fP عند النجاح، أو \fB\-EOPNOTSUPP\fP إذا كانت IMA معطلة أو \fB\-EINVAL\fP إذا مُررت معاملات غير صالحة. .UNINDENT .TP \fBstruct socket *bpf_sock_from_file(struct file *\fP\fIfile\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إذا كان الملف المعطى يمثل مقبسًا، فيُعيد المقبس المرتبط به. .TP \fBالقيمة المعادة\fP مؤشر إلى struct socket عند النجاح أو NULL إذا لم يكن الملف مقبسًا. .UNINDENT .TP \fBlong bpf_check_mtu(void *\fP\fIctx\fP\fB, u32 \fP\fIifindex\fP\fB, u32 *\fP\fImtu_len\fP\fB, s32 \fP\fIlen_diff\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحقق من حجم الحزمة للتأكد من عدم تجاوزه لوحدة النقل القصوى (MTU) لجهاز الشبكة (بناءً على \fIifindex\fP). من المرجح استخدام هذا المساعد مع مساعدين آخرين يعدلون/يغيرون حجم الحزمة. .sp يمكن استخدام المعامل \fIlen_diff\fP للاستعلام مع تغيير مخطط له في الحجم. يتيح هذا التحقق من MTU قبل تغيير سياق (ctx) الحزمة. إن تقديم تعديل \fIlen_diff\fP أكبر من حجم الحزمة الفعلي (مما يؤدي إلى حجم حزمة سالب) لن يتجاوز MTU من حيث المبدأ، ولهذا السبب لا يُعتبر فشلاً. هناك حاجة إلى مساعدي BPF آخرين لإجراء تغيير الحجم المخطط له؛ ولذلك تقع مسؤولية اكتشاف حجم الحزمة السالب على عاتق أولئك المساعدين. .sp تحديد \fIifindex\fP كصفر يعني إجراء فحص MTU مقابل جهاز الشبكة الحالي. هذا أمر عملي إذا لم يُستخدم هذا قبل إعادة التوجيه. .sp عند الإدخال، يجب أن يكون \fImtu_len\fP مؤشرًا صالحًا، وإلا سيرفض المدقق برنامج BPF. إذا هُيئَت قيمة \fImtu_len\fP إلى الصفر، فسيُستخدم حجم حزمة سياق (ctx). عند تقديم قيمة \fImtu_len\fP كمدخل، فإن هذا يحدد طول الطبقة الثالثة (L3) الذي يُجرى فحص MTU مقابله. تذكر أن طولي XDP و TC يعملان في الطبقة الثانية (L2)، لكن هذه القيمة هي L3 لأنها ترتبط بقيم MTU و IP\-header tot_len التي تنتمي للطبقة L3 (سلوك مشابه لـ bpf_fib_lookup). .sp يمكن لجدول توجيه نواة لينكس ضبط وحدات MTU على مستوى مسار أكثر تحديدًا، وهو ما لا يوفره هذا المساعد. لفحوصات MTU على مستوى المسار، استخدم المساعد \fBbpf_fib_lookup\fP(). .sp سياق \fIctx\fP هو إما \fBstruct xdp_md\fP لبرامج XDP أو \fBstruct sk_buff\fP لبرامج tc cls_act. .sp يمكن أن يكون معامل \fIflags\fP مزيجًا من قيمة واحدة أو أكثر من القيم التالية: .INDENT 7.0 .TP \fBBPF_MTU_CHK_SEGS\fP هذا العلم سيعمل فقط مع سياق \fIctx\fP من نوع \fBstruct sk_buff\fP. إذا احتوى سياق الحزمة على مخازن مؤقتة إضافية لقطع الحزمة (تُعرف غالبًا باسم GSO skb)، فإن فحص MTU يكون أصعب في هذه المرحلة، لأنه في مسار الإرسال من الممكن إعادة تقسيم حزمة skb (اعتمادًا على ميزات جهاز الشبكة). قد يظل هذا انتهاكًا لـ MTU، لذا يُمكّن هذا العلم إجراء فحص MTU مقابل القطع، مع رمز إرجاع مختلف للانتهاك لتمييزه. لا يمكن للفحص استخدام len_diff. .UNINDENT .sp عند الإرجاع، يحتوي مؤشر \fImtu_len\fP على قيمة MTU لجهاز الشبكة. تذكر أن وحدة MTU المضبوطة لجهاز الشبكة هي حجم L3، وهو ما يُعاد هنا بينما يعمل طول XDP و TC في L2. يأخذ المساعد هذا في الحسبان من أجلك، لكن تذكر ذلك عند استخدام قيمة MTU في كود BPF الخاص بك. .TP \fBالقيمة المعادة\fP .INDENT 7.0 .IP \(bu 2 0 عند النجاح، وتُملأ قيمة MTU في مؤشر \fImtu_len\fP. .IP \(bu 2 أقل من 0 إذا كان أي معامل إدخال غير صالح (لا يُحدث \fImtu_len\fP) .UNINDENT .sp تعيد انتهاكات MTU قيمًا موجبة، ولكنها تملأ أيضًا قيمة MTU في مؤشر \fImtu_len\fP، حيث يمكن أن يكون ذلك مطلوبًا لتنفيذ معالجة PMTU: .INDENT 7.0 .IP \(bu 2 \fBBPF_MTU_CHK_RET_FRAG_NEEDED\fP .IP \(bu 2 \fBBPF_MTU_CHK_RET_SEGS_TOOBIG\fP .UNINDENT .UNINDENT .TP \fBlong bpf_for_each_map_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لكل عنصر في \fBmap\fP، استدعِ دالة \fBcallback_fn\fP مع \fBmap\fP و \fBcallback_ctx\fP ومعاملات أخرى خاصة بالخريطة. يجب أن تكون دالة \fBcallback_fn\fP دالة ساكنة ويجب أن يكون \fBcallback_ctx\fP مؤشرًا إلى المكدس. تُستخدم \fBflags\fP للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون \fBflags\fP صفراً. .sp فيما يلي قائمة بأنواع الخرائط المدعومة وتوقيعات الاستدعاء المتوقعة لكل منها: .sp BPF_MAP_TYPE_HASH, BPF_MAP_TYPE_PERCPU_HASH, BPF_MAP_TYPE_LRU_HASH, BPF_MAP_TYPE_LRU_PERCPU_HASH, BPF_MAP_TYPE_ARRAY, BPF_MAP_TYPE_PERCPU_ARRAY .sp long (*callback_fn)(struct bpf_map *map, const void *key, void *value, void *ctx); .sp بالنسبة لخرائط per_cpu، فإن map_value هي القيمة الموجودة على المعالج الذي يعمل عليه bpf_prog. .sp إذا أعادت \fBcallback_fn\fP القيمة 0، فسيستمر المساعد إلى العنصر التالي. إذا كانت القيمة المعادة 1، فسيقوم المساعد بتخطي بقية العناصر والعودة. قيم الإرجاع الأخرى لا تُستخدم الآن. .TP \fBالقيمة المعادة\fP عدد عناصر الخريطة المقطوعة عند النجاح، أو \fB\-EINVAL\fP لأعلام \fBflags\fP غير صالحة. .UNINDENT .TP \fBlong bpf_snprintf(char *\fP\fIstr\fP\fB, u32 \fP\fIstr_size\fP\fB, const char *\fP\fIfmt\fP\fB, u64 *\fP\fIdata\fP\fB, u32 \fP\fIdata_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُخرج سلسلة نصية إلى مخزن \fBstr\fP المؤقت بحجم \fBstr_size\fP بناءً على سلسلة تنسيق مخزنة في خريطة للقراءة فقط يشير إليها \fBfmt\fP. .sp يتوافق كل محدد تنسيق في \fBfmt\fP مع عنصر u64 واحد في مصفوفة \fBdata\fP. بالنسبة للسلاسل والمؤشرات حيث يتم الوصول إلى المشار إليهم، تُخزن قيم المؤشر فقط في مصفوفة \fIdata\fP. المعامل \fIdata_len\fP هو حجم \fIdata\fP بالبايت \- ويجب أن يكون مضاعفًا للرقم 8. .sp تتطلب التنسيقات \fB%s\fP و \fB%p{i,I}{4,6}\fP قراءة ذاكرة النواة. قد تفشل قراءة ذاكرة النواة إما بسبب عنوان غير صالح أو عنوان صالح ولكنه يتطلب خطأً كبيرًا في الذاكرة. إذا فشلت قراءة ذاكرة النواة، فستكون السلسلة لـ \fB%s\fP سلسلة فارغة، وسيكون عنوان ip لـ \fB%p{i,I}{4,6}\fP هو 0. عدم إرجاع خطأ إلى برنامج bpf يتوافق مع ما يفعله \fBbpf_trace_printk\fP() في الوقت الحالي. .TP \fBالقيمة المعادة\fP طول السلسلة المنسقة الموجب تمامًا، بما في ذلك حرف الصفر اللاحق. إذا كانت القيمة المعادة أكبر من \fBstr_size\fP، فسيحتوي \fBstr\fP على سلسلة مقتطعة، مضمونة أن تكون منتهية بصفر إلا عندما تكون \fBstr_size\fP صفراً. .sp أو \fB\-EBUSY\fP إذا كان المخزن المؤقت لنسخ ذاكرة per\-CPU مشغولاً. .UNINDENT .TP \fBlong bpf_sys_bpf(u32 \fP\fIcmd\fP\fB, void *\fP\fIattr\fP\fB, u32 \fP\fIattr_size\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP نفذ استدعاء نظام bpf بالمعاملات المعطاة. .TP \fBالقيمة المعادة\fP نتيجة استدعاء نظام. .UNINDENT .TP \fBlong bpf_btf_find_by_name_kind(char *\fP\fIname\fP\fB, int \fP\fIname_sz\fP\fB, u32 \fP\fIkind\fP\fB, int \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ابحث عن نوع BTF بالاسم والنوع المعطى في vmlinux BTF أو في BTFs للوحدة. .TP \fBالقيمة المعادة\fP يُعيد btf_id و btf_obj_fd في الـ 32 بت السفلى والعليا. .UNINDENT .TP \fBlong bpf_sys_close(u32 \fP\fIfd\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP نفذ استدعاء نظام الإغلاق لـ FD المعطى. .TP \fBالقيمة المعادة\fP نتيجة استدعاء نظام. .UNINDENT .TP \fBlong bpf_timer_init(struct bpf_timer *\fP\fItimer\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP هيئ الميقاتية. أول 4 بتات من \fIflags\fP تحدد clockid. يُسمح فقط بـ CLOCK_MONOTONIC و CLOCK_REALTIME و CLOCK_BOOTTIME. جميع البتات الأخرى من \fIflags\fP محجوزة. سيرفض المدقق البرنامج إذا لم تكن الميقاتية \fItimer\fP من نفس الخريطة \fImap\fP. .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EBUSY\fP إذا كانت الميقاتية \fItimer\fP مهيأة بالفعل. \fB\-EINVAL\fP إذا مُررت أعلام \fIflags\fP غير صالحة. \fB\-EPERM\fP إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر. .UNINDENT .TP \fBlong bpf_timer_set_callback(struct bpf_timer *\fP\fItimer\fP\fB, void *\fP\fIcallback_fn\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط الميقاتية لاستدعاء دالة \fIcallback_fn\fP الساكنة. .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EINVAL\fP إذا لم تُهيأ الميقاتية \fItimer\fP بـ bpf_timer_init() سابقًا. \fB\-EPERM\fP إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر. .UNINDENT .TP \fBlong bpf_timer_start(struct bpf_timer *\fP\fItimer\fP\fB, u64 \fP\fInsecs\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط انتهاء صلاحية الميقاتية بعد N نانو ثانية من الوقت الحالي. سيُستدعى الاستدعاء الراجع المكون في سياق المقاطعة البرمجية (soft irq) على معالج ما ولن يتكرر إلا إذا أُجري bpf_timer_start() آخر. في هذه الحالة، يمكن أن ينتقل الاستدعاء التالي إلى معالج مختلف. بما أن struct bpf_timer هو حقل داخل عنصر الخريطة، فإن الخريطة تمتلك الميقاتية. ستقوم bpf_timer_set_callback() بزيادة عداد المراجع (refcnt) لبرنامج BPF للتأكد من بقاء كود callback_fn صالحًا. عندما يصل مرجع مساحة المستخدم إلى خريطة ما إلى الصفر، تُلغى جميع الميقاتيات في الخريطة وتُخفض عدادات المراجع للبرامج المقابلة. يُفعل ذلك للتأكد من أن Ctrl\-C لعملية مستخدم لا تترك أي ميقاتيات تعمل. إذا ثُبتت الخريطة في bpffs، فيمكن لـ callback_fn إعادة تسليح نفسها إلى ما لا نهاية. تقوم مساعدات bpf_map_update/delete_elem() وأوامر sys_bpf لمساحة المستخدم بإلغاء وتحرير الميقاتية في عنصر الخريطة المعطى. يمكن أن تحتوي الخريطة على ميقاتيات تستدعي callback_fn من برامج مختلفة. يمكن لنفس callback_fn أن تخدم ميقاتيات مختلفة من خرائط مختلفة إذا كان تخطيط المفتاح/القيمة متطابقًا عبر الخرائط. يمكن أن يكون لكل bpf_timer_set_callback() دالة callback_fn مختلفة. .sp يمكن لـ \fIflags\fP أن يكون واحدًا مما يلي: .INDENT 7.0 .TP \fBBPF_F_TIMER_ABS\fP ابدأ الميقاتية بقيمة انتهاء مطلقة بدلاً من القيمة النسبية المبدئية. .TP \fBBPF_F_TIMER_CPU_PIN\fP ستُثبت الميقاتية في المعالج الخاص بالمستدعي. .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EINVAL\fP إذا لم تُهيأ الميقاتية \fItimer\fP بـ bpf_timer_init() سابقًا أو مُررت أعلام \fIflags\fP غير صالحة. .UNINDENT .TP \fBlong bpf_timer_cancel(struct bpf_timer *\fP\fItimer\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP ألفِ الميقاتية وانتظر انتهاء callback_fn إذا كانت تعمل. .TP \fBالقيمة المعادة\fP 0 إذا لم تكن الميقاتية نشطة. 1 إذا كانت الميقاتية نشطة. \fB\-EINVAL\fP إذا لم تُهيأ الميقاتية \fItimer\fP بـ bpf_timer_init() سابقًا. \fB\-EDEADLK\fP إذا حاولت callback_fn استدعاء bpf_timer_cancel() على ميقاتيتها الخاصة مما قد يؤدي إلى طريق مسدود (deadlock) بخلاف ذلك. .UNINDENT .TP \fBu64 bpf_get_func_ip(void *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على عنوان الدالة المتتبعة (لبرامج التتبع و kprobe). .sp عند استدعائه لبرنامج kprobe متصل كـ uprobe فإنه يعيد عنوان المسبار لكل من uprobe الدخول والعودة. .TP \fBالقيمة المعادة\fP عنوان الدالة المتتبعة لـ kprobe. وصفر لـ kprobes الموضوعة داخل الدالة (ليس عند الدخول). وعنوان المسبار لـ uprobe و return uprobe. .UNINDENT .TP \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على قيمة bpf_cookie المقدمة (اختياريًا) أثناء اتصال البرنامج. قد تختلف لكل اتصال فردي، حتى لو كان برنامج BPF نفسه هو نفسه. يتوقع سياق برنامج BPF كأول معامل \fIctx\fP. .INDENT 7.0 .TP \fBمدعوم لأنواع البرامج التالية:\fP .INDENT 7.0 .IP \(bu 2 kprobe/uprobe؛ .IP \(bu 2 tracepoint؛ .IP \(bu 2 perf_event. .UNINDENT .UNINDENT .TP \fBالقيمة المعادة\fP القيمة التي حددها المستخدم عند إنشاء رابط BPF/وقت الاتصال أو 0، إذا لم تُحدد. .UNINDENT .TP \fBlong bpf_task_pt_regs(struct task_struct *\fP\fItask\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على struct pt_regs المرتبط بـ \fBtask\fP. .TP \fBالقيمة المعادة\fP مؤشر إلى struct pt_regs. .UNINDENT .TP \fBlong bpf_get_branch_snapshot(void *\fP\fIentries\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على تتبع الفرع من محركات العتاد مثل Intel LBR. يُوقف محرك العتاد بعد فترة وجيزة من استدعاء المساعد. لذلك، يحتاج المستخدم إلى تصفية مدخلات الفروع بناءً على حالة الاستخدام الفعلية. لالتقاط تتبع الفرع قبل نقطة انطلاق برنامج BPF، يجب استدعاء المساعد في بداية برنامج BPF. .sp تُخزن البيانات كـ struct perf_branch_entry في مخزن المخرجات المؤقت \fIentries\fP. المعامل \fIsize\fP هو حجم \fIentries\fP بالبايت. المعامل \fIflags\fP محجوز حاليًا ويجب أن يكون صفراً. .TP \fBالقيمة المعادة\fP عند النجاح، عدد البايتات المكتوبة في \fIbuf\fP\&. عند الخطأ، قيمة سالبة. .sp ‏\fB\-EINVAL\fP إذا لم تكن \fIflags\fP صفراً. .sp \fB\-ENOENT\fP إذا كانت المعمارية لا تدعم سجلات الفروع. .UNINDENT .TP \fBlong bpf_trace_vprintk(const char *\fP\fIfmt\fP\fB, u32 \fP\fIfmt_size\fP\fB, const void *\fP\fIdata\fP\fB, u32 \fP\fIdata_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يسلك سلوك مساعد \fBbpf_trace_printk\fP()، ولكنه يأخذ مصفوفة من u64 لتنسيقها ويمكنه التعامل مع المزيد من معاملات التنسيق كنتيجة لذلك. .sp يجب استخدام المعاملات كما في المساعد \fBbpf_seq_printf\fP(). .TP \fBالقيمة المعادة\fP عدد البايتات المكتوبة في المخزن المؤقت، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBstruct unix_sock *bpf_skc_to_unix_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حول مؤشر \fIsk\fP ديناميكيًا إلى مؤشر \fIunix_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBlong bpf_kallsyms_lookup_name(const char *\fP\fIname\fP\fB, int \fP\fIname_sz\fP\fB, int \fP\fIflags\fP\fB, u64 *\fP\fIres\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على عنوان رمز النواة، ويُعاد في \fIres\fP. يُضبط \fIres\fP إلى 0 إذا لم يُعثر على الرمز. .TP \fBالقيمة المعادة\fP عند النجاح، صفر. عند الخطأ، قيمة سالبة. .sp ‏\fB\-EINVAL\fP إذا لم تكن \fIflags\fP صفراً. .sp ‏\fB\-EINVAL\fP إذا لم يكن حجم السلسلة \fIname\fP هو نفس حجم \fIname_sz\fP. .sp ‏\fB\-ENOENT\fP إذا لم يُعثر على الرمز. .sp ‏\fB\-EPERM\fP إذا لم يملك المستدعِي إذنًا للحصول على عنوان النواة. .UNINDENT .TP \fBlong bpf_find_vma(struct task_struct *\fP\fItask\fP\fB, u64 \fP\fIaddr\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP البحث عن vma للمهمة \fItask\fP التي تحتوي على \fIaddr\fP، واستدعاء دالة \fIcallback_fn\fP مع \fItask\fP و \fIvma\fP و \fIcallback_ctx\fP\&. يجب أن تكون \fIcallback_fn\fP دالة ساكنة، ويجب أن يكون \fIcallback_ctx\fP مؤشرًا إلى المكدس. تُستخدم \fIflags\fP للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون \fIflags\fP صفرًا. .sp توقيع الاستدعاء الراجع المتوقع هو .sp long (*callback_fn)(struct task_struct *task, struct vm_area_struct *vma, void *callback_ctx); .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-ENOENT\fP إذا كان \fItask\->mm\fP هو NULL، أو إذا لم تتضمن أي vma العنوان \fIaddr\fP\&. \fB\-EBUSY\fP في حال الفشل في محاولة قفل mmap_lock. \fB\-EINVAL\fP لأجل \fBflags\fP غير صالحة. .UNINDENT .TP \fBlong bpf_loop(u32 \fP\fInr_loops\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP لعدد \fBnr_loops\fP، تُستدعى دالة \fBcallback_fn\fP مع \fBcallback_ctx\fP كمعامل سياق. يجب أن تكون \fBcallback_fn\fP دالة ساكنة، ويجب أن يكون \fBcallback_ctx\fP مؤشرًا إلى المكدس. تُستخدم \fBflags\fP للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون \fBflags\fP صفرًا. حاليًا، nr_loops محدود بـ 1 << 23 (حوالي 8 ملايين) حلقة. .sp long (*callback_fn)(u64 index, void *ctx); .sp حيث \fBindex\fP هو الفهرس الحالي في الحلقة. يبدأ الفهرس من الصفر. .sp إذا أعادت \fBcallback_fn\fP القيمة 0، فسيستمر المساعد في الحلقة التالية. إذا كانت القيمة المعادة 1، فسيقوم المساعد بتخطي بقية الحلقات والعودة. قيم الإرجاع الأخرى لا تُستخدم الآن، وسيرفضها المدقق. .TP \fBالقيمة المعادة\fP عدد الحلقات التي نُفذت، أو \fB\-EINVAL\fP لأعلام \fBflags\fP غير صالحة، أو \fB\-E2BIG\fP إذا تجاوز \fBnr_loops\fP الحد الأقصى لعدد الحلقات. .UNINDENT .TP \fBlong bpf_strncmp(const char *\fP\fIs1\fP\fB, u32 \fP\fIs1_sz\fP\fB, const char *\fP\fIs2\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP إجراء strncmp() بين \fBs1\fP و \fBs2\fP\&. لا يلزم أن يكون \fBs1\fP منتهيًا بـ null، و \fBs1_sz\fP هو أقصى حجم تخزين لـ \fBs1\fP\&. يجب أن يكون \fBs2\fP سلسلة للقراءة فقط. .TP \fBالقيمة المعادة\fP عدد صحيح أقل من، أو يساوي، أو أكبر من الصفر إذا وُجد أن أول \fBs1_sz\fP بايت من \fBs1\fP أقل من، أو تطابق، أو أكبر من \fBs2\fP\&. .UNINDENT .TP \fBlong bpf_get_func_arg(void *\fP\fIctx\fP\fB, u32 \fP\fIn\fP\fB, u64 *\fP\fIvalue\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على سجل المعامل رقم \fBn\fP (بدءًا من الصفر) للدالة المتعقبة (لبرامج التعقب) ويُعاد في \fBvalue\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EINVAL\fP إذا كان n >= عدد سجلات المعاملات للدالة المتعقبة. .UNINDENT .TP \fBlong bpf_get_func_ret(void *\fP\fIctx\fP\fB, u64 *\fP\fIvalue\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP الحصول على قيمة الإعادة للدالة المتعقبة (لبرامج التعقب) في \fBvalue\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EOPNOTSUPP\fP لبرامج التعقب بخلاف BPF_TRACE_FEXIT أو BPF_MODIFY_RETURN. .UNINDENT .TP \fBlong bpf_get_func_arg_cnt(void *\fP\fIctx\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على عدد سجلات الدالة المقتفاة (لبرامج الاقتفاء) حيث تُخزن وسائط الدالة في هذه السجلات. .TP \fBالقيمة المعادة\fP عدد سجلات الوسائط للدالة المقتفاة. .UNINDENT .TP \fBint bpf_get_retval(void)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا. .sp هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno. .TP \fBالقيمة المعادة\fP قيمة إرجاع برنامج BPF. .UNINDENT .TP \fBint bpf_set_retval(int \fP\fIretval\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اضبط قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا. .sp هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno. .sp لاحظ وجود الحالة الحدية التالية حيث يصدر البرنامج خطأً عبر bpf_set_retval لكنه يشير إلى النجاح عبر \(aqreturn 1\(aq: .INDENT 7.0 .INDENT 3.5 bpf_set_retval(\-EPERM); return 1; .UNINDENT .UNINDENT .sp في هذه الحالة، ستستخدم قيمة إرجاع برنامج BPF قيمة المساعد \-EPERM. يظل هذا صحيحًا بالنسبة لـ cgroup/bind{4,6} التي تدعم حالة النجاح الإضافية \(aqreturn 3\(aq. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBu64 bpf_xdp_get_buff_len(struct xdp_buff *\fP\fIxdp_md\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على الحجم الكلي لصوان xdp معطى (المنطقة الخطية والمفصحة) .TP \fBالقيمة المعادة\fP الحجم الكلي لصوان xdp معطى. .UNINDENT .TP \fBlong bpf_xdp_load_bytes(struct xdp_buff *\fP\fIxdp_md\fP\fB, u32 \fP\fIoffset\fP\fB, void *\fP\fIbuf\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP وُفر هذا المساعد كطريقة سهلة لتحميل البيانات من صوان xdp. يمكن استخدامه لتحميل \fIlen\fP من البايتات من الإزاحة \fIoffset\fP من الإطار المرتبط بـ \fIxdp_md\fP، إلى الصوان الذي يشير إليه \fIbuf\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_xdp_store_bytes(struct xdp_buff *\fP\fIxdp_md\fP\fB, u32 \fP\fIoffset\fP\fB, void *\fP\fIbuf\fP\fB, u32 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP خزّن \fIlen\fP من البايتات من الصوان \fIbuf\fP في الإطار المرتبط بـ \fIxdp_md\fP، عند الإزاحة \fIoffset\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBlong bpf_copy_from_user_task(void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB, const void *\fP\fIuser_ptr\fP\fB, struct task_struct *\fP\fItsk\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اقرأ \fIsize\fP بايت من عنوان فضاء المستخدم \fIuser_ptr\fP في فضاء عناوين \fItsk\fP، ويخزن البيانات في \fIdst\fP\&. لا تُستخدم \fIflags\fP حاليًا ووُفرت للتوسع المستقبلي. لا يمكن استخدام هذا المساعد إلا بواسطة البرامج القابلة للنوم. .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. عند الخطأ، يُصفر الصوان \fIdst\fP. .UNINDENT .TP \fBlong bpf_skb_set_tstamp(struct sk_buff *\fP\fIskb\fP\fB, u64 \fP\fItstamp\fP\fB, u32 \fP\fItstamp_type\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP غيّر __sk_buff\->tstamp_type إلى \fItstamp_type\fP واضبط \fItstamp\fP في __sk_buff\->tstamp معًا. .sp إذا لم تكن هناك حاجة لتغيير __sk_buff\->tstamp_type، فيمكن كتابة قيمة tstamp مباشرة في __sk_buff\->tstamp بدلاً من ذلك. .sp BPF_SKB_TSTAMP_DELIVERY_MONO هي بصمة الوقت الوحيدة التي سيُحتفظ بها أثناء bpf_redirect_*(). يجب استخدام \fItstamp\fP غير صفري مع \fItstamp_type\fP من نوع BPF_SKB_TSTAMP_DELIVERY_MONO\&. .sp لا يمكن استخدام BPF_SKB_TSTAMP_UNSPEC كـ \fItstamp_type\fP إلا مع \fItstamp\fP صفري\&. .sp بروتوكولات skb\->protocol المدعومة هي IPv4 و IPv6 فقط. .sp هذه الدالة مفيدة للغاية عند الحاجة لضبط وقت تسليم أحادي (mono) في __sk_buff\->tstamp ثم bpf_redirect_*() إلى مخرج (egress) واجهة ما. على سبيل المثال، تغيير بصمة وقت (الاستلام) في __sk_buff\->tstamp عند المدخل إلى وقت تسليم أحادي ثم bpf_redirect_*() إلى \%\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. \fB\-EINVAL\fP لمدخلات غير صالحة، و \fB\-EOPNOTSUPP\fP لبروتوكول غير مدعوم. .UNINDENT .TP \fBlong bpf_ima_file_hash(struct file *\fP\fIfile\fP\fB, void *\fP\fIdst\fP\fB, u32 \fP\fIsize\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يُرجع بصمة (hash) IMA المحسوبة لـ \fIfile\fP\&. إذا كانت البصمة أكبر من \fIsize\fP، فسيُنسخ \fIsize\fP بايت فقط إلى \fIdst\fP .TP \fBالقيمة المعادة\fP يُرجع \fBhash_algo\fP عند النجاح، أو \fB\-EOPNOTSUPP\fP إذا فشل حساب البصمة، أو \fB\-EINVAL\fP إذا مُررت وسائط غير صالحة. .UNINDENT .TP \fBvoid *bpf_kptr_xchg(void *\fP\fIdst\fP\fB, void *\fP\fIptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP بادل kptr عند المؤشر \fIdst\fP بـ \fIptr\fP، وأرجع القيمة القديمة. يمكن لـ \fIdst\fP أن يكون قيمة خريطة أو kptr محلي. يمكن لـ \fIptr\fP أن يكون NULL، وإلا فيجب أن يكون مؤشرًا مرجعيًا سيُحرر عند استدعاء هذا المساعد. .TP \fBالقيمة المعادة\fP القيمة القديمة لـ kptr (والتي يمكن أن تكون NULL). المؤشر المُرجع، إن لم يكن NULL، هو مرجع يجب تحريره باستخدام دالة التحرير المقابلة له، أو نقله إلى خريطة BPF قبل خروج البرنامج. .UNINDENT .TP \fBvoid *bpf_map_lookup_percpu_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB, u32 \fP\fIcpu\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أجرِ بحثًا في \fIpercpu map\fP عن مدخل مرتبط بـ \fIkey\fP على وحدة المعالجة المركزية \fIcpu\fP\&. .TP \fBالقيمة المعادة\fP قيمة الخريطة المرتبطة بـ \fIkey\fP على وحدة المعالجة \fIcpu\fP، أو \fBNULL\fP إذا لم يُعثر على مدخل أو كانت وحدة المعالجة المركزية \fIcpu\fP غير صالحة. .UNINDENT .TP \fBstruct mptcp_sock *bpf_skc_to_mptcp_sock(void *\fP\fIsk\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حوّل (cast) مؤشر \fIsk\fP حركيًا إلى مؤشر \fImptcp_sock\fP. .TP \fBالقيمة المعادة\fP \fIsk\fP إذا كان التحويل صالحاً، وإلا فإنه \fBNULL\fP. .UNINDENT .TP \fBlong bpf_dynptr_from_mem(void *\fP\fIdata\fP\fB, u64 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على dynptr إلى الذاكرة المحلية \fIdata\fP\&. .sp يجب أن يكون \fIdata\fP مؤشرًا لقيمة خريطة. الحجم الأقصى \fIsize\fP المدعوم هو DYNPTR_MAX_SIZE. لا تُستخدم \fIflags\fP حاليًا. .TP \fBالقيمة المعادة\fP 0 عند النجاح، و \-E2BIG إذا تجاوز الحجم DYNPTR_MAX_SIZE، و \-EINVAL إذا لم تكن الأعلام 0. .UNINDENT .TP \fBlong bpf_ringbuf_reserve_dynptr(void *\fP\fIringbuf\fP\fB, u32 \fP\fIsize\fP\fB, u64 \fP\fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احجز \fIsize\fP بايت من الحمولة في صوان حلقي \fIringbuf\fP عبر واجهة dynptr. يجب أن تكون \fIflags\fP هي 0. .sp يرجى ملاحظة أنه يجب استدعاء bpf_ringbuf_submit_dynptr أو bpf_ringbuf_discard_dynptr المقابلة على \fIptr\fP، حتى لو فشل الحجز. يُفرض هذا بواسطة المصدق (verifier). .TP \fBالقيمة المعادة\fP 0 عند النجاح، أو خطأ سالب في حال الفشل. .UNINDENT .TP \fBvoid bpf_ringbuf_submit_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP أرسل عينة الصوان الحلقي المحجوزة، التي يشير إليها \fIdata\fP، عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL. .sp لمزيد من المعلومات حول \fIflags\fP، يرجى مراجعة \(aqbpf_ringbuf_submit\(aq. .TP \fBالقيمة المعادة\fP لا شيء. ينجح دائماً. .UNINDENT .TP \fBvoid bpf_ringbuf_discard_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP انبذ عينة الصوان الحلقي المحجوزة عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL. .sp لمزيد من المعلومات حول \fIflags\fP، يرجى مراجعة \(aqbpf_ringbuf_discard\(aq. .TP \fBالقيمة المعادة\fP لا شيء. ينجح دائماً. .UNINDENT .TP \fBlong bpf_dynptr_read(void *\fP\fIdst\fP\fB, u64 \fP\fIlen\fP\fB, const struct bpf_dynptr *\fP\fIsrc\fP\fB, u64 \fP\fIoffset\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اقرأ \fIlen\fP بايت من \fIsrc\fP إلى \fIdst\fP، بدءًا من الإزاحة \fIoffset\fP في \fIsrc\fP\&. لا تُستخدم \fIflags\fP حاليًا. .TP \fBالقيمة المعادة\fP 0 عند النجاح، و \-E2BIG إذا تجاوز مجموع \fIoffset\fP + \fIlen\fP طول بيانات \fIsrc\fP، و \-EINVAL إذا كان \fIsrc\fP عبارة عن dynptr غير صالح أو إذا لم تكن \fIflags\fP تساوي 0. .UNINDENT .TP \fBlong bpf_dynptr_write(const struct bpf_dynptr *\fP\fIdst\fP\fB, u64 \fP\fIoffset\fP\fB, void *\fP\fIsrc\fP\fB, u64 \fP\fIlen\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP اكتب \fIlen\fP بايت من \fIsrc\fP في \fIdst\fP، بدءًا من الإزاحة \fIoffset\fP في \fIdst\fP\&. .sp يجب أن تكون \fIflags\fP هي 0 باستثناء dynptrs من نوع skb. .INDENT 7.0 .TP \fBبالنسبة لـ dynptrs من نوع skb:\fP .INDENT 7.0 .IP \(bu 2 تُبطل جميع شرائح بيانات dynptr آليًا بعد \fBbpf_dynptr_write\fP(). وذلك لأن الكتابة قد تسحب skb وتغير صوان الحزمة الأساسي. .IP \(bu 2 بخصوص \fIflags\fP، يرجى مراجعة الأعلام التي تقبلها \fBbpf_skb_store_bytes\fP(). .UNINDENT .UNINDENT .TP \fBالقيمة المعادة\fP 0 عند النجاح، و \-E2BIG إذا تجاوز مجموع \fIoffset\fP + \fIlen\fP طول بيانات \fIdst\fP، و \-EINVAL إذا كان \fIdst\fP عبارة عن dynptr غير صالح أو إذا كان \fIdst\fP عبارة عن dynptr للقراءة فقط أو إذا كانت \fIflags\fP غير صحيحة. بالنسبة لـ dynptrs من نوع skb، تتوافق الأخطاء الأخرى مع الأخطاء التي تُرجعها \fBbpf_skb_store_bytes\fP(). .UNINDENT .TP \fBvoid *bpf_dynptr_data(const struct bpf_dynptr *\fP\fIptr\fP\fB, u64 \fP\fIoffset\fP\fB, u64 \fP\fIlen\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP احصل على مؤشر لبيانات dynptr الأساسية. .sp يجب أن تكون \fIlen\fP قيمة معروفة ثابتة. تُبطل شريحة البيانات المُرجعة متى ما أُبطل dynptr. .sp قد لا تستخدم dynptrs من نوع skb و xdp الدالة bpf_dynptr_data. وعليها استخدام bpf_dynptr_slice و bpf_dynptr_slice_rdwr بدلاً من ذلك. .TP \fBالقيمة المعادة\fP مؤشر إلى بيانات dynptr الأساسية، أو NULL إذا كان dynptr للقراءة فقط، أو إذا كان dynptr غير صالح، أو إذا كانت الإزاحة والطول خارج الحدود. .UNINDENT .TP \fBs64 bpf_tcp_raw_gen_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32 \fP\fIth_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حاول إصدار كعكة SYN للحزمة مع ترويسات IPv4/TCP المقابلة، \fIiph\fP و \fIth\fP، دون الاعتماد على مقبس استماع. .sp يشير \fIiph\fP إلى ترويسة IPv4. .sp يشير \fIth\fP إلى بداية ترويسة TCP، بينما يحتوي \fIth_len\fP على طول ترويسة TCP (على الأقل \fBsizeof\fP(\fBstruct tcphdr\fP)). .TP \fBالقيمة المعادة\fP عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EINVAL\fP إذا كان \fIth_len\fP غير صالح. .UNINDENT .TP \fBs64 bpf_tcp_raw_gen_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32 \fP\fIth_len\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP حاول إصدار كعكة SYN للحزمة مع ترويسات IPv6/TCP المقابلة، \fIiph\fP و \fIth\fP، دون الاعتماد على مقبس استماع. .sp يشير \fIiph\fP إلى ترويسة IPv6. .sp يشير \fIth\fP إلى بداية ترويسة TCP، بينما يحتوي \fIth_len\fP على طول ترويسة TCP (على الأقل \fBsizeof\fP(\fBstruct tcphdr\fP)). .TP \fBالقيمة المعادة\fP عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EINVAL\fP إذا كان \fIth_len\fP غير صالح. .sp \fB\-EPROTONOSUPPORT\fP إذا لم يكن CONFIG_IPV6 مدمجًا. .UNINDENT .TP \fBlong bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحقق مما إذا كان \fIiph\fP و \fIth\fP يحتويان على ACK صالح لكعكة SYN دون الاعتماد على مقبس استماع. .sp يشير \fIiph\fP إلى ترويسة IPv4. .sp يشير \fIth\fP إلى ترويسة TCP. .TP \fBالقيمة المعادة\fP 0 إذا كان \fIiph\fP و \fIth\fP يمثلان ACK صالحًا لكعكة SYN. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EACCES\fP إذا كانت كعكة SYN غير صالحة. .UNINDENT .TP \fBlong bpf_tcp_raw_check_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP تحقق مما إذا كان \fIiph\fP و \fIth\fP يحتويان على ACK صالح لكعكة SYN دون الاعتماد على مقبس استماع. .sp يشير \fIiph\fP إلى ترويسة IPv6. .sp يشير \fIth\fP إلى ترويسة TCP. .TP \fBالقيمة المعادة\fP 0 إذا كان \fIiph\fP و \fIth\fP يمثلان ACK صالحًا لكعكة SYN. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EACCES\fP إذا كانت كعكة SYN غير صالحة. .sp \fB\-EPROTONOSUPPORT\fP إذا لم يكن CONFIG_IPV6 مدمجًا. .UNINDENT .TP \fBu64 bpf_ktime_get_tai_ns(void)\fP .INDENT 7.0 .TP \fBالوصف\fP ساعة على مستوى النظام غير قابلة للضبط، مُشتقة من وقت ساعة الحائط ولكنها تتجاهل الثواني الكبيسة. لا تتعرض هذه الساعة لانقطاعات أو قفزات إلى الوراء ناتجة عن إدراج بروتوكول وقت الشبكة (NTP) لثوانٍ كبيسة كما يحدث في CLOCK_REALTIME. .sp انظر: \fBclock_gettime\fP(\fBCLOCK_TAI\fP) .TP \fBالقيمة المعادة\fP الـ \fIktime\fP الحالي\&. .UNINDENT .TP \fBlong bpf_user_ringbuf_drain(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIctx\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP استنزاف العينات من مخزن حلقة المستخدم المحدد، واستدعاء الاستدعاء المرجعي المقدم لكل عينة من هذا القبيل: .sp long (*callback_fn)(const struct bpf_dynptr *dynptr, void *ctx); .sp إذا أعاد \fBcallback_fn\fP القيمة 0، سيستمر المساعد في محاولة استنزاف العينة التالية، بحد أقصى قدره BPF_MAX_USER_RINGBUF_SAMPLES عينة. إذا كانت القيمة المعادة 1، سيتخطى المساعد بقية العينات ويعود. لا تُستخدم قيم الإعادة الأخرى حاليًا، وسيُرفض من قبل المُتحقق (verifier). .TP \fBالقيمة المعادة\fP عدد العينات التي استُنزفت إذا لم يُواجه أي خطأ أثناء الاستنزاف، أو 0 إذا لم توجد عينات في مخزن الحلقة. إذا كان مُنتج مساحة المستخدم ينتظر عبر epoll على هذه الخريطة، واستُنزفت عينة واحدة على الأقل، فسيصلهم إشعار حدث يُعلمهم بتوفر مساحة في مخزن الحلقة. إذا مُررت علامة BPF_RB_NO_WAKEUP إلى هذه الدالة، لن يُرسل إشعار تنبيه. وإذا مُررت علامة BPF_RB_FORCE_WAKEUP، فسيُرسل إشعار تنبيه حتى لو لم تُستنزف أي عينة. .sp عند الفشل، تكون القيمة المرجعة واحدة مما يلي: .sp \fB\-EBUSY\fP إذا كان مخزن الحلقة متنازعًا عليه، وكان سياق استدعاء آخر يستنزف مخزن الحلقة بشكل متزامن. .sp \fB\-EINVAL\fP إذا كانت مساحة المستخدم لا تتتبع مخزن الحلقة بشكل صحيح بسبب عدم محاذاة موضع المُنتج إلى 8 بايتات، أو عدم محاذاة العينة إلى 8 بايتات، أو عدم مطابقة موضع المُنتج للطول المعلن للعينة. .sp \fB\-E2BIG\fP إذا حاولت مساحة المستخدم نشر عينة أكبر من حجم مخزن الحلقة، أو عينة لا يمكن احتواؤها داخل struct bpf_dynptr. .UNINDENT .TP \fBvoid *bpf_cgrp_storage_get(struct bpf_map *\fP\fImap\fP\fB, struct cgroup *\fP\fIcgroup\fP\fB, void *\fP\fIvalue\fP\fB, u64 \fP\fIflags\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يجلب bpf_local_storage من \fIcgroup\fP\&. .sp من الناحية المنطقية، يمكن اعتباره جلبًا للقيمة من \fImap\fP باستخدام \fIcgroup\fP بصفته \fBkey\fP\&. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن \fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIcgroup\fP) باستثناء أن هذا المساعد يفرض أن يكون المفتاح بنية cgroup وأن تكون الخريطة أيضًا من نوع \fBBPF_MAP_TYPE_CGRP_STORAGE\fP\&. .sp في الواقع، قيمة التخزين المحلي (local\-storage) مدمجة مباشرة داخل كائن \fIcgroup\fP نفسه، بدلاً من وجودها في الخريطة \fBBPF_MAP_TYPE_CGRP_STORAGE\fP. عندما تُستعلم قيمة التخزين المحلي لخريطة \fImap\fP معينة على كائن \fIcgroup\fP، ستقوم النواة بإجراء تكرار O(n) على جميع قيم التخزين المحلي النشطة لذلك الكائن \fIcgroup\fP حتى تُعثر على قيمة التخزين المحلي الخاصة بالخريطة \fImap\fP. .sp يمكن استخدام \fIflags\fP اختيارية (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام \fIvalue\fP مع \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت \fIvalue\fP هي \fBNULL\fP، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية. .TP \fBالقيمة المعادة\fP يُعاد مؤشر bpf_local_storage عند النجاح. .sp \fBNULL\fP إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد. .UNINDENT .TP \fBlong bpf_cgrp_storage_delete(struct bpf_map *\fP\fImap\fP\fB, struct cgroup *\fP\fIcgroup\fP\fB)\fP .INDENT 7.0 .TP \fBالوصف\fP يحذف bpf_local_storage من \fIcgroup\fP\&. .TP \fBالقيمة المعادة\fP 0 عند النجاح. .sp \fB\-ENOENT\fP إذا تعذر العثور على bpf_local_storage. .UNINDENT .UNINDENT .SH أمثلة .sp تتوفر أمثلة لاستخدام معظم مساعدي eBPF المدرجين في صفحة الدليل هذه داخل مصادر نواة لينكس، في المواقع التالية: .INDENT 0.0 .IP \(bu 2 \fIsamples/bpf/\fP .IP \(bu 2 \fItools/testing/selftests/bpf/\fP .UNINDENT .SH الرخصة .sp يمكن أن يكون لبرامج eBPF رخصة مرتبطة بها، تُمرر مع تعليمات كود البايت إلى النواة عند تحميل البرامج. تنسيق تلك السلسلة النصية مطابق للتنسيق المستخدم في وحدات النواة (يمكن استخدام تراخيص مزدوجة، مثل "Dual BSD/GPL"). بعض الدوال المساعدة لا يمكن الوصول إليها إلا للبرامج المتوافقة مع رخصة جنو العمومية (GNU GPL). .sp لاستخدام هؤلاء المساعدين، يجب تحميل برنامج eBPF مع تمرير سلسلة الترخيص الصحيحة (عبر \fBattr\fP) إلى استدعاء النظام \fBbpf\fP()، ويُترجم هذا بشكل عام في كود المصدر بلغة C للبرنامج باحتوائه على سطر مشابه لما يلي: .INDENT 0.0 .INDENT 3.5 .sp .EX char ____license[] __attribute__((section("license"), used)) = "GPL"; .EE .UNINDENT .UNINDENT .SH التنفيذ .sp صفحة الدليل هذه هي جهد لتوثيق دوال مساعد eBPF الموجودة. ولكن حتى وقت كتابة هذا التقرير، يخضع نظام BPF الفرعي لتطوير مكثف. تُضاف أنواع برامج أو خرائط eBPF جديدة، إلى جانب دوال مساعدة جديدة. تُتاح بعض المساعدات أحيانًا لأنواع برامج إضافية. لذا على الرغم من جهود المجتمع، قد لا تكون هذه الصفحة محدثة. إذا كنت ترغب في التحقق بنفسك من دوال المساعدة الموجودة في نواتك، أو أنواع البرامج التي تدعمها، فإليك بعض الملفات في شجرة النواة التي قد تهمك: .INDENT 0.0 .IP \(bu 2 \fIinclude/uapi/linux/bpf.h\fP هو ترويسة BPF الرئيسة. ويحتوي على القائمة الكاملة لجميع الدوال المساعدة، بالإضافة إلى العديد من تعريفات BPF الأخرى بما في ذلك معظم العلامات أو البنى أو الثوابت التي يستخدمها المساعدون. .IP \(bu 2 يحتوي \fInet/core/filter.c\fP على تعريف معظم الدوال المساعدة المتعلقة بالشبكة، وقائمة أنواع البرامج التي يمكن استخدامها منها. .IP \(bu 2 \fIkernel/trace/bpf_trace.c\fP هو المكافئ لمعظم المساعدين المتعلقين ببرامج التتبع. .IP \(bu 2 يحتوي \fIkernel/bpf/verifier.c\fP على الدوال المستخدمة للتحقق من استخدام أنواع صالحة من خرائط eBPF مع دالة مساعدة معينة. .IP \(bu 2 يحتوي دليل \fIkernel/bpf/\fP على ملفات أخرى تُعرف فيها مساعدات إضافية (للمجموعات التحكيمية cgroups، وخرائط المقابس sockmaps، وما إلى ذلك). .IP \(bu 2 يمكن استخدام أداة bpftool لسبر مدى توفر الدوال المساعدة على النظام (بالإضافة إلى أنواع البرامج والخرائط المدعومة، وعدد من المعلمات الأخرى). للقيام بذلك، شغّل \fBbpftool feature probe\fP (انظر \fBbpftool\-feature\fP(8) للحصول على التفاصيل). أضف الكلمة المفتاحية \fBunprivileged\fP لسرد الميزات المتاحة للمستخدمين غير المتميزين. .UNINDENT .sp يمكن العثور على التوافق بين الدوال المساعدة وأنواع البرامج بشكل عام في الملفات التي تُعرف فيها الدوال المساعدة. ابحث عن كائنات \fBstruct bpf_func_proto\fP وعن الدوال التي تعيدها: تحتوي هذه الدوال على قائمة بالمساعدين الذين يمكن لنوع برنامج معين استدعاؤهم. لاحظ أن لصيقة \fBdefault:\fP في \fBswitch ... case\fP المستخدمة لتصفية المساعدين يمكنها استدعاء دوال أخرى، تسمح هي نفسها بالوصول إلى مساعدين إضافيين. متطلبات رخصة GPL موجودة أيضًا في تلك \fBstruct bpf_func_proto\fP\&. .sp يمكن العثور على التوافق بين الدوال المساعدة وأنواع الخرائط في دالة \fBcheck_map_func_compatibility\fP() في ملف \fIkernel/bpf/verifier.c\fP\&. .sp الدوال المساعدة التي تُبطل الفحوصات على مؤشري \fBdata\fP و \fBdata_end\fP لمعالجة الشبكة مدرجة في دالة \fBbpf_helper_changes_pkt_data\fP() في ملف \fInet/core/filter.c\fP\&. .SH "انظر أيضًا" .sp \fBbpf\fP(2), \fBbpftool\fP(8), \fBcgroups\fP(7), \fBip\fP(8), \fBperf_event_open\fP(2), \fBsendmsg\fP(2), \fBsocket\fP(7), \fBtc\-bpf\fP(8) .\" End of generated man page. .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .