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

Commit Message

Grant Seltzer Richman Dec. 20, 2021, 5:40 a.m. UTC

From: Grant Seltzer <[e-mail]>

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 <[e-mail]>
---
 tools/lib/bpf/bpf.h | 93 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)

Comments

Yonghong Song Dec. 21, 2021, 4:54 a.m. UTC | #1

On 12/19/21 9:40 PM, grantseltzer wrote:
> From: Grant Seltzer <[e-mail]>
> 
> 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 <[e-mail]>
> ---
>   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);
>

Andrii Nakryiko Dec. 22, 2021, 12:06 a.m. UTC | #2

On Sun, Dec 19, 2021 at 9:42 PM grantseltzer <[e-mail]> wrote:
>
> From: Grant Seltzer <[e-mail]>
>
> This adds documention for:

typo: documentation :)

>
> - bpf_map_delete_batch()
> - bpf_map_lookup_batch()
> - bpf_map_lookup_and_delete_batch()
> - bpf_map_update_batch()
>
> Signed-off-by: Grant Seltzer <[e-mail]>
> ---
>  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

"memory address large enough" is very misleading... "points to buffer
large enough"?

But in this case, keys is just an input array of keys, no? In such a
case just saying that "*keys* points to an array of *count* keys"
would be pretty unambiguous, right?

> + * *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)

Usually success is described first. Can you please rephrase here and
in others to something along the lines of:

0, on success; negative error code, otherwise (errno is also set to
the error code)

?

> + */
>  LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,

if keys are really just an input, let's mark them as `const void *`,
while we are documenting all this?

>                                     __u32 *count,
>                                     const struct bpf_map_batch_opts *opts);
> +
> +/**
> + * @brief **bpf_map_lookup_batch()** allows for iteration of BPF map elements.
> + *
> + * 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.
> + *
> + * 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*
> + * @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*

again this "memory address large enough" wording. Address is fixed at
32-bit/64-bit, depending on the architecture. It's quite a confusing
wording that you chose...

> + * @param count number of elements in the map to read in batch
> + * @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.
> + *
> + * Note that *count* is an input and output parameter, where on output it
> + * represents how many elements were succesfully deleted. Also note that if
> + * **EFAULT** is returned up to *count* elements may have been deleted without
> + * being returned via the *keys* and *values* output parameters.
> + *
> + * @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.
> + *
> + * The *keys* and *values* paremeters must point to memory large enough
> + * 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.

just "update existing"

> + *
> + * **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
> + * @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,

I think keys are also `const void *`, while values are written into.
Let's update accordingly.

>                                     __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);
>
> --
> 2.33.1
>

Grant Seltzer Richman Dec. 25, 2021, 8:32 p.m. UTC | #3

On Tue, Dec 21, 2021 at 7:06 PM Andrii Nakryiko
<[e-mail]> wrote:
>
> On Sun, Dec 19, 2021 at 9:42 PM grantseltzer <[e-mail]> wrote:
> >
> > From: Grant Seltzer <[e-mail]>
> >
> > This adds documention for:
>
> typo: documentation :)
>
> >
> > - bpf_map_delete_batch()
> > - bpf_map_lookup_batch()
> > - bpf_map_lookup_and_delete_batch()
> > - bpf_map_update_batch()
> >
> > Signed-off-by: Grant Seltzer <[e-mail]>
> > ---
> >  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
>
> "memory address large enough" is very misleading... "points to buffer
> large enough"?
>
> But in this case, keys is just an input array of keys, no? In such a
> case just saying that "*keys* points to an array of *count* keys"
> would be pretty unambiguous, right?
>
> > + * *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)
>
> Usually success is described first. Can you please rephrase here and
> in others to something along the lines of:
>
> 0, on success; negative error code, otherwise (errno is also set to
> the error code)
>
> ?
>
> > + */
> >  LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,
>
> if keys are really just an input, let's mark them as `const void *`,
> while we are documenting all this?
>
> >                                     __u32 *count,
> >                                     const struct bpf_map_batch_opts *opts);
> > +
> > +/**
> > + * @brief **bpf_map_lookup_batch()** allows for iteration of BPF map elements.
> > + *
> > + * 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.
> > + *
> > + * 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*
> > + * @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*
>
> again this "memory address large enough" wording. Address is fixed at
> 32-bit/64-bit, depending on the architecture. It's quite a confusing
> wording that you chose...
>
> > + * @param count number of elements in the map to read in batch
> > + * @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.
> > + *
> > + * Note that *count* is an input and output parameter, where on output it
> > + * represents how many elements were succesfully deleted. Also note that if
> > + * **EFAULT** is returned up to *count* elements may have been deleted without
> > + * being returned via the *keys* and *values* output parameters.
> > + *
> > + * @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.
> > + *
> > + * The *keys* and *values* paremeters must point to memory large enough
> > + * 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.
>
> just "update existing"
>
> > + *
> > + * **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
> > + * @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,
>
> I think keys are also `const void *`, while values are written into.
> Let's update accordingly.

I don't think values are written into, going to mark that as `const
void *` as well.

>
> >                                     __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);
> >
> > --
> > 2.33.1
> >

Patch

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.
+ *
+ * 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.
+ *
+ * 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*
+ * @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
+ * @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.
+ *
+ * Note that *count* is an input and output parameter, where on output it
+ * represents how many elements were succesfully deleted. Also note that if
+ * **EFAULT** is returned up to *count* elements may have been deleted without
+ * being returned via the *keys* and *values* output parameters.
+ *
+ * @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.
+ *
+ * The *keys* and *values* paremeters must point to memory large enough
+ * 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
+ * @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);