eBPF Documentation

eBPF Documentation

[Dave Tucker]

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@ast-mbp.dhcp.thefacebook.com/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