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

[grantseltzer <grantseltzer@gmail.com>]

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