gobee

اكتب برامج BPF الخاصة بك بلغة Go، وليس بلغة C. يحوّل gobee مجموعة فرعية صارمة من Go إلى BPF C، ويولّد روابط Go مكتوبة الأنواع لجانب مساحة المستخدم، ويقيّم التحميلات مقابل النواة الجارية.

يملك نظام Go البيئي أدوات مساحة مستخدم صلبة لـ BPF. أما الجانب النووي فكان دائمًا ينتهي بعبارة «الآن اكتب برنامجك بلغة C». جلبت Aya دعم eBPF إلى Rust بكتابة خلفية BPF جديدة داخل rustc. يصل gobee إلى ذلك بطريقة مختلفة: عبر التحويل إلى C وإعادة استخدام خلفية clang الناضجة.

ملف Go يدخل، برنامج BPF يخرج

نقطة تتبع تدفّق كل execve إلى مساحة المستخدم عبر ringbuf:

//go:build ignore

package main

import "github.com/boratanrikulu/gobee/bpf"

//bpf:license GPL

type Event struct {
    Pid  uint32
    Comm [16]byte
}

var Events = bpf.RingBuf[Event]{
    MaxEntries: 4096,
}

//bpf:section tracepoint/syscalls/sys_enter_execve
func OnExec(ctx *bpf.ExecveEnterCtx) bpf.TpReturn {
    e, ok := Events.Reserve()
    if !ok {
        return bpf.TpOk
    }
    e.Pid = bpf.GetCurrentPid()
    bpf.GetTaskComm(&e.Comm)
    Events.Submit(e)
    return bpf.TpOk
}

func main() {}

// Code generated by gobee. DO NOT EDIT.

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_core_read.h>

char _license[] SEC("license") = "GPL";

struct Event {
    __u32 Pid;
    __u8 Comm[16];
};

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 4096);
} Events SEC(".maps");

SEC("tracepoint/syscalls/sys_enter_execve")
int OnExec(struct trace_event_raw_sys_enter *ctx) {
    struct Event *e = bpf_ringbuf_reserve(
        &Events, sizeof(struct Event), 0);
    if (!e) {
        return 0;
    }
    e->Pid = (__u32)(
        bpf_get_current_pid_tgid() >> 32);
    bpf_get_current_comm(&e->Comm, 16);
    bpf_ringbuf_submit(e, 0);
    return 0;
}

يُنتج gobee translate --bindings-dir ./bpf ./bpf/src كلا الملفين، بالإضافة إلى خريطة مصدر (events.bpf.c.map) بحيث تُرجَع أخطاء المدقق إلى أسطر Go، وملف روابط مكتوب الأنواع (bpf/events_bindings.go) بحيث يكتب برنامج تشغيل مساحة المستخدم objs.Events وobjs.AttachOnExec() ويفكّ ترميز حمولات ringbuf مباشرة إلى bpf.Event (نفس البنية التي تراها أعلاه، معاد نشرها في Go) بدلاً من عمليات البحث النصية coll.Programs["..."].

لغة C قابلة للقراءة عمدًا. إذا أصدر gobee شيئًا غريبًا، يمكنك رؤيته. لدمج tracepoints + kprobes + XDP في ملف ثنائي واحد، راجع example/sysmon/.

كيف يقارن

إذا كنت تعمل أصلًا ضمن سير عمل C / libbpf، فإن gobee لا يحاول استبداله كليًا. إنه للحالات التي تريد فيها الجانب النووي وجانب مساحة المستخدم وخط البناء كلها داخل وحدة Go واحدة.

ما المدعوم اليوم

راجع docs/status.md للمصفوفة الكاملة (مجموعة فرعية من Go، والعبارات، والتعبيرات، وكل مساعد، وكل نوع خريطة، وكل توجيه). نظرة سريعة:

ماذا يفعل gobee

• يحوّل مجموعة فرعية من Go إلى BPF C (ويشغّل go/types على مدخلاتك أولاً، بحيث تظهر الاستخدامات الخاطئة عند file:line:col).
• يولّد <Stem>_bindings.go مكتوب الأنواع بجوار .bpf.c: bpf.LoadCounter(spec)، وobjs.PerIface.Lookup(...)، وobjs.AttachAll(ifindex)، بالإضافة إلى أنواع بنى جانب النواة والثوابت معاد نشرها في Go.
• يعلّم تلقائيًا *ebpf.VerifierError الصادر من LoadAndAssign بمواضع مصدر Go، دون الحاجة لأنبوب يدوي عبر gobee diagnose.
• يشغّل bpfvet داخل Load<Stem> بحيث تفشل النوى القديمة بسرعة مع bpf program needs kernel >= 5.8, host is 5.4.
• يقدّم نحو 200 كعب Go مكتوب الأنواع لمجموعة مساعدات libbpf v1.5.0، بالإضافة إلى دوال مساعدة معرفة من المستخدم تُصدر كـ .

