[RFC PATCH 11/12] docs/devel: Add userspace-ebpf.rst

[Zhang Chen <chen.zhang@intel.com>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 4278 bytes --]

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

diff --git a/docs/devel/userspace-ebpf.rst b/docs/devel/userspace-ebpf.rst
new file mode 100644
index 0000000000..41eb9b04d6
--- /dev/null
+++ b/docs/devel/userspace-ebpf.rst
@@ -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.
-- 
2.25.1