Re: [PATCH bpf-next] Add documentation to API functions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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
>



[Index of Archives]     [Linux Samsung SoC]     [Linux Rockchip SoC]     [Linux Actions SoC]     [Linux for Synopsys ARC Processors]     [Linux NFS]     [Linux NILFS]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]


  Powered by Linux