1
2========
3BPF maps
4========
5
6BPF 'maps' provide generic storage of different types for sharing data between
7kernel and user space. There are several storage types available, including
8hash, array, bloom filter and radix-tree. Several of the map types exist to
9support specific BPF helpers that perform actions based on the map contents. The
10maps are accessed from BPF programs via BPF helpers which are documented in the
11`man-pages`_ for `bpf-helpers(7)`_.
12
13BPF maps are accessed from user space via the ``bpf`` syscall, which provides
14commands to create maps, lookup elements, update elements and delete elements.
15More details of the BPF syscall are available in `ebpf-syscall`_ and in the
16`man-pages`_ for `bpf(2)`_.
17
18Map Types
19=========
20
21.. toctree::
22   :maxdepth: 1
23   :glob:
24
25   map_*
26
27Usage Notes
28===========
29
30.. c:function::
31   int bpf(int command, union bpf_attr *attr, u32 size)
32
33Use the ``bpf()`` system call to perform the operation specified by
34``command``. The operation takes parameters provided in ``attr``. The ``size``
35argument is the size of the ``union bpf_attr`` in ``attr``.
36
37**BPF_MAP_CREATE**
38
39Create a map with the desired type and attributes in ``attr``:
40
41.. code-block:: c
42
43    int fd;
44    union bpf_attr attr = {
45            .map_type = BPF_MAP_TYPE_ARRAY;  /* mandatory */
46            .key_size = sizeof(__u32);       /* mandatory */
47            .value_size = sizeof(__u32);     /* mandatory */
48            .max_entries = 256;              /* mandatory */
49            .map_flags = BPF_F_MMAPABLE;
50            .map_name = "example_array";
51    };
52
53    fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr));
54
55Returns a process-local file descriptor on success, or negative error in case of
56failure. The map can be deleted by calling ``close(fd)``. Maps held by open
57file descriptors will be deleted automatically when a process exits.
58
59.. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``,
60   ``'_'`` and ``'.'``.
61
62**BPF_MAP_LOOKUP_ELEM**
63
64Lookup key in a given map using ``attr->map_fd``, ``attr->key``,
65``attr->value``. Returns zero and stores found elem into ``attr->value`` on
66success, or negative error on failure.
67
68**BPF_MAP_UPDATE_ELEM**
69
70Create or update key/value pair in a given map using ``attr->map_fd``, ``attr->key``,
71``attr->value``. Returns zero on success or negative error on failure.
72
73**BPF_MAP_DELETE_ELEM**
74
75Find and delete element by key in a given map using ``attr->map_fd``,
76``attr->key``. Returns zero on success or negative error on failure.
77
78.. Links:
79.. _man-pages: https://www.kernel.org/doc/man-pages/
80.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
81.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
82.. _ebpf-syscall: https://docs.kernel.org/userspace-api/ebpf/syscall.html
83