bpf.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Andrii Nakryiko <andrii.nakryiko@gmail.com>
To: grantseltzer <grantseltzer@gmail.com>
Cc: Andrii Nakryiko <andrii@kernel.org>, bpf <bpf@vger.kernel.org>
Subject: Re: [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h
Date: Mon, 6 Dec 2021 19:20:10 -0800	[thread overview]
Message-ID: <CAEf4BzZ4FCBDukW=vsJ7Y1eMm3jV-8Y1yVPzqwBn2_YP=3U4rA@mail.gmail.com> (raw)
In-Reply-To: <20211206203709.332530-1-grantseltzer@gmail.com>

On Mon, Dec 6, 2021 at 12:37 PM grantseltzer <grantseltzer@gmail.com> wrote:
>
> From: Grant Seltzer <grantseltzer@gmail.com>
>
> This adds comments above functions in libbpf.h which document
> their uses. These comments are of a format that doxygen and sphinx
> can pick up and render. These are rendered by libbpf.readthedocs.org
>
> These doc comments are for:
>
> - bpf_object__open_file()
> - bpf_object__open_mem()
> - bpf_program__attach_uprobe()
> - bpf_program__attach_uprobe_opts()
>
> Signed-off-by: Grant Seltzer <grantseltzer@gmail.com>
> ---

Fixed trailing whitespaces, added missing mention of 0 being self for
one of uprobe attach APIs, and applied to bpf-next. Thanks.

>  tools/lib/bpf/libbpf.h | 52 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 52 insertions(+)
>
> diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h
> index 4ec69f224342..d2ca6f1d1dc4 100644
> --- a/tools/lib/bpf/libbpf.h
> +++ b/tools/lib/bpf/libbpf.h
> @@ -108,8 +108,30 @@ struct bpf_object_open_opts {
>  #define bpf_object_open_opts__last_field btf_custom_path
>
>  LIBBPF_API struct bpf_object *bpf_object__open(const char *path);
> +
> +/**
> + * @brief **bpf_object__open_file()** creates a bpf_object by opening
> + * the BPF ELF object file pointed to by the passed path and loading it
> + * into memory.
> + * @param path BPF object file path
> + * @param opts options for how to load the bpf object, this parameter is
> + * option and can be set to NULL
> + * @return pointer to the new bpf_object; or NULL is returned on error,
> + * error code is stored in errno
> + */
>  LIBBPF_API struct bpf_object *
>  bpf_object__open_file(const char *path, const struct bpf_object_open_opts *opts);
> +
> +/**
> + * @brief **bpf_object__open_mem()** creates a bpf_object by reading
> + * the BPF objects raw bytes from a memory buffer containing a valid
> + * BPF ELF object file.
> + * @param obj_buf pointer to the buffer containing ELF file bytes
> + * @param obj_buf_sz number of bytes in the buffer
> + * @param opts options for how to load the bpf object
> + * @return pointer to the new bpf_object; or NULL is returned on error,
> + * error code is stored in errno
> + */
>  LIBBPF_API struct bpf_object *
>  bpf_object__open_mem(const void *obj_buf, size_t obj_buf_sz,
>                      const struct bpf_object_open_opts *opts);
> @@ -344,10 +366,40 @@ struct bpf_uprobe_opts {
>  };
>  #define bpf_uprobe_opts__last_field retprobe
>
> +/**
> + * @brief **bpf_program__attach_uprobe()** attaches a BPF program
> + * to the userspace function which is found by binary path and
> + * offset. You can optionally specify a particular proccess to attach
> + * to. You can also optionally attach the program to the function
> + * exit instead of entry.
> + *
> + * @param prog BPF program to attach
> + * @param retprobe Attach to function exit
> + * @param pid Process ID to attach the uprobe to, -1 for all processes
> + * @param binary_path Path to binary that contains the function symbol
> + * @param func_offset Offset within the binary of the function symbol
> + * @return Reference to the newly created BPF link; or NULL is returned on error,
> + * error code is stored in errno
> + */
>  LIBBPF_API struct bpf_link *
>  bpf_program__attach_uprobe(const struct bpf_program *prog, bool retprobe,
>                            pid_t pid, const char *binary_path,
>                            size_t func_offset);
> +
> +/**
> + * @brief **bpf_program__attach_uprobe_opts()** is just like
> + * bpf_program__attach_uprobe() except with a options struct
> + * for various configurations.
> + *
> + * @param prog BPF program to attach
> + * @param pid Process ID to attach the uprobe to, 0 for self (own process),
> + * -1 for all processes
> + * @param binary_path Path to binary that contains the function symbol
> + * @param func_offset Offset within the binary of the function symbol
> + * @param opts Options for altering program attachment
> + * @return Reference to the newly created BPF link; or NULL is returned on error,
> + * error code is stored in errno
> + */
>  LIBBPF_API struct bpf_link *
>  bpf_program__attach_uprobe_opts(const struct bpf_program *prog, pid_t pid,
>                                 const char *binary_path, size_t func_offset,
> --
> 2.33.1
>

  reply	other threads:[~2021-12-07  3:20 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-06 20:37 [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h grantseltzer
2021-12-07  3:20 ` Andrii Nakryiko [this message]
  -- strict thread matches above, loose matches on Subject: below --
2021-09-18  3:14 grantseltzer
2021-09-21 15:47 ` Andrii Nakryiko

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAEf4BzZ4FCBDukW=vsJ7Y1eMm3jV-8Y1yVPzqwBn2_YP=3U4rA@mail.gmail.com' \
    --to=andrii.nakryiko@gmail.com \
    --cc=andrii@kernel.org \
    --cc=bpf@vger.kernel.org \
    --cc=grantseltzer@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).