bpftool: Support symbolic map creation flags
Subsystems (4)
v5 cover bpftool: Support symbolic map creation flags
Add comma-separated BPF_F_* names to map create flags, with matching documentation, completion and selftests.
Changes in v5:
- State explicitly that the old numeric parser accepted empty input as zero and could truncate or wrap out-of-range values. Rejecting those inputs is an intentional compatibility change already present in v4.
- Explain why BPF_F_PATH_FD is excluded from map creation flags.
- Point the manual to feature list_builtins map_create_flags for the accepted symbolic names and rewrap the feature documentation.
The parser and tests are unchanged from v4.
v4: https://lore.kernel.org/r/[email protected]
Review: https://lore.kernel.org/r/523c73e7f76e0634a3e061e76ca4c39eb21cb006fc78875ddaf6a35e38bfd500@mail.kernel.org
Validation:
- Rebuilt bpftool, its manual pages and the focused selftest runner.
- All 29 bpftool_map_flags subtests passed. The three revised series were tested together: 52 subtests passed with no skips or failures in an x86-64 KVM guest running Linux 7.3.0-rc2 from bpf/master, with LLVM 20-built BPF test objects.
- Bash syntax, bpftool synchronization checks and diff checks passed.
- The generated patches apply cleanly to current bpf-next.
This was a focused run. Unrelated selftests requiring unavailable kernel features were excluded from the build with PERMISSIVE=1.
Tianyi Chen (2):
bpftool: Accept symbolic map creation flags selftests/bpf: Cover symbolic bpftool map creation flags
.../bpftool/Documentation/bpftool-feature.rst | 16 +-- .../bpf/bpftool/Documentation/bpftool-map.rst | 15 ++- tools/bpf/bpftool/bash-completion/bpftool | 22 +++- tools/bpf/bpftool/feature.c | 7 +- tools/bpf/bpftool/main.h | 1 + tools/bpf/bpftool/map.c | 86 ++++++++++++++- .../bpf/prog_tests/bpftool_map_flags.c | 100 ++++++++++++++++++ 7 files changed, 231 insertions(+), 16 deletions(-) create mode 100644 tools/testing/selftests/bpf/prog_tests/bpftool_map_flags.c
base-commit: af0b84a9215d951d16f26b7ee34353b970cf5d4e
Signature · 1 line
2.55.0
PATCH v5 1/2 bpftool: Accept symbolic map creation flags
From: Tianyi Chen <[email protected]>
Accept comma-separated BPF_F_* names for map create flags, so callers can use the UAPI names without looking up their numeric values. Keep base-0 unsigned 32-bit numeric input, including bits unknown to bpftool.
Reject empty names, unknown names and mixed numeric and symbolic lists. The old numeric parser accepted an empty string as zero and could truncate or wrap out-of-range values; reject those inputs as well. Parser acceptance still leaves the kernel to validate the flags for the requested map type.
List accepted symbolic names through feature list_builtins and use the same list for completion. Avoid appending a space to completed list elements so another flag can be added to the same argument.
--- .../bpftool/Documentation/bpftool-feature.rst | 16 ++-- .../bpf/bpftool/Documentation/bpftool-map.rst | 15 +++- tools/bpf/bpftool/bash-completion/bpftool | 22 ++++- tools/bpf/bpftool/feature.c | 7 +- tools/bpf/bpftool/main.h | 1 + tools/bpf/bpftool/map.c | 86 ++++++++++++++++++- 6 files changed, 131 insertions(+), 16 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-feature.rst +9 -7
@@ -28,7 +28,7 @@ FEATURE COMMANDS | **bpftool** **feature help** | | *COMPONENT* := { **kernel** | **dev** *NAME* } -| *GROUP* := { **prog_types** | **map_types** | **attach_types** | **link_types** | **helpers** } +| *GROUP* := { **prog_types** | **map_types** | **map_create_flags** | **attach_types** | **link_types** | **helpers** } DESCRIPTION ===========
@@ -68,12 +68,14 @@ bpftool feature probe dev *NAME* [full] [macros [prefix *PREFIX*]] bpftool feature list_builtins *GROUP* List items known to bpftool. These can be BPF program types - (**prog_types**), BPF map types (**map_types**), attach types - (**attach_types**), link types (**link_types**), or BPF helper functions - (**helpers**). The command does not probe the system, but simply lists the - elements that bpftool knows from compilation time, as provided from libbpf - (for all object types) or from the BPF UAPI header (list of helpers). This - can be used in scripts to iterate over BPF types or helpers. + (**prog_types**), BPF map types (**map_types**), map creation flags + (**map_create_flags**), attach types (**attach_types**), link types + (**link_types**), or BPF helper functions (**helpers**). The command does + not probe the system, but simply lists the elements that bpftool knows + from compilation time, as provided from libbpf (for all object types) or + from the BPF UAPI header (helpers and map creation flags). This can be used + in scripts to iterate over BPF types, helpers, or the symbolic flags + accepted by **map create**. bpftool feature help Print short help message.
tools/bpf/bpftool/Documentation/bpftool-map.rst +12 -3
@@ -48,6 +48,7 @@ MAP COMMANDS | *DATA* := { [**hex**] *BYTES* } | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } | *VALUE* := { *DATA* | *MAP* | *PROG* } +| *FLAGS* := { integer | **BPF_F_NAME[,BPF_F_NAME...]** } | *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } | *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** | | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
@@ -76,9 +77,17 @@ bpftool map { show | list } [*MAP*] bpftool map create *FILE* type *TYPE* key *KEY_SIZE* value *VALUE_SIZE* entries *MAX_ENTRIES* name *NAME* [flags *FLAGS*] [inner_map *MAP*] [offload_dev *NAME*] Create a new map with given parameters and pin it to *bpffs* as *FILE*. - *FLAGS* should be an integer which is the combination of desired flags, - e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h UAPI header for existing - flags). + *FLAGS* accepts an unsigned 32-bit integer combining the desired flags + (decimal, hexadecimal with a **0x** prefix, or octal with a **0** prefix), + or a comma-separated list of full, case-sensitive map creation flag names + from the bpf.h UAPI header. Use **bpftool feature list_builtins + map_create_flags** to list accepted symbolic names. For example, **1024**, + **0x400**, and **BPF_F_MMAPABLE** are equivalent. Multiple names are combined + with bitwise OR, for example **BPF_F_NO_PREALLOC,BPF_F_RDONLY_PROG**. + Repeated names are allowed. Empty list elements, abbreviated names, and + lists mixing numbers with names are not accepted. Use **0** for no flags. + Numeric values can include bits unknown to bpftool. The kernel checks + whether the flags are valid for the requested map type. To create maps of type array-of-maps or hash-of-maps, the **inner_map** keyword must be used to pass an inner map. The kernel needs it to collect
tools/bpf/bpftool/bash-completion/bpftool +20 -2
@@ -718,6 +718,10 @@ _bpftool() esac ;; create) + # Keep a flags list together if readline splits at commas. + if [[ $COMP_WORDBREAKS == *,* && ( $cur == , || $prev == , ) ]]; then + _get_comp_words_by_ref -n , cur prev + fi case $prev in $command) _filedir
@@ -729,7 +733,21 @@ _bpftool() COMPREPLY=( $( compgen -W "$BPFTOOL_MAP_CREATE_TYPES" -- "$cur" ) ) return 0 ;; - key|value|flags|entries) + flags) + compopt -o nospace + local flags="$(bpftool feature list_builtins map_create_flags 2>/dev/null)" + local prefix= flag + # If comma is not a word break, Readline replaces the whole + # word, so preserve the flags before the last comma. + if [[ $cur == *,* && $COMP_WORDBREAKS != *,* ]]; then + prefix="${cur%,*}," + fi + for flag in $(compgen -W "$flags" -- "${cur##*,}"); do + COMPREPLY+=( "${prefix}${flag}" ) + done + return 0 + ;; + key|value|entries) return 0 ;; inner_map)
@@ -1192,7 +1210,7 @@ _bpftool() ;; list_builtins) [[ $prev != "$command" ]] && return 0 - COMPREPLY=( $( compgen -W 'prog_types map_types \ + COMPREPLY=( $( compgen -W 'prog_types map_types map_create_flags \ attach_types link_types helpers' -- "$cur" ) ) ;; *)
tools/bpf/bpftool/feature.c +5 -2
@@ -1220,6 +1220,8 @@ static int do_list_builtins(int argc, char **argv) get_name = (const char *(*)(unsigned int ))libbpf_bpf_prog_type_str; }else if (is_prefix (*argv,"map_types" )) { get_name = (const char *(*)(unsigned int ))libbpf_bpf_map_type_str; + }else if (is_prefix (*argv,"map_create_flags" )) { + get_name = map_create_flag_name; }else if (is_prefix (*argv,"attach_types" )) { get_name = (const char *(*)(unsigned int ))libbpf_bpf_attach_type_str; }else if (is_prefix (*argv,"link_types" )) {
@@ -1227,7 +1229,7 @@ static int do_list_builtins(int argc, char **argv) }else if (is_prefix (*argv,"helpers" )) { get_name = get_helper_name; }else { -p_err ("expected 'prog_types', 'map_types', 'attach_types', 'link_types' or 'helpers', got: %s" , *argv); +p_err ("expected 'prog_types', 'map_types', 'map_create_flags', 'attach_types', 'link_types' or 'helpers', got: %s" , *argv);return -1 ; }
@@ -1265,7 +1267,8 @@ static int do_help(int argc, char **argv)" %1$s %2$s help\n" "\n" " COMPONENT := { kernel | dev NAME }\n" -" GROUP := { prog_types | map_types | attach_types | link_types | helpers }\n" +" GROUP := { prog_types | map_types | map_create_flags |\n" +" attach_types | link_types | helpers }\n" " " HELP_SPEC_OPTIONS " }\n" "" , bin_name, argv[-2]);
tools/bpf/bpftool/main.h +1 -0
@@ -180,6 +180,7 @@ int do_token(int argc, char **argv) __weak;int parse_u32_arg (int *argc,char ***argv,__u32 *val,const char *what);int prog_parse_fd (int *argc,char ***argv);int prog_parse_fds (int *argc,char ***argv,int **fds); +const char *map_create_flag_name (unsigned int id);int map_parse_fd (int *argc,char ***argv,__u32 open_flags);int map_parse_fds (int *argc,char ***argv,int **fds,__u32 open_flags); int map_parse_fd_and_info(int *argc, char ***argv, struct bpf_map_info *info,
tools/bpf/bpftool/map.c +84 -2
105 lines not on this page · raw message
Signature · 1 line
2.55.0
PATCH v5 2/2 selftests/bpf: Cover symbolic bpftool map creation flags
In reply to Tianyi ChenFrom: Tianyi Chen <[email protected]>
Check numeric and symbolic map creation flags, including combined and repeated names, against map information read independently with libbpf. Exercise malformed names and lists, update-only flags, empty input and numeric range errors. Verify rejected input leaves no pinned map.
--- .../bpf/prog_tests/bpftool_map_flags.c | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 tools/testing/selftests/bpf/prog_tests/bpftool_map_flags.c
tools/testing/selftests/bpf/prog_tests/bpftool_map_flags.c new file +100 -0
@@ -0,0 +1,100 @@ +// SPDX-License-Identifier: GPL-2.0-only + +#include <errno.h> +#include <unistd.h> +#include <bpf/bpf.h> +#include <bpftool_helpers.h> +#include <test_progs.h> + +static const struct map_flags_test { +const char *name; +const char *flags; +__u32 expected_flags; +const char *error; +} tests[] = { + {"zero" ,"0" ,0 }, + {"decimal" ,"129" ,BPF_F_NO_PREALLOC |BPF_F_RDONLY_PROG }, + {"hexadecimal" ,"0x81" ,BPF_F_NO_PREALLOC |BPF_F_RDONLY_PROG }, + {"octal" ,"0201" ,BPF_F_NO_PREALLOC |BPF_F_RDONLY_PROG }, + {"positive_sign" ,"+1" ,BPF_F_NO_PREALLOC }, + {"single_name" ,"BPF_F_NO_PREALLOC" ,BPF_F_NO_PREALLOC }, + {"combined_names" ,"BPF_F_NO_PREALLOC,BPF_F_RDONLY_PROG" , +BPF_F_NO_PREALLOC |BPF_F_RDONLY_PROG }, + {"repeated_name" ,"BPF_F_NO_PREALLOC,BPF_F_NO_PREALLOC" ,BPF_F_NO_PREALLOC }, + {"unknown_name" ,"BPF_F_NOT_A_MAP_FLAG" ,0 ,"can't parse" }, + {"other_command_flag" ,"BPF_F_PATH_FD" ,0 ,"can't parse" }, + {"update_flag" ,"BPF_F_LOCK" ,0 ,"can't parse" }, + {"abbreviated_name" ,"BPF_F_NO_PRE" ,0 ,"can't parse" }, + {"lowercase_name" ,"bpf_f_no_prealloc" ,0 ,"can't parse" }, + {"empty" ,"" ,0 ,"can't parse" }, + {"whitespace" ," " ,0 ,"can't parse" }, + {"empty_list" ,"," ,0 ,"can't parse" }, + {"leading_comma" ,",BPF_F_NO_PREALLOC" ,0 ,"can't parse" }, + {"trailing_comma" ,"BPF_F_NO_PREALLOC," ,0 ,"can't parse" }, + {"empty_element" ,"BPF_F_NO_PREALLOC,,BPF_F_RDONLY_PROG" ,0 ,"can't parse" }, + {"number_then_name" ,"1,BPF_F_RDONLY_PROG" ,0 ,"can't parse" }, + {"name_then_number" ,"BPF_F_NO_PREALLOC,128" ,0 ,"can't parse" }, + {"numeric_list" ,"1,128" ,0 ,"can't parse" }, + {"whitespace_in_list" ,"BPF_F_NO_PREALLOC, BPF_F_RDONLY_PROG" ,0 ,"can't parse" }, + {"overflow_u32" ,"4294967296" ,0 ,"can't parse" }, + {"overflow_hex" ,"0x100000000" ,0 ,"can't parse" }, + {"overflow_u64" ,"18446744073709551616" ,0 ,"can't parse" }, + {"negative" ,"-1" ,0 ,"can't parse" }, +/* Numeric bits unknown to bpftool must still reach the kernel. */ + {"all_bits" ,"0xffffffff" ,0 ,"map create failed" }, +/* The kernel validates combinations of known map creation flags. */ + {"invalid_combination" ,"BPF_F_RDONLY,BPF_F_WRONLY" ,0 ,"map create failed" }, +}; + +static void test_map_flags (const struct map_flags_test *test,const char *path) +{ +char cmd[MAX_BPFTOOL_CMD_LEN ], output[1024 ] = {}; +struct bpf_map_info info = {}; +__u32 info_len =sizeof (info); +int fd, err; + +/* Let the flags parser handle negative numbers instead of getopt(). */ + err =snprintf (cmd,sizeof (cmd), +"-- map create %s type hash key 4 value 4 entries 1 name flags_test flags '%s' 2>&1" , + path, test->flags); +if (!ASSERT_GT (err,0 ,"format_command" ) || + !ASSERT_LT (err,sizeof (cmd),"command_length" )) +return ; + + err =get_bpftool_command_output (cmd, output,sizeof (output)); +if (test->error) { +ASSERT_NEQ (err,0 ,"reject_flags" ); +ASSERT_HAS_SUBSTR (output, test->error,"error_message" ); + err =access (path,F_OK ); +ASSERT_EQ (err,-1 ,"no_pin" ); +ASSERT_EQ (errno,ENOENT ,"pin_absent" ); + goto cleanup; + } +if (!ASSERT_OK (err,"create_map" )) + goto cleanup; + + fd =bpf_obj_get (path); +if (!ASSERT_OK_FD (fd,"open_map" )) + goto cleanup; +if (ASSERT_OK (bpf_map_get_info_by_fd (fd, &info, &info_len),"map_info" )) +ASSERT_EQ (info.map_flags, test->expected_flags,"map_flags" ); +close (fd); +cleanup: +unlink (path); +} + +void test_bpftool_map_flags (void ) +{ +char dir[] ="/sys/fs/bpf/bpftool_flags_XXXXXX" ; +char path[sizeof (dir) +sizeof ("/map" )]; +int i; + +if (!ASSERT_OK_PTR (mkdtemp (dir),"create_pin_dir" )) +return ; +snprintf (path,sizeof (path),"%s/map" , dir); +for (i =0 ; i <ARRAY_SIZE (tests); i++) { +if (test__start_subtest (tests[i].name)) +test_map_flags (&tests[i], path); + } +ASSERT_OK (rmdir (dir),"remove_pin_dir" ); +}
Signature · 1 line
2.55.0