libbpf: Document bpf_{btf,link,map,prog}_get_info_by_fd()
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
@@ -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
Quoted 6 lines · Ilya Leoshkevich
Replace the short informal description with the proper doc comments.
Suggested-by Andrii Nakryiko <[email protected]>Signed-off-by Ilya Leoshkevich <[email protected]>---
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@@ -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
[...]
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.
Suggested-by Andrii Nakryiko <[email protected]>Signed-off-by Ilya Leoshkevich <[email protected]>--- 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