Add documentation to API functions
PATCH 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()
Signed-off-by Grant Seltzer <[email protected]>
--- tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+)
tools/lib/bpf/libbpf.h +84 -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]>
The text looks good to me. But please run checkpatch.pl and fix all the errors.
Quoted 13 lines
--- tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+)tools/lib/bpf/libbpf.h +1
-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); +/**
tools/lib/bpf/libbpf.h struct bpf_link; · line 391
Quoted 10 lines
tools/lib/bpf/libbpf.h +10
-0+* @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 +*/ +
nit: empty line is not necessary here.
Quoted 106 lines
tools/lib/bpf/libbpf.h +73
-1LIBBPF_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