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 <jordan@xxxxxxxx> --- 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
