libbpf: Add doc comments in libb.h
PATCH 1/1 libbpf: Add doc comments in libb.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 | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)
tools/lib/bpf/libbpf.h +45 -0
@@ -108,8 +108,26 @@ 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 object file pointed to by the passed path and loading it +* into memory. +* @param path BPF object file relative or absolute path +* @param opts options for how to load the bpf object +* @return pointer to the new bpf_object +*/ 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 an in memory buffer. +* @param obj_buf pointer to the buffer containing bpf object 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 +*/ 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 +362,37 @@ 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 +*/ 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, -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 +*/ 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.31.1
Song Liu
reviewerQuoted 7 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.org
Quoted 8 lines
These doc comments are for:
-
bpf_object__open_file()
-bpf_object__open_mem()
-bpf_program__attach_uprobe()
-bpf_program__attach_uprobe_opts()Signed-off-by Grant Seltzer <[email protected]>
s/libb.h/libbpf.h/ in subject
Quoted 10 lines
--- tools/lib/bpf/libbpf.h | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)tools/lib/bpf/libbpf.h +0
-0@@ -108,8 +108,26 @@ struct bpf_object_open_opts {#define bpf_object_open_opts__last_field btf_custom_path
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 118
Quoted 10 lines
tools/lib/bpf/libbpf.h +8
-0LIBBPF_API struct bpf_object *bpf_object__open(const char *path); + +/** +* @brief **bpf_object__open_file()** creates a bpf_object by opening +* the BPF object file pointed to by the passed path and loading it +* into memory. +* @param path BPF object file relative or absolute path +* @param opts options for how to load the bpf object +* @return pointer to the new bpf_object
Please document return value on errors, i.e. libbpf_err_ptr(err) instead of NULL. Same for all functions here.
Quoted 16 lines
tools/lib/bpf/libbpf.h +10
-0+*/ 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 an in memory buffer. +* @param obj_buf pointer to the buffer containing bpf object 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 +*/ 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);
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 368
Quoted 7 lines
tools/lib/bpf/libbpf.h +4
-0@@ -344,10 +362,37 @@ 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
s/proccess/process/
Quoted 15 lines
tools/lib/bpf/libbpf.h +11
-0+* 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 +*/ 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); +
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 393
Quoted 10 lines
tools/lib/bpf/libbpf.h +10
-0+/** +* @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, -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
Let's also document details about these options.
Quoted 8 lines
tools/lib/bpf/libbpf.h +2
-1+* @return Reference to the newly created BPF link +*/ 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.31.1
Quoted 31 lines · Song Liu
Quoted 7 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.orgQuoted 8 lines
These doc comments are for:
-
bpf_object__open_file()
-bpf_object__open_mem()
-bpf_program__attach_uprobe()
-bpf_program__attach_uprobe_opts()Signed-off-by Grant Seltzer <[email protected]>s/libb.h/libbpf.h/ in subject
Quoted 11 lines
--- tools/lib/bpf/libbpf.h | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)tools/lib/bpf/libbpf.h +0
-0@@ -108,8 +108,26 @@ struct bpf_object_open_opts {#define bpf_object_open_opts__last_field btf_custom_path
Quoted 5 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 114
Quoted 5 lines
tools/lib/bpf/libbpf.h +4
-0LIBBPF_API struct bpf_object *bpf_object__open(const char *path); + +/** +* @brief **bpf_object__open_file()** creates a bpf_object by opening +* the BPF object file pointed to by the passed path and loading it
Would be nice to mention that it's ELF, no? "BPF ELF object file", maybe?
Quoted 2 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 116
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+* into memory. +* @param path BPF object file relative or absolute path
I started worrying about relative vs absolute paths after reading this :) I think just stating "BPF object file path" should be totally fine. Relative vs absolute works totally fine as expected with any API that accepts file paths.
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 117
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @param opts options for how to load the bpf object
let's mention that opts are optional (i.e., you can pass NULL)
Quoted 4 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 118
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @return pointer to the new bpf_object Please document return value on errors, i.e.
libbpf_err_ptr(err)instead of NULL. Same for all functions here.
With libbpf 1.0 and forward APIs like this will return NULL on error, so let's use that as the convention in documentation. So something like "NULL is returned on error, error code is stored in errno"?
Quoted 8 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 125
Quoted 8 lines
tools/lib/bpf/libbpf.h +5
-0+*/ 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 an in memory buffer.
typo: "an in"? Also it's even more important to mention that those bytes should be a valid BPF ELF object file?
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 126
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @param obj_buf pointer to the buffer containing bpf object bytes
s/bpf object bytes/ELF file bytes/ ?
Quoted 11 lines
Quoted 11 lines
tools/lib/bpf/libbpf.h +4
-0+* @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 +*/ 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 +362,37 @@ struct bpf_uprobe_opts { };#define bpf_uprobe_opts__last_field retprobe
Quoted 2 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 366
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+/** +* @brief **bpf_program__attach_uprobe** attaches a BPF program
missing () after attach_uprobe
Quoted 10 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 368
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+* to the userspace function which is found by binary path and +* offset. You can optionally specify a particular proccess to attach s/proccess/process/
Quoted 6 lines
tools/lib/bpf/libbpf.h +6
-0+* 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
There is also 0 for self (own process).
Quoted 3 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 377
Quoted 3 lines
tools/lib/bpf/libbpf.h +3
-0+* @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 on error (errno is set to error code).
Quoted 8 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 385
Quoted 8 lines
tools/lib/bpf/libbpf.h +4
-0+*/ 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
() missing
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 386
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* bpf_program__attach_uprobe except with a options struct
(), let's use that around referenced to functions to make it clear
Quoted 9 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 393
Quoted 7 lines
tools/lib/bpf/libbpf.h +7
-0+* for various configurations. +* +* @param prog BPF program to attach +* @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 +* @param opts Options for altering program attachment Let's also document details about these options.
yep, but on uprobe_opts struct itself
Quoted 9 lines
Quoted 9 lines
tools/lib/bpf/libbpf.h +2
-1+* @return Reference to the newly created BPF link +*/ 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.31.1
Quoted 137 lines · Andrii Nakryiko
Quoted 31 lines · Song Liu
Quoted 7 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.orgQuoted 8 lines
These doc comments are for:
-
bpf_object__open_file()
-bpf_object__open_mem()
-bpf_program__attach_uprobe()
-bpf_program__attach_uprobe_opts()Signed-off-by Grant Seltzer <[email protected]>s/libb.h/libbpf.h/ in subject
Quoted 11 lines
--- tools/lib/bpf/libbpf.h | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)tools/lib/bpf/libbpf.h +0
-0@@ -108,8 +108,26 @@ struct bpf_object_open_opts {#define bpf_object_open_opts__last_field btf_custom_pathQuoted 5 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 114
Quoted 5 lines
tools/lib/bpf/libbpf.h +4
-0LIBBPF_API struct bpf_object *bpf_object__open(const char *path); + +/** +* @brief **bpf_object__open_file()** creates a bpf_object by opening +* the BPF object file pointed to by the passed path and loading it Would be nice to mention that it's ELF, no? "BPF ELF object file", maybe?
Quoted 2 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 116
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+* into memory. +* @param path BPF object file relative or absolute path I started worrying about relative vs absolute paths after reading this :) I think just stating "BPF object file path" should be totally fine. Relative vs absolute works totally fine as expected with any API that accepts file paths.
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 117
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @param opts options for how to load the bpf object let's mention that opts are optional (i.e., you can pass NULL)
Quoted 4 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 118
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @return pointer to the new bpf_object Please document return value on errors, i.e.
libbpf_err_ptr(err)instead of NULL. Same for all functions here.With libbpf 1.0 and forward APIs like this will return NULL on error, so let's use that as the convention in documentation. So something like "NULL is returned on error, error code is stored in errno"?
Quoted 8 lines
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 125
Quoted 8 lines
tools/lib/bpf/libbpf.h +5
-0+*/ 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 an in memory buffer. typo: "an in"? Also it's even more important to mention that those bytes should be a valid BPF ELF object file?
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_object_open_opts { · line 126
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* @param obj_buf pointer to the buffer containing bpf object bytes s/bpf object bytes/ELF file bytes/ ?
Quoted 11 lines
Quoted 11 lines
tools/lib/bpf/libbpf.h +4
-0+* @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 +*/ 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 +362,37 @@ struct bpf_uprobe_opts { };#define bpf_uprobe_opts__last_field retprobeQuoted 2 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 366
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+/** +* @brief **bpf_program__attach_uprobe** attaches a BPF program missing () after
attach_uprobeQuoted 10 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 368
Quoted 2 lines
tools/lib/bpf/libbpf.h +2
-0+* to the userspace function which is found by binary path and +* offset. You can optionally specify a particular proccess to attach s/proccess/process/
Quoted 6 lines
tools/lib/bpf/libbpf.h +6
-0+* 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 There is also 0 for self (own process).
Quoted 3 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 377
Quoted 3 lines
tools/lib/bpf/libbpf.h +3
-0+* @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 on error (errno is set to error code).
Quoted 8 lines
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 385
Quoted 8 lines
tools/lib/bpf/libbpf.h +4
-0+*/ 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 () missing
Quoted 1 line
tools/lib/bpf/libbpf.h struct bpf_uprobe_opts { · line 386
Quoted 1 line
tools/lib/bpf/libbpf.h +1
-0+* bpf_program__attach_uprobe except with a options struct (), let's use that around referenced to functions to make it clear
Quoted 8 lines
Quoted 7 lines
tools/lib/bpf/libbpf.h +7
-0+* for various configurations. +* +* @param prog BPF program to attach +* @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 +* @param opts Options for altering program attachment
Quoted 3 lines
Quoted 1 line
Let's also document details about these options.
yep, but on
uprobe_optsstruct itself
I need to fix something with the configuration, the docs site currently isn't displaying structs.
Also I haven't forgotten about adding a check for libbpf docs generating properly. I'm working on a patch that I'll submit to the docs tree allowing make htmldocs to take an argument for which subsection to exclusively build.
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
tools/lib/bpf/libbpf.h +2
-1+* @return Reference to the newly created BPF link +*/ 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.31.1