BPF-HELPERS(7)

الاسم
مساعدات-BPF - قائمة دوال eBPF المساعدة

الوصف

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

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

نظراً لاتفاقيات eBPF، لا يمكن للمساعد أن يمتلك أكثر من خمسة وسائط.

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

هذا المستند محاولة لسرد وتوثيق المساعدات المتاحة لمطوري eBPF. رُتبت ترتيباً زمنياً (أقدم المساعدات في النواة بالأعلى).

المساعدات

void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)

الوصف
    أجرِ بحثاً في map عن مدخلة مرتبطة بـ key.

القيمة المعادة
    قيمة الخريطة المرتبطة بـ key، أو NULL إذا لم تُعثر على أي مدخلة.

long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags)

الوصف
    أضف أو حدّث قيمة المدخلة المرتبطة بـ key في map بالقيمة value. تكون الـ flags واحدة مما يلي:

BPF_NOEXIST
    يجب ألا تكون المدخلة لـ key موجودة في الخريطة.

BPF_EXIST
    يجب أن تكون المدخلة لـ key موجودة بالفعل في الخريطة.

BPF_ANY
    لا يوجد شرط على وجود المدخلة لـ key.

    لا يمكن استخدام قيمة الراية BPF_NOEXIST للخرائط من الأنواع BPF_MAP_TYPE_ARRAY أو BPF_MAP_TYPE_PERCPU_ARRAY (جميع العناصر موجودة دائماً)، سيعيد المساعد خطأً.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_map_delete_elem(struct bpf_map *map, const void *key)

الوصف
    احذف المدخلة ذات المفتاح key من map.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_probe_read(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    لبرامج التتبع، حاول بأمان قراءة size بايت من عنوان مساحة النواة unsafe_ptr وخزّن البيانات في dst.

    بشكل عام، استخدم bpf_probe_read_user() أو bpf_probe_read_kernel() بدلاً من ذلك.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u64 bpf_ktime_get_ns(void)

الوصف
    أعد الوقت المنقضي منذ إقلاع النظام، بالنانوثانية. لا يشمل الوقت الذي عُلق فيه النظام. انظر: clock_gettime(CLOCK_MONOTONIC)

القيمة المعادة
    الـ ktime الحالي.

long bpf_trace_printk(const char *fmt, u32 fmt_size, ...)

الوصف
    هذا المساعد هو وسيلة "شبيهة بـ printk()" للتنقيح. يطبع رسالة معرفة بتنسيق fmt (بحجم fmt_size) إلى الملف /sys/kernel/tracing/trace من TraceFS، إذا كان متاحاً. يمكنه أخذ ما يصل إلى ثلاثة وسائط u64 إضافية (كمساعد eBPF، يقتصر إجمالي عدد الوسائط على خمسة).

    في كل مرة يُستدعى فيها المساعد، يلحق سطراً بالتتبع. تُهمل الأسطر بينما يكون /sys/kernel/tracing/trace مفتوحاً، استخدم /sys/kernel/tracing/trace_pipe لتجنب ذلك. تنسيق التتبع قابل للتخصيص، ويعتمد المخرج الدقيق الذي ستحصل عليه على الخيارات المحددة في /sys/kernel/tracing/trace_options (انظر أيضاً ملف README في الدليل نفسه). ومع ذلك، فإنه عادة ما يكون افتراضياً كالتالي:

        telnet-470   [001] .N.. 419421.045894: 0x00000001: <formatted msg>

    فيما سبق:

•   telnet هو اسم المهمة الحالية.

•   470 هو معرف العملية (PID) للمهمة الحالية.

•   001 هو رقم وحدة المعالجة المركزية التي تعمل عليها المهمة.

•   في .N..، يشير كل حرف إلى مجموعة من الخيارات (ما إذا كانت irqs ممكنة، خيارات الجدولة، ما إذا كانت hard/softirqs تعمل، مستوى preempt_disabled على التوالي). تعني N أن TIF_NEED_RESCHED و PREEMPT_NEED_RESCHED مضبوطان.

•   419421.045894 هو ختم زمني.

•   0x00000001 هي قيمة وهمية يستخدمها BPF لسجل مؤشر التعليمات.

•   <formatted msg> هي الرسالة المنسقة بـ fmt.

    محددات التحويل التي يدعمها fmt مشابهة، لكنها محدودة أكثر مما هي عليه في printk(). وهي %d و %i و %u و %x و %ld و %li و %lu و %lx و %lld و %lli و %llu و %llx و %p و %s. لا يتوفر أي معدل (حجم الحقل، الحشو بالأصفار، إلخ)، و سيعيد المساعد -EINVAL (لكن لن يطبع شيئاً) إذا واجه محدداً غير معروف.

    أيضاً، لاحظ أن bpf_trace_printk() بطيئة، ويجب استخدامها فقط لأغراض التنقيح. لهذا السبب، تُطبع كتلة تنبيه (تمتد لعدة أسطر) في سجلات النواة وتذكر أنه لا ينبغي استخدام المساعد "للاستخدام في الإنتاج" في المرة الأولى التي يُستخدم فيها هذا المساعد (أو بمزيد من الدقة، عند تخصيص مخازن trace_printk() المؤقتة). لتمرير القيم إلى مساحة المستخدم، يفضل استخدام أحداث perf.

القيمة المعادة
    عدد البايتات المكتوبة في المخزن المؤقت، أو خطأ سالب في حال الفشل.

u32 bpf_get_prandom_u32(void)

الوصف
    احصل على رقم عشوائي زائف.

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

القيمة المعادة
    قيمة غير موقعة عشوائية بطول 32 بت.

u32 bpf_get_smp_processor_id(void)

الوصف
    احصل على معرف معالج SMP (تعدد المعالجة المتماثل). لاحظ أن جميع البرامج تعمل مع تعطيل الهجرة، مما يعني أن معرف معالج SMP مستقر طوال فترة تنفيذ البرنامج.

القيمة المعادة
    معرف SMP للمعالج الذي يشغل البرنامج.

long bpf_skb_store_bytes(struct sk_buff *skb, u32 offset, const void *from, u32 len, u64 flags)

الوصف
    خزّن len بايت من العنوان from في الحزمة المرتبطة بـ skb، عند الإزاحة offset. الـ flags هي مزيج من القيم التالية:

BPF_F_RECOMPUTE_CSUM
    حدّث skb->csum آلياً بعد تخزين البايتات.

BPF_F_INVALIDATE_HASH
    اضبط skb->hash و skb->swhash و skb->l4hash على 0.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_l3_csum_replace(struct sk_buff *skb, u32 offset, u64 from, u64 to, u64 size)

الوصف
    أعد حساب مجموع فحص الطبقة 3 (مثل IP) للحزمة المرتبطة بـ skb. الحساب تراكمي، لذا يجب أن يعرف المساعد القيمة السابقة لحقل الترويسة الذي عُدل (from)، والقيمة الجديدة لهذا الحقل (to)، وعدد البايتات (2 أو 4) لهذا الحقل، المخزنة في size. بدلاً من ذلك، يمكن تخزين الفرق بين القيمتين السابقة والجديدة لحقل الترويسة في to، بضبط from و size على 0. لكلا الطريقتين، تشير offset إلى موقع مجموع فحص IP داخل الحزمة.

    يعمل هذا المساعد بالاشتراك مع bpf_csum_diff()، والتي لا تحدث مجموع الفحص في مكانه، ولكنها توفر مرونة أكبر ويمكنها التعامل مع أحجام أكبر من 2 أو 4 لمجموع الفحص المراد تحديثه.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_l4_csum_replace(struct sk_buff *skb, u32 offset, u64 from, u64 to, u64 flags)

الوصف
    أعد حساب مجموع فحص الطبقة 4 (مثل TCP أو UDP أو ICMP) للحزمة المرتبطة بـ skb. الحساب تراكمي، لذا يجب أن يعرف المساعد القيمة السابقة لحقل الترويسة الذي عُدل (from)، والقيمة الجديدة لهذا الحقل (to)، وعدد البايتات (2 أو 4) لهذا الحقل، المخزنة في البتات الأربعة الدنيا من flags. بدلاً من ذلك، يمكن تخزين الفرق بين القيمتين السابقة والجديدة لحقل الترويسة في to، بضبط from والبتات الأربعة الدنيا من flags على 0. لكلا الطريقتين، تشير offset إلى موقع مجموع فحص IP داخل الحزمة. بالإضافة إلى حجم الحقل، يمكن إضافة (أو المنطقية bitwise OR) رايات فعلية إلى flags. مع BPF_F_MARK_MANGLED_0، يُترك مجموع الفحص الصفري دون مساس (ما لم تُضف BPF_F_MARK_ENFORCE أيضاً)، وبالنسبة للتحديثات التي تؤدي إلى مجموع فحص صفري، تُضبط القيمة على CSUM_MANGLED_0 بدلاً من ذلك. تشير الراية BPF_F_PSEUDO_HDR إلى أن حقل الترويسة المعدل هو جزء من الترويسة الوهمية. يجب ضبط الراية BPF_F_IPV6 لحزم IPv6.

    يعمل هذا المساعد بالاشتراك مع bpf_csum_diff()، والتي لا تحدث مجموع الفحص في مكانه، ولكنها توفر مرونة أكبر ويمكنها التعامل مع أحجام أكبر من 2 أو 4 لمجموع الفحص المراد تحديثه.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_tail_call(void *ctx, struct bpf_map *prog_array_map, u32 index)

الوصف
    يُستخدم هذا المساعد الخاص لإطلاق "نداء ذيلي"، أو بعبارة أخرى، للقفز إلى برنامج eBPF آخر. يُستخدم إطار المكدس نفسه (لكن القيم الموجودة في المكدس وفي السجلات للمستدعِي لا يمكن للمستدعَى الوصول إليها). تسمح هذه الآلية بتسلسل البرامج، إما لرفع الحد الأقصى لعدد تعليمات eBPF المتاحة، أو لتنفيذ برامج معينة في كتل شرطية. لأسباب أمنية، هناك حد أقصى لعدد النداءات الذيلية المتعاقبة التي يمكن إجراؤها.

    عند استدعاء هذا المساعد، يحاول البرنامج القفز إلى برنامج يُشار إليه في الفهرس index في prog_array_map، وهي خريطة خاصة من النوع BPF_MAP_TYPE_PROG_ARRAY، ويمرر ctx، وهو مؤشر للسياق.

    إذا نجح النداء، تشغل النواة فوراً التعليمات الأولى للبرنامج الجديد. هذا ليس استدعاء دالة، ولا يعود أبداً إلى البرنامج السابق. إذا فشل النداء، فلن يكون للمساعد أي تأثير، و يستمر المستدعِي في تشغيل تعليماته اللاحقة. يمكن أن يفشل النداء إذا كان برنامج الوجهة للقفز غير موجود (أي أن index أكبر من عدد المدخلات في prog_array_map)، أو إذا وصل إلى الحد الأقصى لعدد النداءات الذيلية لسلسلة البرامج هذه. هذا الحد معرف في النواة بواسطة الماكرو MAX_TAIL_CALL_CNT (لا يمكن لمساحة المستخدم الوصول إليه)، وهو مضبوط حالياً على 33.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_clone_redirect(struct sk_buff *skb, u32 ifindex, u64 flags)

الوصف
    استنسخ الحزمة المرتبطة بـ skb وأعد توجيهها إلى جهاز شبكة آخر ذو الفهرس ifindex. يمكن استخدام كل من واجهات الدخول (ingress) والخروج (egress) لإعادة التوجيه. تُستخدم القيمة BPF_F_INGRESS في flags للتمييز (يُختار مسار الدخول إذا كانت الراية موجودة، ومسار الخروج بخلاف ذلك). هذه هي الراية الوحيدة المدعومة حالياً.

    بالمقارنة مع المساعد bpf_redirect()، فإن bpf_clone_redirect() تتحمل التكلفة المرتبطة بمضاعفة مخزن الحزمة المؤقت، ولكن يمكن تنفيذ ذلك خارج برنامج eBPF. وعلى العكس من ذلك، فإن bpf_redirect() أكثر كفاءة، ولكنها تُعالج من خلال رمز إجراء حيث يحدث إعادة التوجيه فقط بعد عودة برنامج eBPF.

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

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

u64 bpf_get_current_pid_tgid(void)

الوصف
    احصل على pid و tgid الحاليين.

القيمة المعادة
    عدد صحيح بطول 64 بت يحتوي على tgid و pid الحاليين، ويُنشأ كالتالي: current_task->tgid << 32 | current_task->pid.

u64 bpf_get_current_uid_gid(void)

الوصف
    احصل على uid و gid الحاليين.

القيمة المعادة
    عدد صحيح بطول 64 بت يحتوي على GID و UID الحاليين، ويُنشأ كالتالي: current_gid << 32 | current_uid.

long bpf_get_current_comm(void *buf, u32 size_of_buf)

الوصف
    انسخ سمة comm للمهمة الحالية إلى buf بحجم size_of_buf. تحتوي سمة comm على اسم الملف التنفيذي (باستثناء المسار) للمهمة الحالية. يجب أن يكون size_of_buf موجباً تماماً. عند النجاح، يتأكد المساعد من أن buf ينتهي بـ NUL. عند الفشل، يملأ بالأصفار.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u32 bpf_get_cgroup_classid(struct sk_buff *skb)

الوصف
    استرجع الـ classid للمهمة الحالية، أي لمجموعة net_cls cgroup التي تنتمي إليها skb.

    يمكن استخدام هذا المساعد في مسار خروج (egress) الـ TC، وليس في الدخول (ingress).

    توفر net_cls cgroup واجهة لوسم حزم الشبكة بناءً على معرف يوفره المستخدم لجميع الزيارات القادمة من المهام المنتمية إلى الـ cgroup ذات الصلة. انظر أيضاً توثيق النواة ذو الصلة، المتاح من مصادر لينكس في الملف Documentation/admin-guide/cgroup-v1/net_cls.rst.

    نواة لينكس لديها نسختان من الـ cgroups: هناك cgroups v1 و cgroups v2. كلاهما متاح للمستخدمين، الذين يمكنهم استخدام مزيج منهما، ولكن لاحظ أن net_cls cgroup هي لـ cgroup v1 فقط. وهذا يجعلها غير متوافقة مع برامج BPF التي تعمل على cgroups، وهي ميزة خاصة بـ cgroup-v2 فقط (يمكن للمقبس أن يحمل بيانات لنسخة واحدة فقط من cgroups في المرة الواحدة).

    يتوفر هذا المساعد فقط إذا جُمعت النواة مع ضبط خيار تكوين CONFIG_CGROUP_NET_CLASSID على "y" أو "m".

القيمة المعادة
    الـ classid، أو 0 للـ classid المبدئي غير المضبوط.

long bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 vlan_tci)

الوصف
    ادفع vlan_tci (معلومات التحكم في وسم VLAN) من البروتوكول vlan_proto إلى الحزمة المرتبطة بـ skb، ثم حدّث مجموع الفحص. لاحظ أنه إذا كان vlan_proto مختلفاً عن ETH_P_8021Q و ETH_P_8021AD، فإنه يُعتبر ETH_P_8021Q.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_vlan_pop(struct sk_buff *skb)

الوصف
    اسحب ترويسة VLAN من الحزمة المرتبطة بـ skb.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_get_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, u32 size, u64 flags)

الوصف
    جلب بيانات النفق الوصفية (metadata). تأخذ هذه الدالة المساعدة مؤشرًا key إلى struct bpf_tunnel_key فارغ ذي حجم size، حيث سيُملأ ببيانات النفق الوصفية للحزمة المرتبطة بـ skb. يمكن ضبط الـ flags على BPF_F_TUNINFO_IPV6، مما يشير إلى أن النفق يعتمد على بروتوكول IPv6 بدلاً من IPv4.

    إن الـ struct bpf_tunnel_key هو كائن يعمم المعاملات الرئيسة المستخدمة في بروتوكولات الأنفاق المختلفة في هيكل واحد. بهذه الطريقة، يمكن استخدامه لاتخاذ قرار بسهولة بناءً على محتويات ترويسة التغليف، "الملخصة" في هذا الهيكل. وعلى وجه الخصوص، فإنه يحمل عنوان IP للطرف البعيد (IPv4 أو IPv6، حسب الحالة) في key->remote_ipv4 أو key->remote_ipv6. كما يكشف هذا الهيكل عن key->tunnel_id، والذي يُربط عمومًا بـ VNI (مُعرف الشبكة الافتراضية)، مما يجعله قابلاً للبرمجة جنبًا إلى جنب مع الدالة المساعدة bpf_skb_set_tunnel_key().

    لنتخيل أن الكود التالي هو جزء من برنامج متصل بواجهة دخول TC، على أحد طرفي نفق GRE، ومن المفترض أن يقوم بتصفية جميع الرسائل القادمة من أطراف بعيدة بعنوان IPv4 غير 10.0.0.1:

        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;               // قبول الحزمة

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

    يمكن استخدام هذا مع أنفاق مختلفة مثل VXLan أو Geneve أو GRE أو IP in IP (IPIP).

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_set_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, u32 size, u64 flags)

الوصف
    ملء بيانات النفق الوصفية للحزمة المرتبطة بـ skb. تُضبط بيانات النفق الوصفية وفقًا لمحتويات key ذات الحجم size. يمكن ضبط الـ flags على مزيج من القيم التالية:

BPF_F_TUNINFO_IPV6
    يشير إلى أن النفق يعتمد على بروتوكول IPv6 بدلاً من IPv4.

BPF_F_ZERO_CSUM_TX
    لحزم IPv4، أضف علامة إلى بيانات النفق الوصفية تشير إلى وجوب تخطي حساب مجموع التحقق (checksum) وضبطه على أصفار.

BPF_F_DONT_FRAGMENT
    أضف علامة إلى بيانات النفق الوصفية تشير إلى أنه لا ينبغي تجزئة الحزمة.

BPF_F_SEQ_NUMBER
    أضف علامة إلى بيانات النفق الوصفية تشير إلى وجوب إضافة رقم تسلسلي إلى ترويسة النفق قبل إرسال الحزمة. أضيفت هذه العلامة لتغليف GRE، ولكن قد تُستخدم مع بروتوكولات أخرى في المستقبل.

BPF_F_NO_TUNNEL_KEY
    أضف علامة إلى بيانات النفق الوصفية تشير إلى أنه لا ينبغي تعيين مفتاح نفق في ترويسة النفق الناتجة.

    فيما يلي استخدام نموذجي في مسار الإرسال:

        struct bpf_tunnel_key key;
             ملء المفتاح ...
        bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0);
        bpf_clone_redirect(skb, vxlan_dev_ifindex, 0);

    انظر أيضًا وصف الدالة المساعدة bpf_skb_get_tunnel_key() لمزيد من المعلومات.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u64 bpf_perf_event_read(struct bpf_map *map, u64 flags)

الوصف
    قراءة قيمة عداد أحداث الأداء (perf event). تعتمد هذه الدالة المساعدة على خريطة map من نوع BPF_MAP_TYPE_PERF_EVENT_ARRAY. تُحدد طبيعة عداد أحداث الأداء عندما تُحدث map بواصفات ملفات أحداث الأداء. الـ map هي مصفوفة حجمها هو عدد المعالجات المتاحة، وكل خلية تحتوي على قيمة تتعلق بمعالج واحد. القيمة المطلوب جلبها يُشار إليها بواسطة flags، التي تحتوي على فهرس المعالج المطلوب البحث عنه، مقنعًا بـ BPF_F_INDEX_MASK. بدلاً من ذلك، يمكن ضبط flags على BPF_F_CURRENT_CPU للإشارة إلى وجوب جلب قيمة المعالج الحالي.

    لاحظ أنه قبل الإصدار 4.13 من لينكس، يمكن جلب أحداث الأداء العتادية فقط.

    كن على علم أيضًا أن الدالة المساعدة الأحدث bpf_perf_event_read_value() يُوصى بها عمومًا بدلاً من bpf_perf_event_read(). فالأخيرة بها بعض عيوب واجهة التطبيق الثنائية (ABI) حيث تُستخدم قيمة الخطأ والعداد كرمز إرجاع (وهو أمر خاطئ لأن النطاقات قد تتداخل). تم إصلاح هذه المشكلة في bpf_perf_event_read_value()، والتي توفر في الوقت نفسه ميزات أكثر من واجهة bpf_perf_event_read(). يرجى الرجوع إلى وصف bpf_perf_event_read_value() للحصول على التفاصيل.

القيمة المعادة
    قيمة عداد أحداث الأداء المقروءة من الخريطة، أو رمز خطأ سالب في حالة الفشل.

long bpf_redirect(u32 ifindex, u64 flags)

الوصف
    إعادة توجيه الحزمة إلى جهاز شبكة آخر بالفهرس ifindex. تشبه هذه الدالة المساعدة إلى حد ما bpf_clone_redirect()، باستثناء أنه لا يتم استنساخ الحزمة، مما يوفر أداءً أفضل.

    باستثناء XDP، يمكن استخدام واجهتي الدخول والخروج لإعادة التوجيه. تُستخدم قيمة BPF_F_INGRESS في flags للتمييز بينهما (يُختار مسار الدخول في حالة وجود العلامة، ومسار الخروج بخلاف ذلك). حاليًا، يدعم XDP فقط إعادة التوجيه إلى واجهة الخروج، ولا يقبل أي علامات على الإطلاق.

    يمكن أيضًا تحقيق نفس التأثير باستخدام bpf_redirect_map() الأكثر عمومية، والتي تستخدم خريطة BPF لتخزين هدف إعادة التوجيه بدلاً من تقديمه مباشرةً إلى الدالة المساعدة.

القيمة المعادة
    بالنسبة لـ XDP، تعيد الدالة المساعدة XDP_REDIRECT عند النجاح أو XDP_ABORTED عند الخطأ. بالنسبة لأنواع البرامج الأخرى، تكون القيم TC_ACT_REDIRECT عند النجاح أو TC_ACT_SHOT عند الخطأ.

u32 bpf_get_route_realm(struct sk_buff *skb)

الوصف
    جلب المجال (realm) أو المسار، أي حقل tclassid للوجهة لـ skb. المعرف الذي جُلب هو وسم يوفره المستخدم، يشبه ذاك المستخدم مع net_cls cgroup (انظر وصف الدالة المساعدة bpf_get_cgroup_classid())، ولكن هنا يحمل هذا الوسم مسار (إدخال وجهة)، وليس مهمة.

    يعمل جلب هذا المعرف مع خطاف خروج clsact TC (انظر أيضًا tc-bpf(8))، أو بدلاً من ذلك على qdiscs الخروج التقليدية المصنفة، ولكن ليس على مسار دخول TC. في حالة خطاف خروج clsact TC، فإن هذا له ميزة أنه، داخليًا، لم يتم إسقاط إدخال الوجهة بعد في مسار الإرسال. لذلك، لا يحتاج إدخال الوجهة إلى الإبقاء عليه اصطناعيًا عبر netif_keep_dst() لـ qdisc مصنف حتى يتم تحرير skb.

    هذه الدالة المساعدة متاحة فقط إذا جُمعت النواة مع خيار الإعداد CONFIG_IP_ROUTE_CLASSID.

القيمة المعادة
    مجال المسار للحزمة المرتبطة بـ skb، أو 0 إذا لم يُعثر على أي منها.

