libbpf/ebpf: Add pages for bpf_tracing.h macros

Added pages for macros defined in `bpf_tracing.h`.

Signed-off-by: Dylan Reimerink <[email protected]>

docs/ebpf-library/libbpf/ebpf/BPF_KPROBE.md

@@ -0,0 +1,65 @@
+---
+title: "Libbpf eBPF macro 'BPF_KPROBE'"
+description: "This page documents the 'BPF_KPROBE' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_KPROBE`
+
+[:octicons-tag-24: v0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
+
+The `BPF_KPROBE` macro makes it easier to write [kprobe](../../../linux/program-type/BPF_PROG_TYPE_KPROBE.md) programs.
+
+!!! note
+    The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
+
+## Definition
+
+```c
+#define BPF_KPROBE(name, args...)					    \
+name(struct pt_regs *ctx);						    \
+static __always_inline typeof(name(0))					    \
+____##name(struct pt_regs *ctx, ##args);				    \
+typeof(name(0)) name(struct pt_regs *ctx)				    \
+{									    \
+	_Pragma("GCC diagnostic push")					    \
+	_Pragma("GCC diagnostic ignored \"-Wint-conversion\"")		    \
+	return ____##name(___bpf_kprobe_args(args));			    \
+	_Pragma("GCC diagnostic pop")					    \
+}									    \
+static __always_inline typeof(name(0))					    \
+____##name(struct pt_regs *ctx, ##args)
+```
+
+## Usage
+
+This macro is useful when writing kprobe programs that attach at the start of a function. Traditionally a program author would have to use the [`PT_REGS_PARAM`](PT_REGS_PARM.md) macros to extract a given parameter from the context and then manually cast them to the actual type.
+
+The `BPF_KPROBE` macro allows you to write your program with an argument list, the macro will do the casting for you. This makes reading and writing kprobes easier.
+
+### Example
+
+```c hl_lines="2"
+SEC("kprobe/bpf_map_copy_value")
+int BPF_KPROBE(bpf_prog2, struct bpf_map *map)
+{
+	u32 key = bpf_get_smp_processor_id();
+	struct bpf_perf_event_value *val, buf;
+	enum bpf_map_type type;
+	int error;
+
+	type = BPF_CORE_READ(map, map_type);
+	if (type != BPF_MAP_TYPE_HASH)
+		return 0;
+
+	error = bpf_perf_event_read_value(&counters, key, &buf, sizeof(buf));
+	if (error)
+		return 0;
+
+	val = bpf_map_lookup_elem(&values2, &key);
+	if (val)
+		*val = buf;
+	else
+		bpf_map_update_elem(&values2, &key, &buf, BPF_NOEXIST);
+
+	return 0;
+}
+```

docs/ebpf-library/libbpf/ebpf/BPF_KPROBE_SYSCALL.md

@@ -0,0 +1,10 @@
+---
+title: "Libbpf eBPF macro 'BPF_KPROBE_SYSCALL'"
+description: "This page documents the 'BPF_KPROBE_SYSCALL' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_KPROBE_SYSCALL`
+
+[:octicons-tag-24: v0.7.0](https://github.com/libbpf/libbpf/releases/tag/v0.7.0)
+
+The `BPF_KPROBE_SYSCALL` macro is the original name of [`BPF_KSYSCALL`](BPF_KSYSCALL.md). As of [:octicons-tag-24: v1.0.0](https://github.com/libbpf/libbpf/releases/tag/v1.0.0) it is an alias to [`BPF_KSYSCALL`](BPF_KSYSCALL.md) for backwards compatibility.
+

docs/ebpf-library/libbpf/ebpf/BPF_KRETPROBE.md

@@ -0,0 +1,49 @@
+---
+title: "Libbpf eBPF macro 'BPF_KRETPROBE'"
+description: "This page documents the 'BPF_KRETPROBE' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_KRETPROBE`
+
+[:octicons-tag-24: v0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
+
+The `BPF_KRETPROBE` macro makes it easier to write [kretprobe](../../../linux/program-type/BPF_PROG_TYPE_KPROBE.md) programs.
+
+## Definition
+
+```c
+#define BPF_KRETPROBE(name, args...)					    \
+name(struct pt_regs *ctx);						    \
+static __always_inline typeof(name(0))					    \
+____##name(struct pt_regs *ctx, ##args);				    \
+typeof(name(0)) name(struct pt_regs *ctx)				    \
+{									    \
+	_Pragma("GCC diagnostic push")					    \
+	_Pragma("GCC diagnostic ignored \"-Wint-conversion\"")		    \
+	return ____##name(___bpf_kretprobe_args(args));			    \
+	_Pragma("GCC diagnostic pop")					    \
+}									    \
+static __always_inline typeof(name(0)) ____##name(struct pt_regs *ctx, ##args)
+```
+
+## Usage
+
+This macro is useful when writing kprobe programs that attach at the start of a function. Traditionally a program author would have to use the [`PT_REGS_RC`](PT_REGS_RC.md) macro to extract the return value and then manually cast them to the actual type.
+
+The `BPF_KRETPROBE` macro allows you to write your program with an argument list, the macro will do the casting for you. Unlike the [`BPF_KPROBE`](BPF_KPROBE.md) this macro only provides the optional return value. (and the original `struct pt_regs *` context).
+
+!!! note
+    The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
+
+### Example
+
+```c hl_lines="2"
+SEC("kretprobe/do_unlinkat")
+int BPF_KRETPROBE(do_unlinkat_exit, long ret)
+{
+    pid_t pid;
+
+    pid = bpf_get_current_pid_tgid() >> 32;
+    bpf_printk("KPROBE EXIT: pid = %d, ret = %ld\n", pid, ret);
+    return 0;
+}
+```

docs/ebpf-library/libbpf/ebpf/BPF_KSYSCALL.md

@@ -0,0 +1,85 @@
+---
+title: "Libbpf eBPF macro 'BPF_KSYSCALL'"
+description: "This page documents the 'BPF_KSYSCALL' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_KSYSCALL`
+
+[:octicons-tag-24: v0.7.0](https://github.com/libbpf/libbpf/releases/tag/v0.7.0)
+
+!!! note
+    Originally this macro was called [`BPF_KPROBE_SYSCALL`](BPF_KPROBE_SYSCALL.md), in Libbpf [:octicons-tag-24: v1.0.0](https://github.com/libbpf/libbpf/releases/tag/v1.0.0) it was renamed. The old macro now aliases to this one for backwards compatibility.
+
+The `BPF_KSYSCALL` macro makes it easier to write [kprobe](../../../linux/program-type/BPF_PROG_TYPE_KPROBE.md) programs that attach to syscalls.
+
+## Definition
+
+```c
+#define BPF_KSYSCALL(name, args...)					    \
+name(struct pt_regs *ctx);						    \
+extern _Bool LINUX_HAS_SYSCALL_WRAPPER __kconfig;			    \
+static __always_inline typeof(name(0))					    \
+____##name(struct pt_regs *ctx, ##args);				    \
+typeof(name(0)) name(struct pt_regs *ctx)				    \
+{									    \
+	struct pt_regs *regs = LINUX_HAS_SYSCALL_WRAPPER		    \
+			       ? (struct pt_regs *)PT_REGS_PARM1(ctx)	    \
+			       : ctx;					    \
+	_Pragma("GCC diagnostic push")					    \
+	_Pragma("GCC diagnostic ignored \"-Wint-conversion\"")		    \
+	if (LINUX_HAS_SYSCALL_WRAPPER)					    \
+		return ____##name(___bpf_syswrap_args(args));		    \
+	else								    \
+		return ____##name(___bpf_syscall_args(args));		    \
+	_Pragma("GCC diagnostic pop")					    \
+}									    \
+static __always_inline typeof(name(0))					    \
+____##name(struct pt_regs *ctx, ##args)
+```
+
+## Usage
+
+This macro is useful when writing kprobe programs that attach to syscalls. On some CPU architectures the kernel will use a so called syscall wrapper (indicated by the `CONFIG_ARCH_HAS_SYSCALL_WRAPPER` kernel config). These wrappers change the syscall calling convention, so the actual `struct pt_regs` are in a different location then normally expected.
+
+Traditionally a program author would have to use the [`PT_REGS_SYSCALL_REGS`](PT_REGS_SYSCALL_REGS.md) macros to extract a given parameter from the context and then manually cast them to the actual type.
+
+The `BPF_KSYSCALL` macro allows you to write your program with an argument list, the macro will do the casting for you and accounts for the syscall wrapping.
+
+!!! note
+    The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
+
+!!! warning
+    At the moment `BPF_KSYSCALL` does not transparently handle all the calling convention quirks for the following syscalls:
+
+    * `mmap()` - `__ARCH_WANT_SYS_OLD_MMAP`.
+    * `clone()` - `CONFIG_CLONE_BACKWARDS`, `CONFIG_CLONE_BACKWARDS2`, and `CONFIG_CLONE_BACKWARDS3`.
+    * socket-related syscalls - `__ARCH_WANT_SYS_SOCKETCALL`.
+    * <nospell>compat</nospell> syscalls.
+
+    This may or may not change in the future. User needs to take extra measures to handle such quirks explicitly, if necessary.
+
+!!! note
+    This macro relies on BPF [CO-RE](../../../concepts/core.md) support and virtual [`__kconfig`](__kconfig.md) `extern`s.
+
+### Example
+
+```c hl_lines="2"
+SEC("ksyscall/write")
+int BPF_KSYSCALL(bpf_prog3, unsigned int fd, const char *buf, size_t count)
+{
+	long init_val = 1;
+	long *value;
+	struct hist_key key;
+
+	key.index = log2l(count);
+	key.pid_tgid = bpf_get_current_pid_tgid();
+	key.uid_gid = bpf_get_current_uid_gid();
+	bpf_get_current_comm(&key.comm, sizeof(key.comm));
+
+	value = bpf_map_lookup_elem(&my_hist_map, &key);
+	if (value)
+		__sync_fetch_and_add(value, 1);
+	else
+		bpf_map_update_elem(&my_hist_map, &key, &init_val, BPF_ANY);
+	return 0;
+}
+```

docs/ebpf-library/libbpf/ebpf/BPF_PROG.md

@@ -0,0 +1,69 @@
+---
+title: "Libbpf eBPF macro 'BPF_PROG'"
+description: "This page documents the 'BPF_PROG' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_PROG`
+
+[:octicons-tag-24: v0.0.8](https://github.com/libbpf/libbpf/releases/tag/v0.0.8)
+
+The `BPF_PROG` macro makes it easier to write programs for program types that receive `[]u64` contexts such as [`BPF_PROG_TYPE_TRACING`](../../../linux/program-type/BPF_PROG_TYPE_TRACING.md) programs.
+
+## Definition
+
+```c
+#define BPF_PROG(name, args...)						    \
+name(unsigned long long *ctx);						    \
+static __always_inline typeof(name(0))					    \
+____##name(unsigned long long *ctx, ##args);				    \
+typeof(name(0)) name(unsigned long long *ctx)				    \
+{									    \
+	_Pragma("GCC diagnostic push")					    \
+	_Pragma("GCC diagnostic ignored \"-Wint-conversion\"")		    \
+	return ____##name(___bpf_ctx_cast(args));			    \
+	_Pragma("GCC diagnostic pop")					    \
+}									    \
+static __always_inline typeof(name(0))					    \
+____##name(unsigned long long *ctx, ##args)
+```
+
+## Usage
+
+This macro is useful when using program types that have a `[]u64` context type (typically written as `unsigned long long *`). 
+
+Conventionally with these program contexts, the arguments to the program are put in this array. So the first argument would be in `ctx[0]`, the second in `ctx[1]`. It is up to the program author to cast them into their actual type.
+
+The `BPF_PROG` macro allows you to write your program with a normal function signature, the macro will then do the casting for you.
+
+!!! note
+    The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
+
+!!! warning
+    This macro assumes a 1 to 1 conversion between a `u64` and argument. However, the Sys V calling convention allows types such as structs of up to 16 bytes to be passed over 2 registers and thus two `u64`s in the context. That breaks the assumption and may lead to hard to resolve bugs. The [`BPF_PROG2`](BPF_PROG2.md) macro is the improved version of this one which does account for this. Its recommend to use the second version when you might be dealing with arguments larger than 8 bytes.
+
+### Example
+
+```c hl_lines="2"
+SEC("struct_ops/hid_device_event")
+int BPF_PROG(filter_switch, struct hid_bpf_ctx *hid_ctx)
+{
+    __u8 *data = hid_bpf_get_data(hid_ctx, 0 /* offset */, 192 /* size */);
+    __u8 *buf;
+
+    if (!data)
+        return 0; /* EPERM check */
+
+    if (current_value != data[152]) {
+        buf = bpf_ringbuf_reserve(&ringbuf, 1, 0);
+        if (!buf)
+            return 0;
+
+        *buf = data[152];
+
+        bpf_ringbuf_commit(buf, 0);
+
+        current_value = data[152];
+    }
+
+    return 0;
+}
+```

docs/ebpf-library/libbpf/ebpf/BPF_PROG2.md

@@ -0,0 +1,61 @@
+---
+title: "Libbpf eBPF macro 'BPF_PROG2'"
+description: "This page documents the 'BPF_PROG2' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_PROG2`
+
+[:octicons-tag-24: v1.1.0](https://github.com/libbpf/libbpf/releases/tag/v1.1.0)
+
+The `BPF_PROG2` macro makes it easier to write programs for program types that receive `[]u64` contexts such as [`BPF_PROG_TYPE_TRACING`](../../../linux/program-type/BPF_PROG_TYPE_TRACING.md) programs. It improves upon the older [`BPF_PROG`](BPF_PROG.md) macro.
+
+## Definition
+
+```c
+#define BPF_PROG2(name, args...)						\
+name(unsigned long long *ctx);							\
+static __always_inline typeof(name(0))						\
+____##name(unsigned long long *ctx ___bpf_ctx_decl(args));			\
+typeof(name(0)) name(unsigned long long *ctx)					\
+{										\
+	return ____##name(ctx ___bpf_ctx_arg(args));				\
+}										\
+static __always_inline typeof(name(0))						\
+____##name(unsigned long long *ctx ___bpf_ctx_decl(args))
+```
+
+## Usage
+
+This macro is useful when using program types that have a `[]u64` context type (typically written as `unsigned long long *`). 
+
+Conventionally with these program contexts, the arguments to the program are put in this array. So the first argument would be in `ctx[0]`, the second in `ctx[1]`. It is up to the program author to cast them into their actual type.
+
+The `BPF_PROG2` macro allows you to write your program with a normal function signature, the macro will then do the casting for you.
+
+This macro also accounts for an edge case in the <nospell>Sys V</nospell> calling convention. When a function call is made, every argument will be put in specific registers. When a variable is to large to put in a register (8 bytes) it is often put on the stack and a pointer to it is passed instead (pointers being 8 bytes). However, the <nospell>Sys V</nospell> calling convention specifies that if a variable is between 8 and 16 bytes, it may be transferred using 2 registers instead, for a `struct{u64, u64}` for example. Since the context is a translation of the arguments passed, it to can use one or two slots depending on the type. The `BPF_PROG2` handles this in the background, which is what improved over the [`BPF_PROG`](BPF_PROG.md) version of this macro.
+
+!!! note
+    The original context will stay available as `ctx`, if you ever wish to access it manually or need to pass it to a helper or kfunc. Therefor, the variable name `ctx` should not be reused in arguments or function body.
+
+### Example
+
+The `bpfptr_t` is actually the following type:
+```c
+struct {
+	union {
+		void		*kernel;
+		void __user	*user;
+	};
+	bool		is_kernel : 1;
+}
+```
+
+Which, with padding is 16 bytes and thus requires `BPF_PROG2` to correctly cast the arguments.
+
+```c hl_lines="2"
+SEC("fexit/__sys_bpf")
+int BPF_PROG2(sys_bpf, int, cmd, bpfptr_t, uattr, unsigned int, size, int, ret)
+{
+    bpf_printf("BPF syscall returned with: %d", ret);
+    return 0;
+}
+```

docs/ebpf-library/libbpf/ebpf/BPF_UPROBE.md

@@ -0,0 +1,10 @@
+---
+title: "Libbpf eBPF macro 'BPF_UPROBE'"
+description: "This page documents the 'BPF_KPROBE' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_UPROBE`
+
+[:octicons-tag-24: v1.2.0](https://github.com/libbpf/libbpf/releases/tag/v1.2.0)
+
+The `BPF_UPROBE` macro is an alias of the [`BPF_KPROBE`](BPF_KPROBE.md) macro. Having this macro helps keep code consistent and avoid confusion.
+

docs/ebpf-library/libbpf/ebpf/BPF_URETPROBE.md

@@ -0,0 +1,10 @@
+---
+title: "Libbpf eBPF macro 'BPF_URETPROBE'"
+description: "This page documents the 'BPF_URETPROBE' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `BPF_URETPROBE`
+
+[:octicons-tag-24: v1.2.0](https://github.com/libbpf/libbpf/releases/tag/v1.2.0)
+
+The `BPF_URETPROBE` macro is an alias of the [`BPF_KRETPROBE`](BPF_KRETPROBE.md) macro. Having this macro helps keep code consistent and avoid confusion.
+

docs/ebpf-library/libbpf/ebpf/PT_REGS_FP.md

@@ -0,0 +1,22 @@
+---
+title: "Libbpf eBPF macro 'PT_REGS_FP'"
+description: "This page documents the 'PT_REGS_FP' libbpf eBPF macro, including its definition, usage, and examples."
+---
+# Libbpf eBPF macro `PT_REGS_FP`
+
+[:octicons-tag-24: v0.0.6](https://github.com/libbpf/libbpf/releases/tag/v0.0.6)
+
+The `PT_REGS_FP` macro make it easy to extract the frame pointer from `struct pt_regs` style contexts in an architecture-independent way.
+
+## Usage
+
+Since the `struct pt_regs` type represents the state of the CPU registers, it is different for every architecture. The `PT_REGS_FP` macro picks the correct register in the `struct pt_regs` type depending on the calling convention of the architecture.
+
+The stack pointer tells you the address of the top of the stack, which can be used to read the value of variables on the stack (if you know the correct offsets).
+
+The architecture for which the eBPF program is compiled is determined by setting one of the `__TARGET_ARCH_{arch}` macros. These are typically set by passing a flag to the compiler, such as `-D__TARGET_ARCH_x86` for x86. This allows for easy cross-compilation of eBPF programs for different architectures by changing the compiler invocation.
+
+### Example
+
+!!! example "Docs could be improved"
+    This part of the docs is incomplete, contributions are very welcome