libbpf: Clarify raw-address single kprobe attach behavior

bpf_program__attach_kprobe_opts() documents single-kprobe attach
through func_name, with an optional offset. For the PMU-based path,
func_name = NULL with an absolute address in offset already works as
well, but that is not described in the API.

This commit clarifies this existing non-legacy behavior. For PMU-based
attach, callers can use func_name = NULL with an absolute address in
offset as the raw-address form. For legacy tracefs/debugfs kprobes,
reject this form explicitly.

Signed-off-by: Hoyeon Lee <hoyeon.lee@suse.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Acked-by: Jiri Olsa <jolsa@kernel.org>
Link: https://lore.kernel.org/bpf/20260401143116.185049-3-hoyeon.lee@suse.com

diff --git a/tools/lib/bpf/libbpf.c b/tools/lib/bpf/libbpf.c
index d9c678ed442e5281fb6cd7b965d5fd4b48fe6a02..42bdba4efd0c67696c9f9b0623dccd93ddf47a06 100644 (file)
--- a/tools/lib/bpf/libbpf.c
+++ b/tools/lib/bpf/libbpf.c
@@ -11843,6 +11843,8 @@ bpf_program__attach_kprobe_opts(const struct bpf_program *prog,
        default:
                return libbpf_err_ptr(-EINVAL);
        }
+       if (!func_name && legacy)
+               return libbpf_err_ptr(-EOPNOTSUPP);
 
        if (!legacy) {
                pfd = perf_event_open_probe(false /* uprobe */, retprobe,
@@ -11863,20 +11865,20 @@ bpf_program__attach_kprobe_opts(const struct bpf_program *prog,
        }
        if (pfd < 0) {
                err = pfd;
-               pr_warn("prog '%s': failed to create %s '%s+0x%zx' perf event: %s\n",
+               pr_warn("prog '%s': failed to create %s '%s%s0x%zx' perf event: %s\n",
                        prog->name, retprobe ? "kretprobe" : "kprobe",
-                       func_name, offset,
-                       errstr(err));
+                       func_name ?: "", func_name ? "+" : "",
+                       offset, errstr(err));
                goto err_out;
        }
        link = bpf_program__attach_perf_event_opts(prog, pfd, &pe_opts);
        err = libbpf_get_error(link);
        if (err) {
                close(pfd);
-               pr_warn("prog '%s': failed to attach to %s '%s+0x%zx': %s\n",
+               pr_warn("prog '%s': failed to attach to %s '%s%s0x%zx': %s\n",
                        prog->name, retprobe ? "kretprobe" : "kprobe",
-                       func_name, offset,
-                       errstr(err));
+                       func_name ?: "", func_name ? "+" : "",
+                       offset, errstr(err));
                goto err_clean_legacy;
        }
        if (legacy) {

diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h
index 0be34852350ffe512dee22f7328b215bbfe3a553..bba4e846439676503b47352f2223f63a0b6e253d 100644 (file)
--- a/tools/lib/bpf/libbpf.h
+++ b/tools/lib/bpf/libbpf.h
@@ -557,7 +557,7 @@ struct bpf_kprobe_opts {
        size_t sz;
        /* custom user-provided value fetchable through bpf_get_attach_cookie() */
        __u64 bpf_cookie;
-       /* function's offset to install kprobe to */
+       /* function offset, or raw address if func_name == NULL */
        size_t offset;
        /* kprobe is return probe */
        bool retprobe;
@@ -565,11 +565,36 @@ struct bpf_kprobe_opts {
        enum probe_attach_mode attach_mode;
        size_t :0;
 };
+
 #define bpf_kprobe_opts__last_field attach_mode
 
+/**
+ * @brief **bpf_program__attach_kprobe()** attaches a BPF program to a
+ * kernel function entry or return.
+ *
+ * @param prog BPF program to attach
+ * @param retprobe Attach to function return
+ * @param func_name Name of the kernel function to attach to
+ * @return Reference to the newly created BPF link; or NULL is returned on
+ * error, error code is stored in errno
+ */
 LIBBPF_API struct bpf_link *
 bpf_program__attach_kprobe(const struct bpf_program *prog, bool retprobe,
                           const char *func_name);
+
+/**
+ * @brief **bpf_program__attach_kprobe_opts()** is just like
+ * bpf_program__attach_kprobe() except with an options struct
+ * for various configurations.
+ *
+ * @param prog BPF program to attach
+ * @param func_name Name of the kernel function to attach to. If NULL,
+ * opts->offset is treated as a raw kernel address. Raw-address attach
+ * is supported with PROBE_ATTACH_MODE_PERF and PROBE_ATTACH_MODE_LINK.
+ * @param opts Options for altering program attachment
+ * @return Reference to the newly created BPF link; or NULL is returned on
+ * error, error code is stored in errno
+ */
 LIBBPF_API struct bpf_link *
 bpf_program__attach_kprobe_opts(const struct bpf_program *prog,
                                 const char *func_name,