Skip to contentSkip to conversation

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

PATCH Superseded Jiayuan Chen 3 participants 4 messages May 15, 2025

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 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 kernes that don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE relocations.

---
 tools/bpf/bpftool/Documentation/bpftool-prog.rst |  7 ++++++-
 tools/bpf/bpftool/bash-completion/bpftool        |  2 +-
 tools/bpf/bpftool/prog.c                         | 12 +++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +6 -1
index d6304e01afe0..e60a829ab8d0 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_DIR*]
     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,11 @@ 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 (e.g., fentry/fexit programs, struct_ops, etc) will require
+    actual kernel BTF like /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 +1 -1
index 1ce409a6cbd9..609938c287b7 100644
@@ -511,7 +511,7 @@ _bpftool()
                             ;;
                         *)
                             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..3b6a361dd0f8 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', 'dev', '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_DIR]\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
#1 lore raw

2025-05-15 14:50 UTC+0800 ~ Jiayuan Chen <[email protected]>

Quoted 5 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 kernes that

Typo: "kernes"

Quoted 24 lines

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

---
 tools/bpf/bpftool/Documentation/bpftool-prog.rst |  7 ++++++-
 tools/bpf/bpftool/bash-completion/bpftool        |  2 +-
 tools/bpf/bpftool/prog.c                         | 12 +++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +1 -1
index d6304e01afe0..e60a829ab8d0 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_DIR*]
     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**

tools/bpf/bpftool/Documentation/bpftool-prog.rst bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | na · line 158

Quoted 6 lines
tools/bpf/bpftool/Documentation/bpftool-prog.rst +3 -0
@@ -153,6 +153,11 @@ 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 (e.g., fentry/fexit programs, struct_ops, etc) will require

Nit: No need for both "e.g." and "etc", they're redundant.

tools/bpf/bpftool/Documentation/bpftool-prog.rst bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | na · line 160

Quoted 2 lines
tools/bpf/bpftool/Documentation/bpftool-prog.rst +2 -0
+    actual kernel BTF like /sys/kernel/btf/vmlinux.
+

Can we rephrase the second part of the paragraph a little bit please? “Any other feature” could be clearer, how about:

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.

Quoted 8 lines
tools/bpf/bpftool/Documentation/bpftool-prog.rst +0 -0
     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 +0 -0
index 1ce409a6cbd9..609938c287b7 100644

tools/bpf/bpftool/bash-completion/bpftool _bpftool() · line 517

Quoted 8 lines
tools/bpf/bpftool/bash-completion/bpftool +1 -1
@@ -511,7 +511,7 @@ _bpftool()
                             ;;
                         *)
                             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
                             ;;

Correct, but right before this could you also add the following, please:

	@@ -505,13 +505,13 @@ _bpftool()
	                             _bpftool_get_map_names
	                             return 0
	                             ;;
	-                        pinned|pinmaps)
	+                        pinned|pinmaps|kernel_btf)
	                             _filedir
	                             return 0
	                             ;;
	                         *)

This will make the completion offer file names after the user has typed "kernel_btf".

Quoted 10 lines
tools/bpf/bpftool/prog.c +2 -0
index f010295350be..3b6a361dd0f8 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();

tools/bpf/bpftool/prog.c static int load_with_options(int argc, char **argv, bool first_prog_only) · line 1694

Quoted 10 lines
tools/bpf/bpftool/prog.c +8 -1
+
+			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', 'dev', 'offload_dev', 'xdpmeta_dev', 'pinmaps', "
+			      "'autoattach', or 'kernel_btf', got: '%s'?",

Some of them were missing, thanks for this! Can you remove "dev" from the list, please? It's been deprecated in favour of "offload_dev", to avoid confusion with "xdpmeta_dev".

pw-bot: cr

tools/bpf/bpftool/prog.c static int do_help(int argc, char **argv) · line 2489

Quoted 11 lines
tools/bpf/bpftool/prog.c +1 -0
 			      *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_DIR]\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"

Thanks,
Quentin

#2 lore raw
Quoted 228 lines · Quentin Monnet

2025-05-15 14:50 UTC+0800 ~ Jiayuan Chen <[email protected]>

Quoted 11 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 kernes that

Typo: "kernes"

Quoted 55 lines

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

relocations.

---

 tools/bpf/bpftool/Documentation/bpftool-prog.rst | 7 ++++++-
 tools/bpf/bpftool/bash-completion/bpftool | 2 +-
 tools/bpf/bpftool/prog.c | 12 +++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)

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

