From: Arshad Hussain Date: Fri, 30 May 2025 13:41:36 +0000 (+0530) Subject: LU-9633 ptlrpc: Add kernel doc style for ptlrpc (9) X-Git-Url: https://git.whamcloud.com/gitweb?a=commitdiff_plain;h=4e3a78d064b39aace3df88d5cee0c7e0c89f18b3;p=fs%2Flustre-release.git LU-9633 ptlrpc: Add kernel doc style for ptlrpc (9) 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: I94c5b18dca250d0279b85b92019f34f5e67ce6b5 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/59518 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Petros Koutoupis Reviewed-by: James Simmons Reviewed-by: Oleg Drokin --- diff --git a/lustre/ptlrpc/nrs_crr.c b/lustre/ptlrpc/nrs_crr.c index a17bbfb..1e976d0 100644 --- a/lustre/ptlrpc/nrs_crr.c +++ b/lustre/ptlrpc/nrs_crr.c @@ -22,30 +22,26 @@ #include #include "ptlrpc_internal.h" -/** - * \name CRR-N policy - * +/* + * CRR-N policy * Client Round-Robin scheduling over client NIDs - * - * @{ - * */ #define NRS_POL_NAME_CRRN "crrn" /** - * Binary heap predicate. + * crrn_req_compare() - Binary heap predicate. + * @e1: the first binheap node to compare + * @e2: the second binheap node to compare * * Uses ptlrpc_nrs_request::nr_u::crr::cr_round and * ptlrpc_nrs_request::nr_u::crr::cr_sequence to compare two binheap nodes and * produce a binary predicate that shows their relative priority, so that the * binary heap can perform the necessary sorting operations. * - * \param[in] e1 the first binheap node to compare - * \param[in] e2 the second binheap node to compare - * - * \retval 0 e1 > e2 - * \retval 1 e1 <= e2 + * Return: + * * %0 if e1 > e2 + * * %1 if e1 <= e2 */ static int crrn_req_compare(struct binheap_node *e1, struct binheap_node *e2) @@ -71,7 +67,10 @@ static struct binheap_ops nrs_crrn_heap_ops = { }; /** - * rhashtable operations for nrs_crrn_net::cn_cli_hash + * nrs_crrn_hashfn() - rhashtable operations for nrs_crrn_net::cn_cli_hash + * @data: pointer to key + * @len: length of key + * @seed: seed value (randomness regulator) * * This uses ptlrpc_request::rq_peer.nid (as nid4) as its key, in order to hash * nrs_crrn_client objects. @@ -111,12 +110,13 @@ static void nrs_crrn_exit(void *vcli, void *data) } /** - * Called when a CRR-N policy instance is started. - * - * \param[in] policy the policy + * nrs_crrn_start() - Called when a CRR-N policy instance is started. + * @policy: the policy + * @arg: used for passing parameters and information (optional) * - * \retval -ENOMEM OOM error - * \retval 0 success + * Return: + * * %-ENOMEM OOM error + * * %0 success */ static int nrs_crrn_start(struct ptlrpc_nrs_policy *policy, char *arg) { @@ -139,14 +139,14 @@ static int nrs_crrn_start(struct ptlrpc_nrs_policy *policy, char *arg) if (rc) GOTO(out_binheap, rc); - /** + /* * Set default quantum value to max_rpcs_in_flight for non-MDS OSCs; * there may be more RPCs pending from each struct nrs_crrn_client even * with the default max_rpcs_in_flight value, as we are scheduling over * NIDs, and there may be more than one mount point per client. */ net->cn_quantum = OBD_MAX_RIF_DEFAULT; - /** + /* * Set to 1 so that the test inside nrs_crrn_req_add() can evaluate to * true. */ @@ -165,13 +165,12 @@ out_net: } /** - * Called when a CRR-N policy instance is stopped. + * nrs_crrn_stop() - Called when a CRR-N policy instance is stopped. + * @policy: the policy * * Called when the policy has been instructed to transition to the * ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPED state and has no more pending * requests to serve. - * - * \param[in] policy the policy */ static void nrs_crrn_stop(struct ptlrpc_nrs_policy *policy) { @@ -189,18 +188,18 @@ static void nrs_crrn_stop(struct ptlrpc_nrs_policy *policy) } /** - * Performs a policy-specific ctl function on CRR-N policy instances; similar - * to ioctl. - * - * \param[in] policy the policy instance - * \param[in] opc the opcode - * \param[in,out] arg used for passing parameters and information + * nrs_crrn_ctl() - Performs a policy-specific ctl function on CRR-N policy + * instances; similar to ioctl. + * @policy: the policy instance + * @opc: the opcode + * @arg: used for passing parameters and information * * \pre assert_spin_locked(&policy->pol_nrs->->nrs_lock) * \post assert_spin_locked(&policy->pol_nrs->->nrs_lock) * - * \retval 0 operation carried out successfully - * \retval -ve error + * Return: + * * %0 operation carried out successfully + * * %negative on error */ static int nrs_crrn_ctl(struct ptlrpc_nrs_policy *policy, enum ptlrpc_nrs_ctl opc, @@ -212,9 +211,7 @@ static int nrs_crrn_ctl(struct ptlrpc_nrs_policy *policy, default: RETURN(-EINVAL); - /** - * Read Round Robin quantum size of a policy instance. - */ + /* Read Round Robin quantum size of a policy instance. */ case NRS_CTL_CRRN_RD_QUANTUM: { struct nrs_crrn_net *net = policy->pol_private; @@ -222,9 +219,7 @@ static int nrs_crrn_ctl(struct ptlrpc_nrs_policy *policy, } break; - /** - * Write Round Robin quantum size of a policy instance. - */ + /* Write Round Robin quantum size of a policy instance. */ case NRS_CTL_CRRN_WR_QUANTUM: { struct nrs_crrn_net *net = policy->pol_private; @@ -238,26 +233,28 @@ static int nrs_crrn_ctl(struct ptlrpc_nrs_policy *policy, } /** - * Obtains resources from CRR-N policy instances. The top-level resource lives - * inside \e nrs_crrn_net and the second-level resource inside - * \e nrs_crrn_client object instances. - * - * \param[in] policy the policy for which resources are being taken for - * request \a nrq - * \param[in] nrq the request for which resources are being taken - * \param[in] parent parent resource, embedded in nrs_crrn_net for the + * nrs_crrn_res_get() - Obtains resources from CRR-N policy instances + * @policy: the policy for which resources are being taken for + * request @nrq + * @nrq: the request for which resources are being taken + * @parent: parent resource, embedded in nrs_crrn_net for the * CRR-N policy - * \param[out] resp resources references are placed in this array - * \param[in] moving_req signifies limited caller context; used to perform + * @resp: resources references are placed in this array (out param) + * @moving_req: signifies limited caller context; used to perform * memory allocations in an atomic context in this * policy * - * \retval 0 we are returning a top-level, parent resource, one that is - * embedded in an nrs_crrn_net object - * \retval 1 we are returning a bottom-level resource, one that is embedded - * in an nrs_crrn_client object + * Obtains resources from CRR-N policy instances. The top-level resource lives + * inside @nrs_crrn_net and the second-level resource inside @nrs_crrn_client + * object instances. + * + * see @nrs_resource_get_safe() * - * \see nrs_resource_get_safe() + * Return: + * * %0 we are returning a top-level, parent resource, one that is + * embedded in an nrs_crrn_net object + * * %1 we are returning a bottom-level resource, one that is embedded + * in an nrs_crrn_client object */ static int nrs_crrn_res_get(struct ptlrpc_nrs_policy *policy, struct ptlrpc_nrs_request *nrq, @@ -308,20 +305,17 @@ out: } /** - * Called when releasing references to the resource hierachy obtained for a - * request for scheduling using the CRR-N policy. - * - * \param[in] policy the policy the resource belongs to - * \param[in] res the resource to be released + * nrs_crrn_res_put() - Called when releasing references to the resource + * hierachy obtained for a request for scheduling using the CRR-N policy. + * @policy: the policy the resource belongs to + * @res: the resource to be released */ static void nrs_crrn_res_put(struct ptlrpc_nrs_policy *policy, const struct ptlrpc_nrs_resource *res) { struct nrs_crrn_client *cli; - /** - * Do nothing for freeing parent, nrs_crrn_net resources - */ + /* Do nothing for freeing parent, nrs_crrn_net resources */ if (res->res_parent == NULL) return; @@ -331,19 +325,18 @@ static void nrs_crrn_res_put(struct ptlrpc_nrs_policy *policy, } /** - * Called when getting a request from the CRR-N policy for handlingso that it can be served + * nrs_crrn_req_get() - Called when getting a request from the CRR-N policy for + * handlingso that it can be served * - * \param[in] policy the policy being polled - * \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 force the policy to return a request; unused in this policy + * @policy: the policy being polled + * @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: force the policy to return a request; unused in this policy * - * \retval the request to be handled - * \retval NULL no request available + * see @ptlrpc_nrs_req_get_nolock() + * see @nrs_request_get() * - * \see ptlrpc_nrs_req_get_nolock() - * \see nrs_request_get() + * Return the request to be handled or NULL no request available */ static struct ptlrpc_nrs_request *nrs_crrn_req_get(struct ptlrpc_nrs_policy *policy, @@ -375,10 +368,10 @@ struct ptlrpc_nrs_request *nrs_crrn_req_get(struct ptlrpc_nrs_policy *policy, "%llu\n", NRS_POL_NAME_CRRN, libcfs_idstr(&req->rq_peer), nrq->nr_u.crr.cr_round); - /** Peek at the next request to be served */ + /* Peek at the next request to be served */ node = binheap_root(net->cn_binheap); - /** No more requests */ + /* No more requests */ if (unlikely(node == NULL)) { net->cn_round++; } else { @@ -396,7 +389,10 @@ struct ptlrpc_nrs_request *nrs_crrn_req_get(struct ptlrpc_nrs_policy *policy, } /** - * Adds request \a nrq to a CRR-N \a policy instance's set of queued requests + * nrs_crrn_req_add() - Adds request @nrq to a CRR-N @policy instance's set of + * queued requests + * @policy: the policy + * @nrq: the request to add * * A scheduling round is a stream of requests that have been sorted in batches * according to the client that they originate from (as identified by its NID); @@ -418,11 +414,9 @@ struct ptlrpc_nrs_request *nrs_crrn_req_get(struct ptlrpc_nrs_policy *policy, * maintain an ordered set of rounds, with each round consisting of an ordered * set of batches of requests. * - * \param[in] policy the policy - * \param[in] nrq the request to add - * - * \retval 0 request successfully added - * \retval != 0 error + * Return: + * * %0 request successfully added + * * %!=0 on error */ static int nrs_crrn_req_add(struct ptlrpc_nrs_policy *policy, struct ptlrpc_nrs_request *nrq) @@ -439,7 +433,7 @@ static int nrs_crrn_req_add(struct ptlrpc_nrs_policy *policy, if (cli->cc_quantum == 0 || cli->cc_round < net->cn_round || (cli->cc_active == 0 && cli->cc_quantum > 0)) { - /** + /* * If the client has no pending requests, and still some of its * quantum remaining unused, which implies it has not had a * chance to schedule up to its maximum allowed batch size of @@ -452,14 +446,14 @@ static int nrs_crrn_req_add(struct ptlrpc_nrs_policy *policy, if (cli->cc_active == 0 && cli->cc_quantum > 0) cli->cc_round++; - /** A new scheduling round has commenced */ + /* A new scheduling round has commenced */ if (cli->cc_round < net->cn_round) cli->cc_round = net->cn_round; - /** I was not the last client through here */ + /* I was not the last client through here */ if (cli->cc_sequence < net->cn_sequence) cli->cc_sequence = ++net->cn_sequence; - /** + /* * Reset the quantum if we have reached the maximum quantum * size for this batch, or even if we have not managed to * complete a batch size up to its maximum allowed size. @@ -481,11 +475,10 @@ static int nrs_crrn_req_add(struct ptlrpc_nrs_policy *policy, } /** - * Removes request \a nrq from a CRR-N \a policy instance's set of queued - * requests. - * - * \param[in] policy the policy - * \param[in] nrq the request to remove + * nrs_crrn_req_del() - Removes request @nrq from a CRR-N @policy instance's set + * of queued requests. + * @policy: the policy + * @nrq: the request to remove */ static void nrs_crrn_req_del(struct ptlrpc_nrs_policy *policy, struct ptlrpc_nrs_request *nrq) @@ -506,15 +499,15 @@ static void nrs_crrn_req_del(struct ptlrpc_nrs_policy *policy, binheap_remove(net->cn_binheap, &nrq->nr_node); cli->cc_active--; - /** + /* * If we just deleted the node at the root of the binheap, we may have * to adjust round numbers. */ if (unlikely(is_root)) { - /** Peek at the next request to be served */ + /* Peek at the next request to be served */ struct binheap_node *node = binheap_root(net->cn_binheap); - /** No more requests */ + /* No more requests */ if (unlikely(node == NULL)) { net->cn_round++; } else { @@ -528,11 +521,10 @@ static void nrs_crrn_req_del(struct ptlrpc_nrs_policy *policy, } /** - * Called right after the request \a nrq finishes being handled by CRR-N policy - * instance \a policy. - * - * \param[in] policy the policy that handled the request - * \param[in] nrq the request that was handled + * nrs_crrn_req_stop() - Called right after the request @nrq finishes being + * handled by CRR-N policy instance @policy. + * @policy: the policy that handled the request + * @nrq: the request that was handled */ static void nrs_crrn_req_stop(struct ptlrpc_nrs_policy *policy, struct ptlrpc_nrs_request *nrq) @@ -546,11 +538,9 @@ static void nrs_crrn_req_stop(struct ptlrpc_nrs_policy *policy, libcfs_idstr(&req->rq_peer), nrq->nr_u.crr.cr_round); } -/** - * debugfs interface - */ +/* debugfs interface */ -/** +/* * Retrieves the value of the Round Robin quantum (i.e. the maximum batch size) * for CRR-N policy instances on both the regular and high-priority NRS head * of a service, as long as a policy instance is not in the @@ -560,9 +550,8 @@ static void nrs_crrn_req_stop(struct ptlrpc_nrs_policy *policy, * Quantum values are in # of RPCs, and output is in YAML format. * * For example: - * - * reg_quantum:8 - * hp_quantum:4 + * reg_quantum:8 + * hp_quantum:4 */ static int ptlrpc_lprocfs_nrs_crrn_quantum_seq_show(struct seq_file *m, void *data) @@ -571,7 +560,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_show(struct seq_file *m, void *data) __u16 quantum; int rc; - /** + /* * Perform two separate calls to this as only one of the NRS heads' * policies may be in the ptlrpc_nrs_pol_state::NRS_POL_STATE_STARTED or * ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPING state. @@ -583,7 +572,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_show(struct seq_file *m, void *data) if (rc == 0) { seq_printf(m, NRS_LPROCFS_QUANTUM_NAME_REG "%-5d\n", quantum); - /** + /* * Ignore -ENODEV as the regular NRS head's policy may be in the * ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPED state. */ @@ -600,7 +589,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_show(struct seq_file *m, void *data) true, &quantum); if (rc == 0) { seq_printf(m, NRS_LPROCFS_QUANTUM_NAME_HP"%-5d\n", quantum); - /** + /* * Ignore -ENODEV as the high priority NRS head's policy may be * in the ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPED state. */ @@ -613,6 +602,12 @@ no_hp: } /** + * ptlrpc_lprocfs_nrs_crrn_quantum_seq_write() - Write operation debugfs file + * @file: file pointer to debugfs file + * @buffer: buffer (user space) + * @count: number of bytes in the buffer + * @off: offset + * * Sets the value of the Round Robin quantum (i.e. the maximum batch size) * for CRR-N policy instances of a service. The user can set the quantum size * for the regular or high priority NRS head individually by specifying each @@ -631,6 +626,10 @@ no_hp: * * policy instances in the ptlrpc_nrs_pol_state::NRS_POL_STATE_STOPPED state * are skipped later by nrs_crrn_ctl(). + * + * Return: + * * %>0 on success + * * %negative on failure */ static ssize_t ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, @@ -645,24 +644,22 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, char *val; long quantum_reg; long quantum_hp; - /** lprocfs_find_named_value() modifies its argument, so keep a copy */ + /* lprocfs_find_named_value() modifies its argument, so keep a copy */ size_t count_copy; int rc = 0; int rc2 = 0; - if (count > (sizeof(kernbuf) - 1)) - return -EINVAL; + if (count > (sizeof(kernbuf) - 1)) + return -EINVAL; if (copy_from_user(kernbuf, buffer, count)) return -EFAULT; - kernbuf[count] = '\0'; + kernbuf[count] = '\0'; count_copy = count; - /** - * Check if the regular quantum value has been specified - */ + /* Check if the regular quantum value has been specified */ val = lprocfs_find_named_value(kernbuf, NRS_LPROCFS_QUANTUM_NAME_REG, &count_copy); if (val != kernbuf) { @@ -675,9 +672,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, count_copy = count; - /** - * Check if the high priority quantum value has been specified - */ + /* Check if the high priority quantum value has been specified */ val = lprocfs_find_named_value(kernbuf, NRS_LPROCFS_QUANTUM_NAME_HP, &count_copy); if (val != kernbuf) { @@ -691,7 +686,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, queue |= PTLRPC_NRS_QUEUE_HP; } - /** + /* * If none of the queues has been specified, look for a valid numerical * value */ @@ -714,7 +709,7 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, ((quantum_hp > LPROCFS_NRS_QUANTUM_MAX || quantum_hp <= 0)))) return -EINVAL; - /** + /* * We change the values on regular and HP NRS heads separately, so that * we do not exit early from ptlrpc_nrs_policy_control() with an error * returned by nrs_policy_ctl_locked(), in cases where the user has not @@ -750,12 +745,13 @@ ptlrpc_lprocfs_nrs_crrn_quantum_seq_write(struct file *file, LDEBUGFS_SEQ_FOPS(ptlrpc_lprocfs_nrs_crrn_quantum); /** - * Initializes a CRR-N policy's lprocfs interface for service \a svc - * - * \param[in] svc the service + * nrs_crrn_lprocfs_init() - Initializes a CRR-N policy's lprocfs interface for + * service @svc + * @svc: the service (PTLRPC service) * - * \retval 0 success - * \retval != 0 error + * Return: + * * %0 success + * * %!=0 error */ static int nrs_crrn_lprocfs_init(struct ptlrpc_service *svc) { @@ -774,9 +770,7 @@ static int nrs_crrn_lprocfs_init(struct ptlrpc_service *svc) return 0; } -/** - * CRR-N policy operations - */ +/* CRR-N policy operations */ static const struct ptlrpc_nrs_pol_ops nrs_crrn_ops = { .op_policy_start = nrs_crrn_start, .op_policy_stop = nrs_crrn_stop, @@ -790,15 +784,9 @@ static const struct ptlrpc_nrs_pol_ops nrs_crrn_ops = { .op_lprocfs_init = nrs_crrn_lprocfs_init, }; -/** - * CRR-N policy configuration - */ +/* CRR-N policy configuration */ struct ptlrpc_nrs_pol_conf nrs_conf_crrn = { .nc_name = NRS_POL_NAME_CRRN, .nc_ops = &nrs_crrn_ops, .nc_compat = nrs_policy_compat_all, }; - -/** @} CRR-N policy */ - -/** @} nrs */