From bf056d4a5bd0a6637af9fa5b638d64f68fa528b9 Mon Sep 17 00:00:00 2001 From: Arshad Hussain Date: Sun, 30 Mar 2025 19:31:03 +0530 Subject: [PATCH] LU-9633 lod: Add kernel doc style for lod (Part 4) This patch converts existing functional comments to kernel doc style comments and removes '/**' for comments which is not meant to be a kernel-doc comment Test-Parameters: trivial Signed-off-by: Arshad Hussain Change-Id: I962a4a5eb33ea5b363dff21d2302df3ab584d012 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58602 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Anjus George Reviewed-by: Andreas Dilger Reviewed-by: Petros Koutoupis Reviewed-by: James Simmons Reviewed-by: Oleg Drokin --- lustre/lod/lod_qos.c | 352 ++++++++++++++++++++++++++------------------------- 1 file changed, 180 insertions(+), 172 deletions(-) diff --git a/lustre/lod/lod_qos.c b/lustre/lod/lod_qos.c index f407131..230ae32 100644 --- a/lustre/lod/lod_qos.c +++ b/lustre/lod/lod_qos.c @@ -50,7 +50,12 @@ static inline int lod_statfs_check(struct lu_tgt_descs *ltd, } /** - * Check whether the target is available for new objects. + * lod_statfs_and_check() - Check whether target is available for new objects. + * @env: execution environment for this thread + * @d: LOD device + * @ltd: target table + * @tgt: target + * @reserve: space to reserve on target device * * Request statfs data from the given target and verify it's active and not * read-only. If so, then it can be used to place new objects. This @@ -58,13 +63,9 @@ static inline int lod_statfs_check(struct lu_tgt_descs *ltd, * dirty flags if those numbers change so others can run re-balance procedures. * No external locking is required. * - * \param[in] env execution environment for this thread - * \param[in] d LOD device - * \param[in] ltd target table - * \param[in] tgt target - * - * \retval 0 if the target is good - * \retval negative negated errno on error + * Return: + * * %0 if the target is good + * * %negative negated errno on error */ static int lod_statfs_and_check(const struct lu_env *env, struct lod_device *d, struct lu_tgt_descs *ltd, @@ -136,15 +137,14 @@ static int lod_statfs_and_check(const struct lu_env *env, struct lod_device *d, } /** - * Maintain per-target statfs data. + * lod_qos_statfs_update() - Maintain per-target statfs data. + * @env: execution environment for this thread + * @lod: LOD device + * @ltd: tgt table * * The function refreshes statfs data for all the targets every N seconds. * The actual N is controlled via procfs and set to LOV_DESC_QOS_MAXAGE_DEFAULT * initially. - * - * \param[in] env execution environment for this thread - * \param[in] lod LOD device - * \param[in] ltd tgt table */ void lod_qos_statfs_update(const struct lu_env *env, struct lod_device *lod, struct lu_tgt_descs *ltd) @@ -189,21 +189,21 @@ void lod_qos_statfs_update(const struct lu_env *env, struct lod_device *lod, #define LOV_QOS_EMPTY ((__u32)-1) /** - * Calculate optimal round-robin order with regard to OSSes. + * lod_qos_calc_rr() - Calculate optimal round-robin order with regard to OSSes + * @lod: LOD device + * @ltd: tgt table + * @src_pool: tgt pool + * @lqr: round-robin list * - * Place all the OSTs from pool \a src_pool in a special array to be used for + * Place all the OSTs from pool @src_pool in a special array to be used for * round-robin (RR) stripe allocation. The placement algorithm interleaves * OSTs from the different OSSs so that RR allocation can balance OSSs evenly. * Resorts the targets when the number of active targets changes (because of * a new target or activation/deactivation). * - * \param[in] lod LOD device - * \param[in] ltd tgt table - * \param[in] src_pool tgt pool - * \param[in] lqr round-robin list - * - * \retval 0 on success - * \retval -ENOMEM fails to allocate the array + * Return: + * * %0 on success + * * %-ENOMEM fails to allocate the array */ static int lod_qos_calc_rr(struct lod_device *lod, struct lu_tgt_descs *ltd, const struct lu_tgt_pool *src_pool, @@ -296,7 +296,12 @@ static int lod_qos_calc_rr(struct lod_device *lod, struct lu_tgt_descs *ltd, } /** - * Instantiate and declare creation of a new object. + * lod_qos_declare_object_on() - Instantiate & declare creation of a new object. + * @env: execution environment for this thread + * @d: LOD device + * @ost_idx: OST target index where the object is being created + * @can_block: operation blockable or not + * @th: transaction handle * * The function instantiates LU representation for a new object on the * specified device. Also it declares an intention to create that @@ -308,12 +313,7 @@ static int lod_qos_calc_rr(struct lod_device *lod, struct lu_tgt_descs *ltd, * special method instantiates FID-less object in the cache and later it * will get a FID and proper placement in LU cache. * - * \param[in] env execution environment for this thread - * \param[in] d LOD device - * \param[in] ost_idx OST target index where the object is being created - * \param[in] th transaction handle - * - * \retval object ptr on success, ERR_PTR() otherwise + * Return object ptr on success, ERR_PTR() otherwise */ static struct dt_object *lod_qos_declare_object_on(const struct lu_env *env, struct lod_device *d, @@ -369,16 +369,15 @@ out: } /** - * Calculate a minimum acceptable stripe count. + * lod_stripe_count_min() - Calculate a minimum acceptable stripe count. + * @stripe_count: number of stripes requested + * @flags: 0 or LOD_USES_DEFAULT_STRIPE * * Return an acceptable stripe count depending on flag LOD_USES_DEFAULT_STRIPE: * all stripes or 3/4 of stripes. The code is written this way to avoid * returning 0 for stripe_count < 4, like "stripe_count * 3 / 4" would do. * - * \param[in] stripe_count number of stripes requested - * \param[in] flags 0 or LOD_USES_DEFAULT_STRIPE - * - * \retval acceptable stripecount + * Returns acceptable stripecount */ static int lod_stripe_count_min(__u32 stripe_count, enum lod_uses_hint flags) { @@ -390,16 +389,16 @@ static int lod_stripe_count_min(__u32 stripe_count, enum lod_uses_hint flags) #define LOV_CREATE_RESEED_MIN 2000 /** - * Initialize temporary tgt-in-use array. + * lod_qos_tgt_in_use_clear() - Initialize temporary tgt-in-use array. + * @env: execution environment for this thread + * @stripes: number of items needed in the array * * Allocate or extend the array used to mark targets already assigned to a new * striping so they are not used more than once. * - * \param[in] env execution environment for this thread - * \param[in] stripes number of items needed in the array - * - * \retval 0 on success - * \retval -ENOMEM on error + * Return: + * * %0 on success + * * %-ENOMEM on error */ static inline int lod_qos_tgt_in_use_clear(const struct lu_env *env, __u32 stripes) @@ -417,14 +416,13 @@ static inline int lod_qos_tgt_in_use_clear(const struct lu_env *env, } /** - * Remember a target in the array of used targets. + * lod_qos_tgt_in_use() - Remember a target in the array of used targets. + * @env: execution environment for this thread + * @idx: index in the array + * @tgt_idx: target index to mark as used * * Mark the given target as used for a new striping being created. The status * of an tgt in a striping can be checked with lod_qos_is_tgt_used(). - * - * \param[in] env execution environment for this thread - * \param[in] idx index in the array - * \param[in] tgt_idx target index to mark as used */ static inline void lod_qos_tgt_in_use(const struct lu_env *env, int idx, int tgt_idx) @@ -437,17 +435,17 @@ static inline void lod_qos_tgt_in_use(const struct lu_env *env, } /** - * Check is tgt used in a striping. + * lod_qos_is_tgt_used() - Check is tgt used in a striping. + * @env: execution environment for this thread + * @tgt_idx: target index to check + * @stripes: the number of items used in the array already * * Checks whether tgt with the given index is marked as used in the temporary * array (see lod_qos_tgt_in_use()). * - * \param[in] env execution environment for this thread - * \param[in] tgt_idx target index to check - * \param[in] stripes the number of items used in the array already - * - * \retval 0 not used - * \retval 1 used + * Return: + * * %0 not used + * * %1 used */ static int lod_qos_is_tgt_used(const struct lu_env *env, int tgt_idx, __u32 stripes) @@ -490,13 +488,14 @@ lod_obj_is_ost_use_cb(const struct lu_env *env, struct lod_object *lo, } /** - * Check is OST used in a composite layout - * - * \param[in] lo lod object - * \param[in] ost OST target index to check - * - * \retval false not used - * \retval true used + * lod_comp_is_ost_used() - Check is OST used in a composite layout + * @env: execution environment + * @lo: lod object + * @ost: OST target index to check + * + * Return: + * * %false not used + * * %true used */ static inline bool lod_comp_is_ost_used(const struct lu_env *env, struct lod_object *lo, int ost) @@ -658,7 +657,15 @@ static int lod_check_and_reserve_ost(const struct lu_env *env, } /** - * Allocate a striping using round-robin algorithm. + * lod_ost_alloc_rr() - Allocate a striping using round-robin algorithm. + * @env: execution environment for this thread + * @lo: LOD object + * @stripe: striping created [out] + * @ost_indices: ost indices of striping created [out] + * @flags: allocation flags (0 or LOD_USES_DEFAULT_STRIPE) + * @th: transaction handle + * @comp_idx: index of ldo_comp_entries + * @reserve: space to reserve on the target device * * Allocates a new striping using round-robin algorithm. The function refreshes * all the internal structures (statfs cache, array of available OSTs sorted @@ -671,17 +678,10 @@ static int lod_check_and_reserve_ost(const struct lu_env *env, * time we give priority to targets which already have objects precreated. * Full OSTs are skipped (see lod_qos_dev_is_full() for the details). * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[out] stripe striping created - * \param[out] ost_indices ost indices of striping created - * \param[in] flags allocation flags (0 or LOD_USES_DEFAULT_STRIPE) - * \param[in] th transaction handle - * \param[in] comp_idx index of ldo_comp_entries - * - * \retval 0 on success - * \retval -ENOSPC if not enough OSTs are found - * \retval negative negated errno for other failures + * Return: + * * %0 on success + * * %-ENOSPC if not enough OSTs are found + * * %negative negated errno for other failures */ static int lod_ost_alloc_rr(const struct lu_env *env, struct lod_object *lo, struct dt_object **stripe, __u32 *ost_indices, @@ -872,7 +872,12 @@ lod_qos_mdt_in_use_init(const struct lu_env *env, } /** - * Allocate a striping using round-robin algorithm. + * lod_mdt_alloc_rr() - Allocate a striping using round-robin algorithm. + * @env: execution environment for this thread + * @lo: LOD object + * @stripes: striping created + * @stripe_idx: starting index of stripe allocation + * @stripe_count: Number of stripe objects needed * * Allocates a new striping using round-robin algorithm. The function refreshes * all the internal structures (statfs cache, array of available remote MDTs @@ -882,14 +887,11 @@ lod_qos_mdt_in_use_init(const struct lu_env *env, * internal structures (like pools, etc) are protected and no additional locking * is required. The function succeeds even if a single stripe is allocated. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[out] stripes striping created - * - * \retval positive stripe objects allocated, including the first stripe - * allocated outside - * \retval -ENOSPC if not enough MDTs are found - * \retval negative negated errno for other failures + * Return: + * * %positive stripe objects allocated, including first stripe allocated + * outside the function + * * %-ENOSPC if not enough MDTs are found + * * %negative negated errno for other failures */ int lod_mdt_alloc_rr(const struct lu_env *env, struct lod_object *lo, struct dt_object **stripes, u32 stripe_idx, @@ -1094,7 +1096,15 @@ repeat_find: } /** - * Allocate a specific striping layout on a user defined set of OSTs. + * lod_alloc_ost_list() - Allocate a specific striping layout on a user defined + * set of OSTs. + * @env: execution environment for this thread + * @lo: LOD object + * @stripe: striping created [out] + * @ost_indices: ost indices of striping created [out] + * @th: transaction handle + * @comp_idx: index of ldo_comp_entries + * @reserve: space to reserve on the target device * * Allocates new striping using the OST index range provided by the data from * the lmm_objects contained in the lov_user_md passed to this method. Full @@ -1106,17 +1116,11 @@ repeat_find: * structures are protected, but no concurrent allocation is allowed on the * same objects. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[out] stripe striping created - * \param[out] ost_indices ost indices of striping created - * \param[in] th transaction handle - * \param[in] comp_idx index of ldo_comp_entries - * - * \retval 0 on success - * \retval -ENODEV OST index does not exist on file system - * \retval -EINVAL requested OST index is invalid - * \retval negative negated errno on error + * Return: + * * %0 on success + * * %-ENODEV OST index does not exist on file system + * * %-EINVAL requested OST index is invalid + * * %negative negated errno on error */ static int lod_alloc_ost_list(const struct lu_env *env, struct lod_object *lo, struct dt_object **stripe, __u32 *ost_indices, @@ -1205,7 +1209,15 @@ static int lod_alloc_ost_list(const struct lu_env *env, struct lod_object *lo, } /** - * Allocate a striping on a predefined set of OSTs. + * lod_ost_alloc_specific() - Allocate a striping on a predefined set of OSTs. + * @env: execution environment for this thread + * @lo: LOD object + * @stripe: striping created [out] + * @ost_indices: ost indices of striping created [out] + * @flags: not used + * @th: transaction handle + * @comp_idx: index of ldo_comp_entries + * @reserve: space to reserve on the target device * * Allocates new layout starting from OST index in lo->ldo_stripe_offset. * Full OSTs are not considered. The exact order of OSTs is not important and @@ -1216,19 +1228,12 @@ static int lod_alloc_ost_list(const struct lu_env *env, struct lod_object *lo, * release the stripes allocated. All the internal structures are protected, * but no concurrent allocation is allowed on the same objects. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[out] stripe striping created - * \param[out] ost_indices ost indices of striping created - * \param[in] flags not used - * \param[in] th transaction handle - * \param[in] comp_idx index of ldo_comp_entries - * - * \retval 0 on success - * \retval -ENOSPC if no OST objects are available at all - * \retval -EFBIG if not enough OST objects are found - * \retval -EINVAL requested offset is invalid - * \retval negative errno on failure + * Return: + * * %0 on success + * * %-ENOSPC if no OST objects are available at all + * * %-EFBIG if not enough OST objects are found + * * %-EINVAL requested offset is invalid + * * %negative errno on failure */ static int lod_ost_alloc_specific(const struct lu_env *env, struct lod_object *lo, @@ -1411,17 +1416,17 @@ static void process_semaphore_timer(struct timer_list *t) #endif /** - * Calculate penalties per-ost in a pool + * lod_pool_qos_penalties_calc() - Calculate penalties per-ost in a pool + * @lod: lod_device + * @pool: pool_desc * * The algorithm is similar to ltd_qos_penalties_calc(), but much simpler, * just considering the space of each OST in this pool. * - * \param[in] lod lod_device - * \param[in] pool pool_desc - * - * \retval 0 on success - * \retval -EAGAIN the number of OSTs isn't enough or all tgt spaces are - * almost the same + * Return: + * * %0 on success + * * %-EAGAIN the number of OSTs isn't enough or all tgt spaces are almost the + * same */ static int lod_pool_qos_penalties_calc(struct lod_device *lod, struct lod_pool_desc *pool) @@ -1505,7 +1510,15 @@ out: } /** - * Allocate a striping using an algorithm with weights. + * lod_ost_alloc_qos() - Allocate a striping using an algorithm with weights. + * @env: execution environment for this thread + * @lo: LOD object + * @stripe: striping created + * @ost_indices: ost indices of striping created + * @flags: 0 or LOD_USES_DEFAULT_STRIPE + * @th: transaction handle + * @comp_idx: index of ldo_comp_entries + * @reserve: space to reserve on the target device * * The function allocates OST objects to create a striping. The algorithm * used is based on weights (currently only using the free space), and it's @@ -1526,18 +1539,11 @@ out: * An OST with a higher weight is proportionately more likely to be selected * than one with a lower weight. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[out] stripe striping created - * \param[out] ost_indices ost indices of striping created - * \param[in] flags 0 or LOD_USES_DEFAULT_STRIPE - * \param[in] th transaction handle - * \param[in] comp_idx index of ldo_comp_entries - * - * \retval 0 on success - * \retval -EAGAIN not enough OSTs are found for specified stripe count - * \retval -EINVAL requested OST index is invalid - * \retval negative errno on failure + * Return: + * * %0 on success + * * %-EAGAIN not enough OSTs are found for specified stripe count + * * %-EINVAL requested OST index is invalid + * * %negative errno on failure */ static int lod_ost_alloc_qos(const struct lu_env *env, struct lod_object *lo, struct dt_object **stripe, __u32 *ost_indices, @@ -1801,7 +1807,13 @@ out_nolock: } /** - * Allocate a striping using an algorithm with weights. + * lod_mdt_alloc_qos() - Allocate a striping using an algorithm with weights. + * @env: execution environment for this thread + * @lo: LOD object + * @stripe_idx: starting stripe index to allocate, if it's not 0, + * we are restriping directory + * @stripe_count: total stripe count + * @stripes: striping created * * The function allocates remote MDT objects to create a striping, the first * object was already allocated on current MDT to ensure master object and @@ -1821,18 +1833,12 @@ out_nolock: * An MDT with a higher weight is proportionately more likely to be selected * than one with a lower weight. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[in] stripe_idx starting stripe index to allocate, if it's not - * 0, we are restriping directory - * \param[in] stripe_count total stripe count - * \param[out] stripes striping created - * - * \retval positive stripes allocated, and it should be equal to - * lo->ldo_dir_stripe_count - * \retval -EAGAIN not enough tgts are found for specified stripe count - * \retval -EINVAL requested MDT index is invalid - * \retval negative errno on failure + * Return: + * * %positive stripes allocated, and it should be equal to + * lo->ldo_dir_stripe_count + * * %-EAGAIN not enough tgts are found for specified stripe count + * * %-EINVAL requested MDT index is invalid + * * %negative errno on failure */ int lod_mdt_alloc_qos(const struct lu_env *env, struct lod_object *lo, struct dt_object **stripes, u32 stripe_idx, @@ -2025,7 +2031,13 @@ unlock: } /** - * Check stripe count the caller can use. + * lod_get_stripe_count_plain() - Check stripe count the caller can use. + * @lod: LOD device + * @lo: The lod_object + * @stripe_count: count the caller would like to use + * @overstriping: if overstriping is allowed (overstriping is allowing more + * stripes than available target) + * @flags: Indicates if user specifed stripe count is to be used for default * * For new layouts (no initialized components), check the total size of the * layout against the maximum EA size from the backing file system. This @@ -2035,13 +2047,7 @@ unlock: * Find the maximal possible stripe count not greater than \a stripe_count. * If the provided stripe count is 0, then the filesystem's default is used. * - * \param[in] lod LOD device - * \param[in] lo The lod_object - * \param[in] comp_idx The component id, which the amount of stripes is - calculated for - * \param[in] stripe_count count the caller would like to use - * - * \retval the maximum usable stripe count + * Returns the maximum usable stripe count */ __u16 lod_get_stripe_count_plain(struct lod_device *lod, struct lod_object *lo, __u16 stripe_count, bool overstriping, @@ -2136,19 +2142,20 @@ __u16 lod_get_stripe_count(struct lod_device *lod, struct lod_object *lo, } /** - * Create in-core respresentation for a fully-defined striping + * lod_use_defined_striping() - Create in-core respresentation for a + * fully-defined striping + * @env: execution environment for this thread + * @mo: LOD object + * @buf: buffer containing the striping * * When the caller passes a fully-defined striping (i.e. everything including * OST object FIDs are defined), then we still need to instantiate LU-cache * with the objects representing the stripes defined. This function completes * that task. * - * \param[in] env execution environment for this thread - * \param[in] mo LOD object - * \param[in] buf buffer containing the striping - * - * \retval 0 on success - * \retval negative negated errno on error + * Return: + * * %0 on success + * * %negative negated errno on error */ int lod_use_defined_striping(const struct lu_env *env, struct lod_object *mo, @@ -2381,7 +2388,10 @@ void lod_qos_set_pool(struct lod_object *lo, int pos, const char *pool_name) } /** - * Parse suggested striping configuration. + * lod_qos_parse_config() - Parse suggested striping configuration. + * @env: execution environment for this thread + * @lo: LOD object + * @buf: buffer containing the striping * * The caller gets a suggested striping configuration from a number of sources * including per-directory default and applications. Then it needs to verify @@ -2390,12 +2400,9 @@ void lod_qos_set_pool(struct lod_object *lo, int pos, const char *pool_name) * called concurrently against the same object. It's OK to provide a * fully-defined striping. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[in] buf buffer containing the striping - * - * \retval 0 on success - * \retval negative negated errno on error + * Return: + * * %0 on success + * * %negative negated errno on error */ int lod_qos_parse_config(const struct lu_env *env, struct lod_object *lo, const struct lu_buf *buf) @@ -2612,7 +2619,7 @@ free_comp: RETURN(rc); } -/** +/* * prepare enough OST avoidance bitmap space */ static int lod_prepare_avoidance(const struct lu_env *env, @@ -2677,7 +2684,7 @@ static int lod_prepare_avoidance(const struct lu_env *env, return 0; } -/** +/* * Collect information of used OSTs and OSSs in the overlapped components * of other mirrors */ @@ -2754,7 +2761,13 @@ static void lod_collect_avoidance(struct lod_object *lo, } /** - * Create a striping for an object. + * lod_qos_prep_create() - Create a striping for an object. + * @env: execution environment for this thread + * @lo: LOD object + * @attr: attributes OST objects will be declared with + * @th: transaction handle + * @comp_idx: index of ldo_comp_entries + * @reserve: space to reserve on target device * * The function creates a new striping for the object. The function tries QoS * algorithm first unless free space is distributed evenly among OSTs, but @@ -2762,14 +2775,9 @@ static void lod_collect_avoidance(struct lod_object *lo, * serialized). The caller must ensure no concurrent calls to the function * are made against the same object. * - * \param[in] env execution environment for this thread - * \param[in] lo LOD object - * \param[in] attr attributes OST objects will be declared with - * \param[in] th transaction handle - * \param[in] comp_idx index of ldo_comp_entries - * - * \retval 0 on success - * \retval negative negated errno on error + * Return: + * * %0 on success + * * %negative negated errno on error */ int lod_qos_prep_create(const struct lu_env *env, struct lod_object *lo, struct lu_attr *attr, struct thandle *th, -- 1.8.3.1