Skip to contentSkip to conversation

libbpf: Document bpf_{btf,link,map,prog}_get_info_by_fd()

PATCH Applied Ilya Leoshkevich 3 participants 3 messages Feb 20, 2023 – Feb 27, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 libbpf: Document bpf_{btf,link,map,prog}_get_info_by_fd()

Replace the short informal description with the proper doc comments.

---
 tools/lib/bpf/bpf.h | 67 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)
tools/lib/bpf/bpf.h +63 -4
index 9ed9bceb4111..e8c5c5832359 100644
@@ -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 {
Signature · 1 line
2.39.1
#1 lore raw
Quoted 6 lines · Ilya Leoshkevich

Replace the short informal description with the proper doc comments.

---

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.

Quoted 87 lines
 tools/lib/bpf/bpf.h | 67 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)
tools/lib/bpf/bpf.h +63 -5
index 9ed9bceb4111..e8c5c5832359 100644
@@ -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

[...]

#2 lore raw
In reply to Ilya Leoshkevich
This patch was applied to bpf/bpf-next.git (master) by Andrii Nakryiko <[email protected]>:

Hello:

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

Quoted 7 lines · On Tue, 21 Feb 2023 00:49:58 +0100 you wrote:

Replace the short informal description with the proper doc comments.

---
 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!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html