From 2efe5330cb43f685f3159a28ce211392a0bbe3c3 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Thu, 12 Mar 2026 23:28:38 +0200
Subject: docs: finalize libbpfgo upgrade guidance

---
 README.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 7ee0373..a63f6a3 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,29 @@ git -C ../libbpfgo submodule update --init --recursive
 make -C ../libbpfgo libbpfgo-static
 ```
 
+Validated commands for this pin:
+
+```shell
+env GOTOOLCHAIN=auto mage world
+env GOTOOLCHAIN=auto mage integrationTest
+```
+
+Troubleshooting and rollback:
+
+- If builds fail with `bpf/bpf.h` missing, re-run the checkout, submodule sync,
+  and `make libbpfgo-static` commands above, then retry `env GOTOOLCHAIN=auto mage world`.
+- Prefer Mage targets over raw `go test` for packages that import `libbpfgo`;
+  Mage injects the required `CGO_CFLAGS`, `CGO_LDFLAGS`, and `LIBBPFGO` values.
+- To roll back to the previous wrapper state, repin `go.mod` to
+  `github.com/aquasecurity/libbpfgo v0.6.0-libbpf-1.3.0.20240111220235-90dbffffbdab`,
+  then reset the sibling checkout and rebuild:
+
+```shell
+git -C ../libbpfgo checkout 90dbffffbdab
+git -C ../libbpfgo submodule update --init --recursive
+make -C ../libbpfgo libbpfgo-static
+```
+
 ## Timing Semantics
 
 Each reported event pair has two timing counters:
-- 
cgit v1.2.3