Hi Joe, thanks for documenting this.
Your description of the functions usage looks good to me.
Acked-by: Brian Vazquez <brianvv@xxxxxxxxxx>
On Tue, Mar 2, 2021 at 9:20 AM Joe Stringer <joe@xxxxxxxxx> 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@xxxxxxxxxx>
> Reviewed-by: Quentin Monnet <quentin@xxxxxxxxxxxxx>
> Signed-off-by: Joe Stringer <joe@xxxxxxxxx>
> ---
> CC: Brian Vazquez <brianvv@xxxxxxxxxx>
> CC: Yonghong Song <yhs@xxxxxx>
> ---
> 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
>
