Background and Motivation

Currently, the bpf2go tool only supports compiling a single source file at a time. This limits our ability to create modular eBPF programs composed of multiple source files. Supporting multiple source files would enable better code organization, reusability, and testability for eBPF programs -- improving the developer experience.

Use Cases

1. Modular Components: Develop reusable eBPF components that can be shared across multiple programs. Complex eBPF programs could be broken into logical components with separate source files
2. Testability: Create test harnesses for eBPF code without including test code in production builds

Concrete Example - RMID Allocation in Unvariance Collector

In the Unvariance Collector project, we need to allocate Resource Monitoring IDs (RMIDs) to processes. These RMIDs come from a limited space (typically 0 to ~460 on certain processors). We want to:

1. Create a library for RMID allocation/deallocation with a free list
2. Track metadata for each RMID and maintain state consistency
3. Test this functionality in isolation
4. Include this code in the main collector without the test harness

Ideally, we would:

• Develop the RMID allocation as a self-contained package with its own header file
• Create a test harness in a separate file that includes and tests this functionality
• Link both during testing
• Link just the RMID allocation code (without test harness) with the main collector

unvariance/collector#109 for more info

Proposed Implementation

After examining the codebase (particularly in cmd/bpf2go), I suggest the following changes:

1. Modify the b2g struct in main.go to accept multiple source files:

   • Change SourceFile string to SourceFiles []string
   • Update the command-line parsing to collect multiple positional arguments

2. Refactor the convert() function:

   • Extract the compilation logic in convert function into compileOne
   • When multiple source files are provided, compile each one in sequence
   • This separation allows compiling multiple source files before linking

3. Add a linking step when multiple source files are provided:

   • Create a new function in the gen package (e.g., Link) similar to existing Compile
   • The function would invoke bpftool gen object to combine multiple object files into one
   • Add the linking step when multiple source files are provided

4. Handle dependencies correctly when multiple files are used:

   • Parse dependencies for each source file (already present)
   • Merge the dependencies into a single set for the final object file (new functionality)
   • Write dependencies (already present)

Backward Compatibility

When only one source file is provided, the tool should behave exactly as it does now. This ensures backward compatibility with existing workflows.

Related Issues and Discussions

• [Discussion #1142](bpf2go should be able to generate Go code from object files built out-of-band #1142): This discussion considered generating Go code from a given object file, which would support this use case by allowing users to create multiple object files out-of-band and use bpftool to link them together. However, as mentioned in that discussion, this approach would require users to understand internal plumbing and handle target-specific details manually. Our proposal solves this by using bpf2go to build all object files automatically without exposing internal complexity.

• [Issue #466](elf: support bpf object linking (bpftool gen object) #466): This issue calls for support of BPF object linking and explicitly mentions bpftool gen object, which we intend to use. However, it focuses specifically on handling weak symbols. While this remains an open issue, users who don't use weak symbols shouldn't encounter these problems with our proposed multi-file support.

I'd be happy to work on implementing this feature. Looking forward to your feedback!