diff --git a/README.md b/README.md index df7929b5..e859f3c9 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,16 @@ [![Build and Test VM](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-vm.yml/badge.svg)](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-vm.yml) [![Build and test runtime](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-runtime.yml/badge.svg)](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-runtime.yml) -[![DOI](https://zenodo.org/badge/676866666.svg)](https://zenodo.org/badge/latestdoi/676866666) +[![DOI](https://zenodo.org/badge/676866666.svg)](https://doi.org/10.48550/arXiv.2311.07923) `bpftime`, a full-featured, high-performance eBPF runtime designed to operate in userspace. It offers fast Uprobe and Syscall hook capabilities: Userspace uprobe can be **10x faster than kernel uprobe!** and can programmatically **hook all syscalls of a process** safely and efficiently. +📦 [Features](#key-features) \ +🔨 [Quick Start](#quick-start) \ +⌨️ [Linux Plumbers 23 talk](https://lpc.events/event/17/contributions/1639/) \ +📖 [Slides](https://github.com/eunomia-bpf/bpftime/tree/master/documents/userspace-ebpf-bpftime-lpc.pdf) \ +📚 [Arxiv preprint](https://arxiv.org/abs/2311.07923) + ## Key Features - **Uprobe and Syscall hooks based on binary rewriting**: Run eBPF programs in userspace, attaching them to Uprobes and Syscall tracepoints: **No mannual instrumentation or restart required!**. It can `trace`, `replace` or `patch` the execution of a function, `hook`, `filter` or `redirect` all syscalls of a process safely, and efficiently with an eBPF userspace runtime. @@ -101,16 +107,30 @@ Example using libbpf: More bcc/libbpf-tools examples can be found in [example/libbpf-tools](https://github.com/eunomia-bpf/bpftime/tree/master/example/libbpf-tools). -You can also run bpftime with `bpftrace`, we've test it on [this commit](https://github.com/iovisor/bpftrace/commit/75aca47dd8e1d642ff31c9d3ce330e0c616e5b96). More details about how to run bpftrace in usespace, can be found in [https://github.com/eunomia-bpf/bpftime/tree/master/example/bpftrace](example/bpftrace). +You can also run bpftime with `bpftrace`, we've test it on [this commit](https://github.com/iovisor/bpftrace/commit/75aca47dd8e1d642ff31c9d3ce330e0c616e5b96). More details about how to run bpftrace in usespace, can be found in [example/bpftrace](https://github.com/eunomia-bpf/bpftime/tree/master/example/bpftrace). > ⚠️ **Note**: `bpftime` is actively under development, and it's not yet recommended for production use. See our [roadmap](#roadmap) for details. We'd love to hear your feedback and suggestions! Please feel free to open an issue or [Contact us](#contact). ### **How it Works** -Left: kernel eBPF | Right: userspace bpftime +bpftime supports two modes: + +#### Running in userspace only + +Left: original kernel eBPF | Right: bpftime ![How it works](https://github.com/eunomia-bpf/bpftime/raw/master/documents/bpftime.png?raw=true) +In this mode, bpftime can run eBPF programs in userspace without kernel. It relies on a userspace verifier to ensure the safety of eBPF programs. + +#### Run with kernel eBPF + +![documents/bpftime-kernel.png](https://github.com/eunomia-bpf/bpftime/raw/master/documents/bpftime-kernel.png?raw=true) + +In this mode, bpftime can run together with kernel eBPF. It can load eBPF programs from kernel, and using kernel eBPF maps to cooperate with kernel eBPF programs like kprobes and network filters. + +#### Instrumentation implementation + Current hook implementation is based on binary rewriting and the underly technique is inspired by: - Userspace function hook: [frida-gum](https://github.com/frida/frida-gum) @@ -118,7 +138,7 @@ Current hook implementation is based on binary rewriting and the underly techniq The hook can be easily replaced with other DBI methods or frameworks, or add more hook mechanisms in the future. -see [documents/how-it-works.md](https://github.com/eunomia-bpf/bpftime/tree/master/documents/how-it-works.md) for details. +see [arxiv preprint: https://arxiv.org/abs/2311.07923](https://arxiv.org/abs/2311.07923) for details. ### **Performance Benchmarks** @@ -135,7 +155,7 @@ It can be attached to functions in running process just like the kernel uprobe d How is the performance of LLVM JIT/AOT compared to other eBPF userspace runtimes, native code or wasm runtimes? -![LLVM jit benchmark](https://github.com/eunomia-bpf/bpf-benchmark/raw/main/example-output/merged_execution_times.png?raw=true) +![LLVM jit benchmark](https://github.com/eunomia-bpf/bpf-benchmark/raw/main/example-output/benchmark-11-16.png?raw=true) Across all tests, the LLVM JIT for bpftime consistently showcased superior performance. Both demonstrated high efficiency in integer computations (as seen in log2_int), complex mathematical operations (as observed in prime), and memory operations (evident in memcpy and strcmp). While they lead in performance across the board, each runtime exhibits unique strengths and weaknesses. These insights can be invaluable for users when choosing the most appropriate runtime for their specific use-cases. diff --git a/documents/avaliable-features.md b/documents/avaliable-features.md index 66e2f3dd..0d27851d 100644 --- a/documents/avaliable-features.md +++ b/documents/avaliable-features.md @@ -2,15 +2,29 @@ ## avalibale map types -- `BPF_MAP_TYPE_HASH` -- `BPF_MAP_TYPE_ARRAY` +Userspace eBPF shared memory map types: -see [../runtime/src/maps.cpp](../runtime/src/maps.cpp) for more details. +- BPF_MAP_TYPE_HASH +- BPF_MAP_TYPE_ARRAY +- BPF_MAP_TYPE_RINGBUF +- BPF_MAP_TYPE_PERF_EVENT_ARRAY +- BPF_MAP_TYPE_PERCPU_ARRAY +- BPF_MAP_TYPE_PERCPU_HASH + +User-kernel shared maps: + +- BPF_MAP_TYPE_HASH +- BPF_MAP_TYPE_ARRAY +- BPF_MAP_TYPE_PERCPU_ARRAY +- BPF_MAP_TYPE_PERF_EVENT_ARRAY ## avaliable program types -- UPROBE -- SYSCALL TRACEPOINT +- tracepoint:raw_syscalls:sys_enter +- tracepoint:syscalls:sys_exit_* +- tracepoint:syscalls:sys_enter_* +- uretprobe:* +- uprobe:* ## available helpers @@ -35,3 +49,8 @@ see [../runtime/src/maps.cpp](../runtime/src/maps.cpp) for more details. - `bpf_set_retval`: Helper function for setting the return value of a function. - `bpf_probe_read_str`: Helper function for reading a null-terminated string from a user address. - `bpf_get_stack`: Helper function for retrieving the current kernel stack. + +## Others + +- Support kernel or userspace verifier +- Test JIT with bpf_conformance diff --git a/documents/bpftime-kernel.png b/documents/bpftime-kernel.png new file mode 100644 index 00000000..11905805 Binary files /dev/null and b/documents/bpftime-kernel.png differ diff --git a/documents/userspace-ebpf-bpftime-lpc.pdf b/documents/userspace-ebpf-bpftime-lpc.pdf new file mode 100644 index 00000000..0b7a81b5 Binary files /dev/null and b/documents/userspace-ebpf-bpftime-lpc.pdf differ