Add troubleshooting guide for fentry attachment failures in 3-fentry-unlink (#200)

* Initial plan

* Add troubleshooting section for fentry-unlink example with kernel compatibility guidance

Co-authored-by: yunwei37 <34985212+yunwei37@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: yunwei37 <34985212+yunwei37@users.noreply.github.com>

Author: Copilot

src/3-fentry-unlink/README.md

@@ -83,6 +83,72 @@ $ sudo cat /sys/kernel/debug/tracing/trace_pipe
               rm-9290    [004] d..2  4637.798843: bpf_trace_printk: fexit: pid = 9290, filename = test_file2, ret = 0
 ```
 
+## Troubleshooting
+
+If you encounter errors when running this example, here are some common issues and solutions:
+
+### Error: "failed to attach: ERROR: strerror_r(-524)=22"
+
+This error (error code -524 = ENOTSUPP) typically means your kernel doesn't support fentry/fexit. Here's how to troubleshoot:
+
+**1. Check your kernel version:**
+
+```console
+$ uname -r
+```
+
+You need:
+- Kernel 5.5 or newer for x86/x86_64 processors
+- Kernel 6.0 or newer for ARM/ARM64 processors
+
+If your kernel is too old, you have two options:
+- Upgrade your kernel to a supported version
+- Use the kprobe example instead (see [example 2-kprobe-unlink](../2-kprobe-unlink/))
+
+**2. Verify BTF (BPF Type Format) support:**
+
+BTF is required for fentry/fexit to work. Check if it's enabled:
+
+```console
+$ cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF
+CONFIG_DEBUG_INFO_BTF=y
+```
+
+If BTF is not enabled, you'll need to either:
+- Use a kernel with BTF support enabled
+- Use the kprobe example as an alternative
+
+**3. Check if the kernel function exists:**
+
+The function `do_unlinkat` may have a different name or may not be exported in some kernel versions. You can check available functions:
+
+```console
+$ sudo cat /sys/kernel/debug/tracing/available_filter_functions | grep unlink
+```
+
+If `do_unlinkat` is not listed, the function may not be available for tracing on your kernel.
+
+**4. Verify your kernel configuration:**
+
+Ensure your kernel was compiled with the necessary eBPF features:
+
+```console
+$ cat /boot/config-$(uname -r) | grep BPF
+```
+
+Look for these important settings:
+- `CONFIG_BPF=y`
+- `CONFIG_BPF_SYSCALL=y`
+- `CONFIG_DEBUG_INFO_BTF=y`
+- `CONFIG_BPF_JIT=y`
+
+If you're still experiencing issues after checking these items, please report your kernel version and OS distribution by running:
+
+```console
+$ uname -a
+$ cat /etc/os-release
+```
+
 ## Summary
 
 This program is an eBPF program that captures the `do_unlinkat` and `do_unlinkat_exit` functions using fentry and fexit, and uses `bpf_get_current_pid_tgid` and `bpf_printk` functions to obtain the ID, filename, and return value of the process calling do_unlinkat, and print them in the kernel log.

src/3-fentry-unlink/README.zh.md

@@ -91,6 +91,72 @@ $ sudo cat /sys/kernel/debug/tracing/trace_pipe
               rm-9290    [004] d..2  4637.798843: bpf_trace_printk: fexit: pid = 9290, filename = test_file2, ret = 0
 ```
 
+## 故障排查
+
+如果您在运行此示例时遇到错误，以下是一些常见问题和解决方案：
+
+### 错误："failed to attach: ERROR: strerror_r(-524)=22"
+
+此错误（错误代码 -524 = ENOTSUPP）通常表示您的内核不支持 fentry/fexit。以下是排查方法：
+
+**1. 检查内核版本：**
+
+```console
+$ uname -r
+```
+
+您需要：
+- x86/x86_64 处理器需要内核 5.5 或更高版本
+- ARM/ARM64 处理器需要内核 6.0 或更高版本
+
+如果您的内核版本过旧，您有两个选择：
+- 将内核升级到支持的版本
+- 使用 kprobe 示例代替（参见 [示例 2-kprobe-unlink](../2-kprobe-unlink/)）
+
+**2. 验证 BTF（BPF Type Format）支持：**
+
+fentry/fexit 需要 BTF 支持。检查是否已启用：
+
+```console
+$ cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF
+CONFIG_DEBUG_INFO_BTF=y
+```
+
+如果 BTF 未启用，您需要：
+- 使用已启用 BTF 支持的内核
+- 使用 kprobe 示例作为替代方案
+
+**3. 检查内核函数是否存在：**
+
+`do_unlinkat` 函数在某些内核版本中可能有不同的名称或未导出。您可以检查可用的函数：
+
+```console
+$ sudo cat /sys/kernel/debug/tracing/available_filter_functions | grep unlink
+```
+
+如果未列出 `do_unlinkat`，则该函数可能在您的内核上无法用于跟踪。
+
+**4. 验证内核配置：**
+
+确保您的内核编译时包含了必要的 eBPF 功能：
+
+```console
+$ cat /boot/config-$(uname -r) | grep BPF
+```
+
+查找这些重要设置：
+- `CONFIG_BPF=y`
+- `CONFIG_BPF_SYSCALL=y`
+- `CONFIG_DEBUG_INFO_BTF=y`
+- `CONFIG_BPF_JIT=y`
+
+如果检查这些项目后仍然遇到问题，请通过运行以下命令报告您的内核版本和操作系统发行版：
+
+```console
+$ uname -a
+$ cat /etc/os-release
+```
+
 ## 总结
 
 这段程序是一个 eBPF 程序，通过使用 fentry 和 fexit 捕获 `do_unlinkat` 和 `do_unlinkat_exit` 函数，并通过使用 `bpf_get_current_pid_tgid` 和 `bpf_printk` 函数获取调用 do_unlinkat 的进程的 ID、文件名和返回值，并在内核日志中打印出来。