linux-kernel - Re: [PATCH] libbpf: Added the description of some API functions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 29 Dec 2022 14:33:32 -0800
From:   Andrii Nakryiko <andrii.nakryiko@...il.com>
To:     Xin Liu <liuxin350@...wei.com>
Cc:     andrii@...nel.org, ast@...nel.org, daniel@...earbox.net,
        martin.lau@...ux.dev, song@...nel.org, yhs@...com,
        john.fastabend@...il.com, kpsingh@...nel.org, sdf@...gle.com,
        haoluo@...gle.com, jolsa@...nel.org, bpf@...r.kernel.org,
        linux-kernel@...r.kernel.org, yanan@...wei.com,
        wuchangye@...wei.com, xiesongyang@...wei.com,
        kongweibin2@...wei.com, zhangmingyi5@...wei.com
Subject: Re: [PATCH] libbpf: Added the description of some API functions

On Sat, Dec 24, 2022 at 3:21 AM Xin Liu <liuxin350@...wei.com> wrote:
>
> Currently, many API functions are not described in the document.
> I have tried to add the API description of the following four API
> functions:
>  libbpf_set_print
>  bpf_object__open
>  bpf_object__load
>  bpf_object__close
>
> Signed-off-by: Xin Liu <liuxin350@...wei.com>
> ---

I've tweaked descriptions a bit to match the overall style and fixed
few typos. Pushed to bpf-next, thanks!

>  tools/lib/bpf/libbpf.h | 27 ++++++++++++++++++++++++++-
>  1 file changed, 26 insertions(+), 1 deletion(-)
>
> diff --git a/tools/lib/bpf/libbpf.h b/tools/lib/bpf/libbpf.h
> index eee883f007f9..bf3af52d42be 100644
> --- a/tools/lib/bpf/libbpf.h
> +++ b/tools/lib/bpf/libbpf.h
> @@ -96,6 +96,12 @@ enum libbpf_print_level {
>  typedef int (*libbpf_print_fn_t)(enum libbpf_print_level level,
>                                  const char *, va_list ap);
>
> +/**
> + * @brief **libbpf_set_print()** use the user-provided log print function.
> + * @param fn the log print function. Disable all print if the parameter
> + * is NULL.
> + * @return Pointer to old print function.
> + */
>  LIBBPF_API libbpf_print_fn_t libbpf_set_print(libbpf_print_fn_t fn);
>
>  /* Hide internal to user */
> @@ -174,6 +180,14 @@ struct bpf_object_open_opts {
>  };
>  #define bpf_object_open_opts__last_field kernel_log_level
>
> +/**
> + * @brief **bpf_object__open()** 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.
> + * @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(const char *path);
>
>  /**
> @@ -204,9 +218,20 @@ bpf_object__open_mem(const void *obj_buf, size_t obj_buf_sz,
>                      const struct bpf_object_open_opts *opts);
>
>  /* Load/unload object into/from kernel */
> +/**
> + * @brief **bpf_object__load()** load bpf_object into kernel
> + * @param obj pointer to a valid bpf_object
> + * @return 0, on success; negative error code, otherwise, error code is
> + * stored in errno
> + */
>  LIBBPF_API int bpf_object__load(struct bpf_object *obj);
>
> -LIBBPF_API void bpf_object__close(struct bpf_object *object);
> +/**
> + * @brief **bpf_object__close()** close a bpf_object and release all
> + * resources.
> + * @param obj pointer to a valid bpf_object
> + */
> +LIBBPF_API void bpf_object__close(struct bpf_object *obj);
>
>  /* pin_maps and unpin_maps can both be called with a NULL path, in which case
>   * they will use the pin_path attribute of each map (and ignore all maps that
> --
> 2.33.0
>