Signed-off-by: Sunday Adelodun <[email protected]>
---
drivers/md/dm-vdo/admin-state.c | 74 ++++++++++++++++++++++-----------
1 file changed, 49 insertions(+), 25 deletions(-)
diff --git a/drivers/md/dm-vdo/admin-state.c b/drivers/md/dm-vdo/admin-state.c
index 3f9dba525154..eedbe080f632 100644
--- a/drivers/md/dm-vdo/admin-state.c
+++ b/drivers/md/dm-vdo/admin-state.c
@@ -187,6 +187,8 @@ static const struct admin_state_code *get_next_state(const
struct admin_state *s
/**
* vdo_finish_operation() - Finish the current operation.
+ * @state: The admin_state object representing the current operation.
+ * @result: The result code to pass to any waiting completion handler.
*
* Will notify the operation waiter if there is one. This method should be
used for operations
* started with vdo_start_operation(). For operations which were started with
vdo_start_draining(),
@@ -214,8 +216,10 @@ bool vdo_finish_operation(struct admin_state *state, int
result)
/**
* begin_operation() - Begin an operation if it may be started given the
current state.
- * @waiter A completion to notify when the operation is complete; may be NULL.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The state code describing the operation to begin.
+ * @waiter: A completion to notify when the operation is complete; may be NULL.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
* Return: VDO_SUCCESS or an error.
*/
@@ -259,8 +263,10 @@ static int __must_check begin_operation(struct admin_state
*state,
/**
* start_operation() - Start an operation if it may be started given the
current state.
- * @waiter A completion to notify when the operation is complete.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The state code describing the operation to begin.
+ * @waiter: A completion to notify when the operation is complete.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
* Return: true if the operation was started.
*/
@@ -274,10 +280,10 @@ static inline bool __must_check start_operation(struct
admin_state *state,
/**
* check_code() - Check the result of a state validation.
- * @valid true if the code is of an appropriate type.
- * @code The code which failed to be of the correct type.
- * @what What the code failed to be, for logging.
- * @waiter The completion to notify of the error; may be NULL.
+ * @valid: true if the code is of an appropriate type.
+ * @code: The code which failed to be of the correct type.
+ * @what: What the code failed to be, for logging.
+ * @waiter: The completion to notify of the error; may be NULL.
*
* If the result failed, log an invalid state error and, if there is a
waiter, notify it.
*
@@ -301,7 +307,8 @@ static bool check_code(bool valid, const struct
admin_state_code *code, const ch
/**
* assert_vdo_drain_operation() - Check that an operation is a drain.
- * @waiter The completion to finish with an error if the operation is not a
drain.
+ * @operation: The drain operation type to check.
+ * @waiter: The completion to finish with an error if the operation is not a
drain.
*
* Return: true if the specified operation is a drain.
*/
@@ -313,11 +320,12 @@ static bool __must_check assert_vdo_drain_operation(const
struct admin_state_cod
/**
* vdo_start_draining() - Initiate a drain operation if the current state
permits it.
- * @operation The type of drain to initiate.
- * @waiter The completion to notify when the drain is complete.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The type of drain to initiate.
+ * @waiter: The completion to notify when the drain is complete.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
- * Return: true if the drain was initiated, if not the waiter will be notified.
+ * Return: true if the drain was initiated; otherwise false, with the waiter
notified.
*/
bool vdo_start_draining(struct admin_state *state,
const struct admin_state_code *operation,
@@ -345,6 +353,7 @@ bool vdo_start_draining(struct admin_state *state,
/**
* vdo_finish_draining() - Finish a drain operation if one was in progress.
+ * @state: The admin_state object representing the current administrative
state.
*
* Return: true if the state was draining; will notify the waiter if so.
*/
@@ -355,6 +364,8 @@ bool vdo_finish_draining(struct admin_state *state)
/**
* vdo_finish_draining_with_result() - Finish a drain operation with a status
code.
+ * @state: The admin_state object representing the current administrative
state.
+ * @result: The result code to return to the waiting completion.
*
* Return: true if the state was draining; will notify the waiter if so.
*/
@@ -365,7 +376,8 @@ bool vdo_finish_draining_with_result(struct admin_state
*state, int result)
/**
* vdo_assert_load_operation() - Check that an operation is a load.
- * @waiter The completion to finish with an error if the operation is not a
load.
+ * @operation: The admin_state_code describing the operation to validate.
+ * @waiter: The completion to finish with an error if the operation is not a
load.
*
* Return: true if the specified operation is a load.
*/
@@ -377,9 +389,10 @@ bool vdo_assert_load_operation(const struct
admin_state_code *operation,
/**
* vdo_start_loading() - Initiate a load operation if the current state
permits it.
- * @operation The type of load to initiate.
- * @waiter The completion to notify when the load is complete (may be NULL).
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The type of load to initiate.
+ * @waiter: The completion to notify when the load is complete (may be NULL).
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
* Return: true if the load was initiated, if not the waiter will be notified.
*/
@@ -393,6 +406,7 @@ bool vdo_start_loading(struct admin_state *state,
/**
* vdo_finish_loading() - Finish a load operation if one was in progress.
+ * @state: The admin_state object representing the current administrative
state.
*
* Return: true if the state was loading; will notify the waiter if so.
*/
@@ -403,7 +417,8 @@ bool vdo_finish_loading(struct admin_state *state)
/**
* vdo_finish_loading_with_result() - Finish a load operation with a status
code.
- * @result The result of the load operation.
+ * @state: The admin_state object representing the current administrative
state.
+ * @result: The result of the load operation.
*
* Return: true if the state was loading; will notify the waiter if so.
*/
@@ -414,7 +429,8 @@ bool vdo_finish_loading_with_result(struct admin_state
*state, int result)
/**
* assert_vdo_resume_operation() - Check whether an admin_state_code is a
resume operation.
- * @waiter The completion to notify if the operation is not a resume
operation; may be NULL.
+ * @operation: The admin_state_code to check.
+ * @waiter: The completion to notify if the operation is not a resume
operation; may be NULL.
*
* Return: true if the code is a resume operation.
*/
@@ -427,9 +443,10 @@ static bool __must_check assert_vdo_resume_operation(const
struct admin_state_co
/**
* vdo_start_resuming() - Initiate a resume operation if the current state
permits it.
- * @operation The type of resume to start.
- * @waiter The completion to notify when the resume is complete (may be NULL).
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The type of resume to start.
+ * @waiter: The completion to notify when the resume is complete (may be NULL).
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
* Return: true if the resume was initiated, if not the waiter will be
notified.
*/
@@ -443,6 +460,7 @@ bool vdo_start_resuming(struct admin_state *state,
/**
* vdo_finish_resuming() - Finish a resume operation if one was in progress.
+ * @state: The admin state object representing the current administrative
state.
*
* Return: true if the state was resuming; will notify the waiter if so.
*/
@@ -453,7 +471,8 @@ bool vdo_finish_resuming(struct admin_state *state)
/**
* vdo_finish_resuming_with_result() - Finish a resume operation with a
status code.
- * @result The result of the resume operation.
+ * @state: The admin_state object representing the current administrative
state.
+ * @result: The result of the resume operation.
*
* Return: true if the state was resuming; will notify the waiter if so.
*/
@@ -464,6 +483,7 @@ bool vdo_finish_resuming_with_result(struct admin_state
*state, int result)
/**
* vdo_resume_if_quiescent() - Change the state to normal operation if the
current state is
+ * @state: The admins_state object representing the current administrative
state.
* quiescent.
*
* Return: VDO_SUCCESS if the state resumed, VDO_INVALID_ADMIN_STATE
otherwise.
@@ -479,6 +499,8 @@ int vdo_resume_if_quiescent(struct admin_state *state)
/**
* vdo_start_operation() - Attempt to start an operation.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The administrative state code representing the operation to
start.
*
* Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE
if not
*/
@@ -490,8 +512,10 @@ int vdo_start_operation(struct admin_state *state,
/**
* vdo_start_operation_with_waiter() - Attempt to start an operation.
- * @waiter the completion to notify when the operation completes or fails to
start; may be NULL.
- * @initiator The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
+ * @state: The admin_state object representing the current administrative
state.
+ * @operation: The administrative state code representing the operation to
start.
+ * @waiter: the completion to notify when the operation completes or fails to
start; may be NULL.
+ * @initiator: The vdo_admin_initiator_fn to call if the operation may begin;
may be NULL.
*
* Return: VDO_SUCCESS if the operation was started, VDO_INVALID_ADMIN_STATE
if not
*/
