On Thu, Apr 14, 2022 at 6:08 AM grantseltzer <grantseltzer@xxxxxxxxx> wrote: > > From: Grant Seltzer <grantseltzer@xxxxxxxxx> > > 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@xxxxxxxxx> 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/20220414130832.101112-1-grantseltzer@xxxxxxxxx/ Thanks, Song > --- > 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 > + */ > 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 >
