gobee

Scrivi i tuoi programmi BPF in Go, non in C. gobee transpila un sottoinsieme rigoroso di Go in BPF C, genera binding Go tipizzati per il lato userspace e controlla i load rispetto al kernel in esecuzione.

L'ecosistema Go ha strumenti userspace solidi per BPF. Il lato kernel si è sempre concluso con "ora scrivi il tuo programma in C." Aya ha portato eBPF su Rust scrivendo un nuovo backend BPF in rustc. gobee ci arriva in un altro modo: transpilando in C e riusando il backend maturo di clang.

Un file Go in ingresso, un programma BPF in uscita

Un tracepoint che invia in streaming ogni execve allo userspace tramite un 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 produce entrambi i file, più una sourcemap (events.bpf.c.map) così gli errori del verifier vengono mappati sulle righe Go e un file di binding tipizzati (bpf/events_bindings.go) così il driver userspace scrive objs.Events, objs.AttachOnExec() e decodifica i payload del ringbuf direttamente in bpf.Event (la stessa struct che vedi sopra, ripubblicata in Go) invece di lookup coll.Programs["..."] tipizzati come stringhe.

Il C è leggibile di proposito. Se gobee emette qualcosa di strano, puoi vederlo. Per tracepoint + kprobe + XDP combinati in un unico binario, vedi example/sysmon/.

Come si confronta

Se sei già in un workflow C / libbpf, gobee non cerca di sostituirlo del tutto. È pensato per i casi in cui vuoi il lato kernel, il lato userspace e la pipeline di build tutti in un unico modulo Go.

Cosa è supportato oggi

Vedi docs/status.md per la matrice completa (sottoinsieme di Go, statement, espressioni, ogni helper, ogni tipo di mappa, ogni direttiva). Vista rapida:

Cosa fa gobee

• Transpila un sottoinsieme di Go in BPF C (ed esegue go/types sul tuo input prima, così gli usi errati emergono a file:line:col).
• Genera un <Stem>_bindings.go tipizzato accanto al .bpf.c: bpf.LoadCounter(spec), objs.PerIface.Lookup(...), objs.AttachAll(ifindex), più i tuoi tipi di struct lato kernel e le costanti ripubblicati in Go.
• Annota automaticamente *ebpf.VerifierError di LoadAndAssign con posizioni nel sorgente Go, senza bisogno di pipe manuale verso gobee diagnose.
• Esegue bpfvet all'interno di Load<Stem> così i kernel vecchi falliscono rapidamente con bpf program needs kernel >= 5.8, host is 5.4.

Cosa gobee non farà

• Sostituire clang. Il backend BPF di clang ci dà gratuitamente CO-RE, BTF e codegen amico del verifier. Reimplementarlo costa anni e non porta alcun vantaggio.
• Sostituire cilium/ebpf. I binding generati si appoggiano su di esso.
• Nascondere BPF. Il sottoinsieme di Go mappa 1:1 agli idiomi di BPF C. Se conosci BPF, gobee è zucchero sottile. Se non lo conosci, il manuale resta comunque lettura obbligatoria.
• Eseguire clang al posto tuo. Compilazione, embedding e load restano a carico dell'utente. Stesso schema di bpf2go.

Perché transpilare, invece di generare BPF direttamente

gc, il compilatore Go, non ha un backend BPF basato su LLVM. Aggiungerne uno è un progetto di compilatore pluriennale. rustc è costruito su LLVM ed è per questo che Aya funziona. Quindi gobee emette C e riusa il backend BPF di clang, che ci dà gratuitamente codegen maturo, BTF e rilocazioni CO-RE.

Avvio rapido

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

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

Ti servirà clang con il target BPF. Su Linux è il pacchetto della distribuzione; su macOS, brew install llvm. Il transpiler stesso è Go puro e gira ovunque.

Struttura del progetto (tipica)

yourproject/
├── bpf/                      # pacchetto Go, importabile da qualsiasi punto del progetto
│   ├── embed_amd64.go        # //go:embed bin/x86/your.bpf.o
│   ├── embed_arm64.go
│   ├── your_bindings.go      # generato da gobee
│   ├── bin/{x86,arm64}/your.bpf.o
│   └── src/                  # non è un pacchetto Go; qui vive clang
│       ├── your.go           # //go:build ignore: sorgente BPF
│       ├── your.bpf.c        # generato
│       ├── Makefile          # clang per architettura
│       └── vmlinux.h         # dump BTF venduto
├── main.go                   # importa yourproject/bpf
└── Makefile

La separazione mantiene bpf/ un pacchetto Go pulito e importabile (Go rifiuta i file .c nei pacchetti non-cgo). I sorgenti kernel e gli artefatti di clang vivono un livello più in basso in bpf/src/.

Esempi

• example/helloworld/: il canonico contatore di pacchetti XDP, ~40 righe di BPF, ~80 righe di userspace.
• example/sysmon/: XDP, due tracepoint e un kprobe in un unico binario, che condividono un ringbuf per gli eventi. Dimostra contesti tipizzati per syscall, funzioni helper definite dall'utente e la scorciatoia AttachAll.

CI

GitHub Actions esegue quattro livelli a ogni push:

1. go test, go vet, golden test del transpiler
2. Matrice di copertura: ogni tipo di mappa e ogni tipo di //bpf:section ha almeno un esempio
3. Compilazione con clang di ogni esempio curato, poi report di portabilità di bpfvet
4. Accettazione del verifier su kernel reale: ebpf.NewCollectionWithOptions su ogni .bpf.o (runner Ubuntu 24.04, kernel 6.x)

Documentazione

• docs/design.md: architettura e motivazioni
• docs/go-subset.md: sintassi Go accettata nei file sorgente BPF
• docs/directives.md: riferimento //bpf:*
• docs/status.md: matrice di supporto (unica fonte di verità)

Toolchain

• Il binario gobee compila ovunque (Go puro, nessun CGO).
• Compilare .bpf.o richiede clang con il target BPF. Il clang incluso da Apple non lo include; su macOS usa brew install llvm o compila dentro una VM Linux.
• Eseguire l'artefatto richiede Linux su arm64 o amd64.

Ispirazioni

• Solod: il transpiler da Go a C che ha dimostrato che questo schema funziona.
• Aya: il framework eBPF in Rust di cui gobee insegue l'ergonomia.

Licenza

MIT. Vedi LICENSE.

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