long bpf_perf_event_output(void *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

الوصف
    كتابة كتلة data خام في حدث أداء BPF خاص تحتفظ به map من نوع BPF_MAP_TYPE_PERF_EVENT_ARRAY. يجب أن يحتوي حدث الأداء هذا على السمات التالية: PERF_SAMPLE_RAW كـ sample_type، و PERF_TYPE_SOFTWARE كـ type، و PERF_COUNT_SW_BPF_OUTPUT كـ config.

    تُستخدم الـ flags للإشارة إلى الفهرس في map الذي يجب وضع القيمة فيه، مقنعًا بـ BPF_F_INDEX_MASK. بدلاً من ذلك، يمكن ضبط flags على BPF_F_CURRENT_CPU للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي.

    القيمة المراد كتابتها، ذات الحجم size، تُمرر عبر مكدس eBPF ويؤشر إليها بـ data.

    يجب أيضًا تمرير سياق البرنامج ctx إلى الدالة المساعدة.

    في فضاء المستخدم، يحتاج البرنامج الذي يرغب في قراءة القيم إلى استدعاء perf_event_open() على حدث الأداء (إما لمعالج واحد أو لجميع المعالجات) وتخزين واصف الملف في الـ map. يجب القيام بذلك قبل أن يتمكن برنامج eBPF من إرسال البيانات إليه. يتوفر مثال في الملف samples/bpf/trace_output_user.c في شجرة مصادر نواة لينكس (نظيره في برنامج eBPF موجود في samples/bpf/trace_output.bpf.c).

    تحقق bpf_perf_event_output() أداءً أفضل من bpf_trace_printk() لمشاركة البيانات مع فضاء المستخدم، وهي مناسبة أكثر بكثير لتدفق البيانات من برامج eBPF.

    لاحظ أن هذه الدالة المساعدة لا تقتصر على حالات استخدام التتبع ويمكن استخدامها مع البرامج المتصلة بـ TC أو XDP أيضًا، حيث تسمح بتمرير البيانات إلى مستمعي فضاء المستخدم. يمكن أن تكون البيانات:

•   هياكل (structs) مخصصة فقط،

•   حمولة الحزمة فقط، أو

•   مزيج من الاثنين.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_load_bytes(const void *skb, u32 offset, void *to, u32 len)

الوصف
    وُفرت هذه الدالة المساعدة كطريقة سهلة لتحميل البيانات من حزمة. يمكن استخدامها لتحميل len من البايتات من الإزاحة offset من الحزمة المرتبطة بـ skb، إلى المخزن المؤقت الذي يشير إليه to.

    منذ إصدار لينكس 4.7، استُبدل استخدام هذه الدالة المساعدة في الغالب بـ "الوصول المباشر للحزمة"، مما يتيح معالجة بيانات الحزمة باستخدام skb->data و skb->data_end اللذين يشيران على التوالي إلى أول بايت من بيانات الحزمة وإلى البايت الذي يلي آخر بايت من بيانات الحزمة. ومع ذلك، فإنها تظل مفيدة إذا رغب المرء في قراءة كميات كبيرة من البيانات مرة واحدة من حزمة إلى مكدس eBPF.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_get_stackid(void *ctx, struct bpf_map *map, u64 flags)

الوصف
    السير في مكدس مستخدم أو مكدس نواة وإعادة معرفه. لتحقيق ذلك، تحتاج الدالة المساعدة إلى ctx، وهو مؤشر إلى السياق الذي يتم تنفيذ برنامج التتبع عليه، ومؤشر إلى map من نوع BPF_MAP_TYPE_STACK_TRACE.

    الوسيط الأخير، flags، يحمل عدد إطارات المكدس التي يجب تخطيها (من 0 إلى 255)، مقنعًا بـ BPF_F_SKIP_FIELD_MASK. يمكن استخدام البتات التالية لضبط مزيج من العلامات التالية:

BPF_F_USER_STACK
    جمع مكدس فضاء المستخدم بدلاً من مكدس النواة.

BPF_F_FAST_STACK_CMP
    مقارنة المكدسات عن طريق التجزئة (hash) فقط.

BPF_F_REUSE_STACKID
    إذا تم تجزئة مكدسين مختلفين إلى نفس الـ stackid، فتخلص من القديم.

    معرف المكدس الذي جُلب هو مقبض عدد صحيح بطول 32 بت يمكن دمجه لاحقًا مع بيانات أخرى (بما في ذلك معرفات المكدس الأخرى) واستخدامه كمفتاح في الخرائط. يمكن أن يكون هذا مفيدًا لإنشاء مجموعة متنوعة من الرسوم البيانية (مثل الرسوم البيانية اللهبية flame graphs أو رسوم بيانية خارج المعالج off-cpu graphs).

    للسير في مكدس، تعد هذه الدالة المساعدة تحسينًا لـ bpf_probe_read()، التي يمكن استخدامها مع الحلقات المفرودة ولكنها ليست فعالة وتستهلك الكثير من تعليمات eBPF. بدلاً من ذلك، يمكن لـ bpf_get_stackid() جمع ما يصل إلى PERF_MAX_STACK_DEPTH من إطارات النواة والمستخدم على حد سواء. لاحظ أنه يمكن التحكم في هذا الحد باستخدام برنامج sysctl، وأنه ينبغي زيادته يدويًا من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج جافا). للقيام بذلك، استخدم:

        # sysctl kernel.perf_event_max_stack=<القيمة الجديدة>

القيمة المعادة
    معرف المكدس الموجب أو صفر عند النجاح، أو خطأ سالب في حالة الفشل.

s64 bpf_csum_diff(__be32 *from, u32 from_size, __be32 *to, u32 to_size, __wsum seed)

الوصف
    حساب فرق مجموع التحقق، من المخزن المؤقت الخام الذي يشير إليه from، وبطول from_size (الذي يجب أن يكون من مضاعفات 4)، باتجاه المخزن المؤقت الخام الذي يشير إليه to، وبحجم to_size (نفس الملاحظة). يمكن إضافة seed اختيارية إلى القيمة (يمكن تسلسل هذا، فقد تأتي البذرة من استدعاء سابق للدالة المساعدة).

    هذا مرن بما يكفي لاستخدامه بعدة طرق:

•   عندما تكون from_size == 0، و to_size > 0 وضبط seed على مجموع التحقق، يمكن استخدامها عند دفع بيانات جديدة.

•   عندما تكون from_size > 0، و to_size == 0 وضبط seed على مجموع التحقق، يمكن استخدامها عند إزالة بيانات من حزمة.

•   عندما تكون from_size > 0، و to_size > 0 وضبط seed على 0، يمكن استخدامها لحساب الفرق. لاحظ أن from_size و to_size لا يلزم أن يكونا متساويين.

    يمكن استخدام هذه الدالة المساعدة بالاشتراك مع bpf_l3_csum_replace() و bpf_l4_csum_replace()، حيث يمكن تزويدهما بالفرق المحسوب باستخدام bpf_csum_diff().

القيمة المعادة
    نتيجة مجموع التحقق، أو رمز خطأ سالب في حالة الفشل.

long bpf_skb_get_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

الوصف
    جلب بيانات خيارات النفق الوصفية للحزمة المرتبطة بـ skb، وتخزين بيانات خيارات النفق الخام في المخزن المؤقت opt ذي الحجم size.

    يمكن استخدام هذه الدالة المساعدة مع أجهزة التغليف التي يمكنها العمل في وضع "جمع البيانات الوصفية" (يرجى الرجوع إلى الملاحظة ذات الصلة في وصف bpf_skb_get_tunnel_key() لمزيد من التفاصيل). من الأمثلة المحددة حيث يمكن استخدام ذلك، بالاشتراك مع بروتوكول تغليف Geneve، حيث يسمح بدفع (باستخدام الدالة المساعدة bpf_skb_get_tunnel_opt()) وجلب TLVs (ترويسات النوع-الطول-القيمة) العشوائية من برنامج eBPF. يتيح ذلك التخصيص الكامل لهذه الترويسات.

القيمة المعادة
    حجم بيانات الخيار التي جُلبت.

long bpf_skb_set_tunnel_opt(struct sk_buff *skb, void *opt, u32 size)

الوصف
    ضبط بيانات خيارات النفق الوصفية للحزمة المرتبطة بـ skb لتكون بيانات الخيار الواردة في المخزن المؤقت الخام opt ذي الحجم size.

    انظر أيضًا وصف الدالة المساعدة bpf_skb_get_tunnel_opt() لمزيد من المعلومات.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_change_proto(struct sk_buff *skb, __be16 proto, u64 flags)

الوصف
    تغيير بروتوكول skb إلى proto. المدعوم حاليًا هو الانتقال من IPv4 إلى IPv6، ومن IPv6 إلى IPv4. تتولى الدالة المساعدة العمل الأساس للانتقال، بما في ذلك تغيير حجم مخزن المقبس المؤقت. يُتوقع من برنامج eBPF ملء الترويسات الجديدة، إن وجدت، عبر skb_store_bytes() وإعادة حساب مجموع التحقق باستخدام bpf_l3_csum_replace() و bpf_l4_csum_replace(). الحالة الرئيسة لهذه الدالة المساعدة هي تنفيذ عمليات NAT64 من برنامج eBPF.

    داخليًا، وُسم نوع GSO بأنه مريب (dodgy) بحيث تُفحص الترويسات وتُعاد حساب الأجزاء بواسطة محرك GSO/GRO. كما كُيف حجم هدف GSO أيضًا.

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_change_type(struct sk_buff *skb, u32 type)

الوصف
    تغيير نوع الحزمة للحزمة المرتبطة بـ skb. يتلخص هذا في ضبط skb->pkt_type على type، باستثناء أن برنامج eBPF ليس لديه وصول للكتابة إلى skb->pkt_type بخلاف هذه الدالة المساعدة. يسمح استخدام دالة مساعدة هنا بالتعامل السلس مع الأخطاء.

    حالة الاستخدام الرئيسة هي تغيير الـ skb*s القادمة إلى **PACKET_HOST* بطريقة برمجية بدلاً من الاضطرار إلى إعادة التدوير عبر redirect(..., BPF_F_INGRESS)، على سبيل المثال.

    لاحظ أن type يسمح بقيم معينة فقط. في الوقت الحالي، هي:

PACKET_HOST
    الحزمة مخصصة لنا.

PACKET_BROADCAST
    إرسال الحزمة للجميع.

PACKET_MULTICAST
    إرسال الحزمة لمجموعة.

PACKET_OTHERHOST
    إرسال الحزمة لشخص آخر.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_under_cgroup(struct sk_buff *skb, struct bpf_map *map, u32 index)

الوصف
    التحقق مما إذا كانت skb سليلًا لـ cgroup2 التي تحتفظ بها map من نوع BPF_MAP_TYPE_CGROUP_ARRAY، عند index.

القيمة المعادة
    تعتمد قيمة الإرجاع على نتيجة الاختبار، ويمكن أن تكون:

•   0، إذا فشل skb في اختبار سليل cgroup2.

•   1، إذا اجتاز skb اختبار سليل cgroup2.

•   رمز خطأ سالب، في حال حدوث خطأ.

u32 bpf_get_hash_recalc(struct sk_buff *skb)

الوصف
    استعد خبيئة الحزمة، skb->hash. إذا لم تكن مضبوطة، لا سيما إذا مُسحت الخبيئة بسبب التلاعب، فأعد حساب هذه الخبيئة. يمكن إجراء عمليات الوصول اللاحقة للخبيئة مباشرة عبر skb->hash.

    استدعاء ()bpf_set_hash_invalid، أو تغيير نموذج حزمة أولي باستخدام ()bpf_skb_change_proto، أو استدعاء ()bpf_skb_store_bytes مع BPF_F_INVALIDATE_HASH هي إجراءات عرضة لمسح الخبيئة ولتحفيز حساب جديد عند الاستدعاء التالي لـ ()bpf_get_hash_recalc.

القيمة المعادة
    الخبيئة ذات 32 بت.

u64 bpf_get_current_task(void)

الوصف
    احصل على المهمة الحالية.

القيمة المعادة
    مؤشر إلى بنية المهمة الحالية.

long bpf_probe_write_user(void *dst, const void *src, u32 len)

الوصف
    حاول بطريقة آمنة كتابة عدد len من البايتات من المخزن المؤقت src إلى dst في الذاكرة. يعمل هذا فقط مع الخيوط التي تكون في سياق المستخدم، ويجب أن يكون dst عنواناً صحيحاً في مساحة المستخدم.

    يجب ألا يُستخدم هذا المساعد لتنفيذ أي نوع من آليات الأمان بسبب هجمات TOC-TOU، بل يُستخدم بدلاً من ذلك لتنقيح وتحويل والتلاعب بتنفيذ العمليات شبه التعاونية.

    ضع في حسبانك أن هذه الميزة مخصصة للتجارب، وهي تنطوي على خطر إيقاف النظام والبرامج المشغلة. لذلك، عند وصل برنامج eBPF يستخدم هذا المساعد، يُطبع تحذير يتضمن معرف العملية (PID) واسم العملية في سجلات النواة.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_current_task_under_cgroup(struct bpf_map *map, u32 index)

الوصف
    تحقق مما إذا كان المسبار يُشغّل في سياق مجموعة فرعية معينة من هيكلية cgroup2. مجموعة cgroup2 المطلوب اختبارها محفوظة في map من نوع BPF_MAP_TYPE_CGROUP_ARRAY، عند الـ index.

القيمة المعادة
    تعتمد قيمة الإرجاع على نتيجة الاختبار، ويمكن أن تكون:

•   1، إذا كانت المهمة الحالية تنتمي إلى cgroup2.

•   0، إذا كانت المهمة الحالية لا تنتمي إلى cgroup2.

•   رمز خطأ سالب، في حال حدوث خطأ.

long bpf_skb_change_tail(struct sk_buff *skb, u32 len, u64 flags)

الوصف
    أعد ضبط حجم (تقليص أو تنمية) الحزمة المرتبطة بـ skb إلى الطول len الجديد. تُحجز الـ flags للاستخدام المستقبلي، ويجب تركها عند الصفر.

    الفكرة الأساسية هي أن المساعد يقوم بالعمل المطلوب لتغيير حجم الحزمة، ثم يعيد برنامج eBPF كتابة الباقي عبر مساعدين مثل ()bpf_skb_store_bytes و ()bpf_l3_csum_replace و ()bpf_l3_csum_replace وغيرها. هذا المساعد هو أداة للمسار البطيء مخصصة للردود برسائل التحكم. ولأنه يستهدف المسار البطيء، يمكن للمساعد نفسه أن يكون بطيئاً: فهو يقوم بـ خطيّة (linearize) وإلغاء الاستنساخ (unclone) وإسقاط التفريغات (offloads) من الـ skb بشكل ضمني.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_pull_data(struct sk_buff *skb, u32 len)

الوصف
    اسحب البيانات غير الخطية في حالة كون skb غير خطي ولم تكن كامل الـ len جزءاً من القسم الخطي. اجعل عدد len بايت من skb قابلة للقراءة والكتابة. إذا مُررت قيمة صفر لـ len، فستُجعل جميع البايتات في الجزء الخطي من skb قابلة للقراءة والكتابة.

    هذا المساعد مطلوب فقط للقراءة والكتابة مع الوصول المباشر للحزمة.

    بالنسبة للوصول المباشر للحزمة، فإن اختبار أن الإزاحات للوصول تقع ضمن حدود الحزمة (اختبار على skb->data_end) معرض للفشل إذا كانت الإزاحات غير صحيحة، أو إذا كانت البيانات المطلوبة في أجزاء غير خطية من الـ skb. عند الفشل يمكن للبرنامج الخروج ببساطة، أو في حالة وجود مخزن مؤقت غير خطي، استخدم مساعداً لإتاحة البيانات. المساعد ()bpf_skb_load_bytes هو حل أول للوصول إلى البيانات. والحل الآخر يتمثل في استخدام bpf_skb_pull_data لسحب الأجزاء غير الخطية مرة واحدة، ثم إعادة الاختبار والوصول إلى البيانات في النهاية.

    في الوقت نفسه، يضمن هذا أيضاً أن الـ skb غير مستنسخ، وهو شرط ضروري للكتابة المباشرة. وبما أن هذا يجب أن يكون ثابتاً لـ جزء الكتابة فقط، فإن الفاحص (verifier) يكتشف عمليات الكتابة ويضيف تمهيداً (prologue) يستدعي ()bpf_skb_pull_data لإلغاء استنساخ skb فعلياً من البداية في حال كان مستنسخاً بالفعل.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

s64 bpf_csum_update(struct sk_buff *skb, __wsum csum)

الوصف
    أضف مجموع التدقيق csum إلى skb->csum في حال قام التعريف بتزويد مجموع تدقيق لكامل الحزمة في ذلك الحقل. أعِد خطأً خلاف ذلك. هذا المساعد مخصص للاستخدام مع ()bpf_csum_diff، لا سيما عندما يلزم تحديث مجموع التدقيق بعد كتابة البيانات في الحزمة عبر الوصول المباشر للحزمة.

القيمة المعادة
    مجموع التدقيق عند النجاح، أو رمز خطأ سالب في حال الفشل.

void bpf_set_hash_invalid(struct sk_buff *skb)

الوصف
    أبطل قيمة skb->hash الحالية. يمكن استخدامها بعد التلاعب بالترويسات عبر الوصول المباشر للحزمة، للإشارة إلى أن الخبيئة قديمة ولتحفيز إعادة الحساب في المرة القادمة التي تحاول فيها النواة الوصول لهذه الخبيئة أو عند استدعاء مساعد ()bpf_get_hash_recalc.

القيمة المعادة
    void.

long bpf_get_numa_node_id(void)

الوصف
    أعِد معرف عقدة NUMA الحالية. حالة الاستخدام الرئيسة لهذا المساعد هي اختيار المقابس لعقدة NUMA المحلية، عندما يكون البرنامج موصولاً بالمقابس باستخدام خيار SO_ATTACH_REUSEPORT_EBPF (انظر أيضاً socket(7))، ولكن المساعد متاح أيضاً لأنواع برامج eBPF الأخرى، بشكل مشابه لـ ()bpf_get_smp_processor_id.

القيمة المعادة
    معرف عقدة NUMA الحالية.

long bpf_skb_change_head(struct sk_buff *skb, u32 len, u64 flags)

الوصف
    ينمي مقدمة (headroom) الحزمة المرتبطة بـ skb ويضبط إزاحة ترويسة MAC وفقاً لذلك، مضيفاً مساحة قدرها len بايت. يقوم آلياً بتوسيع وإعادة تخصيص الذاكرة حسب الحاجة.

    يمكن استخدام هذا المساعد على skb من الطبقة 3 لدفع ترويسة MAC لـ إعادة التوجيه إلى جهاز من الطبقة 2.

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_xdp_adjust_head(struct xdp_buff *xdp_md, int delta)

