libbpf: Add sphinx code documentation comments
PATCH v3 1/1 libbpf: Add sphinx code documentation comments
From: Grant Seltzer <[email protected]>
This adds comments above five functions in btf.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
--- tools/lib/bpf/btf.h | 67 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+)
tools/lib/bpf/btf.h +67 -0
@@ -1,5 +1,6 @@/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ /* Copyright (c) 2018 Facebook */ +/*! \file */ #ifndef __LIBBPF_BTF_H#define __LIBBPF_BTF_H
@@ -30,11 +31,77 @@ enum btf_endianness { BTF_BIG_ENDIAN = 1, }; +/** +* @brief **btf__free()** frees all data of a BTF object +* @param btf BTF object to free +*/ LIBBPF_API void btf__free(struct btf *btf); +/** +* @brief **btf__new()** creates a new instance of a BTF object +* from the raw bytes of an ELF's BTF section +* @param data raw bytes +* @param size number of bytes passed in `data` +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new(const void *data, __u32 size); + +/** +* @brief **btf__new_split()** create a new instance of a BTF object from +* the provided raw data bytes. It takes another BTF instance, **base_btf**, +* which serves as a base BTF, which is extended by types in a newly created +* BTF instance +* @param data raw bytes +* @param size length of raw bytes +* @param base_btf the base btf object +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_split(const void *data, __u32 size, struct btf *base_btf); + +/** +* @brief **btf__new_empty()** creates an unpopulated BTF object +* Use `btf__add_*()` to populate such BTF object. +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_empty(void); + +/** +* @brief **btf__new_empty_split()** creates an unpopulated +* BTF object from an ELF BTF section except with a base BTF +* on top of which split BTF should be based +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* If *base_btf* is NULL, `btf__new_empty_split()` is equivalent to +* `btf__new_empty()` and creates non-split BTF. +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_empty_split(struct btf *base_btf); LIBBPF_API struct btf *btf__parse(const char *path, struct btf_ext **btf_ext);
Signature · 1 line
2.31.1
Quoted 12 lines · grantseltzer
From: Grant Seltzer <[email protected]>
This adds comments above five functions in
btf.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.orgSigned-off-by Grant Seltzer <[email protected]>--- tools/lib/bpf/btf.h | 67 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+)
Did a few tweaks and re-flowed the text with vim. Pushed to bpf-next, thanks! I'll sync all this into Github momentarily.
Quoted 69 lines
tools/lib/bpf/btf.h +50
-0@@ -1,5 +1,6 @@/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */ /* Copyright (c) 2018 Facebook */ +/*! \file */ #ifndef __LIBBPF_BTF_H#define __LIBBPF_BTF_H@@ -30,11 +31,77 @@ enum btf_endianness { BTF_BIG_ENDIAN = 1, }; +/** +* @brief **btf__free()** frees all data of a BTF object +* @param btf BTF object to free +*/ LIBBPF_API void btf__free(struct btf *btf); +/** +* @brief **btf__new()** creates a new instance of a BTF object +* from the raw bytes of an ELF's BTF section +* @param data raw bytes +* @param size number of bytes passed in `data` +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new(const void *data, __u32 size); + +/** +* @brief **btf__new_split()** create a new instance of a BTF object from +* the provided raw data bytes. It takes another BTF instance, **base_btf**, +* which serves as a base BTF, which is extended by types in a newly created +* BTF instance +* @param data raw bytes +* @param size length of raw bytes +* @param base_btf the base btf object +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_split(const void *data, __u32 size, struct btf *base_btf); + +/** +* @brief **btf__new_empty()** creates an unpopulated BTF object +* Use `btf__add_*()` to populate such BTF object. +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_empty(void);
tools/lib/bpf/btf.h enum btf_endianness { · line 97
Quoted 10 lines
tools/lib/bpf/btf.h +10
-0+ +/** +* @brief **btf__new_empty_split()** creates an unpopulated +* BTF object from an ELF BTF section except with a base BTF +* on top of which split BTF should be based +* @return new instance of BTF object which has to be eventually freed +* with **btf__free()** +* +* If *base_btf* is NULL, `btf__new_empty_split()` is equivalent to +* `btf__new_empty()` and creates non-split BTF.
Added this to btf__new_split() description as well
Quoted 13 lines
tools/lib/bpf/btf.h +7
-1+* +* On error, error-code-encoded-as-pointer is returned, not a NULL. To +* extract error code from such a pointer `libbpf_get_error()` should be +* used. If `libbpf_set_strict_mode(LIBBPF_STRICT_CLEAN_PTRS)` is +* enabled, NULL is returned on error instead. In both cases thread-local +* `errno` variable is always set to error code as well. +*/ LIBBPF_API struct btf *btf__new_empty_split(struct btf *base_btf); LIBBPF_API struct btf *btf__parse(const char *path, struct btf_ext **btf_ext); --2.31.1