Docs: improve descriptions

Author: yunwei37

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.
 

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] <COMMAND>
+...
 ```
 
-### 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

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)

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 ebpf instructions> [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