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

Yonghong Song <yhs@xxxxxx> · Wed, 5 Jan 2022 20:54:06 -0800

On 1/5/22 6:37 PM, Andrii Nakryiko wrote:
On Sat, Dec 25, 2021 at 12:37 PM grantseltzer <grantseltzer@xxxxxxxxx> wrote:

From: Grant Seltzer <grantseltzer@xxxxxxxxx>

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 <grantseltzer@xxxxxxxxx>
---
  tools/lib/bpf/bpf.c |   4 +-
  tools/lib/bpf/bpf.h | 112 +++++++++++++++++++++++++++++++++++++++++++-
  2 files changed, 112 insertions(+), 4 deletions(-)

diff --git a/tools/lib/bpf/bpf.c b/tools/lib/bpf/bpf.c
index 9b64eed2b003..25f3d6f85fe5 100644
--- a/tools/lib/bpf/bpf.c
+++ b/tools/lib/bpf/bpf.c
@@ -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,
diff --git a/tools/lib/bpf/bpf.h b/tools/lib/bpf/bpf.h
index 00619f64a040..01011747f127 100644
--- a/tools/lib/bpf/bpf.h
+++ b/tools/lib/bpf/bpf.h
@@ -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

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!

Will take a look later today.



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

[...]






