libbpf: Add doc comments in libbpf.h
PATCH v2 1/1 libbpf: Add doc comments in libbpf.h
From: Grant Seltzer <[email protected]>
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__find_map_by_name()
- bpf_map__fd()
- bpf_map__is_internal()
- libbpf_get_error()
- libbpf_num_possible_cpus()
--- tools/lib/bpf/libbpf.h | 66 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 8 deletions(-)
tools/lib/bpf/libbpf.h +58 -8
@@ -478,9 +478,13 @@ struct bpf_map_def {unsigned int map_flags; }; -/* -* The 'struct bpf_map' in include/linux/bpf.h is internal to the kernel, -* so no need to worry about a name clash. +/** +* @brief **bpf_object__find_map_by_name()** returns BPF map of +* the given name, if it exists within the passed BPF object +* @param obj BPF object +* @param name name of the BPF map +* @return BPF map instance, if such map exists within the BPF object; +* or NULL otherwise. */ LIBBPF_API struct bpf_map *bpf_object__find_map_by_name (const struct bpf_object *obj,const char *name);
@@ -506,7 +510,12 @@ bpf_map__next(const struct bpf_map *map, const struct bpf_object *obj); LIBBPF_API struct bpf_map *bpf_map__prev (const struct bpf_map *map,const struct bpf_object *obj); -/* get/set map FD */ +/** +* @brief **bpf_map__fd()** gets the file descriptor of the passed +* BPF map +* @param map the BPF map instance +* @return the file descriptor; or -EINVAL in case of an error +*/ LIBBPF_API int bpf_map__fd(const struct bpf_map *map); LIBBPF_API int bpf_map__reuse_fd(struct bpf_map *map, int fd);/* get map definition */
@@ -547,6 +556,17 @@ LIBBPF_API int bpf_map__set_initial_value(struct bpf_map *map, const void *data, size_t size); LIBBPF_API const void *bpf_map__initial_value(struct bpf_map *map, size_t *psize); LIBBPF_API bool bpf_map__is_offload_neutral(const struct bpf_map *map); + +/** +* @brief **bpf_map__is_internal()** tells the caller whether or not +* the passed map is a special map created by libbpf +* automatically for things like global variables, __ksym externs, +* Kconfig values, etc +* @param map the bpf_map +* @return true if the map is an internal map; or false otherwise +* +* See the enum `libbpf_map_type` for listing of the types +*/ LIBBPF_API bool bpf_map__is_internal(const struct bpf_map *map); LIBBPF_API int bpf_map__set_pin_path(struct bpf_map *map, const char *path); LIBBPF_API const char *bpf_map__get_pin_path(const struct bpf_map *map);
@@ -558,6 +578,36 @@ LIBBPF_API int bpf_map__unpin(struct bpf_map *map, const char *path); LIBBPF_API int bpf_map__set_inner_map_fd(struct bpf_map *map, int fd); LIBBPF_API struct bpf_map *bpf_map__inner_map(struct bpf_map *map); +/** +* @brief **libbpf_get_error()** extracts the error code from the passed +* pointer +* @param ptr pointer returned from libbpf API function +* @return error code; or 0 if no error occured +* +* Many libbpf API functions which return pointers have logic to encode error +* codes as pointers, and do not return NULL. Meaning **libbpf_get_error()** +* should be used on the return value from these functions immediately after +* calling the API function, with no intervening calls that could clobber the +* `errno` variable. Consult the individual functions documentation to verify +* if this logic applies should be used. +* +* For these API functions, if `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` +* is enabled, NULL is returned on error instead. +* +* If ptr is NULL, then errno should be already set by the failing +* API, because libbpf never returns NULL on success and it now always +* sets errno on error. +* +* Example usage: +* +* perfBuffer = perf_buffer__new(bpf_map__fd(obj->maps.events), PERF_BUFFER_PAGES, &opts); +* err = libbpf_get_error(perfBuffer); +* if (err) { +* perfBuffer = NULL; +* fprintf(stderr, "failed to open perf buffer: %d\n", err); +* goto cleanup; +* } +*/ LIBBPF_API long libbpf_get_error (const void *ptr);struct bpf_prog_load_attr {
@@ -822,9 +872,10 @@ bpf_program__bpil_addr_to_offs(struct bpf_prog_info_linear *info_linear); LIBBPF_API voidbpf_program__bpil_offs_to_addr (struct bpf_prog_info_linear *info_linear); -/* -* A helper function to get the number of possible CPUs before looking up -* per-CPU maps. Negative errno is returned on failure. +/** +* @brief **libbpf_num_possible_cpus()** is a helper function to get the +* number of possible CPUs that the host kernel supports and expects. +* @return number of possible CPUs; or error code on failure * * Example usage: *
@@ -834,7 +885,6 @@ bpf_program__bpil_offs_to_addr(struct bpf_prog_info_linear *info_linear);* } * long values[ncpus]; * bpf_map_lookup_elem(per_cpu_map_fd, key, values); -* */ LIBBPF_API int libbpf_num_possible_cpus(void);
Signature · 1 line
2.31.1
Andrii Nakryiko
AppliedQuoted 14 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds comments above functions in
libbpf.hwhich document their uses. These comments are of a format that doxygen and sphinx can pick up and render. These are rendered by libbpf.readthedocs.orgThese doc comments are for:
-bpf_object__find_map_by_name()
-bpf_map__fd()
-bpf_map__is_internal()
-libbpf_get_error()
-libbpf_num_possible_cpus()
Quoted 2 lines
Signed-off-by Grant Seltzer <[email protected]>---
Applied to bpf-next yesterday. Patchbot didn't notice, so I'm giving you a heads up.
Quoted 3 lines
tools/lib/bpf/libbpf.h | 66 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 8 deletions(-)
[...]