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 31.. c:function:: 32 long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags) 33 34An element ``value`` can be added to a queue or stack using the 35``bpf_map_push_elem`` helper. The ``flags`` parameter must be set to 36``BPF_ANY`` or ``BPF_EXIST``. If ``flags`` is set to ``BPF_EXIST`` then, 37when the queue or stack is full, the oldest element will be removed to 38make room for ``value`` to be added. Returns ``0`` on success, or 39negative error in case of failure. 40 41.. c:function:: 42 long bpf_map_peek_elem(struct bpf_map *map, void *value) 43 44This helper fetches an element ``value`` from a queue or stack without 45removing it. Returns ``0`` on success, or negative error in case of 46failure. 47 48.. c:function:: 49 long bpf_map_pop_elem(struct bpf_map *map, void *value) 50 51This helper removes an element into ``value`` from a queue or 52stack. Returns ``0`` on success, or negative error in case of failure. 53 54 55Userspace 56--------- 57 58.. c:function:: 59 int bpf_map_update_elem (int fd, const void *key, const void *value, __u64 flags) 60 61A userspace program can push ``value`` onto a queue or stack using libbpf's 62``bpf_map_update_elem`` function. The ``key`` parameter must be set to 63``NULL`` and ``flags`` must be set to ``BPF_ANY`` or ``BPF_EXIST``, with the 64same semantics as the ``bpf_map_push_elem`` kernel helper. Returns ``0`` on 65success, or negative error in case of failure. 66 67.. c:function:: 68 int bpf_map_lookup_elem (int fd, const void *key, void *value) 69 70A userspace program can peek at the ``value`` at the head of a queue or stack 71using the libbpf ``bpf_map_lookup_elem`` function. The ``key`` parameter must be 72set to ``NULL``. Returns ``0`` on success, or negative error in case of 73failure. 74 75.. c:function:: 76 int bpf_map_lookup_and_delete_elem (int fd, const void *key, void *value) 77 78A userspace program can pop a ``value`` from the head of a queue or stack using 79the libbpf ``bpf_map_lookup_and_delete_elem`` function. The ``key`` parameter 80must be set to ``NULL``. Returns ``0`` on success, or negative error in case of 81failure. 82 83Examples 84======== 85 86Kernel BPF 87---------- 88 89This snippet shows how to declare a queue in a BPF program: 90 91.. code-block:: c 92 93 struct { 94 __uint(type, BPF_MAP_TYPE_QUEUE); 95 __type(value, __u32); 96 __uint(max_entries, 10); 97 } queue SEC(".maps"); 98 99 100Userspace 101--------- 102 103This snippet shows how to use libbpf's low-level API to create a queue from 104userspace: 105 106.. code-block:: c 107 108 int create_queue() 109 { 110 return bpf_map_create(BPF_MAP_TYPE_QUEUE, 111 "sample_queue", /* name */ 112 0, /* key size, must be zero */ 113 sizeof(__u32), /* value size */ 114 10, /* max entries */ 115 NULL); /* create options */ 116 } 117 118 119References 120========== 121 122https://lwn.net/ml/netdev/153986858555.9127.14517764371945179514.stgit@kernel/ 123