docs: add 'Global Variables' page to document VariableSpec

Signed-off-by: Timo Beckers <timo@isovalent.com>

Author: ti-mo

docs/ebpf/concepts/global-variables.md

@@ -0,0 +1,121 @@
+{{ linux_version("5.2", "For all global variable-related BPF operations,
+the kernel needs to understand the BPF_PSEUDO_MAP_VALUE value in ldimm64
+instructions. This is needed for direct, lookup-free map access." )}}
+
+Like typical C programs, BPF programs allow the use of global variables. These
+variables can be initialized from the BPF C code itself, or they can be modified
+by the loading user space application before handing it off to the kernel.
+
+The abstraction {{ proj }} provides to interact with global variables is the
+{{ godoc('VariableSpec') }}, found in the {{ godoc('CollectionSpec.Variables') }}
+field. This page describes how to declare variables in BPF C and how to interact
+with them in Go.
+
+## Runtime Constants
+
+{{ linux_version("5.2", "Read-only maps and the BPF_MAP_FREEZE command are needed
+for implementing constant variables.") }}
+
+Global runtime constants are typically used for configuration values that
+influence the functionality of a BPF program. Think all sorts of network or
+hardware addresses for network filtering, or timeouts for rate limiting. The C
+compiler will reject any runtime modifications to these variables in the BPF
+program, like a typical const.
+
+Crucially, the BPF verifier will also perform dead code analysis if constants
+are used in if statements. If a condition is always true or false, it will
+remove unused code paths from the BPF program, reducing verification time and
+increasing runtime performance.
+
+This enables many features like portable kfuncs, allowing C code to refer to
+kfuncs that may not exist in some kernels, as long as those code paths are
+guaranteed not to execute at runtime. Similarly, this can be used to your
+advantage to disable code paths that are not needed in certain configurations,
+or would result in a verifier error on some kernels or in some contexts.
+
+:ebee-color: Consider the following C BPF program that reads a global constant
+and returns it:
+
+{{ c_example('variables_const', title='BPF C program declaring global constant const_u32') }}
+
+??? warning "Why is `const_u32` declared `volatile`?"
+
+    In short: without the `volatile` qualifier, the variable would be optimized
+    away and not appear in the BPF object file, leaving us unable to modify it
+    from our user space application.
+
+    In this program, the compiler (in)correctly deduces two things about `const_u32`:
+    it is never assigned a value, and it doesn't change over the course of the program.
+    Implementation details aside, it will now assume that the return value of
+    `const_example()` is always 0 and omit the variable from the ELF altogether.
+
+    For BPF programs, it's common practice to declare all global variables that
+    need to be accessed from user space as `volatile`, especially non-`const`
+    globals. Doing so ensures the compiler reliably allocates them in a data
+    section in the ELF.
+
+:simple-go: First, let's take a look at a full Go example that will comprise the
+majority of interactions with constants. In the example below, we'll load a BPF
+object from disk, pull out a variable, set its value and call the BPF program
+once with an empty context. Variations on this pattern will follow later.
+
+{{ go_example('DocVariablesSetConst', title='Go program modifying a const, loading and running the BPF program') }}
+
+1. Any values passed into {{ godoc('VariableSpec.Set') }} must marshal to a
+   fixed width. This behaviour is identical to {{ godoc('Map.Put') }} and
+   friends. Using untyped integers is not supported since their size is platform
+   dependent. We recommend the same approach in BPF C to keep data size
+   predictable.
+2. A 15-byte context is the minimum the kernel will accept for dry-running a BPF
+   program. If your BPF program reads from its context, populating this slice is
+   a great way of doing unit testing without setting up a live testing environment.
+
+## Global Variables
+
+Non-const global variables are mutable and can be modified by both the BPF
+program and the user space application. They are typically used for keeping
+state like metrics, counters, rate limiting, etc.
+
+These variables can also be initialized from user space, much like their `const`
+counterparts, and can be both read and written to from the BPF program as well
+as the user space application. More on that in a future section.
+
+:ebee-color: The following C BPF program reads a global variable and returns it:
+
+{{ c_example('variables_global', title='BPF C program declaring global variable global_u16') }}
+
+??? warning "Why is `global_u16` declared `volatile`?"
+
+    Similar to `volatile const` in a prior example, `volatile` is used here to
+    make compiler output more deterministic. Without it, the compiler may
+    choose to optimize away a variable if it's never assigned to, not knowing
+    its value is actually provided by user space. The `volatile` qualifier
+    doesn't change the variable's semantics.
+
+:simple-go: Next, in user space, initialize `global_u16` to 9000:
+
+{{ go_example('DocVariablesSetGlobalU16') }}
+
+Dry-running `global_example()` a few times results in our value increasing on
+every invocation:
+
+{{ go_example('DocVariablesSetGlobalRun') }}
+
+## Internal/Hidden Global Variables
+
+By default, all global variables described in an ELF's data sections are exposed
+through {{ godoc('CollectionSpec.Variables') }}. However, there may be cases
+where you don't want user space to interfere with a variable (either on purpose
+or by accident) and you want to keep the variable internal to the BPF program.
+
+{{ c_example('variables_hidden', title='BPF C program declaring internal global variable internal_var') }}
+
+The `__hidden` macro is found in Linux' `<bpf/bpf_helpers.h>` as of version 5.13
+and is defined as follows:
+
+```c
+#define __hidden __attribute__((visibility("hidden")))
+```
+
+This will cause the VariableSpec for `hidden_var` to not be included in
+the CollectionSpec. 

docs/ebpf/concepts/section-naming.md

@@ -93,36 +93,35 @@ called `kprobe/slub_flush`.
 
 #### :material-head-cog: Advanced: Special Map Sections
 
-`.data`
+`.data*`
 
 :   The LLVM BPF backend implements accesses to mutable global variables as
     direct Array Map accesses. Since a single BPF program can be executed
     concurrently as a result of the kernel processing packets and other events
-    asynchronously, `.data` and the global variables it represents are
+    asynchronously, a data section and the global variables it represents are
     considered shared memory.
 
-    This section is exposed by {{ godoc('CollectionSpec.Maps') }} as a
-    single-element BPF array and its contents are accessible through {{
-    godoc('MapSpec.Contents') }}. Its layout is described by its {{
-    godoc('MapSpec.Value') }}, a {{ godoc('btf/Datasec') }} containing all
-    global variables in the compilation unit.
+    Variables can be emitted to specific sections, like
+    `#!c SEC(".data.foo") my_var = 123;`, as long as they match the `.data*`
+    prefix. This can prove useful for isolating certain variables to well-known
+    sections for Go code generation or custom variable rewriting logic.
 
-    The contents of the Map may be modified to control the default values
-    used for the eBPF program's global variables.
+    Global, non-hidden variables are emitted to
+    {{ godoc('CollectionSpec.Variables') }}, where they can be modified before
+    loading the CollectionSpec into the kernel. See
+    [Global Variables](../concepts/global-variables.md) for instructions.
 
 `.rodata*`
 
-:   Like `.data`, but for constants. This is a prefix and matches sections like
-    `.rodata.foo`. Constants can be emitted to different sections using e.g.
-    `#!c SEC(".rodata.foo") volatile const foobar = 123;`. This can prove useful
-    for isolating certain constants to well-known sections for Go code
-    generation or custom constant rewriting logic.
+:   Like `.data*`, but for constants. These become read-only after loading the
+    CollectionSpec into the kernel, and are also exposed through
+    {{ godoc('CollectionSpec.Variables') }}.
 
 `.bss`
 
 :   Section emitted by the compiler when zero-initialized globals are present in
-    the ELF. Is typically zero-length. Exposed by {{
-    godoc('CollectionSpec.Maps') }}, but not really useful.
+    the ELF. Is typically zero-length in the ELF, and initialized by {{ proj }}
+    after loading. Also exposed through {{ godoc('CollectionSpec.Variables') }}.
 
 `.rel*`
 

docs/examples/variables/gen.go

@@ -0,0 +1,3 @@
+package main
+
+//go:generate go run github.com/cilium/ebpf/cmd/bpf2go variables variables.c

docs/examples/variables/main.go

@@ -0,0 +1,91 @@
+package main
+
+import "fmt"
+
+func main() {
+	DocVariablesSetConst()
+	DocVariablesSetGlobal()
+}
+
+// Full example written to be displayed in its entirety, so is commented generously.
+func DocVariablesSetConst() {
+	// Load the object file from disk using a bpf2go-generated scaffolding.
+	spec, err := loadVariables()
+	if err != nil {
+		panicf("loading CollectionSpec: %s", err)
+	}
+
+	// Set the 'const_u32' variable to 42 in the CollectionSpec.
+	want := uint32(42) // (1)!
+	if err := spec.Variables["const_u32"].Set(want); err != nil {
+		panicf("setting variable: %s", err)
+	}
+
+	// Load the CollectionSpec.
+	//
+	// Note: modifying spec.Variables after this point is ineffectual!
+	// Modifying *Spec resources does not affect loaded/running BPF programs.
+	var obj variablesPrograms
+	if err := spec.LoadAndAssign(&obj, nil); err != nil {
+		panicf("loading BPF program: %s", err)
+	}
+
+	fmt.Println("Running program with const_u32 set to", want)
+
+	// Dry-run the BPF program with an empty context.
+	ret, _, err := obj.ConstExample.Test(make([]byte, 15)) // (2)!
+	if err != nil {
+		panicf("running BPF program: %s", err)
+	}
+
+	if ret != want {
+		panicf("unexpected return value %d", ret)
+	}
+
+	fmt.Println("BPF program returned", ret)
+
+	// Output:
+	// Running program with const_u32 set to 42
+	// BPF program returned 42
+}
+
+func DocVariablesSetGlobal() {
+	spec, err := loadVariables()
+	if err != nil {
+		panicf("loading CollectionSpec: %s", err)
+	}
+
+	// DocVariablesSetGlobalU16 {
+	set := uint16(9000)
+	if err := spec.Variables["global_u16"].Set(set); err != nil {
+		panicf("setting variable: %s", err)
+	}
+	// }
+
+	var obj variablesPrograms
+	if err := spec.LoadAndAssign(&obj, nil); err != nil {
+		panicf("loading BPF program: %s", err)
+	}
+
+	fmt.Println("Running program with global_u16 set to", set)
+
+	// DocVariablesSetGlobalRun {
+	for range 3 {
+		ret, _, err := obj.GlobalExample.Test(make([]byte, 15))
+		if err != nil {
+			panicf("running BPF program: %s", err)
+		}
+		fmt.Println("BPF program returned", ret)
+	}
+
+	// Output:
+	// Running program with global_u16 set to 9000
+	// BPF program returned 9000
+	// BPF program returned 9001
+	// BPF program returned 9002
+	// }
+}
+
+func panicf(format string, args ...interface{}) {
+	panic(fmt.Sprintf(format, args...))
+}

docs/examples/variables/variables.c

@@ -0,0 +1,33 @@
+//go:build ignore
+
+#include <linux/bpf.h>
+#include <bpf/bpf_helpers.h>
+
+// Remove when toolchain Docker image ships with 5.13+ headers.
+#define __hidden __attribute__((visibility("hidden")))
+
+// variables_const {
+volatile const __u32 const_u32;
+
+SEC("socket") int const_example() {
+	return const_u32;
+}
+// }
+
+// variables_global {
+volatile __u16 global_u16;
+
+SEC("socket") int global_example() {
+	global_u16++;
+	return global_u16;
+}
+// }
+
+// variables_hidden {
+__hidden __u64 hidden_var;
+
+SEC("socket") int hidden_example() {
+	hidden_var++;
+	return hidden_var;
+}
+// }