From f15183251411fbd2d740b1b75743bc990ab7afd6 Mon Sep 17 00:00:00 2001
From: Pavlos Tzianos <pavlos@cloudflare.com>
Date: Mon, 24 Jul 2023 17:54:56 +0100
Subject: [PATCH] Update documentation for map definitions for libbpf >= 1.0.0

---
 README.md | 38 ++++++++++++++++++++++++++------------
 hook.h    | 14 ++++++++++++--
 2 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index e420a0e..c6197fc 100644
--- a/README.md
+++ b/README.md
@@ -7,33 +7,47 @@ using standard tcpdump / libpcap filter expressions.
 
 ## Instrumentation
 
-XDP programs need to expose at least one hook point:
+XDP programs need to expose at least one hook point. The hook point uses
+a pinned map to copy packets to the userspace. Depending on the version
+of libbpf you are using you will need to define the map in different ways.
+In either case, the map must conform to the [ABI](https://github.com/cloudflare/xdpcap/blob/master/internal/abi.go).
+
+### Libbpf >= 1.0.0
+
+For versions of libbpf >= 1.0.0 a map should be defined simply as an anonymous
+struct:
 
 ```C
-struct bpf_map_def xdpcap_hook = {
-	.type = BPF_MAP_TYPE_PROG_ARRAY,
-	.key_size = sizeof(int),
-	.value_size = sizeof(int),
-	.max_entries = 4, // The max value of XDP_* constants
-};
+struct {
+  __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
+  __uint(max_entries, 4);
+  __type(key, int);
+  __type(value, int);
+} xdpcap_hook SEC(".maps");
 ```
 
-This map must be [pinned inside a bpffs](https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#bpffs).
+### Libbpf < 1.0.0
 
-`hook.h` provides a convenience macro for declaring such maps:
+If you are using a libbpf version < 1.0.0 `hook.h` provides a convenience macro
+for declaring such maps:
 
 ```
 #include "hook.h"
 
-struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();
+struct bpf_map_def SEC("maps") xdpcap_hook = XDPCAP_HOOK();
 ```
 
-`return XDP_*` statements should be modified to "feed" a hook:
+### Using the map and the hook
+
+This map must be [pinned inside a bpffs](https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#bpffs).
+
+`hook.h` also provides a simple function call that can you use to modidy all
+statements like `return XDP_*`  to "feed" a hook:
 
 ```C
 #include "hook.h"
 
-struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();
+/* xdpcap_hook map definition here */
 
 int xdp_main(struct xdp_md *ctx) {
 	return xdpcap_exit(ctx, &xdpcap_hook, XDP_PASS);
diff --git a/hook.h b/hook.h
index eff3229..2d4092e 100644
--- a/hook.h
+++ b/hook.h
@@ -4,10 +4,20 @@
 #include <linux/bpf.h>
 
 /**
- * Create a bpf map suitable for use as an xdpcap hook point.
+ * If you are using libbpf >= 1.0.0 you need to define a map as follows:
+ * struct {
+ *   __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
+ *   __uint(max_entries, 5);
+ *   __type(key, int);
+ *   __type(value, int);
+ * } xdpcap_hook __section(".maps");
  *
- * For example:
+ * If you are using a libbpf version < 1.0.0 then you can define a map
+ * like this:
  *   struct bpf_map_def xdpcap_hook = XDPCAP_HOOK();
+ *
+ * In either case the map should then be passed to the xdpcap_exit function
+ * to allow xdpcap to hook into the XDP entrypoint and dump the packets.
  */
 #define XDPCAP_HOOK() { \
 	.type = BPF_MAP_TYPE_PROG_ARRAY, \