docs: briefly document Variable and Collection.Variables

Add a little blurb to distinguish VariableSpec and Variable and clarify the
difference between accessing globals before and after loading.

Signed-off-by: Timo Beckers <[email protected]>

Author: ti-mo

docs/ebpf/concepts/global-variables.md

@@ -92,15 +92,40 @@ as the user space application. More on that in a future section.
     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:
+### Before Loading: Using VariableSpec
+
+For interacting with global variables before loading the BPF program into the
+kernel, use the methods on its {{ godoc('VariableSpec') }} found in {{
+godoc('CollectionSpec.Variables') }} or injected using {{ godoc('LoadAndAssign')
+}}. This ensures the variable is populated before the BPF program has a chance
+to execute.
+
+:simple-go: In user space, initialize `global_u16` to 9000:
 
 {{ go_example('DocVariablesSetGlobalU16') }}
 
-Dry-running `global_example()` a few times results in our value increasing on
+Dry-running `global_example()` a few times results in the value increasing on
 every invocation:
 
 {{ go_example('DocVariablesSetGlobalRun') }}
 
+Once a CollectionSpec has been loaded into the kernel, further modifications
+to a VariableSpec are ineffectual.
+
+### After Loading: Using Variable
+
+After loading the BPF program into the kernel, accessing global variables from
+user space can be done through the {{ godoc('Variable') }} abstraction. These
+can be injected into an object using {{ godoc('LoadAndAssign') }}, or found in
+the {{ godoc('Collection.Variables') }} field.
+
+:simple-go: Building on the previous example, read the incremented variable
+using {{ godoc('Variable.Get') }}:
+
+{{ go_example('DocVariablesGetGlobalU16') }}
+
+Modify the Variable at runtime using {{ godoc('Variable.Set') }}.
+
 ## Internal/Hidden Global Variables
 
 By default, all global variables described in an ELF's data sections are exposed

docs/examples/variables/main.go

@@ -1,6 +1,10 @@
 package main
 
-import "fmt"
+import (
+	"fmt"
+
+	"github.com/cilium/ebpf"
+)
 
 func main() {
 	DocVariablesSetConst()
@@ -62,16 +66,16 @@ func DocVariablesSetGlobal() {
 	}
 	// }
 
-	var obj variablesPrograms
-	if err := spec.LoadAndAssign(&obj, nil); err != nil {
+	coll, err := ebpf.NewCollection(spec)
+	if 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))
+		ret, _, err := coll.Programs["global_example"].Test(make([]byte, 15))
 		if err != nil {
 			panicf("running BPF program: %s", err)
 		}
@@ -84,6 +88,17 @@ func DocVariablesSetGlobal() {
 	// BPF program returned 9001
 	// BPF program returned 9002
 	// }
+
+	// DocVariablesGetGlobalU16 {
+	var global_u16 uint16
+	if err := coll.Variables["global_u16"].Get(&global_u16); err != nil {
+		panicf("getting variable: %s", err)
+	}
+	fmt.Println("Variable global_u16 is now", global_u16)
+
+	// Output:
+	// Variable global_u16 is now 9003
+	// }
 }
 
 func panicf(format string, args ...interface{}) {

docs/includes/glossary.md

@@ -6,8 +6,9 @@
 *[ELF]: Executable and Linkable Format, a container format used for compiled eBPF programs.
 *[Spec]: Unrealized blueprint of an eBPF resource, e.g. MapSpec, ProgramSpec, btf.Spec.
 *[CollectionSpec]: Bundle of ProgramSpecs, MapSpecs and a btf.Spec. Direct result of loading an eBPF ELF.
-*[VariableSpec]: Setter/getter for a global variable declared in an eBPF program.
+*[VariableSpec]: Accessor for a global variable declared in an eBPF program.
 *[Collection]: Bundle of Maps and Programs that were loaded into the kernel. Direct result of instantiating (loading into the kernel) a CollectionSpec.
+*[Variable]: Accessor for a global variable declared in an eBPF program, used after loading.
 *[bpffs]: Birtual filesystem for 'pinning' references to eBPF resources in an familiar file hierarchy. Usually mounted at /sys/fs/bpf, but many individual instances can be mounted.
 *[helper]: A piece of logic provided by the kernel. Read a map value, redirect a packet, etc.
 *[kfunc]: An extensible evolution of the BPF helper mechanism. Can be dynamically provided by kernel modules. Not specified in UAPI.