libbpf: Add doc comments in libbpf.h
PATCH v2 1/1 libbpf: Add doc comments in libbpf.h
From: Grant Seltzer <[email protected]>
This adds comments above functions in libbpf.h which document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.org
These doc comments are for:
- bpf_object__open_file()
- bpf_object__open_mem()
- bpf_program__attach_uprobe()
- bpf_program__attach_uprobe_opts()
--- tools/lib/bpf/libbpf.h | 52 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)
tools/lib/bpf/libbpf.h +52 -0
@@ -108,8 +108,30 @@ struct bpf_object_open_opts {#define bpf_object_open_opts__last_field btf_custom_path LIBBPF_API struct bpf_object *bpf_object__open(const char *path); + +/** +* @brief **bpf_object__open_file()** 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 +* @param opts options for how to load the bpf object, this parameter is +* option and can be set to NULL +* @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_file (const char *path,const struct bpf_object_open_opts *opts); + +/** +* @brief **bpf_object__open_mem()** creates a bpf_object by reading +* the BPF objects raw bytes from a memory buffer containing a valid +* BPF ELF object file. +* @param obj_buf pointer to the buffer containing ELF file bytes +* @param obj_buf_sz number of bytes in the buffer +* @param opts options for how to load the bpf object +* @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_mem (const void *obj_buf,size_t obj_buf_sz,const struct bpf_object_open_opts *opts);
@@ -344,10 +366,40 @@ struct bpf_uprobe_opts { };#define bpf_uprobe_opts__last_field retprobe +/** +* @brief **bpf_program__attach_uprobe()** attaches a BPF program +* to the userspace function which is found by binary path and +* offset. You can optionally specify a particular proccess to attach +* to. You can also optionally attach the program to the function +* exit instead of entry. +* +* @param prog BPF program to attach +* @param retprobe Attach to function exit +* @param pid Process ID to attach the uprobe to, -1 for all processes +* @param binary_path Path to binary that contains the function symbol +* @param func_offset Offset within the binary of the function symbol +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +*/ LIBBPF_API struct bpf_link *bpf_program__attach_uprobe (const struct bpf_program *prog,bool retprobe,pid_t pid,const char *binary_path,size_t func_offset); + +/** +* @brief **bpf_program__attach_uprobe_opts()** is just like +* bpf_program__attach_uprobe() except with a options struct +* for various configurations. +* +* @param prog BPF program to attach +* @param pid Process ID to attach the uprobe to, 0 for self (own process), +* -1 for all processes +* @param binary_path Path to binary that contains the function symbol +* @param func_offset Offset within the binary of the function symbol +* @param opts Options for altering program attachment +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +*/ LIBBPF_API struct bpf_link * bpf_program__attach_uprobe_opts(const struct bpf_program *prog, pid_t pid, const char *binary_path, size_t func_offset,
Signature · 1 line
2.33.1
Quoted 9 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds comments above functions in
libbpf.hwhich document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.orgThese doc comments are for:
Quoted 7 lines
-
bpf_object__open_file()
-bpf_object__open_mem()
-bpf_program__attach_uprobe()
-bpf_program__attach_uprobe_opts()Signed-off-by Grant Seltzer <[email protected]>---
Fixed trailing whitespaces, added missing mention of 0 being self for one of uprobe attach APIs, and applied to bpf-next. Thanks.
Quoted 82 lines
tools/lib/bpf/libbpf.h | 52 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)tools/lib/bpf/libbpf.h +52
-1@@ -108,8 +108,30 @@ struct bpf_object_open_opts {#define bpf_object_open_opts__last_field btf_custom_path LIBBPF_API struct bpf_object *bpf_object__open(const char *path); + +/** +* @brief **bpf_object__open_file()** 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 +* @param opts options for how to load the bpf object, this parameter is +* option and can be set to NULL +* @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_file (const char *path,const struct bpf_object_open_opts *opts); + +/** +* @brief **bpf_object__open_mem()** creates a bpf_object by reading +* the BPF objects raw bytes from a memory buffer containing a valid +* BPF ELF object file. +* @param obj_buf pointer to the buffer containing ELF file bytes +* @param obj_buf_sz number of bytes in the buffer +* @param opts options for how to load the bpf object +* @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_mem (const void *obj_buf,size_t obj_buf_sz,const struct bpf_object_open_opts *opts);@@ -344,10 +366,40 @@ struct bpf_uprobe_opts { };#define bpf_uprobe_opts__last_field retprobe +/** +* @brief **bpf_program__attach_uprobe()** attaches a BPF program +* to the userspace function which is found by binary path and +* offset. You can optionally specify a particular proccess to attach +* to. You can also optionally attach the program to the function +* exit instead of entry. +* +* @param prog BPF program to attach +* @param retprobe Attach to function exit +* @param pid Process ID to attach the uprobe to, -1 for all processes +* @param binary_path Path to binary that contains the function symbol +* @param func_offset Offset within the binary of the function symbol +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +*/ LIBBPF_API struct bpf_link *bpf_program__attach_uprobe (const struct bpf_program *prog,bool retprobe,pid_t pid,const char *binary_path,size_t func_offset); + +/** +* @brief **bpf_program__attach_uprobe_opts()** is just like +* bpf_program__attach_uprobe() except with a options struct +* for various configurations. +* +* @param prog BPF program to attach +* @param pid Process ID to attach the uprobe to, 0 for self (own process), +* -1 for all processes +* @param binary_path Path to binary that contains the function symbol +* @param func_offset Offset within the binary of the function symbol +* @param opts Options for altering program attachment +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +*/ LIBBPF_API struct bpf_link * bpf_program__attach_uprobe_opts(const struct bpf_program *prog, pid_t pid, const char *binary_path, size_t func_offset, --2.33.1