mirror of
https://github.com/varun-r-mallya/Python-BPF.git
synced 2026-02-08 06:00:56 +00:00
101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
1. **AST Parsing** - Python code is parsed into an Abstract Syntax Tree
|
|
2. **IR Generation** - The AST is transformed into LLVM IR using llvmlite
|
|
3. **BPF Compilation** - LLVM IR is compiled to BPF bytecode using `llc`
|
|
4. **Loading** - The BPF object is loaded into the kernel using libbpf
|
|
5. **Attachment** - Programs are attached to kernel hooks (tracepoints, kprobes, etc.)
|
|
|
|
## Guide Contents
|
|
|
|
```{toctree}
|
|
:maxdepth: 2
|
|
|
|
decorators
|
|
maps
|
|
structs
|
|
compilation
|
|
helpers
|
|
```
|
|
|
|
## Code Organization
|
|
|
|
When writing BPF programs with PythonBPF, we recommend:
|
|
|
|
1. **Keep BPF code in separate files** - Easier to manage and test
|
|
2. **Use type hints** - Required for proper code generation
|
|
3. **Follow naming conventions** - Use descriptive names for maps and functions
|
|
4. **Document your code** - Add comments explaining BPF-specific logic
|
|
5. **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:
|
|
|
|
```python
|
|
from pythonbpf import bpf, map, section, bpfglobal, BPF
|
|
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 c_int64(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...
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
Start with {doc}`decorators` to learn about all available decorators, then explore the other sections to master specific features.
|