ما لن يفعله gobee

• لن يستبدل clang. خلفية clang لـ BPF تمنحنا CO-RE وBTF وتوليد كود صديق للمدقق مجانًا. إعادة تنفيذ ذلك تكلف سنوات ولا تضيف شيئًا.
• لن يستبدل cilium/ebpf. الروابط المولَّدة تقع فوقه.
• لن يخفي BPF. المجموعة الفرعية من Go تطابق تعابير C الخاصة بـ BPF بنسبة 1:1. إذا كنت تعرف BPF، فإن gobee مجرد سكر نحوي رقيق. إذا لم تكن تعرفه، فالدليل ما يزال قراءة إلزامية.
• لن يشغّل clang نيابة عنك. الترجمة والتضمين والتحميل تبقى ملكًا للمستخدم. نفس نمط bpf2go.

لماذا التحويل، وليس توليد BPF مباشرة

gc، مترجم Go، لا يملك خلفية BPF مبنية على LLVM. إضافة واحدة مشروع مترجم يستغرق سنوات. rustc مبني على LLVM ولهذا تعمل Aya. لذا يُصدر gobee لغة C ويعيد استخدام خلفية clang لـ BPF، مما يمنحنا توليد كود ناضج وBTF وترحيلات CO-RE مجانًا.

بدء سريع

go install github.com/boratanrikulu/gobee/cmd/gobee@latest

cd example/helloworld
make build                     # gobee translate, clang, go build
sudo ./helloworld eth0

ستحتاج إلى clang مع هدف BPF. على Linux، يكون ذلك حزمة التوزيعة؛ وعلى macOS، brew install llvm. المحوِّل نفسه مكتوب بلغة Go خالصة ويعمل في أي مكان.

هيكل المشروع (النموذجي)

yourproject/
├── bpf/                      # Go package, importable from anywhere in your project
│   ├── embed_amd64.go        # //go:embed bin/x86/your.bpf.o
│   ├── embed_arm64.go
│   ├── your_bindings.go      # generated by gobee
│   ├── bin/{x86,arm64}/your.bpf.o
│   └── src/                  # not a Go package; clang lives here
│       ├── your.go           # //go:build ignore: BPF source
│       ├── your.bpf.c        # generated
│       ├── Makefile          # clang per arch
│       └── vmlinux.h         # vendored BTF dump
├── main.go                   # imports yourproject/bpf
└── Makefile

يحافظ هذا التقسيم على bpf/ كحزمة Go نظيفة قابلة للاستيراد (يرفض Go ملفات .c في الحزم غير cgo). تعيش مصادر النواة ومخرجات clang على مستوى واحد أعمق داخل bpf/src/.

أمثلة

• example/helloworld/: عدّاد حزم XDP المعياري، نحو 40 سطرًا من BPF ونحو 80 سطرًا لمساحة المستخدم.
• example/sysmon/: XDP ونقطتا تتبع وkprobe في ملف ثنائي واحد، تتشارك ringbuf للأحداث. يُظهر سياقات مكتوبة الأنواع لكل استدعاء نظام، ودوال مساعدة معرفة من المستخدم، واختصار AttachAll.

CI

يشغّل GitHub Actions أربع طبقات عند كل دفع:

1. go test وgo vet واختبارات golden للمحوّل
2. مصفوفة تغطية: لكل نوع خريطة وكل نوع //bpf:section مثال واحد على الأقل
3. ترجمة clang لكل مثال مُنتقى، ثم تقرير قابلية نقل bpfvet
4. قبول المدقق بنواة حقيقية: ebpf.NewCollectionWithOptions على كل .bpf.o (منفّذ Ubuntu 24.04، نواة 6.x)

التوثيق

• docs/design.md: العمارة والأساس المنطقي
• docs/go-subset.md: صيغة Go المقبولة في ملفات مصدر BPF
• docs/directives.md: مرجع //bpf:*
• docs/status.md: مصفوفة الدعم (المصدر الوحيد للحقيقة)

سلسلة الأدوات

• ملف gobee الثنائي يُبنى في أي مكان (Go خالص، بدون CGO).
• ترجمة .bpf.o تتطلب clang مع هدف BPF. clang المرفق مع Apple لا يتضمن ذلك؛ على macOS استخدم brew install llvm أو ابنِ داخل جهاز افتراضي Linux.
• تشغيل المخرجات يتطلب Linux على arm64 أو amd64.

مصادر الإلهام

• Solod: المحوّل من Go إلى C الذي أثبت نجاح هذا النمط.
• Aya: إطار eBPF بلغة Rust الذي يسعى gobee إلى بلوغ مستوى سهولة استخدامه.

الترخيص

MIT. انظر LICENSE.

Copyright (c) 2026 Bora Tanrikulu <[email protected]>