Skip to contentSkip to conversation

bpftool: Add support for custom BTF path in prog load/loadall

PATCH Superseded Jiayuan Chen 2 participants 3 messages May 16, 2025

Subsystems (2)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 bpftool: Add support for custom BTF path in prog load/loadall

This patch exposes the btf_custom_path feature to bpftool, allowing users to specify a custom BTF file when loading BPF programs using prog load or prog loadall commands.

The argument 'btf_custom_path' in libbpf is used for those kernels that don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE relocations.

---
V2 -> V3: Optimized document grammar and some prompts
https://lore.kernel.org/bpf/[email protected]/
V1 -> V2: Added bash completion and documentation
https://lore.kernel.org/bpf/[email protected]/

---
 tools/bpf/bpftool/Documentation/bpftool-prog.rst |  8 +++++++-
 tools/bpf/bpftool/bash-completion/bpftool        |  4 ++--
 tools/bpf/bpftool/prog.c                         | 12 +++++++++++-
 3 files changed, 20 insertions(+), 4 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +7 -1
index d6304e01afe0..4dce43e8e8a3 100644
@@ -127,7 +127,7 @@ bpftool prog pin *PROG* *FILE*
     Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
     character ('.'), which is reserved for future extensions of *bpffs*.
 
-bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach]
+bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach] [kernel_btf *BTF_FILE*]
     Load bpf program(s) from binary *OBJ* and pin as *PATH*. **bpftool prog
     load** pins only the first program from the *OBJ* as *PATH*. **bpftool prog
     loadall** pins all programs from the *OBJ* under *PATH* directory. **type**
@@ -153,6 +153,12 @@ bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | na
     program does not support autoattach, bpftool falls back to regular pinning
     for that program instead.
 
+    The **kernel_btf** option allows specifying an external BTF file to replace
+    the system's own vmlinux BTF file for CO-RE relocations. Note that any
+    other feature relying on BTF (such as fentry/fexit programs, struct_ops)
+    requires the BTF file for the actual kernel running on the host, often
+    exposed at /sys/kernel/btf/vmlinux.
+
     Note: *PATH* must be located in *bpffs* mount. It must not contain a dot
     character ('.'), which is reserved for future extensions of *bpffs*.
 
tools/bpf/bpftool/bash-completion/bpftool +2 -2
index 1ce409a6cbd9..27512feb5c70 100644
@@ -505,13 +505,13 @@ _bpftool()
                             _bpftool_get_map_names
                             return 0
                             ;;
-                        pinned|pinmaps)
+                        pinned|pinmaps|kernel_btf)
                             _filedir
                             return 0
                             ;;
                         *)
                             COMPREPLY=( $( compgen -W "map" -- "$cur" ) )
-                            _bpftool_once_attr 'type pinmaps autoattach'
+                            _bpftool_once_attr 'type pinmaps autoattach kernel_btf'
                             _bpftool_one_of_list 'offload_dev xdpmeta_dev'
                             return 0
                             ;;
