[RFC PATCH bpf-next 14/14] bpf, doc: Document map_extra and key prefix filtering for socket hash
From: Jordan Rife <hidden>
Date: 2025-09-09 17:00:47
Also in:
bpf
Subsystem:
bpf [general] (safe dynamic programs and tools), documentation, the rest · Maintainers:
Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko, Eduard Zingerman, Kumar Kartikeya Dwivedi, Jonathan Corbet, Linus Torvalds
Add documentation explaining how to use map_extra with a BPF_MAP_TYPE_SOCKHASH to control bucketing behavior and how to iterate over a specific bucket using a key prefix filter. Signed-off-by: Jordan Rife <redacted> --- Documentation/bpf/bpf_iterators.rst | 11 +++++++++++ Documentation/bpf/map_sockmap.rst | 6 ++++++ 2 files changed, 17 insertions(+)
diff --git a/Documentation/bpf/bpf_iterators.rst b/Documentation/bpf/bpf_iterators.rst
index 189e3ec1c6c8..135bf6a6195c 100644
--- a/Documentation/bpf/bpf_iterators.rst
+++ b/Documentation/bpf/bpf_iterators.rst@@ -587,3 +587,14 @@ A BPF task iterator with *pid* includes all tasks (threads) of a process. The BPF program receives these tasks one after another. You can specify a BPF task iterator with *tid* parameter to include only the tasks that match the given *tid*. + +--------------------------------------------- +Parametrizing BPF_MAP_TYPE_SOCKHASH Iterators +--------------------------------------------- + +An iterator for a ``BPF_MAP_TYPE_SOCKHASH`` can limit results to only sockets +whose keys share a common prefix by using a key prefix filter. The key prefix +length must match the value of ``map_extra`` if ``map_extra`` is used in the +``BPF_MAP_TYPE_SOCKHASH`` definition; otherwise, it must match the map key +length. This guarantees that the iterator only visits a single hash bucket, +ensuring efficient iteration over a subset of map elements.
diff --git a/Documentation/bpf/map_sockmap.rst b/Documentation/bpf/map_sockmap.rst
index 2d630686a00b..505e02c79feb 100644
--- a/Documentation/bpf/map_sockmap.rst
+++ b/Documentation/bpf/map_sockmap.rst@@ -76,6 +76,12 @@ sk_msg_buff *msg``. All these helpers will be described in more detail below. +Hashing behavior is configurable for ``BPF_MAP_TYPE_SOCKHASH`` using the lower +32 bits of ``map_extra``. When provided, ``map_extra`` specifies the number of +bytes from a key to use when calculating its bucket hash. This may be used +to force keys sharing a common prefix, e.g. an (address, port) tuple, into the +same bucket for efficient iteration. + Usage ===== Kernel BPF
--
2.43.0