Skip to contentSkip to conversation

9pfs: convert Doxygen -> kerneldoc format

PATCH In review Christian Schoenebeck 2 participants 9 messages Mar 3, 2022 – Mar 4, 2022

lore
Share & tools
lore
#4 lore raw

PATCH 4/6 9pfs/9p-util.h: convert Doxygen -> kerneldoc format

In reply to Christian Schoenebeck

API 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
index 22835c5f61..cfa7af43c5 100644
@@ -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
#2 lore raw

PATCH 2/6 9pfs/codir.c: convert Doxygen -> kerneldoc format

In reply to Christian Schoenebeck

API 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
index f96d8ac4e6..75148bc985 100644
@@ -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
#1 lore raw

PATCH 1/6 9pfs/9p.h: convert Doxygen -> kerneldoc format

In reply to Christian Schoenebeck

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
index 94b273b3d0..af2635fae9 100644
@@ -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
#5 lore raw

PATCH 5/6 9pfs/coth.h: drop Doxygen format on v9fs_co_run_in_worker()

In reply to Christian Schoenebeck

API 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
index f83c7dda7b..1a1edbdc2a 100644
@@ -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
#3 lore raw

PATCH 3/6 9pfs/9p.c: convert Doxygen -> kerneldoc format

In reply to Christian Schoenebeck

API 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
index 7405352c37..a6d6b3f835 100644
@@ -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
#0 lore raw

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
#6 lore raw

PATCH 6/6 fsdev/p9array.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.

---
 fsdev/p9array.h | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)
fsdev/p9array.h +21 -17
index 6aa25327ca..90e83a7c7b 100644
@@ -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
Reviewed-by on the v1 series
#7 lore raw
In reply to Christian Schoenebeck
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 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

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.

#8 lore raw
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 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

Quoted 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.

Great, then I can take this into today's PR as well.

Thanks!

Best regards,
Christian Schoenebeck