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)
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)
}
/**
- * 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,
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.
*/
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)
{
}
/**
- * 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)
{
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
*/
}
/**
- * 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)
{
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)
{
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 *
}
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)
return request;
}
-/**
- * Returns freed \a request to pool.
+/*
+ * Returns freed @request to pool.
*/
static void __ptlrpc_free_req_to_pool(struct ptlrpc_request *request)
{
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)
}
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.
*/
}
/**
- * 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 *
}
/**
- * 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)
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,
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)
{
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.
*/
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.
*/
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,
}
/**
+ * 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)
{
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)
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)
}
/**
+ * 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)
}
/**
- * 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)
{
return true;
}
-/**
+/*
* Check request processing status.
* Returns the status.
*/
RETURN(rc);
}
-/**
+/*
* save pre-versions of objects into request for replay.
* Versions are obtained from server reply.
* used for VBR.
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)
{
}
/**
- * 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)
{
}
/**
- * 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)
{
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)
RETURN(rc);
}
-/**
+/*
* Time out all uncompleted requests in request set pointed by \a data
* This is called when a wait times out.
*/
}
}
-/**
+/*
* Interrupts (sets interrupted flag) all uncompleted requests in
* a set \a data. This is called when a wait_event is interrupted
* by a signal.
}
}
-/**
+/*
* Get the smallest timeout in the set; this does NOT set a timeout.
*/
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)
}
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,
}
/**
- * 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)
{
RETURN(!count);
}
-/**
+/*
* Drop one request reference. Must be called with import imp_lock held.
* When reference count drops to zero, request is freed.
*/
}
/**
- * 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)
{
/**
- * 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)
{
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)
}
/**
- * 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)
{
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)
{
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
spin_unlock(&req->rq_lock);
}
-/**
+/*
* Grab additional reference on a request \a req
*/
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
*/
}
/**
- * 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)
{
}
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.
}
/**
- * 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)
}
/**
- * 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)
{
}
/**
- * 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)
{
}
}
-/**
+/*
* 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
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
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
}
/**
- * 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)
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.
}
/**
- * 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)
git://git.whamcloud.com / fs / lustre-release.git / commitdiff