The whole BPF verifier and development process is so botched, it's ridiculous. It's like maintainers decided to make this as hard as possible out of pettiness and "they have to use C APIs instead" or something.
- Loading an eBPF module without the CAP_BPF (and in some cases without the CAP_NET_ADMIN which you need for XDP) capabilities will generate a "unknown/invalid memory access" error which is super useless as an error message.
- In my personal opinion a bytecode format for both little endian (bpfel) and big endian (bpfeb) machines is kinda unnecessary. I mean, it's a virtual bytecode format for a reason, right!?
- Compiling eBPF via clang to the bpf bytecode format without debug symbols will make every following error message down the line utterly useless. Took me a while to figure out what "unknown scalar" really means. If you forget that "-g" flag you're totally fucked.
- Anything pointer related that eBPF verifier itself doesn't support will lead to "unknown scalar" errors which are actually out of bounds errors most of the time (e.g. have to use if pointer - The bpftool maintainer is kind of unfriendly, he's telling you to read a book about the bytecode format if your code doesn't compile and you're asking about examples on how to use pointers inside a BPF codebase because it seems to enforce specific rules in terms of what kind of method (__always_static) are allowed to modify or allocate memory. There's a lot of limitations that are documented _nowhere_ on the internet, and seemingly all developers are supposed to know them by reading the bpftool codebase itself!? Who's the audience for using the bpftool then? Developers of the bpftool itself?
- The BCC tools (bpf compiler collection) are still using examples that can't compile on an up-to-date kernel. [1] If you don't have the old headers, you'll find a lot of issues that show you the specific git hash where the "bpf-helpers.h" file was still inside the kernel codebase.
- The libbpf repo contain also examples that won't compile. Especially the xdp related ones [2]
- There's also an ongoing migration of all projects (?) to xdp-tools, which seems to be redundant in terms of bpf related topics, but also has only a couple examples that somehow work [3]
- Literally the only userspace eBPF generation framework that worked outside a super outdated enterprise linux environment is the cilium ebpf project [4], but only because they're using the old "bpf-helpers.h" file that are meanwhile removed from the kernel itself. [5] They're also incomplete for things like the new "__u128" and "__bpf_helper_methods" syntax which are sometimes missing.
- The only working examples that can also be used for reference on "what's available" in terms of eBPF and kernel userspace APIs is a forked repo of the bootlin project [6] which literally taught me how to use eBPF in practice.
- All other (official?) examples show you how to make a bpf_printk call, but _none_ of them show you how to even interact with bpf maps (whose syntax changed like 5 times over the course of the last years, and 4 of them don't run through the verifier, obviously). They're also somewhat documented in the wiki of the libbpf project, without further explanation on why or what [7]. Without that bootlin repo I still would have no idea other than how to make a print inside a "kretprobe". Anything more advanced is totally undocumented.
- OpenSnitch even has a workflow that copies their own codebase inside the kernel codebase, just to make it compile - because all other ways are too redundant or too broken. Not kidding you. [8]
Note that none of any BPF related projects uses any kind of reliable version scheme, and none of those project uses anything "modern" like conan (or whatever) as a package manager. Because that would have been too easy to use, and too easy on documenting on what breaks when. /s
Overall I have to say, BPF was the worst development experience I ever had. Writing a kernel module is _easier_ than writing a BPF module, because then you have at least reliable tooling. In the BPF world, anything will and can break at any unpredictable moment. If you compare that to the experience of other development environments like say, JVM or even the JS world, where debuggers that interact with JIT compilers are the norm, well ... then you've successfully been transferred back to the PTSD moments of the 90s.
Honestly I don't know how people can use BPF and say "yeah this has been a great experience and I love it" and not realize how broken the tooling is on every damn level.
I totally recommend reading the book [9] and watching the YouTube videos of Liz Rice [10]. They're awesome, and they show you how to tackle some of the problems I mentioned. I think that without her work, BPF would have had zero chance of success.
What's missing in the BPF world is definitely better tooling, better error messages (e.g. "did you forget to do this?" or even "unexpected statement" would be sooooo much better than the current state), and an easier way to debug an eBPF program. Documentation on what's available and what is not is also necessary, because it's impossible to find out right now. If I am not allowed to use pointers or whatever, then say so in the beginning.
[1] https://github.com/iovisor/bcc
[2] https://github.com/libbpf/libbpf
[3] https://github.com/xdp-project/xdp-tools
[4] https://github.com/cilium/ebpf/
[5] https://github.com/cilium/ebpf/tree/master/examples/headers
[6] https://elixir.bootlin.com/linux/latest/source/tools/testing...
[7] https://github.com/libbpf/libbpf/wiki/Libbpf-1.0-migration-g...
[8] https://github.com/evilsocket/opensnitch/blob/master/ebpf_pr...
[9] https://isovalent.com/learning-ebpf/
[10] (e.g.) https://www.youtube.com/watch?v=L3_AOFSNKK8