new file mode 100644
@@ -0,0 +1,106 @@
+===========================
+Userspace eBPF support
+===========================
+
+eBPF is a revolutionary technology with origins in the Linux kernel that
+can run sandboxed programs in an operating system kernel. It is used to
+safely and efficiently extend the capabilities of the kernel without
+requiring to change kernel source code or load kernel
+modules.(from https://ebpf.io/)
+
+Recently, I worked on QEMU net filter related jobs, like netfilter/iptables
+in kernel. We noticed kernel extend the netfilter original cBPF to eBPF,
+
+It make Linux kernel have the ability to load code dynamically. Why not
+enable user space eBPF in QEMU? It can load binary eBPF program even
+when VM running. Add some hooks in QEMU as the user space eBPF load point.
+Do the things on different layers. The original idea from Jason Wang.
+
+
+That’s the advantages of kernel eBPF. Most of the functions can be
+implemented in QEMU. The Power of Programmability.
+
+ 1). Safety:
+
+ Building on the foundation of seeing and understanding all system
+ calls and combining that with a packet and socket-level view of all
+ networking operations allows for revolutionary new approaches to
+ securing systems.
+
+ 2). Tracing & Profiling:
+
+ The ability to attach eBPF programs to trace points as well as kernel
+ and user application probe points allows unprecedented visibility into
+ the runtime behavior of applications and the system itself.
+
+ 3). Networking:
+
+ The combination of programmability and efficiency makes eBPF a natural
+ fit for all packet processing requirements of networking solutions.
+
+ 4). Observability & Monitoring:
+
+ Instead of relying on static counters and gauges exposed by the
+ perating system, eBPF enables the collection & in-kernel aggregation
+ of custom metrics and generation of visibility events based on a wide
+ range of possible sources.
+
+ Qemu userspace ebpf design based on ubpf project (https://github.com/iovisor/ubpf).
+ The most mature userspace ebpf implementation. This project officially
+ support by iovisor(Like BCC and bpftrace). Qemu userspace ebpf make
+ the ubpf project as the git submodule.
+
+ Current implementation support load ebpf program and run it in
+ filter-ubpf module, developer can easy reuse the ubpf function in
+ Qemu's other modules from the function in /ebpf/ubpf.c, And it support JIT.
+ For the uBPF License is Apache License 2.0, It's OK to compatible
+ with QEMU’s GPLv2 LICENSE same as mason.
+
+ How to use it:
+ 1. Write your ebpf C program. For example filter dst IP:
+
+ bpf_filter.c
+
+#include <arpa/inet.h>
+#include <stdint.h>
+
+#define ONE_ONE_ONE_ONE 0x01010101
+
+struct ipv4_header {
+ uint8_t ver_ihl;
+ uint8_t tos;
+ uint16_t total_length;
+ uint16_t id;
+ uint16_t frag;
+ uint8_t ttl;
+ uint8_t proto;
+ uint16_t csum;
+ uint32_t src;
+ uint32_t dst;
+};
+
+int is_dst_one_one_one_one(void *opaque) {
+ struct ipv4_header *ipv4_header = (struct ipv4_header*)opaque;
+
+ if (ntohl(ipv4_header->dst) == ONE_ONE_ONE_ONE) {
+ return 1;
+ }
+
+ return 0;
+}
+
+ 2. Build it with clang:
+ clang -O2 -target bpf -c bpf_filter.c -o ip_dst.o
+
+ 3. Load it with Qemu filter-ubpf:
+ -object filter-ubpf,netdev=hn0,id=ubpf1,queue=tx,ip-mode=on,
+ ubpf-handler=ip_dst.o
+
+ 4. Boot the VM and it will filt IP dst 1.1.1.1 packet.
+
+
+TODO: Need to add more comments and test-case for ubpf, current
+ implementation not include ebpf verifier. Qemu is a userspace
+ program, not like kernel ebpf run code in kernel space, I think
+ if the someone want to hack Qemu code no need to load a malicious
+ ubpf program, he can hack Qemu code directly.
Introduce userspace ebpf basic knowledge. Signed-off-by: Zhang Chen <chen.zhang@intel.com> --- docs/devel/userspace-ebpf.rst | 106 ++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/devel/userspace-ebpf.rst