gobee: Go で記述する eBPF

gobee は、Go の厳密なサブセットを eBPF C コードに変換（トランスパイール）し、ユーザースペース向けの型付きバインディングを生成するツールです。 このツールは成熟した

clang

特徴と仕組み

1. トランスパイールによるアプローチ

• gobee: Go のサブセットを C に変換し、成熟した clang の BPF バックエンドを活用します。
• Aya (Rust):

  rustc

  に BPF バックエンドを追加するアプローチを採用しています。

2. 生成されるアーティファクト

gobee は以下の 3 つの要素を生成します。

1. BPF C コード:

   .bpf.c

   ファイルとして出力されます。
2. ソースマップ (Sourcemap): Verifier エラーと Go ソースコードを行番号付きでマッピングしたファイル（例：

   events.bpf.c.map

   ）。
3. 型付きバインディング: ユーザースペースで使用するための型定義ファイル（例：

   bpf/events_bindings.go

   ）。

3. ユーザースペースとの親和性

• 冗長な文字列検索 (

  coll.Programs["..."]

  ) を避け、同一の構造体を用いてリングバッファへの直接デコードが可能です。
• 生成された C コードは意図的に可読性を高めており、

  gobee

  が意図しない奇妙なコードを出力しても確認可能に設計されています。

使用例：Tracepoint からのイベント収集

リングバッファ経由で全ての

execve

Go コード (入力)

//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() {}

生成された BPF C コード (出力)

// 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

他のツールとの比較

注記: gobee は既存の C/libbpf ワークフローを置き換えることを意図しておりません。カーネル側・ユーザースペース側・ビルドパイプラインを一つの Go モジュール内で管理したい場合に最適です。

対応状況 (What's supported today)

詳細は docs/status.md を参照してください。

task_struct

sock

vmlinux.h

__always_inline

Load

Close

Attach

AttachAll

bpfvet

gobee が行うこと (Summary)

• Go のサブセットを BPF C にトランスパイールし、誤利用をファイル・行・列単位で警告します (

  go/types

  を事前実行)。

• .bpf.c

  の隣に型付きバインディング

  <Stem>_bindings.go

  を生成します。

• LoadAndAssign

  からの Verifier エラーに対し、Go ソース位置を自動アノテーションします（手動パイプ不要）。
• ローダ内 (

  Load<Stem>

  ) で

  bpfvet

  を実行し、カーネルバージョンの不整合を早期に検出します。
• ~200 のヘルパー・スタブに加え、ユーザー定義ヘルパーも静的関数として生成します。

gobee が行わないこと (Limitations)

• clang の置き換えはしません: CO-RE や BTF などの機能は clang に既に実装されており、再実装のメリットはありません。
• cilium/ebpf の置き換えはしません: 生成されたバインディングは cilium/ebpf と互換性のあるスタックの上で動作します。
• BPF プログラムを隠しません: Go サブセットは BPF C に 1:1 マッピングし、BPF を知らない場合でもマニュアル参照が必要です。
• 自動ビルド・ロードは行いません: コンパイルからロードまでの手順は依然としてユーザーの手動作業（bpf2go と同様）が必要です。

なぜトランスパイールするか？

Go のコンパイラ (gc) には、LLVM ベースの BPF バックエンドが存在しません。rustc と異なり、その追加には多大なコストがかかります。 gobee は C を介して

clang

• 成熟したコード生成
• CO-RE / BTF サポート
• Verifier フriendly な構造

クイックスタート

前提条件

• Linux: ディストリビューションのパッケージから clang (BPF ターゲット) をインストール。
• macOS:

  brew install llvm

  で LLVM/clang をインストールしてください。
• Go バイナリ生成環境: arm64 または amd64 の Linux が必要です。

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

cd example/helloworld
make build                     # トランスパイル、コンパイル、ビルドのワンステップ
sudo ./helloworld eth0

プロジェクト構造例

yourproject/
├── bpf/                      # import 可能な Go パッケージ
│   ├── embed_amd64.go        # CGO エンベディメント定義
│   ├── embed_arm64.go
│   ├── your_bindings.go      # gobee が生成したバインディング
│   ├── bin/{x86,arm64}/your.bpf.o  # コンパイル済みオブジェクトファイル
│   └── src/                  # clang の入力用ディレクトリ (Go パッケージではない)
│       ├── your.go           //go:build ignore を持つ BPF ソース
│       ├── your.bpf.c        # gobee が生成した C コード
│       ├── Makefile          # アーキテクチャ別のclang コンパイル設定
│       └── vmlinux.h         # バインダされた BTF ドンプ
├── main.go                   # bpf パッケージを import する実装ファイル
└── Makefile                  # 全工程のビルド管理

この構造は、

bpf/

src/

リソース

実装例 (Examples)

• example/helloworld: キャンノニカルな XDP パケットカウンタ（BPF 40 行 / ユーザースペース 80 行）。
• example/sysmon: XDP、tracepoint、kprobe を統合。リングバッファ共有と

  AttachAll

  のデモ。

ドキュメント

• docs/design.md: アーキテクチャと設計思想
• docs/go-subset.md: 受け入れられる Go サブセットの言語仕様
• docs/directives.md:

  //bpf:*

  ディレクティブのリファレンス
• docs/status.md: サポートマトリックス（真の情報源）

影響を受けたプロジェクト

• Solod: Go から C へのトランスパイールパターン。
• Aya: ergonomics を重視する Rust eBPF フレームワーク。

ライセンス

MIT License Copyright (c) 2026 Bora Tanrikulu me@bora.sh