linux-kernel - [PATCH] libbpf: Added the description of some API functions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20221224112058.12038-1-liuxin350@huawei.com>
Date:   Sat, 24 Dec 2022 19:20:58 +0800
From:   Xin Liu <liuxin350@...wei.com>
To:     <andrii@...nel.org>, <ast@...nel.org>, <daniel@...earbox.net>,
        <martin.lau@...ux.dev>, <song@...nel.org>, <yhs@...com>,
        <john.fastabend@...il.com>, <kpsingh@...nel.org>, <sdf@...gle.com>,
        <haoluo@...gle.com>, <jolsa@...nel.org>
CC:     <bpf@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
        <yanan@...wei.com>, <wuchangye@...wei.com>,
        <xiesongyang@...wei.com>, <kongweibin2@...wei.com>,
        <liuxin350@...wei.com>, <zhangmingyi5@...wei.com>
Subject: [PATCH] libbpf: Added the description of some API functions

Currently, many API functions are not described in the document.
I have tried to add the API description of the following four API
functions:
 libbpf_set_print
 bpf_object__open
 bpf_object__load
 bpf_object__close

Signed-off-by: Xin Liu <liuxin350@...wei.com>
---
 tools/lib/bpf/libbpf.h | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h
index eee883f007f9..bf3af52d42be 100644
--- a/tools/lib/bpf/libbpf.h
+++ b/tools/lib/bpf/libbpf.h
@@ -96,6 +96,12 @@ enum libbpf_print_level {
 typedef int (*libbpf_print_fn_t)(enum libbpf_print_level level,
 				 const char *, va_list ap);
 
+/**
+ * @brief **libbpf_set_print()** use the user-provided log print function.
+ * @param fn the log print function. Disable all print if the parameter
+ * is NULL.
+ * @return Pointer to old print function.
+ */
 LIBBPF_API libbpf_print_fn_t libbpf_set_print(libbpf_print_fn_t fn);
 
 /* Hide internal to user */
@@ -174,6 +180,14 @@ struct bpf_object_open_opts {
 };
 #define bpf_object_open_opts__last_field kernel_log_level
 
+/**
+ * @brief **bpf_object__open()** creates a bpf_object by opening
+ * the BPF ELF object file pointed to by the passed path and loading it
+ * into memory.
+ * @param path BPF object file path.
+ * @return pointer to the new bpf_object; or NULL is returned on error,
+ * error code is stored in errno
+ */
 LIBBPF_API struct bpf_object *bpf_object__open(const char *path);
 
 /**
@@ -204,9 +218,20 @@ bpf_object__open_mem(const void *obj_buf, size_t obj_buf_sz,
 		     const struct bpf_object_open_opts *opts);
 
 /* Load/unload object into/from kernel */
+/**
+ * @brief **bpf_object__load()** load bpf_object into kernel
+ * @param obj pointer to a valid bpf_object
+ * @return 0, on success; negative error code, otherwise, error code is
+ * stored in errno
+ */
 LIBBPF_API int bpf_object__load(struct bpf_object *obj);
 
-LIBBPF_API void bpf_object__close(struct bpf_object *object);
+/**
+ * @brief **bpf_object__close()** close a bpf_object and release all
+ * resources.
+ * @param obj pointer to a valid bpf_object
+ */
+LIBBPF_API void bpf_object__close(struct bpf_object *obj);
 
 /* pin_maps and unpin_maps can both be called with a NULL path, in which case
  * they will use the pin_path attribute of each map (and ignore all maps that
-- 
2.33.0