Documentation/bpf/maps.rst

   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