| Message ID | 20220412215431.271150-1-grantseltzer@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | BPF |
| Headers | show |
| Series | [bpf-next] Add documentation to API functions | expand |
On Tue, Apr 12, 2022 at 4:33 PM grantseltzer <grantseltzer@gmail.com> wrote: > > From: Grant Seltzer <grantseltzer@gmail.com> > > 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 <grantseltzer@gmail.com> The text looks good to me. But please run checkpatch.pl and fix all the errors. > --- > tools/lib/bpf/libbpf.h | 84 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 84 insertions(+) > > diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h > index 63d66f1adf1a..09a8bf2fd7d9 100644 > --- a/tools/lib/bpf/libbpf.h > +++ b/tools/lib/bpf/libbpf.h > @@ -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 > + */ > + nit: empty line is not necessary here. > 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_type > bpf_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 void > bpf_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 int > bpf_program__set_attach_target(struct bpf_program *prog, int attach_prog_fd, > const char *attach_func_name); > -- > 2.34.1 >
diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h index 63d66f1adf1a..09a8bf2fd7d9 100644 --- a/tools/lib/bpf/libbpf.h +++ b/tools/lib/bpf/libbpf.h @@ -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_type bpf_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 void bpf_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 int bpf_program__set_attach_target(struct bpf_program *prog, int attach_prog_fd, const char *attach_func_name);