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>
---
tools/lib/bpf/libbpf.c | 14 ++++++++------
tools/lib/bpf/libbpf.h | 27 ++++++++++++++++++++++++++-
2 files changed, 34 insertions(+), 7 deletions(-)
diff --git a/tools/lib/bpf/libbpf.c b/tools/lib/bpf/libbpf.c
index 536c19c14d21..ebb965230bb4 100644
--- a/tools/lib/bpf/libbpf.c
+++ b/tools/lib/bpf/libbpf.c
@@ -11816,6 +11816,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,
@@ -11836,20 +11838,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 0be34852350f..bba4e8464396 100644
--- 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,
--
2.52.0On Wed, Apr 01, 2026 at 04:05:03PM +0900, Hoyeon Lee wrote:
> 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>
Acked-by: Jiri Olsa <jolsa@kernel.org>
jirka
> ---
> tools/lib/bpf/libbpf.c | 14 ++++++++------
> tools/lib/bpf/libbpf.h | 27 ++++++++++++++++++++++++++-
> 2 files changed, 34 insertions(+), 7 deletions(-)
>
> diff --git a/tools/lib/bpf/libbpf.c b/tools/lib/bpf/libbpf.c
> index 536c19c14d21..ebb965230bb4 100644
> --- a/tools/lib/bpf/libbpf.c
> +++ b/tools/lib/bpf/libbpf.c
> @@ -11816,6 +11816,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,
> @@ -11836,20 +11838,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 0be34852350f..bba4e8464396 100644
> --- 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,
> --
> 2.52.0
>
© 2016 - 2026 Red Hat, Inc.