Hello eBPF Community! I wanted to follow up on an excerpt from the "Happy Birthday BPF" email [1]. > Despite books about BPF and pretty complete documentation at > https://ebpf.io/what-is-ebpf, developers and users complain that the > documentation is spread around. As one of those users who has complained, I'd like to explain why and propose a solution.Before I do, I'd just like to say thank you to everyone who has contributed Current State ============= Firstly, the documentation at ebpf.io does a great job of describing the basics, but defers to the eBPF & XDP Reference [2] for more depth. That guide is a treasure trove of information, but , there are also notable omissions: - A definitive list of program types - A definitive list of map types - Information about which kernel versions they were introduced in, what they are intended for and perhaps even some examples - Documentation for bpf-helpers outside of the manpage This documentation partially exists in bcc [3], but with bcc-style syntax examples. Certain program types are a little more complex and require documentation of their own (see: man tc-bpf) or [4] for BPF_PROG_TYPE_FLOW_DISSECTOR. Other types seem to have no examples or documentation available outside the kernel source, for example BPF_PROG_TYPE_SK_SKB. For understanding CO:RE, BTF and program lifecycle I've found the blog posts on the Facebook eBPF Microsite [5] invaluable. If you're working on a loader other than libbpf, you'll be reading man bpf. If you're working on a compiler or VM, the official documentation for the eBPF instruction set is here [6], but it certainly helps to have this unofficial guide [7] as a reference (and the aforementioned eBPF and XDP reference covers some of this too) as well as this blog post [8]. ... and then of course are the libbpf/bcc/wrapper docs ... Desired State ============= What I would love to see is the following: 1. ebpf.io is the home to all official documentation 2. Documentation arranged from bottom of the stack up a. eBPF VM Instruction Set b. ELF File Format, BTF and CO:RE c. eBPF compilers d. eBPF Syscall Interface e. eBPF Program Types, Map Types and Helpers 3. Docs that then point to the API documentation for libbpf, libxdp, bcc, and various other libraries. I'd be willing to help pull some of this together if there's some agreement that this is necessary and the breakdown is correct. Thanks in advance, - Dave [1]: https://lore.kernel.org/bpf/20210926203409.kn3gzz2eaodflels@xxxxxxxxxxxxxxxxxxxxxxxxxxxx/T/#u [2]: https://docs.cilium.io/en/stable/bpf/ [3]: https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md [4]: https://www.kernel.org/doc/html/latest/bpf/prog_flow_dissector.html [5]: https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html [6]: https://www.kernel.org/doc/Documentation/networking/filter.txt [7]: https://github.com/iovisor/bpf-docs/blob/master/eBPF.md [8]: https://pchaigno.github.io/bpf/2021/10/20/ebpf-instruction-sets.html
