From c15fd5c14d3177153fe95ff771751a0975009c51 Mon Sep 17 00:00:00 2001 From: Arshad Hussain Date: Mon, 2 Jun 2025 22:30:21 +0530 Subject: [PATCH] LU-9633 ptlrpc: Add kernel doc style for ptlrpc (11) 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: I757552dc766b50acfbb35838be3d12406de90009 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/59756 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 --- lustre/ptlrpc/sec.c | 275 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 198 insertions(+), 77 deletions(-) diff --git a/lustre/ptlrpc/sec.c b/lustre/ptlrpc/sec.c index 5c70df6..645010a 100644 --- a/lustre/ptlrpc/sec.c +++ b/lustre/ptlrpc/sec.c @@ -313,9 +313,10 @@ void sptlrpc_cli_ctx_put(struct ptlrpc_cli_ctx *ctx, int sync) EXPORT_SYMBOL(sptlrpc_cli_ctx_put); /** - * Expire the client context immediately. + * sptlrpc_cli_ctx_expire() - Expire the client context immediately. + * @ctx: Pointer to a client context struct * - * \pre Caller must hold at least 1 reference on the \a ctx. + * Caller must hold at least 1 reference on the @ctx. */ void sptlrpc_cli_ctx_expire(struct ptlrpc_cli_ctx *ctx) { @@ -325,8 +326,11 @@ void sptlrpc_cli_ctx_expire(struct ptlrpc_cli_ctx *ctx) EXPORT_SYMBOL(sptlrpc_cli_ctx_expire); /** + * sptlrpc_cli_ctx_wakeup() - wake up threads waiting for this client context + * @ctx: Pointer to a client context struct + * * To wake up the threads who are waiting for this client context. Called - * after some status change happened on \a ctx. + * after some status change happened on @ctx. */ void sptlrpc_cli_ctx_wakeup(struct ptlrpc_cli_ctx *ctx) { @@ -372,17 +376,20 @@ static int import_sec_check_expire(struct obd_import *imp) } /** + * import_sec_validate_get() - validates and get security context for a + * client-side PTLRPC import. + * @imp: obd import associated with client + * @sec: client side ptlrpc security [out] + * * Get and validate the client side ptlrpc security facilities from - * \a imp. There is a race condition on client reconnect when the import is + * @imp. There is a race condition on client reconnect when the import is * being destroyed while there are outstanding client bound requests. In * this case do not output any error messages if import secuity is not * found. * - * \param[in] imp obd import associated with client - * \param[out] sec client side ptlrpc security - * - * \retval 0 if security retrieved successfully - * \retval -ve errno if there was a problem + * Return: + * * %0 if security retrieved successfully + * * %errno if there was a problem */ static int import_sec_validate_get(struct obd_import *imp, struct ptlrpc_sec **sec) @@ -415,11 +422,15 @@ static int import_sec_validate_get(struct obd_import *imp, } /** - * Given a \a req, find or allocate an appropriate context for it. + * sptlrpc_req_get_ctx() - Get context fro a given request + * @req: PTLRPC request to get the context + * + * Given a @req, find or allocate an appropriate context for it. * \pre req->rq_cli_ctx == NULL. * - * \retval 0 succeed, and req->rq_cli_ctx is set. - * \retval -ev error number, and req->rq_cli_ctx == NULL. + * Return: + * * %0 succeed, and req->rq_cli_ctx is set. + * * %negative on errorr, and req->rq_cli_ctx == NULL. */ int sptlrpc_req_get_ctx(struct ptlrpc_request *req) { @@ -455,13 +466,15 @@ int sptlrpc_req_get_ctx(struct ptlrpc_request *req) } /** - * Drop the context for \a req. - * \pre req->rq_cli_ctx != NULL. - * \post req->rq_cli_ctx == NULL. + * sptlrpc_req_put_ctx() - Drop the context for @req. + * @req: Request to drop context + * @sync: If sync == 0, this function should return quickly without sleep * - * If \a sync == 0, this function should return quickly without sleep; + * If @sync == 0, this function should return quickly without sleep; * otherwise it might trigger and wait for the whole process of sending * an context-destroying rpc to server. + * \pre req->rq_cli_ctx != NULL. + * \post req->rq_cli_ctx == NULL. */ void sptlrpc_req_put_ctx(struct ptlrpc_request *req, int sync) { @@ -546,9 +559,13 @@ int sptlrpc_req_ctx_switch(struct ptlrpc_request *req, } /** - * If current context of \a req is dead somehow, e.g. we just switched flavor + * sptlrpc_req_replace_dead_ctx() - + * @req: + * @sec: + * + * If current context of @req is dead somehow, e.g. we just switched flavor * thus marked original contexts dead, we'll find a new context for it. if - * no switch is needed, \a req will end up with the same context. + * no switch is needed, @req will end up with the same context. * * \note a request must have a context, to keep other parts of code happy. * In any case of failure during the switching, we must restore the old one. @@ -675,18 +692,20 @@ void req_off_ctx_list(struct ptlrpc_request *req, struct ptlrpc_cli_ctx *ctx) } /** - * To refresh the context of \req, if it's not up-to-date. - * \param timeout - * - == 0: do not wait - * - == MAX_SCHEDULE_TIMEOUT: wait indefinitely - * - > 0: not supported + * sptlrpc_req_refresh_ctx() - refresh the context of @req, if not up-to-date. + * @req: Request to drop context + * @timeout: == 0: do not wait + * == MAX_SCHEDULE_TIMEOUT: wait indefinitely + * >0: not supported * + * To refresh the context of @req, if it's not up-to-date. * The status of the context could be subject to be changed by other threads * at any time. We allow this race, but once we return with 0, the caller will * suppose it's uptodated and keep using it until the owning rpc is done. * - * \retval 0 only if the context is uptodated. - * \retval -ev error number. + * Return: + * * %0 only if the context is uptodated. + * * %negative error number. */ int sptlrpc_req_refresh_ctx(struct ptlrpc_request *req, long timeout) { @@ -895,7 +914,10 @@ int sptlrpc_export_update_ctx(struct obd_export *exp) } /** - * Initialize flavor settings for \a req, according to \a opcode. + * sptlrpc_req_set_flavor() - Initialize flavor settings for @req, according to + * @opcode. + * @req: pointer to struct ptlrpc_request + * @opcode: operation code (ost_cmd) for @req * * \note this could be called in two situations: * - new request from ptlrpc_pre_req(), with proper @opcode @@ -979,8 +1001,8 @@ void sptlrpc_request_out_callback(struct ptlrpc_request *req) req->rq_reqbuf_len = 0; } -/** - * Given an import \a imp, check whether current user has a valid context +/* + * Given an import @imp, check whether current user has a valid context * or not. We may create a new context and try to refresh it, and try * repeatedly try in case of non-fatal errors. Return 0 means success. */ @@ -1034,9 +1056,9 @@ int sptlrpc_import_check_ctx(struct obd_import *imp) RETURN(rc); } -/** +/* * Used by ptlrpc client, to perform the pre-defined security transformation - * upon the request message of \a req. After this function called, + * upon the request message of @req. After this function called, * req->rq_reqmsg is still accessible as clear text. */ int sptlrpc_cli_wrap_request(struct ptlrpc_request *req) @@ -1148,9 +1170,9 @@ static int do_cli_unwrap_reply(struct ptlrpc_request *req) RETURN(rc); } -/** +/* * Used by ptlrpc client, to perform security transformation upon the reply - * message of \a req. After return successfully, req->rq_repmsg points to + * message of @req. After return successfully, req->rq_repmsg points to * the reply message in clear text. * * \pre the reply buffer should have been un-posted from LNet, so nothing is @@ -1182,19 +1204,24 @@ int sptlrpc_cli_unwrap_reply(struct ptlrpc_request *req) } /** + * sptlrpc_cli_unwrap_early_reply() - security transformation for early reply + * @req: pointer to struct ptlrpc_request + * @req_ret: store new duplicate req struct [out] + * * Used by ptlrpc client, to perform security transformation upon the early - * reply message of \a req. We expect the rq_reply_off is 0, and - * rq_nob_received is the early reply size. + * reply message of @req. We expect the rq_reply_off is 0, and rq_nob_received + * is the early reply size. * * Because the receive buffer might be still posted, the reply data might be * changed at any time, no matter we're holding rq_lock or not. For this reason * we allocate a separate ptlrpc_request and reply buffer for early reply * processing. * - * \retval 0 success, \a req_ret is filled with a duplicated ptlrpc_request. - * Later the caller must call sptlrpc_cli_finish_early_reply() on the returned - * \a *req_ret to release it. - * \retval -ev error number, and \a req_ret will not be set. + * Return: + * * %0 success, @req_ret is filled with a duplicated ptlrpc_request. Later the + * caller must call sptlrpc_cli_finish_early_reply() on the returned @req_ret to + * release it. + * * %negative on Failure error number, and @req_ret will not be set. */ int sptlrpc_cli_unwrap_early_reply(struct ptlrpc_request *req, struct ptlrpc_request **req_ret) @@ -1283,10 +1310,10 @@ err_req: RETURN(rc); } -/** - * Used by ptlrpc client, to release a processed early reply \a early_req. +/* + * Used by ptlrpc client, to release a processed early reply @early_req. * - * \pre \a early_req was obtained from calling sptlrpc_cli_unwrap_early_reply(). + * @early_req was obtained from calling sptlrpc_cli_unwrap_early_reply(). */ void sptlrpc_cli_finish_early_reply(struct ptlrpc_request *early_req) { @@ -1517,12 +1544,12 @@ int flavor_equal(struct sptlrpc_flavor *sf1, struct sptlrpc_flavor *sf2) return (memcmp(sf1, sf2, sizeof(*sf1)) == 0); } -/** - * To get an appropriate ptlrpc_sec for the \a imp, according to the current +/* + * To get an appropriate ptlrpc_sec for the @imp, according to the current * configuration. Upon called, imp->imp_sec may or may not be NULL. * - * - regular import: \a svc_ctx should be NULL and \a flvr is ignored; - * - reverse import: \a svc_ctx and \a flvr are obtained from incoming request. + * - regular import: @svc_ctx should be NULL and @flvr is ignored; + * - reverse import: @svc_ctx and @flvr are obtained from incoming request. */ int sptlrpc_import_sec_adapt(struct obd_import *imp, struct ptlrpc_svc_ctx *svc_ctx, @@ -1655,8 +1682,16 @@ void sptlrpc_import_flush_all_ctx(struct obd_import *imp) EXPORT_SYMBOL(sptlrpc_import_flush_all_ctx); /** - * Used by ptlrpc client to allocate request buffer of \a req. Upon return - * successfully, req->rq_reqmsg points to a buffer with size \a msgsize. + * sptlrpc_cli_alloc_reqbuf() - allocate request buffer of @req + * @req: pointer to struct ptlrpc_request + * @msgsize: sizeof of message + * + * Used by ptlrpc client to allocate request buffer of @req. Upon return + * successfully, req->rq_reqmsg points to a buffer with size @msgsize. + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_cli_alloc_reqbuf(struct ptlrpc_request *req, int msgsize) { @@ -1685,7 +1720,10 @@ int sptlrpc_cli_alloc_reqbuf(struct ptlrpc_request *req, int msgsize) } /** - * Used by ptlrpc client to free request buffer of \a req. After this + * sptlrpc_cli_free_reqbuf() - free request buffer of @req + * @req: pointer to struct ptlrpc_request + * + * Used by ptlrpc client to free request buffer of @req. After this * req->rq_reqmsg is set to NULL and should not be accessed anymore. */ void sptlrpc_cli_free_reqbuf(struct ptlrpc_request *req) @@ -1751,13 +1789,22 @@ void _sptlrpc_enlarge_msg_inplace(struct lustre_msg *msg, EXPORT_SYMBOL(_sptlrpc_enlarge_msg_inplace); /** - * Used by ptlrpc client to enlarge the \a segment of request message pointed - * by req->rq_reqmsg to size \a newsize, all previously filled-in data will be + * sptlrpc_cli_enlarge_reqbuf() - Grow a segment size of @req + * @req: pointer to struct ptlrpc_request + * @field: Segment/field to grow + * @newsize: newsize to grow + * + * Used by ptlrpc client to enlarge the @segment of request message pointed + * by req->rq_reqmsg to size @newsize, all previously filled-in data will be * preserved after the enlargement. this must be called after original request * buffer being allocated. * - * \note after this be called, rq_reqmsg and rq_reqlen might have been changed, + * After this be called, rq_reqmsg and rq_reqlen might have been changed, * so caller should refresh its local pointers if needed. + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_cli_enlarge_reqbuf(struct ptlrpc_request *req, const struct req_msg_field *field, @@ -1784,9 +1831,16 @@ int sptlrpc_cli_enlarge_reqbuf(struct ptlrpc_request *req, EXPORT_SYMBOL(sptlrpc_cli_enlarge_reqbuf); /** - * Used by ptlrpc client to allocate reply buffer of \a req. + * sptlrpc_cli_alloc_repbuf() - allocate reply buffer of @req. + * @req: pointer to struct ptlrpc_request to be released + * @msgsize: size of message * - * \note After this, req->rq_repmsg is still not accessible. + * Used by ptlrpc client to allocate reply buffer of @req. + * After this, req->rq_repmsg is still not accessible. + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_cli_alloc_repbuf(struct ptlrpc_request *req, int msgsize) { @@ -1807,7 +1861,10 @@ int sptlrpc_cli_alloc_repbuf(struct ptlrpc_request *req, int msgsize) } /** - * Used by ptlrpc client to free reply buffer of \a req. After this + * sptlrpc_cli_free_repbuf() - free reply buffer of @req. + * @req: pointer to struct ptlrpc_request to be released + * + * Used by ptlrpc client to free reply buffer of @req. After this * req->rq_repmsg is set to NULL and should not be accessed anymore. */ void sptlrpc_cli_free_repbuf(struct ptlrpc_request *req) @@ -2040,9 +2097,15 @@ static int flavor_allowed(struct sptlrpc_flavor *exp, #define EXP_FLVR_UPDATE_EXPIRE (OBD_TIMEOUT_DEFAULT + 10) /** - * Given an export \a exp, check whether the flavor of incoming \a req - * is allowed by the export \a exp. Main logic is about taking care of - * changing configurations. Return 0 means success. + * sptlrpc_target_export_check() - chk if flavor allowed by the export + * @exp: export to check if flavor(security protocol) is suppported + * @req: pointer to struct ptlrpc_request (incoming request from client) + * + * Given an export @exp, check whether the flavor of incoming @req + * is allowed by the export @exp. Main logic is about taking care of + * changing configurations. + * + * Return 0 on success. */ int sptlrpc_target_export_check(struct obd_export *exp, struct ptlrpc_request *req) @@ -2356,15 +2419,19 @@ static int sptlrpc_svc_check_from(struct ptlrpc_request *req, int svc_rc) } /** + * sptlrpc_svc_unwrap_request() - perform transformation upon request message + * @req: pointer to struct ptlrpc_request + * * Used by ptlrpc server, to perform transformation upon request message of - * incoming \a req. This must be the first thing to do with an incoming + * incoming @req. This must be the first thing to do with an incoming * request in ptlrpc layer. * - * \retval SECSVC_OK success, and req->rq_reqmsg point to request message in + * Return: + * * %0 SECSVC_OK success, and req->rq_reqmsg point to request message in * clear text, size is req->rq_reqlen; also req->rq_svc_ctx is set. - * \retval SECSVC_COMPLETE success, the request has been fully processed, and + * * %1 SECSVC_COMPLETE success, the request has been fully processed, and * reply message has been prepared. - * \retval SECSVC_DROP failed, this request should be dropped. + * * %2 SECSVC_DROP failed, this request should be dropped. */ int sptlrpc_svc_unwrap_request(struct ptlrpc_request *req) { @@ -2425,9 +2492,17 @@ int sptlrpc_svc_unwrap_request(struct ptlrpc_request *req) } /** - * Used by ptlrpc server, to allocate reply buffer for \a req. If succeed, + * sptlrpc_svc_alloc_rs() - Allocate reply buffer for @req + * @req: pointer to struct ptlrpc_request + * @msglen: length of message + * + * Used by ptlrpc server, to allocate reply buffer for @req. If succeed, * req->rq_reply_state is set, and req->rq_reply_state->rs_msg point to - * a buffer of \a msglen size. + * a buffer of @msglen size. + * + * Return: + * * %0 on success + * * %errno on failure */ int sptlrpc_svc_alloc_rs(struct ptlrpc_request *req, int msglen) { @@ -2475,11 +2550,11 @@ int sptlrpc_svc_alloc_rs(struct ptlrpc_request *req, int msglen) RETURN(rc); } -/** +/* * Used by ptlrpc server, to perform transformation upon reply message. * - * \post req->rq_reply_off is set to approriate server-controlled reply offset. - * \post req->rq_repmsg and req->rq_reply_state->rs_msg becomes inaccessible. + * req->rq_reply_off is set to approriate server-controlled reply offset. + * req->rq_repmsg and req->rq_reply_state->rs_msg becomes inaccessible. */ int sptlrpc_svc_wrap_reply(struct ptlrpc_request *req) { @@ -2501,7 +2576,8 @@ int sptlrpc_svc_wrap_reply(struct ptlrpc_request *req) } /** - * Used by ptlrpc server, to free reply_state. + * sptlrpc_svc_free_rs() - Used by ptlrpc server, to free reply_state. + * @rs: pointer to reply state structure */ void sptlrpc_svc_free_rs(struct ptlrpc_reply_state *rs) { @@ -2565,8 +2641,14 @@ EXPORT_SYMBOL(sptlrpc_svc_ctx_invalidate); */ /** - * Perform transformation upon bulk data pointed by \a desc. This is called - * before transforming the request message. + * sptlrpc_cli_wrap_bulk() - Perform transformation upon bulk data pointed + * by @desc. This is called before transforming the request message. + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_cli_wrap_bulk(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc) @@ -2586,8 +2668,18 @@ int sptlrpc_cli_wrap_bulk(struct ptlrpc_request *req, EXPORT_SYMBOL(sptlrpc_cli_wrap_bulk); /** - * This is called after unwrap the reply message. - * return nob of actual plain text size received, or error code. + * sptlrpc_cli_unwrap_bulk_read() - unwrap bulk reply data + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * @nob: bytes GOT/PUT + * + * Unwrap bulk reply data. This is called after wrapping RPC reply message. + * This is called after unwrap the reply message. return nob of actual plain + * text size received, or error code. + * + * Return: + * * %+ve nob of actual bulk data in clear text. + * % %-ve error code. */ int sptlrpc_cli_unwrap_bulk_read(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc, @@ -2612,8 +2704,15 @@ int sptlrpc_cli_unwrap_bulk_read(struct ptlrpc_request *req, EXPORT_SYMBOL(sptlrpc_cli_unwrap_bulk_read); /** - * This is called after unwrap the reply message. - * return 0 for success or error code. + * sptlrpc_cli_unwrap_bulk_write() - transform upon incoming bulk write(client) + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * + * This is called after unwrap the reply message from server. + * + * Return: + * * %0 on success + * * %ETIMEOUT on failure */ int sptlrpc_cli_unwrap_bulk_write(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc) @@ -2649,7 +2748,15 @@ EXPORT_SYMBOL(sptlrpc_cli_unwrap_bulk_write); #ifdef HAVE_SERVER_SUPPORT /** - * Performe transformation upon outgoing bulk read. + * sptlrpc_svc_wrap_bulk() - Performe transformation upon outgoing bulk read + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * + * Transform data before sending bulk data (encrypt) + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_svc_wrap_bulk(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc) @@ -2670,7 +2777,15 @@ int sptlrpc_svc_wrap_bulk(struct ptlrpc_request *req, EXPORT_SYMBOL(sptlrpc_svc_wrap_bulk); /** - * Performe transformation upon incoming bulk write. + * sptlrpc_svc_unwrap_bulk() - Performe transformation upon incoming bulk write + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * + * Transform data after getting bulk data (decrypt) + * + * Return: + * * %0 on success + * * %ETIMEOUT on failure */ int sptlrpc_svc_unwrap_bulk(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc) @@ -2709,7 +2824,13 @@ int sptlrpc_svc_unwrap_bulk(struct ptlrpc_request *req, EXPORT_SYMBOL(sptlrpc_svc_unwrap_bulk); /** - * Prepare buffers for incoming bulk write. + * sptlrpc_svc_prep_bulk() - Prepare buffers for incoming bulk write. + * @req: pointer to struct ptlrpc_request + * @desc: bulk descriptor (data transfer) + * + * Return: + * * %0 on success + * * %negative on failure */ int sptlrpc_svc_prep_bulk(struct ptlrpc_request *req, struct ptlrpc_bulk_desc *desc) @@ -2905,7 +3026,7 @@ int bulk_sec_desc_unpack(struct lustre_msg *msg, int offset, int swabbed) EXPORT_SYMBOL(bulk_sec_desc_unpack); /* - * Compute the checksum of an RPC buffer payload. If the return \a buflen + * Compute the checksum of an RPC buffer payload. If the return @buflen * is not large enough, truncate the result to fit so that it is possible * to use a hash function with a large hash space, but only use a part of * the resulting hash. -- 1.8.3.1