9pfs: convert Doxygen -> kerneldoc format
cover 9pfs: convert Doxygen -> kerneldoc format
This patch set converts occurrences of API doc comments from Doxygen format into kerneldoc format. No behaviour change whatsoever.
Christian Schoenebeck (6):
9pfs/9p.h: convert Doxygen -> kerneldoc format 9pfs/codir.c: convert Doxygen -> kerneldoc format 9pfs/9p.c: convert Doxygen -> kerneldoc format 9pfs/9p-util.h: convert Doxygen -> kerneldoc format 9pfs/coth.h: drop Doxygen format on v9fs_co_run_in_worker() fsdev/p9array.h: convert Doxygen -> kerneldoc format
fsdev/p9array.h | 38 ++++++++++++++++------------- hw/9pfs/9p-util.h | 10 ++++---- hw/9pfs/9p.c | 62 ++++++++++++++++++++++++++--------------------- hw/9pfs/9p.h | 12 ++++----- hw/9pfs/codir.c | 30 +++++++++++------------ hw/9pfs/coth.h | 4 +-- 6 files changed, 84 insertions(+), 72 deletions(-)
Signature · 1 line
2.30.2
PATCH 1/6 9pfs/9p.h: convert Doxygen -> kerneldoc format
API doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format.
Based-on: <[email protected]>
--- hw/9pfs/9p.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
hw/9pfs/9p.h +6 -6
@@ -100,8 +100,8 @@ typedef enum P9ProtoVersion { V9FS_PROTO_2000L = 0x02, } P9ProtoVersion; -/** -* @brief Minimum message size supported by this 9pfs server. +/* +* Minimum message size supported by this 9pfs server. * * A client establishes a session by sending a Tversion request along with a * 'msize' parameter which suggests the server a maximum message size ever to be
@@ -231,7 +231,7 @@ static inline void v9fs_readdir_init(P9ProtoVersion proto_version, V9fsDir *dir) } } -/** +/* * Type for 9p fs drivers' (a.k.a. 9p backends) result of readdir requests, * which is a chained list of directory entries. */
@@ -289,8 +289,8 @@ typedef enum AffixType_t { AffixType_Suffix, /* A.k.a. postfix. */ } AffixType_t; -/** -* @brief Unique affix of variable length. +/* +* Unique affix of variable length. * * An affix is (currently) either a suffix or a prefix, which is either * going to be prepended (prefix) or appended (suffix) with some other
@@ -304,7 +304,7 @@ typedef struct VariLenAffix {AffixType_t type;/* Whether this affix is a suffix or a prefix. */ uint64_t value;/* Actual numerical value of this affix. */ /* -* Lenght of the affix, that is how many (of the lowest) bits of @c value +* Lenght of the affix, that is how many (of the lowest) bits of ``value`` * must be used for appending/prepending this affix to its final resulting, * unique number. */
Signature · 1 line
2.30.2
PATCH 2/6 9pfs/codir.c: convert Doxygen -> kerneldoc format
In reply to Christian SchoenebeckAPI doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format.
--- hw/9pfs/codir.c | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-)
hw/9pfs/codir.c +15 -15
@@ -184,14 +184,25 @@ out: }/** -* @brief Reads multiple directory entries in one rush. +* v9fs_co_readdir_many() - Reads multiple directory entries in one rush. +* +* @pdu: the causing 9p (T_readdir) client request +* @fidp: already opened directory where readdir shall be performed on +* @entries: output for directory entries (must not be NULL) +* @offset: initial position inside the directory the function shall +* seek to before retrieving the directory entries +* @maxsize: maximum result message body size (in bytes) +* @dostat: whether a stat() should be performed and returned for +* each directory entry +* Return: resulting response message body size (in bytes) on success, +* negative error code otherwise * * Retrieves the requested (max. amount of) directory entries from the fs * driver. This function must only be called by the main IO thread (top half). * Internally this function call will be dispatched to a background IO thread * (bottom half) where it is eventually executed by the fs driver. * -* @discussion Acquiring multiple directory entries in one rush from the fs +* Acquiring multiple directory entries in one rush from the fs * driver, instead of retrieving each directory entry individually, is very * beneficial from performance point of view. Because for every fs driver * request latency is added, which in practice could lead to overall
@@ -199,20 +210,9 @@ out:* directory) if every directory entry was individually requested from fs * driver. * -* @note You must @b ALWAYS call @c v9fs_free_dirents(entries) after calling +* NOTE: You must ALWAYS call v9fs_free_dirents(entries) after calling * v9fs_co_readdir_many(), both on success and on error cases of this -* function, to avoid memory leaks once @p entries are no longer needed. -* -* @param pdu - the causing 9p (T_readdir) client request -* @param fidp - already opened directory where readdir shall be performed on -* @param entries - output for directory entries (must not be NULL) -* @param offset - initial position inside the directory the function shall -* seek to before retrieving the directory entries -* @param maxsize - maximum result message body size (in bytes) -* @param dostat - whether a stat() should be performed and returned for -* each directory entry -* @returns resulting response message body size (in bytes) on success, -* negative error code otherwise +* function, to avoid memory leaks once @entries are no longer needed. */ int coroutine_fn v9fs_co_readdir_many(V9fsPDU *pdu, V9fsFidState *fidp, struct V9fsDirEnt **entries,
Signature · 1 line
2.30.2
PATCH 3/6 9pfs/9p.c: convert Doxygen -> kerneldoc format
In reply to Christian SchoenebeckAPI doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format.
--- hw/9pfs/9p.c | 62 +++++++++++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 27 deletions(-)
hw/9pfs/9p.c +35 -27
@@ -628,8 +628,8 @@ static inline uint64_t mirror64bit(uint64_t value) ((uint64_t )mirror8bit ((value >>56 ) &0xff )); } -/** -* @brief Parameter k for the Exponential Golomb algorihm to be used. +/* +* Parameter k for the Exponential Golomb algorihm to be used. * * The smaller this value, the smaller the minimum bit count for the Exp. * Golomb generated affixes will be (at lowest index) however for the
@@ -642,28 +642,30 @@ static inline uint64_t mirror64bit(uint64_t value)* should be small, for a large amount of devices k might be increased * instead. The default of k=0 should be fine for most users though. * -* @b IMPORTANT: In case this ever becomes a runtime parameter; the value of +* IMPORTANT: In case this ever becomes a runtime parameter; the value of * k should not change as long as guest is still running! Because that would * cause completely different inode numbers to be generated on guest. */ #define EXP_GOLOMB_K 0/** -* @brief Exponential Golomb algorithm for arbitrary k (including k=0). +* expGolombEncode() - Exponential Golomb algorithm for arbitrary k +* (including k=0). * -* The Exponential Golomb algorithm generates @b prefixes (@b not suffixes!) +* @n: natural number (or index) of the prefix to be generated +* (1, 2, 3, ...) +* @k: parameter k of Exp. Golomb algorithm to be used +* (see comment on EXP_GOLOMB_K macro for details about k) +* Return: prefix for given @n and @k +* +* The Exponential Golomb algorithm generates prefixes (NOT suffixes!) * with growing length and with the mathematical property of being * "prefix-free". The latter means the generated prefixes can be prepended * in front of arbitrary numbers and the resulting concatenated numbers are * guaranteed to be always unique. * * This is a minor adjustment to the original Exp. Golomb algorithm in the -* sense that lowest allowed index (@param n) starts with 1, not with zero. -* -* @param n - natural number (or index) of the prefix to be generated -* (1, 2, 3, ...) -* @param k - parameter k of Exp. Golomb algorithm to be used -* (see comment on EXP_GOLOMB_K macro for details about k) +* sense that lowest allowed index (@n) starts with 1, not with zero. */ static VariLenAffix expGolombEncode (uint64_t n,int k) {
@@ -677,7 +679,9 @@ static VariLenAffix expGolombEncode(uint64_t n, int k) }/** -* @brief Converts a suffix into a prefix, or a prefix into a suffix. +* invertAffix() - Converts a suffix into a prefix, or a prefix into a suffix. +* @affix: either suffix or prefix to be inverted +* Return: inversion of passed @affix * * Simply mirror all bits of the affix value, for the purpose to preserve * respectively the mathematical "prefix-free" or "suffix-free" property
@@ -701,16 +705,16 @@ static VariLenAffix invertAffix(const VariLenAffix *affix) }/** -* @brief Generates suffix numbers with "suffix-free" property. +* affixForIndex() - Generates suffix numbers with "suffix-free" property. +* @index: natural number (or index) of the suffix to be generated +* (1, 2, 3, ...) +* Return: Suffix suitable to assemble unique number. * * This is just a wrapper function on top of the Exp. Golomb algorithm. * * Since the Exp. Golomb algorithm generates prefixes, but we need suffixes, * this function converts the Exp. Golomb prefixes into appropriate suffixes * which are still suitable for generating unique numbers. -* -* @param n - natural number (or index) of the suffix to be generated -* (1, 2, 3, ...) */ static VariLenAffix affixForIndex (uint64_t index) {
@@ -810,8 +814,8 @@ static int qid_inode_prefix_hash_bits(V9fsPDU *pdu, dev_t dev)return val->prefix_bits; } -/** -* @brief Slow / full mapping host inode nr -> guest inode nr. +/* +* Slow / full mapping host inode nr -> guest inode nr. * * This function performs a slower and much more costly remapping of an * original file inode number on host to an appropriate different inode
@@ -823,7 +827,7 @@ static int qid_inode_prefix_hash_bits(V9fsPDU *pdu, dev_t dev)* qid_path_suffixmap() failed. In practice this slow / full mapping is not * expected ever to be used at all though. * -* @see qid_path_suffixmap() for details +* See qid_path_suffixmap() for details * */ static int qid_path_fullmap(V9fsPDU *pdu, const struct stat *stbuf,
@@ -864,8 +868,8 @@ static int qid_path_fullmap(V9fsPDU *pdu, const struct stat *stbuf,return 0 ; } -/** -* @brief Quick mapping host inode nr -> guest inode nr. +/* +* Quick mapping host inode nr -> guest inode nr. * * This function performs quick remapping of an original file inode number * on host to an appropriate different inode number on guest. This remapping
@@ -1281,12 +1285,15 @@ static int coroutine_fn stat_to_v9stat(V9fsPDU *pdu, V9fsPath *path,/** -* Convert host filesystem's block size into an appropriate block size for -* 9p client (guest OS side). The value returned suggests an "optimum" block -* size for 9p I/O, i.e. to maximize performance. +* blksize_to_iounit() - Block size exposed to 9p client. +* Return: block size * * @pdu: 9p client request * @blksize: host filesystem's block size +* +* Convert host filesystem's block size into an appropriate block size for +* 9p client (guest OS side). The value returned suggests an "optimum" block +* size for 9p I/O, i.e. to maximize performance. */ static int32_t blksize_to_iounit (const V9fsPDU *pdu,int32_t blksize) {
@@ -2398,10 +2405,11 @@ out_nofid: }/** -* Returns size required in Rreaddir response for the passed dirent @p name. +* v9fs_readdir_response_size() - Returns size required in Rreaddir response +* for the passed dirent @name. * -* @param name - directory entry's name (i.e. file name, directory name) -* @returns required size in bytes +* @name: directory entry's name (i.e. file name, directory name) +* Return: required size in bytes */ size_t v9fs_readdir_response_size (V9fsString *name) {
Signature · 1 line
2.30.2
PATCH 4/6 9pfs/9p-util.h: convert Doxygen -> kerneldoc format
In reply to Christian SchoenebeckAPI doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format.
--- hw/9pfs/9p-util.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
hw/9pfs/9p-util.h +5 -5
@@ -97,7 +97,7 @@ ssize_t flistxattrat_nofollow(int dirfd, const char *filename,ssize_t fremovexattrat_nofollow (int dirfd,const char *filename,const char *name); -/** +/* * Darwin has d_seekoff, which appears to function similarly to d_off. * However, it does not appear to be supported on all file systems, * so ensure it is manually injected earlier and call here when
@@ -113,15 +113,15 @@ static inline off_t qemu_dirent_off(struct dirent *dent) }/** -* Duplicate directory entry @dent. +* qemu_dirent_dup() - Duplicate directory entry @dent. +* +* @dent: original directory entry to be duplicated +* Return: duplicated directory entry which should be freed with g_free() * * It is highly recommended to use this function instead of open coding * duplication of dirent objects, because the actual struct dirent * size may be bigger or shorter than sizeof(struct dirent) and correct * handling is platform specific (see gitlab issue #841). -* -* @dent - original directory entry to be duplicated -* @returns duplicated directory entry which should be freed with g_free() */ static inline struct dirent *qemu_dirent_dup (struct dirent *dent) {
Signature · 1 line
2.30.2
PATCH 5/6 9pfs/coth.h: drop Doxygen format on v9fs_co_run_in_worker()
In reply to Christian SchoenebeckAPI doc comments in QEMU are supposed to be in kerneldoc format, so drop Doxygen format used on v9fs_co_run_in_worker() macro.
--- hw/9pfs/coth.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
hw/9pfs/coth.h +2 -2
@@ -19,7 +19,7 @@#include "qemu/coroutine.h" #include "9p.h" -/** +/* * we want to use bottom half because we want to make sure the below * sequence of events. *
@@ -29,7 +29,7 @@* we cannot swap step 1 and 2, because that would imply worker thread * can enter coroutine while step1 is still running * -* @b PERFORMANCE @b CONSIDERATIONS: As a rule of thumb, keep in mind +* PERFORMANCE CONSIDERATIONS: As a rule of thumb, keep in mind * that hopping between threads adds @b latency! So when handling a * 9pfs request, avoid calling v9fs_co_run_in_worker() too often, because * this might otherwise sum up to a significant, huge overall latency for
Signature · 1 line
2.30.2
PATCH 6/6 fsdev/p9array.h: convert Doxygen -> kerneldoc format
In reply to Christian SchoenebeckAPI doc comments in QEMU are supposed to be in kerneldoc format, so convert API doc comments from Doxygen format to kerneldoc format.
--- fsdev/p9array.h | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-)
fsdev/p9array.h +21 -17
@@ -81,11 +81,11 @@*/ /** -* Declares an array type for the passed @a scalar_type. +* P9ARRAY_DECLARE_TYPE() - Declares an array type for the passed @scalar_type. * -* This is typically used from a shared header file. +* @scalar_type: type of the individual array elements * -* @param scalar_type - type of the individual array elements +* This is typically used from a shared header file. */ #define P9ARRAY_DECLARE_TYPE (scalar_type) \ typedef struct P9Array##scalar_type { \
@@ -97,14 +97,14 @@ void p9array_auto_free_##scalar_type(scalar_type **auto_var); \/** -* Defines an array type for the passed @a scalar_type and appropriate -* @a scalar_cleanup_func. +* P9ARRAY_DEFINE_TYPE() - Defines an array type for the passed @scalar_type +* and appropriate @scalar_cleanup_func. * -* This is typically used from a C unit file. +* @scalar_type: type of the individual array elements +* @scalar_cleanup_func: appropriate function to free memory dynamically +* allocated by individual array elements before * -* @param scalar_type - type of the individual array elements -* @param scalar_cleanup_func - appropriate function to free memory dynamically -* allocated by individual array elements before +* This is typically used from a C unit file. */ #define P9ARRAY_DEFINE_TYPE (scalar_type, scalar_cleanup_func) \ void p9array_new_##scalar_type(scalar_type **auto_var, size_t len) \
@@ -132,23 +132,27 @@ } \/** +* P9ARRAY_REF() - Declare a reference variable for an array. +* +* @scalar_type: type of the individual array elements +* * Used to declare a reference variable (unique pointer) for an array. After * leaving the scope of the reference variable, the associated array is * automatically freed. -* -* @param scalar_type - type of the individual array elements */ #define P9ARRAY_REF (scalar_type) \ __attribute((__cleanup__(p9array_auto_free_##scalar_type))) scalar_type*/** -* Allocates a new array of passed @a scalar_type with @a len number of array -* elements and assigns the created array to the reference variable -* @a auto_var. +* P9ARRAY_NEW() - Allocate a new array. * -* @param scalar_type - type of the individual array elements -* @param auto_var - destination reference variable -* @param len - amount of array elements to be allocated immediately +* @scalar_type: type of the individual array elements +* @auto_var: destination reference variable +* @len: amount of array elements to be allocated immediately +* +* Allocates a new array of passed @scalar_type with @len number of array +* elements and assigns the created array to the reference variable +* @auto_var. */ #define P9ARRAY_NEW (scalar_type, auto_var, len) \ QEMU_BUILD_BUG_MSG( \
Signature · 1 line
2.30.2
Quoted 11 lines · On Thu, 3 Mar 2022 14:40:56 +0100 Christian Schoenebeck…
This patch set converts occurrences of API doc comments from Doxygen format into kerneldoc format. No behaviour change whatsoever.
Christian Schoenebeck (6):
9pfs/9p.h: convert Doxygen -> kerneldoc format9pfs/codir.c: convert Doxygen -> kerneldoc format9pfs/9p.c: convert Doxygen -> kerneldoc format9pfs/9p-util.h: convert Doxygen -> kerneldoc format9pfs/coth.h: drop Doxygen format onv9fs_co_run_in_worker()fsdev/p9array.h: convert Doxygen -> kerneldoc format
Quoted 8 lines
fsdev/p9array.h | 38 ++++++++++++++++------------- hw/9pfs/9p-util.h | 10 ++++---- hw/9pfs/9p.c | 62 ++++++++++++++++++++++++++--------------------- hw/9pfs/9p.h | 12 ++++----- hw/9pfs/codir.c | 30 +++++++++++------------ hw/9pfs/coth.h | 4 +-- 6 files changed, 84 insertions(+), 72 deletions(-)
LGTM.
Quoted 23 lines · On Freitag, 4. März 2022 08:39:36 CET Greg Kurz wrote:
On Thu, 3 Mar 2022 14:40:56 +0100
Quoted 12 lines · Christian Schoenebeck
This patch set converts occurrences of API doc comments from Doxygen format
into kerneldoc format. No behaviour change whatsoever.Christian Schoenebeck (6):
9pfs/9p.h: convert Doxygen -> kerneldoc format9pfs/codir.c: convert Doxygen -> kerneldoc format9pfs/9p.c: convert Doxygen -> kerneldoc format9pfs/9p-util.h: convert Doxygen -> kerneldoc format9pfs/coth.h: drop Doxygen format onv9fs_co_run_in_worker()fsdev/p9array.h: convert Doxygen -> kerneldoc formatQuoted 7 lines
fsdev/p9array.h | 38 ++++++++++++++++------------- hw/9pfs/9p-util.h | 10 ++++---- hw/9pfs/9p.c | 62 ++++++++++++++++++++++++++--------------------- hw/9pfs/9p.h | 12 ++++----- hw/9pfs/codir.c | 30 +++++++++++------------ hw/9pfs/coth.h | 4 +-- 6 files changed, 84 insertions(+), 72 deletions(-)
Quoted 3 lines
LGTM.
Reviewed-by Greg Kurz <[email protected]>
Great, then I can take this into today's PR as well.
Thanks!
Best regards,
Christian Schoenebeck