From: Arshad Hussain Date: Fri, 14 Mar 2025 10:28:05 +0000 (+0530) Subject: LU-9633 lmv: Add kernel doc style for lmv/lmv_obd.c X-Git-Tag: 2.16.54~57 X-Git-Url: https://git.whamcloud.com/gitweb?a=commitdiff_plain;h=e5e1e032d38c705a69f437f2a38558ecaf9bda65;p=fs%2Flustre-release.git LU-9633 lmv: Add kernel doc style for lmv/lmv_obd.c 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: I42b80cd0db819f8abc3db6114a8769dd772d2784 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58418 Reviewed-by: Andreas Dilger Reviewed-by: Petros Koutoupis Reviewed-by: James Simmons Reviewed-by: Anjus George Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- diff --git a/lustre/lmv/lmv_obd.c b/lustre/lmv/lmv_obd.c index 939ff17..be272ab 100644 --- a/lustre/lmv/lmv_obd.c +++ b/lustre/lmv/lmv_obd.c @@ -55,11 +55,18 @@ void lmv_activate_target(struct lmv_obd *lmv, struct lmv_tgt_desc *tgt, } /** - * Error codes: + * lmv_set_mdc_active() - set the active state of a Metadata Client (MDC) + * @lmv: pointer to lmv_obd + * @uuid: UUID of the target MDC + * @activate: 1 to activate MDC or 0 to de-activate MDC * - * -EINVAL : UUID can't be found in the LMV's target list - * -ENOTCONN: The UUID is found, but the target connection is bad (!) - * -EBADF : The UUID is found, but the OBD of the wrong type (!) + * Return: + * * %0: Success (MDC was put into activate state) + * * %-ERRNO: Failure + * Error codes: + * -EINVAL : UUID can't be found in the LMV's target list + * -ENOTCONN: UUID is found, but the target connection is bad (!) + * -EBADF : UUID is found, but the OBD of the wrong type (!) */ static int lmv_set_mdc_active(struct lmv_obd *lmv, const struct obd_uuid *uuid, @@ -1869,7 +1876,11 @@ lmv_locate_tgt_by_name(struct lmv_obd *lmv, struct lmv_stripe_object *lso, } /** - * Locate MDT of op_data->op_fid1 + * lmv_locate_tgt() - Locate MDT of op_data->op_fid1 + * @lmv: LMV device + * @op_data: client MD stack parameters, name, namelen etc, + * op_mds and op_fid1 will be updated if op_lso1 indicates + * fid1 represents a striped directory. * * For striped directory, it will locate the stripe by name hash, if hash_type * is unknown, it will return the stripe specified by 'op_data->op_stripe_index' @@ -1878,13 +1889,8 @@ lmv_locate_tgt_by_name(struct lmv_obd *lmv, struct lmv_stripe_object *lso, * * For plain directory, it just locate the MDT of op_data->op_fid1. * - * \param[in] lmv LMV device - * \param[in/out] op_data client MD stack parameters, name, namelen etc, - * op_mds and op_fid1 will be updated if op_lso1 - * indicates fid1 represents a striped directory. - * - * retval pointer to the lmv_tgt_desc if succeed. - * ERR_PTR(errno) if failed. + * Return: + * * pointer to the lmv_tgt_desc if succeed. ERR_PTR(errno) if failed. */ struct lmv_tgt_desc * lmv_locate_tgt(struct lmv_obd *lmv, struct md_op_data *op_data) @@ -3089,19 +3095,17 @@ static int lmv_file_resync(struct obd_export *exp, struct md_op_data *data) } /** - * Get dirent with the closest hash for striped directory + * lmv_dirent_next() - Get dirent with the closest hash for striped directory + * @ctxt: dir read context * * This function will search the dir entry, whose hash value is the * closest(>=) to hash from all of sub-stripes, and it is only being called * for striped directory. * - * \param[in] ctxt dir read context * - * \retval dirent get the entry successfully - * NULL does not get the entry, normally it means - * it reaches the end of the directory, while read - * stripe dirent error is ignored to allow partial - * access. + * * Returns dirent if retrieval of the entry is successfully. NULL does not + * get the entry, normally it means it reaches the end of the directory, + * while read stripe dirent error is ignored to allow partial access. */ static struct lu_dirent *lmv_dirent_next(struct lmv_dir_ctxt *ctxt) { @@ -3146,7 +3150,15 @@ static struct lu_dirent *lmv_dirent_next(struct lmv_dir_ctxt *ctxt) } /** - * Build dir entry page for striped directory + * lmv_striped_read_page() - Build dir entry page for striped directory + * @exp: obd export refer to LMV + * @op_data: hold those MD parameters of read_entry + * @mrinfo: ldlm callback being used in enqueue in mdc_read_entry, and partial + * readdir result will be stored in it. + * @offset: starting hash offset + * @ppage: the page holding the entry. Note: because the entry will be + * accessed in upper layer, so we need hold the page until the usages of entry + * is finished, see ll_dir_entry_next. * * This function gets one entry by @offset from a striped directory. It will * read entries from all of stripes, and choose one closest to the required @@ -3156,18 +3168,9 @@ static struct lu_dirent *lmv_dirent_next(struct lmv_dir_ctxt *ctxt) * 2. op_data will be shared by all of stripes, instead of allocating new * one, so need to restore before reusing. * - * \param[in] exp obd export refer to LMV - * \param[in] op_data hold those MD parameters of read_entry - * \param[in] mrinfo ldlm callback being used in enqueue in mdc_read_entry, - * and partial readdir result will be stored in it. - * \param[in] offset starting hash offset - * \param[out] ppage the page holding the entry. Note: because the entry - * will be accessed in upper layer, so we need hold the - * page until the usages of entry is finished, see - * ll_dir_entry_next. - * - * retval =0 if get entry successfully - * <0 cannot get entry + * * Return: + * * %>=0: get entry successfully + * * %<0: Cannot get entry */ static int lmv_striped_read_page(struct obd_export *exp, struct md_op_data *op_data, @@ -3315,7 +3318,12 @@ static int lmv_read_page(struct obd_export *exp, struct md_op_data *op_data, } /** - * Unlink a file/directory + * lmv_unlink() - Unlink a file/directory + * @exp: export refer to LMV + * @op_data: different parameters transferred between + * client MD stacks, name, namelen, FIDs etc. op_fid1 is the parent FID, + * op_fid2 is the child FID. + * @request: point to the request of unlink. * * Unlink a file or directory under the parent dir. The unlink request * usually will be sent to the MDT where the child is located, but if @@ -3328,15 +3336,9 @@ static int lmv_read_page(struct obd_export *exp, struct md_op_data *op_data, * it will walk through all of sub-stripes until the child is being * unlinked finally. * - * \param[in] exp export refer to LMV - * \param[in] op_data different parameters transferred beween client - * MD stacks, name, namelen, FIDs etc. - * op_fid1 is the parent FID, op_fid2 is the child - * FID. - * \param[out] request point to the request of unlink. - * - * retval 0 if succeed - * negative errno if failed. + * * Return: + * * %0: Success + * * %-ERRNO: Failure */ static int lmv_unlink(struct obd_export *exp, struct md_op_data *op_data, struct ptlrpc_request **request) @@ -3428,20 +3430,20 @@ static int lmv_precleanup(struct obd_device *obd) } /** - * Get by key a value associated with a LMV device. + * lmv_get_info() - Get by key a value associated with a LMV device. + * @env: execution environment for this thread + * @exp: export for the LMV device + * @keylen: length of key identifier + * @key: identifier of key to get value for + * @vallen: size of \a val + * @val: pointer to storage location for value * * Dispatch request to lower-layer devices as needed. + * lsm: optional striping metadata of object * - * \param[in] env execution environment for this thread - * \param[in] exp export for the LMV device - * \param[in] keylen length of key identifier - * \param[in] key identifier of key to get value for - * \param[in] vallen size of \a val - * \param[out] val pointer to storage location for value - * \param[in] lsm optional striping metadata of object - * - * \retval 0 on success - * \retval negative negated errno on failure + * Return: + * * %0 on success + * * %negative negated errno on failure */ static int lmv_get_info(const struct lu_env *env, struct obd_export *exp, __u32 keylen, void *key, __u32 *vallen, void *val) @@ -3586,20 +3588,21 @@ out_fas: } /** - * Asynchronously set by key a value associated with a LMV device. + * lmv_set_info_async() - Asynchronously set by key a value associated with a + * LMV device. + * @env: execution environment for this thread + * @exp: export for the LMV device + * @keylen: length of key identifier + * @key: identifier of key to store value for + * @vallen: size of value to store + * @val: pointer to data to be stored + * @set: optional list of related ptlrpc requests * * Dispatch request to lower-layer devices as needed. * - * \param[in] env execution environment for this thread - * \param[in] exp export for the LMV device - * \param[in] keylen length of key identifier - * \param[in] key identifier of key to store value for - * \param[in] vallen size of value to store - * \param[in] val pointer to data to be stored - * \param[in] set optional list of related ptlrpc requests - * - * \retval 0 on success - * \retval negative negated errno on failure + * Return: + * * %0 on success + * * %negative negated errno on failure */ static int lmv_set_info_async(const struct lu_env *env, struct obd_export *exp, __u32 keylen, void *key, __u32 vallen, void *val, @@ -4137,7 +4140,7 @@ static int lmv_get_fid_from_lsm(struct obd_export *exp, RETURN(0); } -/** +/* * For lmv, only need to send request to master MDT, and the master MDT will * process with other slave MDTs. The only exception is Q_GETOQUOTA for which * we directly fetch data from the slave MDTs.