Documentation/bpf/map_hash.rst

1 .. SPDX-License-Identifier: GPL-2.0-only
3 .. Copyright (C) 2022-2023 Isovalent, Inc.
10    - ``BPF_MAP_TYPE_HASH`` was introduced in kernel version 3.19
11    - ``BPF_MAP_TYPE_PERCPU_HASH`` was introduced in version 4.6
12    - Both ``BPF_MAP_TYPE_LRU_HASH`` and ``BPF_MAP_TYPE_LRU_PERCPU_HASH``
16 purpose hash map storage. Both the key and the value can be structs,
19 The kernel is responsible for allocating and freeing key/value pairs, up
20 to the max_entries limit that you specify. Hash maps use pre-allocation
22 used to disable pre-allocation when it is too memory expensive.
24 ``BPF_MAP_TYPE_PERCPU_HASH`` provides a separate value slot per
25 CPU. The per-cpu values are stored internally in an array.
40 **BPF_F_NO_COMMON_LRU**  Per-CPU LRU, global map   Per-CPU LRU, per-cpu map
41 **!BPF_F_NO_COMMON_LRU** Global LRU, global map    Global LRU, per-cpu map
48 ----------
53 .. code-block:: c
55    long bpf_map_update_elem(struct bpf_map *map, const void *key, const void *value, u64 flags)
61 - ``BPF_ANY`` will create a new element or update an existing element
62 - ``BPF_NOEXIST`` will create a new element only if one did not already
64 - ``BPF_EXIST`` will update an existing element
72 .. code-block:: c
74    void *bpf_map_lookup_elem(struct bpf_map *map, const void *key)
77 helper. This helper returns a pointer to the value associated with
78 ``key``, or ``NULL`` if no entry was found.
83 .. code-block:: c
85    long bpf_map_delete_elem(struct bpf_map *map, const void *key)
92 --------------
101 .. code-block:: c
103    void *bpf_map_lookup_percpu_elem(struct bpf_map *map, const void *key, u32 cpu)
106 value in the hash slot for a specific CPU. Returns value associated with
107 ``key`` on ``cpu`` , or ``NULL`` if no entry was found or ``cpu`` is
111 -----------
119 ---------
124 .. code-block:: c
129 libbpf's ``bpf_map_get_next_key()`` function. The first key can be fetched by
131 ``NULL``. Subsequent calls will fetch the next key that follows the
132 current key. ``bpf_map_get_next_key()`` returns 0 on success, -ENOENT if
133 cur_key is the last key in the hash, or negative error in case of
137 will instead return the *first* key in the hash table which is
139 to be key deletion intermixed with ``bpf_map_get_next_key()``.
147 This example shows how to declare an LRU Hash with a struct key and a
148 struct value.
150 .. code-block:: c
155     struct key {
159     struct value {
167             __type(key, struct key);
168             __type(value, struct value);
174 .. code-block:: c
178             struct key key = {
181             struct value *value = bpf_map_lookup_elem(&packet_stats, &key);
183             if (value) {
184                     __sync_fetch_and_add(&value->packets, 1);
185                     __sync_fetch_and_add(&value->bytes, bytes);
187                     struct value newval = { 1, bytes };
189                     bpf_map_update_elem(&packet_stats, &key, &newval, BPF_NOEXIST);
195 .. code-block:: c
202             struct key *cur_key = NULL;
203             struct key next_key;
204             struct value value;
212                     bpf_map_lookup_elem(map_fd, &next_key, &value);
214                     // Use key and value here
228 --------------------------------------
235 - Attempt to use CPU-local state to batch operations
236 - Attempt to fetch free nodes from global lists
237 - Attempt to pull any node from a global list and remove it from the hashmap
238 - Attempt to pull any node from any CPU's list and remove it from the hashmap
244 .. kernel-figure::  map_lru_hash_update.dot
252 either a successful update or a failure with various error codes. The key in
259 properties would be per-cpu.