Global Variables, Decl Tags, and package `pin`

Note: the hotfix release 0.17.1 is out. Users are highly encouraged to upgrade.

As we close the door on the year 2024, we're also wrapping up the ebpf-go v0.17 development cycle. This release represents a large body of work and is our largest feature release since BTF.

Users are, as always, highly encouraged to upgrade, and we're looking forward to hearing your feedback on the new Global Variables API. We've been putting this interface trough its paces internally, along with a few eager community members, and we're ready to let the wider community make use of it.

This release also marks the end of our Go 1.21 support; Go 1.22 is required going forward.

Breaking Changes

Before we get to the fun stuff, we need to call out a few breaking changes:

• Global variables with a static qualifier can no longer be rewritten using CollectionSpec.RewriteConstants()! See the section on global variables under major features below.

• program: remove LogSize and VerifierError.Truncated by @lmb in #1526

• prog: add ProgramOptions.LogSizeStart to obtain full log after verifier bug by @ti-mo in #1630

  The ProgramOptions.LogSize field was deprecated and a no-op since 0.16 and has now been removed completely. In its place, a new field was added to obtain full verifier logs when the verifier hits an internal bug. The ProgramOptions.LogSizeStart field controls the starting size of the log buffer. Use this if you have a good understanding of the log size you're expecting, or if you're trying to pull out the full log when the verifier hits an internal bug. The error string now also contains some hints about what happened and how to handle this situation.

• map: remove MapSpec.Freeze field by @ti-mo in #1558

• elf_reader: don't use BPF_F_RDONLY_PROG flag to trigger map freezing by @ti-mo in #1568

  The Freeze field was ambiguous from the start, and has been a source of subtle bugs over the years. Automatic map freezing is now done based solely on map name (.(ro)data prefix). If you were manually setting this flag, consider using a conventional map name instead.

• info: expose ksym info and func info by ProgramInfo by @Asphaltt in #1576

• info: expose more prog jited info by @Asphaltt in #1598

  Some ext_info types in package btf were redefined to enable pulling raw func and line infos out of Program.Info(). These were all types without methods and all unexported fields, but calling them out regardless in case someone's doing unintended advanced things with BTF.

• kallsyms: change Modules caching strategy, cache address lookups by @ti-mo in #1590

  Users attaching bpf programs to kernel symbols should see a marked decrease in allocations made in the library during program creation in the general case. Only used entries are now cached, making kallsyms lookups on subsequent program loads free. In the pathological case (new kernel symbols on every load), scanning is repeated, resulting in more CPU time being used instead of holding on to all kallsyms symbols indefinitely. ProgramSpec.KernelModule() was unexported until further notice.

  Also, bpf2go users should now be able to generate Go bindings as unprivileged users once again. Oops!

Major Features

Easy global variables: introducing ebpf.VariableSpec and ebpf.Variable

• CollectionSpec: add new Variables field to interact with constants and global variables by @ti-mo in #1564
• Collection: add Variables field to interact with global variables by @ti-mo in #1572
• bpf2go: generate assignment structs and Go types for Variables and VariableSpecs by @smagnani96 in #1610

This has been a frequent ask in the community for years, so we finally bit the bullet and committed to an API to interact with global bpf variables through CollectionSpec.Variables and CollectionSpec.Variables. We've published a small guide over on ebpf-go.dev/concepts/global-variables that details how to use them, so we're not going to reiterate here.

See the documentation on the use of the static qualifier! These are no longer considered global variables, and can't be modified at runtime.

bpf2go now also generates objects to be used with CollectionSpec.Assign and .LoadAndAssign(), and also emits Go type declarations for C types used as bpf C variables. Our test coverage was somewhat lacking for the latter, please drop something on the issue tracker if you're noticing surprising bpf2go output.

Note that it's currently not possible to manually create a VariableSpec and wire it up to a CollectionSpec, so if you were previously relying on e.g. manually assembling a CollectionSpec and using RewriteConstants() in tests, this will no longer work. This may land as the API crystallizes and we settle on a good mechanism to enable this. Please reach out on the Cilium Slack if you'd like to see this happen.

Tags!

• btf: export DeclTag and TypeTag by @dylandreimerink in #1548

As you'll notice, the btf.Struct, btf.Union, btf.Member, btf.Typedef, btf.Func and btf.Var have gained a new field: Tags! Set one or more tags on these objects from bpf C using __attribute__((btf_decl_tag("mytag"))) and
you'll find Tags being populated in Go.

There's also the btf.Func.ParamTags field that holds tags declared on individual function parameters. These are part of the Func since they appear only in the function prototype, not in the parameter type itself, since those can appear in many different types. (it does get confusing!)

