docs: readme

Author: linsyking

README.md

@@ -8,16 +8,17 @@ ePass could work with the verifier to improve its flexibility (i.e. reduce false
 ## Key Features
 
 - **IR-based compilation**: Converts BPF programs to an SSA-based intermediate representation for code rewriting
-- **Flexible passes**: ePass core provides various APIs to analyze and manipulate the IR, allowing users to write flexible passes including runtime checks and optimization.
-- **Command-line interface**: Easy-to-use CLI tool for testing in userspace
+- **Flexible passes**: ePass core provides various APIs to analyze and manipulate the IR, allowing users to write flexible passes including static analyzing, runtime checks, and optimization.
+- **User-friendly debugging**: ePass supports compiling to both kernel and userspace for easier debugging.
 
 > ePass is under active development and we are improving its usability and safety. We welcome any suggestions and feedback. Feel free to open issues or contact us.
 
 ## Design Goals
 
-- Flexible passes, allowing diverse use cases
+- Flexible passes for diverse use cases
 - Working with existing verifier instead of replacing its
 - Keeping kernel safety
+- Support both userspace and kernel
 
 ## Prerequisites
 
@@ -27,60 +28,40 @@ ePass could work with the verifier to improve its flexibility (i.e. reduce false
 
 ## Project Components
 
-- `ePass core`: the core compiler framework
+- `ePass core`: the core compiler framework, including a userspace CLI
 - `ePass kernel`: Linux kernel 6.5 with ePass core built-in, along with the kernel component and kernel passes
 - `ePass libbpf`: libbpf with ePass support for userspace ePass testing
-- `ePass bpftool`: support for ePass
 
-## Quick Start
-
-The main development happens in `core` directory. To start, `cd` into `core`.
-
-### Build
+There are some testing projects including `bpftool`, `xdp-tools`, `falcolib` in `third-party`. They depend on `ePass libbpf`.
 
-```bash
-make configure # Do it once
+### ePass Overview
 
-make build
-```
+![Overview](./docs/overview.png)
 
-### Install
+### ePass Core
 
-```bash
-make install
-```
+![Core Architecture](./docs/core_design.png)
 
-### Basic Usage
-
-```bash
-# Run ePass on the program
-epass read prog.o
+## Quick Start
 
-# Run ePass on the program with gopt and popt
-epass read --popt popts --gopt gopts prog.o
+There are two ways to use ePass. The first way is to build a linux kernel with ePass builtin, which is used for production. Users could specify ePass options when calling the `BPF` system call. See [Kernel Testing](docs/KERNEL_TESTING.md).
 
-# Print the BPF program
-epass print prog.o
-```
+The second way is to build ePass in userspace and testing programs without changing the kernel, which is used mainly for testing. Users could specify ePass options via environment variable and use `ePass libbpf`. Programs will be modified in userspace before sending to the kernel. See [Userspace Testing](docs/USERSPACE_TESTING.md).
 
-## Development
+We recommend users trying ePass in userspace before switching to the ePass kernel version!
 
-### Generate Additional Assets
+## Testing
 
-```bash
-# Generate kernel objects
-make kernel
+See [Testing](./docs/TESTING.md).
 
-# Build ePass object files for libbpf
-make buildobj
-```
+## Development and Contribution
 
+See [Development](./docs/CONTRIBUTION_GUIDE.md).
 
 ## Contact and citation
 
-Feel free to open an issue for question, bug report or feature request! You could also email xiangyiming2002@gmail.com
+Feel free to open an issue for question, bug report or feature request! You could also email <xiangyiming2002@gmail.com>.
 
 ## Acknowledgement
 
-ePass is sponsoredby OrderLab from University of Michigan.
-
+ePass is sponsored by [OrderLab](https://orderlab.io/) from University of Michigan.

docs/EPASS_OPTIONS.md

@@ -0,0 +1,7 @@
+# Epass Options
+
+## Global Options
+
+
+
+## Pass Options

docs/KERNEL_TESTING.md

@@ -0,0 +1 @@
+# Kernel Testing

docs/TESTING.md

@@ -0,0 +1 @@
+# ePass Testing

docs/USERSPACE_TESTING.md

@@ -0,0 +1,65 @@
+# Userspace Testing
+
+The main development happens in `core` directory. To start, `cd` into `core`.
+
+### Build
+
+```bash
+make configure # Do it once
+
+make build
+```
+
+### Install
+
+```bash
+make install
+```
+
+### Basic Usage
+
+```bash
+# Run ePass on the program
+epass read prog.o
+
+# Run ePass on the program with gopt and popt
+epass read --popt popts --gopt gopts prog.o
+
+# Print the BPF program
+epass print prog.o
+```
+
+For `gopt` and `popt`, see [ePass Options](./EPASS_OPTIONS.md).
+
+### Use ePass with `libbpf`
+
+We may want to load a ePass-modified program to the kernel to see its effect. ePass provides a modified libbpf that allows users to run ePass before loading programs to the kernel. The advantage is that you do not need to change the kernel. However, running ePass in userspace cannot leverage the verifier, so it cannot use verifier information, cannot run verifier dependent passes, and cannot run kernel passes.
+
+First, initializing all submodules.
+
+```bash
+git submodule update --init --recursive
+```
+
+Now open the `libbpf` source code directory and build:
+
+```bash
+cd third-party/ePass-libbpf/src
+make -j
+```
+
+To install `ePass libbpf`, install:
+
+```bash
+sudo make install
+```
+
+After installing ePass libbpf, you could run any programs that depends on the `libbpf` shared library with `ePass` commands.
+
+For `bpftool`, you need to build `bpftool` because by default it statically link `libbpf`.
+
+An example of using ePass to load `test.o` eBPF program using `bpftool`:
+
+```bash
+sudo LIBBPF_ENABLE_EPASS=1 LIBBPF_EPASS_GOPT="verbose=3" LIBBPF_EPASS_POPT="msan" bpftool prog load test.o /sys/fs/bpf/test
+```