bpf: expose original requested max_entries in bpf_map_info
Subsystems (4)
PATCH 1/1 bpf: expose original requested max_entries in bpf_map_info
When creating LRU hash maps with BPF_F_NO_COMMON_LRU, the kernel silently rounds max_entries up to a multiple of num_possible_cpus() in htab_map_alloc() to ensure each per-CPU LRU list has at least one element. However, the original value requested by the caller is lost -- map->max_entries is overwritten with the rounded value.
This creates a problem for userspace map managers (e.g., Cilium) that reconcile map parameters against their configured values. When the kernel-reported max_entries differs from the originally requested value, the reconciliation logic detects a "mismatch" and may enter an infinite delete-recreate loop, as seen in production incidents where non-power- of-2 CPU counts caused small but persistent rounding differences.
Add a new 'requested_max_entries' field to struct bpf_map (kernel- internal) and struct bpf_map_info (UAPI) that preserves the caller's original max_entries value. The field is set in bpf_map_init_from_attr() before any map-type-specific adjustments, and exposed to userspace via BPF_OBJ_GET_INFO_BY_FD.
This is a purely additive, backward-compatible change:
- Old callers that don't know about the new field see it zeroed (via memset in bpf_map_get_info_by_fd) and can safely ignore it.
- New callers can compare requested_max_entries vs max_entries to detect kernel adjustments and avoid false reconciliation mismatches.
The new field is placed between max_entries (u32) and map_extra (u64) in struct bpf_map, filling the existing alignment padding hole -- no increase in struct size.
Also update the BPF_F_NO_COMMON_LRU documentation to describe the rounding behavior and the new field.
Selftests are included covering LRU hash maps with and without BPF_F_NO_COMMON_LRU, LRU per-CPU hash maps with BPF_F_NO_COMMON_LRU, and regular hash maps.
--- include/linux/bpf.h | 1 + include/uapi/linux/bpf.h | 12 ++ kernel/bpf/syscall.c | 2 + tools/include/uapi/linux/bpf.h | 12 ++ .../prog_tests/map_requested_max_entries.c | 134 ++++++++++++++++++ 5 files changed, 161 insertions(+) create mode 100644 tools/testing/selftests/bpf/prog_tests/map_requested_max_entries.c
include/linux/bpf.h +1 -0
@@ -304,6 +304,7 @@ struct bpf_map {u32 key_size;u32 value_size;u32 max_entries; +u32 requested_max_entries;/* original max_entries before kernel adjustment */ u64 map_extra;/* any per-map-type extra fields */ u32 map_flags;u32 id;
include/uapi/linux/bpf.h +12 -0
@@ -1405,6 +1405,12 @@ enum {* which can scale and perform better. * Note, the LRU nodes (including free nodes) cannot be moved * across different LRU lists. +* +* When this flag is set, the kernel rounds max_entries up to a multiple +* of num_possible_cpus() so that each per-CPU LRU list has at least one +* element. The actual (possibly adjusted) value is reported via +* bpf_map_info.max_entries, while the original requested value is +* preserved in bpf_map_info.requested_max_entries. */ BPF_F_NO_COMMON_LRU = (1U << 1),/* Specify numa node during map creation */
@@ -6717,6 +6723,12 @@ struct bpf_map_info {__u64 map_extra;__aligned_u64 hash;__u32 hash_size; +/* Original max_entries as requested by the caller. May differ from +* max_entries if the kernel adjusted it (e.g., rounded up to a +* multiple of num_possible_cpus() for per-CPU LRU hash maps when +* BPF_F_NO_COMMON_LRU is set). +*/ +__u32 requested_max_entries; } __attribute__((aligned(8)));struct bpf_btf_info {
kernel/bpf/syscall.c +2 -0
@@ -439,6 +439,7 @@ void bpf_map_init_from_attr(struct bpf_map *map, union bpf_attr *attr) map->key_size = attr->key_size; map->value_size = attr->value_size; map->max_entries = attr->max_entries; + map->requested_max_entries = attr->max_entries; map->map_flags =bpf_map_flags_retain_permanent (attr->map_flags); map->numa_node =bpf_map_attr_numa_node (attr); map->map_extra = attr->map_extra;
@@ -5301,6 +5302,7 @@ static int bpf_map_get_info_by_fd(struct file *file, info.key_size = map->key_size; info.value_size = map->value_size; info.max_entries = map->max_entries; + info.requested_max_entries = map->requested_max_entries; info.map_flags = map->map_flags; info.map_extra = map->map_extra;memcpy (info.name, map->name,sizeof (map->name));
tools/include/uapi/linux/bpf.h +12 -0
@@ -1405,6 +1405,12 @@ enum {* which can scale and perform better. * Note, the LRU nodes (including free nodes) cannot be moved * across different LRU lists. +* +* When this flag is set, the kernel rounds max_entries up to a multiple +* of num_possible_cpus() so that each per-CPU LRU list has at least one +* element. The actual (possibly adjusted) value is reported via +* bpf_map_info.max_entries, while the original requested value is +* preserved in bpf_map_info.requested_max_entries. */ BPF_F_NO_COMMON_LRU = (1U << 1),/* Specify numa node during map creation */
@@ -6717,6 +6723,12 @@ struct bpf_map_info {__u64 map_extra;__aligned_u64 hash;__u32 hash_size; +/* Original max_entries as requested by the caller. May differ from +* max_entries if the kernel adjusted it (e.g., rounded up to a +* multiple of num_possible_cpus() for per-CPU LRU hash maps when +* BPF_F_NO_COMMON_LRU is set). +*/ +__u32 requested_max_entries; } __attribute__((aligned(8)));struct bpf_btf_info {
tools/testing/selftests/bpf/prog_tests/map_requested_max_entries.c new file +134 -0
134 lines not on this page · raw message
Signature · 1 line
2.39.5 (Apple Git-154)
Quoted 7 lines · Anand Kumar Shaw
When creating LRU hash maps with
BPF_F_NO_COMMON_LRU, the kernel silently roundsmax_entriesup to a multiple ofnum_possible_cpus()inhtab_map_alloc()to ensure each per-CPU LRU list has at least one element. However, the original value requested by the caller is lost --map->max_entriesis overwritten with the rounded value.
Quoted 6 lines
This creates a problem for userspace map managers (e.g., Cilium) that reconcile map parameters against their configured values. When the kernel-reported
max_entriesdiffers from the originally requested value, the reconciliation logic detects a "mismatch" and may enter an infinite delete-recreate loop, as seen in production incidents where non-power- of-2 CPU counts caused small but persistent rounding differences.
Clearly a user space issue.
The kernel side never promised to keep max_entries constant.
pw-bot: cr
Quoted 2 lines · On Sat, Feb 15, 2026 Alexei Starovoitov <[email protected]> wrote:
Clearly a user space issue.
The kernel side never promised to keepmax_entriesconstant.
Thank you for the review, Alexei.
I agree that callers who create maps can track their own values. However, BPF maps can be pinned to bpffs and opened by a different process that didn't create them. In that case, the consumer has no way to distinguish a kernel-adjusted max_entries from the original request. The kernel is the only entity that knows the adjustment happened.
That said, I understand this may not be a strong enough use case to justify a permanent UAPI addition. Happy to drop the patch if that's the consensus.
Thanks,
Anand