diff --git a/docs/ebpf/concepts/global-variables.md b/docs/ebpf/concepts/global-variables.md index 1f3c02ecf..ea83e8774 100644 --- a/docs/ebpf/concepts/global-variables.md +++ b/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 diff --git a/docs/examples/variables/main.go b/docs/examples/variables/main.go index abb022afd..ee0ddb7e6 100644 --- a/docs/examples/variables/main.go +++ b/docs/examples/variables/main.go @@ -1,6 +1,10 @@ package main -import "fmt" +import ( + "fmt" + + "github.com/cilium/ebpf" +) func main() { DocVariablesSetConst() @@ -62,8 +66,8 @@ 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) } @@ -71,7 +75,7 @@ func DocVariablesSetGlobal() { // 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{}) { diff --git a/docs/includes/glossary.md b/docs/includes/glossary.md index e3ae3a7b1..bb1f4ae83 100644 --- a/docs/includes/glossary.md +++ b/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.