bpftool: Formatting defined by user:fmt: decl tag
cover bpftool: Formatting defined by user:fmt: decl tag
bpftool map dump command is handy when developing and troubleshooting ebpf programs. It is nice to get data formatted in the most useful way, eliminating the need to postprocess bpftool output. There were multiple contributions in this vein over the years, e.g.:
30255d317579 bpftool: Print as a string for char array
Sometimes the type alone doesn't carry enough semantic information, such as __be32 storing an IPv4 address or __be16 encoding a port.
I propose using BTF decl tags to influence bpftool formatting. Specifically, if the type itself or any type in the typedef chain has "user:fmt:*" tag attached:
* "user:fmt:be" format the value as big-endian value (supports
2, 4, or 8 byte integers);
* "user:fmt:ip" format the value as IPv4 ot IPv6 address.
The typedef approach requires switching to a custom type (e.g. bpf_inaddr) in map keys, values, and types that are embedded in a key or value type.
The code remains nice and clean since the typedef and the underlying type are compatible; e.g. we can key.addr = iphdr->daddr;
Nick Zavaritsky (1):
bpftool: Formatting defined by user:fmt: decl tag
tools/bpf/bpftool/btf_dumper.c | 119 +++++++++++++++++++++++++++++---- tools/bpf/bpftool/main.h | 12 ++++ tools/bpf/bpftool/map.c | 7 +- 3 files changed, 124 insertions(+), 14 deletions(-)
Signature · 1 line
2.43.0
PATCH 1/1 bpftool: Formatting defined by user:fmt: decl tag
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Example:
typedef struct in6_addr bpf_in6_addr
__attribute__((__btf_decl_tag__("user:fmt:ip")));bpf_in6_addr in6;
$ bpftool map dump name .data
[{
"value": {
".data": [{
"in6": "2001:db8:130f::9c0:876a:130b"
}
]
}
}
]versus
$ bpftool map dump name .data
[{
"value": {
".data": [{
"in6": {
"in6_u": {
"u6_addr8": [32,1,13,184,19,15,0,0,0,0,9,192,135,106,19,11
],
"u6_addr16": [288,47117,3859,0,0,49161,27271,2835
],
"u6_addr32": [3087860000,3859,3221815296,185821831
]
}
}
}
]
}
}
]--- tools/bpf/bpftool/btf_dumper.c | 119 +++++++++++++++++++++++++++++---- tools/bpf/bpftool/main.h | 12 ++++ tools/bpf/bpftool/map.c | 7 +- 3 files changed, 124 insertions(+), 14 deletions(-)
tools/bpf/bpftool/btf_dumper.c +106 -13
@@ -11,6 +11,8 @@#include <linux/err.h> #include <bpf/btf.h> #include <bpf/bpf.h> +#include <errno.h> +#include <arpa/inet.h> #include "json_writer.h" #include "main.h"
@@ -132,18 +134,6 @@ static void btf_dumper_ptr(const struct btf_dumper *d,jsonw_printf (d->jw,"%lu" , value); } -static int btf_dumper_modifier (const struct btf_dumper *d,__u32 type_id, -__u8 bit_offset,const void *data) -{ -int actual_type_id; - - actual_type_id =btf__resolve_type (d->btf, type_id); -if (actual_type_id <0 ) -return actual_type_id; - -return btf_dumper_do_type (d, actual_type_id, bit_offset, data); -} -static int btf_dumper_enum (const struct btf_dumper *d,const struct btf_type *t,const void *data)
@@ -556,6 +546,36 @@ static int btf_dumper_do_type(const struct btf_dumper *d, __u32 type_id, __u8 bit_offset, const void *data) {const struct btf_type *t =btf__type_by_id (d->btf, type_id); +char addr[INET6_ADDRSTRLEN ]; + +if (!t) +return -errno; + +switch ((bit_offset ==0 && d->fmt_tags) ? d->fmt_tags[type_id] : +BTF_FMT_DEFAULT ) { +case BTF_FMT_BE16 : +jsonw_printf (d->jw,"\"%d\"" , +be16_to_cpu (*(const __be16 *)data)); +return 0 ; +case BTF_FMT_BE32 : +jsonw_printf (d->jw,"\"%u\"" , +be32_to_cpu (*(const __be32 *)data)); +return 0 ; +case BTF_FMT_BE64 : +jsonw_printf (d->jw,"\"%lu\"" , +be64_to_cpu (*(const __be64 *)data)); +return 0 ; +case BTF_FMT_IP4 : +jsonw_string (d->jw, +inet_ntop (AF_INET , data, addr,sizeof (addr))); +return 0 ; +case BTF_FMT_IP6 : +jsonw_string (d->jw, +inet_ntop (AF_INET6 , data, addr,sizeof (addr))); +return 0 ; +default : +break ; + }switch (BTF_INFO_KIND (t->info)) {case BTF_KIND_INT :
@@ -584,7 +604,7 @@ static int btf_dumper_do_type(const struct btf_dumper *d, __u32 type_id,case BTF_KIND_VOLATILE :case BTF_KIND_CONST :case BTF_KIND_RESTRICT : -return btf_dumper_modifier (d, type_id, bit_offset, data); +return btf_dumper_do_type (d, t->type, bit_offset, data);case BTF_KIND_VAR :return btf_dumper_var (d, type_id, bit_offset, data);case BTF_KIND_DATASEC :
@@ -595,6 +615,79 @@ static int btf_dumper_do_type(const struct btf_dumper *d, __u32 type_id, } } +enum btf_fmt_tag *btf_fmt_tags_get (const struct btf *btf) +{ +int n =btf__type_cnt (btf); +enum btf_fmt_tag *tags =calloc (n,sizeof (tags[0 ])); + +if (!tags) +return NULL ; + +for (int i =1 ; i < n; i++) { +const struct btf_type *t =btf__type_by_id (btf, i); +const struct btf_decl_tag *tag; +const char *name; +__s64 size; + +if (!t) + goto err_free; +if (btf_kind (t) !=BTF_KIND_DECL_TAG ) +continue ; + + tag = (const void *)(t +1 ); +if (tag->component_idx !=-1 ) +continue ; + + name =btf__name_by_offset (btf, t->name_off); +if (!name) + goto err_free; + +#define BTF_FMT_TAG_PREFIX "user:fmt:" +if (strncmp (name,BTF_FMT_TAG_PREFIX , +sizeof (BTF_FMT_TAG_PREFIX ) -1 )) +continue ; + + size =btf__resolve_size (btf, t->type); +if (size <0 ) +continue ;// could be a forward decl + +if (btf_kind (btf__type_by_id (btf, t->type)) ==BTF_KIND_VAR ) +continue ; + + name +=sizeof (BTF_FMT_TAG_PREFIX ) -1 ; +if (!strcmp (name,"be" )) { +switch (size) { +case 2 : + tags[t->type] =BTF_FMT_BE16 ; +break ; +case 4 : + tags[t->type] =BTF_FMT_BE32 ; +break ; +case 8 : + tags[t->type] =BTF_FMT_BE64 ; +break ; +default : +break ; + } + }else if (!strcmp (name,"ip" )) { +switch (size) { +case 4 : + tags[t->type] =BTF_FMT_IP4 ; +break ; +case 16 : + tags[t->type] =BTF_FMT_IP6 ; +break ; +default : +break ; + } + } + } +return tags; +err_free: +free (tags); +return NULL ; +} +int btf_dumper_type (const struct btf_dumper *d,__u32 type_id,const void *data) {
tools/bpf/bpftool/main.h +12 -0
@@ -210,8 +210,20 @@ unsigned int get_possible_cpus(void);const char *ifindex_to_arch (__u32 ifindex,__u64 ns_dev,__u64 ns_ino,const char **opt); +enum btf_fmt_tag { +BTF_FMT_DEFAULT =0 , +BTF_FMT_BE16 , +BTF_FMT_BE32 , +BTF_FMT_BE64 , +BTF_FMT_IP4 , +BTF_FMT_IP6 , +}; + +enum btf_fmt_tag *btf_fmt_tags_get (const struct btf *btf); +struct btf_dumper {const struct btf *btf; +const enum btf_fmt_tag *fmt_tags;json_writer_t *jw;bool is_plain_text;bool prog_id_as_func_ptr;
tools/bpf/bpftool/map.c +6 -1
@@ -744,6 +744,7 @@ static int do_show(int argc, char **argv)static int dump_map_elem (int fd,void *key,void *value,struct bpf_map_info *map_info,struct btf *btf, +const enum btf_fmt_tag *fmt_tags,json_writer_t *btf_wtr) {if (bpf_map_lookup_elem (fd, key, value)) {
@@ -756,6 +757,7 @@ static int dump_map_elem(int fd, void *key, void *value, }else if (btf) {struct btf_dumper d = { .btf = btf, + .fmt_tags = fmt_tags, .jw = btf_wtr, .is_plain_text = true, };
@@ -829,6 +831,7 @@ map_dump(int fd, struct bpf_map_info *info, json_writer_t *wtr,void *key, *value, *prev_key;unsigned int num_elems =0 ;struct btf *btf =NULL ; +enum btf_fmt_tag *fmt_tags =NULL ;int err; key =malloc (info->key_size);
@@ -846,6 +849,7 @@ map_dump(int fd, struct bpf_map_info *info, json_writer_t *wtr,if (err) { goto exit_free; } + fmt_tags =btf_fmt_tags_get (btf);if (show_header) {jsonw_start_object (wtr);/* map object */
@@ -872,7 +876,7 @@ map_dump(int fd, struct bpf_map_info *info, json_writer_t *wtr, err =0 ;break ; } -if (!dump_map_elem (fd, key, value, info, btf, wtr)) +if (!dump_map_elem (fd, key, value, info, btf, fmt_tags, wtr)) num_elems++; prev_key = key; }
@@ -891,6 +895,7 @@ map_dump(int fd, struct bpf_map_info *info, json_writer_t *wtr,free (value);close (fd);free_map_kv_btf (btf); +free (fmt_tags);return err; }
Signature · 1 line
2.43.0
Quentin Monnet
maintainerNote: For future submissions please make sure to add the maintainers in copy for your message, "./scripts/get_maintainer.pl tools/bpf/bpftool/" will give you the list.
2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
Quoted 31 lines
Example:
typedef struct
in6_addrbpf_in6_addr__attribute__((__btf_decl_tag__("user:fmt:ip")));
bpf_in6_addrin6;$ bpftool map dump name .data [{ "value": { ".data": [{ "in6": "2001:db8:130f::9c0:876a:130b" } ] } } ]versus
$ bpftool map dump name .data [{ "value": { ".data": [{ "in6": { "in6_u": { "u6_addr8": [32,1,13,184,19,15,0,0,0,0,9,192,135,106,19,11 ], "u6_addr16": [288,47117,3859,0,0,49161,27271,2835 ], "u6_addr32": [3087860000,3859,3221815296,185821831
Quoted 8 lines
]
}
}
}
]
}
}
]My concern with the example above is that 1) this may be a breaking change for existing scripts parsing map dumps, and 2) we lose the structure and byte representation for in6 (in this example), which means less post-processing for humans, but potentially more for tooling.
If you mean to use the BTF tags as opt-in in your own maps, then that's probably OK. If you mean to change it in existing structures, I don't know - maybe I'd add the custom representation _in addition_ to the existing one, rather than in place.
Quentin
Quoted 21 lines · Quentin Monnet
Note: For future submissions please make sure to add the maintainers in copy for your message, "
./scripts/get_maintainer.pltools/bpf/bpftool/" will give you the list.2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Quoted 6 lines
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
I don’t intend to touch existing kernel types. This feature targets ebpf projects that wish to make it easier for humans to process bpftool dumps of their maps.
By having it in bpftool, we eliminate the need for custom post processing. Bpftool can “make it easier for humans” more reliably since it has access to BTF (and tags). It is hard to write a generic post processor that improves the presentation of e.g. IP addresses. Pattern-matching will work for IPv6 addresses. For ports and IPv4 addresses not so much, unless wrapper structures are introduced (e.g. struct{__be32 ip4addr;}). Wrapper structures will make ebpf code using them look funny.
How can this feature get discovered? Having annotated types declared in bpftool headers will surely help.
Quoted 53 lines
Quoted 33 lines
Example:
typedef struct
in6_addrbpf_in6_addr
__attribute__((__btf_decl_tag__("user:fmt:ip")));bpf_in6_addrin6;$ bpftool map dump name .data [{ "value": { ".data": [{ "in6": "2001:db8:130f::9c0:876a:130b" } ] } } ]versus
$ bpftool map dump name .data [{ "value": { ".data": [{ "in6": { "in6_u": { "u6_addr8": [32,1,13,184,19,15,0,0,0,0,9,192,135,106,19,11 ], "u6_addr16": [288,47117,3859,0,0,49161,27271,2835 ], "u6_addr32": [3087860000,3859,3221815296,185821831Quoted 8 lines
] } } } ] } } ]My concern with the example above is that 1) this may be a breaking change for existing scripts parsing map dumps, and 2) we lose the structure and byte representation for in6 (in this example), which means less post-processing for humans, but potentially more for tooling.
If you mean to use the BTF tags as opt-in in your own maps, then that's probably OK. If you mean to change it in existing structures, I don't know - maybe I'd add the custom representation
_inaddition_to the existing one, rather than in place.Quentin
Quentin Monnet
maintainer2025-09-25 13:11 UTC+0200 ~ Nick Zavaritsky <[email protected]>
Quoted 41 lines
Quoted 21 lines · Quentin Monnet
Note: For future submissions please make sure to add the maintainers in copy for your message, "
./scripts/get_maintainer.pltools/bpf/bpftool/" will give you the list.2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Quoted 6 lines
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
I don’t intend to touch existing kernel types. This feature targets ebpf projects that wish to make it easier for humans to process bpftool dumps of their maps.
By having it in bpftool, we eliminate the need for custom post processing. Bpftool can “make it easier for humans” more reliably since it has access to BTF (and tags). It is hard to write a generic post processor that improves the presentation of e.g. IP addresses. Pattern-matching will work for IPv6 addresses. For ports and IPv4 addresses not so much, unless wrapper structures are introduced (e.g. struct{__be32 ip4addr;}). Wrapper structures will make ebpf code using them look funny.
Quoted 2 lines
How can this feature get discovered? Having annotated types declared in bpftool headers will surely help.
Yes, discoverability is one of my main concerns here. I'm not convinced it's a good idea to introduce a new convention for tags just for bpftool. If this gets adopted, this should be documented at a larger scale for other tooling to pick it up, too; and the defined formats should probably not be proper to bpftool. What "bpftool headers" are you talking about, exactly?
(My other concern would be security and the risk of obfuscating map contents from bpftool dumps, but given that formatting strings are defined in bpftool - not in user programs - and you have checks on lengths to associate format strings to pieces of data, I think we're good and I don't see a way for users to exploit this and hide some bytes from the formatted output.)
Quentin
Quoted 54 lines · Quentin Monnet
2025-09-25 13:11 UTC+0200 ~ Nick Zavaritsky <[email protected]>
Quoted 41 lines
Quoted 21 lines · Quentin Monnet
Note: For future submissions please make sure to add the maintainers in copy for your message, "
./scripts/get_maintainer.pltools/bpf/bpftool/" will give you the list.2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Quoted 6 lines
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
I don’t intend to touch existing kernel types. This feature targets ebpf projects that wish to make it easier for humans to process bpftool dumps of their maps.
By having it in bpftool, we eliminate the need for custom post processing. Bpftool can “make it easier for humans” more reliably since it has access to BTF (and tags). It is hard to write a generic post processor that improves the presentation of e.g. IP addresses. Pattern-matching will work for IPv6 addresses. For ports and IPv4 addresses not so much, unless wrapper structures are introduced (e.g. struct{__be32 ip4addr;}). Wrapper structures will make ebpf code using them look funny.
Quoted 2 lines
How can this feature get discovered? Having annotated types declared in bpftool headers will surely help.
Yes, discoverability is one of my main concerns here. I'm not convinced it's a good idea to introduce a new convention for tags just for bpftool. If this gets adopted, this should be documented at a larger scale for other tooling to pick it up, too; and the defined formats should probably not be proper to bpftool. What "bpftool headers" are you talking about, exactly?
Quoted 6 lines
(My other concern would be security and the risk of obfuscating map contents from bpftool dumps, but given that formatting strings are defined in bpftool - not in user programs - and you have checks on lengths to associate format strings to pieces of data, I think we're good and I don't see a way for users to exploit this and hide some bytes from the formatted output.)
I share these concerns.
Instead of introducing a new tag convention can we teach bpftool to pretty print fields when their type is uapi struct? Like, instead of adding:
typedef struct in6_addr bpf_in6_addr
__attribute__((__btf_decl_tag__("user:fmt:ip")));bpf_in6_addr in6;
just use "typedef struct in6_addr foo; foo in6;" or "struct in6_addr in6;" to define a field in a map and bpftool can print it as an ipv6 address? in6_addr semantics is fixed.
So we can pretty print it and similar structs.
Probably with an additional command line flag
to keep backward compat by default.
Quoted 73 lines · Alexei Starovoitov
Quoted 54 lines · Quentin Monnet
2025-09-25 13:11 UTC+0200 ~ Nick Zavaritsky <[email protected]>
Quoted 41 lines
Quoted 21 lines · Quentin Monnet
Note: For future submissions please make sure to add the maintainers in copy for your message, "
./scripts/get_maintainer.pltools/bpf/bpftool/" will give you the list.2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Quoted 6 lines
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
I don’t intend to touch existing kernel types. This feature targets ebpf projects that wish to make it easier for humans to process bpftool dumps of their maps.
By having it in bpftool, we eliminate the need for custom post processing. Bpftool can “make it easier for humans” more reliably since it has access to BTF (and tags). It is hard to write a generic post processor that improves the presentation of e.g. IP addresses. Pattern-matching will work for IPv6 addresses. For ports and IPv4 addresses not so much, unless wrapper structures are introduced (e.g. struct{__be32 ip4addr;}). Wrapper structures will make ebpf code using them look funny.
Quoted 2 lines
How can this feature get discovered? Having annotated types declared in bpftool headers will surely help.
Yes, discoverability is one of my main concerns here. I'm not convinced it's a good idea to introduce a new convention for tags just for bpftool. If this gets adopted, this should be documented at a larger scale for other tooling to pick it up, too; and the defined formats should probably not be proper to bpftool. What "bpftool headers" are you talking about, exactly?
Quoted 6 lines
(My other concern would be security and the risk of obfuscating map contents from bpftool dumps, but given that formatting strings are defined in bpftool - not in user programs - and you have checks on lengths to associate format strings to pieces of data, I think we're good and I don't see a way for users to exploit this and hide some bytes from the formatted output.)
I share these concerns.
Instead of introducing a new tag convention can we teach bpftool to pretty print fields when their type is uapi struct? Like, instead of adding:
typedef structin6_addrbpf_in6_addr
__attribute__((__btf_decl_tag__("user:fmt:ip")));bpf_in6_addrin6;
Quoted 3 lines
just use "typedef struct
in6_addrfoo; foo in6;" or "structin6_addrin6;" to define a field in a map and bpftool can print it as an ipv6 address?in6_addrsemantics is fixed.
Thank you for having a look! There are some challenges to consider with printing uapi structs.
There’s no uapi struct for IPv4 address, __be16 and friends aren’t structures either.
I understand the appeal of making formatting work without decl tags. A similar approach was taken with bpf_spinlock (special casing a structure type), but it is somewhat different. Spinlock is opaque. No one has a need to come up with their own definition to provide a convenient view into the data.
It is expected that BPF_spinlock might have special semantics since it is clearly a bpf-specific thing. Personally, I feel that special-casing common types such as IP addresses is very unexpected.
Lastly, in theory, people can target bpf with non-C languages. They might have their own idiomatic types named differently already.
Quoted 3 lines
So we can pretty print it and similar structs.
Probably with an additional command line flag
to keep backward compat by default.
Imagine bpftool learns about another type later. Do we have to add another flag for backward compat?
Quoted 50 lines · Quentin Monnet
2025-09-25 13:11 UTC+0200 ~ Nick Zavaritsky <[email protected]>
Quoted 41 lines
Quoted 21 lines · Quentin Monnet
Note: For future submissions please make sure to add the maintainers in copy for your message, "
./scripts/get_maintainer.pltools/bpf/bpftool/" will give you the list.2025-09-21 13:24 UTC+0000 ~ Nick Zavaritsky <[email protected]>
Quoted 9 lines
Certain data types get exceptionally unwieldy when formatted by bpftool, e.g. IP6 addresses.
Introduce custom formatting in bpftool driven by user:fmt: decl tag. When a type is tagged user:fmt:ip, the value is formatted as IP4 or IP6 address depending on the value size.
When a type is tagged user:fmt:be, the value is interpreted as a big-endian integer (2, 4 or 8 bytes).
Quoted 6 lines
Hi, thanks for this!
I'm not sure I understand correctly. The 'user:fmt:*' tags are not used yet, correct? So you're proposing to add it to existing code to get a fancier bpftool output. Do you mean adding it to your own executables? Or to existing kernel structures/types?
I don’t intend to touch existing kernel types. This feature targets ebpf projects that wish to make it easier for humans to process bpftool dumps of their maps.
By having it in bpftool, we eliminate the need for custom post processing. Bpftool can “make it easier for humans” more reliably since it has access to BTF (and tags). It is hard to write a generic post processor that improves the presentation of e.g. IP addresses. Pattern-matching will work for IPv6 addresses. For ports and IPv4 addresses not so much, unless wrapper structures are introduced (e.g. struct{__be32 ip4addr;}). Wrapper structures will make ebpf code using them look funny.
Quoted 2 lines
How can this feature get discovered? Having annotated types declared in bpftool headers will surely help.
Quoted 6 lines
Yes, discoverability is one of my main concerns here. I'm not convinced it's a good idea to introduce a new convention for tags just for bpftool. If this gets adopted, this should be documented at a larger scale for other tooling to pick it up, too; and the defined formats should probably not be proper to bpftool. What "bpftool headers" are you talking about, exactly?
I actually meant “libbpf header”, sorry for a confusing typo. So probably bpf_helpers.h. My idea was declaring bpf_be16, bpf_be32, bpf_be32, bpf_inaddr, and bpf_in6_addr typedefs, the last one via forward structure declaration.
This way the feature is somewhat discoverable (how do people find out about __arg_nonnull, etc?)
One can use the provided types as-is, or use the underlying mechanism to define a custom type, should someone be unhappy with bpf_inet_addr being an alias of __be32. People using non C languages with their own idiomatic types can leverage the proposed decl tags too.
Quoted 7 lines
(My other concern would be security and the risk of obfuscating map contents from bpftool dumps, but given that formatting strings are defined in bpftool - not in user programs - and you have checks on lengths to associate format strings to pieces of data, I think we're good and I don't see a way for users to exploit this and hide some bytes from the formatted output.)
It is not that hard to hide some bytes from bpftool.
struct __attribute__((aligned(128))) hide_some_bytes{
char c;
};
Quoted 2 lines
Quentin