add btf dumping to bpftool
Subsystems (4)
v4 cover add btf dumping to bpftool
This patch set adds a new bpftool btf dump sub-command, which allows to dump BTF contents (only types for now). Currently it only outputs low-level content, almost 1:1 with binary BTF format, but follow up patches will add ability to dump BTF types as a compilable C header file. JSON output is supported as well.
Patch #1 adds btf sub-command, dumping BTF types in human-readable format. It also implements reading .BTF data from ELF file.
Patch #2 adds minimal documentation with output format examples and different ways to specify source of BTF data.
Patch #3 adds support for btf command in bash-completion/bpftool script. Patch #4 fixes minor indentation issue in bash-completion script.
Output format is mostly following existing format of BPF verifier log, but deviates from it in few places. More details are in commit message for patch #1.
Example of output for all supported BTF kinds are in patch #2 as part of documentation. Some field names are quite verbose and I'd rather shorten them, if we don't feel like being very close to BPF verifier names is a necessity, but in this patch I left them exactly the same as in verifier log.
v3->v4:
- reverse Christmas tree (Quentin)
- better docs (Quentin)
v2->v3:
- make map's key|value|kv|all suggestion more precise (Quentin)
- fix default case indentations (Quentin)
v1->v2:
- fix unnecessary trailing whitespaces in bpftool-btf.rst (Yonghong)
- add btf in main.c for a list of possible OBJECTs
- handle unknown keyword under bpftool btf dump (Yonghong)
Andrii Nakryiko (4):
bpftool: add ability to dump BTF types bpftool/docs: add btf sub-command documentation
bpftool: add bash completions for btf command
bpftool: fix indendation in bash-completion/bpftool
.../bpf/bpftool/Documentation/bpftool-btf.rst | 222 +++++++ .../bpftool/Documentation/bpftool-cgroup.rst | 3 +- .../bpftool/Documentation/bpftool-feature.rst | 3 +- .../bpf/bpftool/Documentation/bpftool-map.rst | 3 +- .../bpf/bpftool/Documentation/bpftool-net.rst | 3 +- .../bpftool/Documentation/bpftool-perf.rst | 3 +- .../bpftool/Documentation/bpftool-prog.rst | 3 +- tools/bpf/bpftool/Documentation/bpftool.rst | 3 +- tools/bpf/bpftool/bash-completion/bpftool | 68 +- tools/bpf/bpftool/btf.c | 586 ++++++++++++++++++ tools/bpf/bpftool/main.c | 3 +- tools/bpf/bpftool/main.h | 1 + 12 files changed, 882 insertions(+), 19 deletions(-) create mode 100644 tools/bpf/bpftool/Documentation/bpftool-btf.rst create mode 100644 tools/bpf/bpftool/btf.c
Signature · 1 line
2.17.1
PATCH v4 1/4 bpftool: add ability to dump BTF types
Add new btf dump sub-command to bpftool. It allows to dump human-readable low-level BTF types representation of BTF types. BTF can be retrieved from few different sources:
- from BTF object by ID;
- from PROG, if it has associated BTF;
- from MAP, if it has associated BTF data; it's possible to narrow
down types to either key type, value type, both, or all BTF types;
- from ELF file (.BTF section).
Output format mostly follows BPF verifier log format with few notable exceptions:
- all the type/field/param/etc names are enclosed in single quotes to
allow easier grepping and to stand out a little bit more;
- FUNC_PROTO output follows STRUCT/UNION/ENUM format of having one line per each argument; this is more uniform and allows easy grepping, as opposed to succinct, but inconvenient format that BPF verifier log is using.
--- tools/bpf/bpftool/btf.c | 586 +++++++++++++++++++++++++++++++++++++++ tools/bpf/bpftool/main.c | 3 +- tools/bpf/bpftool/main.h | 1 + 3 files changed, 589 insertions(+), 1 deletion(-) create mode 100644 tools/bpf/bpftool/btf.c
tools/bpf/bpftool/btf.c new file +586 -0
@@ -0,0 +1,586 @@ +// SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +/* Copyright (C) 2019 Facebook */ + +#include <errno.h> +#include <fcntl.h> +#include <linux/err.h> +#include <stdbool.h> +#include <stdio.h> +#include <string.h> +#include <unistd.h> +#include <gelf.h> +#include <bpf.h> +#include <linux/btf.h> + +#include "btf.h" +#include "json_writer.h" +#include "main.h" + +static const char *const btf_kind_str[NR_BTF_KINDS ] = { + [BTF_KIND_UNKN ] ="UNKNOWN" , + [BTF_KIND_INT ] ="INT" , + [BTF_KIND_PTR ] ="PTR" , + [BTF_KIND_ARRAY ] ="ARRAY" , + [BTF_KIND_STRUCT ] ="STRUCT" , + [BTF_KIND_UNION ] ="UNION" , + [BTF_KIND_ENUM ] ="ENUM" , + [BTF_KIND_FWD ] ="FWD" , + [BTF_KIND_TYPEDEF ] ="TYPEDEF" , + [BTF_KIND_VOLATILE ] ="VOLATILE" , + [BTF_KIND_CONST ] ="CONST" , + [BTF_KIND_RESTRICT ] ="RESTRICT" , + [BTF_KIND_FUNC ] ="FUNC" , + [BTF_KIND_FUNC_PROTO ] ="FUNC_PROTO" , + [BTF_KIND_VAR ] ="VAR" , + [BTF_KIND_DATASEC ] ="DATASEC" , +}; + +static const char *btf_int_enc_str (__u8 encoding) +{ +switch (encoding) { +case 0 : +return "(none)" ; +case BTF_INT_SIGNED : +return "SIGNED" ; +case BTF_INT_CHAR : +return "CHAR" ; +case BTF_INT_BOOL : +return "BOOL" ; +default : +return "UNKN" ; + } +} + +static const char *btf_var_linkage_str (__u32 linkage) +{ +switch (linkage) { +case BTF_VAR_STATIC : +return "static" ; +case BTF_VAR_GLOBAL_ALLOCATED : +return "global-alloc" ; +default : +return "(unknown)" ; + } +} + +static const char *btf_str (const struct btf *btf,__u32 off) +{ +if (!off) +return "(anon)" ; +return btf__name_by_offset (btf, off) ? :"(invalid)" ; +} + +static int dump_btf_type (const struct btf *btf,__u32 id, +const struct btf_type *t) +{ +json_writer_t *w = json_wtr; +int kind, safe_kind; + + kind =BTF_INFO_KIND (t->info); + safe_kind = kind <=BTF_KIND_MAX ? kind :BTF_KIND_UNKN ; + +if (json_output) { +jsonw_start_object (w); +jsonw_uint_field (w,"id" , id); +jsonw_string_field (w,"kind" , btf_kind_str[safe_kind]); +jsonw_string_field (w,"name" ,btf_str (btf, t->name_off)); + }else { +printf ("[%u] %s '%s'" , id, btf_kind_str[safe_kind], +btf_str (btf, t->name_off)); + } + +switch (BTF_INFO_KIND (t->info)) { +case BTF_KIND_INT : { +__u32 v = *(__u32 *)(t +1 ); +const char *enc; + + enc =btf_int_enc_str (BTF_INT_ENCODING (v)); + +if (json_output) { +jsonw_uint_field (w,"size" , t->size); +jsonw_uint_field (w,"bits_offset" ,BTF_INT_OFFSET (v)); +jsonw_uint_field (w,"nr_bits" ,BTF_INT_BITS (v)); +jsonw_string_field (w,"encoding" , enc); + }else { +printf (" size=%u bits_offset=%u nr_bits=%u encoding=%s" , + t->size,BTF_INT_OFFSET (v),BTF_INT_BITS (v), + enc); + } +break ; + } +case BTF_KIND_PTR : +case BTF_KIND_CONST : +case BTF_KIND_VOLATILE : +case BTF_KIND_RESTRICT : +case BTF_KIND_TYPEDEF : +if (json_output) +jsonw_uint_field (w,"type_id" , t->type); +else +printf (" type_id=%u" , t->type); +break ; +case BTF_KIND_ARRAY : { +const struct btf_array *arr = (const void *)(t +1 ); + +if (json_output) { +jsonw_uint_field (w,"type_id" , arr->type); +jsonw_uint_field (w,"index_type_id" , arr->index_type); +jsonw_uint_field (w,"nr_elems" , arr->nelems); + }else { +printf (" type_id=%u index_type_id=%u nr_elems=%u" , + arr->type, arr->index_type, arr->nelems); + } +break ; + } +case BTF_KIND_STRUCT : +case BTF_KIND_UNION : { +const struct btf_member *m = (const void *)(t +1 ); +__u16 vlen =BTF_INFO_VLEN (t->info); +int i; + +if (json_output) { +jsonw_uint_field (w,"size" , t->size); +jsonw_uint_field (w,"vlen" , vlen); +jsonw_name (w,"members" ); +jsonw_start_array (w); + }else { +printf (" size=%u vlen=%u" , t->size, vlen); + } +for (i =0 ; i < vlen; i++, m++) { +const char *name =btf_str (btf, m->name_off); +__u32 bit_off, bit_sz; + +if (BTF_INFO_KFLAG (t->info)) { + bit_off =BTF_MEMBER_BIT_OFFSET (m->offset); + bit_sz =BTF_MEMBER_BITFIELD_SIZE (m->offset); + }else { + bit_off = m->offset; + bit_sz =0 ; + } + +if (json_output) { +jsonw_start_object (w); +jsonw_string_field (w,"name" , name); +jsonw_uint_field (w,"type_id" , m->type); +jsonw_uint_field (w,"bits_offset" , bit_off); +if (bit_sz) { +jsonw_uint_field (w,"bitfield_size" , + bit_sz); + } +jsonw_end_object (w); + }else { +printf ("\n\t'%s' type_id=%u bits_offset=%u" , + name, m->type, bit_off); +if (bit_sz) +printf (" bitfield_size=%u" , bit_sz); + } + } +if (json_output) +jsonw_end_array (w); +break ; + } +case BTF_KIND_ENUM : { +const struct btf_enum *v = (const void *)(t +1 ); +__u16 vlen =BTF_INFO_VLEN (t->info); +int i; + +if (json_output) { +jsonw_uint_field (w,"size" , t->size); +jsonw_uint_field (w,"vlen" , vlen); +jsonw_name (w,"values" ); +jsonw_start_array (w); + }else { +printf (" size=%u vlen=%u" , t->size, vlen); + } +for (i =0 ; i < vlen; i++, v++) { +const char *name =btf_str (btf, v->name_off); + +if (json_output) { +jsonw_start_object (w); +jsonw_string_field (w,"name" , name); +jsonw_uint_field (w,"val" , v->val); +jsonw_end_object (w); + }else { +printf ("\n\t'%s' val=%u" , name, v->val); + } + } +if (json_output) +jsonw_end_array (w); +break ; + } +case BTF_KIND_FWD : { +const char *fwd_kind =BTF_INFO_KIND (t->info) ?"union" + :"struct" ; + +if (json_output) +jsonw_string_field (w,"fwd_kind" , fwd_kind); +else +printf (" fwd_kind=%s" , fwd_kind); +break ; + } +case BTF_KIND_FUNC : +if (json_output) +jsonw_uint_field (w,"type_id" , t->type); +else +printf (" type_id=%u" , t->type); +break ; +case BTF_KIND_FUNC_PROTO : { +const struct btf_param *p = (const void *)(t +1 ); +__u16 vlen =BTF_INFO_VLEN (t->info); +int i; + +if (json_output) { +jsonw_uint_field (w,"ret_type_id" , t->type); +jsonw_uint_field (w,"vlen" , vlen); +jsonw_name (w,"params" ); +jsonw_start_array (w); + }else { +printf (" ret_type_id=%u vlen=%u" , t->type, vlen); + } +for (i =0 ; i < vlen; i++, p++) { +const char *name =btf_str (btf, p->name_off); + +if (json_output) { +jsonw_start_object (w); +jsonw_string_field (w,"name" , name); +jsonw_uint_field (w,"type_id" , p->type); +jsonw_end_object (w); + }else { +printf ("\n\t'%s' type_id=%u" , name, p->type); + } + } +if (json_output) +jsonw_end_array (w); +break ; + } +case BTF_KIND_VAR : { +const struct btf_var *v = (const void *)(t +1 ); +const char *linkage; + + linkage =btf_var_linkage_str (v->linkage); + +if (json_output) { +jsonw_uint_field (w,"type_id" , t->type); +jsonw_string_field (w,"linkage" , linkage); + }else { +printf (" type_id=%u, linkage=%s" , t->type, linkage); + } +break ; + } +case BTF_KIND_DATASEC : { +const struct btf_var_secinfo *v = (const void *)(t+1 ); +__u16 vlen =BTF_INFO_VLEN (t->info); +int i; + +if (json_output) { +jsonw_uint_field (w,"size" , t->size); +jsonw_uint_field (w,"vlen" , vlen); +jsonw_name (w,"vars" ); +jsonw_start_array (w); + }else { +printf (" size=%u vlen=%u" , t->size, vlen); + } +for (i =0 ; i < vlen; i++, v++) { +if (json_output) { +jsonw_start_object (w); +jsonw_uint_field (w,"type_id" , v->type); +jsonw_uint_field (w,"offset" , v->offset); +jsonw_uint_field (w,"size" , v->size); +jsonw_end_object (w); + }else { +printf ("\n\ttype_id=%u offset=%u size=%u" , + v->type, v->offset, v->size); + } + } +if (json_output) +jsonw_end_array (w); +break ; + } +default : +break ; + } + +if (json_output) +jsonw_end_object (json_wtr); +else +printf ("\n" ); + +return 0 ; +} + +static int dump_btf_raw (const struct btf *btf, +__u32 *root_type_ids,int root_type_cnt) +{ +const struct btf_type *t; +int i; + +if (json_output) { +jsonw_start_object (json_wtr); +jsonw_name (json_wtr,"types" ); +jsonw_start_array (json_wtr); + } + +if (root_type_cnt) { +for (i =0 ; i < root_type_cnt; i++) { + t =btf__type_by_id (btf, root_type_ids[i]); +dump_btf_type (btf, root_type_ids[i], t); + } + }else { +int cnt =btf__get_nr_types (btf); + +for (i =1 ; i <= cnt; i++) { + t =btf__type_by_id (btf, i); +dump_btf_type (btf, i, t); + } + } + +if (json_output) { +jsonw_end_array (json_wtr); +jsonw_end_object (json_wtr); + } +return 0 ; +} + +static bool check_btf_endianness (GElf_Ehdr *ehdr) +{ +static unsigned int const endian =1 ; + +switch (ehdr->e_ident[EI_DATA ]) { +case ELFDATA2LSB : +return *(unsigned char const *)&endian ==1 ; +case ELFDATA2MSB : +return *(unsigned char const *)&endian ==0 ; +default : +return 0 ; + } +} + +static int btf_load_from_elf (const char *path,struct btf **btf) +{ +int err =-1 , fd =-1 , idx =0 ; +Elf_Data *btf_data =NULL ; +Elf_Scn *scn =NULL ; +Elf *elf =NULL ; +GElf_Ehdr ehdr; + +if (elf_version (EV_CURRENT ) ==EV_NONE ) { +p_err ("failed to init libelf for %s" , path); +return -1 ; + } + + fd =open (path,O_RDONLY ); +if (fd <0 ) { +p_err ("failed to open %s: %s" , path,strerror (errno)); +return -1 ; + } + + elf =elf_begin (fd,ELF_C_READ ,NULL ); +if (!elf) { +p_err ("failed to open %s as ELF file" , path); + goto done; + } +if (!gelf_getehdr (elf, &ehdr)) { +p_err ("failed to get EHDR from %s" , path); + goto done; + } +if (!check_btf_endianness (&ehdr)) { +p_err ("non-native ELF endianness is not supported" ); + goto done; + } +if (!elf_rawdata (elf_getscn (elf, ehdr.e_shstrndx),NULL )) { +p_err ("failed to get e_shstrndx from %s\n" , path); + goto done; + } + +while ((scn =elf_nextscn (elf, scn)) !=NULL ) { +GElf_Shdr sh; +char *name; + + idx++; +if (gelf_getshdr (scn, &sh) != &sh) { +p_err ("failed to get section(%d) header from %s" , + idx, path); + goto done; + } + name =elf_strptr (elf, ehdr.e_shstrndx, sh.sh_name); +if (!name) { +p_err ("failed to get section(%d) name from %s" , + idx, path); + goto done; + } +if (strcmp (name,BTF_ELF_SEC ) ==0 ) { + btf_data =elf_getdata (scn,0 ); +if (!btf_data) { +p_err ("failed to get section(%d, %s) data from %s" , + idx, name, path); + goto done; + } +break ; + } + } + +if (!btf_data) { +p_err ("%s ELF section not found in %s" ,BTF_ELF_SEC , path); + goto done; + } + + *btf =btf__new (btf_data->d_buf, btf_data->d_size); +if (IS_ERR (*btf)) { + err =PTR_ERR (*btf); + *btf =NULL ; +p_err ("failed to load BTF data from %s: %s" , + path,strerror (err)); + goto done; + } + + err =0 ; +done: +if (err) { +if (*btf) { +btf__free (*btf); + *btf =NULL ; + } + } +if (elf) +elf_end (elf); +close (fd); +return err; +} + +static int do_dump (int argc,char **argv) +{ +struct btf *btf =NULL ; +__u32 root_type_ids[2 ]; +int root_type_cnt =0 ; +__u32 btf_id =-1 ; +const char *src; +int fd =-1 ; +int err; + +if (!REQ_ARGS (2 )) { +usage (); +return -1 ; + } + src =GET_ARG (); + +if (is_prefix (src,"map" )) { +struct bpf_map_info info = {}; +__u32 len =sizeof (info); + +if (!REQ_ARGS (2 )) { +usage (); +return -1 ; + } + + fd =map_parse_fd_and_info (&argc, &argv, &info, &len); +if (fd <0 ) +return -1 ; + + btf_id = info.btf_id; +if (argc &&is_prefix (*argv,"key" )) { + root_type_ids[root_type_cnt++] = info.btf_key_type_id; +NEXT_ARG (); + }else if (argc &&is_prefix (*argv,"value" )) { + root_type_ids[root_type_cnt++] = info.btf_value_type_id; +NEXT_ARG (); + }else if (argc &&is_prefix (*argv,"all" )) { +NEXT_ARG (); + }else if (argc &&is_prefix (*argv,"kv" )) { + root_type_ids[root_type_cnt++] = info.btf_key_type_id; + root_type_ids[root_type_cnt++] = info.btf_value_type_id; +NEXT_ARG (); + }else { + root_type_ids[root_type_cnt++] = info.btf_key_type_id; + root_type_ids[root_type_cnt++] = info.btf_value_type_id; + } + }else if (is_prefix (src,"prog" )) { +struct bpf_prog_info info = {}; +__u32 len =sizeof (info); + +if (!REQ_ARGS (2 )) { +usage (); +return -1 ; + } + + fd =prog_parse_fd (&argc, &argv); +if (fd <0 ) +return -1 ; + + err =bpf_obj_get_info_by_fd (fd, &info, &len); +if (err) { +p_err ("can't get prog info: %s" ,strerror (errno)); + goto done; + } + + btf_id = info.btf_id; + }else if (is_prefix (src,"id" )) { +char *endptr; + + btf_id =strtoul (*argv, &endptr,0 ); +if (*endptr) { +p_err ("can't parse %s as ID" , **argv); +return -1 ; + } +NEXT_ARG (); + }else if (is_prefix (src,"file" )) { + err =btf_load_from_elf (*argv, &btf); +if (err) + goto done; +NEXT_ARG (); + }else { + err =-1 ; +p_err ("unrecognized BTF source specifier: '%s'" , src); + goto done; + } + +if (!btf) { + err =btf__get_from_id (btf_id, &btf); +if (err) { +p_err ("get btf by id (%u): %s" , btf_id,strerror (err)); + goto done; + } +if (!btf) { + err =ENOENT ; +p_err ("can't find btf with ID (%u)" , btf_id); + goto done; + } + } + +dump_btf_raw (btf, root_type_ids, root_type_cnt); + +done: +close (fd); +btf__free (btf); +return err; +} + +static int do_help (int argc,char **argv) +{ +if (json_output) { +jsonw_null (json_wtr); +return 0 ; + } + +fprintf (stderr, +"Usage: %s btf dump BTF_SRC\n" +" %s btf help\n" +"\n" +" BTF_SRC := { id BTF_ID | prog PROG | map MAP [{key | value | kv | all}] | file FILE }\n" +" " HELP_SPEC_MAP "\n" +" " HELP_SPEC_PROGRAM "\n" +" " HELP_SPEC_OPTIONS "\n" +"" , + bin_name, bin_name); + +return 0 ; +} + +static const struct cmd cmds[] = { + {"help" , do_help }, + {"dump" , do_dump }, + {0 } +}; + +int do_btf (int argc,char **argv) +{ +return cmd_select (cmds, argc, argv, do_help); +}
tools/bpf/bpftool/main.c +2 -1
@@ -56,7 +56,7 @@ static int do_help(int argc, char **argv)" %s batch file FILE\n" " %s version\n" "\n" -" OBJECT := { prog | map | cgroup | perf | net | feature }\n" +" OBJECT := { prog | map | cgroup | perf | net | feature | btf }\n" " " HELP_SPEC_OPTIONS "\n" "" , bin_name, bin_name, bin_name);
@@ -188,6 +188,7 @@ static const struct cmd cmds[] = { { "perf", do_perf }, { "net", do_net }, { "feature", do_feature }, + { "btf", do_btf }, { "version", do_version }, { 0 } };
tools/bpf/bpftool/main.h +1 -0
@@ -150,6 +150,7 @@ int do_perf(int argc, char **arg);int do_net (int argc,char **arg);int do_tracelog (int argc,char **arg);int do_feature (int argc,char **argv); +int do_btf (int argc,char **argv);int parse_u32_arg (int *argc,char ***argv,__u32 *val,const char *what);int prog_parse_fd (int *argc,char ***argv);
Signature · 1 line
2.17.1
PATCH v4 2/4 bpftool/docs: add btf sub-command documentation
In reply to Andrii NakryikoDocument usage and sample output format for btf dump sub-command.
--- .../bpf/bpftool/Documentation/bpftool-btf.rst | 222 ++++++++++++++++++ .../bpftool/Documentation/bpftool-cgroup.rst | 3 +- .../bpftool/Documentation/bpftool-feature.rst | 3 +- .../bpf/bpftool/Documentation/bpftool-map.rst | 3 +- .../bpf/bpftool/Documentation/bpftool-net.rst | 3 +- .../bpftool/Documentation/bpftool-perf.rst | 3 +- .../bpftool/Documentation/bpftool-prog.rst | 3 +- tools/bpf/bpftool/Documentation/bpftool.rst | 3 +- 8 files changed, 236 insertions(+), 7 deletions(-) create mode 100644 tools/bpf/bpftool/Documentation/bpftool-btf.rst
tools/bpf/bpftool/Documentation/bpftool-btf.rst new file +222 -0
@@ -0,0 +1,222 @@ +================ +bpftool-btf +================ +------------------------------------------------------------------------------- +tool for inspection of BTF data +------------------------------------------------------------------------------- + +:Manual section: 8 + +SYNOPSIS +======== + + **bpftool** [*OPTIONS*] **btf** *COMMAND* + + *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] } + + *COMMANDS* := { **dump** | **help** } + +BTF COMMANDS +============= + +| **bpftool** **btf dump** *BTF_SRC* +| **bpftool** **btf help** +| +| *BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* } +| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } +| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } + +DESCRIPTION +=========== + **bpftool btf dump** *BTF_SRC* + Dump BTF entries from a given *BTF_SRC*. + + When **id** is specified, BTF object with that ID will be + loaded and all its BTF types emitted. + + When **map** is provided, it's expected that map has + associated BTF object with BTF types describing key and + value. It's possible to select whether to dump only BTF + type(s) associated with key (**key**), value (**value**), + both key and value (**kv**), or all BTF types present in + associated BTF object (**all**). If not specified, **kv** + is assumed. + + When **prog** is provided, it's expected that program has + associated BTF object with BTF types. + + When specifying *FILE*, an ELF file is expected, containing + .BTF section with well-defined BTF binary format data, + typically produced by clang or pahole. + + **bpftool btf help** + Print short help message. + +OPTIONS +======= + -h, --help + Print short generic help message (similar to **bpftool help**). + + -V, --version + Print version number (similar to **bpftool version**). + + -j, --json + Generate JSON output. For commands that cannot produce JSON, this + option has no effect. + + -p, --pretty + Generate human-readable JSON output. Implies **-j**. + +EXAMPLES +======== +**# bpftool btf dump id 1226** +:: + + [1] PTR '(anon)' type_id=2 + [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2 + 'pad' type_id=3 bits_offset=0 + 'sock' type_id=4 bits_offset=64 + [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none) + [4] PTR '(anon)' type_id=5 + [5] FWD 'sock' fwd_kind=union + +This gives an example of default output for all supported BTF kinds. + +**$ cat prog.c** +:: + + struct fwd_struct; + + enum my_enum { + VAL1 = 3, + VAL2 = 7, + }; + + typedef struct my_struct my_struct_t; + + struct my_struct { + const unsigned int const_int_field; + int bitfield_field: 4; + char arr_field[16]; + const struct fwd_struct *restrict fwd_field; + enum my_enum enum_field; + volatile my_struct_t *typedef_ptr_field; + }; + + union my_union { + int a; + struct my_struct b; + }; + + struct my_struct struct_global_var __attribute__((section("data_sec"))) = { + .bitfield_field = 3, + .enum_field = VAL1, + }; + int global_var __attribute__((section("data_sec"))) = 7; + + __attribute__((noinline)) + int my_func(union my_union *arg1, int arg2) + { + static int static_var __attribute__((section("data_sec"))) = 123; + static_var++; + return static_var; + } + +**$ bpftool btf dump file prog.o** +:: + + [1] PTR '(anon)' type_id=2 + [2] UNION 'my_union' size=48 vlen=2 + 'a' type_id=3 bits_offset=0 + 'b' type_id=4 bits_offset=0 + [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED + [4] STRUCT 'my_struct' size=48 vlen=6 + 'const_int_field' type_id=5 bits_offset=0 + 'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4 + 'arr_field' type_id=8 bits_offset=40 + 'fwd_field' type_id=10 bits_offset=192 + 'enum_field' type_id=14 bits_offset=256 + 'typedef_ptr_field' type_id=15 bits_offset=320 + [5] CONST '(anon)' type_id=6 + [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none) + [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED + [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16 + [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none) + [10] RESTRICT '(anon)' type_id=11 + [11] PTR '(anon)' type_id=12 + [12] CONST '(anon)' type_id=13 + [13] FWD 'fwd_struct' fwd_kind=union + [14] ENUM 'my_enum' size=4 vlen=2 + 'VAL1' val=3 + 'VAL2' val=7 + [15] PTR '(anon)' type_id=16 + [16] VOLATILE '(anon)' type_id=17 + [17] TYPEDEF 'my_struct_t' type_id=4 + [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2 + 'arg1' type_id=1 + 'arg2' type_id=3 + [19] FUNC 'my_func' type_id=18 + [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc + [21] VAR 'global_var' type_id=3, linkage=global-alloc + [22] VAR 'my_func.static_var' type_id=3, linkage=static + [23] DATASEC 'data_sec' size=0 vlen=3 + type_id=20 offset=0 size=48 + type_id=21 offset=0 size=4 + type_id=22 offset=52 size=4 + +The following commands print BTF types associated with specified map's key, +value, both key and value, and all BTF types, respectively. By default, both +key and value types will be printed. + +**# bpftool btf dump map id 123 key** + +:: + + [39] TYPEDEF 'u32' type_id=37 + +**# bpftool btf dump map id 123 value** + +:: + + [86] PTR '(anon)' type_id=87 + +**# bpftool btf dump map id 123 kv** + +:: + + [39] TYPEDEF 'u32' type_id=37 + [86] PTR '(anon)' type_id=87 + +**# bpftool btf dump map id 123 all** + +:: + + [1] PTR '(anon)' type_id=0 + . + . + . + [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4 + +All the standard ways to specify map or program are supported: + +**# bpftool btf dump map id 123** + +**# bpftool btf dump map pinned /sys/fs/bpf/map_name** + +**# bpftool btf dump prog id 456** + +**# bpftool btf dump prog tag b88e0a09b1d9759d** + +**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name** + +SEE ALSO +======== + **bpf**\ (2), + **bpf-helpers**\ (7), + **bpftool**\ (8), + **bpftool-map**\ (8), + **bpftool-prog**\ (8), + **bpftool-cgroup**\ (8), + **bpftool-feature**\ (8), + **bpftool-net**\ (8), + **bpftool-perf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-cgroup.rst +2 -1
@@ -145,4 +145,5 @@ SEE ALSO **bpftool-map**\ (8), **bpftool-feature**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-feature.rst +2 -1
@@ -82,4 +82,5 @@ SEE ALSO **bpftool-map**\ (8), **bpftool-cgroup**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-map.rst +2 -1
@@ -258,4 +258,5 @@ SEE ALSO **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-net.rst +2 -1
@@ -143,4 +143,5 @@ SEE ALSO **bpftool-map**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-perf.rst +2 -1
@@ -85,4 +85,5 @@ SEE ALSO **bpftool-map**\ (8), **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), - **bpftool-net**\ (8) + **bpftool-net**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool-prog.rst +2 -1
@@ -271,4 +271,5 @@ SEE ALSO **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
tools/bpf/bpftool/Documentation/bpftool.rst +2 -1
@@ -76,4 +76,5 @@ SEE ALSO **bpftool-cgroup**\ (8), **bpftool-feature**\ (8), **bpftool-net**\ (8), - **bpftool-perf**\ (8) + **bpftool-perf**\ (8), + **bpftool-btf**\ (8)
Signature · 1 line
2.17.1
PATCH v4 3/4 bpftool: add bash completions for btf command
In reply to Andrii NakryikoAdd full support for btf command in bash-completion script.
--- tools/bpf/bpftool/bash-completion/bpftool | 46 +++++++++++++++++++++++ 1 file changed, 46 insertions(+)
tools/bpf/bpftool/bash-completion/bpftool +46 -0
@@ -217,6 +217,7 @@ _bpftool() done cur=${words[cword]} prev=${words[cword - 1]} + pprev=${words[cword - 2]} local object=${words[1]} command=${words[2]}
@@ -607,6 +608,51 @@ _bpftool() ;; esac ;; + btf) + local PROG_TYPE='id pinned tag' + local MAP_TYPE='id pinned' + case $command in + dump) + case $prev in + $command) + COMPREPLY+=( $( compgen -W "id map prog file" -- \ + "$cur" ) ) + return 0 + ;; + prog) + COMPREPLY=( $( compgen -W "$PROG_TYPE" -- "$cur" ) ) + return 0 + ;; + map) + COMPREPLY=( $( compgen -W "$MAP_TYPE" -- "$cur" ) ) + return 0 + ;; + id) + case $pprev in + prog) + _bpftool_get_prog_ids + ;; + map) + _bpftool_get_map_ids + ;; + esac + return 0 + ;; + *) + if [[ $cword == 6 ]] && [[ ${words[3]} == "map" ]]; then + COMPREPLY+=( $( compgen -W 'key value kv all' -- \ + "$cur" ) ) + fi + return 0 + ;; + esac + ;; + *) + [[ $prev == $object ]] && \ + COMPREPLY=( $( compgen -W 'dump help' -- "$cur" ) ) + ;; + esac + ;; cgroup) case $command in show|list)
Signature · 1 line
2.17.1
PATCH v4 4/4 bpftool: fix indendation in bash-completion/bpftool
In reply to Andrii NakryikoFix misaligned default case branch for prog dump sub-command.
--- tools/bpf/bpftool/bash-completion/bpftool | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-)
tools/bpf/bpftool/bash-completion/bpftool +11 -11
@@ -273,17 +273,17 @@ _bpftool() "$cur" ) ) return 0 ;; - *) - _bpftool_once_attr 'file' - if _bpftool_search_list 'xlated'; then - COMPREPLY+=( $( compgen -W 'opcodes visual linum' -- \ - "$cur" ) ) - else - COMPREPLY+=( $( compgen -W 'opcodes linum' -- \ - "$cur" ) ) - fi - return 0 - ;; + *) + _bpftool_once_attr 'file' + if _bpftool_search_list 'xlated'; then + COMPREPLY+=( $( compgen -W 'opcodes visual linum' -- \ + "$cur" ) ) + else + COMPREPLY+=( $( compgen -W 'opcodes linum' -- \ + "$cur" ) ) + fi + return 0 + ;; esac ;; pin)
Signature · 1 line
2.17.1
Alexei Starovoitov
AppliedQuoted 27 lines · Andrii Nakryiko
This patch set adds a new
bpftool btf dumpsub-command, which allows to dump BTF contents (only types for now). Currently it only outputs low-level content, almost 1:1 with binary BTF format, but follow up patches will add ability to dump BTF types as a compilable C header file. JSON output is supported as well.Patch #1 adds
btfsub-command, dumping BTF types in human-readable format. It also implements reading .BTF data from ELF file.
Patch #2 adds minimal documentation with output format examples and different ways to specify source of BTF data.
Patch #3 adds support for btf command in bash-completion/bpftool script. Patch #4 fixes minor indentation issue in bash-completion script.Output format is mostly following existing format of BPF verifier log, but deviates from it in few places. More details are in commit message for patch #1.
Example of output for all supported BTF kinds are in patch #2 as part of documentation. Some field names are quite verbose and I'd rather shorten them, if we don't feel like being very close to BPF verifier names is a necessity, but in this patch I left them exactly the same as in verifier log.
v3->v4:
- reverse Christmas tree (Quentin)
- better docs (Quentin)
Quoted 8 lines
v2->v3:
- make map's key|value|kv|all suggestion more precise (Quentin)
- fix default case indentations (Quentin)
v1->v2:
- fix unnecessary trailing whitespaces inbpftool-btf.rst(Yonghong)
- add btf inmain.cfor a list of possible OBJECTs
- handle unknown keyword underbpftool btf dump(Yonghong)
Applied. Thanks!