On Tue, Apr 12, 2022 at 4:33 PM 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>
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
>
