Commit | Line | Data |
---|---|---|
bc84e959 | 1 | |
fb73a20e DH |
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 | |
cacad346 DV |
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)`_. | |
fb73a20e DH |
17 | |
18 | Map Types | |
5931d9a3 | 19 | ========= |
bc84e959 | 20 | |
fb73a20e DH |
21 | .. toctree:: |
22 | :maxdepth: 1 | |
23 | :glob: | |
bc84e959 | 24 | |
fb73a20e | 25 | map_* |
bc84e959 | 26 | |
fb73a20e DH |
27 | Usage Notes |
28 | =========== | |
bc84e959 | 29 | |
fb73a20e DH |
30 | .. c:function:: |
31 | int bpf(int command, union bpf_attr *attr, u32 size) | |
bc84e959 | 32 | |
fb73a20e DH |
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``. | |
bc84e959 | 36 | |
fb73a20e | 37 | **BPF_MAP_CREATE** |
bc84e959 | 38 | |
fb73a20e | 39 | Create a map with the desired type and attributes in ``attr``: |
bc84e959 | 40 | |
fb73a20e | 41 | .. code-block:: c |
bc84e959 | 42 | |
fb73a20e DH |
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 | }; | |
bc84e959 | 52 | |
fb73a20e | 53 | fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); |
bc84e959 | 54 | |
fb73a20e DH |
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. | |
bc84e959 | 58 | |
fb73a20e DH |
59 | .. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``, |
60 | ``'_'`` and ``'.'``. | |
5931d9a3 | 61 | |
fb73a20e DH |
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. | |
5931d9a3 | 77 | |
fb73a20e DH |
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 | |
cacad346 | 82 | .. _ebpf-syscall: https://docs.kernel.org/userspace-api/ebpf/syscall.html |