Merge pull request #34 from OrderLab/dev

Basic documentation

Author: linsyking

.github/workflows/build.yml

@@ -0,0 +1,25 @@
+name: Build ePass
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+
+env:
+  BUILD_TYPE: Release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Dependency
+      run: sudo apt install -y libbpf-dev
+
+    - name: Configure CMake
+      run: cd core && make configure
+
+    - name: Build
+      run: cd core && make
+

.gitmodules

@@ -0,0 +1,15 @@
+[submodule "third-party/ePass-xdp-tools"]
+	path = third-party/ePass-xdp-tools
+	url = git@github.com:OrderLab/ePass-xdp-tools.git
+[submodule "third-party/ePass-falcolib"]
+	path = third-party/ePass-falcolib
+	url = git@github.com:OrderLab/ePass-falcolib.git
+[submodule "ePass-kernel"]
+	path = ePass-kernel
+	url = git@github.com:OrderLab/ePass-kernel.git
+[submodule "third-party/ePass-libbpf"]
+	path = third-party/ePass-libbpf
+	url = git@github.com:OrderLab/ePass-libbpf.git
+[submodule "third-party/ePass-bpftool"]
+	path = third-party/ePass-bpftool
+	url = git@github.com:OrderLab/ePass-bpftool.git

README.md

@@ -1 +1,68 @@
 # ePass
+
+[![Build ePass](https://github.com/OrderLab/ePass/actions/workflows/build.yml/badge.svg)](https://github.com/OrderLab/ePass/actions/workflows/build.yml)
+
+ePass is an in-kernel LLVM-like compiler framework that introduces an SSA-based intermediate representation (IR) for eBPF programs. It provides a lifter that lifts eBPF bytecode to ePass IR, a pass runner that runs user-defined passes, and a code generator that compiles IR to eBPF bytecode. Users could write flexible passes using our LLVM-like APIs to analyze and manipulate the IR.
+ePass also provides an in-kernel supervisor that cooperates ePass core with the verifier to improve its flexibility (i.e. reduce false rejections) and safety (i.e. reduce false acceptance at runtime). It could also be used in userspace for testing.
+
+## 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 static analyzing, runtime checks, and optimization.
+- **Verifier aware**: ePass works with the existing verifier. The verifier is better for static verification while ePass focuses more on code rewriting and runtime verification.
+- **User-friendly debugging**: ePass supports compiling to both kernel and userspace for easier debugging.
+
+> ⚠️ Warning: ePass is under active development and we are improving its usability and safety for production use. We welcome any suggestions and feedback. Feel free to open issues or [contact us](#contact-and-citation).
+
+## Design Goals
+
+- Flexible passes for diverse use cases
+- Working with existing verifier instead of replacing its
+- Keeping kernel safety
+- Support both userspace and kernel
+
+## Prerequisites
+
+- **clang >= 17**
+- **Ninja** (optional, for faster compilation)
+- **libbpf**
+
+## Project Components
+
+- `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
+
+There are some testing projects including `bpftool`, `xdp-tools`, `falcolib` in `third-party`. They depend on `ePass libbpf`.
+
+### ePass Overview
+
+![Overview](./docs/overview.png)
+
+### ePass Core
+
+![Core Architecture](./docs/core_design.png)
+
+## Quick Start
+
+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).
+
+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).
+
+We recommend users trying ePass in userspace before switching to the ePass kernel version!
+
+## Testing
+
+See [Testing](./docs/TESTING.md).
+
+## 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>.
+
+## Acknowledgement
+
+ePass is sponsored by [OrderLab](https://orderlab.io/) from University of Michigan.

core/Makefile

@@ -28,8 +28,11 @@ configure:
 		cmake -S . -B $(BUILD_DIR) -G Ninja; \
 	fi
 
+install: build
+	sudo cmake --install $(BUILD_DIR)
+
 buildobj:
 	./scripts/buildobj.sh
 
-.PHONY: build format kernel genctor test configure buildobj
+.PHONY: build format kernel genctor test configure buildobj install
 .DEFAULT_GOAL := build

core/Readme.md

@@ -0,0 +1,34 @@
+# Contribution Guide
+
+
+## Project Structure
+
+```
+ePass/
+├── core/                 # Main compiler implementation
+│   ├── include/          # Header files
+│   ├── docs/             # Technical documentation
+│   ├── passes/           # Optimization passes
+│   ├── aux/              # Auxiliary utilities
+│   ├── epasstool/        # CLI tool
+│   └── tests/            # Simple BPF tests
+├── test/                 # Integration tests and evaluation
+├── rejected/             # Collected rejected programs
+└── tools/                # Helper scripts and utilities
+```
+
+## Common Development Patterns
+
+### Iterating Through Instructions
+
+```c
+struct ir_basic_block **pos;
+array_for(pos, fun->reachable_bbs)
+{
+    struct ir_basic_block *bb = *pos;
+    struct ir_insn *insn;
+    list_for_each_entry(insn, &bb->ir_insn_head, list_ptr) {
+        // Process instruction
+    }
+}
+```

core/TODO.md

@@ -0,0 +1 @@
+# Create New Instruction