cbpfc

package module
v0.0.0-...-083e74b Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: BSD-3-Clause Imports: 9 Imported by: 7

README

cbpfc

GoDoc

cbpfc is a classic BPF (cBPF) to extended BPF (eBPF) compiler. It can compile cBPF to eBPF, or to C, and the generated code should be accepted by the kernel verifier.

cbpfc/clang is a simple clang wrapper for compiling C to eBPF.

Tests

Dependencies
  • clang
    • Path can be set via environment variable $CLANG
Unprivileged
  • go test -short
Full
  • Requires:

    • root or CAP_SYS_ADMIN to load XDP programs
    • Recent (4.14+) Linux kernel
  • sudo go test

Documentation

Overview

Package cbpfc implements a cBPF (classic BPF) to eBPF (extended BPF, not be confused with cBPF extensions) compiler.

cbpfc can compile cBPF filters to:

  • C, which can be compiled to eBPF with Clang
  • eBPF

Both the C and eBPF output are intended to be accepted by the kernel verifier:

  • All packet loads are guarded with runtime packet length checks
  • RegA and RegX are zero initialized as required
  • Division by zero is guarded by runtime checks

The generated C / eBPF is intended to be embedded into a larger C / eBPF program.

Footguns / limitations:

  • The maximum absolute offset of a packet that can be read is 0xFFFF, any accesses past that will be treated as out of bounds cBPF packet accesses, and the filter will return 0. That includes offsets added directly to the packet pointer passed in.
  • If the packet pointer passed in has an offset (eg because you've skipped past the ethernet header), the maximum possible offset must be passed in via EBPFOpts or COpts.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ToC

func ToC(filter []bpf.Instruction, opts COpts) (string, error)

ToC compiles a cBPF filter to a C function with a signature of:

uint32_t opts.FunctionName(const uint8_t *const data, const uint8_t *const data_end)

If the data pointer is offset from the original BPF context pointer, the maximum value of this offset must be set as COpts.PacketStartMaxOffset.

The function returns the filter's return value: 0 if the packet does not match the cBPF filter, non 0 if the packet does match.

Example

ExampleToC demonstrates how to use ToC() to embed a cBPF filter in a C program, and compile it to eBPF.

package main

import (
	"bytes"
	"fmt"
	"os"
	"text/template"

	"github.com/cloudflare/cbpfc/clang"

	"golang.org/x/net/bpf"
)

var testTemplate = template.Must(template.New(entryPoint).Parse(`
#define __section(NAME) __attribute__((section(NAME), used))

char __license[] __section("license") = "BSD";

// Shim out all the definitions required by cbpfc
// Real programs should use the proper headers
typedef unsigned long long uint64_t;
typedef long long int64_t;
typedef unsigned int uint32_t;
typedef int int32_t;
typedef unsigned short uint16_t;
typedef unsigned char uint8_t;

typedef char bool;
#define false 0
#define true 1

#define ntohs __builtin_bswap16
#define ntohl __builtin_bswap32

struct xdp_md {
	uint32_t data;
	uint32_t data_end;
};

enum xdp_action {
	XDP_DROP = 1,
	XDP_PASS,
};

{{.Filter}}

__section("xdp") int {{.ProgramName}}(struct xdp_md *ctx) {
	uint8_t *data = (uint8_t *)(long)ctx->data;
	uint8_t const *data_end = (uint8_t *)(long)ctx->data_end;

	if ({{.FilterName}}(data + {{.Offset}}, data_end)) {
		return XDP_DROP;
	}

	return XDP_PASS;
}
`))

type testTemplateOpts struct {
	// Definition of the filter
	Filter string

	// Function name of the filter
	FilterName string

	// Name of the eBPF program
	ProgramName string

	// Offset the packet start is advanced by before the filter is called.
	// Must match the COpts.PacketStartMaxOffset the filter was compiled with.
	Offset uint16
}

// ExampleToC demonstrates how to use ToC() to embed a cBPF filter
// in a C program, and compile it to eBPF.
func main() {
	// simple cBPF filter that matches all packets
	filter := []bpf.Instruction{
		bpf.RetConstant{Val: 1},
	}

	elf, err := buildC(filter, "example", COpts{FunctionName: "example_filter"})
	if err != nil {
		panic(err)
	}

	// ELF with a single eBPF program 'example'
	// Can be loaded with cilium/ebpf or libbpf
	_ = elf
}

// buildC compiles a cBPF filter to C, embeds it in a C template,
// and compiles the resulting C program to eBPF / XDP using clang.
// The XDP program XDP_DROP's incoming packets that match the filter.
// Returns the compiled ELF
func buildC(filter []bpf.Instruction, programName string, opts COpts) ([]byte, error) {
	// convert filter to C
	ebpfFilter, err := ToC(filter, opts)
	if err != nil {
		return nil, fmt.Errorf("converting filter to C: %w", err)
	}

	// embed filter in C template
	c := bytes.Buffer{}
	err = testTemplate.Execute(&c, testTemplateOpts{
		Filter:      ebpfFilter,
		FilterName:  opts.FunctionName,
		ProgramName: programName,
		Offset:      opts.PacketStartMaxOffset,
	})
	if err != nil {
		return nil, fmt.Errorf("executing template with C filter: %w", err)
	}

	// lookup clang binary to use
	clangBin, ok := os.LookupEnv("CLANG")
	if !ok {
		clangBin = "/usr/bin/clang"
	}

	// compile C program
	elf, err := clang.Compile(c.Bytes(), entryPoint, clang.Opts{
		Clang:     clangBin,
		EmitDebug: true, // For BTF
	})
	if err != nil {
		return nil, fmt.Errorf("compiling C: %w", err)
	}

	return elf, nil
}

func ToEBPF

func ToEBPF(filter []bpf.Instruction, opts EBPFOpts) (asm.Instructions, error)

ToEBF converts a cBPF filter to eBPF.

The generated eBPF code always jumps to opts.ResultLabel, with register opts.Result containing the filter's return value: 0 if the packet does not match the cBPF filter, non 0 if the packet does match.

Example

ExampleToEBPF demonstrates how to use ToEBPF() to embed a cBPF filter in an eBPF assembly program.

package main

import (
	"fmt"

	"github.com/cilium/ebpf/asm"
	"golang.org/x/net/bpf"
)

// ExampleToEBPF demonstrates how to use ToEBPF() to embed a cBPF filter
// in an eBPF assembly program.
func main() {
	// simple cBPF filter that matches all packets
	filter := []bpf.Instruction{
		bpf.RetConstant{Val: 1},
	}

	prog, err := buildEBPF(filter, 0)
	if err != nil {
		panic(err)
	}

	// Prog can be loaded directly using cilium/ebpf,
	// or converted to a '[]struct bpf_insn' for libbpf
	_ = prog
}

// buildEBPF compiles a cBPF filter to eBPF, and embeds it an eBPF program.
// The XDP program XDP_DROP's incoming packets that match the filter.
// Returns the eBPF program instructions
func buildEBPF(filter []bpf.Instruction, offset uint16) (asm.Instructions, error) {
	ebpfFilter, err := ToEBPF(filter, EBPFOpts{
		// Pass packet start and end pointers in these registers
		PacketStart:          asm.R2,
		PacketStartMaxOffset: offset,
		PacketEnd:            asm.R3,
		// Result of filter
		Result:      asm.R4,
		ResultLabel: "result",
		// Registers used by generated code
		Working:     [4]asm.Register{asm.R4, asm.R5, asm.R6, asm.R7},
		LabelPrefix: "filter",
	})
	if err != nil {
		return nil, fmt.Errorf("converting filter to eBPF: %w", err)
	}

	prog := asm.Instructions{
		// R1 holds XDP context

		// Packet start
		asm.LoadMem(asm.R2, asm.R1, 0, asm.Word),
		// Fixed offset
		asm.Add.Imm(asm.R2, int32(offset)),

		// Packet end
		asm.LoadMem(asm.R3, asm.R1, 4, asm.Word),

		// Fall through to filter
	}

	prog = append(prog, ebpfFilter...)

	prog = append(prog,
		asm.Mov.Imm(asm.R0, 2).WithSymbol("result"), // XDP_PASS
		asm.JEq.Imm(asm.R4, 0, "return"),
		asm.Mov.Imm(asm.R0, 1), // XDP_DROP
		asm.Return().WithSymbol("return"),
	)

	return prog, nil
}

Types

type COpts

type COpts struct {
	// FunctionName is the symbol to use as the generated C function. Must match regex:
	//     [A-Za-z_][0-9A-Za-z_]*
	FunctionName string

	// NoInline doesn't force the generated function to be inlined, allowing clang to emit
	// a BPF to BPF call.
	// Requires at least kernel 5.10 (for x86, later for other architectures) if used with tail-calls.
	NoInline bool

	// PacketStartMaxOffset is the maximum offset the packet start / data is at, in bytes.
	PacketStartMaxOffset uint16
}

type EBPFOpts

type EBPFOpts struct {
	// PacketStart is a register holding a pointer to the start of the packet.
	// If this pointer is offset from the original BPF context pointer,
	// the maximum value of this offset must be set as PacketStartMaxOffset.
	// Not modified.
	PacketStart asm.Register
	// PacketStartMaxOffset is the maximum offset PacketStart is at, in bytes.
	PacketStartMaxOffset uint16
	// PacketEnd is a register holding a pointer to the end of the packet.
	// Not modified.
	PacketEnd asm.Register
	// Register to output the filter return value in.
	Result asm.Register

	// Label to jump to with the result of the filter in register Result.
	ResultLabel string

	// Working are registers used internally.
	// Caller saved.
	// Must be different to PacketStart and PacketEnd, but Result can be reused.
	Working [4]asm.Register

	// StackOffset is the number of bytes of stack already used / reserved.
	// R10 (ebpf frame pointer) + StackOffset will be used as the top of the stack.
	StackOffset int

	// LabelPrefix is the prefix to prepend to labels used internally.
	LabelPrefix string
}

EBPFOpts control how a cBPF filter is converted to eBPF

Directories

Path Synopsis
Package clang implements a simple wrapper for invoking clang to compile C to eBPF
Package clang implements a simple wrapper for invoking clang to compile C to eBPF

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL