Commit 0cb80454 authored by Joe Stringer's avatar Joe Stringer Committed by Alexei Starovoitov
Browse files

bpf: Document BPF_MAP_*_BATCH syscall commands 



Based roughly on the following commits:
* Commit cb4d03ab ("bpf: Add generic support for lookup batch op")
* Commit 05799638 ("bpf: Add batch ops to all htab bpf map")
* Commit aa2e93b8 ("bpf: Add generic support for update and delete
  batch ops")

Signed-off-by: default avatarJoe Stringer <joe@cilium.io>
Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
Reviewed-by: default avatarQuentin Monnet <quentin@isovalent.com>
Acked-by: default avatarToke Høiland-Jørgensen <toke@redhat.com>
Acked-by: default avatarBrian Vazquez <brianvv@google.com>
Acked-by: default avatarYonghong Song <yhs@fb.com>
Link: https://lore.kernel.org/bpf/20210302171947.2268128-9-joe@cilium.io
parent 5d999994

include/uapi/linux/bpf.h

+111 −3
Original line number Diff line number Diff line
@@ -553,13 +553,55 @@ union bpf_iter_link_info { 
 *	Description

 *		Iterate and fetch multiple elements in a map.

 *

 *		Two opaque values are used to manage batch operations,

 *		*in_batch* and *out_batch*. Initially, *in_batch* must be set

 *		to NULL to begin the batched operation. After each subsequent

 *		**BPF_MAP_LOOKUP_BATCH**, the caller should pass the resultant

 *		*out_batch* as the *in_batch* for the next operation to

 *		continue iteration from the current point.

 *

 *		The *keys* and *values* are output parameters which must point

 *		to memory large enough to hold *count* items based on the key

 *		and value size of the map *map_fd*. The *keys* buffer must be

 *		of *key_size* * *count*. The *values* buffer must be of

 *		*value_size* * *count*.

 *

 *		The *elem_flags* argument may be specified as one of the

 *		following:

 *

 *		**BPF_F_LOCK**

 *			Look up the value of a spin-locked map without

 *			returning the lock. This must be specified if the

 *			elements contain a spinlock.

 *

 *		On success, *count* elements from the map are copied into the

 *		user buffer, with the keys copied into *keys* and the values

 *		copied into the corresponding indices in *values*.

 *

 *		If an error is returned and *errno* is not **EFAULT**, *count*

 *		is set to the number of successfully processed elements.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 *		May set *errno* to **ENOSPC** to indicate that *keys* or

 *		*values* is too small to dump an entire bucket during

 *		iteration of a hash-based map type.

 *

 * BPF_MAP_LOOKUP_AND_DELETE_BATCH

 *	Description

 *		Iterate and delete multiple elements in a map.

 *		Iterate and delete all elements in a map.

 *

 *		This operation has the same behavior as

 *		**BPF_MAP_LOOKUP_BATCH** with two exceptions:

 *

 *		* Every element that is successfully returned is also deleted

 *		  from the map. This is at least *count* elements. Note that

 *		  *count* is both an input and an output parameter.

 *		* Upon returning with *errno* set to **EFAULT**, up to

 *		  *count* elements may be deleted without returning the keys

 *		  and values of the deleted elements.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*
@@ -567,15 +609,81 @@ union bpf_iter_link_info { 
 *

 * BPF_MAP_UPDATE_BATCH

 *	Description

 *		Iterate and update multiple elements in a map.

 *		Update multiple elements in a map by *key*.

 *

 *		The *keys* and *values* are input parameters which must point

 *		to memory large enough to hold *count* items based on the key

 *		and value size of the map *map_fd*. The *keys* buffer must be

 *		of *key_size* * *count*. The *values* buffer must be of

 *		*value_size* * *count*.

 *

 *		Each element specified in *keys* is sequentially updated to the

 *		value in the corresponding index in *values*. The *in_batch*

 *		and *out_batch* parameters are ignored and should be zeroed.

 *

 *		The *elem_flags* argument should be specified as one of the

 *		following:

 *

 *		**BPF_ANY**

 *			Create new elements or update a existing elements.

 *		**BPF_NOEXIST**

 *			Create new elements only if they do not exist.

 *		**BPF_EXIST**

 *			Update existing elements.

 *		**BPF_F_LOCK**

 *			Update spin_lock-ed map elements. This must be

 *			specified if the map value contains a spinlock.

 *

 *		On success, *count* elements from the map are updated.

 *

 *		If an error is returned and *errno* is not **EFAULT**, *count*

 *		is set to the number of successfully processed elements.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*

 *		is set appropriately.

 *

 *		May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**, or

 *		**E2BIG**. **E2BIG** indicates that the number of elements in

 *		the map reached the *max_entries* limit specified at map

 *		creation time.

 *

 *		May set *errno* to one of the following error codes under

 *		specific circumstances:

 *

 *		**EEXIST**

 *			If *flags* specifies **BPF_NOEXIST** and the element

 *			with *key* already exists in the map.

 *		**ENOENT**

 *			If *flags* specifies **BPF_EXIST** and the element with

 *			*key* does not exist in the map.

 *

 * BPF_MAP_DELETE_BATCH

 *	Description

 *		Iterate and delete multiple elements in a map.

 *		Delete multiple elements in a map by *key*.

 *

 *		The *keys* parameter is an input parameter which must point

 *		to memory large enough to hold *count* items based on the key

 *		size of the map *map_fd*, that is, *key_size* * *count*.

 *

 *		Each element specified in *keys* is sequentially deleted. The

 *		*in_batch*, *out_batch*, and *values* parameters are ignored

 *		and should be zeroed.

 *

 *		The *elem_flags* argument may be specified as one of the

 *		following:

 *

 *		**BPF_F_LOCK**

 *			Look up the value of a spin-locked map without

 *			returning the lock. This must be specified if the

 *			elements contain a spinlock.

 *

 *		On success, *count* elements from the map are updated.

 *

 *		If an error is returned and *errno* is not **EFAULT**, *count*

 *		is set to the number of successfully processed elements. If

 *		*errno* is **EFAULT**, up to *count* elements may be been

 *		deleted.

 *

 *	Return

 *		Returns zero on success. On error, -1 is returned and *errno*