User Guide

This user guide provides comprehensive documentation for all PythonBPF features. Whether you're building simple tracing tools or complex performance monitoring systems, this guide will help you master PythonBPF.

Overview

PythonBPF transforms Python code into eBPF bytecode that runs in the Linux kernel. It provides a Pythonic interface to eBPF features through decorators, type annotations, and familiar programming patterns.

Core Concepts

Decorators

PythonBPF uses decorators to mark code for BPF compilation:

@bpf - Mark functions and classes for BPF compilation
@map - Define BPF maps for data storage
@struct - Define custom data structures
@section(name) - Specify attachment points
@bpfglobal - Define global variables

Compilation Pipeline

Your Python code goes through several stages:

IR Generation - The Python AST is transformed into LLVM IR using llvmlite
BPF Compilation - LLVM IR is compiled to BPF bytecode using llc
Loading - The BPF object is loaded into the kernel using libbpf
Attachment - Programs are attached to kernel hooks (tracepoints, kprobes, etc.)

Code Organization

When writing BPF programs with PythonBPF, we recommend:

Use type hints - Required for proper code generation
Test incrementally - Verify each component works before adding complexity

Type System

PythonBPF uses Python's ctypes module for type definitions:

c_int8, c_int16, c_int32, c_int64 - Signed integers
c_uint8, c_uint16, c_uint32, c_uint64 - Unsigned integers
c_char, c_bool - Characters and booleans
c_void_p - Void pointers
str(N) - Fixed-length strings (e.g., str(16) for 16-byte string)

Example Structure

A typical PythonBPF program follows this structure:

from pythonbpf import bpf, map, section, bpfglobal, BPF, compile
from pythonbpf.maps import HashMap
from ctypes import c_void_p, c_int64, c_uint32

# Define maps
@bpf
@map
def my_map() -> HashMap:
    return HashMap(key=c_uint32, value=c_uint64, max_entries=1024)

# Define BPF function
@bpf
@section("tracepoint/...")
def my_function(ctx: c_void_p) -> c_int64:
    # BPF logic here
    return 0

# License (required)
@bpf
@bpfglobal
def LICENSE() -> str:
    return "GPL"

# Compile, load, and run
if __name__ == "__main__":
    b = BPF()
    b.load_and_attach()
    # Use the program...

# Or, compile to an object file
compile()

Next Steps

Start with {doc}decorators to learn about all available decorators, then explore the other sections to master specific features.

2.5 KiB Raw Blame History