الوصف

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

الوصف

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

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

الـ ktime الحالي.

الوصف

هذا المساعد هو وسيلة "شبيهة بـ 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>

فيما سبق:

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

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

الوصف

أعد حساب مجموع فحص الطبقة 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

استرجع الـ 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 المبدئي غير المضبوط.

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

جلب بيانات النفق الوصفية (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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

قراءة قيمة عداد أحداث الأداء (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() للحصول على التفاصيل.

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

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

الوصف

إعادة توجيه الحزمة إلى جهاز شبكة آخر بالفهرس 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 عند الخطأ.

الوصف

جلب المجال (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 إذا لم يُعثر على أي منها.

الوصف

كتابة كتلة 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 أيضًا، حيث تسمح بتمرير البيانات إلى مستمعي فضاء المستخدم. يمكن أن تكون البيانات:

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

حجم بيانات الخيار التي جُلبت.

الوصف

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

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

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

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

الوصف

تغيير بروتوكول 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

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

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

الوصف

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

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

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

الوصف

استعد خبيئة الحزمة، 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 بت.

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

اسحب البيانات غير الخطية في حالة كون 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

الوصف

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

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

void.

الوصف

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

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

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

الوصف

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

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

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

0

الوصف

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

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

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

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

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

الوصف

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

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

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

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

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

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

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

الوصف

أعِد توجيه الحزمة إلى نقطة النهاية التي تشير إليها 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 عند الخطأ.

الوصف

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

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

SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

الوصف

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

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

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

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

الوصف

اضبط العنوان الذي يشير إليه 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

يقرأ قيمة عداد أحداث الأداء (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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

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

0

الوصف

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

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

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

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

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

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

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

الوصف

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

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

SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

الوصف

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

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

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

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

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

0

الوصف

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

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

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

0

الوصف

لسياسات المقبس، يسحب البيانات غير الخطية من مساحة المستخدم لـ 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

يربط المقبس المرتبط بـ 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

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

الوصف

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

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

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

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

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

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

الوصف

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

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

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

الوصف

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

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

SK_PASS عند النجاح، أو SK_DROP عند الخطأ.

الوصف

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

يمكن استدعاء أنواع *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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

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

0

الوصف

يُستخدم هذا المساعد في البرامج التي تنفذ فك ترميز الأشعة تحت الحمراء، للإبلاغ عن ضغطة مفتاح فُك ترميزها بنجاح مع 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

الوصف

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

الوصف

يرجع معرف 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 في حال تعذر جلب المعرف.

الوصف

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

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

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

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

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

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

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

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

الوصف

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

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

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

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

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

0

الوصف

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

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

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

0

الوصف

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

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

0

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

الوصف

يبحث عن مقبس 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[] باستخدام تجزئة المجموعة.

الوصف

التحقق مما إذا كان 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 صالحًا، أو قيمة خطأ سالبة خلاف ذلك.

الوصف

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

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

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

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

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

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

الوصف

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

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

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

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

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

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

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

الوصف

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

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

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

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

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

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

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

الوصف

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

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

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

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

0 عند النجاح.

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

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

الوصف

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

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

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

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

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

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

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

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

الوصف

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

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

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

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

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

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

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

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

الوصف

الحصول على 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 جديد.

الوصف

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

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

0 عند النجاح.

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

الوصف

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

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

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

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

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

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

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

الوصف

محاولة إصدار 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

الوصف

كتابة كتلة 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

الوصف

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

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

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

الوصف

نسخ سلسلة نصية منتهية بـ 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 الختامي. وعند الخطأ، يُرجع قيمة سالبة.

الوصف

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

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

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

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

الوصف

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

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

الـ jiffies بـ 64 بت

الوصف

بالنسبة لبرنامج 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 إذا كانت المعمارية لا تدعم سجلات الفروع.

الوصف

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

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

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

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

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

الوصف

كتابة كتلة 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 عند النجاح، أو خطأ سالب في حال الفشل.

الوصف

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

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

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

الوصف

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

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

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

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

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

الوصف

المساعد محمل بشكل زائد اعتماداً على نوع برنامج 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.

الوصف

المساعد محمل بشكل زائد اعتماداً على نوع برنامج 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 مزيجاً من القيم التالية:

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

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

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

الوصف

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

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

الـ ktime الحالي.

الوصف

يستخدم 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 إذا حدث طفحان: ستتم محاولة معالجة الكائن نفسه مرة أخرى.

الوصف

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

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

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

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

الوصف

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

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

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

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

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

الوصف

أعد معرف 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 في حال تعذر جلب المعرف.

الوصف

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

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

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

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

الوصف

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

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

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

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

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

الوصف

غيّر مستوى الاختبار التحسبي للـ 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.

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

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

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

الوصف

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

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

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

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

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

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

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

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

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

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

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

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

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

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

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

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

الوصف

تحميل خيار الترويسة. دعم قراءة خيار ترويسة 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 بابتين على الأقل، وهو الحد الأدنى لحجم خيار الترويسة.

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

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

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

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

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

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

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

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

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

الوصف

تخزين خيار الترويسة. ستُنسخ البيانات من المخزن المؤقت 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 الحالي.

الوصف

حجز 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 الحالي.

الوصف

الحصول على 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 جديد.

الوصف

حذف bpf_local_storage من inode.

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

0 عند النجاح.

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

الوصف

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

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

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

الوصف

قراءة عدد size من البايتات من عنوان مساحة المستخدم user_ptr وتخزين البيانات في dst. هذا غلاف لـ copy_from_user().

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

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

الوصف

استخدام 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 للكتابة إلى seq_write تمثيل نصي لـ ptr->ptr، باستخدام ptr->type_id كما هو الحال في bpf_snprintf_btf(). الـ flags مطابقة لتلك المستخدمة في bpf_snprintf_btf.

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

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

الوصف

راجع bpf_get_cgroup_classid() للوصف الرئيسي. يختلف هذا المساعد عن bpf_get_cgroup_classid() في أن فئة net_cls الخاصة بـ cgroup v1 تُسترجع فقط من المقبس المرتبط بـ skb بدلًا من العملية الحالية.

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

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

الوصف

توجيه الحزمة إلى جهاز شبكة آخر بالفهرس 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 عند الخطأ.

الوصف

أخذ مؤشر إلى 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 غير صالح.

الوصف

أخذ مؤشر إلى ksym لكل معالج، percpu_ptr، وإعادة مؤشر إلى متغير النواة لكل معالج على هذا المعالج. راجع وصف 'ksym' في bpf_per_cpu_ptr().

يتمتع bpf_this_cpu_ptr() بنفس دلالات this_cpu_ptr() في النواة. وبخلاف bpf_per_cpu_ptr()، فإنه لا يعيد NULL أبدًا.

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

مؤشر يشير إلى متغير النواة لكل معالج على هذا المعالج.

الوصف

توجيه الحزمة إلى جهاز شبكة آخر بالفهرس 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 عند الخطأ.

الوصف

الحصول على 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 جديد.

الوصف

حذف bpf_local_storage من task.

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

0 عند النجاح.

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

الوصف

إعادة مؤشر BTF للمهمة "الحالية". يمكن استخدام هذا المؤشر أيضًا في المساعدات التي تقبل ARG_PTR_TO_BTF_ID من نوع task_struct.

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

مؤشر للمهمة الحالية.

الوصف

اضبط خيارات معينة أو امسحها في bprm:

‏BPF_F_BPRM_SECUREEXEC لضبط بت التنفيذ الآمن (secureexec) الذي يضبط AT_SECURE auxv لـ glibc. ويُمسح البت إذا لم يُحدد العلم.

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

‏-EINVAL إذا مُررت flags غير صالحة، وصفر فيما عدا ذلك.

الوصف

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

انظر: clock_gettime(CLOCK_MONOTONIC_COARSE)

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

الـ ktime الحالي.

الوصف

يُعيد وسم IMA المخزن لـ inode (إذا كان متاحًا). إذا كان الوسم أكبر من size، فستُنسخ بايتات بقدر size فقط إلى dst

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

يُعاد hash_algo عند النجاح، أو -EOPNOTSUPP إذا كانت IMA معطلة أو -EINVAL إذا مُررت معاملات غير صالحة.

الوصف

إذا كان الملف المعطى يمثل مقبسًا، فيُعيد المقبس المرتبط به.

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

مؤشر إلى struct socket عند النجاح أو NULL إذا لم يكن الملف مقبسًا.

الوصف

تحقق من حجم الحزمة للتأكد من عدم تجاوزه لوحدة النقل القصوى (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 مزيجًا من قيمة واحدة أو أكثر من القيم التالية:

عند الإرجاع، يحتوي مؤشر mtu_len على قيمة MTU لجهاز الشبكة. تذكر أن وحدة MTU المضبوطة لجهاز الشبكة هي حجم L3، وهو ما يُعاد هنا بينما يعمل طول XDP و TC في L2. يأخذ المساعد هذا في الحسبان من أجلك، لكن تذكر ذلك عند استخدام قيمة MTU في كود BPF الخاص بك.

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

تعيد انتهاكات MTU قيمًا موجبة، ولكنها تملأ أيضًا قيمة MTU في مؤشر mtu_len، حيث يمكن أن يكون ذلك مطلوبًا لتنفيذ معالجة PMTU:

الوصف

لكل عنصر في 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 غير صالحة.

الوصف

يُخرج سلسلة نصية إلى مخزن 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 مشغولاً.

الوصف

نفذ استدعاء نظام bpf بالمعاملات المعطاة.

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

نتيجة استدعاء نظام.

الوصف

ابحث عن نوع BTF بالاسم والنوع المعطى في vmlinux BTF أو في BTFs للوحدة.

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

يُعيد btf_id و btf_obj_fd في الـ 32 بت السفلى والعليا.

الوصف

نفذ استدعاء نظام الإغلاق لـ FD المعطى.

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

نتيجة استدعاء نظام.

الوصف

هيئ الميقاتية. أول 4 بتات من flags تحدد clockid. يُسمح فقط بـ CLOCK_MONOTONIC و CLOCK_REALTIME و CLOCK_BOOTTIME. جميع البتات الأخرى من flags محجوزة. سيرفض المدقق البرنامج إذا لم تكن الميقاتية timer من نفس الخريطة map.

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

0 عند النجاح. -EBUSY إذا كانت الميقاتية timer مهيأة بالفعل. -EINVAL إذا مُررت أعلام flags غير صالحة. -EPERM إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر.

الوصف

اضبط الميقاتية لاستدعاء دالة callback_fn الساكنة.

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

0 عند النجاح. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا. -EPERM إذا كانت الميقاتية في خريطة ليس لها أي مراجع مستخدم. يجب أن يحتفظ مساحة المستخدم إما بواصف ملف لخريطة بها ميقاتيات أو يثبت هذه الخريطة في bpffs. عند إلغاء تثبيت الخريطة أو إغلاق واصف الملف، ستُلغى جميع الميقاتيات في الخريطة وتُحرر.

الوصف

اضبط انتهاء صلاحية الميقاتية بعد 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 أن يكون واحدًا مما يلي:

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

0 عند النجاح. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا أو مُررت أعلام flags غير صالحة.

الوصف

ألفِ الميقاتية وانتظر انتهاء callback_fn إذا كانت تعمل.

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

0 إذا لم تكن الميقاتية نشطة. 1 إذا كانت الميقاتية نشطة. -EINVAL إذا لم تُهيأ الميقاتية timer بـ bpf_timer_init() سابقًا. -EDEADLK إذا حاولت callback_fn استدعاء bpf_timer_cancel() على ميقاتيتها الخاصة مما قد يؤدي إلى طريق مسدود (deadlock) بخلاف ذلك.

الوصف

احصل على عنوان الدالة المتتبعة (لبرامج التتبع و kprobe).

عند استدعائه لبرنامج kprobe متصل كـ uprobe فإنه يعيد عنوان المسبار لكل من uprobe الدخول والعودة.

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

عنوان الدالة المتتبعة لـ kprobe. وصفر لـ kprobes الموضوعة داخل الدالة (ليس عند الدخول). وعنوان المسبار لـ uprobe و return uprobe.

الوصف

احصل على قيمة bpf_cookie المقدمة (اختياريًا) أثناء اتصال البرنامج. قد تختلف لكل اتصال فردي، حتى لو كان برنامج BPF نفسه هو نفسه. يتوقع سياق برنامج BPF كأول معامل ctx.

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

القيمة التي حددها المستخدم عند إنشاء رابط BPF/وقت الاتصال أو 0، إذا لم تُحدد.

الوصف

احصل على struct pt_regs المرتبط بـ task.

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

مؤشر إلى struct pt_regs.

الوصف

احصل على تتبع الفرع من محركات العتاد مثل Intel LBR. يُوقف محرك العتاد بعد فترة وجيزة من استدعاء المساعد. لذلك، يحتاج المستخدم إلى تصفية مدخلات الفروع بناءً على حالة الاستخدام الفعلية. لالتقاط تتبع الفرع قبل نقطة انطلاق برنامج BPF، يجب استدعاء المساعد في بداية برنامج BPF.

تُخزن البيانات كـ struct perf_branch_entry في مخزن المخرجات المؤقت entries. المعامل size هو حجم entries بالبايت. المعامل flags محجوز حاليًا ويجب أن يكون صفراً.

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

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

‏-EINVAL إذا لم تكن flags صفراً.

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

الوصف

يسلك سلوك مساعد bpf_trace_printk()، ولكنه يأخذ مصفوفة من u64 لتنسيقها ويمكنه التعامل مع المزيد من معاملات التنسيق كنتيجة لذلك.

يجب استخدام المعاملات كما في المساعد bpf_seq_printf().

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

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

الوصف

حول مؤشر sk ديناميكيًا إلى مؤشر unix_sock.

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

احصل على عنوان رمز النواة، ويُعاد في res. يُضبط res إلى 0 إذا لم يُعثر على الرمز.

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

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

‏-EINVAL إذا لم تكن flags صفراً.

‏-EINVAL إذا لم يكن حجم السلسلة name هو نفس حجم name_sz.

‏-ENOENT إذا لم يُعثر على الرمز.

‏-EPERM إذا لم يملك المستدعِي إذنًا للحصول على عنوان النواة.

الوصف

البحث عن 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 غير صالحة.

الوصف

لعدد 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 الحد الأقصى لعدد الحلقات.

الوصف

إجراء strncmp() بين s1 و s2. لا يلزم أن يكون s1 منتهيًا بـ null، و s1_sz هو أقصى حجم تخزين لـ s1. يجب أن يكون s2 سلسلة للقراءة فقط.

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

عدد صحيح أقل من، أو يساوي، أو أكبر من الصفر إذا وُجد أن أول s1_sz بايت من s1 أقل من، أو تطابق، أو أكبر من s2.

الوصف

الحصول على سجل المعامل رقم n (بدءًا من الصفر) للدالة المتعقبة (لبرامج التعقب) ويُعاد في value.

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

0 عند النجاح. -EINVAL إذا كان n >= عدد سجلات المعاملات للدالة المتعقبة.

الوصف

الحصول على قيمة الإعادة للدالة المتعقبة (لبرامج التعقب) في value.

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

0 عند النجاح. -EOPNOTSUPP لبرامج التعقب بخلاف BPF_TRACE_FEXIT أو BPF_MODIFY_RETURN.

الوصف

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

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

عدد سجلات الوسائط للدالة المقتفاة.

الوصف

احصل على قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا.

هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno.

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

قيمة إرجاع برنامج BPF.

الوصف

اضبط قيمة إرجاع برنامج BPF التي ستُعاد إلى الطبقات العليا.

هذا المساعد مدعوم حاليًا بواسطة برامج cgroup وفقط عبر الخطافات (hooks) حيث تُعاد قيمة إرجاع برنامج BPF إلى فضاء المستخدم عبر errno.

لاحظ وجود الحالة الحدية التالية حيث يصدر البرنامج خطأً عبر bpf_set_retval لكنه يشير إلى النجاح عبر 'return 1':

في هذه الحالة، ستستخدم قيمة إرجاع برنامج BPF قيمة المساعد -EPERM. يظل هذا صحيحًا بالنسبة لـ cgroup/bind{4,6} التي تدعم حالة النجاح الإضافية 'return 3'.

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

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

الوصف

احصل على الحجم الكلي لصوان xdp معطى (المنطقة الخطية والمفصحة)

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

الحجم الكلي لصوان xdp معطى.

الوصف

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

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

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

الوصف

خزّن len من البايتات من الصوان buf في الإطار المرتبط بـ xdp_md، عند الإزاحة offset.

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

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

الوصف

اقرأ size بايت من عنوان فضاء المستخدم user_ptr في فضاء عناوين tsk، ويخزن البيانات في dst. لا تُستخدم flags حاليًا ووُفرت للتوسع المستقبلي. لا يمكن استخدام هذا المساعد إلا بواسطة البرامج القابلة للنوم.

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

0 عند النجاح، أو خطأ سالب في حال الفشل. عند الخطأ، يُصفر الصوان dst.

الوصف

غيّر __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 لبروتوكول غير مدعوم.

الوصف

يُرجع بصمة (hash) IMA المحسوبة لـ file. إذا كانت البصمة أكبر من size، فسيُنسخ size بايت فقط إلى dst

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

يُرجع hash_algo عند النجاح، أو -EOPNOTSUPP إذا فشل حساب البصمة، أو -EINVAL إذا مُررت وسائط غير صالحة.

الوصف

بادل kptr عند المؤشر dst بـ ptr، وأرجع القيمة القديمة. يمكن لـ dst أن يكون قيمة خريطة أو kptr محلي. يمكن لـ ptr أن يكون NULL، وإلا فيجب أن يكون مؤشرًا مرجعيًا سيُحرر عند استدعاء هذا المساعد.

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

القيمة القديمة لـ kptr (والتي يمكن أن تكون NULL). المؤشر المُرجع، إن لم يكن NULL، هو مرجع يجب تحريره باستخدام دالة التحرير المقابلة له، أو نقله إلى خريطة BPF قبل خروج البرنامج.

الوصف

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

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

قيمة الخريطة المرتبطة بـ key على وحدة المعالجة cpu، أو NULL إذا لم يُعثر على مدخل أو كانت وحدة المعالجة المركزية cpu غير صالحة.

الوصف

حوّل (cast) مؤشر sk حركيًا إلى مؤشر mptcp_sock.

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

sk إذا كان التحويل صالحاً، وإلا فإنه NULL.

الوصف

احصل على dynptr إلى الذاكرة المحلية data.

يجب أن يكون data مؤشرًا لقيمة خريطة. الحجم الأقصى size المدعوم هو DYNPTR_MAX_SIZE. لا تُستخدم flags حاليًا.

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

0 عند النجاح، و -E2BIG إذا تجاوز الحجم DYNPTR_MAX_SIZE، و -EINVAL إذا لم تكن الأعلام 0.

الوصف

احجز size بايت من الحمولة في صوان حلقي ringbuf عبر واجهة dynptr. يجب أن تكون flags هي 0.

يرجى ملاحظة أنه يجب استدعاء bpf_ringbuf_submit_dynptr أو bpf_ringbuf_discard_dynptr المقابلة على ptr، حتى لو فشل الحجز. يُفرض هذا بواسطة المصدق (verifier).

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

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

الوصف

أرسل عينة الصوان الحلقي المحجوزة، التي يشير إليها data، عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL.

لمزيد من المعلومات حول flags، يرجى مراجعة 'bpf_ringbuf_submit'.

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

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

الوصف

انبذ عينة الصوان الحلقي المحجوزة عبر واجهة dynptr. لا يقوم هذا بأي عملية إذا كان dynptr غير صالح أو NULL.

لمزيد من المعلومات حول flags، يرجى مراجعة 'bpf_ringbuf_discard'.

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

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

الوصف

اقرأ len بايت من src إلى dst، بدءًا من الإزاحة offset في src. لا تُستخدم flags حاليًا.

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

0 عند النجاح، و -E2BIG إذا تجاوز مجموع offset + len طول بيانات src، و -EINVAL إذا كان src عبارة عن dynptr غير صالح أو إذا لم تكن flags تساوي 0.

الوصف

اكتب len بايت من src في dst، بدءًا من الإزاحة offset في dst.

يجب أن تكون flags هي 0 باستثناء dynptrs من نوع skb.

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

0 عند النجاح، و -E2BIG إذا تجاوز مجموع offset + len طول بيانات dst، و -EINVAL إذا كان dst عبارة عن dynptr غير صالح أو إذا كان dst عبارة عن dynptr للقراءة فقط أو إذا كانت flags غير صحيحة. بالنسبة لـ dynptrs من نوع skb، تتوافق الأخطاء الأخرى مع الأخطاء التي تُرجعها bpf_skb_store_bytes().

الوصف

احصل على مؤشر لبيانات dynptr الأساسية.

يجب أن تكون len قيمة معروفة ثابتة. تُبطل شريحة البيانات المُرجعة متى ما أُبطل dynptr.

قد لا تستخدم dynptrs من نوع skb و xdp الدالة bpf_dynptr_data. وعليها استخدام bpf_dynptr_slice و bpf_dynptr_slice_rdwr بدلاً من ذلك.

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

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

الوصف

حاول إصدار كعكة SYN للحزمة مع ترويسات IPv4/TCP المقابلة، iph و th، دون الاعتماد على مقبس استماع.

يشير iph إلى ترويسة IPv4.

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

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

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

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

-EINVAL إذا كان 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 مدمجًا.

الوصف

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

يشير iph إلى ترويسة IPv4.

يشير th إلى ترويسة TCP.

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

0 إذا كان iph و th يمثلان ACK صالحًا لكعكة SYN.

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

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

الوصف

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

يشير iph إلى ترويسة IPv6.

يشير th إلى ترويسة TCP.

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

0 إذا كان iph و th يمثلان ACK صالحًا لكعكة SYN.

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

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

-EPROTONOSUPPORT إذا لم يكن CONFIG_IPV6 مدمجًا.

الوصف

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

انظر: clock_gettime(CLOCK_TAI)

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

الـ ktime الحالي.

الوصف

استنزاف العينات من مخزن حلقة المستخدم المحدد، واستدعاء الاستدعاء المرجعي المقدم لكل عينة من هذا القبيل:

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.

الوصف

يجلب 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 جديد.

الوصف

يحذف bpf_local_storage من cgroup.

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

0 عند النجاح.

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

char ____license[] __attribute__((section("license"), used)) = "GPL";