gobee

Écrivez vos programmes BPF en Go, pas en C. gobee transpile un sous-ensemble strict de Go en C BPF, génère des bindings Go typés pour le côté espace utilisateur, et vérifie les charges par rapport au noyau en cours d'exécution.

L'écosystème Go dispose d'outils solides pour l'espace utilisateur BPF. Le côté noyau s'est toujours terminé par « maintenant écrivez votre programme en C. » Aya a apporté eBPF à Rust en écrivant un nouveau backend BPF dans rustc. gobee y parvient différemment : en transpilant vers C et en réutilisant le backend mature de clang.

Un fichier Go en entrée, un programme BPF en sortie

Une tracepoint qui diffuse chaque execve vers l'espace utilisateur via 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 produit les deux fichiers, plus une sourcemap (events.bpf.c.map) pour que les erreurs du vérificateur correspondent aux lignes Go, et un fichier de bindings typés (bpf/events_bindings.go) pour que le pilote espace utilisateur écrive objs.Events, objs.AttachOnExec() et décode les payloads du ringbuf directement dans bpf.Event (la même structure que ci-dessus, republiée en Go) au lieu de recherches coll.Programs["..."] basées sur des chaînes.

Le C est intentionnellement lisible. Si gobee émet quelque chose d'étrange, vous pouvez le voir. Pour les tracepoints + kprobes + XDP combinés en un seul binaire, voir example/sysmon/.

Comparaison

Si vous êtes déjà dans un workflow C / libbpf, gobee ne cherche pas à le remplacer entièrement. Il est destiné aux cas où vous voulez le côté noyau, le côté espace utilisateur et le pipeline de construction dans un seul module Go.

Ce qui est supporté aujourd'hui

Voir docs/status.md pour la matrice complète (sous-ensemble Go, instructions, expressions, chaque helper, chaque type de map, chaque directive). Aperçu rapide :

Ce que gobee fait

• Transpile un sous-ensemble Go en C BPF (et exécute d'abord go/types sur votre entrée, de sorte que les mauvaises utilisations apparaissent à fichier:ligne:col).
• Génère un <Stem>_bindings.go typé à côté du .bpf.c : bpf.LoadCounter(spec), objs.PerIface.Lookup(...), objs.AttachAll(ifindex), plus vos types de structures et constantes côté noyau republiés en Go.
• Annote automatiquement *ebpf.VerifierError de LoadAndAssign avec des positions source Go, sans nécessiter de pipe manuel gobee diagnose.
• Exécute bpfvet à l'intérieur de Load<Stem> pour que les anciens noyaux échouent rapidement avec « bpf program needs kernel >= 5.8, host is 5.4 ».
• Expose environ 200 stubs Go typés pour l'ensemble des helpers libbpf v1.5.0, plus les fonctions helpers définies par l'utilisateur émises comme .

Ce que gobee ne fera pas

• Remplacer clang. Le backend BPF de clang nous donne CO-RE, BTF et une génération de code compatible avec le vérificateur gratuitement. Réimplémenter cela coûterait des années et n'apporterait rien.
• Remplacer cilium/ebpf. Les bindings générés reposent dessus.
• Cacher BPF. Le sous-ensemble Go correspond 1:1 aux idiomes C BPF. Si vous connaissez BPF, gobee est un sucre fin. Sinon, le manuel reste une lecture obligatoire.
• Exécuter clang pour vous. La compilation, l'intégration et le chargement restent de votre responsabilité. Même modèle que bpf2go.

Pourquoi transpiler, pas générer du BPF directement

gc, le compilateur Go, n'a pas de backend BPF basé sur LLVM. En ajouter un est un projet de compilateur de plusieurs années. rustc est construit sur LLVM et c'est pourquoi Aya fonctionne. Donc gobee émet du C et réutilise le backend BPF de clang, ce qui nous donne une génération de code mature, du BTF et des relocalisations CO-RE gratuitement.

Démarrage rapide

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

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

Vous aurez besoin de clang avec la cible BPF. Sous Linux, c'est le paquet de la distribution ; sous macOS, brew install llvm. Le transpileur lui-même est du Go pur et fonctionne partout.

Structure de projet (typique)

yourproject/
├── bpf/                      # Package Go, importable depuis n'importe où dans votre projet
│   ├── embed_amd64.go        # //go:embed bin/x86/your.bpf.o
│   ├── embed_arm64.go
│   ├── your_bindings.go      # généré par gobee
│   ├── bin/{x86,arm64}/your.bpf.o
│   └── src/                  # pas un package Go ; clang vit ici
│       ├── your.go           # //go:build ignore : source BPF
│       ├── your.bpf.c        # généré
│       ├── Makefile          # clang par arch
│       └── vmlinux.h         # dump BTF vendored
├── main.go                   # importe yourproject/bpf
└── Makefile

La séparation maintient bpf/ comme un package Go propre et importable (Go rejette les fichiers .c dans les packages non-cgo). Les sources du noyau et les artefacts clang vivent un niveau plus bas dans bpf/src/.

Exemples

• example/helloworld/ : le compteur de paquets XDP canonique, ~40 lignes BPF, ~80 lignes espace utilisateur.
• example/sysmon/ : XDP, deux tracepoints et un kprobe dans un seul binaire, partageant un ringbuf pour les événements. Montre les contextes typés par appel système, les fonctions helpers définies par l'utilisateur et le raccourci AttachAll.

CI

GitHub Actions exécute quatre couches à chaque push :

1. go test, go vet, tests dorés du transpileur
2. Matrice de couverture : chaque type de map et chaque sorte de //bpf:section a au moins un exemple
3. Compilation clang de chaque exemple sélectionné, puis rapport de portabilité bpfvet
4. Acceptation par le vérificateur sur noyau réel : ebpf.NewCollectionWithOptions sur chaque .bpf.o (runner Ubuntu 24.04, noyau 6.x)

Docs

• docs/design.md : architecture et justification
• docs/go-subset.md : syntaxe Go acceptée dans les fichiers source BPF
• docs/directives.md : référence //bpf:*
• docs/status.md : matrice de support (source unique de vérité)

Toolchain

• Le binaire gobee se compile partout (Go pur, pas de CGO).
• La compilation de .bpf.o nécessite clang avec la cible BPF. Le clang fourni par Apple ne l'inclut pas ; sous macOS, utilisez brew install llvm ou compilez dans une VM Linux.
• L'exécution de l'artefact nécessite Linux sur arm64 ou amd64.

Inspirations

• Solod : le transpileur Go-vers-C qui a prouvé que ce modèle fonctionne.
• Aya : le framework Rust eBPF dont gobee poursuit l'ergonomie.

Licence

MIT. Voir LICENSE.

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