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(-)
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.
Signed-off-by: Jiayuan Chen <jiayuan.chen@linux.dev>
---
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.
+ 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*.
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'
+ _bpftool_once_attr 'type pinmaps autoattach kernel_btf'
_bpftool_one_of_list 'offload_dev xdpmeta_dev'
return 0
;;
diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
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();
} 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"
--
2.47.1On Wed, May 14, 2025 at 11:52 PM Jiayuan Chen <jiayuan.chen@linux.dev> wrote:
>
> 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.
>
> Signed-off-by: Jiayuan Chen <jiayuan.chen@linux.dev>
> ---
> 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.
>
> + 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*.
>
> 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'
> + _bpftool_once_attr 'type pinmaps autoattach kernel_btf'
> _bpftool_one_of_list 'offload_dev xdpmeta_dev'
> return 0
> ;;
> diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
> 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();
> } 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"
Is it a DIR or a FILE/PATH?
> " %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
>
>
2025-05-15 14:50 UTC+0800 ~ Jiayuan Chen <jiayuan.chen@linux.dev>
> 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"
> don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE
> relocations.
>
> Signed-off-by: Jiayuan Chen <jiayuan.chen@linux.dev>
> ---
> 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.
>
> + 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.
> + 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.
> 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'
> + _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".
> diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
> 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();
> } 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
> *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
May 15, 2025 at 17:17, "Quentin Monnet" <qmo@kernel.org> wrote:
>
> 2025-05-15 14:50 UTC+0800 ~ Jiayuan Chen <jiayuan.chen@linux.dev>
>
> >
> > 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"
>
> >
> > don't have CONFIG_DEBUG_INFO_BTF enabled but still want to perform CO-RE
> >
> > relocations.
> >
> >
> >
> > Signed-off-by: Jiayuan Chen <jiayuan.chen@linux.dev>
> >
> > ---
> >
> > 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.
> >
> >
> >
> > + 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.
>
> >
> > + 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.
>
> >
> > 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'
> >
> > + _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".
>
> >
> > diff --git a/tools/bpf/bpftool/prog.c b/tools/bpf/bpftool/prog.c
> >
> > 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();
> >
> > } 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
>
> >
> > *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
>
Thank you, Quentin. Your suggestions are all very valuable; I will make the updates.
© 2016 - 2025 Red Hat, Inc.