Re: [PATCH bpf-next] libbpf: Add documentation for bpf_map batch operations

[Yonghong Song <yhs@fb.com>]

On 12/19/21 9:40 PM, grantseltzer wrote:
> From: Grant Seltzer <grantseltzer@gmail.com>
> 
> This adds documention for:
> 
> - bpf_map_delete_batch()
> - bpf_map_lookup_batch()
> - bpf_map_lookup_and_delete_batch()
> - bpf_map_update_batch()
> 
> Signed-off-by: Grant Seltzer <grantseltzer@gmail.com>
> ---
>   tools/lib/bpf/bpf.h | 93 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 93 insertions(+)
> 
> diff --git a/tools/lib/bpf/bpf.h b/tools/lib/bpf/bpf.h
> index 00619f64a040..b1a2ac9ca9c7 100644
> --- a/tools/lib/bpf/bpf.h
> +++ b/tools/lib/bpf/bpf.h
> @@ -254,20 +254,113 @@ struct bpf_map_batch_opts {
>   };
>   #define bpf_map_batch_opts__last_field flags
>   
> +
> +/**
> + * @brief **bpf_map_delete_batch()** allows for batch deletion of multiple
> + * elements in a BPF map.
> + *
> + * The parameter *keys* points to a memory address large enough to hold
> + * *count* keys of elements in the map *fd*.
> + *
> + * @param fd BPF map file descriptor
> + * @param keys memory address large enough to hold *count* * *key_size*
> + * @param count number of elements in the map to sequentially delete
> + * @param opts options for configuring the way the batch deletion works
> + * @return  int error code, 0 if no error (errno is also set to error)
> + */
>   LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,
>   				    __u32 *count,
>   				    const struct bpf_map_batch_opts *opts);
> +
> +/**
> + * @brief **bpf_map_lookup_batch()** allows for iteration of BPF map elements.

"for iteration" => "for batch lookup"

> + *
> + * The parameter *in_batch* is the address of the first element in the batch to read.
> + * *out_batch* is an output parameter that should be passed as *in_batch* to subsequent
> + * calls to **bpf_map_lookup_batch()**. NULL can be passed for *in_batch* to set
> + * *out_batch* as the first element of the map.

NULL can be passed for *in_batch* to indicate that the batched lookup 
starts from the beginning of the map.

> + *
> + * 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*.
> + *
> + * @param fd BPF map file descriptor
> + * @param in_batch address of the first element in batch to read, can pass NULL to
> + * get address of the first element in *out_batch*

can pass NULL to indicate that the batched lookup starts from the 
beginning of the map.

> + * @param out_batch output parameter that should be passed to next call as *in_batch*
> + * @param keys memory address large enough to hold *count* * *key_size*
> + * @param values memory address large enough to hold *count* * *value_size*
> + * @param count number of elements in the map to read in batch

count is an input/output parameter. It may return the actual number of 
lookup elements if it returns 0 or return ENOENT. Please take a look at
selftest map_tests/htab_map_batch_ops.c for a usage of the function.

> + * @param opts options for configuring the way the batch lookup works
> + * @return int error code, 0 if no error (errno is also set to error)
> + */
>   LIBBPF_API int bpf_map_lookup_batch(int fd, void *in_batch, void *out_batch,
>   				    void *keys, void *values, __u32 *count,
>   				    const struct bpf_map_batch_opts *opts);
> +
> +/**
> + * @brief **bpf_map_lookup_and_delete_batch()** allows for iteration of BPF map
> + * elements where each element is deleted after being retrieved.

"for iteration" => "for batch lookup and delete"?

> + *
> + * Note that *count* is an input and output parameter, where on output it
> + * represents how many elements were succesfully deleted. Also note that if

successfully

> + * **EFAULT** is returned up to *count* elements may have been deleted without
> + * being returned via the *keys* and *values* output parameters.

Okay, I see you mention *count* as input/output here. Again ENOENT might 
need to be handled specially.

> + *
> + * @param fd BPF map file descriptor
> + * @param in_batch address of the first element in batch to read, can pass NULL to
> + * get address of the first element in *out_batch*
> + * @param out_batch output parameter that should be passed to next call as *in_batch*
> + * @param keys memory address large enough to hold *count* * *key_size*
> + * @param values memory address large enough to hold *count* * *value_size*
> + * @param count number of elements in the map to read and delete in batch
> + * @param opts options for configuring the way the batch lookup and delete works
> + * @return int error code, 0 if no error (errno is also set to error)
> + * See note on EFAULT.
> + */
>   LIBBPF_API int bpf_map_lookup_and_delete_batch(int fd, void *in_batch,
>   					void *out_batch, void *keys,
>   					void *values, __u32 *count,
>   					const struct bpf_map_batch_opts *opts);
> +
> +/**
> + * @brief **bpf_map_update_batch()** updates multiple elements in a map
> + * by specifiying keys and their corresponding values.

specifying

> + *
> + * The *keys* and *values* paremeters must point to memory large enough

parameters

> + * to hold *count* items based on the key and value size of the map.
> + *
> + * The *opts* parameter can be used to control how *bpf_map_update_batch()*
> + * should handle keys that either do or do not already exist in the map.
> + * In particular the *flags* field of *bpf_map_batch_opts* can be
> + * 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.
> + *
> + * @param fd BPF map file descriptor
> + * @param keys memory address large enough to hold *count* * *key_size*
> + * @param values memory address large enough to hold *count* * *value_size*
> + * @param count number of elements in the map to update in batch

Again, count is an input/output parameter. Here ENOENT is not involved.
As you mentioned in the above, if error code is EFAULT, return count 
value cannot be trusted. Otherwise, it should tell how many have been
successfully updated.

> + * @param opts options for configuring the way the batch update works
> + * @return int error code, 0 if no error (errno is also set to error)
> + */
>   LIBBPF_API int bpf_map_update_batch(int fd, void *keys, void *values,
>   				    __u32 *count,
>   				    const struct bpf_map_batch_opts *opts);
>   
> +
>   LIBBPF_API int bpf_obj_pin(int fd, const char *pathname);
>   LIBBPF_API int bpf_obj_get(const char *pathname);
>