الوصف
    اضبط (انقل) xdp_md->data بمقدار delta بايت. لاحظ أنه من الممكن استخدام قيمة سالبة لـ delta. يمكن استخدام هذا المساعد لـ تحضير الحزمة لدفع الترويسات أو سحبها.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_probe_read_str(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    انسخ سلسلة نصية منتهية بـ NUL من عنوان نواة غير آمن unsafe_ptr إلى dst. انظر ()bpf_probe_read_kernel_str لمزيد من التفاصيل.

    بشكل عام، استخدم ()bpf_probe_read_user_str أو ()bpf_probe_read_kernel_str بدلاً من ذلك.

القيمة المعادة
    عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة.

u64 bpf_get_socket_cookie(struct sk_buff *skb)

الوصف
    إذا كان الـ struct sk_buff الذي يشير إليه skb له مقبس معروف، فاستعد الكعكة (التي ولدتها النواة) لهذا المقبس. إذا لم تُضبط أي كعكة بعد، فولّد كعكة جديدة. بمجرد توليدها، تظل كعكة المقبس ثابتة طوال حياة المقبس. يمكن أن يكون هذا المساعد مفيداً لمراقبة إحصائيات حركة مرور الشبكة لكل مقبس لأنه يوفر معرف مقبس عاماً يمكن افتراض فرادته.

القيمة المعادة
    رقم فريد بطول 8 بايت عند النجاح، أو 0 إذا كان حقل المقبس مفقوداً داخل skb.

u64 bpf_get_socket_cookie(struct bpf_sock_addr *ctx)

الوصف
    يكافئ مساعد ()bpf_get_socket_cookie الذي يقبل skb، ولكنه يحصل على المقبس من سياق struct bpf_sock_addr.

القيمة المعادة
    رقم فريد بطول 8 بايت.

u64 bpf_get_socket_cookie(struct bpf_sock_ops *ctx)

الوصف
    يكافئ مساعد ()bpf_get_socket_cookie الذي يقبل skb، ولكنه يحصل على المقبس من سياق struct bpf_sock_ops.

القيمة المعادة
    رقم فريد بطول 8 بايت.

u64 bpf_get_socket_cookie(struct sock *sk)

الوصف
    يكافئ مساعد ()bpf_get_socket_cookie الذي يقبل sk، ولكنه يحصل على المقبس من BTF struct sock. يعمل هذا المساعد أيضاً للبرامج القابلة للنوم.

القيمة المعادة
    رقم فريد بطول 8 بايت أو 0 إذا كان sk فارغاً (NULL).

u32 bpf_get_socket_uid(struct sk_buff *skb)

الوصف
    احصل على معرف المستخدم (UID) للمالك للمقبس المرتبط بـ skb.

القيمة المعادة
    معرف المستخدم (UID) للمالك للمقبس المرتبط بـ skb. إذا كان المقبس NULL، أو إذا لم يكن مقبساً كاملاً (أي إذا كان مقبس انتظار وقت أو مقبس طلب بدلاً من ذلك)، تُعاد قيمة overflowuid (لاحظ أن overflowuid قد تكون أيضاً قيمة UID الفعلية للمقبس).

long bpf_set_hash(struct sk_buff *skb, u32 hash)

الوصف
    اضبط الخبيئة الكاملة لـ skb (اضبط الحقل skb->hash) على القيمة hash.

القيمة المعادة
    0

long bpf_setsockopt(void *bpf_socket, int level, int optname, void *optval, int optlen)

الوصف
    حاكَ استدعاءً لـ ()setsockopt على المقبس المرتبط بـ bpf_socket، الذي يجب أن يكون مقبساً كاملاً. يجب تحديد المستوى (level) الذي يتواجد فيه الخيار واسم الخيار optname، انظر (2)setsockopt لمزيد من المعلومات. يشير optval إلى قيمة الخيار ذات الطول optlen.

    يجب أن يكون bpf_socket واحداً مما يلي:

•   struct bpf_sock_ops لـ BPF_PROG_TYPE_SOCK_OPS.

•   struct bpf_sock_addr لـ BPF_CGROUP_INET4_CONNECT و BPF_CGROUP_INET6_CONNECT و BPF_CGROUP_UNIX_CONNECT.

    ينفذ هذا المساعد فعلياً مجموعة فرعية من ()setsockopt. وهو يدعم المستويات (levels) التالية:

•   SOL_SOCKET، الذي يدعم الأسماء optname التالية: SO_RCVBUF و SO_SNDBUF و SO_MAX_PACING_RATE و SO_PRIORITY و SO_RCVLOWAT و SO_MARK و SO_BINDTODEVICE و SO_KEEPALIVE و SO_REUSEADDR و SO_REUSEPORT و SO_BINDTOIFINDEX و SO_TXREHASH.

•   IPPROTO_TCP، الذي يدعم الأسماء optname التالية: TCP_CONGESTION و TCP_BPF_IW و TCP_BPF_SNDCWND_CLAMP و TCP_SAVE_SYN و TCP_KEEPIDLE و TCP_KEEPINTVL و TCP_KEEPCNT و TCP_SYNCNT و TCP_USER_TIMEOUT و TCP_NOTSENT_LOWAT و TCP_NODELAY و TCP_MAXSEG و TCP_WINDOW_CLAMP و TCP_THIN_LINEAR_TIMEOUTS و TCP_BPF_DELACK_MAX و TCP_BPF_RTO_MIN و TCP_BPF_SOCK_OPS_CB_FLAGS.

•   IPPROTO_IP، الذي يدعم الاسم optname للقيمة IP_TOS.

•   IPPROTO_IPV6، الذي يدعم الأسماء optname التالية: IPV6_TCLASS و IPV6_AUTOFLOWLABEL.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_adjust_room(struct sk_buff *skb, s32 len_diff, u32 mode, u64 flags)

الوصف
    نمّ أو قلص مساحة البيانات في الحزمة المرتبطة بـ skb بمقدار len_diff، ووفقاً للوضع (mode) المحدد.

    مبدئياً، سيعيد المساعد ضبط أي مؤشر مجموع تدقيق مفرغ (offloaded) في skb إلى CHECKSUM_NONE. يمكن تجنب ذلك عبر العلامة التالية:

•   BPF_F_ADJ_ROOM_NO_CSUM_RESET: لا تعد ضبط بيانات مجموع التدقيق المفرغة لـ skb إلى CHECKSUM_NONE.

    هناك وضعان مدعومان في هذا الوقت:

•   BPF_ADJ_ROOM_MAC: اضبط المساحة في طبقة MAC (تُضاف مساحة أو تُزال بين ترويستي الطبقة 2 والطبقة 3).

•   BPF_ADJ_ROOM_NET: اضبط المساحة في طبقة الشبكة (تُضاف مساحة أو تُزال بين ترويستي الطبقة 3 والطبقة 4).

    العلامات التالية مدعومة في هذا الوقت:

•   BPF_F_ADJ_ROOM_FIXED_GSO: لا تضبط gso_size. ضبط mss بهذه الطريقة غير مسموح به لمخططات البيانات (datagrams).

•   BPF_F_ADJ_ROOM_ENCAP_L3_IPV4 و BPF_F_ADJ_ROOM_ENCAP_L3_IPV6: تُحجز أي مساحة جديدة لحفظ ترويسة نفق. اضبط إزاحات skb والحقول الأخرى وفقاً لذلك.

•   BPF_F_ADJ_ROOM_ENCAP_L4_GRE و BPF_F_ADJ_ROOM_ENCAP_L4_UDP: استُخدمت مع علامات ENCAP_L3 لتحديد نوع النفق بشكل أكبر.

•   BPF_F_ADJ_ROOM_ENCAP_L2(len): استُخدمت مع علامات ENCAP_L3/L4 لتحديد نوع النفق بشكل أكبر؛ len هي طول ترويسة MAC الداخلية.

•   BPF_F_ADJ_ROOM_ENCAP_L2_ETH: استُخدمت مع علامة BPF_F_ADJ_ROOM_ENCAP_L2 لـ تحديد نوع الطبقة 2 كـ إيثرنت.

•   BPF_F_ADJ_ROOM_DECAP_L3_IPV4 و BPF_F_ADJ_ROOM_DECAP_L3_IPV6: تشير إلى إصدار ترويسة IP الجديد بعد فك تغليف ترويسة IP الخارجية. تُستخدم عندما تكون إصدارات IP الداخلية والخارجية مختلفة.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_redirect_map(struct bpf_map *map, u64 key, u64 flags)

الوصف
    أعِد توجيه الحزمة إلى نقطة النهاية التي تشير إليها map عند الفهرس key. اعتماداً على نوعها، يمكن أن تحتوي هذه الـ map على مراجع لأجهزة الشبكة (لتوجيه الحزم عبر منافذ أخرى)، أو لوحدات المعالجة المركزية (لإعادة توجيه إطارات XDP إلى وحدة معالجة أخرى؛ ولكن هذا منفذ فقط لـ XDP الأصيل (بدعم من التعريف) حتى وقت كتابة هذا النص).

    تُستخدم البتات الدنيا لـ flags كرمز إعادة في حال فشل البحث في الخريطة. وذلك لكي تكون القيمة المعادة واحدة من رموز إعادة برنامج XDP حتى XDP_TX، كما يختارها المستدعي. يمكن ضبط البتات العليا لـ flags على BPF_F_BROADCAST أو BPF_F_EXCLUDE_INGRESS كما هو محدد أدناه.

    باستخدام BPF_F_BROADCAST، ستُبث الحزمة إلى جميع الواجهات في الخريطة، ومع BPF_F_EXCLUDE_INGRESS، ستُستثنى واجهة الدخول (ingress) عند القيام بالبث.

    انظر أيضاً ()bpf_redirect، الذي يدعم فقط إعادة التوجيه إلى ifindex، ولكنه لا يتطلب خريطة للقيام بذلك.

القيمة المعادة
    XDP_REDIRECT عند النجاح، أو قيمة البتات الدنيا لمعطى flags عند الخطأ.

long bpf_sk_redirect_map(struct sk_buff *skb, struct bpf_map *map, u32 key, u64 flags)

الوصف
    أعِد توجيه الحزمة إلى المقبس الذي تشير إليه map (من نوع BPF_MAP_TYPE_SOCKMAP) عند الفهرس key. يمكن استخدام واجهات الدخول (ingress) والخروج (egress) لإعادة التوجيه. تُستخدم القيمة BPF_F_INGRESS في flags للتمييز (يُختار مسار الدخول إذا كانت العلامة موجودة، ومسار الخروج خلاف ذلك). هذه هي العلامة الوحيدة المدعومة حالياً.

القيمة المعادة
    SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

long bpf_sock_map_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags)

الوصف
    أضف مدخلاً إلى خريطة map تشير إلى المقابس، أو حدثها. يُستخدم skops كقيمة جديدة للمدخل المرتبط بـ key. الـ flags هي واحدة مما يلي:

BPF_NOEXIST
    يجب ألا تكون المدخلة لـ key موجودة في الخريطة.

BPF_EXIST
    يجب أن تكون المدخلة لـ key موجودة بالفعل في الخريطة.

BPF_ANY
    لا يوجد شرط على وجود المدخلة لـ key.

    إذا كانت الخريطة map تحتوي على برامج eBPF (محلل وحكم)، فسوف يَرثها المقبس الذي أُضيف. إذا كان المقبس موصولاً بالفعل ببرامج eBPF، فسيؤدي ذلك إلى حدوث خطأ.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_xdp_adjust_meta(struct xdp_buff *xdp_md, int delta)

الوصف
    اضبط العنوان الذي يشير إليه xdp_md->data_meta بمقدار delta (التي يمكن أن تكون موجبة أو سالبة). لاحظ أن هذه العملية تعدل العنوان المخزن في xdp_md->data، لذا يجب تحميل الأخير فقط بعد استدعاء المساعد.

    يعد استخدام xdp_md->data_meta اختياريًا ولا يُشترط على البرامج استخدامه. والسبب المنطقي هو أنه عند معالجة الحزمة باستخدام XDP (على سبيل المثال كمُلح DoS)، يمكن دفع المزيد من البيانات الوصفية (meta data) معها قبل تمريرها إلى المكدس، ولإعطاء ضمان بأن برنامج eBPF وارد (ingress) متصل كمصنف TC على الجهاز نفسه يمكنه التقاط هذه البيانات لمزيد من المعالجة اللاحقة. وبما أن TC يعمل مع مخازن المقابس المؤقتة (socket buffers)، يظل من الممكن ضبط مؤشرات mark أو priority، أو مؤشرات أخرى لمخزن المقبس المؤقت من XDP. إن وجود مساحة العمل (scratch space) هذه بشكل عام وقابل للبرمجة يتيح مرونة أكبر حيث بإمكان المستخدم تخزين أي بيانات وصفية يحتاجها.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_perf_event_read_value(struct bpf_map *map, u64 flags, struct bpf_perf_event_value *buf, u32 buf_size)

الوصف
    يقرأ قيمة عداد أحداث الأداء (perf event counter)، ويخزنها في buf بحجم buf_size. يعتمد هذا المساعد على map من نوع BPF_MAP_TYPE_PERF_EVENT_ARRAY. تُحدد طبيعة عداد أحداث الأداء عند تحديث map بواصفات ملفات أحداث الأداء. الـ map هي مصفوفة حجمها هو عدد وحدات المعالجة المركزية (CPUs) المتاحة، وكل خلية تحتوي على قيمة تتعلق بوحدة معالجة مركزية واحدة. تُشار القيمة المراد جلبها بواسطة flags، التي تحتوي على فهرس وحدة المعالجة المركزية للبحث عنها، مغطاة بـ BPF_F_INDEX_MASK. وبدلاً من ذلك، يمكن ضبط flags على BPF_F_CURRENT_CPU للإشارة إلى وجوب جلب القيمة الخاصة بوحدة المعالجة المركزية الحالية.

    يسلك هذا المساعد سلوكًا قريبًا من المساعد bpf_perf_event_read()، باستثناء أنه بدلاً من مجرد إرجاع القيمة الملحوظة، فإنه يملأ بنية buf. وهذا يسمح بجلب بيانات إضافية: لا سيما أوقات التمكين والتشغيل (في buf->enabled و buf->running، على التوالي) حيث تُنسخ. وبشكل عام، يُوصى باستخدام bpf_perf_event_read_value() بدلاً من bpf_perf_event_read()، الذي يعاني من بعض مشكلات ABI ويوفر وظائف أقل.

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

        normalized_counter = counter * t_enabled / t_running

    حيث t_enabled هو وقت التمكين للحدث و t_running هو وقت التشغيل للحدث منذ آخر تطبيع. تُراكم أوقات التمكين والتشغيل منذ فتح حدث الأداء. ولتحقيق عامل قياس بين استدعاءين لبرنامج eBPF، يمكن للمستخدمين استخدام معرف وحدة المعالجة المركزية (CPU id) كمفتاح (وهو أمر نموذجي لنموذج استخدام مصفوفة perf) لتذكر القيمة السابقة وإجراء الحساب داخل برنامج eBPF.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_perf_prog_read_value(struct bpf_perf_event_data *ctx, struct bpf_perf_event_value *buf, u32 buf_size)

الوصف
    لبرنامج eBPF متصل بحدث أداء، يجلب قيمة عداد الحدث المرتبط بـ ctx ويخزنها في البنية التي يشير إليها buf وبحجم buf_size. تُخزن أوقات التمكين والتشغيل أيضًا في البنية (انظر وصف المساعد bpf_perf_event_read_value() لمزيد من التفاصيل).

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_getsockopt(void *bpf_socket, int level, int optname, void *optval, int optlen)

الوصف
    يحاكي استدعاء getsockopt() على المقبس المرتبط بـ bpf_socket، والذي يجب أن يكون مقبساً كاملاً. يجب تحديد المستوى (level) الذي يوجد فيه الخيار واسم الخيار optname، انظر getsockopt(2) لمزيد من المعلومات. تُخزن القيمة المجلوبة في البنية التي يشير إليها opval وبطول optlen.

    يجب أن يكون bpf_socket واحداً مما يلي:

•   struct bpf_sock_ops لـ BPF_PROG_TYPE_SOCK_OPS.

•   struct bpf_sock_addr لـ BPF_CGROUP_INET4_CONNECT و BPF_CGROUP_INET6_CONNECT و BPF_CGROUP_UNIX_CONNECT.

    ينفذ هذا المساعد في الواقع مجموعة فرعية من getsockopt(). وهو يدعم نفس مجموعة optname المدعومة من قبل المساعد bpf_setsockopt(). الاستثناءات هي TCP_BPF_* للمساعد bpf_setsockopt() فقط و TCP_SAVED_SYN للمساعد bpf_getsockopt() فقط.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_override_return(struct pt_regs *regs, u64 rc)

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

    يعمل هذا المساعد عن طريق ضبط PC (عداد البرنامج) على دالة تجاوز تُشغل بدلاً من الدالة الأصلية المفحوصة. وهذا يعني أن الدالة المفحوصة لا تُشغل على الإطلاق. تعود الدالة البديلة فقط بالقيمة المطلوبة.

    لهذا المساعد تداعيات أمنية، وبالتالي يخضع لقيود. وهو متاح فقط إذا كانت الـ نواة قد جُمعت مع خيار الضبط CONFIG_BPF_KPROBE_OVERRIDE، وفي هذه الحالة لا يعمل إلا على الدوال الموسومة بـ ALLOW_ERROR_INJECTION في كود النواة.

القيمة المعادة
    0

long bpf_sock_ops_cb_flags_set(struct bpf_sock_ops *bpf_sock, int argval)

الوصف
    يحاول ضبط قيمة حقل bpf_sock_ops_cb_flags لمقبس TCP الكامل المرتبط بـ bpf_sock_ops إلى argval.

    الاستخدام الرئيس لهذا الحقل هو تحديد ما إذا كان ينبغي إجراء استدعاءات لبرامج eBPF من نوع BPF_PROG_TYPE_SOCK_OPS في نقاط مختلفة في كود TCP. يمكن لبرنامج من نفس النوع تغيير قيمته، لكل اتصال وحسب الضرورة، عند إنشاء الاتصال. يمكن الوصول إلى هذا الحقل مباشرة للقراءة، ولكن يجب استخدام هذا المساعد للتحديثات من أجل إرجاع خطأ إذا حاول برنامج eBPF ضبط رد نداء (callback) غير مدعوم في النواة الحالية.

    argval هي مصفوفة أعلام يمكنها دمج هذه الأعلام:

•   BPF_SOCK_OPS_RTO_CB_FLAG (مهلة إعادة الإرسال)

•   BPF_SOCK_OPS_RETRANS_CB_FLAG (إعادة الإرسال)

•   BPF_SOCK_OPS_STATE_CB_FLAG (تغيير حالة TCP)

•   BPF_SOCK_OPS_RTT_CB_FLAG (كل RTT)

    لذلك، يمكن استخدام هذه الدالة لمسح علم رد نداء عن طريق ضبط البت المناسب على الصفر. على سبيل المثال لتعطيل رد نداء RTO:

bpf_sock_ops_cb_flags_set(bpf_sock,
    bpf_sock->bpf_sock_ops_cb_flags & ~BPF_SOCK_OPS_RTO_CB_FLAG)

    فيما يلي بعض الأمثلة على المواضع التي يمكن فيها استدعاء مثل هذا البرنامج eBPF:

•   عند انطلاق RTO.

•   عند إعادة إرسال حزمة.

•   عند انتهاء الاتصال.

•   عند إرسال حزمة.

•   عند استلام حزمة.

القيمة المعادة
    الكود -EINVAL إذا لم يكن المقبس مقبس TCP كاملاً؛ وبخلاف ذلك، يُرجع رقم موجب يحتوي على البتات التي تعذر ضبطها (وهو ما يؤول إلى 0 إذا ضُبطت جميع البتات كما هو مطلوب).

long bpf_msg_redirect_map(struct sk_msg_buff *msg, struct bpf_map *map, u32 key, u64 flags)

الوصف
    يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى المقبس. إذا سُمح للرسالة msg بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة SK_PASS)، فسيُعاد توجيهها إلى المقبس المشار إليه بواسطة map (من نوع BPF_MAP_TYPE_SOCKMAP) عند الفهرس key. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة BPF_F_INGRESS في flags للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، ومسار الصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً.

القيمة المعادة
    SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

long bpf_msg_apply_bytes(struct sk_msg_buff *msg, u32 bytes)

الوصف
    لسياسات المقبس، يطبق حكم برنامج eBPF على الـ bytes (عدد البايتات) التالية من الرسالة msg.

    على سبيل المثال، يمكن استخدام هذا المساعد في الحالات التالية:

•   استدعاء نظام واحد sendmsg() أو sendfile() يحتوي على عدة رسائل منطقية من المفترض أن يقرأها برنامج eBPF ويصدر حكماً بشأنها.

•   برنامج eBPF يهتم فقط بقراءة الـ bytes الأولى من msg. إذا كانت للرسالة حمولة كبيرة، فإن إعداد واستدعاء برنامج eBPF بشكل متكرر لجميع البايتات، رغم أن الحكم معروف بالفعل، سيؤدي إلى عبء غير ضروري.

    عند استدعائه من داخل برنامج eBPF، يقوم المساعد بضبط عداد داخلي في بنية BPF التحتية، يُستخدم لتطبيق الحكم الأخير على الـ bytes التالية. إذا كان bytes أصغر من البيانات الحالية التي تُعالج من استدعاء نظام sendmsg() أو sendfile()، فسيُرسل الـ bytes الأول وسيُعاد تشغيل برنامج eBPF مع مؤشر بداية البيانات الذي يشير إلى البايت رقم bytes + 1. إذا كان bytes أكبر من البيانات الحالية التي تُعالج، فسيُطبق حكم eBPF على عدة استدعاءات sendmsg() أو sendfile() حتى تُستهلك bytes.

    لاحظ أنه إذا أُغلق المقبس والعداد الداخلي يحمل قيمة غير صفرية، فهذه ليست مشكلة لأن البيانات لا تُخزن مؤقتاً لـ bytes وتُرسل فور استلامها.

القيمة المعادة
    0

long bpf_msg_cork_bytes(struct sk_msg_buff *msg, u32 bytes)

الوصف
    لسياسات المقبس، يمنع تنفيذ برنامج حكم eBPF للرسالة msg حتى يُجمع bytes (عدد بايتات).

    يمكن استخدام هذا عندما يحتاج المرء إلى عدد معين من البايتات قبل أن يتمكن من تعيين حكم، حتى لو امتدت البيانات عبر عدة استدعاءات sendmsg() أو sendfile(). الحالة القصوى هي قيام مستخدم باستدعاء sendmsg() بشكل متكرر بقطع رسائل بطول 1 بايت. من الواضح أن هذا سيء للأداء، ولكنه لا يزال صالحاً. إذا كان برنامج eBPF يحتاج bytes بايت للتحقق من ترويسة، يمكن استخدام هذا المساعد لمنع استدعاء برنامج eBPF مرة أخرى حتى يُجمع bytes بايت.

القيمة المعادة
    0

long bpf_msg_pull_data(struct sk_msg_buff *msg, u32 start, u32 end, u64 flags)

الوصف
    لسياسات المقبس، يسحب البيانات غير الخطية من مساحة المستخدم لـ msg ويضبط المؤشرات msg->data و msg->data_end على إزاحات البايت start و end في msg، على التوالي.

    إذا أُشغل برنامج من نوع BPF_PROG_TYPE_SK_MSG على msg، فيمكنه فقط تحليل البيانات التي استهلكتها مؤشرات (data, data_end) بالفعل. بالنسبة لخطافات sendmsg()، فمن المرجح أن يكون هذا هو عنصر قائمة التشتت (scatterlist) الأول. ولكن بالنسبة للاستدعاءات التي تعتمد على معالج sendpage (مثل sendfile())، سيكون هذا النطاق هو (0, 0) لأن البيانات مشتركة مع مساحة المستخدم والهدف افتراضياً هو تجنب السماح لمساحة المستخدم بتعديل البيانات أثناء (أو بعد) اتخاذ حكم eBPF. يمكن استخدام هذا المساعد لسحب البيانات وضبط مؤشر البداية والنهاية على قيم معطاة. ستُنسخ البيانات إذا لزم الأمر (أي إذا لم تكن البيانات خطية وإذا لم يشر مؤشرا البداية والنهاية إلى نفس القطعة).

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

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_bind(struct bpf_sock_addr *ctx, struct sockaddr *addr, int addr_len)

الوصف
    يربط المقبس المرتبط بـ ctx بالعنوان الذي يشير إليه addr، بطول addr_len. يسمح هذا بإجراء اتصال صادر من عنوان IP المنشود، والذي يمكن أن يكون مفيداً على سبيل المثال عندما ينبغي لجميع العمليات داخل cgroup استخدام عنوان IP واحد على مضيف تم ضبط عناوين IP متعددة عليه.

    يعمل هذا المساعد لمقابس IPv4 و IPv6 و TCP و UDP. يجب أن يكون النطاق (addr->sa_family) هو AF_INET (أو AF_INET6). ويُنصح بتمرير منفذ صفري (sin_port أو sin6_port) مما يحفز سلوكاً مشابهاً لـ IP_BIND_ADDRESS_NO_PORT ويسمح للنواة باختيار منفذ غير مستخدم بكفاءة طالما أن الرباعية (4-tuple) فريدة. قد يؤدي تمرير منفذ غير صفري إلى تدهور الأداء.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_xdp_adjust_tail(struct xdp_buff *xdp_md, int delta)

الوصف
    يضبط (يحرك) xdp_md->data_end بمقدار delta بايت. ومن الممكن تقليص وتوسيع ذيل الحزمة. يُجرى التقليص عبر كون delta عدداً صحيحاً سالباً.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_skb_get_xfrm_state(struct sk_buff *skb, u32 index, struct bpf_xfrm_state *xfrm_state, u32 size, u64 flags)

الوصف
    يجلب حالة XFRM (إطار عمل تحويل IP، انظر أيضاً ip-xfrm(8)) عند index في "المسار الأمني" لـ XFRM لـ skb.

    تُخزن القيمة المجلوبة في struct bpf_xfrm_state الذي يشير إليه xfrm_state وبطول size.

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

    هذا المساعد متاح فقط إذا كانت الـ نواة قد جُمعت مع خيار الضبط CONFIG_XFRM.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_get_stack(void *ctx, void *buf, u32 size, u64 flags)

الوصف
    يرجع مكدساً للمستخدم أو للنواة في مخزن مؤقت يوفره برنامج bpf. ولتحقيق ذلك، يحتاج المساعد إلى ctx، وهو مؤشر للسياق الذي يُنفذ فيه برنامج التتبع. ولتخزين تتبع المكدس (stacktrace)، يوفر برنامج bpf buf مع size غير سالب.

    الوسيط الأخير، flags، يحمل عدد أطر المكدس المراد تخطيها (من 0 إلى 255)، مغطاة بـ BPF_F_SKIP_FIELD_MASK. ويمكن استخدام البتات التالية لضبط الأعلام التالية:

BPF_F_USER_STACK
    جمع مكدس فضاء المستخدم بدلاً من مكدس النواة.

BPF_F_USER_BUILD_ID
    يجمع (build_id، file_offset) بدلاً من عناوين ips لمكدس المستخدم، ولا يصلح إلا إذا حُدد BPF_F_USER_STACK أيضاً.

    file_offset هي إزاحة بالنسبة لبداية الملف القابل للتنفيذ أو الكائن المشترك الذي يدعم vma الذي يقع فيه ip. وهي ليست إزاحة بالنسبة لعنوان الأساس لهذا الكائن. وبناءً عليه، يجب تعديلها بإضافة (sh_addr - sh_offset)، حيث يمثل sh_{addr,offset} قسم الملف القابل للتنفيذ الذي يحتوي على file_offset في الكائن، لكي تكون المقارنات مع st_value للرموز صالحة.

    يمكن لـ bpf_get_stack() جمع ما يصل إلى PERF_MAX_STACK_DEPTH من كل من أطر الـ نواة والمستخدم، بشرط توفر حجم مخزن مؤقت كبير بما يكفي. لاحظ أن هذا الحد يمكن التحكم فيه باستخدام برنامج sysctl، وأنه ينبغي زيادته يدوياً من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج Java). وللقيام بذلك، استخدم:

        # sysctl kernel.perf_event_max_stack=<القيمة الجديدة>