index d6304e01afe0..e60a829ab8d0 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*.

-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_DIR*]

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,11 @@ 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.

Quoted 6 lines

+ 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 (e.g., fentry/fexit programs, struct_ops, etc) will require

Nit: No need for both "e.g." and "etc", they're redundant.

Quoted 5 lines

+ actual kernel BTF like /sys/kernel/btf/vmlinux.

+

Can we rephrase the second part of the paragraph a little bit please?

“Any other feature” could be clearer, how about:

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.

Quoted 25 lines

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

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

diff --git a/tools/bpf/bpftool/bash-completion/bpftool b/tools/bpf/bpftool/bash-completion/bpftool

index 1ce409a6cbd9..609938c287b7 100644

--- a/tools/bpf/bpftool/bash-completion/bpftool

+++ b/tools/bpf/bpftool/bash-completion/bpftool

@@ -511,7 +511,7 @@ _bpftool()

;;

*)

COMPREPLY=( $( compgen -W "map" -- "$cur" ) )

- _bpftool_once_attr 'type pinmaps autoattach'

Quoted 8 lines

+ _bpftool_once_attr 'type pinmaps autoattach kernel_btf'

_bpftool_one_of_list 'offload_dev xdpmeta_dev'

return 0

;;

Correct, but right before this could you also add the following, please:

@@ -505,13 +505,13 @@ _bpftool()

_bpftool_get_map_names

return 0

;;

- pinned|pinmaps)

+ pinned|pinmaps|kernel_btf)

_filedir

return 0

;;

*)

This will make the completion offer file names after the user has typed

"kernel_btf".

Quoted 31 lines
tools/bpf/bpftool/prog.c +0 -0
 
 index f010295350be..3b6a361dd0f8 100644
 
 --- a/tools/bpf/bpftool/prog.c
 
 +++ b/tools/bpf/bpftool/prog.c
 
 @@ -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();

tools/bpf/bpftool/prog.c

Quoted 10 lines
tools/bpf/bpftool/prog.c +0 -0
 
 } else {
 
 - p_err("expected no more arguments, 'type', 'map' or 'dev', got: '%s'?",
 
 + p_err("expected no more arguments, "
 
 + "'type', 'map', 'dev', 'offload_dev', 'xdpmeta_dev', 'pinmaps', "
 
 + "'autoattach', or 'kernel_btf', got: '%s'?",

Some of them were missing, thanks for this! Can you remove "dev" from

the list, please? It's been deprecated in favour of "offload_dev", to

avoid confusion with "xdpmeta_dev".

pw-bot: cr

Quoted 19 lines

*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_DIR]\n"

" %1$s %2$s attach PROG ATTACH_TYPE [MAP]\n"

Quoted 9 lines
Quoted 4 lines

" %1$s %2$s detach PROG ATTACH_TYPE [MAP]\n"

" %1$s %2$s run PROG \\\n"

Thanks,

Quentin

Thank you, Quentin. Your suggestions are all very valuable; I will make the updates.

#3 lore raw
In reply to Jiayuan Chen
Quoted 78 lines · Jiayuan Chen

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 kernes that don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE relocations.

---
 tools/bpf/bpftool/Documentation/bpftool-prog.rst |  7 ++++++-
 tools/bpf/bpftool/bash-completion/bpftool        |  2 +-
 tools/bpf/bpftool/prog.c                         | 12 +++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +6 -1
index d6304e01afe0..e60a829ab8d0 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_DIR*]
     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,11 @@ 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 (e.g., fentry/fexit programs, struct_ops, etc) will require
+    actual kernel BTF like /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 +1 -1
index 1ce409a6cbd9..609938c287b7 100644
@@ -511,7 +511,7 @@ _bpftool()
                             ;;
                         *)
                             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 +10 -1
index f010295350be..3b6a361dd0f8 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', 'dev', 'offload_dev', 'xdpmeta_dev', 'pinmaps', "
+                             "'autoattach', or 'kernel_btf', got: '%s'?",
                              *argv);
                        goto err_free_reuse_maps;
                }

tools/bpf/bpftool/prog.c static int do_help(int argc, char **argv) · line 2486

Quoted 4 lines
tools/bpf/bpftool/prog.c +1 -0
@@ -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_DIR]\n"

Is it a DIR or a FILE/PATH?

Quoted 7 lines
tools/bpf/bpftool/prog.c +0 -1
                "       %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"
--

2.47.1