diff mbox series

[PATCHv2,bpf-next,08/15] bpf: Document BPF_MAP_*_BATCH syscall commands

Message ID 20210302171947.2268128-9-joe@cilium.io (mailing list archive)
State Accepted
Delegated to: BPF
Headers show
Series Improve BPF syscall command documentation | expand

Checks

Context Check Description
netdev/cover_letter success Link
netdev/fixes_present success Link
netdev/patch_count success Link
netdev/tree_selection success Clearly marked for bpf-next
netdev/subject_prefix success Link
netdev/cc_maintainers warning 6 maintainers not CCed: netdev@vger.kernel.org john.fastabend@gmail.com kpsingh@kernel.org songliubraving@fb.com kafai@fb.com andrii@kernel.org
netdev/source_inline success Was 0 now: 0
netdev/verify_signedoff success Link
netdev/module_param success Was 0 now: 0
netdev/build_32bit success Errors and warnings before: 11835 this patch: 11835
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/verify_fixes success Link
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 139 lines checked
netdev/build_allmodconfig_warn success Errors and warnings before: 12482 this patch: 12482
netdev/header_inline success Link
netdev/stable success Stable not CCed

Commit Message

Joe Stringer March 2, 2021, 5:19 p.m. UTC
Based roughly on the following commits:
* Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op")
* Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map")
* Commit aa2e93b8e58e ("bpf: Add generic support for update and delete
  batch ops")

Acked-by: Toke Høiland-Jørgensen <toke@redhat.com>
Reviewed-by: Quentin Monnet <quentin@isovalent.com>
Signed-off-by: Joe Stringer <joe@cilium.io>
---
CC: Brian Vazquez <brianvv@google.com>
CC: Yonghong Song <yhs@fb.com>
---
 include/uapi/linux/bpf.h | 114 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 111 insertions(+), 3 deletions(-)

Comments

Brian Vazquez March 3, 2021, 5:38 p.m. UTC | #1
Hi Joe, thanks for documenting this.

Your description of the functions usage looks good to me.

Acked-by: Brian Vazquez <brianvv@google.com>




On Tue, Mar 2, 2021 at 9:20 AM Joe Stringer <joe@cilium.io> wrote:
>
> Based roughly on the following commits:
> * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op")
> * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map")
> * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete
>   batch ops")
>
> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com>
> Reviewed-by: Quentin Monnet <quentin@isovalent.com>
> Signed-off-by: Joe Stringer <joe@cilium.io>
> ---
> CC: Brian Vazquez <brianvv@google.com>
> CC: Yonghong Song <yhs@fb.com>
> ---
>  include/uapi/linux/bpf.h | 114 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 111 insertions(+), 3 deletions(-)
>
> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
> index 0cf92ef011f1..c8b9d19fce22 100644
> --- a/include/uapi/linux/bpf.h
> +++ b/include/uapi/linux/bpf.h
> @@ -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*
> --
> 2.27.0
>
Yonghong Song March 3, 2021, 8:44 p.m. UTC | #2
On 3/2/21 9:19 AM, Joe Stringer wrote:
> Based roughly on the following commits:
> * Commit cb4d03ab499d ("bpf: Add generic support for lookup batch op")
> * Commit 057996380a42 ("bpf: Add batch ops to all htab bpf map")
> * Commit aa2e93b8e58e ("bpf: Add generic support for update and delete
>    batch ops")
> 
> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com>
> Reviewed-by: Quentin Monnet <quentin@isovalent.com>
> Signed-off-by: Joe Stringer <joe@cilium.io>
> ---
> CC: Brian Vazquez <brianvv@google.com>
> CC: Yonghong Song <yhs@fb.com>
> ---

Acked-by: Yonghong Song <yhs@fb.com>
diff mbox series

Patch

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 0cf92ef011f1..c8b9d19fce22 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -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*