Support for eBPF CO-RE #35324

I discussed this with @andrewrk at Zig Day Portland, and I'm creating this issue to track the work and get feedback on the approach.

Background

eBPF is a niche topic that most people aren't familiar with, so I'll provide some background information.

eBPF programs run in the Linux kernel on a dedicated bytecode virtual machine and are used to instrument or control various operations within the Linux kernel. eBPF programs have access to kernel data structures and often dig through them to access process state, filesystem information, etc. The layout, size, alignment, etc of kernel data structures may change from one release to the next or as a result of vendor patches, which means that an eBPF program compiled for one kernel isn't guaranteed to work properly on another kernel.

eBPF "Compile Once - Run Everywhere" (CO-RE) is a mechanism that allows you to compile an eBPF program for one kernel and have it run on another. eBPF CO-RE is an industry standard, and eBPF usage without it is extremely limited.

There are a few moving pieces that make this work:

• BPF Type Format (BTF): debug information for the symbols and data structures in the Linux kernel.
  • An eBPF program compiled into an ELF object has BTF sections embedded into it to keep track of which kernel data structures are used and how they're accessed. In short, BTF is used to keep track of relocations that must be fixed up at load-time.
• libbpf: library developed in-kernel for handling eBPF programs.
  • Performs the necessary relocations before submitting the eBPF program to the kernel.
  • Used by a userspace program on the target machine to perform the necessary relocations before submitting the eBPF program to the kernel.
  • Uses the BTF from the target machine's kernel.
    • See yours using bpftool (warning: produces ~3MB header): bpftool btf dump file /sys/kernel/btf/vmlinux format c >vmlinux.h

Most eBPF programs are written in C, since this is the language that libbpf is written in, and libbpf provides macros (BPF_CORE_READ, etc) for accessing kernel data structures safely. These macros are used to emit compiler intrinsics that emit BTF relocation information.

The LLVM documentation for one of those intrinsics is here: llvm.preserve.struct.access.index. There are corresponding intrinsics for arrays, unions, etc.

Problem

The Zig compiler doesn't emit the intrinsics that tell LLVM to produce the BTF relocations necessary for CO-RE to work properly, which means that Zig can't realistically be used for writing eBPF programs.

Approach

Zig has a concept of pointer address space via the addrspace keyword. The default "userspace" address space is .generic.

The approach here is:

• Add a new .kernel address space.
• Make .kernel the default address space for the bpfel and bpfeb backends.
• Emit the necessary LLVM intrinsics for .kernel pointers.
• Use the existing @addrSpaceCast builtin when creating pointers to userspace memory.

I've already added the new .kernel address space and made it the default for the BPF targets. I'm currently working on emitting the intrinsics in Air.zig.

I'm interested in the usage of the .kernel pointers when writing ebpf program (equivalent to BPF_CORE_READ in C I think ?). Could you please elaborate a little bit on it?

@Totorow wrote in #35324 (comment):

I'm interested in the usage of the .kernel pointers when writing ebpf program (equivalent to BPF_CORE_READ in C I think ?). Could you please elaborate a little bit on it?

Without a more specific question all I can do is try to explain the existing proposal in a different way.

In a normal Zig program that runs in userspace, all pointers are actually *addrspace(.generic) because .generic is the default address space for Zig programs on most platforms. What I'm proposing here is that the default address space in eBPF targets be changed to .kernel so that all pointers in eBPF programs are *addrspace(.kernel) by default instead.

When we access a field through a .kernel pointer, we can emit the same LLVM intrinsics that BPF_CORE_READ does. Those intrinsics say things like "track metadata about this struct field access." Accessing a struct field is done through a "get element pointer" operation, which returns a pointer to the field inside of a struct. Since that pointer is also a .kernel pointer, you'd get the proper intrinsics emitted when accessing nested fields of kernel data structures.

Is there something specific you wanted to know more about?

Aside: I'm also wondering if it would "just work" to emit the intrinsics for everything all the time when the target is eBPF, or if that would generate too much BTF debug info.

I think we could emit the every encountered pointer access in eBPF program at first (except user change the address space with @addrSpaceCast explicitly). This could introduce some unexpected relocations (e.g. user defined structure inside program), maybe we could eliminate them later.

This is something that’s been on my radar for a long time, and I really like the idea of using address space to emit struct access information.

My two cents is that it might be best left off by default, and let the BPF helpers and program signatures set the .kernel address space where appropriate. It documents the boundary between the kernel and our BPF program, and if I was to take an address of a variable in the stack, or a map entry, I would assume they’d be generic.

On another note, I’ve been down the road many times of trying to wrap libbpf in Zig. IMO it’s fine, but generally a PITA. Users would be better served with a pure Zig implementation. I will probably start to write that out once I’m done organizing SYCL.