These descriptions are present in the man-pages project from the original submissions around 2015-2016. Import them so that they can be kept up to date as developers extend the bpf syscall commands. These descriptions follow the pattern used by scripts/bpf_helpers_doc.py so that we can take advantage of the parser to generate more up-to-date man page writing based upon these headers. Some minor wording adjustments were made to make the descriptions more consistent for the description / return format. Signed-off-by: Joe Stringer <joe@cilium.io> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Reviewed-by: Quentin Monnet <quentin@isovalent.com> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> Acked-by: Yonghong Song <yhs@fb.com> Link: https://lore.kernel.org/bpf/20210302171947.2268128-2-joe@cilium.io
Unified · Split
| @@ -93,7 +93,127 @@ union bpf_iter_link_info { · 92 unmodified lines | |||
| 93 | } map; | 93 | } map; |
| 94 | }; | 94 | }; |
| 95 | 95 | ||
| 96 | /* BPF syscall commands, see bpf(2) man-page for details. */ | 96 | /* BPF syscall commands, see bpf(2) man-page for more details. */ |
| 97 | /** | ||
| 98 | * DOC: eBPF Syscall Preamble | ||
| 99 | * | ||
| 100 | * The operation to be performed by the **bpf**\ () system call is determined | ||
| 101 | * by the *cmd* argument. Each operation takes an accompanying argument, | ||
| 102 | * provided via *attr*, which is a pointer to a union of type *bpf_attr* (see | ||
| 103 | * below). The size argument is the size of the union pointed to by *attr*. | ||
| 104 | */ | ||
| 105 | /** | ||
| 106 | * DOC: eBPF Syscall Commands | ||
| 107 | * | ||
| 108 | * BPF_MAP_CREATE | ||
| 109 | * Description | ||
| 110 | * Create a map and return a file descriptor that refers to the | ||
| 111 | * map. The close-on-exec file descriptor flag (see **fcntl**\ (2)) | ||
| 112 | * is automatically enabled for the new file descriptor. | ||
| 113 | * | ||
| 114 | * Applying **close**\ (2) to the file descriptor returned by | ||
| 115 | * **BPF_MAP_CREATE** will delete the map (but see NOTES). | ||
| 116 | * | ||
| 117 | * Return | ||
| 118 | * A new file descriptor (a nonnegative integer), or -1 if an | ||
| 119 | * error occurred (in which case, *errno* is set appropriately). | ||
| 120 | * | ||
| 121 | * BPF_MAP_LOOKUP_ELEM | ||
| 122 | * Description | ||
| 123 | * Look up an element with a given *key* in the map referred to | ||
| 124 | * by the file descriptor *map_fd*. | ||
| 125 | * | ||
| 126 | * Return | ||
| 127 | * Returns zero on success. On error, -1 is returned and *errno* | ||
| 128 | * is set appropriately. | ||
| 129 | * | ||
| 130 | * BPF_MAP_UPDATE_ELEM | ||
| 131 | * Description | ||
| 132 | * Create or update an element (key/value pair) in a specified map. | ||
| 133 | * | ||
| 134 | * The *flags* argument should be specified as one of the | ||
| 135 | * following: | ||
| 136 | * | ||
| 137 | * **BPF_ANY** | ||
| 138 | * Create a new element or update an existing element. | ||
| 139 | * **BPF_NOEXIST** | ||
| 140 | * Create a new element only if it did not exist. | ||
| 141 | * **BPF_EXIST** | ||
| 142 | * Update an existing element. | ||
| 143 | * | ||
| 144 | * Return | ||
| 145 | * Returns zero on success. On error, -1 is returned and *errno* | ||
| 146 | * is set appropriately. | ||
| 147 | * | ||
| 148 | * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, | ||
| 149 | * **E2BIG**, **EEXIST**, or **ENOENT**. | ||
| 150 | * | ||
| 151 | * **E2BIG** | ||
| 152 | * The number of elements in the map reached the | ||
| 153 | * *max_entries* limit specified at map creation time. | ||
| 154 | * **EEXIST** | ||
| 155 | * If *flags* specifies **BPF_NOEXIST** and the element | ||
| 156 | * with *key* already exists in the map. | ||
| 157 | * **ENOENT** | ||
| 158 | * If *flags* specifies **BPF_EXIST** and the element with | ||
| 159 | * *key* does not exist in the map. | ||
| 160 | * | ||
| 161 | * BPF_MAP_DELETE_ELEM | ||
| 162 | * Description | ||
| 163 | * Look up and delete an element by key in a specified map. | ||
| 164 | * | ||
| 165 | * Return | ||
| 166 | * Returns zero on success. On error, -1 is returned and *errno* | ||
| 167 | * is set appropriately. | ||
| 168 | * | ||
| 169 | * BPF_MAP_GET_NEXT_KEY | ||
| 170 | * Description | ||
| 171 | * Look up an element by key in a specified map and return the key | ||
| 172 | * of the next element. Can be used to iterate over all elements | ||
| 173 | * in the map. | ||
| 174 | * | ||
| 175 | * Return | ||
| 176 | * Returns zero on success. On error, -1 is returned and *errno* | ||
| 177 | * is set appropriately. | ||
| 178 | * | ||
| 179 | * The following cases can be used to iterate over all elements of | ||
| 180 | * the map: | ||
| 181 | * | ||
| 182 | * * If *key* is not found, the operation returns zero and sets | ||
| 183 | * the *next_key* pointer to the key of the first element. | ||
| 184 | * * If *key* is found, the operation returns zero and sets the | ||
| 185 | * *next_key* pointer to the key of the next element. | ||
| 186 | * * If *key* is the last element, returns -1 and *errno* is set | ||
| 187 | * to **ENOENT**. | ||
| 188 | * | ||
| 189 | * May set *errno* to **ENOMEM**, **EFAULT**, **EPERM**, or | ||
| 190 | * **EINVAL** on error. | ||
| 191 | * | ||
| 192 | * BPF_PROG_LOAD | ||
| 193 | * Description | ||
| 194 | * Verify and load an eBPF program, returning a new file | ||
| 195 | * descriptor associated with the program. | ||
| 196 | * | ||
| 197 | * Applying **close**\ (2) to the file descriptor returned by | ||
| 198 | * **BPF_PROG_LOAD** will unload the eBPF program (but see NOTES). | ||
| 199 | * | ||
| 200 | * The close-on-exec file descriptor flag (see **fcntl**\ (2)) is | ||
| 201 | * automatically enabled for the new file descriptor. | ||
| 202 | * | ||
| 203 | * Return | ||
| 204 | * A new file descriptor (a nonnegative integer), or -1 if an | ||
| 205 | * error occurred (in which case, *errno* is set appropriately). | ||
| 206 | * | ||
| 207 | * NOTES | ||
| 208 | * eBPF objects (maps and programs) can be shared between processes. | ||
| 209 | * For example, after **fork**\ (2), the child inherits file descriptors | ||
| 210 | * referring to the same eBPF objects. In addition, file descriptors | ||
| 211 | * referring to eBPF objects can be transferred over UNIX domain sockets. | ||
| 212 | * File descriptors referring to eBPF objects can be duplicated in the | ||
| 213 | * usual way, using **dup**\ (2) and similar calls. An eBPF object is | ||
| 214 | * deallocated only after all file descriptors referring to the object | ||
| 215 | * have been closed. | ||
| 216 | */ | ||
| 97 | enum bpf_cmd { | 217 | enum bpf_cmd { |
| 98 | BPF_MAP_CREATE, | 218 | BPF_MAP_CREATE, |
| 99 | BPF_MAP_LOOKUP_ELEM, | 219 | BPF_MAP_LOOKUP_ELEM, |