1
2 ========
3 BPF maps
4 ========
5
6 BPF 'maps' provide generic storage of different types for sharing data between
7 kernel and user space. There are several storage types available, including
8 hash, array, bloom filter and radix-tree. Several of the map types exist to
9 support specific BPF helpers that perform actions based on the map contents. The
10 maps are accessed from BPF programs via BPF helpers which are documented in the
11 `man-pages`_ for `bpf-helpers(7)`_.
12
13 BPF maps are accessed from user space via the ``bpf`` syscall, which provides
14 commands to create maps, lookup elements, update elements and delete elements.
15 More details of the BPF syscall are available in `ebpf-syscall`_ and in the
16 `man-pages`_ for `bpf(2)`_.
17
18 Map Types
19 =========
20
21 .. toctree::
22 :maxdepth: 1
23 :glob:
24
25 map_*
26
27 Usage Notes
28 ===========
29
30 .. c:function::
31 int bpf(int command, union bpf_attr *attr, u32 size)
32
33 Use the ``bpf()`` system call to perform the operation specified by
34 ``command``. The operation takes parameters provided in ``attr``. The ``size``
35 argument is the size of the ``union bpf_attr`` in ``attr``.
36
37 **BPF_MAP_CREATE**
38
39 Create 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
55 Returns a process-local file descriptor on success, or negative error in case of
56 failure. The map can be deleted by calling ``close(fd)``. Maps held by open
57 file 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
64 Lookup key in a given map using ``attr->map_fd``, ``attr->key``,
65 ``attr->value``. Returns zero and stores found elem into ``attr->value`` on
66 success, or negative error on failure.
67
68 **BPF_MAP_UPDATE_ELEM**
69
70 Create 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
75 Find 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.