Add documentation to API functions
PATCH v2 1/1 Add documentation to API functions
From: Grant Seltzer <[email protected]>
This adds documentation for the following API functions:
- bpf_program__set_expected_attach_type()
- bpf_program__set_type()
- bpf_program__set_attach_target()
- bpf_program__attach()
- bpf_program__pin()
- bpf_program__unpin()
--- tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+)
tools/lib/bpf/libbpf.h +83 -0
@@ -378,7 +378,31 @@ struct bpf_link; LIBBPF_API struct bpf_link *bpf_link__open(const char *path); LIBBPF_API int bpf_link__fd(const struct bpf_link *link); LIBBPF_API const char *bpf_link__pin_path(const struct bpf_link *link); +/** +* @brief **bpf_link__pin()** pins the BPF link to a file +* in the BPF FS specified by a path. This increments the links +* reference count, allowing it to stay loaded after the process +* which loaded it has exited. +* +* @param link BPF link to pin, must already be loaded +* @param path file path in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__pin(struct bpf_link *link, const char *path); + +/** +* @brief **bpf_link__unpin()** unpins the BPF link from a file +* in the BPFFS specified by a path. This decrements the links +* reference count. +* +* The file pinning the BPF link can also be unlinked by a different +* process in which case this function will return an error. +* +* @param link BPF link to unpin +* @param path file path to the pin in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__unpin(struct bpf_link *link); LIBBPF_API int bpf_link__update_program(struct bpf_link *link,struct bpf_program *prog);
@@ -386,6 +410,21 @@ LIBBPF_API void bpf_link__disconnect(struct bpf_link *link); LIBBPF_API int bpf_link__detach(struct bpf_link *link); LIBBPF_API int bpf_link__destroy(struct bpf_link *link); +/** +* @brief **bpf_program__attach()** is a generic function for attaching +* a BPF program based on auto-detection of program type, attach type, +* and extra parameters, where applicable. +* +* @param prog BPF program to attach +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +* +* This is supported for: +* - kprobe/kretprobe +* - tracepoint +* - raw tracepoint +* - tracing programs (typed raw TP/fentry/fexit/fmod_ret) +*/ LIBBPF_API struct bpf_link *bpf_program__attach (const struct bpf_program *prog);
@@ -686,11 +725,36 @@ LIBBPF_DEPRECATED_SINCE(0, 8, "use bpf_program__set_type() instead") LIBBPF_API int bpf_program__set_sk_lookup(struct bpf_program *prog); LIBBPF_API enum bpf_prog_type bpf_program__type(const struct bpf_program *prog); +/** +* @brief **bpf_program__set_type()** sets the program +* type of the passed BPF program. +* @param prog BPF program to set the program type for +* @param type program type to set the BPF map to have +*/ LIBBPF_API void bpf_program__set_type(struct bpf_program *prog,enum bpf_prog_type type); LIBBPF_API enum bpf_attach_typebpf_program__expected_attach_type (const struct bpf_program *prog); +/** +* @brief **bpf_program__set_expected_attach_type()** sets the +* attach type of the passed BPF program. This is used for +* auto-detection of attachment when programs are loaded. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow: +* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +* +*/ LIBBPF_API voidbpf_program__set_expected_attach_type (struct bpf_program *prog,enum bpf_attach_type type);
@@ -707,6 +771,26 @@ LIBBPF_API int bpf_program__set_log_level(struct bpf_program *prog, __u32 log_le LIBBPF_API const char *bpf_program__log_buf(const struct bpf_program *prog, size_t *log_size); LIBBPF_API int bpf_program__set_log_buf(struct bpf_program *prog, char *log_buf, size_t log_size); +/** +* @brief **bpf_program__set_attach_target()** sets the +* specified BPF program to attach to a specific tracepoint +* or kernel function. This can be used to supplement +* the BPF program name/section not matching the tracepoint +* or function semantics. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow: +* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +*/ LIBBPF_API intbpf_program__set_attach_target (struct bpf_program *prog,int attach_prog_fd,const char *attach_func_name);
Signature · 1 line
2.34.1
Song Liu
reviewerQuoted 11 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds documentation for the following API functions:
-bpf_program__set_expected_attach_type()
-bpf_program__set_type()
-bpf_program__set_attach_target()
-bpf_program__attach()
-bpf_program__pin()
-bpf_program__unpin()
Quoted 1 line
Signed-off-by Grant Seltzer <[email protected]>
Could you please rebase on top of latest bpf-next/master branch so that the tests would run properly:
https://patchwork.kernel.org/project/netdevbpf/patch/[email protected]/
Thanks,
Song
Quoted 128 lines
--- tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+)tools/lib/bpf/libbpf.h +83
-1@@ -378,7 +378,31 @@ struct bpf_link; LIBBPF_API struct bpf_link *bpf_link__open(const char *path); LIBBPF_API int bpf_link__fd(const struct bpf_link *link); LIBBPF_API const char *bpf_link__pin_path(const struct bpf_link *link); +/** +* @brief **bpf_link__pin()** pins the BPF link to a file +* in the BPF FS specified by a path. This increments the links +* reference count, allowing it to stay loaded after the process +* which loaded it has exited. +* +* @param link BPF link to pin, must already be loaded +* @param path file path in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__pin(struct bpf_link *link, const char *path); + +/** +* @brief **bpf_link__unpin()** unpins the BPF link from a file +* in the BPFFS specified by a path. This decrements the links +* reference count. +* +* The file pinning the BPF link can also be unlinked by a different +* process in which case this function will return an error. +* +* @param link BPF link to unpin +* @param path file path to the pin in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__unpin(struct bpf_link *link); LIBBPF_API int bpf_link__update_program(struct bpf_link *link,struct bpf_program *prog);@@ -386,6 +410,21 @@ LIBBPF_API void bpf_link__disconnect(struct bpf_link *link); LIBBPF_API int bpf_link__detach(struct bpf_link *link); LIBBPF_API int bpf_link__destroy(struct bpf_link *link); +/** +* @brief **bpf_program__attach()** is a generic function for attaching +* a BPF program based on auto-detection of program type, attach type, +* and extra parameters, where applicable. +* +* @param prog BPF program to attach +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +* +* This is supported for: +* - kprobe/kretprobe +* - tracepoint +* - raw tracepoint +* - tracing programs (typed raw TP/fentry/fexit/fmod_ret) +*/ LIBBPF_API struct bpf_link *bpf_program__attach (const struct bpf_program *prog);@@ -686,11 +725,36 @@ LIBBPF_DEPRECATED_SINCE(0, 8, "use bpf_program__set_type() instead") LIBBPF_API int bpf_program__set_sk_lookup(struct bpf_program *prog); LIBBPF_API enum bpf_prog_type bpf_program__type(const struct bpf_program *prog); +/** +* @brief **bpf_program__set_type()** sets the program +* type of the passed BPF program. +* @param prog BPF program to set the program type for +* @param type program type to set the BPF map to have +*/ LIBBPF_API void bpf_program__set_type(struct bpf_program *prog,enum bpf_prog_type type); LIBBPF_API enum bpf_attach_typebpf_program__expected_attach_type (const struct bpf_program *prog); +/** +* @brief **bpf_program__set_expected_attach_type()** sets the +* attach type of the passed BPF program. This is used for +* auto-detection of attachment when programs are loaded. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow: +* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +* +*/ LIBBPF_API voidbpf_program__set_expected_attach_type (struct bpf_program *prog,enum bpf_attach_type type);@@ -707,6 +771,26 @@ LIBBPF_API int bpf_program__set_log_level(struct bpf_program *prog, __u32 log_le LIBBPF_API const char *bpf_program__log_buf(const struct bpf_program *prog, size_t *log_size); LIBBPF_API int bpf_program__set_log_buf(struct bpf_program *prog, char *log_buf, size_t log_size); +/** +* @brief **bpf_program__set_attach_target()** sets the +* specified BPF program to attach to a specific tracepoint +* or kernel function. This can be used to supplement +* the BPF program name/section not matching the tracepoint +* or function semantics. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow: +* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +*/ LIBBPF_API intbpf_program__set_attach_target (struct bpf_program *prog,int attach_prog_fd,const char *attach_func_name); --2.34.1
Quoted 56 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds documentation for the following API functions:
-bpf_program__set_expected_attach_type()
-bpf_program__set_type()
-bpf_program__set_attach_target()
-bpf_program__attach()
-bpf_program__pin()
-bpf_program__unpin()Signed-off-by Grant Seltzer <[email protected]>--- tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+)tools/lib/bpf/libbpf.h +24
-0@@ -378,7 +378,31 @@ struct bpf_link; LIBBPF_API struct bpf_link *bpf_link__open(const char *path); LIBBPF_API int bpf_link__fd(const struct bpf_link *link); LIBBPF_API const char *bpf_link__pin_path(const struct bpf_link *link); +/** +* @brief **bpf_link__pin()** pins the BPF link to a file +* in the BPF FS specified by a path. This increments the links +* reference count, allowing it to stay loaded after the process +* which loaded it has exited. +* +* @param link BPF link to pin, must already be loaded +* @param path file path in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__pin(struct bpf_link *link, const char *path); + +/** +* @brief **bpf_link__unpin()** unpins the BPF link from a file +* in the BPFFS specified by a path. This decrements the links +* reference count. +* +* The file pinning the BPF link can also be unlinked by a different +* process in which case this function will return an error. +* +* @param link BPF link to unpin +* @param path file path to the pin in a BPF file system +* @return 0, on success; negative error code, otherwise +*/ LIBBPF_API int bpf_link__unpin(struct bpf_link *link); LIBBPF_API int bpf_link__update_program(struct bpf_link *link,struct bpf_program *prog);@@ -386,6 +410,21 @@ LIBBPF_API void bpf_link__disconnect(struct bpf_link *link); LIBBPF_API int bpf_link__detach(struct bpf_link *link); LIBBPF_API int bpf_link__destroy(struct bpf_link *link); +/**
tools/lib/bpf/libbpf.h LIBBPF_API void bpf_link__disconnect(struct bpf_link *link); · line 423
Quoted 10 lines
tools/lib/bpf/libbpf.h +10
-0+* @brief **bpf_program__attach()** is a generic function for attaching +* a BPF program based on auto-detection of program type, attach type, +* and extra parameters, where applicable. +* +* @param prog BPF program to attach +* @return Reference to the newly created BPF link; or NULL is returned on error, +* error code is stored in errno +* +* This is supported for: +* - kprobe/kretprobe
uprobe/uretprobe as well, though depending on specific SEC() definition (just like for kprobe/kretprobe now).
Quoted 8 lines
tools/lib/bpf/libbpf.h +4
-0+* - tracepoint +* - raw tracepoint +* - tracing programs (typed raw TP/fentry/fexit/fmod_ret) +*/ LIBBPF_API struct bpf_link *bpf_program__attach (const struct bpf_program *prog);
tools/lib/bpf/libbpf.h LIBBPF_DEPRECATED_SINCE(0, 8, "use bpf_program__set_type() instead") · line 733
Quoted 9 lines
tools/lib/bpf/libbpf.h +6
-0@@ -686,11 +725,36 @@ LIBBPF_DEPRECATED_SINCE(0, 8, "use bpf_program__set_type() instead") LIBBPF_API int bpf_program__set_sk_lookup(struct bpf_program *prog); LIBBPF_API enum bpf_prog_type bpf_program__type(const struct bpf_program *prog); +/** +* @brief **bpf_program__set_type()** sets the program +* type of the passed BPF program. +* @param prog BPF program to set the program type for +* @param type program type to set the BPF map to have +*/
Can you please mention that the type has to be set before BPF object is loaded, otherwise it has no effect (though it would be good to change it to return an error, actually, not sure about ABI implications, though, but I think we did such changes before, so probably it's fine).
Quoted 13 lines
tools/lib/bpf/libbpf.h +8
-0LIBBPF_API void bpf_program__set_type(struct bpf_program *prog,enum bpf_prog_type type); LIBBPF_API enum bpf_attach_typebpf_program__expected_attach_type (const struct bpf_program *prog); +/** +* @brief **bpf_program__set_expected_attach_type()** sets the +* attach type of the passed BPF program. This is used for +* auto-detection of attachment when programs are loaded. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow:
tools/lib/bpf/libbpf.h LIBBPF_DEPRECATED_SINCE(0, 8, "use bpf_program__set_type() instead") · line 756
Quoted 10 lines
tools/lib/bpf/libbpf.h +10
-0+* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +*
same about the note to do it before load phase, and maybe changing this to return int error
Quoted 18 lines
tools/lib/bpf/libbpf.h +11
-0+*/ LIBBPF_API voidbpf_program__set_expected_attach_type (struct bpf_program *prog,enum bpf_attach_type type);@@ -707,6 +771,26 @@ LIBBPF_API int bpf_program__set_log_level(struct bpf_program *prog, __u32 log_le LIBBPF_API const char *bpf_program__log_buf(const struct bpf_program *prog, size_t *log_size); LIBBPF_API int bpf_program__set_log_buf(struct bpf_program *prog, char *log_buf, size_t log_size); +/** +* @brief **bpf_program__set_attach_target()** sets the +* specified BPF program to attach to a specific tracepoint +* or kernel function. This can be used to supplement +* the BPF program name/section not matching the tracepoint +* or function semantics. +* @param prog BPF program to set the attach type for +* @param type attach type to set the BPF map to have +* +* An example workflow:
tools/lib/bpf/libbpf.h LIBBPF_API int bpf_program__set_log_level(struct bpf_program *prog, __u32 log_le · line 793
Quoted 10 lines
tools/lib/bpf/libbpf.h +10
-0+* +* ... +* xdp_fd = bpf_prog_get_fd_by_id(id); +* trace_obj = bpf_object__open_file("func.o", NULL); +* prog = bpf_object__find_program_by_title(trace_obj, "fentry/myfunc"); +* bpf_program__set_expected_attach_type(prog, BPF_TRACE_FENTRY); +* bpf_program__set_attach_target(prog, xdp_fd, "xdpfilt_blk_all"); +* bpf_object__load(trace_obj); +* ... +*/
same about the load note, but now we actually have int error being returned (which probably would be good to mention in @return section)?
Quoted 6 lines
tools/lib/bpf/libbpf.h +0
-1LIBBPF_API intbpf_program__set_attach_target (struct bpf_program *prog,int attach_prog_fd,const char *attach_func_name); --2.34.1