1.. SPDX-License-Identifier: GPL-2.0-only 2.. Copyright (C) 2022 Red Hat, Inc. 3 4========================================= 5BPF_MAP_TYPE_QUEUE and BPF_MAP_TYPE_STACK 6========================================= 7 8.. note:: 9 - ``BPF_MAP_TYPE_QUEUE`` and ``BPF_MAP_TYPE_STACK`` were introduced 10 in kernel version 4.20 11 12``BPF_MAP_TYPE_QUEUE`` provides FIFO storage and ``BPF_MAP_TYPE_STACK`` 13provides LIFO storage for BPF programs. These maps support peek, pop and 14push operations that are exposed to BPF programs through the respective 15helpers. These operations are exposed to userspace applications using 16the existing ``bpf`` syscall in the following way: 17 18- ``BPF_MAP_LOOKUP_ELEM`` -> peek 19- ``BPF_MAP_LOOKUP_AND_DELETE_ELEM`` -> pop 20- ``BPF_MAP_UPDATE_ELEM`` -> push 21 22``BPF_MAP_TYPE_QUEUE`` and ``BPF_MAP_TYPE_STACK`` do not support 23``BPF_F_NO_PREALLOC``. 24 25Usage 26===== 27 28Kernel BPF 29---------- 30 31bpf_map_push_elem() 32~~~~~~~~~~~~~~~~~~~ 33 34.. code-block:: c 35 36 long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags) 37 38An element ``value`` can be added to a queue or stack using the 39``bpf_map_push_elem`` helper. The ``flags`` parameter must be set to 40``BPF_ANY`` or ``BPF_EXIST``. If ``flags`` is set to ``BPF_EXIST`` then, 41when the queue or stack is full, the oldest element will be removed to 42make room for ``value`` to be added. Returns ``0`` on success, or 43negative error in case of failure. 44 45bpf_map_peek_elem() 46~~~~~~~~~~~~~~~~~~~ 47 48.. code-block:: c 49 50 long bpf_map_peek_elem(struct bpf_map *map, void *value) 51 52This helper fetches an element ``value`` from a queue or stack without 53removing it. Returns ``0`` on success, or negative error in case of 54failure. 55 56bpf_map_pop_elem() 57~~~~~~~~~~~~~~~~~~ 58 59.. code-block:: c 60 61 long bpf_map_pop_elem(struct bpf_map *map, void *value) 62 63This helper removes an element into ``value`` from a queue or 64stack. Returns ``0`` on success, or negative error in case of failure. 65 66 67Userspace 68--------- 69 70bpf_map_update_elem() 71~~~~~~~~~~~~~~~~~~~~~ 72 73.. code-block:: c 74 75 int bpf_map_update_elem (int fd, const void *key, const void *value, __u64 flags) 76 77A userspace program can push ``value`` onto a queue or stack using libbpf's 78``bpf_map_update_elem`` function. The ``key`` parameter must be set to 79``NULL`` and ``flags`` must be set to ``BPF_ANY`` or ``BPF_EXIST``, with the 80same semantics as the ``bpf_map_push_elem`` kernel helper. Returns ``0`` on 81success, or negative error in case of failure. 82 83bpf_map_lookup_elem() 84~~~~~~~~~~~~~~~~~~~~~ 85 86.. code-block:: c 87 88 int bpf_map_lookup_elem (int fd, const void *key, void *value) 89 90A userspace program can peek at the ``value`` at the head of a queue or stack 91using the libbpf ``bpf_map_lookup_elem`` function. The ``key`` parameter must be 92set to ``NULL``. Returns ``0`` on success, or negative error in case of 93failure. 94 95bpf_map_lookup_and_delete_elem() 96~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 98.. code-block:: c 99 100 int bpf_map_lookup_and_delete_elem (int fd, const void *key, void *value) 101 102A userspace program can pop a ``value`` from the head of a queue or stack using 103the libbpf ``bpf_map_lookup_and_delete_elem`` function. The ``key`` parameter 104must be set to ``NULL``. Returns ``0`` on success, or negative error in case of 105failure. 106 107Examples 108======== 109 110Kernel BPF 111---------- 112 113This snippet shows how to declare a queue in a BPF program: 114 115.. code-block:: c 116 117 struct { 118 __uint(type, BPF_MAP_TYPE_QUEUE); 119 __type(value, __u32); 120 __uint(max_entries, 10); 121 } queue SEC(".maps"); 122 123 124Userspace 125--------- 126 127This snippet shows how to use libbpf's low-level API to create a queue from 128userspace: 129 130.. code-block:: c 131 132 int create_queue() 133 { 134 return bpf_map_create(BPF_MAP_TYPE_QUEUE, 135 "sample_queue", /* name */ 136 0, /* key size, must be zero */ 137 sizeof(__u32), /* value size */ 138 10, /* max entries */ 139 NULL); /* create options */ 140 } 141 142 143References 144========== 145 146https://lwn.net/ml/netdev/153986858555.9127.14517764371945179514.stgit@kernel/ 147