bpftool: Add support for custom BTF path in prog load/loadall
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
@@ -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
@@ -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
@@ -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
Quentin Monnet
maintainer2025-05-15 14:50 UTC+0800 ~ Jiayuan Chen <[email protected]>
Quoted 5 lines
This patch exposes the
btf_custom_pathfeature 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_BTFenabled but still want to perform CO-RE relocations.Signed-off-by Jiayuan Chen <[email protected]>--- 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@@ -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
-0Note: *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
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@@ -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
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_pathfeature to bpftool, allowing usersto 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 thatTypo: "kernes"
Quoted 55 lines
don't have
CONFIG_DEBUG_INFO_BTFenabled but still want to perform CO-RErelocations.
Signed-off-by Jiayuan Chen <[email protected]>---
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.rstb/tools/bpf/bpftool/Documentation/bpftool-prog.rstindex
d6304e01afe0..e60a829ab8d0100644---
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 requireNit: 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 actualkernel 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..609938c287b7100644--- 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 autoattachkernel_btf'
_bpftool_one_of_list'offload_devxdpmeta_dev'return 0
;;
Correct, but right before this could you also add the following, please:
@@ -505,13 +505,13 @@
_bpftool()
_bpftool_get_map_namesreturn 0
;;
- pinned|pinmaps)
+ pinned|pinmaps|kernel_btf)
_filedirreturn 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
-0index 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", toavoid 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_btfBTF_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.
Quoted 78 lines · Jiayuan Chen
This patch exposes the
btf_custom_pathfeature 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 haveCONFIG_DEBUG_INFO_BTFenabled but still want to perform CO-RE relocations.Signed-off-by Jiayuan Chen <[email protected]>--- 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@@ -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@@ -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@@ -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