| 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 | |
| 79 | |
| 80 | |
| 81 | |
| 82 | |