libbpf: Add documentation for bpf_map batch operations

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
 tools/lib/bpf/bpf.c |   4 +-
 tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +0 -0

index 9b64eed2b003..25f3d6f85fe5 100644

tools/lib/bpf/bpf.c +1 -1

 			 const struct bpf_map_batch_opts *opts)
 {
 	return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
 				    count, opts);
 }
 
-int bpf_map_update_batch(int fd, void *keys, void *values, __u32 *count,
+int bpf_map_update_batch(int fd, const void *keys, const void *values, __u32 *count,
 			 const struct bpf_map_batch_opts *opts)
 {
 	return bpf_map_batch_common(BPF_MAP_UPDATE_BATCH, fd, NULL, NULL,

tools/lib/bpf/bpf.h +110 -2

index 00619f64a040..01011747f127 100644
@@ -254,20 +254,128 @@ struct bpf_map_batch_opts {
 };
 #define bpf_map_batch_opts__last_field flags
 
-LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,
+
+/**
+ * @brief **bpf_map_delete_batch()** allows for batch deletion of multiple
+ * elements in a BPF map.
+ *
+ * @param fd BPF map file descriptor
+ * @param keys pointer to an array of *count* keys
+ * @param count number of elements in the map to sequentially delete
+ * @param opts options for configuring the way the batch deletion works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_delete_batch(int fd, const void *keys,
 				    __u32 *count,
 				    const struct bpf_map_batch_opts *opts);
+
+/**
+ * @brief **bpf_map_lookup_batch()** allows for batch lookup 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 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
+ * 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 pointer to an array large enough for *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count number of elements in the map to read in batch. If ENOENT is
+ * returned, count will be set as the number of elements that were read before
+ * running out of entries in the map
+ * @param opts options for configuring the way the batch lookup works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 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 batch lookup and deletion
+ * 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 successfully 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. If **ENOENT**
+ * is returned then *count* will be set to the number of elements that were read
+ * before running out of entries in the map.
+ *
+ * @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 pointer to an array of *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to read and delete in batch; on output it represents number of elements
+ * that were successfully read and deleted
+ * If ENOENT is returned, count will be set as the number of elements that were
+ * read before running out of entries in the map
+ * @param opts options for configuring the way the batch lookup and delete works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 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);
-LIBBPF_API int bpf_map_update_batch(int fd, void *keys, void *values,
+
+/**
+ * @brief **bpf_map_update_batch()** updates multiple elements in a map
+ * by specifying keys and their corresponding values.
+ *
+ * The *keys* and *values* parameters 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* parameter of *bpf_map_batch_opts* can be
+ * one of the following:
+ *
+ * Note that *count* is an input and output parameter, where on output it
+ * represents how many elements were successfully updated. Also note that if
+ * **EFAULT** then *count* should not be trusted to be correct.
+ *
+ * **BPF_ANY**
+ *     Create new elements or 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 pointer to an array of *count* keys
+ * @param values pointer to an array of *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to update in batch; on output it represents the number of elements
+ * that were successfully updated. If EFAULT is returned, *count* should not
+ * be trusted to be correct.
+ * @param opts options for configuring the way the batch update works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_update_batch(int fd, const void *keys, const 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);
 

Quoted 23 lines · grantseltzer

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
 tools/lib/bpf/bpf.c |   4 +-
 tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +0 -0

index 9b64eed2b003..25f3d6f85fe5 100644
@@ -691,7 +691,7 @@ static int bpf_map_batch_common(int cmd, int fd, void  *in_batch,
      return libbpf_err_errno(ret);
 }
 

tools/lib/bpf/bpf.c static int bpf_map_batch_common(int cmd, int fd, void *in_batch, · line 694

Quoted 2 lines

tools/lib/bpf/bpf.c +1 -1

-int bpf_map_delete_batch(int fd, void *keys, __u32 *count,
+int bpf_map_delete_batch(int fd, const void *keys, __u32 *count,

Maybe you should drop these const qualifier changes.

All batch operations use bpf_map_batch_common, which has the following signature:

static int bpf_map_batch_common(int cmd, int fd, void *in_batch,
void *out_batch, void *keys, void *values, __u32 *count,
const struct bpf_map_batch_opts *opts)

Adding these const qualifiers causes the following error:

bpf.c:698:15: error: passing argument 5 of ‘bpf_map_batch_common’ discards ‘const’ qualifier from pointer target type [-Werror=discarded-qualifiers]

Quoted 147 lines

tools/lib/bpf/bpf.c +1 -1

                       const struct bpf_map_batch_opts *opts)
 {
      return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
                                  count, opts);
 }
 
-int bpf_map_update_batch(int fd, void *keys, void *values, __u32 *count,
+int bpf_map_update_batch(int fd, const void *keys, const void *values, __u32 *count,
                       const struct bpf_map_batch_opts *opts)
 {
      return bpf_map_batch_common(BPF_MAP_UPDATE_BATCH, fd, NULL, NULL,

tools/lib/bpf/bpf.h +110 -2

index 00619f64a040..01011747f127 100644
@@ -254,20 +254,128 @@ struct bpf_map_batch_opts {
 };
 #define bpf_map_batch_opts__last_field flags
 
-LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,
+
+/**
+ * @brief **bpf_map_delete_batch()** allows for batch deletion of multiple
+ * elements in a BPF map.
+ *
+ * @param fd BPF map file descriptor
+ * @param keys pointer to an array of *count* keys
+ * @param count number of elements in the map to sequentially delete
+ * @param opts options for configuring the way the batch deletion works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_delete_batch(int fd, const void *keys,
                                  __u32 *count,
                                  const struct bpf_map_batch_opts *opts);
+
+/**
+ * @brief **bpf_map_lookup_batch()** allows for batch lookup 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 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
+ * 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 pointer to an array large enough for *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count number of elements in the map to read in batch. If ENOENT is
+ * returned, count will be set as the number of elements that were read before
+ * running out of entries in the map
+ * @param opts options for configuring the way the batch lookup works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 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 batch lookup and deletion
+ * 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 successfully 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. If **ENOENT**
+ * is returned then *count* will be set to the number of elements that were read
+ * before running out of entries in the map.
+ *
+ * @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 pointer to an array of *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to read and delete in batch; on output it represents number of elements
+ * that were successfully read and deleted
+ * If ENOENT is returned, count will be set as the number of elements that were
+ * read before running out of entries in the map
+ * @param opts options for configuring the way the batch lookup and delete works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 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);
-LIBBPF_API int bpf_map_update_batch(int fd, void *keys, void *values,
+
+/**
+ * @brief **bpf_map_update_batch()** updates multiple elements in a map
+ * by specifying keys and their corresponding values.
+ *
+ * The *keys* and *values* parameters 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* parameter of *bpf_map_batch_opts* can be
+ * one of the following:
+ *
+ * Note that *count* is an input and output parameter, where on output it
+ * represents how many elements were successfully updated. Also note that if
+ * **EFAULT** then *count* should not be trusted to be correct.
+ *
+ * **BPF_ANY**
+ *     Create new elements or 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 pointer to an array of *count* keys
+ * @param values pointer to an array of *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to update in batch; on output it represents the number of elements
+ * that were successfully updated. If EFAULT is returned, *count* should not
+ * be trusted to be correct.
+ * @param opts options for configuring the way the batch update works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_update_batch(int fd, const void *keys, const 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);
 

Quoted 27 lines · Hengqi Chen

Quoted 23 lines · grantseltzer

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
 tools/lib/bpf/bpf.c |   4 +-
 tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +0 -0

index 9b64eed2b003..25f3d6f85fe5 100644
@@ -691,7 +691,7 @@ static int bpf_map_batch_common(int cmd, int fd, void  *in_batch,
      return libbpf_err_errno(ret);
 }
 

Quoted 4 lines

tools/lib/bpf/bpf.c static int bpf_map_batch_common(int cmd, int fd, void *in_batch, · line 694

Quoted 2 lines

tools/lib/bpf/bpf.c +1 -1

-int bpf_map_delete_batch(int fd, void *keys, __u32 *count,
+int bpf_map_delete_batch(int fd, const void *keys, __u32 *count,

Maybe you should drop these const qualifier changes.

Can you help me understand the benefit of using the const qualifier in this context? I added it at Andrii's suggestion without proper understanding. I understand that it will properly convey that the keys or values aren't output parameters like in other batch operation functions, I don't think it would change where the underlying data is stored, just the pointer variable.

Is it worth it to have seperate 'common' functions for the sake of having a const qualifier?

Quoted 12 lines

All batch operations use bpf_map_batch_common, which has the following signature:

static int bpf_map_batch_common(int cmd, int fd, void *in_batch,
void *out_batch, void *keys, void *values, __u32 *count,
const struct bpf_map_batch_opts *opts)

Adding these const qualifiers causes the following error:

bpf.c:698:15: error: passing argument 5 of ‘bpf_map_batch_common’ discards ‘const’ qualifier from pointer target type [-Werror=discarded-qualifiers]

Quoted 8 lines

Quoted 8 lines

tools/lib/bpf/bpf.c +0 -0

                       const struct bpf_map_batch_opts *opts)
 {
      return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
                                  count, opts);
 }
 

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
 tools/lib/bpf/bpf.c |   4 +-
 tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +2 -2

index 9b64eed2b003..25f3d6f85fe5 100644
@@ -691,7 +691,7 @@ static int bpf_map_batch_common(int cmd, int fd, void  *in_batch,
        return libbpf_err_errno(ret);
 }
 
-int bpf_map_delete_batch(int fd, void *keys, __u32 *count,
+int bpf_map_delete_batch(int fd, const void *keys, __u32 *count,
                         const struct bpf_map_batch_opts *opts)
 {
        return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
                                    count, opts);
 }
 
-int bpf_map_update_batch(int fd, void *keys, void *values, __u32 *count,
+int bpf_map_update_batch(int fd, const void *keys, const void *values, __u32 *count,
                         const struct bpf_map_batch_opts *opts)
 {
        return bpf_map_batch_common(BPF_MAP_UPDATE_BATCH, fd, NULL, NULL,

tools/lib/bpf/bpf.h +0 -0

index 00619f64a040..01011747f127 100644
@@ -254,20 +254,128 @@ struct bpf_map_batch_opts {
 };
 #define bpf_map_batch_opts__last_field flags

tools/lib/bpf/bpf.h +5 -0

+ * @param opts options for configuring the way the batch deletion works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_delete_batch(int fd, const void *keys,
                                    __u32 *count,
                                    const struct bpf_map_batch_opts *opts);

Quoted 45 lines · grantseltzer

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
  tools/lib/bpf/bpf.c |   4 +-
  tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
  2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +2 -2

index 9b64eed2b003..25f3d6f85fe5 100644
@@ -691,7 +691,7 @@ static int bpf_map_batch_common(int cmd, int fd, void  *in_batch,
         return libbpf_err_errno(ret);
  }
 
-int bpf_map_delete_batch(int fd, void *keys, __u32 *count,
+int bpf_map_delete_batch(int fd, const void *keys, __u32 *count,
                          const struct bpf_map_batch_opts *opts)
  {
         return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
                                     count, opts);
  }
 
-int bpf_map_update_batch(int fd, void *keys, void *values, __u32 *count,
+int bpf_map_update_batch(int fd, const void *keys, const void *values, __u32 *count,
                          const struct bpf_map_batch_opts *opts)
  {
         return bpf_map_batch_common(BPF_MAP_UPDATE_BATCH, fd, NULL, NULL,

tools/lib/bpf/bpf.h +0 -0

index 00619f64a040..01011747f127 100644
@@ -254,20 +254,128 @@ struct bpf_map_batch_opts {
  };
  #define bpf_map_batch_opts__last_field flags

tools/lib/bpf/bpf.h struct bpf_map_batch_opts { · line 264

Quoted 10 lines

tools/lib/bpf/bpf.h +8 -1

 
-LIBBPF_API int bpf_map_delete_batch(int fd, void *keys,
+
+/**
+ * @brief **bpf_map_delete_batch()** allows for batch deletion of multiple
+ * elements in a BPF map.
+ *
+ * @param fd BPF map file descriptor
+ * @param keys pointer to an array of *count* keys
+ * @param count number of elements in the map to sequentially delete

it's important to mention that count is updated after bpf_map_delete_batch() returns with the actual number of elements that were deleted. Please double-check the other APIs as well whether there are important points to mention. These batch APIs are one of the trickiest ones in bpf() syscall, let's do a thorough job documenting them so that users don't have to read kernel code each time they want to use it

But other than that, great job! I've CC'ed Yonghong to take another look, as he should know the semantics of batch APIs much better. Yonghong, please take a look when you can. Thanks!

Quoted 9 lines

tools/lib/bpf/bpf.h +5 -0

+ * @param opts options for configuring the way the batch deletion works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_delete_batch(int fd, const void *keys,
                                     __u32 *count,
                                     const struct bpf_map_batch_opts *opts);

[...]

From: Grant Seltzer <[email protected]>

This adds documentation for:

- bpf_map_delete_batch()
- bpf_map_lookup_batch()
- bpf_map_lookup_and_delete_batch()
- bpf_map_update_batch()

Signed-off-by Grant Seltzer <[email protected]>

---
  tools/lib/bpf/bpf.c |   4 +-
  tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
  2 files changed, 112 insertions(+), 4 deletions(-)

tools/lib/bpf/bpf.c +2 -2

index 9b64eed2b003..25f3d6f85fe5 100644
@@ -691,7 +691,7 @@ static int bpf_map_batch_common(int cmd, int fd, void  *in_batch,
  	return libbpf_err_errno(ret);
  }
 
-int bpf_map_delete_batch(int fd, void *keys, __u32 *count,
+int bpf_map_delete_batch(int fd, const void *keys, __u32 *count,
  			 const struct bpf_map_batch_opts *opts)
  {
  	return bpf_map_batch_common(BPF_MAP_DELETE_BATCH, fd, NULL,

@@ -715,7 +715,7 @@ int bpf_map_lookup_and_delete_batch(int fd, void *in_batch, void *out_batch,
  				    count, opts);
  }
 
-int bpf_map_update_batch(int fd, void *keys, void *values, __u32 *count,
+int bpf_map_update_batch(int fd, const void *keys, const void *values, __u32 *count,
  			 const struct bpf_map_batch_opts *opts)
  {
  	return bpf_map_batch_common(BPF_MAP_UPDATE_BATCH, fd, NULL, NULL,

tools/lib/bpf/bpf.h +0 -0

index 00619f64a040..01011747f127 100644
@@ -254,20 +254,128 @@ struct bpf_map_batch_opts {
  };
  #define bpf_map_batch_opts__last_field flags

tools/lib/bpf/bpf.h +32 -0

+ * @param opts options for configuring the way the batch deletion works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_delete_batch(int fd, const void *keys,
  				    __u32 *count,
  				    const struct bpf_map_batch_opts *opts);
+
+/**
+ * @brief **bpf_map_lookup_batch()** allows for batch lookup 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 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
+ * 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 pointer to an array large enough for *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count number of elements in the map to read in batch. If ENOENT is
+ * returned, count will be set as the number of elements that were read before
+ * running out of entries in the map
+ * @param opts options for configuring the way the batch lookup works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
  LIBBPF_API int bpf_map_lookup_batch(int fd, void *in_batch, void *out_batch,

tools/lib/bpf/bpf.h +25 -1

+ * being returned via the *keys* and *values* output parameters. If **ENOENT**
+ * is returned then *count* will be set to the number of elements that were read
+ * before running out of entries in the map.
+ *
+ * @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 pointer to an array of *count* keys
+ * @param values pointer to an array large enough for *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to read and delete in batch; on output it represents number of elements
+ * that were successfully read and deleted
+ * If ENOENT is returned, count will be set as the number of elements that were
+ * read before running out of entries in the map
+ * @param opts options for configuring the way the batch lookup and delete works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
  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);
-LIBBPF_API int bpf_map_update_batch(int fd, void *keys, void *values,
+
+/**
+ * @brief **bpf_map_update_batch()** updates multiple elements in a map
+ * by specifying keys and their corresponding values.
+ *
+ * The *keys* and *values* parameters must point to memory large enough

tools/lib/bpf/bpf.h +27 -0

+ *
+ * **BPF_ANY**
+ *     Create new elements or 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 pointer to an array of *count* keys
+ * @param values pointer to an array of *count* values
+ * @param count input and output parameter; on input it's the number of elements
+ * in the map to update in batch; on output it represents the number of elements
+ * that were successfully updated. If EFAULT is returned, *count* should not
+ * be trusted to be correct.
+ * @param opts options for configuring the way the batch update works
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
+LIBBPF_API int bpf_map_update_batch(int fd, const void *keys, const 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);