القيمة المعادة
    طول buf المنسوخ غير السالب المساوي لـ size أو أقل منه عند النجاح، أو خطأ سالب في حالة الفشل.

long bpf_skb_load_bytes_relative(const void *skb, u32 offset, void *to, u32 len, u32 start_header)

الوصف
    هذا المساعد مشابه لـ bpf_skb_load_bytes() في أنه يوفر طريقة سهلة لتحميل len بايت من offset من الحزمة المرتبطة بـ skb، إلى المخزن المؤقت الذي يشير إليه to. والفرق عن bpf_skb_load_bytes() هو وجود وسيط خامس start_header من أجل اختيار إزاحة أساسية للبدء منها. يمكن لـ start_header أن يكون أحد:

BPF_HDR_START_MAC
    الإزاحة الأساسية لتحميل البيانات منها هي ترويسة mac لـ skb.

BPF_HDR_START_NET
    الإزاحة الأساسية لتحميل البيانات منها هي ترويسة الشبكة لـ skb.

    بشكل عام، تعد "الوصول المباشر للحزمة" (direct packet access) هي الطريقة المفضلة للوصول إلى بيانات الحزمة، ومع ذلك، فإن هذا المساعد مفيد بشكل خاص في مرشحات المقابس حيث لا يشير skb->data دائماً إلى بداية ترويسة mac وحيث لا يتوفر "الوصول المباشر للحزمة".

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_fib_lookup(void *ctx, struct bpf_fib_lookup *params, int plen, u32 flags)

الوصف
    يقوم بالبحث في FIB (قاعدة معلومات التوجيه) في جداول الـ نواة باستخدام المعاملات في params. إذا نجح البحث وأظهرت النتيجة وجوب توجيه الحزمة، فسيتم البحث في جداول الجوار (neighbor tables) عن القفزة التالية (nexthop). إذا نجح ذلك (أي أظهر بحث FIB التوجيه وحُلّت القفزة التالية)، يُرجع عنوان القفزة التالية في ipv4_dst أو ipv6_dst بناءً على العائلة، ويُضبط smac على عنوان mac لجهاز الصدور، ويُضبط dmac على عنوان mac للقفزة التالية، ويُضبط rt_metric على القياس (metric) من المسار (IPv4/IPv6 فقط)، ويُضبط ifindex على فهرس جهاز القفزة التالية من بحث FIB.

    الوسيط plen هو حجم البنية الممررة. والوسيط flags يمكن أن يكون مزيجاً من واحد أو أكثر من القيم التالية:

BPF_FIB_LOOKUP_DIRECT
    يقوم ببحث مباشر في الجدول مقابل البحث الكامل باستخدام قواعد FIB.

BPF_FIB_LOOKUP_TBID
    يُستخدم مع BPF_FIB_LOOKUP_DIRECT. يستخدم معرف جدول التوجيه الموجود في params->tbid لبحث fib.

BPF_FIB_LOOKUP_OUTPUT
    ينفذ البحث من منظور الصدور (egress) (المبدئي هو الورود ingress).

BPF_FIB_LOOKUP_SKIP_NEIGH
    يتخطى بحث جدول الجوار. لن يُضبط params->dmac و params->smac كمخرجات. حالة الاستخدام الشائعة هي استدعاء bpf_redirect_neigh() بعد إجراء bpf_fib_lookup().

BPF_FIB_LOOKUP_SRC
    يشتق ويضبط عنوان IP المصدر في params->ipv{4,6}_src للقفزة التالية. إذا تعذر اشتقاق عنوان المصدر، يُرجع BPF_FIB_LKUP_RET_NO_SRC_ADDR. في هذه الحالة، لن يُضبط params->dmac و params->smac أيضاً.

BPF_FIB_LOOKUP_MARK
    يستخدم العلامة (mark) الموجودة في params->mark لبحث fib. لا ينبغي استخدام هذا الخيار مع BPF_FIB_LOOKUP_DIRECT، لأنه ليس له معنى إلا في عمليات البحث الكاملة.

    ctx هو إما struct xdp_md لبرامج XDP أو برامج struct sk_buff tc cls_act.

القيمة المعادة

•   < 0 إذا كان أي وسيط إدخال غير صالح

•   0 عند النجاح (تُوجه الحزمة، وجار القفزة التالية موجود)

•   > 0 واحد من أكواد BPF_FIB_LKUP_RET_ التي توضح سبب عدم توجيه الحزمة أو حاجتها للمساعدة من المكدس الكامل

    إذا فشل البحث مع BPF_FIB_LKUP_RET_FRAG_NEEDED، فهذا يعني أنه تم تجاوز MTU ويحتوي الناتج params->mtu_result على MTU.

long bpf_sock_hash_update(struct bpf_sock_ops *skops, struct bpf_map *map, void *key, u64 flags)

الوصف
    يضيف إدخالاً إلى، أو يحدث مخرطة مقابس (sockhash) map تشير إلى مقابس. يُستخدم skops كقيمة جديدة للإدخال المرتبط بـ key. flags هي واحدة من:

BPF_NOEXIST
    يجب ألا تكون المدخلة لـ key موجودة في الخريطة.

BPF_EXIST
    يجب أن تكون المدخلة لـ key موجودة بالفعل في الخريطة.

BPF_ANY
    لا يوجد شرط على وجود المدخلة لـ key.

    إذا كانت الخريطة map تحتوي على برامج eBPF (محلل وحكم)، فسوف يَرثها المقبس الذي أُضيف. إذا كان المقبس موصولاً بالفعل ببرامج eBPF، فسيؤدي ذلك إلى حدوث خطأ.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_msg_redirect_hash(struct sk_msg_buff *msg, struct bpf_map *map, void *key, u64 flags)

الوصف
    يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى المقبس. إذا سُمح للرسالة msg بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة SK_PASS)، فسيُعاد توجيهها إلى المقبس المشار إليه بواسطة map (من نوع BPF_MAP_TYPE_SOCKHASH) باستخدام مفتاح المخرطة key. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة BPF_F_INGRESS في flags للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، ومسار الصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً.

القيمة المعادة
    SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

long bpf_sk_redirect_hash(struct sk_buff *skb, struct bpf_map *map, void *key, u64 flags)

الوصف
    يُستخدم هذا المساعد في البرامج التي تنفذ سياسات على مستوى مقبس skb. إذا سُمح لـ sk_buff skb بالمرور (أي إذا أرجع برنامج حكم eBPF القيمة SK_PASS)، فسيُعاد توجيهه إلى المقبس المشار إليه بواسطة map (من نوع BPF_MAP_TYPE_SOCKHASH) باستخدام مفتاح المخرطة key. يمكن استخدام كل من واجهات الورود (ingress) والصدور (egress) لإعادة التوجيه. وتُستخدم قيمة BPF_F_INGRESS في flags للتمييز (يُختار مسار الورود إذا كان العلم موجوداً، والصدور بخلاف ذلك). هذا هو العلم الوحيد المدعوم حالياً.

القيمة المعادة
    SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

long bpf_lwt_push_encap(struct sk_buff *skb, u32 type, void *hdr, u32 len)

الوصف
    تغليف الحزمة المرتبطة بـ skb داخل ترويسة بروتوكول من الطبقة الثالثة. تُوفّر هذه الترويسة في المخزن المؤقت عند العنوان hdr، ويكون حجمها len بالبايت. يشير type إلى بروتوكول الترويسة ويمكن أن يكون أحد القيم التالية:

BPF_LWT_ENCAP_SEG6
    تغليف IPv6 مع ترويسة توجيه المقاطع (struct ipv6_sr_hdr). تحتوي hdr على SRH فقط، وتُحسب ترويسة IPv6 بواسطة النواة.

BPF_LWT_ENCAP_SEG6_INLINE
    يعمل فقط إذا احتوت skb على حزمة IPv6. يُدرج ترويسة توجيه المقاطع (struct ipv6_sr_hdr) داخل ترويسة IPv6.

BPF_LWT_ENCAP_IP
    تغليف IP ‏(GRE/GUE/IPIP/إلخ). يجب أن تكون الترويسة الخارجية IPv4 أو IPv6، متبوعة بصفر أو أكثر من الترويسات الإضافية، بما يصل إلى LWT_BPF_MAX_HEADROOM بايت إجمالاً في جميع الترويسات الملحقة. يرجى ملاحظة أنه إذا كانت skb_is_gso(skb) صحيحة، فلا يمكن إلحاق أكثر من ترويستين، ويجب أن تكون الترويسة الداخلية، إن وجدت، إما GRE أو UDP/GUE.

    يمكن استدعاء أنواع *BPF_LWT_ENCAP_SEG6 بواسطة برامج BPF من النوع BPF_PROG_TYPE_LWT_IN؛ ويمكن استدعاء النوع BPF_LWT_ENCAP_IP بواسطة برامج bpf من الأنواع BPF_PROG_TYPE_LWT_IN و BPF_PROG_TYPE_LWT_XMIT.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_lwt_seg6_store_bytes(struct sk_buff *skb, u32 offset, const void *from, u32 len)

الوصف
    يخزن len بايت من العنوان from في الحزمة المرتبطة بـ skb، عند الإزاحة offset. يمكن تعديل الأعلام والوسم و TLVs فقط داخل ترويسة توجيه المقاطع IPv6 الخارجية القصوى من خلال هذا المساعد.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_lwt_seg6_adjust_srh(struct sk_buff *skb, u32 offset, s32 delta)

الوصف
    ضبط الحجم المخصص لـ TLVs في ترويسة IPv6 Segment Routing الخارجية الموجودة في الحزمة المرتبطة بـ skb، عند الموضع offset بمقدار delta بايت. لا تُقبل إلا الإزاحات التي تلي الأجزاء (segments). يمكن أن تكون delta موجبة (للتوسيع) أو سالبة (للتقليص).

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_lwt_seg6_action(struct sk_buff *skb, u32 action, void *param, u32 param_len)

الوصف
    يطبق إجراء توجيه مقاطع IPv6 من النوع action على الحزمة المرتبطة بـ skb. يأخذ كل إجراء معطىً محتوًى في العنوان param، وبطول param_len بايت. يمكن أن يكون action أحد:

SEG6_LOCAL_ACTION_END_X
    إجراء End.X: نقطة نهاية مع اتصال عرضي من الطبقة الثالثة. نوع param: struct in6_addr.

SEG6_LOCAL_ACTION_END_T
    إجراء End.T: نقطة نهاية مع بحث في جدول IPv6 محدد. نوع param: int.

SEG6_LOCAL_ACTION_END_B6
    إجراء End.B6: نقطة نهاية مقيدة بسياسة SRv6. نوع param: struct ipv6_sr_hdr.

SEG6_LOCAL_ACTION_END_B6_ENCAP
    إجراء End.B6.Encap: نقطة نهاية مقيدة بسياسة تغليف SRv6. نوع param: struct ipv6_sr_hdr.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_rc_repeat(void *ctx)

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

    تحتوي بعض بروتوكولات الأشعة تحت الحمراء مثل NEC على رسالة IR خاصة لتكرار الزر الأخير، وذلك عند الاستمرار في الضغط على الزر.

    يجب أن تشير ctx إلى عينة lirc كما مررت إلى البرنامج.

    هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين CONFIG_BPF_LIRC_MODE2 على "y".

القيمة المعادة
    0

long bpf_rc_keydown(void *ctx, u32 protocol, u64 scancode, u32 toggle)

الوصف
    يُستخدم هذا المساعد في البرامج التي تنفذ فك ترميز الأشعة تحت الحمراء، للإبلاغ عن ضغطة مفتاح فُك ترميزها بنجاح مع scancode وقيمة toggle في البروتوكول protocol المعطى. سيُترجم كود المسح (scancode) إلى كود مفتاح باستخدام خريطة مفاتيح rc، ويُبلغ عنه كحدث ضغط مفتاح إدخال. بعد فترة، يُولد حدث رفع مفتاح. يمكن تمديد هذه الفترة باستدعاء إما bpf_rc_keydown() مجدداً بنفس القيم، أو استدعاء bpf_rc_repeat().

    تتضمن بعض البروتوكولات بت تبديل (toggle bit)، في حال حُرر الزر وضُغط عليه مجدداً بين أكواد مسح متتالية.

    يجب أن تشير ctx إلى عينة lirc كما مررت إلى البرنامج.

    protocol هو رقم البروتوكول الذي فُك ترميزه (انظر enum rc_proto للاطلاع على بعض القيم المحددة مسبقاً).

    هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين CONFIG_BPF_LIRC_MODE2 على "y".

القيمة المعادة
    0

u64 bpf_skb_cgroup_id(struct sk_buff *skb)

الوصف
    يرجع معرف cgroup v2 للمقبس المرتبط بـ skb. هذا مشابه تقريباً للمساعد bpf_get_cgroup_classid() لـ cgroup v1 من خلال توفير وسم أو معرف يمكن مطابقته أو استخدامه في عمليات البحث في الخريطة مثلاً لتنفيذ سياسة. يُكشف معرف cgroup v2 لمسار معين في التسلسل الهرمي في مساحة المستخدم من خلال واجهة برمجة تطبيقات f_handle من أجل الوصول إلى نفس المعرف المكون من 64 بت.

    يمكن استخدام هذا المساعد في مسار خروج TC، ولكن ليس في مسار الدخول، وهو متاح فقط إذا وُزعت النواة مع خيار التكوين CONFIG_SOCK_CGROUP_DATA.

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

u64 bpf_get_current_cgroup_id(void)

الوصف
    يجلب معرف cgroup الحالي بناءً على الـ cgroup التي تعمل المهمة الحالية ضمنها.

القيمة المعادة
    عدد صحيح بطول 64 بت يحتوي على معرف cgroup الحالي بناءً على الـ cgroup التي تعمل المهمة الحالية ضمنها.

void *bpf_get_local_storage(void *map, u64 flags)

الوصف
    يجلب المؤشر إلى منطقة التخزين المحلية. يُحدد نوع وحجم التخزين المحلي بواسطة المعطى map. معنى flags محدد لكل نوع خريطة، ويجب أن يكون 0 للتخزين المحلي لـ cgroup.

    بناءً على نوع برنامج BPF، يمكن مشاركة منطقة تخزين محلية بين نسخ متعددة من برنامج BPF تعمل في آن واحد.

    يجب على المستخدم الاهتمام بالمزامنة بنفسه. على سبيل المثال، باستخدام تعليمات BPF_ATOMIC لتغيير البيانات المشتركة.

القيمة المعادة
    مؤشر إلى منطقة التخزين المحلية.

long bpf_sk_select_reuseport(struct sk_reuseport_md *reuse, struct bpf_map *map, void *key, u64 flags)

الوصف
    يختار مقبس SO_REUSEPORT من خريطة map من النوع BPF_MAP_TYPE_REUSEPORT_SOCKARRAY. ويتحقق من أن المقبس المختار يطابق الطلب الوارد في مخزن المقبس المؤقت.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u64 bpf_skb_ancestor_cgroup_id(struct sk_buff *skb, int ancestor_level)

الوصف
    يرجع معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبطة بـ skb عند المستوى ancestor_level. تكون cgroup الجذر عند ancestor_level صفر وكل خطوة لأسفل في التسلسل الهرمي تزيد المستوى. إذا كان ancestor_level == مستوى cgroup المرتبطة بـ skb، فستكون القيمة المرجعة هي نفسها قيمة bpf_skb_cgroup_id().

    المساعد مفيد لتنفيذ سياسات بناءً على مجموعات cgroup التي تقع في مرتبة أعلى في التسلسل الهرمي من مجموعة cgroup المباشرة المرتبطة بـ skb.

    تنسيق المعرف المرجع وقيود المساعد هي نفسها كما في bpf_skb_cgroup_id().

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

struct bpf_sock *bpf_sk_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)

الوصف
    يبحث عن مقبس TCP يطابق tuple، اختيارياً في مساحة أسماء شبكة فرعية netns. يجب فحص القيمة المرجعة، وإذا لم تكن NULL، تُحرر عبر bpf_sk_release().

    يجب أن تشير ctx إلى سياق البرنامج، مثل skb أو المقبس (حسب الخطاف المستخدم). يُستخدم هذا لتحديد مساحة أسماء الشبكة الأساسية للبحث.

    يجب أن تكون tuple_size واحدة من:

sizeof(tuple->ipv4)
    البحث عن مقبس IPv4.

sizeof(tuple->ipv6)
    البحث عن مقبس IPv6.

    إذا كانت netns عدداً صحيحاً سالباً بطول 32 بت، فسيُستخدم جدول بحث المقبس في مساحة أسماء الشبكة المرتبطة بـ ctx. بالنسبة لخطافات TC، هذه هي مساحة أسماء الشبكة للجهاز في skb. بالنسبة لخطافات المقبس، هذه هي مساحة أسماء الشبكة للمقبس. إذا كانت netns أي قيمة أخرى موقعة بطول 32 بت أكبر من أو تساوي الصفر، فإنها تحدد معرف مساحة أسماء الشبكة بالنسبة إلى مساحة أسماء الشبكة المرتبطة بـ ctx. قيم netns خارج نطاق الأعداد الصحيحة 32 بت محجوزة للاستخدام المستقبلي.

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

    هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين CONFIG_NET.

القيمة المعادة
    مؤشر إلى struct bpf_sock، أو NULL في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة struct bpf_sock من reuse->socks[] باستخدام تجزئة المجموعة.

struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)

الوصف
    يبحث عن مقبس UDP يطابق tuple، اختيارياً في مساحة أسماء شبكة فرعية netns. يجب فحص القيمة المرجعة، وإذا لم تكن NULL، تُحرر عبر bpf_sk_release().

    يجب أن تشير ctx إلى سياق البرنامج، مثل skb أو المقبس (حسب الخطاف المستخدم). يُستخدم هذا لتحديد مساحة أسماء الشبكة الأساسية للبحث.

    يجب أن تكون tuple_size واحدة من:

sizeof(tuple->ipv4)
    البحث عن مقبس IPv4.

sizeof(tuple->ipv6)
    البحث عن مقبس IPv6.

    إذا كانت netns عدداً صحيحاً سالباً بطول 32 بت، فسيُستخدم جدول بحث المقبس في مساحة أسماء الشبكة المرتبطة بـ ctx. بالنسبة لخطافات TC، هذه هي مساحة أسماء الشبكة للجهاز في skb. بالنسبة لخطافات المقبس، هذه هي مساحة أسماء الشبكة للمقبس. إذا كانت netns أي قيمة أخرى موقعة بطول 32 بت أكبر من أو تساوي الصفر، فإنها تحدد معرف مساحة أسماء الشبكة بالنسبة إلى مساحة أسماء الشبكة المرتبطة بـ ctx. قيم netns خارج نطاق الأعداد الصحيحة 32 بت محجوزة للاستخدام المستقبلي.

    جميع قيم flags محجوزة للاستخدام في المستقبل، ويجب تركها عند الصفر.

    هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين CONFIG_NET.

القيمة المعادة
    مؤشر إلى struct bpf_sock، أو NULL في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة struct bpf_sock من reuse->socks[] باستخدام تجزئة المجموعة.

long bpf_sk_release(void *sock)

الوصف
    يحرر المرجع الذي يحمله sock. يجب أن يكون sock مؤشراً غير NULL أُرجع من bpf_sk_lookup_xxx().

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags)

الوصف
    يدفع عنصراً value في الخريطة map. الـ flags هي واحدة من:

BPF_EXIST
    إذا كان الطابور/المكدس ممتلئاً، يُزال أقدم عنصر لإفساح مجال لهذا العنصر.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_map_pop_elem(struct bpf_map *map, void *value)

الوصف
    يسحب عنصراً من الخريطة map.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_map_peek_elem(struct bpf_map *map, void *value)

الوصف
    يجلب عنصراً من الخريطة map دون إزالته.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_msg_push_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

الوصف
    لسياسات المقابس، يدرج len بايت في msg عند الإزاحة start.

    إذا شُغِّل برنامج من النوع BPF_PROG_TYPE_SK_MSG على msg، فقد يرغب في إدراج بيانات وصفية أو خيارات في msg. يمكن قراءة ذلك واستخدامه لاحقاً بواسطة أي من خطافات BPF في الطبقة الأدنى.

    قد يفشل هذا المساعد إذا كان هناك ضغط على الذاكرة (فشل malloc) وفي هذه الحالات ستتلقى برامج BPF خطأً مناسباً وسيتعين على برامج BPF معالجته.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_msg_pop_data(struct sk_msg_buff *msg, u32 start, u32 len, u64 flags)

الوصف
    سيزيل len بايت من msg بدءاً من البايت start. قد يؤدي هذا إلى أخطاء ENOMEM في حالات معينة إذا لزم التخصيص والنسخ بسبب امتلاء المخزن المؤقت الدائري. ومع ذلك، سيحاول المساعد تجنب إجراء التخصيص إن أمكن. يمكن أن تحدث أخطاء أخرى إذا كانت معلمات الإدخال غير صالحة إما لأن البايت start ليس جزءاً صالحاً من حمولة msg و/أو كانت قيمة pop كبيرة جداً.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_rc_pointer_rel(void *ctx, s32 rel_x, s32 rel_y)

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

    يجب أن تشير ctx إلى عينة lirc كما مررت إلى البرنامج.

    هذا المساعد متاح فقط إذا وُزعت النواة مع تعيين خيار التكوين CONFIG_BPF_LIRC_MODE2 على "y".

القيمة المعادة
    0

long bpf_spin_lock(struct bpf_spin_lock *lock)

الوصف
    يستحوذ على قفل دوار (spinlock) يمثله المؤشر lock، والذي يُخزن كجزء من قيمة خريطة. يسمح أخذ القفل بتحديث بقية الحقول في تلك القيمة بأمان. يمكن (ويجب) تحرير القفل الدوار لاحقاً باستدعاء bpf_spin_unlock(lock).

    تأتي الأقفال الدوارة في برامج BPF مع عدد من القيود والضوابط:

•   كائنات bpf_spin_lock مسموح بها فقط داخل خرائط من الأنواع BPF_MAP_TYPE_HASH و BPF_MAP_TYPE_ARRAY (يمكن توسيع هذه القائمة في المستقبل).

•   وصف BTF للخريطة إلزامي.

•   يمكن لبرنامج BPF أخذ قفل واحد فقط في المرة الواحدة، حيث إن أخذ قفلين أو أكثر قد يسبب أقفالاً مميتة (dead locks).

•   يُسمح بـ struct bpf_spin_lock واحد فقط لكل عنصر خريطة.

•   عند أخذ القفل، لا يُسمح بالاستدعاءات (سواء من BPF إلى BPF أو المساعدين).

•   تعليمات BPF_LD_ABS و BPF_LD_IND غير مسموح بها داخل منطقة مقفلة بقفل دوار.

•   يجب على برنامج BPF استدعاء bpf_spin_unlock() لتحرير القفل، في جميع مسارات التنفيذ، قبل أن يعود.

•   يمكن لبرنامج BPF الوصول إلى struct bpf_spin_lock فقط عبر المساعدين bpf_spin_lock() و bpf_spin_unlock(). تحميل أو تخزين بيانات في حقل struct bpf_spin_lock lock; للخريطة غير مسموح به.

•   لاستخدام المساعد bpf_spin_lock()، يجب أن يكون وصف BTF لقيمة الخريطة هيكلاً (struct) ويحتوي على حقل struct bpf_spin_lock anyname; عند المستوى الأعلى. القفل المتداخل داخل هيكل آخر غير مسموح به.