Also, an honorable mention to btf.TypeTag, which has now been exported. This allows tagging pointers with an arbitrary string value and is mainly used by the Linux verifier to tag kernel pointers, see the __kptr and __kptr_ref macros in Linux' bpf_helpers.h.

Pins!

• pin: new package for loading bpf pins and walking bpffs directories by @ti-mo in #1626

We've added a new root-level package pin, which currently features the Load() and WalkDir() functions. Since all LoadPinned* functions in the library now check for the underlying object's type, we've repurposed the machinery to allow loading an opaque pin and returning a Go object of the right type.WalkDir does what it says on the tin, it walks bpffs directories and invokes a callback that received the loaded object. Super convenient!

Minor Features

We've also added a handful of minor features during this release:

• info: expose additional bpf_prog_info fields in ProgramInfo by @tyrone-wu in #1512
• feat(gen): Make Identifier function configurable by @wdullaer in #1560
• feat(ringbuf): Add AvailableBytes() by @dave-tucker in #1533
• elf_reader: permit multiple .data* sections by @mejedi in #1546
• elf_reader: support referencing weak variables by @ti-mo in #1571
• map: add map_extra, memlock, frozen to MapInfo by @ti-mo in #1570
• feat: add support for untyped extern __ksym variables by @patrickpichler in #1578
• map,prog,link: verify object type in LoadPinned*() by @mtardy in #1581
• features: add HaveV4ISA probe for checking ISA v4 support in the kernel by @smagnani96 in #1608
• elf_reader: support value BTF on ringbuf and perf array maps by @ti-mo in #1628
• map: automatically set CPUMap MaxEntries based on possible CPUs by @learnitall in #1627

Other Changes

Last but not least, there's bugfixes, CI changes and some internal refactoring that happened to eventually make ebpf-go work with ebpf-for-windows. See individual PRs for more context. Stay tuned!

• example/ringbuffer: fix comm len by @florianl in #1531
• docs: make timo code owner by @lmb in #1532
• elf: use elf.EM_NONE instead of unix.EM_NONE by @lmb in #1538
• internal/fdtrace: allow tracing of sys package by @lmb in #1536
• internal: use sentinel error in TestVerifierErrorWrapping by @lmb in #1539
• internal/sys: add constants by @lmb in #1537
• internal: split out linux specific bits into a separate package by @lmb in #1540
• ci/goimports: group cilium/ebpf imports after 3rd party imports by @rgo3 in #1541
• *: remove unused parameters and tautological conditions by @ti-mo in #1549
• internal: remove dependency on x/exp/constraints by @ti-mo in #1557
• go,testdata: drop support for Go 1.21, pin testdata toolchain to 1.23 by @ti-mo in #1563
• map tests queues and refactor by @smagnani96 in #1559
• Update MapType up until Arena, docker run -i, fix RunOptions panic by @ti-mo in #1569
• link: uprobe multi/tracefs kprobe: add context to EINVAL, don't overflow pid_t in tests by @ti-mo in #1574
• testdata: centralize declaration of bpf helpers by @ti-mo in #1579
• GHA: re-enable mainline kernel in testing matrix by @ti-mo in #1583
• btf: Handle Tags when making copies by @mejedi in #1582
• kallsyms: introduce 'reader', an efficient /proc/kallsyms line parser by @ti-mo in #1588
• link: don't crash when calling testLink with a RawLink directly by @lmb in #1593
• internal: add a way to write portable feature tests by @lmb in #1597
• internal: move PlatformPrefix to internal/linux by @lmb in #1599
• rlimit: stub out implementation on non-Linux platforms by @lmb in #1600
• CI: switch arm64 runners to GHA by @lmb in #1601
• prog, map: add nil checks for value marshaller by @aibor in #1609
• Unprivileged objNameAllowsDot, return *btf.Var from Variable{Spec}.Type() by @ti-mo in #1612
• elf: include data sections without references in CollectionSpec by @ti-mo in #1614
• btf: replace decl and type tags with placeholders on unsupported kernels by @ti-mo in #1615
• variable: copy VariableSpec.Type during initial assignment and during copy by @ti-mo in #1616
• Optimize epoll.Wait by using sentinel errors by @def in #1619
• elf: reintroduce unreferenced datasec pruning by @ti-mo in #1621
• kconfig: fix panic handling libbpf_tristate values by @ti-mo in #1622
• README.md: add pin package to the overview by @rgo3 in #1629

New Contributors

• @dave-tucker made their first contribution in #1533
• @tyrone-wu made their first contribution in #1512
• @wdullaer made their first contribution in #1560
• @patrickpichler made their first contribution in #1578
• @def made their first contribution in #1619
• @learnitall made their first contribution in #1627

Full Changelog: v0.16.0...v0.17.0