1bc84e959SChristoph Hellwig 2fb73a20eSDonald Hunter======== 3fb73a20eSDonald HunterBPF maps 4fb73a20eSDonald Hunter======== 5bc84e959SChristoph Hellwig 6fb73a20eSDonald HunterBPF 'maps' provide generic storage of different types for sharing data between 7fb73a20eSDonald Hunterkernel and user space. There are several storage types available, including 8fb73a20eSDonald Hunterhash, array, bloom filter and radix-tree. Several of the map types exist to 9fb73a20eSDonald Huntersupport specific BPF helpers that perform actions based on the map contents. The 10fb73a20eSDonald Huntermaps are accessed from BPF programs via BPF helpers which are documented in the 11fb73a20eSDonald Hunter`man-pages`_ for `bpf-helpers(7)`_. 12bc84e959SChristoph Hellwig 13fb73a20eSDonald HunterBPF maps are accessed from user space via the ``bpf`` syscall, which provides 14*cacad346SDavid Vernetcommands to create maps, lookup elements, update elements and delete elements. 15*cacad346SDavid VernetMore details of the BPF syscall are available in `ebpf-syscall`_ and in the 16*cacad346SDavid Vernet`man-pages`_ for `bpf(2)`_. 17bc84e959SChristoph Hellwig 185931d9a3SDave TuckerMap Types 195931d9a3SDave Tucker========= 205931d9a3SDave Tucker 215931d9a3SDave Tucker.. toctree:: 225931d9a3SDave Tucker :maxdepth: 1 235931d9a3SDave Tucker :glob: 245931d9a3SDave Tucker 255931d9a3SDave Tucker map_* 26fb73a20eSDonald Hunter 27fb73a20eSDonald HunterUsage Notes 28fb73a20eSDonald Hunter=========== 29fb73a20eSDonald Hunter 30fb73a20eSDonald Hunter.. c:function:: 31fb73a20eSDonald Hunter int bpf(int command, union bpf_attr *attr, u32 size) 32fb73a20eSDonald Hunter 33fb73a20eSDonald HunterUse the ``bpf()`` system call to perform the operation specified by 34fb73a20eSDonald Hunter``command``. The operation takes parameters provided in ``attr``. The ``size`` 35fb73a20eSDonald Hunterargument is the size of the ``union bpf_attr`` in ``attr``. 36fb73a20eSDonald Hunter 37fb73a20eSDonald Hunter**BPF_MAP_CREATE** 38fb73a20eSDonald Hunter 39fb73a20eSDonald HunterCreate a map with the desired type and attributes in ``attr``: 40fb73a20eSDonald Hunter 41fb73a20eSDonald Hunter.. code-block:: c 42fb73a20eSDonald Hunter 43fb73a20eSDonald Hunter int fd; 44fb73a20eSDonald Hunter union bpf_attr attr = { 45fb73a20eSDonald Hunter .map_type = BPF_MAP_TYPE_ARRAY; /* mandatory */ 46fb73a20eSDonald Hunter .key_size = sizeof(__u32); /* mandatory */ 47fb73a20eSDonald Hunter .value_size = sizeof(__u32); /* mandatory */ 48fb73a20eSDonald Hunter .max_entries = 256; /* mandatory */ 49fb73a20eSDonald Hunter .map_flags = BPF_F_MMAPABLE; 50fb73a20eSDonald Hunter .map_name = "example_array"; 51fb73a20eSDonald Hunter }; 52fb73a20eSDonald Hunter 53fb73a20eSDonald Hunter fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); 54fb73a20eSDonald Hunter 55fb73a20eSDonald HunterReturns a process-local file descriptor on success, or negative error in case of 56fb73a20eSDonald Hunterfailure. The map can be deleted by calling ``close(fd)``. Maps held by open 57fb73a20eSDonald Hunterfile descriptors will be deleted automatically when a process exits. 58fb73a20eSDonald Hunter 59fb73a20eSDonald Hunter.. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``, 60fb73a20eSDonald Hunter ``'_'`` and ``'.'``. 61fb73a20eSDonald Hunter 62fb73a20eSDonald Hunter**BPF_MAP_LOOKUP_ELEM** 63fb73a20eSDonald Hunter 64fb73a20eSDonald HunterLookup key in a given map using ``attr->map_fd``, ``attr->key``, 65fb73a20eSDonald Hunter``attr->value``. Returns zero and stores found elem into ``attr->value`` on 66fb73a20eSDonald Huntersuccess, or negative error on failure. 67fb73a20eSDonald Hunter 68fb73a20eSDonald Hunter**BPF_MAP_UPDATE_ELEM** 69fb73a20eSDonald Hunter 70fb73a20eSDonald HunterCreate or update key/value pair in a given map using ``attr->map_fd``, ``attr->key``, 71fb73a20eSDonald Hunter``attr->value``. Returns zero on success or negative error on failure. 72fb73a20eSDonald Hunter 73fb73a20eSDonald Hunter**BPF_MAP_DELETE_ELEM** 74fb73a20eSDonald Hunter 75fb73a20eSDonald HunterFind and delete element by key in a given map using ``attr->map_fd``, 76fb73a20eSDonald Hunter``attr->key``. Returns zero on success or negative error on failure. 77fb73a20eSDonald Hunter 78fb73a20eSDonald Hunter.. Links: 79fb73a20eSDonald Hunter.. _man-pages: https://www.kernel.org/doc/man-pages/ 80fb73a20eSDonald Hunter.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html 81fb73a20eSDonald Hunter.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html 82*cacad346SDavid Vernet.. _ebpf-syscall: https://docs.kernel.org/userspace-api/ebpf/syscall.html 83