[bpf-next] libbpf: Document bpf_{btf,link,map,prog}_get_info_by_fd()

Commit Message

Ilya Leoshkevich Feb. 20, 2023, 11:49 p.m. UTC

Replace the short informal description with the proper doc comments.

Suggested-by: Andrii Nakryiko <[e-mail]>
Signed-off-by: Ilya Leoshkevich <[e-mail]>
---
 tools/lib/bpf/bpf.h | 67 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)

Comments

Andrii Nakryiko Feb. 27, 2023, 9:32 p.m. UTC | #1

On Mon, Feb 20, 2023 at 3:50 PM Ilya Leoshkevich <[e-mail]> wrote:
>
> Replace the short informal description with the proper doc comments.
>
> Suggested-by: Andrii Nakryiko <[e-mail]>
> Signed-off-by: Ilya Leoshkevich <[e-mail]>
> ---

Thanks for the follow up! I diff few small adjustments for consistency
(eBPF -> BPF), also updated invalid generic bpf_fd to
{prog,map,btf,link}_fd. Also "BPF BTF" read very awkwardly, so I
called it just "BTF object".

Let me know if you disagree with updates, but otherwise I've pushed
this to bpf-next, thanks.


>  tools/lib/bpf/bpf.h | 67 ++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 63 insertions(+), 4 deletions(-)
>
> diff --git a/tools/lib/bpf/bpf.h b/tools/lib/bpf/bpf.h
> index 9ed9bceb4111..e8c5c5832359 100644
> --- a/tools/lib/bpf/bpf.h
> +++ b/tools/lib/bpf/bpf.h
> @@ -386,14 +386,73 @@ LIBBPF_API int bpf_link_get_fd_by_id(__u32 id);
>  LIBBPF_API int bpf_link_get_fd_by_id_opts(__u32 id,
>                                 const struct bpf_get_fd_by_id_opts *opts);
>  LIBBPF_API int bpf_obj_get_info_by_fd(int bpf_fd, void *info, __u32 *info_len);
> -/* Type-safe variants of bpf_obj_get_info_by_fd(). The callers still needs to
> - * pass info_len, which should normally be
> - * sizeof(struct bpf_{prog,map,btf,link}_info), in order to be compatible with
> - * different libbpf and kernel versions.
> +
> +/**
> + * @brief **bpf_prog_get_info_by_fd()** obtains information about the eBPF
> + * program corresponding to *bpf_fd*.
> + *
> + * Populates up to *info_len* bytes of *info* and updates *info_len* with the
> + * actual number of bytes written to *info*.
> + *
> + * @param bpf_fd eBPF program file descriptor
> + * @param info pointer to **struct bpf_prog_info** that will be populated with
> + * eBPF program information
> + * @param info_len pointer to the size of *info*; on success updated with the
> + * number of bytes written to *info*
> + * @return 0, on success; negative error code, otherwise (errno is also set to
> + * the error code)
>   */
>  LIBBPF_API int bpf_prog_get_info_by_fd(int prog_fd, struct bpf_prog_info *info, __u32 *info_len);
> +
> +/**
> + * @brief **bpf_map_get_info_by_fd()** obtains information about the eBPF
> + * map corresponding to *bpf_fd*.
> + *
> + * Populates up to *info_len* bytes of *info* and updates *info_len* with the
> + * actual number of bytes written to *info*.
> + *
> + * @param bpf_fd eBPF map file descriptor
> + * @param info pointer to **struct bpf_map_info** that will be populated with
> + * eBPF map information
> + * @param info_len pointer to the size of *info*; on success updated with the
> + * number of bytes written to *info*
> + * @return 0, on success; negative error code, otherwise (errno is also set to
> + * the error code)
> + */
>  LIBBPF_API int bpf_map_get_info_by_fd(int map_fd, struct bpf_map_info *info, __u32 *info_len);
> +
> +/**
> + * @brief **bpf_btf_get_info_by_fd()** obtains information about the eBPF
> + * BTF corresponding to *bpf_fd*.
> + *
> + * Populates up to *info_len* bytes of *info* and updates *info_len* with the
> + * actual number of bytes written to *info*.
> + *
> + * @param bpf_fd eBPF BTF file descriptor
> + * @param info pointer to **struct bpf_btf_info** that will be populated with
> + * eBPF BTF information
> + * @param info_len pointer to the size of *info*; on success updated with the
> + * number of bytes written to *info*
> + * @return 0, on success; negative error code, otherwise (errno is also set to
> + * the error code)
> + */
>  LIBBPF_API int bpf_btf_get_info_by_fd(int btf_fd, struct bpf_btf_info *info, __u32 *info_len);
> +
> +/**
> + * @brief **bpf_btf_get_info_by_fd()** obtains information about the eBPF
> + * link corresponding to *bpf_fd*.
> + *
> + * Populates up to *info_len* bytes of *info* and updates *info_len* with the
> + * actual number of bytes written to *info*.
> + *
> + * @param bpf_fd eBPF link file descriptor
> + * @param info pointer to **struct bpf_link_info** that will be populated with
> + * eBPF link information
> + * @param info_len pointer to the size of *info*; on success updated with the
> + * number of bytes written to *info*
> + * @return 0, on success; negative error code, otherwise (errno is also set to
> + * the error code)
> + */
>  LIBBPF_API int bpf_link_get_info_by_fd(int link_fd, struct bpf_link_info *info, __u32 *info_len);
>
>  struct bpf_prog_query_opts {
> --
> 2.39.1


[...]

[e-mail] Feb. 27, 2023, 9:40 p.m. UTC | #2

Hello:

This patch was applied to bpf/bpf-next.git (master)
by Andrii Nakryiko <[e-mail]>:

On Tue, 21 Feb 2023 00:49:58 +0100 you wrote:
> Replace the short informal description with the proper doc comments.
> 
> Suggested-by: Andrii Nakryiko <[e-mail]>
> Signed-off-by: Ilya Leoshkevich <[e-mail]>
> ---
>  tools/lib/bpf/bpf.h | 67 ++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 63 insertions(+), 4 deletions(-)

Here is the summary with links:
  - [bpf-next] libbpf: Document bpf_{btf,link,map,prog}_get_info_by_fd()
    https://git.kernel.org/bpf/bpf-next/c/0a504fa1a780

You are awesome, thank you!

Patch

diff --git a/tools/lib/bpf/bpf.h b/tools/lib/bpf/bpf.h
index 9ed9bceb4111..e8c5c5832359 100644
--- a/tools/lib/bpf/bpf.h
+++ b/tools/lib/bpf/bpf.h
@@ -386,14 +386,73 @@  LIBBPF_API int bpf_link_get_fd_by_id(__u32 id);
 LIBBPF_API int bpf_link_get_fd_by_id_opts(__u32 id,
 				const struct bpf_get_fd_by_id_opts *opts);
 LIBBPF_API int bpf_obj_get_info_by_fd(int bpf_fd, void *info, __u32 *info_len);
-/* Type-safe variants of bpf_obj_get_info_by_fd(). The callers still needs to
- * pass info_len, which should normally be
- * sizeof(struct bpf_{prog,map,btf,link}_info), in order to be compatible with
- * different libbpf and kernel versions.
+
+/**
+ * @brief **bpf_prog_get_info_by_fd()** obtains information about the eBPF
+ * program corresponding to *bpf_fd*.
+ *
+ * Populates up to *info_len* bytes of *info* and updates *info_len* with the
+ * actual number of bytes written to *info*.
+ *
+ * @param bpf_fd eBPF program file descriptor
+ * @param info pointer to **struct bpf_prog_info** that will be populated with
+ * eBPF program information
+ * @param info_len pointer to the size of *info*; on success updated with the
+ * number of bytes written to *info*
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
  */
 LIBBPF_API int bpf_prog_get_info_by_fd(int prog_fd, struct bpf_prog_info *info, __u32 *info_len);
+
+/**
+ * @brief **bpf_map_get_info_by_fd()** obtains information about the eBPF
+ * map corresponding to *bpf_fd*.
+ *
+ * Populates up to *info_len* bytes of *info* and updates *info_len* with the
+ * actual number of bytes written to *info*.
+ *
+ * @param bpf_fd eBPF map file descriptor
+ * @param info pointer to **struct bpf_map_info** that will be populated with
+ * eBPF map information
+ * @param info_len pointer to the size of *info*; on success updated with the
+ * number of bytes written to *info*
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 LIBBPF_API int bpf_map_get_info_by_fd(int map_fd, struct bpf_map_info *info, __u32 *info_len);
+
+/**
+ * @brief **bpf_btf_get_info_by_fd()** obtains information about the eBPF
+ * BTF corresponding to *bpf_fd*.
+ *
+ * Populates up to *info_len* bytes of *info* and updates *info_len* with the
+ * actual number of bytes written to *info*.
+ *
+ * @param bpf_fd eBPF BTF file descriptor
+ * @param info pointer to **struct bpf_btf_info** that will be populated with
+ * eBPF BTF information
+ * @param info_len pointer to the size of *info*; on success updated with the
+ * number of bytes written to *info*
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 LIBBPF_API int bpf_btf_get_info_by_fd(int btf_fd, struct bpf_btf_info *info, __u32 *info_len);
+
+/**
+ * @brief **bpf_btf_get_info_by_fd()** obtains information about the eBPF
+ * link corresponding to *bpf_fd*.
+ *
+ * Populates up to *info_len* bytes of *info* and updates *info_len* with the
+ * actual number of bytes written to *info*.
+ *
+ * @param bpf_fd eBPF link file descriptor
+ * @param info pointer to **struct bpf_link_info** that will be populated with
+ * eBPF link information
+ * @param info_len pointer to the size of *info*; on success updated with the
+ * number of bytes written to *info*
+ * @return 0, on success; negative error code, otherwise (errno is also set to
+ * the error code)
+ */
 LIBBPF_API int bpf_link_get_info_by_fd(int link_fd, struct bpf_link_info *info, __u32 *info_len);
 
 struct bpf_prog_query_opts {