From b6398b3335c90115975e8e61263608f5eb403b86 Mon Sep 17 00:00:00 2001 From: Arshad Hussain Date: Fri, 18 Apr 2025 04:32:33 +0530 Subject: [PATCH] LU-9633 ptlrpc: Add kernel doc style for ptlrpc (3) 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: I2e99e4e411a4e253604b1cca3b2c70fca9579b4a Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58859 Tested-by: jenkins Tested-by: Maloo Reviewed-by: James Simmons Reviewed-by: Petros Koutoupis Reviewed-by: Anjus George Reviewed-by: Oleg Drokin --- lustre/ptlrpc/nrs.c | 478 ++++++++++++++++++++++++++-------------------------- 1 file changed, 238 insertions(+), 240 deletions(-) diff --git a/lustre/ptlrpc/nrs.c b/lustre/ptlrpc/nrs.c index a26edca..19e6c9d 100644 --- a/lustre/ptlrpc/nrs.c +++ b/lustre/ptlrpc/nrs.c @@ -23,7 +23,7 @@ #include #include "ptlrpc_internal.h" -/** +/* * NRS core object. */ struct nrs_core nrs_core; @@ -84,7 +84,7 @@ static void nrs_policy_stop0(struct ptlrpc_nrs_policy *policy) EXIT; } -/** +/* * Increases the policy's usage started reference count. */ static inline void nrs_policy_started_get(struct ptlrpc_nrs_policy *policy) @@ -92,7 +92,7 @@ static inline void nrs_policy_started_get(struct ptlrpc_nrs_policy *policy) refcount_inc(&policy->pol_start_ref); } -/** +/* * Decreases the policy's usage started reference count, and stops the policy * in case it was already stopping and have no more outstanding usage * references (which indicates it has no more queued or started requests, and @@ -147,11 +147,13 @@ static int nrs_policy_stop_locked(struct ptlrpc_nrs_policy *policy) } /** - * Transitions the \a nrs NRS head's primary policy to + * nrs_policy_stop_primary() - Stop policy + * @nrs: the NRS head to carry out this operation on + * + * Transitions the @nrs NRS head's primary policy to * ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPING and if the policy has no * pending usage references, to ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPED. * - * \param[in] nrs the NRS head to carry out this operation on */ static void nrs_policy_stop_primary(struct ptlrpc_nrs *nrs) { @@ -180,7 +182,7 @@ static void nrs_policy_stop_primary(struct ptlrpc_nrs *nrs) EXIT; } -/** +/* * Transitions a policy across the ptlrpc_nrs_pol_state range of values, in * response to an lprocfs command to start a policy. * @@ -333,7 +335,7 @@ out: RETURN(rc); } -/** +/* * Increases the policy's usage reference count (caller count). */ static inline void nrs_policy_get_locked(struct ptlrpc_nrs_policy *policy) @@ -342,7 +344,7 @@ __must_hold(&policy->pol_nrs->nrs_lock) policy->pol_ref++; } -/** +/* * Decreases the policy's usage reference count. */ static void nrs_policy_put_locked(struct ptlrpc_nrs_policy *policy) @@ -353,7 +355,7 @@ __must_hold(&policy->pol_nrs->nrs_lock) policy->pol_ref--; } -/** +/* * Find and return a policy by name. */ static struct ptlrpc_nrs_policy * nrs_policy_find_locked(struct ptlrpc_nrs *nrs, @@ -371,7 +373,7 @@ static struct ptlrpc_nrs_policy * nrs_policy_find_locked(struct ptlrpc_nrs *nrs, return NULL; } -/** +/* * Release references for the resource hierarchy moving upwards towards the * policy instance resource. */ @@ -390,20 +392,20 @@ static void nrs_resource_put(struct ptlrpc_nrs_resource *res) } /** - * Obtains references for each resource in the resource hierarchy for request - * \a nrq if it is to be handled by \a policy. - * - * \param[in] policy the policy - * \param[in] nrq the request - * \param[in] moving_req denotes whether this is a call to the function by - * ldlm_lock_reorder_req(), in order to move \a nrq to - * the high-priority NRS head; we should not sleep when - * set. - * - * \retval NULL resource hierarchy references not obtained - * \retval valid-pointer the bottom level of the resource hierarchy - * - * \see ptlrpc_nrs_pol_ops::op_res_get() + * nrs_resource_get() - Obtains references for each resource in the resource + * hierarchy for request + * @nrq if it is to be handled by @policy. + * @policy: the policy + * @nrq: the request + * @moving_req: denotes whether this is a call to the function by + * ldlm_lock_reorder_req(), in order to move @nrq to the high-priority NRS head; + * we should not sleep when set. + * + * Note: ptlrpc_nrs_pol_ops::op_res_get() + * + * Return: + * * %NULL resource hierarchy references not obtained + * * %valid-pointer the bottom level of the resource hierarchy */ static struct ptlrpc_nrs_resource * nrs_resource_get(struct ptlrpc_nrs_policy *policy, @@ -441,21 +443,19 @@ struct ptlrpc_nrs_resource * nrs_resource_get(struct ptlrpc_nrs_policy *policy, } /** + * nrs_resource_get_safe() - Obtains resources + * @nrs: the NRS head instance that will be handling request @nrq. + * @nrq: the request that is being handled. + * @resp: the array where references to the resource hierarchy are stored [out] + * @moving_req: is set when obtaining resources while moving a request from a + * policy on the regular NRS head to a policy on the HP NRS head + * (via ldlm_lock_reorder_req()). It signifies that allocations to get resources + * should be atomic; for a full explanation, see comment in + * ptlrpc_nrs_pol_ops::op_res_get(). + * * Obtains resources for the resource hierarchies and policy references for * the fallback and current primary policy (if any), that will later be used - * to handle request \a nrq. - * - * \param[in] nrs the NRS head instance that will be handling request \a nrq. - * \param[in] nrq the request that is being handled. - * \param[out] resp the array where references to the resource hierarchy are - * stored. - * \param[in] moving_req is set when obtaining resources while moving a - * request from a policy on the regular NRS head to a - * policy on the HP NRS head (via - * ldlm_lock_reorder_req()). It signifies that - * allocations to get resources should be atomic; for - * a full explanation, see comment in - * ptlrpc_nrs_pol_ops::op_res_get(). + * to handle request @nrq. */ static void nrs_resource_get_safe(struct ptlrpc_nrs *nrs, struct ptlrpc_nrs_request *nrq, @@ -502,14 +502,13 @@ static void nrs_resource_get_safe(struct ptlrpc_nrs *nrs, } /** + * nrs_resource_put_safe() - Releases references + * @resp: the resource hierarchy that is being released + * * Releases references to resource hierarchies and policies, because they are no * longer required; used when request handling has been completed, or the * request is moving to the high priority NRS head. - * - * \param resp the resource hierarchy that is being released - * - * \see ptlrpcnrs_req_hp_move() - * \see ptlrpc_nrs_req_finalize() + * Note: see ptlrpcnrs_req_hp_move() and ptlrpc_nrs_req_finalize() */ static void nrs_resource_put_safe(struct ptlrpc_nrs_resource **resp) { @@ -535,20 +534,18 @@ static void nrs_resource_put_safe(struct ptlrpc_nrs_resource **resp) } /** - * Obtains an NRS request from \a policy for handling or examination; the - * request should be removed in the 'handling' case. + * nrs_request_get() - Obtains an NRS request from @policy for handling or + * examination; the request should be removed in the 'handling' case. + * @policy: the policy from which a request + * @peek: when set, signifies that we just want to examine the request, and not + * handle it, so the request is not removed from the policy. + * @force: when set, it will force a policy to return a request if it has one + * pending * * Calling into this function implies we already know the policy has a request * waiting to be handled. * - * \param[in] policy the policy from which a request - * \param[in] peek when set, signifies that we just want to examine the - * request, and not handle it, so the request is not removed - * from the policy. - * \param[in] force when set, it will force a policy to return a request if it - * has one pending - * - * \retval the NRS request to be handled + * Returns the NRS request to be handled */ static inline struct ptlrpc_nrs_request * nrs_request_get(struct ptlrpc_nrs_policy *policy, @@ -570,14 +567,15 @@ struct ptlrpc_nrs_request * nrs_request_get(struct ptlrpc_nrs_policy *policy, } /** - * Enqueues request \a nrq for later handling, via one one the policies for + * nrs_request_enqueue() - Enqueues request + * @nrq: the request being enqueued + * + * Enqueues request @nrq for later handling, via one one the policies for * which resources where earlier obtained via nrs_resource_get_safe(). The * function attempts to enqueue the request first on the primary policy * (if any), since this is the preferred choice. * - * \param nrq the request being enqueued - * - * \see nrs_resource_get_safe() + * Note: see nrs_resource_get_safe() */ static inline void nrs_request_enqueue(struct ptlrpc_nrs_request *nrq) { @@ -617,12 +615,10 @@ static inline void nrs_request_enqueue(struct ptlrpc_nrs_request *nrq) } /** - * Called when a request has been handled + * nrs_request_stop() - Called when a request has been handled + * @nrq: the request that has been handled; can be used for job/resource control * - * \param[in] nrs the request that has been handled; can be used for - * job/resource control. - * - * \see ptlrpc_nrs_req_stop_nolock() + * Note: see ptlrpc_nrs_req_stop_nolock() */ static inline void nrs_request_stop(struct ptlrpc_nrs_request *nrq) { @@ -639,22 +635,22 @@ static inline void nrs_request_stop(struct ptlrpc_nrs_request *nrq) } /** - * Handler for operations that can be carried out on policies. - * + * nrs_policy_ctl() - Handler for operations that can be carried out on policies + * @nrs: the NRS head this policy belongs to. + * @name: the human-readable policy name; should be the same as + * ptlrpc_nrs_pol_desc::pd_name. + * @opc: the opcode of the operation being carried out. + * @arg: can be used to pass information in and out between when carrying an + * operation; usually data that is private to the policy at some level, or + * generic policy status information. [out] + * + * Handler for operations that can be carried out on policies * Handles opcodes that are common to all policy types within NRS core, and * passes any unknown opcodes to the policy-specific control function. * - * \param[in] nrs the NRS head this policy belongs to. - * \param[in] name the human-readable policy name; should be the same as - * ptlrpc_nrs_pol_desc::pd_name. - * \param[in] opc the opcode of the operation being carried out. - * \param[in,out] arg can be used to pass information in and out between when - * carrying an operation; usually data that is private to - * the policy at some level, or generic policy status - * information. - * - * \retval -ve error condition - * \retval 0 operation was carried out successfully + * Return: + * * %-ve error condition + * * %0 operation was carried out successfully */ static int nrs_policy_ctl(struct ptlrpc_nrs *nrs, char *name, enum ptlrpc_nrs_ctl opc, void *arg) @@ -699,14 +695,14 @@ out: } /** - * Unregisters a policy by name. - * - * \param[in] nrs the NRS head this policy belongs to. - * \param[in] name the human-readable policy name; should be the same as - * ptlrpc_nrs_pol_desc::pd_name - * - * \retval -ve error - * \retval 0 success + * nrs_policy_unregister() - Unregisters a policy by name. + * @nrs: the NRS head this policy belongs to. + * @name: the human-readable policy name; should be the same as + * ptlrpc_nrs_pol_desc::pd_name + * + * Return: + * * %-ve error + * * %0 success */ static int nrs_policy_unregister(struct ptlrpc_nrs *nrs, char *name) { @@ -765,14 +761,15 @@ out_unlock: } /** - * Register a policy from \policy descriptor \a desc with NRS head \a nrs. - * - * \param[in] nrs the NRS head on which the policy will be registered. - * \param[in] desc the policy descriptor from which the information will be - * obtained to register the policy. - * - * \retval -ve error - * \retval 0 success + * nrs_policy_register() - Register a policy from policy descriptor @desc with + * NRS head @nrs. + * @nrs: the NRS head on which the policy will be registered. + * @desc: the policy descriptor from which the information will be obtained to + * register the policy. + * + * Return: + * * %-ve error + * * %0 success */ static int nrs_policy_register(struct ptlrpc_nrs *nrs, struct ptlrpc_nrs_pol_desc *desc) @@ -845,10 +842,9 @@ static int nrs_policy_register(struct ptlrpc_nrs *nrs, } /** - * Enqueue request \a req using one of the policies its resources are referring - * to. - * - * \param[in] req the request to enqueue. + * ptlrpc_nrs_req_add_nolock() - Enqueue request @req using one of the policies + * its resources are referring to. + * @req: the request to enqueue. */ static void ptlrpc_nrs_req_add_nolock(struct ptlrpc_request *req) { @@ -871,9 +867,9 @@ static void ptlrpc_nrs_req_add_nolock(struct ptlrpc_request *req) } /** - * Enqueue a request on the high priority NRS head. - * - * \param req the request to enqueue. + * ptlrpc_nrs_hpreq_add_nolock() - Enqueue a request on the high priority NRS + * head. + * @req: the request to enqueue. */ static void ptlrpc_nrs_hpreq_add_nolock(struct ptlrpc_request *req) { @@ -890,14 +886,14 @@ static void ptlrpc_nrs_hpreq_add_nolock(struct ptlrpc_request *req) } /** - * Returns a boolean predicate indicating whether the policy described by - * \a desc is adequate for use with service \a svc. - * - * \param[in] svc the service - * \param[in] desc the policy descriptor - * - * \retval false the policy is not compatible with the service - * \retval true the policy is compatible with the service + * nrs_policy_compatible() - Returns a boolean predicate indicating whether the + * policy described by @desc is adequate for use with service @svc. + * @svc: the service + * @desc: the policy descriptor + * + * Return: + * * %false the policy is not compatible with the service + * * %true the policy is compatible with the service */ static inline bool nrs_policy_compatible(const struct ptlrpc_service *svc, const struct ptlrpc_nrs_pol_desc *desc) @@ -906,17 +902,16 @@ static inline bool nrs_policy_compatible(const struct ptlrpc_service *svc, } /** - * Registers all compatible policies in nrs_core.nrs_policies, for NRS head - * \a nrs. - * - * \param[in] nrs the NRS head + * nrs_register_policies_locked() - Registers all compatible policies in + * nrs_core.nrs_policies, for NRS head @nrs. + * @nrs: the NRS head * - * \retval -ve error - * \retval 0 success + * Note: pre mutex_is_locked(&nrs_core.nrs_mutex) + * see ptlrpc_service_nrs_setup() * - * \pre mutex_is_locked(&nrs_core.nrs_mutex) - * - * \see ptlrpc_service_nrs_setup() + * Return: + * * %-ve error + * * %0 success */ static int nrs_register_policies_locked(struct ptlrpc_nrs *nrs) { @@ -949,16 +944,18 @@ static int nrs_register_policies_locked(struct ptlrpc_nrs *nrs) } /** - * Initializes NRS head \a nrs of service partition \a svcpt, and registers all - * compatible policies in NRS core, with the NRS head. + * nrs_svcpt_setup_locked0() - Initializes NRS head + * @nrs: the NRS head + * @svcpt: the PTLRPC service partition to setup * - * \param[in] nrs the NRS head - * \param[in] svcpt the PTLRPC service partition to setup + * Initializes NRS head @nrs of service partition @svcpt, and registers all + * compatible policies in NRS core, with the NRS head. * - * \retval -ve error - * \retval 0 success + * Note: mutex_is_locked(&nrs_core.nrs_mutex) * - * \pre mutex_is_locked(&nrs_core.nrs_mutex) + * Return: + * * %-ve error + * * %0 success */ static int nrs_svcpt_setup_locked0(struct ptlrpc_nrs *nrs, struct ptlrpc_service_part *svcpt) @@ -988,13 +985,18 @@ static int nrs_svcpt_setup_locked0(struct ptlrpc_nrs *nrs, } /** + * nrs_svcpt_setup_locked() - Allocates a regular/high-priority NRS head + * @svcpt: the PTLRPC service partition to setup [in,out] + * * Allocates a regular and optionally a high-priority NRS head (if the service * handles high-priority RPCs), and then registers all available compatible * policies on those NRS heads. * - * \param[in,out] svcpt the PTLRPC service partition to setup + * Note: mutex_is_locked(&nrs_core.nrs_mutex) * - * \pre mutex_is_locked(&nrs_core.nrs_mutex) + * Return: + * * %-ve error + * * %0 success */ static int nrs_svcpt_setup_locked(struct ptlrpc_service_part *svcpt) { @@ -1032,12 +1034,11 @@ out: } /** - * Unregisters all policies on all available NRS heads in a service partition; - * called at PTLRPC service unregistration time. + * nrs_svcpt_cleanup_locked() - Unregisters all policies on all available NRS + * heads in a service partition; called at PTLRPC service unregistration time. + * @svcpt: the PTLRPC service partition * - * \param[in] svcpt the PTLRPC service partition - * - * \pre mutex_is_locked(&nrs_core.nrs_mutex) + * Note: pre mutex_is_locked(&nrs_core.nrs_mutex) */ static void nrs_svcpt_cleanup_locked(struct ptlrpc_service_part *svcpt) { @@ -1081,12 +1082,11 @@ again: } /** - * Returns the descriptor for a policy as identified by by \a name. - * - * \param[in] name the policy name + * nrs_policy_find_desc_locked() - Returns the descriptor for a policy as + * identified by by @name. + * @name: the policy name * - * \retval the policy descriptor - * \retval NULL + * Returns the policy descriptor on success and NULL on error */ static struct ptlrpc_nrs_pol_desc *nrs_policy_find_desc_locked(const char *name) { @@ -1101,16 +1101,17 @@ static struct ptlrpc_nrs_pol_desc *nrs_policy_find_desc_locked(const char *name) } /** - * Removes the policy from all supported NRS heads of all partitions of all - * PTLRPC services. + * nrs_policy_unregister_locked() - Removes the policy from all supported NRS + * heads of all partitions of all PTLRPC services. + * @desc: the policy descriptor to unregister * - * \param[in] desc the policy descriptor to unregister + * pre mutex_is_locked(&nrs_core.nrs_mutex) + * pre mutex_is_locked(&ptlrpc_all_services_mutex) * - * \retval -ve error - * \retval 0 successfully unregistered policy on all supported NRS heads + * Return: + * * %0 successfully unregistered policy on all supported NRS heads + * * %-ve error * - * \pre mutex_is_locked(&nrs_core.nrs_mutex) - * \pre mutex_is_locked(&ptlrpc_all_services_mutex) */ static int nrs_policy_unregister_locked(struct ptlrpc_nrs_pol_desc *desc) { @@ -1164,7 +1165,8 @@ again: } /** - * Registers a new policy with NRS core. + * ptlrpc_nrs_policy_register() - Registers a new policy with NRS core. + * @conf: configuration information for the new policy to register * * The function will only succeed if policy registration with all compatible * service partitions (if any) is successful. @@ -1173,10 +1175,9 @@ again: * time when registering a policy that ships with NRS core, or in a * module's init() function for policies registering from other modules. * - * \param[in] conf configuration information for the new policy to register - * - * \retval -ve error - * \retval 0 success + * Return: + * * %-ve error + * * %0 success */ static int ptlrpc_nrs_policy_register(struct ptlrpc_nrs_pol_conf *conf) { @@ -1324,18 +1325,18 @@ fail: } /** - * Setup NRS heads on all service partitions of service \a svc, and register - * all compatible policies on those NRS heads. - * + * ptlrpc_service_nrs_setup() - Setup NRS heads on all service partitions of + * service @svc, and register all compatible policies on those NRS heads. * To be called from withing ptl - * \param[in] svc the service to setup + * @svc: the service to setup * - * \retval -ve error, the calling logic should eventually call - * ptlrpc_service_nrs_cleanup() to undo any work performed - * by this function. + * Note: see ptlrpc_register_service() and ptlrpc_service_nrs_cleanup() + * + * Return: + * * %0 on success + * * %-ve error, the calling logic should eventually call + * ptlrpc_service_nrs_cleanup() to undo any work performed by this function. * - * \see ptlrpc_register_service() - * \see ptlrpc_service_nrs_cleanup() */ int ptlrpc_service_nrs_setup(struct ptlrpc_service *svc) { @@ -1378,9 +1379,9 @@ failed: } /** - * Unregisters all policies on all service partitions of service \a svc. - * - * \param[in] svc the PTLRPC service to unregister + * ptlrpc_service_nrs_cleanup() - Unregisters all policies on all service + * partitions of service @svc. + * @svc: the PTLRPC service to unregister */ void ptlrpc_service_nrs_cleanup(struct ptlrpc_service *svc) { @@ -1412,15 +1413,14 @@ void ptlrpc_service_nrs_cleanup(struct ptlrpc_service *svc) } /** - * Obtains NRS head resources for request \a req. + * ptlrpc_nrs_req_initialize() - Obtains NRS head resources for request @req. + * @svcpt: the service partition + * @req: the request + * @hp: which NRS head of @svcpt to use * - * These could be either on the regular or HP NRS head of \a svcpt; resources + * These could be either on the regular or HP NRS head of @svcpt; resources * taken on the regular head can later be swapped for HP head resources by * ldlm_lock_reorder_req(). - * - * \param[in] svcpt the service partition - * \param[in] req the request - * \param[in] hp which NRS head of \a svcpt to use */ void ptlrpc_nrs_req_initialize(struct ptlrpc_service_part *svcpt, struct ptlrpc_request *req, bool hp) @@ -1439,12 +1439,11 @@ void ptlrpc_nrs_req_initialize(struct ptlrpc_service_part *svcpt, } /** - * Releases resources for a request; is called after the request has been - * handled. - * - * \param[in] req the request + * ptlrpc_nrs_req_finalize() - Releases resources for a request; is called after + * the request has been handled. + * @req: the request * - * \see ptlrpc_server_finish_request() + * Note: see ptlrpc_server_finish_request() */ void ptlrpc_nrs_req_finalize(struct ptlrpc_request *req) { @@ -1463,13 +1462,11 @@ void ptlrpc_nrs_req_stop_nolock(struct ptlrpc_request *req) } /** - * Enqueues request \a req on either the regular or high-priority NRS head - * of service partition \a svcpt. - * - * \param[in] svcpt the service partition - * \param[in] req the request to be enqueued - * \param[in] hp whether to enqueue the request on the regular or - * high-priority NRS head. + * ptlrpc_nrs_req_add() - Enqueues request @req on either the regular or + * high-priority NRS head of service partition @svcpt. + * @svcpt: the service partition + * @req: the request to be enqueued + * @hp: whether to enqueue the request on the regular or high-priority NRS head. */ void ptlrpc_nrs_req_add(struct ptlrpc_service_part *svcpt, struct ptlrpc_request *req, bool hp) @@ -1517,20 +1514,16 @@ static void nrs_request_removed(struct ptlrpc_nrs_policy *policy) } /** - * Obtains a request for handling from an NRS head of service partition - * \a svcpt. - * - * \param[in] svcpt the service partition - * \param[in] hp whether to obtain a request from the regular or - * high-priority NRS head. - * \param[in] peek when set, signifies that we just want to examine the - * request, and not handle it, so the request is not removed - * from the policy. - * \param[in] force when set, it will force a policy to return a request if it - * has one pending - * - * \retval the request to be handled - * \retval NULL the head has no requests to serve + * ptlrpc_nrs_req_get_nolock0() - Obtains a request for handling from an NRS + * head of service partition @svcpt. + * @svcpt: the service partition + * @hp: whether to obtain a request from the regular or high-priority NRS head. + * @peek: when set, signifies that we just want to examine the request, and not + * handle it, so the request is not removed from the policy. + * @force: when set, it will force a policy to return a request if it has one + * pending + * + * Returns request to be handled or NULL if the head has no request to serve */ struct ptlrpc_request * ptlrpc_nrs_req_get_nolock0(struct ptlrpc_service_part *svcpt, bool hp, @@ -1565,9 +1558,9 @@ ptlrpc_nrs_req_get_nolock0(struct ptlrpc_service_part *svcpt, bool hp, } /** - * Dequeues request \a req from the policy it has been enqueued on. - * - * \param[in] req the request + * ptlrpc_nrs_req_del_nolock() - Dequeues request @req from the policy it has + * been enqueued on. + * @req: the request */ void ptlrpc_nrs_req_del_nolock(struct ptlrpc_request *req) { @@ -1581,17 +1574,19 @@ void ptlrpc_nrs_req_del_nolock(struct ptlrpc_request *req) } /** + * ptlrpc_nrs_req_pending_nolock() - Returns whether there are any requests + * currently enqueued on any of the + * @svcpt: the service partition to enquire. + * @hp: whether the regular or high-priority NRS head is to be enquired. + * * Returns whether there are any requests currently enqueued on any of the - * policies of service partition's \a svcpt NRS head specified by \a hp. Should + * policies of service partition's @svcpt NRS head specified by @hp. Should * be called while holding ptlrpc_service_part::scp_req_lock to get a reliable * result. * - * \param[in] svcpt the service partition to enquire. - * \param[in] hp whether the regular or high-priority NRS head is to be - * enquired. - * - * \retval false the indicated NRS head has no enqueued requests. - * \retval true the indicated NRS head has some enqueued requests. + * Return: + * * %false the indicated NRS head has no enqueued requests. + * * %true the indicated NRS head has some enqueued requests. */ bool ptlrpc_nrs_req_pending_nolock(struct ptlrpc_service_part *svcpt, bool hp) { @@ -1601,14 +1596,14 @@ bool ptlrpc_nrs_req_pending_nolock(struct ptlrpc_service_part *svcpt, bool hp) }; /** - * Returns whether NRS policy is throttling reqeust - * - * \param[in] svcpt the service partition to enquire. - * \param[in] hp whether the regular or high-priority NRS head is to be - * enquired. - * - * \retval false the indicated NRS head has no enqueued requests. - * \retval true the indicated NRS head has some enqueued requests. + * ptlrpc_nrs_req_throttling_nolock() - Returns whether NRS policy is throttling + * reqeust + * @svcpt: the service partition to enquire. + * @hp: whether the regular or high-priority NRS head is to be enquired. + * + * Return: + * * %false the indicated NRS head has no enqueued requests. + * * %true the indicated NRS head has some enqueued requests. */ bool ptlrpc_nrs_req_throttling_nolock(struct ptlrpc_service_part *svcpt, bool hp) @@ -1619,9 +1614,9 @@ bool ptlrpc_nrs_req_throttling_nolock(struct ptlrpc_service_part *svcpt, }; /** - * Moves request \a req from the regular to the high-priority NRS head. - * - * \param[in] req the request to move + * ptlrpc_nrs_req_hp_move() - Moves request @req from the regular to the + * high-priority NRS head. + * @req: the request to move */ void ptlrpc_nrs_req_hp_move(struct ptlrpc_request *req) { @@ -1663,30 +1658,32 @@ out: } /** - * Carries out a control operation \a opc on the policy identified by the - * human-readable \a name, on either all partitions, or only on the first - * partition of service \a svc. - * - * \param[in] svc the service the policy belongs to. - * \param[in] queue whether to carry out the command on the policy which - * belongs to the regular, high-priority, or both NRS - * heads of service partitions of \a svc. - * \param[in] name the policy to act upon, by human-readable name - * \param[in] opc the opcode of the operation to carry out - * \param[in] single when set, the operation will only be carried out on the - * NRS heads of the first service partition of \a svc. - * This is useful for some policies which e.g. share - * identical values on the same parameters of different - * service partitions; when reading these parameters via - * lprocfs, these policies may just want to obtain and - * print out the values from the first service partition. - * Storing these values centrally elsewhere then could be - * another solution for this. - * \param[in,out] arg can be used as a generic in/out buffer between control - * operations and the user environment. - * - *\retval -ve error condition - *\retval 0 operation was carried out successfully + * ptlrpc_nrs_policy_control() - Carries out control operation @opc on policy + * @svc: the service the policy belongs to. + * @queue: whether to carry out the command on the policy which + * belongs to the regular, high-priority, or both NRS + * heads of service partitions of @svc. + * @name: the policy to act upon, by human-readable name + * @opc: the opcode of the operation to carry out + * @single: when set, the operation will only be carried out on the + * NRS heads of the first service partition of @svc. + * This is useful for some policies which e.g. share + * identical values on the same parameters of different + * service partitions; when reading these parameters via + * lprocfs, these policies may just want to obtain and + * print out the values from the first service partition. + * Storing these values centrally elsewhere then could be + * another solution for this. + * @arg: can be used as a generic in/out buffer between control operations and + * the user environment. [in,out] + * + * Carries out a control operation @opc on the policy identified by the + * human-readable @name, on either all partitions, or only on the first + * partition of service @svc. + * + * Return: + * * %-ve error condition + * * %0 operation was carried out successfully */ int ptlrpc_nrs_policy_control(const struct ptlrpc_service *svc, enum ptlrpc_nrs_queue_type queue, char *name, @@ -1731,11 +1728,12 @@ out: } /** - * Adds all policies that ship with the ptlrpc module, to NRS core's list of - * policies \e nrs_core.nrs_policies. + * ptlrpc_nrs_init() - Adds all policies that ship with the ptlrpc module, + * to NRS core's list of policies @nrs_core.nrs_policies. * - * \retval 0 all policies have been registered successfully - * \retval -ve error + * Return: + * * %0 all policies have been registered successfully + * * %-ve error */ int ptlrpc_nrs_init(void) { @@ -1782,8 +1780,8 @@ fail: } /** - * Removes all policy descriptors from nrs_core::nrs_policies, and frees the - * policy descriptors. + * ptlrpc_nrs_fini() - Removes all policy descriptors from + * nrs_core::nrs_policies, and frees the policy descriptors. * * Since all PTLRPC services are stopped at this point, there are no more * instances of any policies, because each service will have stopped its policy -- 1.8.3.1