Skip to content

Commit d9eead0

Browse files
linsykinglinsyking
committed
feat: add submodules
1 parent 535d9a3 commit d9eead0

23 files changed

+101
-77
lines changed

‎.gitmodules‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[submodule "third-party/ePass-xdp-tools"]
2+
path = third-party/ePass-xdp-tools
3+
url = git@github.com:OrderLab/ePass-xdp-tools.git
4+
[submodule "third-party/ePass-falcolib"]
5+
path = third-party/ePass-falcolib
6+
url = git@github.com:OrderLab/ePass-falcolib.git
7+
[submodule "ePass-kernel"]
8+
path = ePass-kernel
9+
url = git@github.com:OrderLab/ePass-kernel.git
10+
[submodule "third-party/ePass-libbpf"]
11+
path = third-party/ePass-libbpf
12+
url = git@github.com:OrderLab/ePass-libbpf.git
13+
[submodule "third-party/ePass-bpftool"]
14+
path = third-party/ePass-bpftool
15+
url = git@github.com:OrderLab/ePass-bpftool.git

‎README.md‎

Lines changed: 28 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,53 @@
11
# ePass
22

3+
[![Build ePass](https://github.com/OrderLab/ePass/actions/workflows/build.yml/badge.svg)](https://github.com/OrderLab/ePass/actions/workflows/build.yml)
4+
35
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.
46
ePass could work 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.
57

6-
## Features
8+
## Key Features
79

810
- **IR-based compilation**: Converts BPF programs to an SSA-based intermediate representation for code rewriting
911
- **Flexible passes**: ePass core provides various APIs to analyze and manipulate the IR, allowing users to write flexible passes including runtime checks and optimization.
1012
- **Command-line interface**: Easy-to-use CLI tool for testing in userspace
1113

14+
> 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.
15+
16+
## Design Goals
17+
18+
- Flexible passes, allowing diverse use cases
19+
- Working with existing verifier instead of replacing its
20+
- Keeping kernel safety
21+
1222
## Prerequisites
1323

1424
- **clang >= 17**
1525
- **Ninja** (optional, for faster compilation)
1626
- **libbpf**
1727

28+
## Project Components
29+
30+
- `ePass core`: the core compiler framework
31+
- `ePass kernel`: Linux kernel 6.5 with ePass core built-in, along with the kernel component and kernel passes
32+
- `ePass libbpf`: libbpf with ePass support for userspace ePass testing
33+
- `ePass bpftool`: support for ePass
34+
1835
## Quick Start
1936

37+
The main development happens in `core` directory. To start, `cd` into `core`.
38+
2039
### Build
2140

2241
```bash
23-
cmake -S . -B build -GNinja
24-
make
42+
make configure # Do it once
43+
44+
make build
2545
```
2646

2747
### Install
2848

2949
```bash
30-
sudo cmake --install build
50+
make install
3151
```
3252

3353
### Basic Usage
@@ -45,32 +65,6 @@ epass print prog.o
4565

4666
## Development
4767

48-
### Build Commands
49-
50-
```bash
51-
# Format code
52-
make format
53-
54-
# Configure build system (run for the first time)
55-
make configure
56-
57-
# Build with generated constructors (run after you create a new instruction)
58-
make buildall
59-
60-
# Default Build
61-
make build
62-
```
63-
64-
### Testing
65-
66-
```bash
67-
# Run integration tests
68-
cd test && ./run_tests.sh
69-
70-
# Run Python test suite
71-
cd test && python test.py
72-
```
73-
7468
### Generate Additional Assets
7569

7670
```bash
@@ -81,46 +75,12 @@ make kernel
8175
make buildobj
8276
```
8377

84-
## Project Structure
85-
86-
```
87-
ePass/
88-
├── core/ # Main compiler implementation
89-
│ ├── include/ # Header files
90-
│ ├── docs/ # Technical documentation
91-
│ ├── passes/ # Optimization passes
92-
│ ├── aux/ # Auxiliary utilities
93-
│ ├── epasstool/ # CLI tool
94-
│ └── tests/ # Simple BPF tests
95-
├── test/ # Integration tests and evaluation
96-
├── rejected/ # Collected rejected programs
97-
└── tools/ # Helper scripts and utilities
98-
```
9978

100-
## Contributing
79+
## Contact and citation
10180

102-
1. Follow the existing code style and patterns
103-
2. Run `make format` before submitting changes
104-
3. Ensure all tests pass
105-
4. Update documentation as needed
81+
Feel free to open an issue for question, bug report or feature request! You could also email xiangyiming2002@gmail.com
10682

107-
## Common Development Patterns
108-
109-
### Iterating Through Instructions
110-
111-
```c
112-
struct ir_basic_block **pos;
113-
array_for(pos, fun->reachable_bbs)
114-
{
115-
struct ir_basic_block *bb = *pos;
116-
struct ir_insn *insn;
117-
list_for_each_entry(insn, &bb->ir_insn_head, list_ptr) {
118-
// Process instruction
119-
}
120-
}
121-
```
83+
## Acknowledgement
12284

123-
## TODO
85+
ePass is sponsoredby OrderLab from University of Michigan.
12486

125-
- [ ] bpf-to-bpf calls
126-
- [ ] Full test suite

‎core/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,11 @@ configure:
2828
cmake -S . -B $(BUILD_DIR) -G Ninja; \
2929
fi
3030

31+
install: build
32+
sudo cmake --install $(BUILD_DIR)
33+
3134
buildobj:
3235
./scripts/buildobj.sh
3336

34-
.PHONY: build format kernel genctor test configure buildobj
37+
.PHONY: build format kernel genctor test configure buildobj install
3538
.DEFAULT_GOAL := build

‎core/TODO.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎core/include/linux/bpf_ir.h‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1124,11 +1124,10 @@ struct ir_value bpf_ir_value_stack_ptr(struct ir_function *fun);
11241124

11251125
struct ir_value bpf_ir_value_r0(struct ir_function *fun);
11261126

1127-
#define VR_POS_STACK_PTR \
1128-
(struct ir_vr_pos) \
1129-
{ \
1130-
.allocated = true, .alloc_reg = BPF_REG_10, .spilled = 0 \
1131-
}
1127+
#define VR_POS_STACK_PTR \
1128+
(struct ir_vr_pos){ .allocated = true, \
1129+
.alloc_reg = BPF_REG_10, \
1130+
.spilled = 0 }
11321131

11331132
struct ir_value bpf_ir_value_norm_stack_ptr(void);
11341133

core/docs/CG.md renamed to docs/CG.md

File renamed without changes.

‎docs/CONTRIBUTION_GUIDE.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Contribution Guide
2+
3+
4+
## Project Structure
5+
6+
```
7+
ePass/
8+
├── core/ # Main compiler implementation
9+
│ ├── include/ # Header files
10+
│ ├── docs/ # Technical documentation
11+
│ ├── passes/ # Optimization passes
12+
│ ├── aux/ # Auxiliary utilities
13+
│ ├── epasstool/ # CLI tool
14+
│ └── tests/ # Simple BPF tests
15+
├── test/ # Integration tests and evaluation
16+
├── rejected/ # Collected rejected programs
17+
└── tools/ # Helper scripts and utilities
18+
```
19+
20+
## Common Development Patterns
21+
22+
### Iterating Through Instructions
23+
24+
```c
25+
struct ir_basic_block **pos;
26+
array_for(pos, fun->reachable_bbs)
27+
{
28+
struct ir_basic_block *bb = *pos;
29+
struct ir_insn *insn;
30+
list_for_each_entry(insn, &bb->ir_insn_head, list_ptr) {
31+
// Process instruction
32+
}
33+
}
34+
```

core/docs/CREATE_INSTRUCTION.md renamed to docs/CREATE_INSTRUCTION.md

File renamed without changes.

core/docs/Common.md renamed to docs/Common.md

File renamed without changes.

core/docs/Config.md renamed to docs/Config.md

File renamed without changes.

0 commit comments

Comments
 (0)