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