| Message ID | 20211206203709.332530-1-grantseltzer@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | BPF |
| Headers | show |
| Series | [bpf-next,v2] libbpf: Add doc comments in libbpf.h | expand |
On Mon, Dec 6, 2021 at 12:37 PM grantseltzer <grantseltzer@gmail.com> wrote: > > From: Grant Seltzer <grantseltzer@gmail.com> > > 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() > > Signed-off-by: Grant Seltzer <grantseltzer@gmail.com> > --- Fixed trailing whitespaces, added missing mention of 0 being self for one of uprobe attach APIs, and applied to bpf-next. Thanks. > tools/lib/bpf/libbpf.h | 52 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 52 insertions(+) > > diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h > index 4ec69f224342..d2ca6f1d1dc4 100644 > --- a/tools/lib/bpf/libbpf.h > +++ b/tools/lib/bpf/libbpf.h > @@ -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 >
diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h index 4ec69f224342..d2ca6f1d1dc4 100644 --- a/tools/lib/bpf/libbpf.h +++ b/tools/lib/bpf/libbpf.h @@ -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,