•   يجب أن يكون حقل struct bpf_spin_lock lock في قيمة الخريطة محاذياً لمضاعفات 4 بايت في تلك القيمة.

•   استدعاء النظام مع الأمر BPF_MAP_LOOKUP_ELEM لا ينسخ حقل bpf_spin_lock إلى مساحة المستخدم.

•   استدعاء النظام مع الأمر BPF_MAP_UPDATE_ELEM، أو التحديث من برنامج BPF، لا يحدّث حقل bpf_spin_lock.

•   لا يمكن أن يكون bpf_spin_lock على المكدس أو داخل حزمة شبكة (يمكن أن يكون فقط داخل قيم الخريطة).

•   bpf_spin_lock متاح للجذر (root) فقط.

•   لا يمكن لبرامج التتبع وبرامج تصفية المقابس استخدام bpf_spin_lock() بسبب عدم كفاية فحوصات الشفعة (Preemption) (ولكن قد يتغير هذا في المستقبل).

•   bpf_spin_lock غير مسموح به في الخرائط الداخلية لـ map-in-map.

القيمة المعادة
    0

long bpf_spin_unlock(struct bpf_spin_lock *lock)

الوصف
    يحرر الـ lock الذي أُقفل سابقاً باستدعاء bpf_spin_lock(lock).

القيمة المعادة
    0

struct bpf_sock *bpf_sk_fullsock(struct bpf_sock *sk)

الوصف
    يجلب هذا المساعد مؤشراً لـ struct bpf_sock بحيث يمكن الوصول إلى جميع الحقول في bpf_sock هذه.

القيمة المعادة
    مؤشر struct bpf_sock عند النجاح، أو NULL في حالة الفشل.

struct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *sk)

الوصف
    يجلب هذا المساعد مؤشراً لـ struct bpf_tcp_sock من مؤشر struct bpf_sock.

القيمة المعادة
    مؤشر struct bpf_tcp_sock عند النجاح، أو NULL في حالة الفشل.

long bpf_skb_ecn_set_ce(struct sk_buff *skb)

الوصف
    يضبط حقل ECN (إشعار الازدحام الصريح) لترويسة IP على CE (مواجهة ازدحام) إذا كانت القيمة الحالية ECT (نقل قادر على ECN). وإلا، لا يفعل شيئاً. يعمل مع IPv6 و IPv4.

القيمة المعادة
    1 إذا ضُبط علم CE (سواء من خلال استدعاء المساعد الحالي أو لأنه كان موجوداً بالفعل)، و 0 إذا لم يُضبط.

struct bpf_sock *bpf_get_listener_sock(struct bpf_sock *sk)

الوصف
    إرجاع مؤشر struct bpf_sock في حالة TCP_LISTEN. لا حاجة لاستدعاء bpf_sk_release() وهو غير مسموح به.

القيمة المعادة
    مؤشر struct bpf_sock عند النجاح، أو NULL في حالة الفشل.

struct bpf_sock *bpf_skc_lookup_tcp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)

الوصف
    يبحث عن مقبس TCP يطابق tuple، اختيارياً في مساحة أسماء شبكة فرعية netns. يجب فحص القيمة المرجعة، وإذا لم تكن NULL، تُحرر عبر bpf_sk_release().

    هذه الدالة مطابقة لـ bpf_sk_lookup_tcp()، باستثناء أنها ترجع أيضًا مقابس الانتظار الزمني (timewait) أو الطلب (request). استخدم bpf_sk_fullsock() أو bpf_tcp_sock() للوصول إلى الهيكل الكامل.

    هذا المساعد متاح فقط إذا وُزعت النواة مع خيار التكوين CONFIG_NET.

القيمة المعادة
    مؤشر إلى struct bpf_sock، أو NULL في حالة الفشل. بالنسبة للمقابس التي تحتوي على خيار reuseport، تكون نتيجة struct bpf_sock من reuse->socks[] باستخدام تجزئة المجموعة.

long bpf_tcp_check_syncookie(void *sk, void *iph, u32 iph_len, struct tcphdr *th, u32 th_len)

الوصف
    التحقق مما إذا كان iph و th يحتويان على SYN cookie ACK صالح للمقبس المستمع في sk.

    يشير iph إلى بداية ترويسة IPv4 أو IPv6، بينما يحتوي iph_len على sizeof(struct iphdr) أو sizeof(struct ipv6hdr).

    يشير th إلى بداية ترويسة TCP، بينما يحتوي th_len على طول ترويسة TCP (على الأقل sizeof(struct tcphdr)).

القيمة المعادة
    0 إذا كان iph و th يمثلان SYN cookie ACK صالحًا، أو قيمة خطأ سالبة خلاف ذلك.

long bpf_sysctl_get_name(struct bpf_sysctl *ctx, char *buf, size_t buf_len, u64 flags)

الوصف
    الحصول على اسم sysctl في /proc/sys/ ونسخه إلى المخزن المؤقت buf المقدم من البرنامج وبحجم buf_len.

    يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا.

    إذا كانت flags صفرًا، يُنسخ الاسم الكامل (مثل "net/ipv4/tcp_mem"). استخدم الوسم BPF_F_SYSCTL_BASE_NAME لنسخ الاسم الأساسي فقط (مثل "tcp_mem").

القيمة المعادة
    عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي).

    -E2BIG إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي buf في هذه الحالة على اسم مبتور).

long bpf_sysctl_get_current_value(struct bpf_sysctl *ctx, char *buf, size_t buf_len)

الوصف
    الحصول على القيمة الحالية لـ sysctl كما تظهر في /proc/sys (بما في ذلك السطر الجديد، إلخ)، ونسخها كسلسلة نصية إلى المخزن المؤقت buf المقدم من البرنامج وبحجم buf_len.

    تُنسخ القيمة بالكامل، بغض النظر عن موضع الملف الذي أصدر عنده فضاء المستخدم sys_read مثلاً.

    يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا.

القيمة المعادة
    عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي).

    -E2BIG إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي buf في هذه الحالة على اسم مبتور).

    -EINVAL إذا كانت القيمة الحالية غير متاحة، مثلاً لأن sysctl غير مهيأ والقراءة ترجع -EIO له.

long bpf_sysctl_get_new_value(struct bpf_sysctl *ctx, char *buf, size_t buf_len)

الوصف
    الحصول على القيمة الجديدة التي يكتبها فضاء المستخدم إلى sysctl (قبل حدوث الكتابة الفعلية) ونسخها كسلسلة نصية إلى المخزن المؤقت buf المقدم من البرنامج وبحجم buf_len.

    قد يكتب فضاء المستخدم قيمة جديدة عند موضع ملف أكبر من 0.

    يكون المخزن المؤقت دائمًا منتهيًا بـ NUL، ما لم يكن حجمه صفرًا.

القيمة المعادة
    عدد الأحرف المنسوخة (لا يشمل ذلك حرف NUL الختامي).

    -E2BIG إذا لم يكن المخزن المؤقت كبيرًا بما يكفي (سيحتوي buf في هذه الحالة على اسم مبتور).

    -EINVAL إذا كان يجري قراءة sysctl.

long bpf_sysctl_set_new_value(struct bpf_sysctl *ctx, const char *buf, size_t buf_len)

الوصف
    تجاوز القيمة الجديدة التي يكتبها فضاء المستخدم إلى sysctl بالقيمة المقدمة من البرنامج في المخزن المؤقت buf وبحجم buf_len.

    يجب أن يحتوي buf على سلسلة نصية بنفس الصيغة التي يقدمها فضاء المستخدم عند الكتابة إلى sysctl.

    قد يكتب فضاء المستخدم قيمة جديدة عند موضع ملف أكبر من 0. لتجاوز كامل قيمة sysctl، يجب ضبط موضع الملف على الصفر.

القيمة المعادة
    0 عند النجاح.

    -E2BIG إذا كان buf_len كبيرًا جدًا.

    -EINVAL إذا كان يجري قراءة sysctl.

long bpf_strtol(const char *buf, size_t buf_len, u64 flags, long *res)

الوصف
    تحويل الجزء الأولي من السلسلة النصية من المخزن المؤقت buf ذو الحجم buf_len إلى عدد صحيح طويل وفقًا للأساس المعطى وحفظ النتيجة في res.

    قد تبدأ السلسلة النصية بمقدار تعسفي من المسافات البيضاء (كما تحددها isspace(3)) تليها علامة '-' اختيارية واحدة.

    تُرمّز البتات الخمسة الأقل أهمية في flags الأساس، والبتات الأخرى غير مستخدمة حاليًا.

    يجب أن يكون الأساس إما 8 أو 10 أو 16 أو 0 لاكتشافه آليًا بصورة مماثلة لـ strtol(3) في فضاء المستخدم.

القيمة المعادة
    عدد الأحرف المستهلكة عند النجاح. يجب أن يكون موجبًا ولا يتجاوز buf_len.

    -EINVAL إذا لم يُعثر على أرقام صالحة أو إذا قُدّم أساس غير مدعوم.

    -ERANGE إذا كانت القيمة الناتجة خارج النطاق.

long bpf_strtoul(const char *buf, size_t buf_len, u64 flags, unsigned long *res)

الوصف
    تحويل الجزء الأولي من السلسلة النصية من المخزن المؤقت buf ذو الحجم buf_len إلى عدد صحيح طويل غير موقع وفقًا للأساس المعطى وحفظ النتيجة في res.

    قد تبدأ السلسلة النصية بمقدار تعسفي من المسافات البيضاء (كما تحددها isspace(3)).

    تُرمّز البتات الخمسة الأقل أهمية في flags الأساس، والبتات الأخرى غير مستخدمة حاليًا.

    يجب أن يكون الأساس إما 8 أو 10 أو 16 أو 0 لاكتشافه آليًا بصورة مماثلة لـ strtoul(3) في فضاء المستخدم.

القيمة المعادة
    عدد الأحرف المستهلكة عند النجاح. يجب أن يكون موجبًا ولا يتجاوز buf_len.

    -EINVAL إذا لم يُعثر على أرقام صالحة أو إذا قُدّم أساس غير مدعوم.

    -ERANGE إذا كانت القيمة الناتجة خارج النطاق.

void *bpf_sk_storage_get(struct bpf_map *map, void *sk, void *value, u64 flags)

الوصف
    الحصول على bpf-local-storage من sk.

    من الناحية المنطقية، يمكن اعتبار ذلك كأنه الحصول على قيمة من الخريطة map مع استخدام sk كـ key. ومن هذا المنظور، لا يختلف الاستخدام كثيرًا عن bpf_map_lookup_elem(map, &sk) باستثناء أن هذا المساعد يفرض أن يكون المفتاح مقبسًا كاملاً (full socket) وأن تكون الخريطة من نوع BPF_MAP_TYPE_SK_STORAGE أيضًا.

    داخليًا، تُخزّن القيمة محليًا عند sk بدلاً من الخريطة map. تُستخدم الخريطة map كـ "نوع" للتخزين المحلي bpf. يتم البحث عن "نوع" التخزين المحلي (أي الخريطة) بين جميع مخازن bpf المحلية الموجودة عند sk.

    يكون sk مؤشر struct sock للنواة في برامج LSM. ويكون sk مؤشر struct bpf_sock لأنواع البرامج الأخرى.

    يمكن استخدام وسم اختياري flags (BPF_SK_STORAGE_GET_F_CREATE) بحيث يُنشأ تخزين محلي bpf جديد إذا لم يكن موجودًا. يمكن استخدام value مع BPF_SK_STORAGE_GET_F_CREATE لتحديد القيمة الأولية للتخزين المحلي. إذا كان value هو NULL، فسيُهيأ التخزين المحلي الجديد بالصفر.

القيمة المعادة
    يُرجع مؤشر للتخزين المحلي bpf عند النجاح.

    NULL إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة تخزين محلي bpf جديد.

long bpf_sk_storage_delete(struct bpf_map *map, void *sk)

الوصف
    حذف تخزين محلي bpf من sk.

القيمة المعادة
    0 عند النجاح.

    -ENOENT إذا تعذر العثور على التخزين المحلي bpf. -EINVAL إذا لم يكن sk مقبسًا كاملاً (على سبيل المثال request_sock).

long bpf_send_signal(u32 sig)

الوصف
    إرسال الإشارة sig إلى عملية المهمة الحالية. قد تُسلم الإشارة إلى أي من خيوط (threads) هذه العملية.

القيمة المعادة
    0 عند النجاح أو وضعه في الطابور بنجاح.

    -EBUSY إذا كان طابور العمل تحت nmi ممتلئًا.

    -EINVAL إذا كانت الإشارة sig غير صالحة.

    -EPERM إذا لم تكن هناك صلاحية لإرسال الإشارة sig.

    -EAGAIN إذا كان بإمكان برنامج bpf المحاولة مرة أخرى.

s64 bpf_tcp_gen_syncookie(void *sk, void *iph, u32 iph_len, struct tcphdr *th, u32 th_len)

الوصف
    محاولة إصدار SYN cookie للحزمة مع ترويسات IP/TCP المقابلة، iph و th، على المقبس المستمع في sk.

    يشير iph إلى بداية ترويسة IPv4 أو IPv6، بينما يحتوي iph_len على sizeof(struct iphdr) أو sizeof(struct ipv6hdr).

    يشير th إلى بداية ترويسة TCP، بينما يحتوي th_len على طول ترويسة TCP مع الخيارات (على الأقل sizeof(struct tcphdr)).

القيمة المعادة
    عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EINVAL لا يمكن إصدار SYN cookie بسبب خطأ

    -ENOENT لا ينبغي إصدار SYN cookie (لا يوجد SYN flood)

    -EOPNOTSUPP تهيئة النواة لا تُفعّل SYN cookies

    -EPROTONOSUPPORT إصدار حزمة IP ليس 4 أو 6

