Commit | Line | Data |
---|---|---|
64488ca5 DH |
1 | .. SPDX-License-Identifier: GPL-2.0-only |
2 | .. Copyright (C) 2022 Red Hat, Inc. | |
3 | ||
4 | ========================================= | |
5 | BPF_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`` | |
13 | provides LIFO storage for BPF programs. These maps support peek, pop and | |
14 | push operations that are exposed to BPF programs through the respective | |
15 | helpers. These operations are exposed to userspace applications using | |
16 | the 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 | ||
25 | Usage | |
26 | ===== | |
27 | ||
28 | Kernel BPF | |
29 | ---------- | |
30 | ||
539886a3 DH |
31 | bpf_map_push_elem() |
32 | ~~~~~~~~~~~~~~~~~~~ | |
33 | ||
34 | .. code-block:: c | |
35 | ||
64488ca5 DH |
36 | long bpf_map_push_elem(struct bpf_map *map, const void *value, u64 flags) |
37 | ||
38 | An 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, | |
41 | when the queue or stack is full, the oldest element will be removed to | |
42 | make room for ``value`` to be added. Returns ``0`` on success, or | |
43 | negative error in case of failure. | |
44 | ||
539886a3 DH |
45 | bpf_map_peek_elem() |
46 | ~~~~~~~~~~~~~~~~~~~ | |
47 | ||
48 | .. code-block:: c | |
49 | ||
64488ca5 DH |
50 | long bpf_map_peek_elem(struct bpf_map *map, void *value) |
51 | ||
52 | This helper fetches an element ``value`` from a queue or stack without | |
53 | removing it. Returns ``0`` on success, or negative error in case of | |
54 | failure. | |
55 | ||
539886a3 DH |
56 | bpf_map_pop_elem() |
57 | ~~~~~~~~~~~~~~~~~~ | |
58 | ||
59 | .. code-block:: c | |
60 | ||
64488ca5 DH |
61 | long bpf_map_pop_elem(struct bpf_map *map, void *value) |
62 | ||
63 | This helper removes an element into ``value`` from a queue or | |
64 | stack. Returns ``0`` on success, or negative error in case of failure. | |
65 | ||
66 | ||
67 | Userspace | |
68 | --------- | |
69 | ||
539886a3 DH |
70 | bpf_map_update_elem() |
71 | ~~~~~~~~~~~~~~~~~~~~~ | |
72 | ||
73 | .. code-block:: c | |
74 | ||
64488ca5 DH |
75 | int bpf_map_update_elem (int fd, const void *key, const void *value, __u64 flags) |
76 | ||
77 | A 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 | |
80 | same semantics as the ``bpf_map_push_elem`` kernel helper. Returns ``0`` on | |
81 | success, or negative error in case of failure. | |
82 | ||
539886a3 DH |
83 | bpf_map_lookup_elem() |
84 | ~~~~~~~~~~~~~~~~~~~~~ | |
85 | ||
86 | .. code-block:: c | |
87 | ||
64488ca5 DH |
88 | int bpf_map_lookup_elem (int fd, const void *key, void *value) |
89 | ||
90 | A userspace program can peek at the ``value`` at the head of a queue or stack | |
91 | using the libbpf ``bpf_map_lookup_elem`` function. The ``key`` parameter must be | |
92 | set to ``NULL``. Returns ``0`` on success, or negative error in case of | |
93 | failure. | |
94 | ||
539886a3 DH |
95 | bpf_map_lookup_and_delete_elem() |
96 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
97 | ||
98 | .. code-block:: c | |
99 | ||
64488ca5 DH |
100 | int bpf_map_lookup_and_delete_elem (int fd, const void *key, void *value) |
101 | ||
102 | A userspace program can pop a ``value`` from the head of a queue or stack using | |
103 | the libbpf ``bpf_map_lookup_and_delete_elem`` function. The ``key`` parameter | |
104 | must be set to ``NULL``. Returns ``0`` on success, or negative error in case of | |
105 | failure. | |
106 | ||
107 | Examples | |
108 | ======== | |
109 | ||
110 | Kernel BPF | |
111 | ---------- | |
112 | ||
113 | This 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 | ||
124 | Userspace | |
125 | --------- | |
126 | ||
127 | This snippet shows how to use libbpf's low-level API to create a queue from | |
128 | userspace: | |
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 | ||
143 | References | |
144 | ========== | |
145 | ||
146 | https://lwn.net/ml/netdev/153986858555.9127.14517764371945179514.stgit@kernel/ |