tools/bpf/bpftool/prog.c +11 -1
index f010295350be..96eea8a67225 100644
@@ -1681,8 +1681,17 @@ static int load_with_options(int argc, char **argv, bool first_prog_only)
 		} else if (is_prefix(*argv, "autoattach")) {
 			auto_attach = true;
 			NEXT_ARG();
+		} else if (is_prefix(*argv, "kernel_btf")) {
+			NEXT_ARG();
+
+			if (!REQ_ARGS(1))
+				goto err_free_reuse_maps;
+
+			open_opts.btf_custom_path = GET_ARG();
 		} else {
-			p_err("expected no more arguments, 'type', 'map' or 'dev', got: '%s'?",
+			p_err("expected no more arguments, "
+			      "'type', 'map', 'offload_dev', 'xdpmeta_dev', 'pinmaps', "
+			      "'autoattach', or 'kernel_btf', got: '%s'?",
 			      *argv);
 			goto err_free_reuse_maps;
 		}
@@ -2474,6 +2483,7 @@ static int do_help(int argc, char **argv)
 		"                         [map { idx IDX | name NAME } MAP]\\\n"
 		"                         [pinmaps MAP_DIR]\n"
 		"                         [autoattach]\n"
+		"                         [kernel_btf BTF_FILE]\n"
 		"       %1$s %2$s attach PROG ATTACH_TYPE [MAP]\n"
 		"       %1$s %2$s detach PROG ATTACH_TYPE [MAP]\n"
 		"       %1$s %2$s run PROG \\\n"
Signature · 1 line
2.47.1
maintainer Reviewed-by on v3 1/1
#1 lore raw

2025-05-16 11:23 UTC+0800 ~ Jiayuan Chen <[email protected]>

Quoted 27 lines

This patch exposes the btf_custom_path feature to bpftool, allowing users to specify a custom BTF file when loading BPF programs using prog load or prog loadall commands.

The argument 'btf_custom_path' in libbpf is used for those kernels that don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE relocations.

---
V2 -> V3: Optimized document grammar and some prompts
https://lore.kernel.org/bpf/[email protected]/
V1 -> V2: Added bash completion and documentation
https://lore.kernel.org/bpf/[email protected]/

---
 tools/bpf/bpftool/Documentation/bpftool-prog.rst |  8 +++++++-
 tools/bpf/bpftool/bash-completion/bpftool        |  4 ++--
 tools/bpf/bpftool/prog.c                         | 12 +++++++++++-
 3 files changed, 20 insertions(+), 4 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +0 -0
index d6304e01afe0..4dce43e8e8a3 100644

tools/bpf/bpftool/Documentation/bpftool-prog.rst bpftool prog pin *PROG* *FILE* · line 130

Quoted 5 lines
tools/bpf/bpftool/Documentation/bpftool-prog.rst +1 -1
@@ -127,7 +127,7 @@ bpftool prog pin *PROG* *FILE*
     Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
     character ('.'), which is reserved for future extensions of *bpffs*.
 
-bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach]
+bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach] [kernel_btf *BTF_FILE*]

Woops, I just realised we also need to add kernel_btf to the command summary at the top of the document (line 34), sorry for missing it during the previous pass. Please add it, and mark v4 as:

Thanks!

#2 lore raw
Quoted 64 lines · Quentin Monnet

2025-05-16 11:23 UTC+0800 ~ Jiayuan Chen <[email protected]>

Quoted 61 lines

This patch exposes the btf_custom_path feature to bpftool, allowing users

to specify a custom BTF file when loading BPF programs using prog load or

prog loadall commands.

The argument 'btf_custom_path' in libbpf is used for those kernels that

don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE

relocations.

---

V2 -> V3: Optimized document grammar and some prompts

https://lore.kernel.org/bpf/[email protected]/

V1 -> V2: Added bash completion and documentation

https://lore.kernel.org/bpf/[email protected]/

---

 tools/bpf/bpftool/Documentation/bpftool-prog.rst | 8 +++++++-
 tools/bpf/bpftool/bash-completion/bpftool | 4 ++--
 tools/bpf/bpftool/prog.c | 12 +++++++++++-
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst

index d6304e01afe0..4dce43e8e8a3 100644

--- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst

+++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst

@@ -127,7 +127,7 @@ bpftool prog pin *PROG* *FILE*

Note: *FILE* must be located in *bpffs* mount. It must not contain a dot

character ('.'), which is reserved for future extensions of *bpffs*.

Quoted 8 lines
Quoted 4 lines

-bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach]

+bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach] [kernel_btf *BTF_FILE*]

Woops, I just realised we also need to add kernel_btf to the command

summary at the top of the document (line 34), sorry for missing it

It was my mistake to miss that part. I'll prepare an updated version soon. :)

Thanks.

Quoted 6 lines

during the previous pass. Please add it, and mark v4 as:

Thanks!