long bpf_skb_output(void *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

الوصف
    كتابة كتلة data خام في حدث أداء BPF خاص تحتفظ به map من نوع BPF_MAP_TYPE_PERF_EVENT_ARRAY. يجب أن يحتوي حدث الأداء هذا على السمات التالية: PERF_SAMPLE_RAW كـ sample_type، و PERF_TYPE_SOFTWARE كـ type، و PERF_COUNT_SW_BPF_OUTPUT كـ config.

    تُستخدم الـ flags للإشارة إلى الفهرس في map الذي يجب وضع القيمة فيه، مقنعًا بـ BPF_F_INDEX_MASK. بدلاً من ذلك، يمكن ضبط flags على BPF_F_CURRENT_CPU للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي.

    القيمة المراد كتابتها، ذات الحجم size، تُمرر عبر مكدس eBPF ويؤشر إليها بـ data.

    تمثل ctx مؤشرًا إلى struct sk_buff داخل النواة.

    هذا المساعد مشابه لـ bpf_perf_event_output() ولكنه مقتصر على برامج bpf من نوع raw_tracepoint.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_probe_read_user(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    محاولة قراءة size بايت بأمان من عنوان فضاء المستخدم unsafe_ptr وتخزين البيانات في dst.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_probe_read_kernel(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    محاولة قراءة size بايت بأمان من عنوان فضاء النواة unsafe_ptr وتخزين البيانات في dst.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_probe_read_user_str(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    نسخ سلسلة نصية منتهية بـ NUL من عنوان مستخدم غير آمن unsafe_ptr إلى dst. يجب أن يتضمن size بايت NUL الختامي. في حال كان طول السلسلة أصغر من size، لا يُملأ الهدف بمزيد من بايتات NUL. إذا كان طول السلسلة أكبر من size، فسيُنسخ size-1 بايت فقط ويُضبط البايت الأخير على NUL.

    عند النجاح، تُرجع عدد البايتات المكتوبة، بما في ذلك حرف NUL الختامي. وهذا يجعل هذا المساعد مفيدًا في برامج التتبع لقراءة السلاسل النصية، والأهم من ذلك للحصول على طولها في وقت التشغيل. انظر القصاصة التالية:

        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 (طول السلسلة) كحجم للحدث،
                // بعد التحقق من حدوده.
        }

    بالمقارنة، فإن استخدام المساعد bpf_probe_read_user() هنا بدلاً من ذلك لقراءة السلسلة سيتطلب تقدير الطول في وقت التصريف، وغالبًا ما سيؤدي ذلك إلى نسخ ذاكرة أكثر من اللازم.

    حالة استخدام مفيدة أخرى هي عند تحليل وسائط العملية الفردية أو متغيرات البيئة الفردية بالتنقل عبر current->mm->arg_start و current->mm->env_start: باستخدام هذا المساعد والقيمة المرجعة، يمكن للمرء التنقل بسرعة عند الإزاحة الصحيحة لمنطقة الذاكرة.

القيمة المعادة
    عند النجاح، يُرجع الطول الموجب تمامًا لسلسلة الخرج، بما في ذلك حرف NUL الختامي. وعند الخطأ، يُرجع قيمة سالبة.

long bpf_probe_read_kernel_str(void *dst, u32 size, const void *unsafe_ptr)

الوصف
    نسخ سلسلة نصية منتهية بـ NUL من عنوان نواة غير آمن unsafe_ptr إلى dst. تنطبق نفس دلالات bpf_probe_read_user_str().

القيمة المعادة
    عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة.

long bpf_tcp_send_ack(void *tp, u32 rcv_nxt)

الوصف
    إرسال tcp-ack. يمثل tp هيكل tcp_sock داخل النواة. ويمثل rcv_nxt الـ ack_seq المراد إرساله.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_send_signal_thread(u32 sig)

الوصف
    إرسال الإشارة sig إلى الخيط (thread) المقابل للمهمة الحالية.

القيمة المعادة
    0 عند النجاح أو وضعه في الطابور بنجاح.

    -EBUSY إذا كان طابور العمل تحت nmi ممتلئًا.

    -EINVAL إذا كانت الإشارة sig غير صالحة.

    -EPERM إذا لم تكن هناك صلاحية لإرسال الإشارة sig.

    -EAGAIN إذا كان بإمكان برنامج bpf المحاولة مرة أخرى.

u64 bpf_jiffies64(void)

الوصف
    الحصول على jiffies بـ 64 بت

القيمة المعادة
    الـ jiffies بـ 64 بت

long bpf_read_branch_records(struct bpf_perf_event_data *ctx, void *buf, u32 size, u64 flags)

الوصف
    بالنسبة لبرنامج eBPF الملحق بحدث perf، استعد سجلات الفروع (struct perf_branch_entry) المرتبطة بـ ctx وخزّنها في المخزن المؤقت الذي يشير إليه buf بحجم يصل إلى size بايت.

القيمة المعادة
    عند النجاح، عدد البايتات المكتوبة في buf. عند الخطأ، قيمة سالبة.

    يمكن ضبط flags على BPF_F_GET_BRANCH_RECORDS_SIZE ليعيد بدلاً من ذلك عدد البايتات المطلوبة لتخزين كافة مدخلات الفروع. إذا ضُبط هذا الوسم، فقد يكون buf فارغاً (NULL).

    -EINVAL إذا كانت المعطيات غير صالحة أو إذا لم يكن size من مضاعفات sizeof(struct perf_branch_entry).

    -ENOENT إذا كانت المعمارية لا تدعم سجلات الفروع.

long bpf_get_ns_current_pid_tgid(u64 dev, u64 ino, struct bpf_pidns_info *nsdata, u32 size)

الوصف
    يُرجع 0 عند النجاح، وقيم pid و tgid كما تُرى من namespace الحالي ستُرجع في nsdata.

القيمة المعادة
    0 عند النجاح، أو أحد ما يلي في حالة الفشل:

    -EINVAL إذا كانت dev و inum الموفرة لا تطابق dev_t ورقم inode مع nsfs للمهمة الحالية، أو إذا فقد تحويل dev إلى dev_t البتات العالية.

    -ENOENT إذا كان pidns غير موجود للمهمة الحالية.

long bpf_xdp_output(void *ctx, struct bpf_map *map, u64 flags, void *data, u64 size)

الوصف
    كتابة كتلة data خام في حدث أداء BPF خاص تحتفظ به map من نوع BPF_MAP_TYPE_PERF_EVENT_ARRAY. يجب أن يحتوي حدث الأداء هذا على السمات التالية: PERF_SAMPLE_RAW كـ sample_type، و PERF_TYPE_SOFTWARE كـ type، و PERF_COUNT_SW_BPF_OUTPUT كـ config.

    تُستخدم الـ flags للإشارة إلى الفهرس في map الذي يجب وضع القيمة فيه، مقنعًا بـ BPF_F_INDEX_MASK. بدلاً من ذلك، يمكن ضبط flags على BPF_F_CURRENT_CPU للإشارة إلى وجوب استخدام فهرس نواة المعالج الحالي.

    القيمة المراد كتابتها، ذات الحجم size، تُمرر عبر مكدس eBPF ويؤشر إليها بـ data.

    ctx هو مؤشر إلى struct xdp_buff داخل النواة.

    هذا المساعد مشابه لـ bpf_perf_eventoutput() ولكنه مقصور على برامج raw_tracepoint bpf.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u64 bpf_get_netns_cookie(void *ctx)

الوصف
    استعد الكعكة (التي ولدتها النواة) لنطاق أسماء الشبكة الذي يرتبط به المُدخل ctx. تظل كعكة نطاق أسماء الشبكة مستقرة طوال عمرها وتوفر معرفاً عاماً يمكن افتراض فرادته. إذا كان ctx فارغاً (NULL)، فيعيد المساعد الكعكة لنطاق أسماء الشبكة الأولي. الكعكة نفسها مشابهة جداً لكعكة المساعد bpf_get_socket_cookie()، ولكن لنطاقات أسماء الشبكة بدلاً من المقابس.

القيمة المعادة
    رقم مبهم بطول 8 بايت.

u64 bpf_get_current_ancestor_cgroup_id(int ancestor_level)

الوصف
    أعد معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبط بالمهمة الحالية عند ancestor_level. يقع cgroup الجذر عند ancestor_level صفر، وتزيد كل خطوة لأسفل في التسلسل الهرمي من المستوى. إذا كان ancestor_level يساوي مستوى cgroup المرتبط بالمهمة الحالية، فستكون القيمة المعادة هي نفسها قيمة bpf_get_current_cgroup_id().

    هذا المساعد مفيد لتنفيذ سياسات تعتمد على cgroups التي تقع في مرتبة أعلى في التسلسل الهرمي من الـ cgroup المباشر المرتبط بالمهمة الحالية.

    تنسيق المعرف المعاد وقيود المساعد هي نفسها في bpf_get_current_cgroup_id().

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

long bpf_sk_assign(struct sk_buff *skb, void *sk, u64 flags)

الوصف
    المساعد محمل بشكل زائد اعتماداً على نوع برنامج BPF. ينطبق هذا الوصف على برنامجي BPF_PROG_TYPE_SCHED_CLS و BPF_PROG_TYPE_SCHED_ACT.

    خصّص sk لـ skb. عند اقترانه بإعدادات توجيه مناسبة لاستلام الحزمة نحو المقبس، سيؤدي ذلك إلى تسليم skb إلى المقبس المحدد. قد تتعارض عمليات إعادة التوجيه اللاحقة لـ skb عبر bpf_redirect() أو bpf_clone_redirect() أو طرق أخرى خارج BPF مع التسليم الناجح للمقبس.

    هذه العملية صالحة فقط من مسار دخول (ingress) الـ TC.

    يجب أن تكون معطاة flags صفراً.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل:

    -EINVAL إذا كانت flags المحددة غير مدعومة.

    -ENOENT إذا كان المقبس غير متاح للتخصيص.

    -ENETUNREACH إذا كان المقبس لا يمكن الوصول إليه (نطاق أسماء شبكة خاطئ).

    -EOPNOTSUPP إذا كانت العملية غير مدعومة، على سبيل المثال استدعاء من خارج دخول TC.

long bpf_sk_assign(struct bpf_sk_lookup *ctx, struct bpf_sock *sk, u64 flags)

الوصف
    المساعد محمل بشكل زائد اعتماداً على نوع برنامج BPF. ينطبق هذا الوصف على برامج BPF_PROG_TYPE_SK_LOOKUP.

    اختر sk كنتيجة للبحث عن مقبس.

    لنجاح العملية، يجب أن يكون المقبس الممرر متوافقاً مع وصف الحزمة المقدم من الكائن ctx.

    يجب أن يكون بروتوكول L4‏ (IPPROTO_TCP أو IPPROTO_UDP) مطابقاً تماماً. بينما يجب أن تكون عائلة بروتوكول الإنترنت (AF_INET أو AF_INET6) متوافقة، أي أنه يمكن اختيار مقابس IPv6 التي ليست v6-only لحزم IPv4.

    يمكن فقط اختيار مستمعي TCP ومقابس UDP غير المتصلة. يمكن لـ sk أن يكون فارغاً (NULL) أيضاً لإعادة تعيين أي اختيار سابق.

    يمكن أن تكون معطاة flags مزيجاً من القيم التالية:

•   BPF_SK_LOOKUP_F_REPLACE لتجاوز اختيار المقبس السابق، الذي ربما قام به برنامج BPF تم تشغيله قبلنا.

•   BPF_SK_LOOKUP_F_NO_REUSEPORT لتخطي موازنة الحمل داخل مجموعة reuseport للمقبس الذي يتم اختياره.

    عند النجاح، سيشير ctx->sk إلى المقبس المختار.

القيمة المعادة
    0 عند النجاح، أو رقم خطأ سالب في حالة الفشل.

•   -EAFNOSUPPORT إذا كانت عائلة المقبس (sk->family) غير متوافقة مع عائلة الحزمة (ctx->family).

•   -EEXIST إذا كان المقبس قد اختير بالفعل، ربما بواسطة برنامج آخر، ولم يُحدد وسم BPF_SK_LOOKUP_F_REPLACE.

•   -EINVAL إذا حُددت أوسمة غير مدعومة.

•   -EPROTOTYPE إذا كان بروتوكول L4 للمقبس (sk->protocol) لا يطابق بروتوكول الحزمة (ctx->protocol).

•   -ESOCKTNOSUPPORT إذا لم يكن المقبس في حالة مسموح بها (TCP مستمع أو UDP غير متصل).

u64 bpf_ktime_get_boot_ns(void)

الوصف
    أعد الوقت المنقضي منذ إقلاع النظام، بالنانو ثانية. يتضمن الوقت الذي عُلق فيه النظام. انظر: clock_gettime(CLOCK_BOOTTIME)

القيمة المعادة
    الـ ktime الحالي.

long bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len)

الوصف
    يستخدم bpf_seq_printf() الدالة seq_printf() التابعة لـ seq_file لطباعة سلسلة التنسيق. يمثل m ملف seq_file. الـ fmt و fmt_size مخصصان لسلسلة التنسيق نفسها. الـ data و data_len هما معطيات سلسلة التنسيق. الـ data عبارة عن مصفوفة u64 وتُخزن قيم سلسلة التنسيق المقابلة في المصفوفة. بالنسبة للسلاسل والمؤشرات حيث يُوصل إلى المشار إليهم، تُخزن قيم المؤشرات فقط في مصفوفة data. الـ data_len هو حجم data بالبايت - ويجب أن يكون من مضاعفات 8.

    تتطلب التنسيقات %s، %p{i,I}{4,6} قراءة ذاكرة النواة. قد تفشل قراءة ذاكرة النواة بسبب عنوان غير صالح أو عنوان صالح ولكنه يتطلب خطأً كبيراً في الذاكرة. إذا فشلت قراءة ذاكرة النواة، فستكون السلسلة الخاصة بـ %s سلسلة فارغة، وعنوان ip لـ %p{i,I}{4,6} سيكون 0. عدم إعادة خطأ لبرنامج bpf يتوافق مع ما يفعله bpf_trace_printk() حالياً.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل:

    -EBUSY إذا كان المخزن المؤقت لنسخ الذاكرة لكل وحدة معالجة مركزية مشغولاً، يمكن المحاولة مرة أخرى بإرجاع 1 من برنامج bpf.

    -EINVAL إذا كانت المعطيات غير صالحة، أو إذا كان fmt غير صالح/غير مدعوم.

    -E2BIG إذا كان fmt يحتوي على الكثير من محددات التنسيق.

    -EOVERFLOW إذا حدث طفحان: ستتم محاولة معالجة الكائن نفسه مرة أخرى.

long bpf_seq_write(struct seq_file *m, const void *data, u32 len)

الوصف
    يستخدم bpf_seq_write() الدالة seq_write() التابعة لـ seq_file لكتابة البيانات. يمثل m ملف seq_file. يمثل data و len البيانات المراد كتابتها بالبايت.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل:

    -EOVERFLOW إذا حدث طفحان: ستتم محاولة معالجة الكائن نفسه مرة أخرى.

u64 bpf_sk_cgroup_id(void *sk)

الوصف
    أعد معرف cgroup v2 للمقبس sk.

    يجب أن يكون sk مؤشراً غير فارغ (non-NULL) لمقبس، مثل ذاك المعاد من bpf_sk_lookup_xxx() أو bpf_sk_fullsock() وغيرهما. تنسيق المعرف المعاد هو نفسه في bpf_skb_cgroup_id().

    هذا المساعد متاح فقط إذا جُمعت النواة مع خيار التكوين CONFIG_SOCK_CGROUP_DATA.

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

u64 bpf_sk_ancestor_cgroup_id(void *sk, int ancestor_level)

الوصف
    أعد معرف cgroup v2 الذي يعد سلفاً لـ cgroup المرتبط بالمقبس sk عند ancestor_level. يقع cgroup الجذر عند ancestor_level صفر وتزيد كل خطوة لأسفل في التسلسل الهرمي من المستوى. إذا كان ancestor_level يساوي مستوى cgroup المرتبط بـ sk، فستكون القيمة المعادة هي نفسها قيمة bpf_sk_cgroup_id().

    هذا المساعد مفيد لتنفيذ سياسات تعتمد على cgroups التي تقع في مرتبة أعلى في التسلسل الهرمي من الـ cgroup المباشر المرتبط بـ sk.

    تنسيق المعرف المعاد وقيود المساعد هي نفسها في bpf_sk_cgroup_id().

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

long bpf_ringbuf_output(void *ringbuf, void *data, u64 size, u64 flags)

الوصف
    انسخ size بايت من data إلى مخزن حلقي ringbuf. إذا حُدد BPF_RB_NO_WAKEUP في flags، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد BPF_RB_FORCE_WAKEUP في flags، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد 0 في flags، يُرسل إشعار تكيفي بتوفر بيانات جديدة.

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

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

void *bpf_ringbuf_reserve(void *ringbuf, u64 size, u64 flags)

الوصف
    احجز size بايت من الحمولة في مخزن حلقي ringbuf. يجب أن تكون flags مساوية لـ 0.

القيمة المعادة
    مؤشر صالح مع توفر size بايت من الذاكرة؛ وإلا فإنه NULL.

void bpf_ringbuf_submit(void *data, u64 flags)

الوصف
    أرسل عينة المخزن الحلقي المحجوزة، والتي يشير إليها data. إذا حُدد BPF_RB_NO_WAKEUP في flags، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد BPF_RB_FORCE_WAKEUP في flags، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد 0 في flags، يُرسل إشعار تكيفي بتوفر بيانات جديدة.

    انظر 'bpf_ringbuf_output()' لتعريف الإشعار التكيفي.

القيمة المعادة
    لا شيء. ينجح دائماً.

void bpf_ringbuf_discard(void *data, u64 flags)

الوصف
    تجاهل عينة المخزن الحلقي المحجوزة، والتي يشير إليها data. إذا حُدد BPF_RB_NO_WAKEUP في flags، فلا يُرسل أي إشعار بتوفر بيانات جديدة. إذا حُدد BPF_RB_FORCE_WAKEUP في flags، يُرسل إشعار بتوفر بيانات جديدة دون قيد أو شرط. إذا حُدد 0 في flags، يُرسل إشعار تكيفي بتوفر بيانات جديدة.

    انظر 'bpf_ringbuf_output()' لتعريف الإشعار التكيفي.

القيمة المعادة
    لا شيء. ينجح دائماً.

u64 bpf_ringbuf_query(void *ringbuf, u64 flags)

الوصف
    استعلم عن الخصائص المختلفة للمخزن الحلقي المقدم. ما يتم الاستعلام عنه بالضبط تحدده flags:

•   BPF_RB_AVAIL_DATA: كمية البيانات التي لم تُستهلك بعد.

•   BPF_RB_RING_SIZE: حجم المخزن الحلقي.

•   BPF_RB_CONS_POS: موضع المستهلك (يمكن أن يلتف).

•   BPF_RB_PROD_POS: موضع المنتج (المنتجين) (يمكن أن يلتف).

    البيانات المعادة هي مجرد لقطة لحظية للقيم الفعلية وقد تكون غير دقيقة، لذا يجب استخدام هذه الأداة لدعم الاستدلالات ولإعداد التقارير، وليس لإجراء حسابات صحيحة بنسبة 100%.

القيمة المعادة
    القيمة المطلوبة، أو 0 إذا لم يُتعرف على flags.

long bpf_csum_level(struct sk_buff *skb, u64 level)

الوصف
    غيّر مستوى الاختبار التحسبي للـ skb بطبقة واحدة لأعلى أو لأسفل، أو أعد تعيينه بالكامل إلى لا شيء لجعل المكدس يقوم بالتحقق من الاختبار التحسبي. ينطبق المستوى على البروتوكولات التالية: TCP، وUDP، وGRE، وSCTP، وFCOE. على سبيل المثال، فك تغليف | ETH | IP | UDP | GUE | IP | TCP | إلى | ETH | IP | TCP | عبر مساعد bpf_skb_adjust_room() مع تمرير وسم BPF_F_ADJ_ROOM_NO_CSUM_RESET سيتطلب استدعاءً واحداً لـ bpf_csum_level() مع BPF_CSUM_LEVEL_DEC نظراً لإزالة ترويسة UDP. وبالمثل، فإن تغليف الأخير في الأول يمكن أن يرافقه استدعاء مساعد لـ bpf_csum_level() مع BPF_CSUM_LEVEL_INC إذا كان لا يزال من المفترض معالجة skb في طبقات أعلى من المكدس بدلاً من مجرد الخروج عند tc.

    هناك ثلاثة إعدادات مدعومة للمستوى في الوقت الحالي:

•   BPF_CSUM_LEVEL_INC: يزيد skb->csum_level لـ skbs التي تملك CHECKSUM_UNNECESSARY.

•   BPF_CSUM_LEVEL_DEC: ينقص skb->csum_level لـ skbs التي تملك CHECKSUM_UNNECESSARY.

•   BPF_CSUM_LEVEL_RESET: يعيد تعيين skb->csum_level إلى 0 ويضبط CHECKSUM_NONE لفرض التحقق من الاختبار التحسبي بواسطة المكدس.

•   BPF_CSUM_LEVEL_QUERY: لا عملية، يعيد skb->csum_level الحالي.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل. في حالة BPF_CSUM_LEVEL_QUERY، يُرجع skb->csum_level الحالي أو رمز الخطأ -EACCES في حالة عدم خضوع skb لـ CHECKSUM_UNNECESSARY.

struct tcp6_sock *bpf_skc_to_tcp6_sock(void *sk)

الوصف
    حوّل مؤشر sk ديناميكياً إلى مؤشر tcp6_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

struct tcp_sock *bpf_skc_to_tcp_sock(void *sk)

الوصف
    حوّل مؤشر sk ديناميكياً إلى مؤشر tcp_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

struct tcp_timewait_sock *bpf_skc_to_tcp_timewait_sock(void *sk)

الوصف
    حوّل مؤشر sk ديناميكياً إلى مؤشر tcp_timewait_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

struct tcp_request_sock *bpf_skc_to_tcp_request_sock(void *sk)

الوصف
    حوّل مؤشر sk ديناميكياً إلى مؤشر tcp_request_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

struct udp6_sock *bpf_skc_to_udp6_sock(void *sk)

الوصف
    حوّل مؤشر sk ديناميكياً إلى مؤشر udp6_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

long bpf_get_task_stack(struct task_struct *task, void *buf, u32 size, u64 flags)

الوصف
    إرجاع مكدس مستخدم أو مكدس نواة في المخزن المؤقت المقدم من برنامج bpf. ملاحظة: لن يُملأ مكدس المستخدم إلا إذا كانت المهمة task هي المهمة الحالية؛ وسترجع جميع المهام الأخرى -EOPNOTSUPP. ولتحقيق ذلك، يحتاج المساعد إلى task، وهو مؤشر صالح لـ struct task_struct. ولتخزين تتبع المكدس (stacktrace)، يقدم برنامج bpf مخزنًا buf بحجم size غير سالب.

    الوسيط الأخير، flags، يحمل عدد أطر المكدس المراد تخطيها (من 0 إلى 255)، مغطاة بـ BPF_F_SKIP_FIELD_MASK. ويمكن استخدام البتات التالية لضبط الأعلام التالية:

BPF_F_USER_STACK
    جمع مكدس فضاء مستخدم بدلاً من مكدس نواة. يجب أن تكون المهمة task هي المهمة الحالية.

BPF_F_USER_BUILD_ID
    اجمع buildid+offset بدلاً من ips لمكدس المستخدم، وهذا صالح فقط إذا حُدد BPF_F_USER_STACK أيضاً.

    يمكن لـ bpf_get_task_stack() جمع ما يصل إلى PERF_MAX_STACK_DEPTH من إطارات النواة والمستخدم على حد سواء، بشرط وجود حجم مخزن مؤقت كبير كافٍ. لاحظ أنه يمكن التحكم في هذا الحد عبر برنامج sysctl، وأنه ينبغي زيادته يدوياً من أجل تحليل مكدسات المستخدم الطويلة (مثل مكدسات برامج Java). للقيام بذلك، استخدم:

        # sysctl kernel.perf_event_max_stack=<القيمة الجديدة>

القيمة المعادة
    طول buf المنسوخ غير السالب المساوي لـ size أو أقل منه عند النجاح، أو خطأ سالب في حالة الفشل.

long bpf_load_hdr_opt(struct bpf_sock_ops *skops, void *searchby_res, u32 len, u64 flags)

الوصف
    تحميل خيار الترويسة. دعم قراءة خيار ترويسة TCP معين لبرنامج bpf (BPF_PROG_TYPE_SOCK_OPS).

    إذا كان flags هو 0، فسيُبحث عن الخيار من skops->skb_data. يحتوي التعليق في struct bpf_sock_ops على تفاصيل حول ما يحتويه skb_data تحت عمليات skops->op المختلفة.

    تحدد البايت الأولى من searchby_res النوع الذي يُراد البحث عنه.

    إذا كان نوع البحث نوعًا تجريبيًا (أي 253 أو 254 وفقًا للمعيار RFC6994)، فإنه يحتاج أيضًا إلى تحديد الـ "magic" الذي يكون إما 2 بايت أو 4 بايت. ثم يحتاج أيضًا إلى تحديد حجم الـ magic باستخدام البايت الثانية وهي "kind-length" لخيار ترويسة TCP، وتتضمن "kind-length" أيضًا أول بابتين "kind" و "kind-length" نفسها كما يفعل خيار ترويسة TCP العادي.

    على سبيل المثال، للبحث عن النوع التجريبي 254 مع magic بحجم 2 بايت وقيمته 0xeB9F، يجب أن يكون searchby_res هو [ 254, 4, 0xeB, 0x9F, 0, 0, .... 0 ].

    للبحث عن خيار مقياس النافذة القياسي (3)، يجب أن يكون searchby_res هو [ 3, 0, 0, .... 0 ]. لاحظ أنه يجب أن يكون kind-length صفرًا للخيار العادي.

    البحث عن No-Op (0) و End-of-Option-List (1) غير مدعوم.

    يجب أن يكون len بابتين على الأقل، وهو الحد الأدنى لحجم خيار الترويسة.

    الأعلام المدعومة:

•   BPF_LOAD_HDR_OPT_TCP_SYN للبحث من حزمة saved_syn أو حزمة syn المستلمة لتوها.

القيمة المعادة
    > 0 عند العثور عليه، ويُنسخ خيار الترويسة إلى searchby_res. القيمة المعادة هي الطول الإجمالي المنسوخ. عند الفشل، يُعاد رمز خطأ سالب:

    -EINVAL إذا كانت إحدى المعاملات غير صالحة.

    -ENOMSG إذا لم يُعثر على الخيار.

    -ENOENT إذا لم تكن حزمة syn متاحة عند استخدام BPF_LOAD_HDR_OPT_TCP_SYN.

    -ENOSPC إذا لم تتوفر مساحة كافية. نُسخ عدد len من البايتات فقط.

    -EFAULT عند الفشل في تحليل خيارات الترويسة في الحزمة.

    -EPERM إذا تعذر استخدام المساعد تحت skops->op الحالي.

long bpf_store_hdr_opt(struct bpf_sock_ops *skops, const void *from, u32 len, u64 flags)

الوصف
    تخزين خيار الترويسة. ستُنسخ البيانات من المخزن المؤقت from بطول len إلى ترويسة TCP.

    يجب أن يحتوي المخزن المؤقت from على الخيار بالكامل بما في ذلك النوع (kind)، وطول النوع (kind-length)، وبيانات الخيار الفعلية. يجب أن يكون len بطول kind-length على الأقل. ليس بالضرورة أن يكون kind-length بمحاذاة 4 بايت. ستتولى النواة الحشو (padding) وضبط قيمة المحاذاة لـ 4 بايت في th->doff.

    سيتحقق هذا المساعد من وجود خيارات مكررة بالبحث عن الخيار نفسه في skb الصادر.

    لا يمكن استدعاء هذا المساعد إلا أثناء BPF_SOCK_OPS_WRITE_HDR_OPT_CB.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل:

    -EINVAL إذا كانت المعامل غير صالحة.

    -ENOSPC إذا لم تتوفر مساحة كافية في الترويسة. لم يُكتب أي شيء.

    -EEXIST إذا كان الخيار موجودًا بالفعل.

    -EFAULT عند الفشل في تحليل خيارات الترويسة الموجودة.

    -EPERM إذا تعذر استخدام المساعد تحت skops->op الحالي.

long bpf_reserve_hdr_opt(struct bpf_sock_ops *skops, u32 len, u64 flags)

الوصف
    حجز len بايت لخيار ترويسة bpf. ستُستخدم المساحة بواسطة bpf_store_hdr_opt() لاحقًا في BPF_SOCK_OPS_WRITE_HDR_OPT_CB.

    إذا استُدعي bpf_reserve_hdr_opt() مرات متعددة، فسيُحجز إجمالي عدد البايتات.

    لا يمكن استدعاء هذا المساعد إلا أثناء BPF_SOCK_OPS_HDR_OPT_LEN_CB.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حالة الفشل:

    -EINVAL إذا كانت إحدى المعاملات غير صالحة.

    -ENOSPC إذا لم تتوفر مساحة كافية في الترويسة.

    -EPERM إذا تعذر استخدام المساعد تحت skops->op الحالي.

void *bpf_inode_storage_get(struct bpf_map *map, void *inode, void *value, u64 flags)

الوصف
    الحصول على bpf_local_storage من inode.

    من الناحية المنطقية، يمكن اعتباره كالحصول على القيمة من map باستخدام inode كـ مفتاح. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن bpf_map_lookup_elem(map, &inode) باستثناء أن هذا المساعد يفرض أن يكون المفتاح inode وأن تكون الخريطة أيضًا من نوع BPF_MAP_TYPE_INODE_STORAGE.

    في الخلفية، تُخزن القيمة محليًا في inode بدلًا من الـ map. تُستخدم الـ map كـ "نوع" لـ bpf-local-storage. ويُبحث عن "نوع" bpf-local-storage (أي الـ map) في كافة bpf_local_storage الموجودة في inode.

    يمكن استخدام flags اختيارية (BPF_LOCAL_STORAGE_GET_F_CREATE) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام value مع BPF_LOCAL_STORAGE_GET_F_CREATE لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت value هي NULL، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية.

القيمة المعادة
    يُعاد مؤشر bpf_local_storage عند النجاح.

    NULL إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد.

int bpf_inode_storage_delete(struct bpf_map *map, void *inode)

الوصف
    حذف bpf_local_storage من inode.

القيمة المعادة
    0 عند النجاح.

    -ENOENT إذا تعذر العثور على bpf_local_storage.

long bpf_d_path(const struct path *path, char *buf, u32 sz)

الوصف
    إعادة المسار الكامل لكائن struct path المعطى، والذي يجب أن يكون كائن path الخاص بـ BTF للنواة. يُعاد المسار في المخزن المؤقت buf المزود بحجم sz ويكون منتهيًا بـ NULL.

القيمة المعادة
    عند النجاح، الطول الموجب تماماً للسلسلة النصية، بما في ذلك محرف NUL اللاحق. عند الخطأ، قيمة سالبة.

long bpf_copy_from_user(void *dst, u32 size, const void *user_ptr)

الوصف
    قراءة عدد size من البايتات من عنوان مساحة المستخدم user_ptr وتخزين البيانات في dst. هذا غلاف لـ copy_from_user().

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_snprintf_btf(char *str, u32 str_size, struct btf_ptr *ptr, u32 btf_ptr_size, u64 flags)

الوصف
    استخدام BTF لتخزين تمثيل نصي لـ ptr->ptr في str، باستخدام ptr->type_id. يجب أن تحدد هذه القيمة النوع الذي يشير إليه ptr->ptr. يمكن استخدام LLVM __builtin_btf_type_id(type, 1) للبحث عن معرفات أنواع BTF في vmlinux. عبر تتبع بنية البيانات باستخدام BTF، تُخزن معلومات النوع والقيم في أول str_size - 1 بايت من str. يُجرى نسخ آمن لبيانات المؤشر لتجنب انهيار النواة أثناء العملية. يمكن للأنواع الأصغر استخدام مساحة النصوص على المكدس؛ بينما يمكن للبرامج الأكبر استخدام بيانات الخريطة لتخزين التمثيل النصي.

    يمكن مشاركة السلسلة لاحقًا مع مساحة المستخدم عبر bpf_perf_event_output() أو واجهات الذاكرة الحلقية (ring buffer). يجب تجنب bpf_trace_printk() لأنها تضع حدًا صغيرًا جدًا على حجم السلسلة مما يفقدها الفائدة.

    flags هي مزيج من

BTF_F_COMPACT
    لا يوجد تنسيق حول معلومات النوع

BTF_F_NONAME
    لا توجد أسماء أو أنواع لأعضاء struct/union

BTF_F_PTR_RAW
    إظهار قيم المؤشر الخام (غير المموهة)؛ وهو ما يعادل محدد printk %px.

BTF_F_ZERO
    إظهار أعضاء struct/union ذات القيمة الصفرية؛ لا تُعرض مبدئيًا

القيمة المعادة
    عدد البايتات التي كُتبت (أو التي كانت ستُكتب إذا كان لابد من بتر المخرج بسبب حجم السلسلة)، أو خطأ سالب في حالات الفشل.

long bpf_seq_printf_btf(struct seq_file *m, struct btf_ptr *ptr, u32 ptr_size, u64 flags)

الوصف
    استخدام BTF للكتابة إلى seq_write تمثيل نصي لـ ptr->ptr، باستخدام ptr->type_id كما هو الحال في bpf_snprintf_btf(). الـ flags مطابقة لتلك المستخدمة في bpf_snprintf_btf.

القيمة المعادة
    0 عند النجاح أو خطأ سالب في حالة الفشل.

u64 bpf_skb_cgroup_classid(struct sk_buff *skb)

الوصف
    راجع bpf_get_cgroup_classid() للوصف الرئيسي. يختلف هذا المساعد عن bpf_get_cgroup_classid() في أن فئة net_cls الخاصة بـ cgroup v1 تُسترجع فقط من المقبس المرتبط بـ skb بدلًا من العملية الحالية.

القيمة المعادة
    يُرجع المعرف أو 0 في حال تعذر جلب المعرف.

long bpf_redirect_neigh(u32 ifindex, struct bpf_redir_neigh *params, int plen, u64 flags)

الوصف
    توجيه الحزمة إلى جهاز شبكة آخر بالفهرس ifindex وملء عناوين L2 من النظام الفرعي المجاور. هذا المساعد مشابه نوعًا ما لـ bpf_redirect()، باستثناء أنه يملأ عناوين L2 أيضًا، مما يعني، داخليًا، أن المساعد يعتمد على البحث عن الجار للحصول على عنوان L2 للقفزة التالية (nexthop).

    سيقوم المساعد بإجراء بحث FIB بناءً على ترويسة شبكة skb للحصول على عنوان القفزة التالية، ما لم يتم توفير ذلك من قبل المستدعِي في وسيطة params. تشير وسيطة plen إلى طول params ويجب ضبطها على 0 إذا كانت params هي NULL.

    وسيطة flags محجوزة ويجب أن تكون 0. المساعد مدعوم حاليًا فقط لأنواع برامج tc BPF، ومُفعّل لبروتوكولات IPv4 و IPv6.

القيمة المعادة
    يعيد المساعد TC_ACT_REDIRECT عند النجاح أو TC_ACT_SHOT عند الخطأ.

void *bpf_per_cpu_ptr(const void *percpu_ptr, u32 cpu)

الوصف
    أخذ مؤشر إلى ksym لكل معالج، percpu_ptr، وإعادة مؤشر إلى متغير النواة لكل معالج على cpu. الـ ksym هو متغير خارجي (extern) مُزيّن بـ '__ksym'. بالنسبة لـ ksym، يوجد متغير عام (إما ساكن أو عام) مُعرّف بنفس الاسم في النواة. يكون ksym لكل معالج إذا كان المتغير العام لكل معالج. يشير المؤشر المعاد إلى المتغير العام لكل معالج على cpu.

    يتمتع bpf_per_cpu_ptr() بنفس دلالات per_cpu_ptr() في النواة، باستثناء أن bpf_per_cpu_ptr() قد يعيد NULL. يحدث هذا إذا كان cpu أكبر من nr_cpu_ids. يجب على المستدعِي لـ bpf_per_cpu_ptr() التحقق من القيمة المعادة.

القيمة المعادة
    مؤشر يشير إلى متغير النواة لكل معالج على cpu، أو NULL إذا كان cpu غير صالح.

void *bpf_this_cpu_ptr(const void *percpu_ptr)

الوصف
    أخذ مؤشر إلى ksym لكل معالج، percpu_ptr، وإعادة مؤشر إلى متغير النواة لكل معالج على هذا المعالج. راجع وصف 'ksym' في bpf_per_cpu_ptr().

    يتمتع bpf_this_cpu_ptr() بنفس دلالات this_cpu_ptr() في النواة. وبخلاف bpf_per_cpu_ptr()، فإنه لا يعيد NULL أبدًا.

القيمة المعادة
    مؤشر يشير إلى متغير النواة لكل معالج على هذا المعالج.

long bpf_redirect_peer(u32 ifindex, u64 flags)

الوصف
    توجيه الحزمة إلى جهاز شبكة آخر بالفهرس ifindex. هذا المساعد مشابه نوعًا ما لـ bpf_redirect()، باستثناء أن التوجيه يحدث لجهاز النظير (peer) لـ ifindex، ويحدث تبديل نطاق أسماء الشبكة (netns) من الدخول (ingress) إلى الدخول دون المرور عبر طابور الأعمال المؤجلة (backlog queue) للمعالج.

    لا تُمسح skb->mark و skb->tstamp أثناء تبديل netns.

    وسيطة flags محجوزة ويجب أن تكون 0. المساعد مدعوم حاليًا فقط لأنواع برامج tc BPF عند خطاف الدخول (ingress hook) ولأنواع الأجهزة المستهدفة veth و netkit. يجب أن يقع جهاز النظير في نطاق أسماء شبكة مختلف.

القيمة المعادة
    يعيد المساعد TC_ACT_REDIRECT عند النجاح أو TC_ACT_SHOT عند الخطأ.

void *bpf_task_storage_get(struct bpf_map *map, struct task_struct *task, void *value, u64 flags)

الوصف
    الحصول على bpf_local_storage من الـ task.

    من الناحية المنطقية، يمكن اعتباره كالحصول على القيمة من map باستخدام task كـ مفتاح. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن bpf_map_lookup_elem(map, &task) باستثناء أن هذا المساعد يفرض أن يكون المفتاح task_struct وأن تكون الخريطة أيضًا من نوع BPF_MAP_TYPE_TASK_STORAGE.

    في الخلفية، تُخزن القيمة محليًا في task بدلًا من الـ map. تُستخدم الـ map كـ "نوع" لـ bpf-local-storage. ويُبحث عن "نوع" bpf-local-storage (أي الـ map) في كافة bpf_local_storage الموجودة في task.

    يمكن استخدام flags اختيارية (BPF_LOCAL_STORAGE_GET_F_CREATE) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام value مع BPF_LOCAL_STORAGE_GET_F_CREATE لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت value هي NULL، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية.

القيمة المعادة
    يُعاد مؤشر bpf_local_storage عند النجاح.

    NULL إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد.

long bpf_task_storage_delete(struct bpf_map *map, struct task_struct *task)

الوصف
    حذف bpf_local_storage من task.

القيمة المعادة
    0 عند النجاح.

    -ENOENT إذا تعذر العثور على bpf_local_storage.

struct task_struct *bpf_get_current_task_btf(void)

الوصف
    إعادة مؤشر BTF للمهمة "الحالية". يمكن استخدام هذا المؤشر أيضًا في المساعدات التي تقبل ARG_PTR_TO_BTF_ID من نوع task_struct.

القيمة المعادة
    مؤشر للمهمة الحالية.

long bpf_bprm_opts_set(struct linux_binprm *bprm, u64 flags)

الوصف
    اضبط خيارات معينة أو امسحها في bprm:

    ‏BPF_F_BPRM_SECUREEXEC لضبط بت التنفيذ الآمن (secureexec) الذي يضبط AT_SECURE auxv لـ glibc. ويُمسح البت إذا لم يُحدد العلم.

القيمة المعادة
    ‏-EINVAL إذا مُررت flags غير صالحة، وصفر فيما عدا ذلك.

u64 bpf_ktime_get_coarse_ns(void)

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

    انظر: clock_gettime(CLOCK_MONOTONIC_COARSE)

القيمة المعادة
    الـ ktime الحالي.

long bpf_ima_inode_hash(struct inode *inode, void *dst, u32 size)

الوصف
    يُعيد وسم IMA المخزن لـ inode (إذا كان متاحًا). إذا كان الوسم أكبر من size، فستُنسخ بايتات بقدر size فقط إلى dst

القيمة المعادة
    يُعاد hash_algo عند النجاح، أو -EOPNOTSUPP إذا كانت IMA معطلة أو -EINVAL إذا مُررت معاملات غير صالحة.

struct socket *bpf_sock_from_file(struct file *file)

الوصف
    إذا كان الملف المعطى يمثل مقبسًا، فيُعيد المقبس المرتبط به.

القيمة المعادة
    مؤشر إلى struct socket عند النجاح أو NULL إذا لم يكن الملف مقبسًا.

long bpf_check_mtu(void *ctx, u32 ifindex, u32 *mtu_len, s32 len_diff, u64 flags)

الوصف
    تحقق من حجم الحزمة للتأكد من عدم تجاوزه لوحدة النقل القصوى (MTU) لجهاز الشبكة (بناءً على ifindex). من المرجح استخدام هذا المساعد مع مساعدين آخرين يعدلون/يغيرون حجم الحزمة.

    يمكن استخدام المعامل len_diff للاستعلام مع تغيير مخطط له في الحجم. يتيح هذا التحقق من MTU قبل تغيير سياق (ctx) الحزمة. إن تقديم تعديل len_diff أكبر من حجم الحزمة الفعلي (مما يؤدي إلى حجم حزمة سالب) لن يتجاوز MTU من حيث المبدأ، ولهذا السبب لا يُعتبر فشلاً. هناك حاجة إلى مساعدي BPF آخرين لإجراء تغيير الحجم المخطط له؛ ولذلك تقع مسؤولية اكتشاف حجم الحزمة السالب على عاتق أولئك المساعدين.

    تحديد ifindex كصفر يعني إجراء فحص MTU مقابل جهاز الشبكة الحالي. هذا أمر عملي إذا لم يُستخدم هذا قبل إعادة التوجيه.

    عند الإدخال، يجب أن يكون mtu_len مؤشرًا صالحًا، وإلا سيرفض المدقق برنامج BPF. إذا هُيئَت قيمة mtu_len إلى الصفر، فسيُستخدم حجم حزمة سياق (ctx). عند تقديم قيمة mtu_len كمدخل، فإن هذا يحدد طول الطبقة الثالثة (L3) الذي يُجرى فحص MTU مقابله. تذكر أن طولي XDP و TC يعملان في الطبقة الثانية (L2)، لكن هذه القيمة هي L3 لأنها ترتبط بقيم MTU و IP-header tot_len التي تنتمي للطبقة L3 (سلوك مشابه لـ bpf_fib_lookup).

    يمكن لجدول توجيه نواة لينكس ضبط وحدات MTU على مستوى مسار أكثر تحديدًا، وهو ما لا يوفره هذا المساعد. لفحوصات MTU على مستوى المسار، استخدم المساعد bpf_fib_lookup().

    سياق ctx هو إما struct xdp_md لبرامج XDP أو struct sk_buff لبرامج tc cls_act.

    يمكن أن يكون معامل flags مزيجًا من قيمة واحدة أو أكثر من القيم التالية:

BPF_MTU_CHK_SEGS
    هذا العلم سيعمل فقط مع سياق ctx من نوع struct sk_buff. إذا احتوى سياق الحزمة على مخازن مؤقتة إضافية لقطع الحزمة (تُعرف غالبًا باسم GSO skb)، فإن فحص MTU يكون أصعب في هذه المرحلة، لأنه في مسار الإرسال من الممكن إعادة تقسيم حزمة skb (اعتمادًا على ميزات جهاز الشبكة). قد يظل هذا انتهاكًا لـ MTU، لذا يُمكّن هذا العلم إجراء فحص MTU مقابل القطع، مع رمز إرجاع مختلف للانتهاك لتمييزه. لا يمكن للفحص استخدام len_diff.

    عند الإرجاع، يحتوي مؤشر mtu_len على قيمة MTU لجهاز الشبكة. تذكر أن وحدة MTU المضبوطة لجهاز الشبكة هي حجم L3، وهو ما يُعاد هنا بينما يعمل طول XDP و TC في L2. يأخذ المساعد هذا في الحسبان من أجلك، لكن تذكر ذلك عند استخدام قيمة MTU في كود BPF الخاص بك.

القيمة المعادة

•   0 عند النجاح، وتُملأ قيمة MTU في مؤشر mtu_len.

•   أقل من 0 إذا كان أي معامل إدخال غير صالح (لا يُحدث mtu_len)

    تعيد انتهاكات MTU قيمًا موجبة، ولكنها تملأ أيضًا قيمة MTU في مؤشر mtu_len، حيث يمكن أن يكون ذلك مطلوبًا لتنفيذ معالجة PMTU:

•   BPF_MTU_CHK_RET_FRAG_NEEDED

•   BPF_MTU_CHK_RET_SEGS_TOOBIG

long bpf_for_each_map_elem(struct bpf_map *map, void *callback_fn, void *callback_ctx, u64 flags)

الوصف
    لكل عنصر في map، استدعِ دالة callback_fn مع map و callback_ctx ومعاملات أخرى خاصة بالخريطة. يجب أن تكون دالة callback_fn دالة ساكنة ويجب أن يكون callback_ctx مؤشرًا إلى المكدس. تُستخدم flags للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون flags صفراً.

    فيما يلي قائمة بأنواع الخرائط المدعومة وتوقيعات الاستدعاء المتوقعة لكل منها:

    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

    long (*callback_fn)(struct bpf_map *map, const void *key, void *value, void *ctx);

    بالنسبة لخرائط per_cpu، فإن map_value هي القيمة الموجودة على المعالج الذي يعمل عليه bpf_prog.

    إذا أعادت callback_fn القيمة 0، فسيستمر المساعد إلى العنصر التالي. إذا كانت القيمة المعادة 1، فسيقوم المساعد بتخطي بقية العناصر والعودة. قيم الإرجاع الأخرى لا تُستخدم الآن.

القيمة المعادة
    عدد عناصر الخريطة المقطوعة عند النجاح، أو -EINVAL لأعلام flags غير صالحة.

long bpf_snprintf(char *str, u32 str_size, const char *fmt, u64 *data, u32 data_len)

الوصف
    يُخرج سلسلة نصية إلى مخزن str المؤقت بحجم str_size بناءً على سلسلة تنسيق مخزنة في خريطة للقراءة فقط يشير إليها fmt.

    يتوافق كل محدد تنسيق في fmt مع عنصر u64 واحد في مصفوفة data. بالنسبة للسلاسل والمؤشرات حيث يتم الوصول إلى المشار إليهم، تُخزن قيم المؤشر فقط في مصفوفة data. المعامل data_len هو حجم data بالبايت - ويجب أن يكون مضاعفًا للرقم 8.

    تتطلب التنسيقات %s و %p{i,I}{4,6} قراءة ذاكرة النواة. قد تفشل قراءة ذاكرة النواة إما بسبب عنوان غير صالح أو عنوان صالح ولكنه يتطلب خطأً كبيرًا في الذاكرة. إذا فشلت قراءة ذاكرة النواة، فستكون السلسلة لـ %s سلسلة فارغة، وسيكون عنوان ip لـ %p{i,I}{4,6} هو 0. عدم إرجاع خطأ إلى برنامج bpf يتوافق مع ما يفعله bpf_trace_printk() في الوقت الحالي.

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

    أو -EBUSY إذا كان المخزن المؤقت لنسخ ذاكرة per-CPU مشغولاً.

long bpf_sys_bpf(u32 cmd, void *attr, u32 attr_size)

الوصف
    نفذ استدعاء نظام bpf بالمعاملات المعطاة.

القيمة المعادة
    نتيجة استدعاء نظام.

long bpf_btf_find_by_name_kind(char *name, int name_sz, u32 kind, int flags)

الوصف
    ابحث عن نوع BTF بالاسم والنوع المعطى في vmlinux BTF أو في BTFs للوحدة.

القيمة المعادة
    يُعيد btf_id و btf_obj_fd في الـ 32 بت السفلى والعليا.

long bpf_sys_close(u32 fd)

الوصف
    نفذ استدعاء نظام الإغلاق لـ FD المعطى.

القيمة المعادة
    نتيجة استدعاء نظام.

long bpf_timer_init(struct bpf_timer *timer, struct bpf_map *map, u64 flags)

الوصف
    هيئ الميقاتية. أول 4 بتات من flags تحدد clockid. يُسمح فقط بـ CLOCK_MONOTONIC و CLOCK_REALTIME و CLOCK_BOOTTIME. جميع البتات الأخرى من flags محجوزة. سيرفض المدقق البرنامج إذا لم تكن الميقاتية timer من نفس الخريطة map.

القيمة المعادة
    0 عند النجاح. -EBUSY إذا كانت الميقاتية timer مهيأة بالفعل. -EINVAL إذا مُررت أعلام flags غير صالحة. -EPERM إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر.

long bpf_timer_set_callback(struct bpf_timer *timer, void *callback_fn)

الوصف
    اضبط الميقاتية لاستدعاء دالة callback_fn الساكنة.

القيمة المعادة
    0 عند النجاح. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا. -EPERM إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر.

long bpf_timer_start(struct bpf_timer *timer, u64 nsecs, u64 flags)

الوصف
    اضبط انتهاء صلاحية الميقاتية بعد 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 مختلفة.

    يمكن لـ flags أن يكون واحدًا مما يلي:

BPF_F_TIMER_ABS
    ابدأ الميقاتية بقيمة انتهاء مطلقة بدلاً من القيمة النسبية المبدئية.

BPF_F_TIMER_CPU_PIN
    ستُثبت الميقاتية في المعالج الخاص بالمستدعي.

القيمة المعادة
    0 عند النجاح. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا أو مُررت أعلام flags غير صالحة.

long bpf_timer_cancel(struct bpf_timer *timer)

الوصف
    ألفِ الميقاتية وانتظر انتهاء callback_fn إذا كانت تعمل.

القيمة المعادة
    0 إذا لم تكن الميقاتية نشطة. 1 إذا كانت الميقاتية نشطة. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا. -EDEADLK إذا حاولت callback_fn استدعاء bpf_timer_cancel() على ميقاتيتها الخاصة مما قد يؤدي إلى طريق مسدود (deadlock) بخلاف ذلك.

u64 bpf_get_func_ip(void *ctx)

الوصف
    احصل على عنوان الدالة المتتبعة (لبرامج التتبع و kprobe).

    عند استدعائه لبرنامج kprobe متصل كـ uprobe فإنه يعيد عنوان المسبار لكل من uprobe الدخول والعودة.

القيمة المعادة
    عنوان الدالة المتتبعة لـ kprobe. وصفر لـ kprobes الموضوعة داخل الدالة (ليس عند الدخول). وعنوان المسبار لـ uprobe و return uprobe.

u64 bpf_get_attach_cookie(void *ctx)

الوصف
    احصل على قيمة bpf_cookie المقدمة (اختياريًا) أثناء اتصال البرنامج. قد تختلف لكل اتصال فردي، حتى لو كان برنامج BPF نفسه هو نفسه. يتوقع سياق برنامج BPF كأول معامل ctx.

مدعوم لأنواع البرامج التالية:

•   kprobe/uprobe؛

•   tracepoint؛

•   perf_event.

القيمة المعادة
    القيمة التي حددها المستخدم عند إنشاء رابط BPF/وقت الاتصال أو 0، إذا لم تُحدد.

long bpf_task_pt_regs(struct task_struct *task)

الوصف
    احصل على struct pt_regs المرتبط بـ task.

القيمة المعادة
    مؤشر إلى struct pt_regs.

long bpf_get_branch_snapshot(void *entries, u32 size, u64 flags)

الوصف
    احصل على تتبع الفرع من محركات العتاد مثل Intel LBR. يُوقف محرك العتاد بعد فترة وجيزة من استدعاء المساعد. لذلك، يحتاج المستخدم إلى تصفية مدخلات الفروع بناءً على حالة الاستخدام الفعلية. لالتقاط تتبع الفرع قبل نقطة انطلاق برنامج BPF، يجب استدعاء المساعد في بداية برنامج BPF.

    تُخزن البيانات كـ struct perf_branch_entry في مخزن المخرجات المؤقت entries. المعامل size هو حجم entries بالبايت. المعامل flags محجوز حاليًا ويجب أن يكون صفراً.

القيمة المعادة
    عند النجاح، عدد البايتات المكتوبة في buf. عند الخطأ، قيمة سالبة.

    ‏-EINVAL إذا لم تكن flags صفراً.

    -ENOENT إذا كانت المعمارية لا تدعم سجلات الفروع.

long bpf_trace_vprintk(const char *fmt, u32 fmt_size, const void *data, u32 data_len)

الوصف
    يسلك سلوك مساعد bpf_trace_printk()، ولكنه يأخذ مصفوفة من u64 لتنسيقها ويمكنه التعامل مع المزيد من معاملات التنسيق كنتيجة لذلك.

    يجب استخدام المعاملات كما في المساعد bpf_seq_printf().

القيمة المعادة
    عدد البايتات المكتوبة في المخزن المؤقت، أو خطأ سالب في حال الفشل.

struct unix_sock *bpf_skc_to_unix_sock(void *sk)

الوصف
    حول مؤشر sk ديناميكيًا إلى مؤشر unix_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

long bpf_kallsyms_lookup_name(const char *name, int name_sz, int flags, u64 *res)

الوصف
    احصل على عنوان رمز النواة، ويُعاد في res. يُضبط res إلى 0 إذا لم يُعثر على الرمز.

القيمة المعادة
    عند النجاح، صفر. عند الخطأ، قيمة سالبة.

    ‏-EINVAL إذا لم تكن flags صفراً.

    ‏-EINVAL إذا لم يكن حجم السلسلة name هو نفس حجم name_sz.

    ‏-ENOENT إذا لم يُعثر على الرمز.

    ‏-EPERM إذا لم يملك المستدعِي إذنًا للحصول على عنوان النواة.

long bpf_find_vma(struct task_struct *task, u64 addr, void *callback_fn, void *callback_ctx, u64 flags)

الوصف
    البحث عن vma للمهمة task التي تحتوي على addr، واستدعاء دالة callback_fn مع task و vma و callback_ctx. يجب أن تكون callback_fn دالة ساكنة، ويجب أن يكون callback_ctx مؤشرًا إلى المكدس. تُستخدم flags للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون flags صفرًا.

    توقيع الاستدعاء الراجع المتوقع هو

    long (*callback_fn)(struct task_struct *task, struct vm_area_struct *vma, void *callback_ctx);

القيمة المعادة
    0 عند النجاح. -ENOENT إذا كان task->mm هو NULL، أو إذا لم تتضمن أي vma العنوان addr. -EBUSY في حال الفشل في محاولة قفل mmap_lock. -EINVAL لأجل flags غير صالحة.

long bpf_loop(u32 nr_loops, void *callback_fn, void *callback_ctx, u64 flags)

الوصف
    لعدد nr_loops، تُستدعى دالة callback_fn مع callback_ctx كمعامل سياق. يجب أن تكون callback_fn دالة ساكنة، ويجب أن يكون callback_ctx مؤشرًا إلى المكدس. تُستخدم flags للتحكم في جوانب معينة من المساعد. حاليًا، يجب أن تكون flags صفرًا. حاليًا، nr_loops محدود بـ 1 << 23 (حوالي 8 ملايين) حلقة.

    long (*callback_fn)(u64 index, void *ctx);

    حيث index هو الفهرس الحالي في الحلقة. يبدأ الفهرس من الصفر.

    إذا أعادت callback_fn القيمة 0، فسيستمر المساعد في الحلقة التالية. إذا كانت القيمة المعادة 1، فسيقوم المساعد بتخطي بقية الحلقات والعودة. قيم الإرجاع الأخرى لا تُستخدم الآن، وسيرفضها المدقق.

القيمة المعادة
    عدد الحلقات التي نُفذت، أو -EINVAL لأعلام flags غير صالحة، أو -E2BIG إذا تجاوز nr_loops الحد الأقصى لعدد الحلقات.

long bpf_strncmp(const char *s1, u32 s1_sz, const char *s2)

الوصف
    إجراء strncmp() بين s1 و s2. لا يلزم أن يكون s1 منتهيًا بـ null، و s1_sz هو أقصى حجم تخزين لـ s1. يجب أن يكون s2 سلسلة للقراءة فقط.

القيمة المعادة
    عدد صحيح أقل من، أو يساوي، أو أكبر من الصفر إذا وُجد أن أول s1_sz بايت من s1 أقل من، أو تطابق، أو أكبر من s2.

long bpf_get_func_arg(void *ctx, u32 n, u64 *value)

الوصف
    الحصول على سجل المعامل رقم n (بدءًا من الصفر) للدالة المتعقبة (لبرامج التعقب) ويُعاد في value.

القيمة المعادة
    0 عند النجاح. -EINVAL إذا كان n >= عدد سجلات المعاملات للدالة المتعقبة.

long bpf_get_func_ret(void *ctx, u64 *value)

الوصف
    الحصول على قيمة الإعادة للدالة المتعقبة (لبرامج التعقب) في value.

القيمة المعادة
    0 عند النجاح. -EOPNOTSUPP لبرامج التعقب بخلاف BPF_TRACE_FEXIT أو BPF_MODIFY_RETURN.

long bpf_get_func_arg_cnt(void *ctx)

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

القيمة المعادة
    عدد سجلات الوسائط للدالة المقتفاة.

int bpf_get_retval(void)

الوصف
    احصل على قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا.

    هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno.

القيمة المعادة
    قيمة إرجاع برنامج BPF.

int bpf_set_retval(int retval)

الوصف
    اضبط قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا.

    هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno.

    لاحظ وجود الحالة الحدية التالية حيث يصدر البرنامج خطأً عبر bpf_set_retval لكنه يشير إلى النجاح عبر 'return 1': bpf_set_retval(-EPERM); return 1;

    في هذه الحالة، ستستخدم قيمة إرجاع برنامج BPF قيمة المساعد -EPERM. يظل هذا صحيحًا بالنسبة لـ cgroup/bind{4,6} التي تدعم حالة النجاح الإضافية 'return 3'.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

u64 bpf_xdp_get_buff_len(struct xdp_buff *xdp_md)

الوصف
    احصل على الحجم الكلي لصوان xdp معطى (المنطقة الخطية والمفصحة)

القيمة المعادة
    الحجم الكلي لصوان xdp معطى.

long bpf_xdp_load_bytes(struct xdp_buff *xdp_md, u32 offset, void *buf, u32 len)

الوصف
    وُفر هذا المساعد كطريقة سهلة لتحميل البيانات من صوان xdp. يمكن استخدامه لتحميل len من البايتات من الإزاحة offset من الإطار المرتبط بـ xdp_md، إلى الصوان الذي يشير إليه buf.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_xdp_store_bytes(struct xdp_buff *xdp_md, u32 offset, void *buf, u32 len)

الوصف
    خزّن len من البايتات من الصوان buf في الإطار المرتبط بـ xdp_md، عند الإزاحة offset.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

long bpf_copy_from_user_task(void *dst, u32 size, const void *user_ptr, struct task_struct *tsk, u64 flags)

الوصف
    اقرأ size بايت من عنوان فضاء المستخدم user_ptr في فضاء عناوين tsk، ويخزن البيانات في dst. لا تُستخدم flags حاليًا ووُفرت للتوسع المستقبلي. لا يمكن استخدام هذا المساعد إلا بواسطة البرامج القابلة للنوم.

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل. عند الخطأ، يُصفر الصوان dst.

long bpf_skb_set_tstamp(struct sk_buff *skb, u64 tstamp, u32 tstamp_type)

الوصف
    غيّر __sk_buff->tstamp_type إلى tstamp_type واضبط tstamp في __sk_buff->tstamp معًا.

    إذا لم تكن هناك حاجة لتغيير __sk_buff->tstamp_type، فيمكن كتابة قيمة tstamp مباشرة في __sk_buff->tstamp بدلاً من ذلك.

    BPF_SKB_TSTAMP_DELIVERY_MONO هي بصمة الوقت الوحيدة التي سيُحتفظ بها أثناء bpf_redirect_*(). يجب استخدام tstamp غير صفري مع tstamp_type من نوع BPF_SKB_TSTAMP_DELIVERY_MONO.

    لا يمكن استخدام BPF_SKB_TSTAMP_UNSPEC كـ tstamp_type إلا مع tstamp صفري.

    بروتوكولات skb->protocol المدعومة هي IPv4 و IPv6 فقط.

    هذه الدالة مفيدة للغاية عند الحاجة لضبط وقت تسليم أحادي (mono) في __sk_buff->tstamp ثم bpf_redirect_*() إلى مخرج (egress) واجهة ما. على سبيل المثال، تغيير بصمة وقت (الاستلام) في __sk_buff->tstamp عند المدخل إلى وقت تسليم أحادي ثم bpf_redirect_*() إلى <sch_fq@phy-dev>.

القيمة المعادة
    0 عند النجاح. -EINVAL لمدخلات غير صالحة، و -EOPNOTSUPP لبروتوكول غير مدعوم.

long bpf_ima_file_hash(struct file *file, void *dst, u32 size)

الوصف
    يُرجع بصمة (hash) IMA المحسوبة لـ file. إذا كانت البصمة أكبر من size، فسيُنسخ size بايت فقط إلى dst

القيمة المعادة
    يُرجع hash_algo عند النجاح، أو -EOPNOTSUPP إذا فشل حساب البصمة، أو -EINVAL إذا مُررت وسائط غير صالحة.

void *bpf_kptr_xchg(void *dst, void *ptr)

الوصف
    بادل kptr عند المؤشر dst بـ ptr، وأرجع القيمة القديمة. يمكن لـ dst أن يكون قيمة خريطة أو kptr محلي. يمكن لـ ptr أن يكون NULL، وإلا فيجب أن يكون مؤشرًا مرجعيًا سيُحرر عند استدعاء هذا المساعد.

القيمة المعادة
    القيمة القديمة لـ kptr (والتي يمكن أن تكون NULL). المؤشر المُرجع، إن لم يكن NULL، هو مرجع يجب تحريره باستخدام دالة التحرير المقابلة له، أو نقله إلى خريطة BPF قبل خروج البرنامج.

void *bpf_map_lookup_percpu_elem(struct bpf_map *map, const void *key, u32 cpu)

الوصف
    أجرِ بحثًا في percpu map عن مدخل مرتبط بـ key على وحدة المعالجة المركزية cpu.

القيمة المعادة
    قيمة الخريطة المرتبطة بـ key على وحدة المعالجة cpu، أو NULL إذا لم يُعثر على مدخل أو كانت وحدة المعالجة المركزية cpu غير صالحة.

struct mptcp_sock *bpf_skc_to_mptcp_sock(void *sk)

الوصف
    حوّل (cast) مؤشر sk حركيًا إلى مؤشر mptcp_sock.

القيمة المعادة
    sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

long bpf_dynptr_from_mem(void *data, u64 size, u64 flags, struct bpf_dynptr *ptr)

الوصف
    احصل على dynptr إلى الذاكرة المحلية data.

    يجب أن يكون data مؤشرًا لقيمة خريطة. الحجم الأقصى size المدعوم هو DYNPTR_MAX_SIZE. لا تُستخدم flags حاليًا.

القيمة المعادة
    0 عند النجاح، و -E2BIG إذا تجاوز الحجم DYNPTR_MAX_SIZE، و -EINVAL إذا لم تكن الأعلام 0.

long bpf_ringbuf_reserve_dynptr(void *ringbuf, u32 size, u64 flags, struct bpf_dynptr *ptr)

الوصف
    احجز size بايت من الحمولة في صوان حلقي ringbuf عبر واجهة dynptr. يجب أن تكون flags هي 0.

    يرجى ملاحظة أنه يجب استدعاء bpf_ringbuf_submit_dynptr أو bpf_ringbuf_discard_dynptr المقابلة على ptr، حتى لو فشل الحجز. يُفرض هذا بواسطة المصدق (verifier).

القيمة المعادة
    0 عند النجاح، أو خطأ سالب في حال الفشل.

void bpf_ringbuf_submit_dynptr(struct bpf_dynptr *ptr, u64 flags)

الوصف
    أرسل عينة الصوان الحلقي المحجوزة، التي يشير إليها data، عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL.

    لمزيد من المعلومات حول flags، يرجى مراجعة 'bpf_ringbuf_submit'.

القيمة المعادة
    لا شيء. ينجح دائماً.

void bpf_ringbuf_discard_dynptr(struct bpf_dynptr *ptr, u64 flags)

الوصف
    انبذ عينة الصوان الحلقي المحجوزة عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL.

    لمزيد من المعلومات حول flags، يرجى مراجعة 'bpf_ringbuf_discard'.

القيمة المعادة
    لا شيء. ينجح دائماً.

long bpf_dynptr_read(void *dst, u64 len, const struct bpf_dynptr *src, u64 offset, u64 flags)

الوصف
    اقرأ len بايت من src إلى dst، بدءًا من الإزاحة offset في src. لا تُستخدم flags حاليًا.

القيمة المعادة
    0 عند النجاح، و -E2BIG إذا تجاوز مجموع offset + len طول بيانات src، و -EINVAL إذا كان src عبارة عن dynptr غير صالح أو إذا لم تكن flags تساوي 0.

long bpf_dynptr_write(const struct bpf_dynptr *dst, u64 offset, void *src, u64 len, u64 flags)

الوصف
    اكتب len بايت من src في dst، بدءًا من الإزاحة offset في dst.

    يجب أن تكون flags هي 0 باستثناء dynptrs من نوع skb.

بالنسبة لـ dynptrs من نوع skb:

•   تُبطل جميع شرائح بيانات dynptr آليًا بعد bpf_dynptr_write(). وذلك لأن الكتابة قد تسحب skb وتغير صوان الحزمة الأساسي.

•   بخصوص flags، يرجى مراجعة الأعلام التي تقبلها bpf_skb_store_bytes().

القيمة المعادة
    0 عند النجاح، و -E2BIG إذا تجاوز مجموع offset + len طول بيانات dst، و -EINVAL إذا كان dst عبارة عن dynptr غير صالح أو إذا كان dst عبارة عن dynptr للقراءة فقط أو إذا كانت flags غير صحيحة. بالنسبة لـ dynptrs من نوع skb، تتوافق الأخطاء الأخرى مع الأخطاء التي تُرجعها bpf_skb_store_bytes().

void *bpf_dynptr_data(const struct bpf_dynptr *ptr, u64 offset, u64 len)

الوصف
    احصل على مؤشر لبيانات dynptr الأساسية.

    يجب أن تكون len قيمة معروفة ثابتة. تُبطل شريحة البيانات المُرجعة متى ما أُبطل dynptr.

    قد لا تستخدم dynptrs من نوع skb و xdp الدالة bpf_dynptr_data. وعليها استخدام bpf_dynptr_slice و bpf_dynptr_slice_rdwr بدلاً من ذلك.

القيمة المعادة
    مؤشر إلى بيانات dynptr الأساسية، أو NULL إذا كان dynptr للقراءة فقط، أو إذا كان dynptr غير صالح، أو إذا كانت الإزاحة والطول خارج الحدود.

s64 bpf_tcp_raw_gen_syncookie_ipv4(struct iphdr *iph, struct tcphdr *th, u32 th_len)

الوصف
    حاول إصدار كعكة SYN للحزمة مع ترويسات IPv4/TCP المقابلة، iph و th، دون الاعتماد على مقبس استماع.

    يشير iph إلى ترويسة IPv4.

    يشير th إلى بداية ترويسة TCP، بينما يحتوي th_len على طول ترويسة TCP (على الأقل sizeof(struct tcphdr)).

القيمة المعادة
    عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EINVAL إذا كان th_len غير صالح.

s64 bpf_tcp_raw_gen_syncookie_ipv6(struct ipv6hdr *iph, struct tcphdr *th, u32 th_len)

الوصف
    حاول إصدار كعكة SYN للحزمة مع ترويسات IPv6/TCP المقابلة، iph و th، دون الاعتماد على مقبس استماع.

    يشير iph إلى ترويسة IPv6.

    يشير th إلى بداية ترويسة TCP، بينما يحتوي th_len على طول ترويسة TCP (على الأقل sizeof(struct tcphdr)).

القيمة المعادة
    عند النجاح، تحمل البتات الـ 32 الأدنى قيمة SYN cookie المُنشأة، تليها 16 بتًا تحمل قيمة MSS لهذا الكوكي، والبتات الـ 16 العليا غير مستخدمة.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EINVAL إذا كان th_len غير صالح.

    -EPROTONOSUPPORT إذا لم يكن CONFIG_IPV6 مدمجًا.

long bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *iph, struct tcphdr *th)

الوصف
    تحقق مما إذا كان iph و th يحتويان على ACK صالح لكعكة SYN دون الاعتماد على مقبس استماع.

    يشير iph إلى ترويسة IPv4.

    يشير th إلى ترويسة TCP.

القيمة المعادة
    0 إذا كان iph و th يمثلان ACK صالحًا لكعكة SYN.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EACCES إذا كانت كعكة SYN غير صالحة.

long bpf_tcp_raw_check_syncookie_ipv6(struct ipv6hdr *iph, struct tcphdr *th)

الوصف
    تحقق مما إذا كان iph و th يحتويان على ACK صالح لكعكة SYN دون الاعتماد على مقبس استماع.

    يشير iph إلى ترويسة IPv6.

    يشير th إلى ترويسة TCP.

القيمة المعادة
    0 إذا كان iph و th يمثلان ACK صالحًا لكعكة SYN.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EACCES إذا كانت كعكة SYN غير صالحة.

    -EPROTONOSUPPORT إذا لم يكن CONFIG_IPV6 مدمجًا.

u64 bpf_ktime_get_tai_ns(void)

الوصف
    ساعة على مستوى النظام غير قابلة للضبط، مُشتقة من وقت ساعة الحائط ولكنها تتجاهل الثواني الكبيسة. لا تتعرض هذه الساعة لانقطاعات أو قفزات إلى الوراء ناتجة عن إدراج بروتوكول وقت الشبكة (NTP) لثوانٍ كبيسة كما يحدث في CLOCK_REALTIME.

    انظر: clock_gettime(CLOCK_TAI)

القيمة المعادة
    الـ ktime الحالي.

long bpf_user_ringbuf_drain(struct bpf_map *map, void *callback_fn, void *ctx, u64 flags)

الوصف
    استنزاف العينات من مخزن حلقة المستخدم المحدد، واستدعاء الاستدعاء المرجعي المقدم لكل عينة من هذا القبيل:

    long (*callback_fn)(const struct bpf_dynptr *dynptr, void *ctx);

    إذا أعاد callback_fn القيمة 0، سيستمر المساعد في محاولة استنزاف العينة التالية، بحد أقصى قدره BPF_MAX_USER_RINGBUF_SAMPLES عينة. إذا كانت القيمة المعادة 1، سيتخطى المساعد بقية العينات ويعود. لا تُستخدم قيم الإعادة الأخرى حاليًا، وسيُرفض من قبل المُتحقق (verifier).

القيمة المعادة
    عدد العينات التي استُنزفت إذا لم يُواجه أي خطأ أثناء الاستنزاف، أو 0 إذا لم توجد عينات في مخزن الحلقة. إذا كان مُنتج مساحة المستخدم ينتظر عبر epoll على هذه الخريطة، واستُنزفت عينة واحدة على الأقل، فسيصلهم إشعار حدث يُعلمهم بتوفر مساحة في مخزن الحلقة. إذا مُررت علامة BPF_RB_NO_WAKEUP إلى هذه الدالة، لن يُرسل إشعار تنبيه. وإذا مُررت علامة BPF_RB_FORCE_WAKEUP، فسيُرسل إشعار تنبيه حتى لو لم تُستنزف أي عينة.

    عند الفشل، تكون القيمة المرجعة واحدة مما يلي:

    -EBUSY إذا كان مخزن الحلقة متنازعًا عليه، وكان سياق استدعاء آخر يستنزف مخزن الحلقة بشكل متزامن.

    -EINVAL إذا كانت مساحة المستخدم لا تتتبع مخزن الحلقة بشكل صحيح بسبب عدم محاذاة موضع المُنتج إلى 8 بايتات، أو عدم محاذاة العينة إلى 8 بايتات، أو عدم مطابقة موضع المُنتج للطول المعلن للعينة.

    -E2BIG إذا حاولت مساحة المستخدم نشر عينة أكبر من حجم مخزن الحلقة، أو عينة لا يمكن احتواؤها داخل struct bpf_dynptr.

void *bpf_cgrp_storage_get(struct bpf_map *map, struct cgroup *cgroup, void *value, u64 flags)

الوصف
    يجلب bpf_local_storage من cgroup.

    من الناحية المنطقية، يمكن اعتباره جلبًا للقيمة من map باستخدام cgroup بصفته key. من هذا المنظور، لا يختلف الاستخدام كثيرًا عن bpf_map_lookup_elem(map, &cgroup) باستثناء أن هذا المساعد يفرض أن يكون المفتاح بنية cgroup وأن تكون الخريطة أيضًا من نوع BPF_MAP_TYPE_CGRP_STORAGE.

    في الواقع، قيمة التخزين المحلي (local-storage) مدمجة مباشرة داخل كائن cgroup نفسه، بدلاً من وجودها في الخريطة BPF_MAP_TYPE_CGRP_STORAGE. عندما تُستعلم قيمة التخزين المحلي لخريطة map معينة على كائن cgroup، ستقوم النواة بإجراء تكرار O(n) على جميع قيم التخزين المحلي النشطة لذلك الكائن cgroup حتى تُعثر على قيمة التخزين المحلي الخاصة بالخريطة map.

    يمكن استخدام flags اختيارية (BPF_LOCAL_STORAGE_GET_F_CREATE) لإنشاء bpf_local_storage جديد إذا لم يكن موجودًا. يمكن استخدام value مع BPF_LOCAL_STORAGE_GET_F_CREATE لتحديد القيمة الأولية لـ bpf_local_storage. إذا كانت value هي NULL، فسيُهيأ bpf_local_storage الجديد بقيمة صفرية.

القيمة المعادة
    يُعاد مؤشر bpf_local_storage عند النجاح.

    NULL إذا لم يُعثر عليه أو إذا حدث خطأ أثناء إضافة bpf_local_storage جديد.

long bpf_cgrp_storage_delete(struct bpf_map *map, struct cgroup *cgroup)

الوصف
    يحذف bpf_local_storage من cgroup.

القيمة المعادة
    0 عند النجاح.

    -ENOENT إذا تعذر العثور على bpf_local_storage.

أمثلة

تتوفر أمثلة لاستخدام معظم مساعدي eBPF المدرجين في صفحة الدليل هذه داخل مصادر نواة لينكس، في المواقع التالية:

•   samples/bpf/

•   tools/testing/selftests/bpf/

الرخصة

يمكن أن يكون لبرامج eBPF رخصة مرتبطة بها، تُمرر مع تعليمات كود البايت إلى النواة عند تحميل البرامج. تنسيق تلك السلسلة النصية مطابق للتنسيق المستخدم في وحدات النواة (يمكن استخدام تراخيص مزدوجة، مثل "Dual BSD/GPL"). بعض الدوال المساعدة لا يمكن الوصول إليها إلا للبرامج المتوافقة مع رخصة جنو العمومية (GNU GPL).

لاستخدام هؤلاء المساعدين، يجب تحميل برنامج eBPF مع تمرير سلسلة الترخيص الصحيحة (عبر attr) إلى استدعاء النظام bpf()، ويُترجم هذا بشكل عام في كود المصدر بلغة C للبرنامج باحتوائه على سطر مشابه لما يلي:

    char ____license[] __attribute__((section("license"), used)) = "GPL";

التنفيذ

صفحة الدليل هذه هي جهد لتوثيق دوال مساعد eBPF الموجودة. ولكن حتى وقت كتابة هذا التقرير، يخضع نظام BPF الفرعي لتطوير مكثف. تُضاف أنواع برامج أو خرائط eBPF جديدة، إلى جانب دوال مساعدة جديدة. تُتاح بعض المساعدات أحيانًا لأنواع برامج إضافية. لذا على الرغم من جهود المجتمع، قد لا تكون هذه الصفحة محدثة. إذا كنت ترغب في التحقق بنفسك من دوال المساعدة الموجودة في نواتك، أو أنواع البرامج التي تدعمها، فإليك بعض الملفات في شجرة النواة التي قد تهمك:

•   include/uapi/linux/bpf.h هو ترويسة BPF الرئيسة. ويحتوي على القائمة الكاملة لجميع الدوال المساعدة، بالإضافة إلى العديد من تعريفات BPF الأخرى بما في ذلك معظم العلامات أو البنى أو الثوابت التي يستخدمها المساعدون.

•   يحتوي net/core/filter.c على تعريف معظم الدوال المساعدة المتعلقة بالشبكة، وقائمة أنواع البرامج التي يمكن استخدامها منها.

•   kernel/trace/bpf_trace.c هو المكافئ لمعظم المساعدين المتعلقين ببرامج التتبع.

•   يحتوي kernel/bpf/verifier.c على الدوال المستخدمة للتحقق من استخدام أنواع صالحة من خرائط eBPF مع دالة مساعدة معينة.

•   يحتوي دليل kernel/bpf/ على ملفات أخرى تُعرف فيها مساعدات إضافية (للمجموعات التحكيمية cgroups، وخرائط المقابس sockmaps، وما إلى ذلك).

•   يمكن استخدام أداة bpftool لسبر مدى توفر الدوال المساعدة على النظام (بالإضافة إلى أنواع البرامج والخرائط المدعومة، وعدد من المعلمات الأخرى). للقيام بذلك، شغّل bpftool feature probe (انظر bpftool-feature(8) للحصول على التفاصيل). أضف الكلمة المفتاحية unprivileged لسرد الميزات المتاحة للمستخدمين غير المتميزين.

    يمكن العثور على التوافق بين الدوال المساعدة وأنواع البرامج بشكل عام في الملفات التي تُعرف فيها الدوال المساعدة. ابحث عن كائنات struct bpf_func_proto وعن الدوال التي تعيدها: تحتوي هذه الدوال على قائمة بالمساعدين الذين يمكن لنوع برنامج معين استدعاؤهم. لاحظ أن لصيقة default: في switch ... case المستخدمة لتصفية المساعدين يمكنها استدعاء دوال أخرى، تسمح هي نفسها بالوصول إلى مساعدين إضافيين. متطلبات رخصة GPL موجودة أيضًا في تلك struct bpf_func_proto.

    يمكن العثور على التوافق بين الدوال المساعدة وأنواع الخرائط في دالة check_map_func_compatibility() في ملف kernel/bpf/verifier.c.

    الدوال المساعدة التي تُبطل الفحوصات على مؤشري data و data_end لمعالجة الشبكة مدرجة في دالة bpf_helper_changes_pkt_data() في ملف net/core/filter.c.

انظر أيضًا

bpf(2), bpftool(8), cgroups(7), ip(8), perf_event_open(2), sendmsg(2), socket(7), tc-bpf(8)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.