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)
{
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)
{
}
/**
+ * 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)
}
/**
- * 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)
{
}
/**
- * 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)
{
}
/**
- * 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.
}
/**
- * 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)
{
}
/**
- * 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
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.
*/
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)
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
}
/**
+ * 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)
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)
{
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,
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)
{
}
/**
- * 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)
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,
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)
{
}
/**
- * 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)
#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)
}
/**
+ * 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)
{
}
/**
- * 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)
{
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)
{
}
/**
- * 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)
{
*/
/**
- * 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)
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,
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)
#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)
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)
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)
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.
git://git.whamcloud.com / fs / lustre-release.git / commitdiff