From de733e99c387ebcb2ab6a0093f89ab74e59fb100 Mon Sep 17 00:00:00 2001 From: yunwei37 <1067852565@qq.com> Date: Sat, 30 Sep 2023 17:00:16 +0000 Subject: [PATCH] Docs: improve descriptions --- README.md | 28 +++++++++++++++++++--------- documents/build-and-test.md | 33 ++++++++++++++++++--------------- tools/cli/main.cpp | 3 ++- vm/README.md | 36 ++++++++++++++++++++++++++++++++++-- 4 files changed, 73 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index d244787f..25d6d5c0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# bpftime: Userspace eBPF runtime for fast Uprobe & Syscall hook +# bpftime: Userspace eBPF runtime for fast Uprobe & Syscall Hook -`bpftime`, a full-featured, high-performance eBPF runtime designed to operate in userspace. It's engineered to offer fast Uprobe and Syscall hook capabilities. Userspace uprobe can be **10x faster than kernel uprobe!** +`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. > ⚠️ **Note**: `bpftime` is actively under development. The API or design might change in upcoming releases, and it's not yet recommended for production use. See our [roadmap](#roadmap) for details. @@ -41,10 +41,22 @@ continue malloc... malloc called from pid 250215 ``` -You can also inject the userspace runtime library into a running process: +You can also dynamically attach the eBPF program with a running process: ```console +$ ./example/malloc/test & echo $! # The pid is 101771 +[1] 101771 +101771 +continue malloc... +continue malloc... +``` +And attach to it: + +```console +$ sudo bpftime attach 101771 # You may need to run make install in root +Inject: "/root/.bpftime/libbpftime-agent.so" +Successfully injected. ID: 1 ``` You can see the output from original program: @@ -57,11 +69,6 @@ $ bpftime load ./example/malloc/malloc pid=247322 malloc calls: 10 ``` -Run the target program and dynamically attach the eBPF program into it: - -```console -``` - Alternatively, you can also run our sample eBPF program directly in the kernel eBPF, to see the similar output: ```console @@ -102,7 +109,10 @@ Left: kernel eBPF | Right: userspace bpftime ![How it works](documents/bpftime.png) -The inline hook implementation is based on frida. +The 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) +- Syscall hooks: [zpoline: a system call hook mechanism based on binary rewriting](https://www.usenix.org/conference/atc23/presentation/yasukata) see [documents/how-it-works.md](documents/how-it-works.md) for details. diff --git a/documents/build-and-test.md b/documents/build-and-test.md index 8c90300d..80e654a1 100644 --- a/documents/build-and-test.md +++ b/documents/build-and-test.md @@ -12,34 +12,37 @@ sudo apt install -y --no-install-recommends \ git submodule update --init --recursive ``` -## Compilation - -Build the complete runtime: +### Build and install cli tool ```bash -make build +sudo apt-get install libelf-dev zlib1g-dev # Install dependencies +make build && make install # Build and install the runtime +cd tools/cli-rs && cargo build --release +mkdir -p ~/.bpftime && cp ./target/release/bpftime ~/.bpftime +export PATH=$PATH:~/.bpftime ``` -For a lightweight build without the runtime (only vm library and LLVM JIT): +Then you can run cli: -```bash -make build-vm # build the simple vm with a simple jit -make build-llvm # build the vm with llvm jit +```console +$ bpftime +Usage: bpftime [OPTIONS] +... ``` -### Build and install cli tool +## Compilation + +Build the complete runtime: ```bash -sudo apt-get install libelf-dev zlib1g-dev # Install dependencies -cd tools/cli-rs && cargo build --release -mkdir ~/.bpftime && cp ./target/release/bpftime ~/.bpftime -export PATH=$PATH:~/.bpftime +make build ``` -### Build and install runtime +For a lightweight build without the runtime (only vm library and LLVM JIT): ```bash -make install # Install the runtime +make build-vm # build the simple vm with a simple jit +make build-llvm # build the vm with llvm jit ``` ## Testing diff --git a/tools/cli/main.cpp b/tools/cli/main.cpp index 46c7fc08..7fe21f92 100644 --- a/tools/cli/main.cpp +++ b/tools/cli/main.cpp @@ -74,7 +74,7 @@ static libbpf_object_ptr open_and_attach_libbpf_object(const char *filename) return obj_ptr; } -void inject_agent(int target_pid, const char *agent_dynlib_path) +int inject_agent(int target_pid, const char *agent_dynlib_path) { // check the args frida_init(); @@ -98,6 +98,7 @@ void inject_agent(int target_pid, const char *agent_dynlib_path) frida_injector_close_sync(injector, NULL, NULL); frida_unref(injector); frida_deinit(); + return 0; } std::string get_lib_path(const char *library_name) diff --git a/vm/README.md b/vm/README.md index 4d93872f..f414c741 100644 --- a/vm/README.md +++ b/vm/README.md @@ -1,6 +1,8 @@ -# bpftime vm +# bpftime vm: userspace eBPF vm with JIT support -the bpf vm and jit for eBPF, you can choose from llvm-jit and a simple-jit/interpreter based on ubpf. +The bpf vm and jit for eBPF usersapce runtime. + +you can choose from llvm-jit and a simple-jit/interpreter based on ubpf. ## LLVM jit for eBPF @@ -10,3 +12,33 @@ see [llvm-jit/README.md](llvm-jit/README.md) see [simple-jit/README.md](simple-jit/README.md) +## build + +The JIT can be built as a standalone library and integrated into other projects. + +In `vm` directory, run: + +```sh +make build +``` + +## Example Usage + +See [example/main.c](example/main.c) for how to use it. + +## cli + +A tool for loading and running eBPF programs. + +```console +$ bpftime-cli +Usage: build/vm/cli/bpftime-cli [path to memory for the ebpf program] +``` + +## benchmark + +see [github.com/eunomia-bpf/bpf-benchmark](https://github.com/eunomia-bpf/bpf-benchmark) for how we evaluate and details. + +## Roadmap + +- [ ] AOT support for LLVM JIT