* [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h
@ 2021-09-18 3:14 grantseltzer
2021-09-21 15:47 ` Andrii Nakryiko
0 siblings, 1 reply; 4+ messages in thread
From: grantseltzer @ 2021-09-18 3:14 UTC (permalink / raw)
To: andrii; +Cc: bpf, grantseltzer
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__find_map_by_name()
- bpf_map__fd()
- bpf_map__is_internal()
- libbpf_get_error()
- libbpf_num_possible_cpus()
Signed-off-by: Grant Seltzer <grantseltzer@gmail.com>
---
tools/lib/bpf/libbpf.h | 66 +++++++++++++++++++++++++++++++++++++-----
1 file changed, 58 insertions(+), 8 deletions(-)
diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h
index 2f6f0e15d1e7..7fbe71e6d855 100644
--- a/tools/lib/bpf/libbpf.h
+++ b/tools/lib/bpf/libbpf.h
@@ -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 void
bpf_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);
--
2.31.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h
2021-09-18 3:14 [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h grantseltzer
@ 2021-09-21 15:47 ` Andrii Nakryiko
0 siblings, 0 replies; 4+ messages in thread
From: Andrii Nakryiko @ 2021-09-21 15:47 UTC (permalink / raw)
To: grantseltzer; +Cc: Andrii Nakryiko, bpf
On Fri, Sep 17, 2021 at 8:17 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__find_map_by_name()
> - bpf_map__fd()
> - bpf_map__is_internal()
> - libbpf_get_error()
> - libbpf_num_possible_cpus()
>
> Signed-off-by: Grant Seltzer <grantseltzer@gmail.com>
> ---
Applied to bpf-next yesterday. Patchbot didn't notice, so I'm giving
you a heads up.
> tools/lib/bpf/libbpf.h | 66 +++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 58 insertions(+), 8 deletions(-)
>
[...]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h
2021-12-06 20:37 grantseltzer
@ 2021-12-07 3:20 ` Andrii Nakryiko
0 siblings, 0 replies; 4+ messages in thread
From: Andrii Nakryiko @ 2021-12-07 3:20 UTC (permalink / raw)
To: grantseltzer; +Cc: Andrii Nakryiko, bpf
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
>
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h
@ 2021-12-06 20:37 grantseltzer
2021-12-07 3:20 ` Andrii Nakryiko
0 siblings, 1 reply; 4+ messages in thread
From: grantseltzer @ 2021-12-06 20:37 UTC (permalink / raw)
To: andrii; +Cc: bpf, grantseltzer
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>
---
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-12-07 3:20 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-18 3:14 [PATCH bpf-next v2] libbpf: Add doc comments in libbpf.h grantseltzer
2021-09-21 15:47 ` Andrii Nakryiko
2021-12-06 20:37 grantseltzer
2021-12-07 3:20 ` Andrii Nakryiko
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.