From: Arshad Hussain Date: Tue, 15 Apr 2025 18:16:58 +0000 (+0530) Subject: LU-9633 ptlrpc: Add kernel doc style for ptlrpc (1) X-Git-Tag: 2.16.55~57 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=d697b1bf5a386545f5b5b2832592074f457b6b0c;p=fs%2Flustre-release.git LU-9633 ptlrpc: Add kernel doc style for ptlrpc (1) 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: I5d3cfd1f1d3af9810d846ed055fac5029f96bc4a Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58857 Tested-by: jenkins Tested-by: Maloo Reviewed-by: James Simmons Reviewed-by: Anjus George Reviewed-by: Oleg Drokin --- diff --git a/lustre/ptlrpc/client.c b/lustre/ptlrpc/client.c index 9b01015..6a84e11 100644 --- a/lustre/ptlrpc/client.c +++ b/lustre/ptlrpc/client.c @@ -92,7 +92,11 @@ static int ptlrpcd_check_work(struct ptlrpc_request *req); static int ptlrpc_unregister_reply(struct ptlrpc_request *request, int async); /** - * Initialize passed in client structure \a cl. + * ptlrpc_init_client() - Initialize passed in client structure @cl + * @req_portal: request portal(sending request) number + * @rep_portal: reply portal(receiving request) number + * @name: name of the client + * @cl: struct pltrpc_client which is being initilize [out] */ void ptlrpc_init_client(int req_portal, int rep_portal, const char *name, struct ptlrpc_client *cl) @@ -104,7 +108,12 @@ void ptlrpc_init_client(int req_portal, int rep_portal, const char *name, EXPORT_SYMBOL(ptlrpc_init_client); /** - * Return PortalRPC connection for remore uud \a uuid + * ptlrpc_uuid_to_connection() - Return PortalRPC connection for remote uuid + * @uuid + * @uuid: remote @uuid to connect + * @refnet: reference network + * + * Return struct ptlrpc_connection on success and error pointer on failure */ struct ptlrpc_connection *ptlrpc_uuid_to_connection(struct obd_uuid *uuid, u32 refnet) @@ -136,7 +145,13 @@ struct ptlrpc_connection *ptlrpc_uuid_to_connection(struct obd_uuid *uuid, } /** - * Allocate and initialize new bulk descriptor on the sender. + * ptlrpc_new_bulk() - Allocate and initialize new bulk descriptor on the sender + * @nfrags: (nfrags * pages) done during this bulk transfer + * @max_brw: maximum read/write which can be done during this bulk transfer + * @type: type of bulk transfer (PTLRPC_BULK_*) + * @portal: Endpoint to do bulk transfer + * @ops: callbacks function for this bulk routine + * * Returns pointer to the descriptor or NULL on error. */ struct ptlrpc_bulk_desc *ptlrpc_new_bulk(unsigned int nfrags, @@ -190,10 +205,17 @@ out: return NULL; } -/** - * Prepare bulk descriptor for specified outgoing request \a req that - * can fit \a nfrags * pages. \a type is bulk type. \a portal is where - * the bulk to be sent. Used on client-side. +/* + * ptlrpc_prep_bulk_imp() - Prepare bulk descriptor(wrapper to @ptlrpc_new_bulk) + * @req: outgoint request + * @nfrags: (nfrags * pages) done during this bulk transfer + * @max_brw: maximum read/write which can be done during this bulk transfer + * @type: type of bulk transfer (PTLRPC_BULK_*) + * @portal: Endpoint to do bulk transfer + * @ops: callbacks function for this bulk routine + * + * This is used on client side. + * * Returns pointer to newly allocatrd initialized bulk descriptor or NULL on * error. */ @@ -308,8 +330,10 @@ void ptlrpc_free_bulk(struct ptlrpc_bulk_desc *desc) EXPORT_SYMBOL(ptlrpc_free_bulk); /** - * Set server timelimit for this req, i.e. how long are we willing to wait - * for reply before timing out this request. + * ptlrpc_at_set_req_timeout() - Set server timelimit for this req + * @req: Request for which timeout is being set + * + * How long are we willing to wait for reply before timing out this request. */ void ptlrpc_at_set_req_timeout(struct ptlrpc_request *req) { @@ -387,12 +411,13 @@ static void ptlrpc_at_adj_service(struct ptlrpc_request *req, } /** - * Returns Expected network latency per remote node (secs). - * - * \param[in] req ptlrpc request + * ptlrpc_at_get_net_latency() - Returns Expected network latency per remote + * node (secs) + * @req: ptlrpc request * - * \retval 0 if AT(Adaptive Timeout) is off - * \retval >0 (iat_net_latency) latency per node + * Return: + * * %0 if AT(Adaptive Timeout) is off + * * %>0 (iat_net_latency) latency per node */ int ptlrpc_at_get_net_latency(struct ptlrpc_request *req) { @@ -471,7 +496,7 @@ static int unpack_reply(struct ptlrpc_request *req) return 0; } -/** +/* * Handle an early reply message, called with the rq_lock held. * If anything goes wrong just ignore it - same as if it never happened */ @@ -567,8 +592,10 @@ void ptlrpc_request_cache_free(struct ptlrpc_request *req) } /** - * Wind down request pool \a pool. - * Frees all requests from the pool too + * ptlrpc_free_rq_pool() - Frees all requests from the pool. + * @pool: struct ptlrpc_request_pool (empty preallocated requests) + * + * Also, Wind down request pool @pool */ void ptlrpc_free_rq_pool(struct ptlrpc_request_pool *pool) { @@ -592,7 +619,12 @@ void ptlrpc_free_rq_pool(struct ptlrpc_request_pool *pool) EXPORT_SYMBOL(ptlrpc_free_rq_pool); /** - * Allocates, initializes and adds \a num_rq requests to the pool \a pool + * ptlrpc_add_rqs_to_pool() - Allocates, initializes & adds @num_rq requests + * to the pool @pool + * @pool: pool where request should be added + * @num_rq: count of request to add to @pool + * + * Return total number of requests successfully added to the pool. */ int ptlrpc_add_rqs_to_pool(struct ptlrpc_request_pool *pool, int num_rq) { @@ -632,11 +664,13 @@ int ptlrpc_add_rqs_to_pool(struct ptlrpc_request_pool *pool, int num_rq) EXPORT_SYMBOL(ptlrpc_add_rqs_to_pool); /** - * Create and initialize new request pool with given attributes: - * \a num_rq - initial number of requests to create for the pool - * \a msgsize - maximum message size possible for requests in thid pool - * \a populate_pool - function to be called when more requests need to be added - * to the pool + * ptlrpc_init_rq_pool() - Create and initialize new request pool with given + * attributes + * @num_rq: initial number of requests to create for the pool + * @msgsize: maximum message size possible for requests in thid pool + * @populate_pool: function to be called when more requests need to be added + * to the pool + * * Returns pointer to newly created pool or NULL on error. */ struct ptlrpc_request_pool * @@ -664,8 +698,9 @@ ptlrpc_init_rq_pool(int num_rq, int msgsize, } EXPORT_SYMBOL(ptlrpc_init_rq_pool); -/** - * Fetches one request from pool \a pool +/* + * Fetches one request from pool @pool. + * Called from ptlrpc_request_alloc_internal */ static struct ptlrpc_request * ptlrpc_prep_req_from_pool(struct ptlrpc_request_pool *pool) @@ -706,8 +741,8 @@ ptlrpc_prep_req_from_pool(struct ptlrpc_request_pool *pool) return request; } -/** - * Returns freed \a request to pool. +/* + * Returns freed @request to pool. */ static void __ptlrpc_free_req_to_pool(struct ptlrpc_request *request) { @@ -893,8 +928,15 @@ out_free: EXPORT_SYMBOL(ptlrpc_request_bufs_pack); /** - * Pack request buffers for network transfer, performing necessary encryption - * steps if necessary. + * ptlrpc_request_pack() - Pack request buffers for network transfer, performing + * necessary encryption steps if necessary. + * @request: request that needs to be packed + * @version: protocol version + * @opcode: operation type + * + * Return: + * * %0 on success + * * %negative value on failure */ int ptlrpc_request_pack(struct ptlrpc_request *request, __u32 version, int opcode) @@ -903,9 +945,11 @@ int ptlrpc_request_pack(struct ptlrpc_request *request, } EXPORT_SYMBOL(ptlrpc_request_pack); -/** - * Helper function to allocate new request on import \a imp - * and possibly using existing request from pool \a pool if provided. +/* + * __ptlrpc_request_alloc() - Helper function to allocate new request on import. + * @imp: request allocated for this import + * @pool: struct ptlrpc_request_pool (empty preallocated requests). NULL if no + * * Returns allocated request structure with import field filled or * NULL on error. */ @@ -966,9 +1010,15 @@ static int ptlrpc_reconnect_if_idle(struct obd_import *imp) } /** - * Helper function for creating a request. + * ptlrpc_request_alloc_internal() - Helper function for creating a request. + * @imp: request allocated for this import + * @pool: struct ptlrpc_request_pool (empty preallocated requests). NULL if no + * pool should be used + * @format: pointer to struct req_format + * * Calls __ptlrpc_request_alloc to allocate new request sturcture and inits - * buffer structures according to capsule template \a format. + * buffer structures according to capsule template @format + * * Returns allocated request structure pointer or NULL on error. */ static struct ptlrpc_request * @@ -998,8 +1048,13 @@ ptlrpc_request_alloc_internal(struct obd_import *imp, } /** - * Allocate new request structure for import \a imp and initialize its - * buffer structure according to capsule template \a format. + * ptlrpc_request_alloc() - Allocate new request structure for import @imp + * @imp: pointer to struct obd_import + * @format: pointer to struct req_format + * + * Also, initialize its buffer structure according to capsule template @format. + * + * Returns allocated request on success, and -errno on failure. */ struct ptlrpc_request *ptlrpc_request_alloc(struct obd_import *imp, const struct req_format *format) @@ -1009,8 +1064,16 @@ struct ptlrpc_request *ptlrpc_request_alloc(struct obd_import *imp, EXPORT_SYMBOL(ptlrpc_request_alloc); /** - * Allocate new request structure for import \a imp from pool \a pool and - * initialize its buffer structure according to capsule template \a format. + * ptlrpc_request_alloc_pool() - Allocate new request struct for import + * @imp: request allocated for this import + * @pool: struct ptlrpc_request_pool (empty preallocated requests). NULL if no + * pool should be used + * @format: pointer to struct req_format + * + * Allocate new request structure for import @imp from pool @pool and + * initialize its buffer structure according to capsule template @format. + * + * Returns allocated request structure pointer or NULL on error. */ struct ptlrpc_request * ptlrpc_request_alloc_pool(struct obd_import *imp, @@ -1022,8 +1085,11 @@ ptlrpc_request_alloc_pool(struct obd_import *imp, EXPORT_SYMBOL(ptlrpc_request_alloc_pool); /** - * For requests not from pool, free memory of the request structure. - * For requests obtained from a pool earlier, return request back to pool. + * ptlrpc_request_free() - Free mem of the request struct + * @request: Lustre request(RPC) + * + * For requests not from pool, free memory of the request structure. For + * requests obtained from a pool earlier, return request back to pool. */ void ptlrpc_request_free(struct ptlrpc_request *request) { @@ -1035,10 +1101,15 @@ void ptlrpc_request_free(struct ptlrpc_request *request) EXPORT_SYMBOL(ptlrpc_request_free); /** - * Allocate new request for operation \a opcode and immediatelly pack it for - * network transfer. - * Only used for simple requests like OBD_PING where the only important - * part of the request is operation itself. + * ptlrpc_request_alloc_pack() - Allocate new rquest for operation + * @imp: request to allocate for this import + * @format: pointer to struct req_format + * @version: protocol version + * @opcode: operation type + * + * Allocate new request for operation @opcode and immediatelly pack it for + * network transfer. Only used for simple requests like OBD_PING where the only + * important part of the request is operation itself. * * Returns allocated request on success, and -errno on failure. */ @@ -1064,6 +1135,8 @@ struct ptlrpc_request *ptlrpc_request_alloc_pack(struct obd_import *imp, EXPORT_SYMBOL(ptlrpc_request_alloc_pack); /** + * ptlrpc_prep_set() - Allocate and initialize new request structure + * * Allocate and initialize new request set structure on the current CPT. * Returns a pointer to the newly allocated set structure or NULL on error. */ @@ -1094,11 +1167,17 @@ struct ptlrpc_request_set *ptlrpc_prep_set(void) EXPORT_SYMBOL(ptlrpc_prep_set); /** + * ptlrpc_prep_fcset() - Allocate and initialize new request set + * @max: max in-flight request + * @func: Function to add more request + * @arg: Additional arguments + * * Allocate and initialize new request set structure with flow control * extension. This extension allows to control the number of requests in-flight * for the whole set. A callback function to generate requests must be provided * and the request set will keep the number of requests sent over the wire to * @max_inflight. + * * Returns a pointer to the newly allocated set structure or NULL on error. */ struct ptlrpc_request_set *ptlrpc_prep_fcset(int max, set_producer_func func, @@ -1119,12 +1198,14 @@ struct ptlrpc_request_set *ptlrpc_prep_fcset(int max, set_producer_func func, } /** + * ptlrpc_set_destroy() - Free request set structure + * @set: ptlrpc_request_set to be destroyed + * * Wind down and free request set structure previously allocated with - * ptlrpc_prep_set. - * Ensures that all requests on the set have completed and removes - * all requests from the request list in a set. - * If any unsent request happen to be on the list, pretends that they got - * an error in flight and calls their completion handler. + * ptlrpc_prep_set. Ensures that all requests on the set have completed and + * removes all requests from the request list in a set. If any unsent request + * happen to be on the list, pretends that they got an error in flight and calls + * their completion handler. */ void ptlrpc_set_destroy(struct ptlrpc_request_set *set) { @@ -1174,8 +1255,10 @@ void ptlrpc_set_destroy(struct ptlrpc_request_set *set) EXPORT_SYMBOL(ptlrpc_set_destroy); /** - * Add a new request to the general purpose request set. + * ptlrpc_set_add_req() - Add a new request to the general purpose request set. * Assumes request reference from the caller. + * @set: request set(group of multiple RPCs) where request will be added + * @req: Request to be added */ void ptlrpc_set_add_req(struct ptlrpc_request_set *set, struct ptlrpc_request *req) @@ -1210,9 +1293,12 @@ void ptlrpc_set_add_req(struct ptlrpc_request_set *set, EXPORT_SYMBOL(ptlrpc_set_add_req); /** - * Add a request to a request with dedicated server thread - * and wake the thread to make any necessary processing. - * Currently only used for ptlrpcd. + * ptlrpc_set_add_new_req() - Add a request to a request set + * @pc: pointer to ptlrpcd_ctl (dedicated server thread, ie ptlrpcd) + * @req: request to get added + * + * Add a request to a request with dedicated server thread (ptlrpcd) and wake + * the thread to make any necessary processing. Currently only used for ptlrpcd. */ void ptlrpc_set_add_new_req(struct ptlrpcd_ctl *pc, struct ptlrpc_request *req) @@ -1248,14 +1334,19 @@ void ptlrpc_set_add_new_req(struct ptlrpcd_ctl *pc, } /** + * ptlrpc_import_delay_req() - Determine if the request can be sent + * @imp: import this request is tied to + * @req: request to be sent + * @status: error code [out] + * * Based on the current state of the import, determine if the request * can be sent, is an error, or should be delayed. + * Note: The imp->imp_lock must be held. * - * Returns true if this request should be delayed. If false, and - * *status is set, then the request can not be sent and *status is the - * error code. If false and status is 0, then request can be sent. - * - * The imp->imp_lock must be held. + * Return + * * %1 if this request should be delayed + * * %0 request cannot be send and status is non-zoro(holds error code) + * * %0 request can be send and status is 0 */ static int ptlrpc_import_delay_req(struct obd_import *imp, struct ptlrpc_request *req, int *status) @@ -1324,13 +1415,16 @@ static int ptlrpc_import_delay_req(struct obd_import *imp, } /** - * Decide if the error message should be printed to the console or not. - * Makes its decision based on request type, status, and failure frequency. - * - * \param[in] req request that failed and may need a console message + * ptlrpc_console_allow() - Decide if the error message should be printed to + * the console or not. Makes its decision based on request type, status, and + * failure frequency. + * @req: request that failed and may need a console message + * @opc: OST requests type + * @err: Error associated with @req * - * \retval false if no message should be printed - * \retval true if console message should be printed + * Return: + * * %false if no message should be printed + * * %true if console message should be printed */ static bool ptlrpc_console_allow(struct ptlrpc_request *req, __u32 opc, int err) { @@ -1367,7 +1461,7 @@ static bool ptlrpc_console_allow(struct ptlrpc_request *req, __u32 opc, int err) return true; } -/** +/* * Check request processing status. * Returns the status. */ @@ -1396,7 +1490,7 @@ static int ptlrpc_check_status(struct ptlrpc_request *req) RETURN(rc); } -/** +/* * save pre-versions of objects into request for replay. * Versions are obtained from server reply. * used for VBR. @@ -1437,12 +1531,12 @@ __u64 ptlrpc_known_replied_xid(struct obd_import *imp) return req->rq_xid - 1; } -/** - * Callback function called when client receives RPC reply for \a req. - * Returns 0 on success or error code. - * The return alue would be assigned to req->rq_status by the caller +/* + * Callback function called when client receives RPC reply for req. + * The return value would be assigned to req->rq_status by the caller * as request processing status. * This function also decides if the request needs to be saved for later replay. + * Returns 0 on success or error code. */ static int after_reply(struct ptlrpc_request *req) { @@ -1659,9 +1753,11 @@ static int after_reply(struct ptlrpc_request *req) } /** - * Helper function to send request \a req over the network for the first time - * Also adjusts request phase. - * Returns 0 on success or error code. + * ptlrpc_send_new_req() - Helper function to send request @req over the network + * for the first time. Also adjusts request phase. + * @req: request to be added + * + * Returns 0 on success or error code on failure */ static int ptlrpc_send_new_req(struct ptlrpc_request *req) { @@ -1827,12 +1923,18 @@ static inline int ptlrpc_set_producer(struct ptlrpc_request_set *set) } /** - * this sends any unsent RPCs in \a set and returns 1 if all are sent - * and no more replies are expected. - * (it is possible to get less replies than requests sent e.g. due to timed out - * requests or requests that we had trouble to send out) + * ptlrpc_check_set() - sends any unsent RPCs in set + * @env: execution environment + * @set: ptlrpc_request_set all request in a set + * + * This sends any unsent RPCs in @set and returns 1 if all are sent + * and no more replies are expected. (it is possible to get less replies than + * requests sent e.g. due to timed out requests or requests that we had trouble + * to send out) * * NOTE: This function contains a potential schedule point (cond_resched()). + * + * Returns 0 on success or error code otherwise. */ int ptlrpc_check_set(const struct lu_env *env, struct ptlrpc_request_set *set) { @@ -2316,8 +2418,11 @@ interpret: EXPORT_SYMBOL(ptlrpc_check_set); /** - * Time out request \a req. is \a async_unlink is set, that means do not wait - * until LNet actually confirms network buffer unlinking. + * ptlrpc_expire_one_request() - Time out request + * @req: request to expire + * @async_unlink: if true, that means do not wait. Else if false, wait until + * LNet actually confirms network buffer unlinking. + * * Return 1 if we should give up further retrying attempts or 0 otherwise. */ int ptlrpc_expire_one_request(struct ptlrpc_request *req, int async_unlink) @@ -2398,7 +2503,7 @@ int ptlrpc_expire_one_request(struct ptlrpc_request *req, int async_unlink) RETURN(rc); } -/** +/* * Time out all uncompleted requests in request set pointed by \a data * This is called when a wait times out. */ @@ -2442,7 +2547,7 @@ void ptlrpc_expired_set(struct ptlrpc_request_set *set) } } -/** +/* * Interrupts (sets interrupted flag) all uncompleted requests in * a set \a data. This is called when a wait_event is interrupted * by a signal. @@ -2469,7 +2574,7 @@ static void ptlrpc_interrupted_set(struct ptlrpc_request_set *set) } } -/** +/* * Get the smallest timeout in the set; this does NOT set a timeout. */ time64_t ptlrpc_set_next_timeout(struct ptlrpc_request_set *set) @@ -2511,9 +2616,14 @@ time64_t ptlrpc_set_next_timeout(struct ptlrpc_request_set *set) } /** + * ptlrpc_set_wait() - Send all unset request + * @env: execution environment + * @set: ptlrpc_request_set all request in a set + * * Send all unset request from the set and then wait untill all * requests in the set complete (either get a reply, timeout, get an * error or otherwise be interrupted). + * * Returns 0 on success or error code otherwise. */ int ptlrpc_set_wait(const struct lu_env *env, struct ptlrpc_request_set *set) @@ -2618,7 +2728,7 @@ int ptlrpc_set_wait(const struct lu_env *env, struct ptlrpc_request_set *set) } EXPORT_SYMBOL(ptlrpc_set_wait); -/** +/* * Helper fuction for request freeing. * Called when request count reached zero and request needs to be freed. * Removes request from all sorts of sending/replay lists it might be on, @@ -2690,13 +2800,15 @@ static void __ptlrpc_free_req(struct ptlrpc_request *request, int locked) } /** - * Helper function - * Drops one reference count for request \a request. - * \a locked set indicates that caller holds import imp_lock. + * __ptlrpc_req_put() - Drops one reference count for request @request. + * @request: Lustre request(RPC) + * @locked: set indicates that caller holds import imp_lock. + * * Frees the request whe reference count reaches zero. * - * \retval 1 the request is freed - * \retval 0 some others still hold references on the request + * Return: + * * %1 the request is freed + * * %0 some others still hold references on the request */ static int __ptlrpc_req_put(struct ptlrpc_request *request, int locked) { @@ -2746,7 +2858,7 @@ static int __ptlrpc_req_put(struct ptlrpc_request *request, int locked) RETURN(!count); } -/** +/* * Drop one request reference. Must be called with import imp_lock held. * When reference count drops to zero, request is freed. */ @@ -2757,7 +2869,8 @@ void ptlrpc_req_put_with_imp_lock(struct ptlrpc_request *request) } /** - * Drops one reference count for a request. + * ptlrpc_req_put() - Drops one reference count for a request. + * @request: Request to drop reference */ void ptlrpc_req_put(struct ptlrpc_request *request) { @@ -2767,7 +2880,10 @@ EXPORT_SYMBOL(ptlrpc_req_put); /** - * Returns xid of a \a request + * ptlrpc_req_xid() - Returns XID of a @request + * @request: return XID for this request + * + * Returns xid of a @request */ __u64 ptlrpc_req_xid(struct ptlrpc_request *request) { @@ -2776,10 +2892,16 @@ __u64 ptlrpc_req_xid(struct ptlrpc_request *request) EXPORT_SYMBOL(ptlrpc_req_xid); /** - * Disengage the client's reply buffer from the network + * ptlrpc_unregister_reply() - Disengage the client's reply buffer from the + * network + * @request: request to unregister + * @async: If true, do not wait for unregister to finish + * + * Disengage the client's reply buffer from the network. * NB does _NOT_ unregister any client-side bulk. * IDEMPOTENT, but _not_ safe against concurrent callers. * The request owner (i.e. the thread doing the I/O) must call... + * * Returns 0 on success or 1 if unregistering cannot be made. */ static int ptlrpc_unregister_reply(struct ptlrpc_request *request, int async) @@ -2866,7 +2988,11 @@ static void ptlrpc_free_request(struct ptlrpc_request *req) } /** - * the request is committed and dropped from the replay list of its import + * ptlrpc_request_committed() - Commit request and free + * @req: request to be committed + * @force: @req should be forced committed (Not check trans number) + * + * The request is committed and dropped from the replay list of its import */ void ptlrpc_request_committed(struct ptlrpc_request *req, int force) { @@ -2889,12 +3015,15 @@ void ptlrpc_request_committed(struct ptlrpc_request *req, int force) EXPORT_SYMBOL(ptlrpc_request_committed); /** - * Iterates through replay_list on import and prunes - * all requests have transno smaller than last_committed for the - * import and don't have rq_replay set. + * ptlrpc_free_committed() - Iterates through replay_list on import and prunes + * @imp: pointer to obd_import (import where replay list is being processed) + * + * Iterates through replay_list on import and prunes all requests have transno + * smaller than last_committed for the import and don't have rq_replay set. * Since requests are sorted in transno order, stops when meeting first * transno bigger than last_committed. - * caller must hold imp->imp_lock + * + * Note: caller must hold imp->imp_lock */ void ptlrpc_free_committed(struct obd_import *imp) { @@ -3038,7 +3167,7 @@ out: EXIT; } -/** +/* * Schedule previously sent request for resend. * For bulk requests we assign new xid (to avoid problems with * lost replies and therefore several transfers landing into same buffer @@ -3082,7 +3211,7 @@ void ptlrpc_restart_req(struct ptlrpc_request *req) spin_unlock(&req->rq_lock); } -/** +/* * Grab additional reference on a request \a req */ struct ptlrpc_request *ptlrpc_request_addref(struct ptlrpc_request *req) @@ -3093,7 +3222,7 @@ struct ptlrpc_request *ptlrpc_request_addref(struct ptlrpc_request *req) } EXPORT_SYMBOL(ptlrpc_request_addref); -/** +/* * Add a request to import replay_list. * Must be called under imp_lock */ @@ -3154,8 +3283,10 @@ void ptlrpc_retain_replayable_request(struct ptlrpc_request *req, } /** - * Send request and wait until it completes. - * Returns request processing status. + * ptlrpc_queue_wait() - Send request and wait until it completes. + * @req: request to be sent and waited + * + * Return 0 on success or error code otherwise. */ int ptlrpc_queue_wait(struct ptlrpc_request *req) { @@ -3185,7 +3316,7 @@ int ptlrpc_queue_wait(struct ptlrpc_request *req) } EXPORT_SYMBOL(ptlrpc_queue_wait); -/** +/* * Callback used for replayed requests reply processing. * In case of successful reply calls registered request replay callback. * In case of error restart replay process. @@ -3330,8 +3461,10 @@ static int ptlrpc_replay_interpret(const struct lu_env *env, } /** - * Prepares and queues request for replay. - * Adds it to ptlrpcd queue for actual sending. + * ptlrpc_replay_req() - Prepares and queues request for replay. Adds it to + * ptlrpcd queue for actual sending. + * @req: request to replay + * * Returns 0 on success. */ int ptlrpc_replay_req(struct ptlrpc_request *req) @@ -3375,7 +3508,10 @@ int ptlrpc_replay_req(struct ptlrpc_request *req) } /** - * Aborts all in-flight request on import \a imp sending and delayed lists + * ptlrpc_abort_inflight() - Aborts all in-flight request on import. + * @imp: import where request will be aborted + * + * Aborts all in-flight request on import @imp sending and delayed lists */ void ptlrpc_abort_inflight(struct obd_import *imp) { @@ -3429,7 +3565,8 @@ void ptlrpc_abort_inflight(struct obd_import *imp) } /** - * Abort all uncompleted requests in request set \a set + * ptlrpc_abort_set() - Abort all uncompleted requests in request set @set + * @set: ptlrpc_request_set to be aborted */ void ptlrpc_abort_set(struct ptlrpc_request_set *set) { @@ -3451,7 +3588,7 @@ void ptlrpc_abort_set(struct ptlrpc_request_set *set) } } -/** +/* * Initialize the XID for the node. This is common among all requests on * this node, and only requires the property that it is monotonically * increasing. It does not need to be sequential. Since this is also used @@ -3487,7 +3624,7 @@ void ptlrpc_init_xid(void) atomic64_set(&ptlrpc_last_xid, xid); } -/** +/* * Increase xid and returns resulting new value to the caller. * * Multi-bulk BRW RPCs consume multiple XIDs for each bulk transfer, starting @@ -3504,7 +3641,7 @@ __u64 ptlrpc_next_xid(void) return atomic64_add_return(PTLRPC_BULK_OPS_COUNT, &ptlrpc_last_xid); } -/** +/* * If request has a new allocated XID (new request or EINPROGRESS resend), * use this XID as matchbits of bulk, otherwise allocate a new matchbits for * request to ensure previous bulk fails and avoid problems with lost replies @@ -3582,7 +3719,9 @@ void ptlrpc_set_mbits(struct ptlrpc_request *req) } /** - * Get a glimpse at what next xid value might have been. + * ptlrpc_sample_next_xid() - Get a glimpse at what next xid value might have + * been. + * * Returns possible next xid. */ __u64 ptlrpc_sample_next_xid(void) @@ -3592,7 +3731,9 @@ __u64 ptlrpc_sample_next_xid(void) EXPORT_SYMBOL(ptlrpc_sample_next_xid); /** - * Functions for operating ptlrpc workers. + * struct ptlrpc_work_async_args - Functions for operating ptlrpc workers. + * @cb: callback function + * @cbdata: additional data * * A ptlrpc work is a function which will be running inside ptlrpc context. * The callback shouldn't sleep otherwise it will block that ptlrpcd thread. @@ -3655,7 +3796,10 @@ static int ptlrpcd_check_work(struct ptlrpc_request *req) } /** - * Create a work for ptlrpc. + * ptlrpcd_alloc_work() - Create a work for ptlrpc. + * @imp: pointer to obd_import struct + * @cb: callback function + * @cbdata: additional data */ void *ptlrpcd_alloc_work(struct obd_import *imp, int (*cb)(const struct lu_env *, void *), void *cbdata)