mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-21 16:29:59 +00:00
scsi: core: doc: Change function comments to kernel-doc style
Despite of functions being documented, they are not in the kernel-doc specification, and could not be included in kernel documentation. Change the style of functions comments to be compliant to the kernel-doc style. When the function comments are outdated, update then. [mkp: a few edits] Link: https://lore.kernel.org/r/20200419050148.33371-1-andrealmeid@collabora.com Signed-off-by: André Almeida <andrealmeid@collabora.com> Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
This commit is contained in:
André Almeida
Martin K. Petersen
parent
04ee8a01ab
commit
ea941016ab
1 changed files with 57 additions and 102 deletions
|
|
@ -202,24 +202,17 @@ static void __scsi_queue_insert(struct scsi_cmnd *cmd, int reason, bool unbusy)
|
|||
blk_mq_requeue_request(cmd->request, true);
|
||||
}
|
||||
|
||||
/*
|
||||
* Function: scsi_queue_insert()
|
||||
/**
|
||||
* scsi_queue_insert - Reinsert a command in the queue.
|
||||
* @cmd: command that we are adding to queue.
|
||||
* @reason: why we are inserting command to queue.
|
||||
*
|
||||
* Purpose: Insert a command in the midlevel queue.
|
||||
* We do this for one of two cases. Either the host is busy and it cannot accept
|
||||
* any more commands for the time being, or the device returned QUEUE_FULL and
|
||||
* can accept no more commands.
|
||||
*
|
||||
* Arguments: cmd - command that we are adding to queue.
|
||||
* reason - why we are inserting command to queue.
|
||||
*
|
||||
* Lock status: Assumed that lock is not held upon entry.
|
||||
*
|
||||
* Returns: Nothing.
|
||||
*
|
||||
* Notes: We do this for one of two cases. Either the host is busy
|
||||
* and it cannot accept any more commands for the time being,
|
||||
* or the device returned QUEUE_FULL and can accept no more
|
||||
* commands.
|
||||
* Notes: This could be called either from an interrupt context or a
|
||||
* normal process context.
|
||||
* Context: This could be called either from an interrupt context or a normal
|
||||
* process context.
|
||||
*/
|
||||
void scsi_queue_insert(struct scsi_cmnd *cmd, int reason)
|
||||
{
|
||||
|
|
@ -301,16 +294,12 @@ int __scsi_execute(struct scsi_device *sdev, const unsigned char *cmd,
|
|||
}
|
||||
EXPORT_SYMBOL(__scsi_execute);
|
||||
|
||||
/*
|
||||
* Function: scsi_init_cmd_errh()
|
||||
/**
|
||||
* scsi_init_cmd_errh - Initialize cmd fields related to error handling.
|
||||
* @cmd: command that is ready to be queued.
|
||||
*
|
||||
* Purpose: Initialize cmd fields related to error handling.
|
||||
*
|
||||
* Arguments: cmd - command that is ready to be queued.
|
||||
*
|
||||
* Notes: This function has the job of initializing a number of
|
||||
* fields related to error handling. Typically this will
|
||||
* be called once for each command, as required.
|
||||
* This function has the job of initializing a number of fields related to error
|
||||
* handling. Typically this will be called once for each command, as required.
|
||||
*/
|
||||
static void scsi_init_cmd_errh(struct scsi_cmnd *cmd)
|
||||
{
|
||||
|
|
@ -496,17 +485,11 @@ static void scsi_starved_list_run(struct Scsi_Host *shost)
|
|||
spin_unlock_irqrestore(shost->host_lock, flags);
|
||||
}
|
||||
|
||||
/*
|
||||
* Function: scsi_run_queue()
|
||||
/**
|
||||
* scsi_run_queue - Select a proper request queue to serve next.
|
||||
* @q: last request's queue
|
||||
*
|
||||
* Purpose: Select a proper request queue to serve next
|
||||
*
|
||||
* Arguments: q - last request's queue
|
||||
*
|
||||
* Returns: Nothing
|
||||
*
|
||||
* Notes: The previous command was completely finished, start
|
||||
* a new one if possible.
|
||||
* The previous command was completely finished, start a new one if possible.
|
||||
*/
|
||||
static void scsi_run_queue(struct request_queue *q)
|
||||
{
|
||||
|
|
@ -896,34 +879,27 @@ static int scsi_io_completion_nz_result(struct scsi_cmnd *cmd, int result,
|
|||
return result;
|
||||
}
|
||||
|
||||
/*
|
||||
* Function: scsi_io_completion()
|
||||
/**
|
||||
* scsi_io_completion - Completion processing for SCSI commands.
|
||||
* @cmd: command that is finished.
|
||||
* @good_bytes: number of processed bytes.
|
||||
*
|
||||
* Purpose: Completion processing for block device I/O requests.
|
||||
* We will finish off the specified number of sectors. If we are done, the
|
||||
* command block will be released and the queue function will be goosed. If we
|
||||
* are not done then we have to figure out what to do next:
|
||||
*
|
||||
* Arguments: cmd - command that is finished.
|
||||
* a) We can call scsi_io_completion_reprep(). The request will be
|
||||
* unprepared and put back on the queue. Then a new command will
|
||||
* be created for it. This should be used if we made forward
|
||||
* progress, or if we want to switch from READ(10) to READ(6) for
|
||||
* example.
|
||||
*
|
||||
* Lock status: Assumed that no lock is held upon entry.
|
||||
* b) We can call scsi_io_completion_action(). The request will be
|
||||
* put back on the queue and retried using the same command as
|
||||
* before, possibly after a delay.
|
||||
*
|
||||
* Returns: Nothing
|
||||
*
|
||||
* Notes: We will finish off the specified number of sectors. If we
|
||||
* are done, the command block will be released and the queue
|
||||
* function will be goosed. If we are not done then we have to
|
||||
* figure out what to do next:
|
||||
*
|
||||
* a) We can call scsi_requeue_command(). The request
|
||||
* will be unprepared and put back on the queue. Then
|
||||
* a new command will be created for it. This should
|
||||
* be used if we made forward progress, or if we want
|
||||
* to switch from READ(10) to READ(6) for example.
|
||||
*
|
||||
* b) We can call __scsi_queue_insert(). The request will
|
||||
* be put back on the queue and retried using the same
|
||||
* command as before, possibly after a delay.
|
||||
*
|
||||
* c) We can call scsi_end_request() with blk_stat other than
|
||||
* BLK_STS_OK, to fail the remainder of the request.
|
||||
* c) We can call scsi_end_request() with blk_stat other than
|
||||
* BLK_STS_OK, to fail the remainder of the request.
|
||||
*/
|
||||
void scsi_io_completion(struct scsi_cmnd *cmd, unsigned int good_bytes)
|
||||
{
|
||||
|
|
@ -951,8 +927,7 @@ void scsi_io_completion(struct scsi_cmnd *cmd, unsigned int good_bytes)
|
|||
blk_rq_sectors(req), good_bytes));
|
||||
|
||||
/*
|
||||
* Next deal with any sectors which we were able to correctly
|
||||
* handle. Failed, zero length commands always need to drop down
|
||||
* Failed, zero length commands always need to drop down
|
||||
* to retry code. Fast path should return in this block.
|
||||
*/
|
||||
if (likely(blk_rq_bytes(req) > 0 || blk_stat == BLK_STS_OK)) {
|
||||
|
|
@ -1002,16 +977,14 @@ static blk_status_t scsi_init_sgtable(struct request *req,
|
|||
return BLK_STS_OK;
|
||||
}
|
||||
|
||||
/*
|
||||
* Function: scsi_init_io()
|
||||
/**
|
||||
* scsi_init_io - SCSI I/O initialization function.
|
||||
* @cmd: command descriptor we wish to initialize
|
||||
*
|
||||
* Purpose: SCSI I/O initialize function.
|
||||
*
|
||||
* Arguments: cmd - Command descriptor we wish to initialize
|
||||
*
|
||||
* Returns: BLK_STS_OK on success
|
||||
* BLK_STS_RESOURCE if the failure is retryable
|
||||
* BLK_STS_IOERR if the failure is fatal
|
||||
* Returns:
|
||||
* * BLK_STS_OK - on success
|
||||
* * BLK_STS_RESOURCE - if the failure is retryable
|
||||
* * BLK_STS_IOERR - if the failure is fatal
|
||||
*/
|
||||
blk_status_t scsi_init_io(struct scsi_cmnd *cmd)
|
||||
{
|
||||
|
|
@ -1921,21 +1894,13 @@ struct scsi_device *scsi_device_from_queue(struct request_queue *q)
|
|||
}
|
||||
EXPORT_SYMBOL_GPL(scsi_device_from_queue);
|
||||
|
||||
/*
|
||||
* Function: scsi_block_requests()
|
||||
/**
|
||||
* scsi_block_requests - Utility function used by low-level drivers to prevent
|
||||
* further commands from being queued to the device.
|
||||
* @shost: host in question
|
||||
*
|
||||
* Purpose: Utility function used by low-level drivers to prevent further
|
||||
* commands from being queued to the device.
|
||||
*
|
||||
* Arguments: shost - Host in question
|
||||
*
|
||||
* Returns: Nothing
|
||||
*
|
||||
* Lock status: No locks are assumed held.
|
||||
*
|
||||
* Notes: There is no timer nor any other means by which the requests
|
||||
* get unblocked other than the low-level driver calling
|
||||
* scsi_unblock_requests().
|
||||
* There is no timer nor any other means by which the requests get unblocked
|
||||
* other than the low-level driver calling scsi_unblock_requests().
|
||||
*/
|
||||
void scsi_block_requests(struct Scsi_Host *shost)
|
||||
{
|
||||
|
|
@ -1943,25 +1908,15 @@ void scsi_block_requests(struct Scsi_Host *shost)
|
|||
}
|
||||
EXPORT_SYMBOL(scsi_block_requests);
|
||||
|
||||
/*
|
||||
* Function: scsi_unblock_requests()
|
||||
/**
|
||||
* scsi_unblock_requests - Utility function used by low-level drivers to allow
|
||||
* further commands to be queued to the device.
|
||||
* @shost: host in question
|
||||
*
|
||||
* Purpose: Utility function used by low-level drivers to allow further
|
||||
* commands from being queued to the device.
|
||||
*
|
||||
* Arguments: shost - Host in question
|
||||
*
|
||||
* Returns: Nothing
|
||||
*
|
||||
* Lock status: No locks are assumed held.
|
||||
*
|
||||
* Notes: There is no timer nor any other means by which the requests
|
||||
* get unblocked other than the low-level driver calling
|
||||
* scsi_unblock_requests().
|
||||
*
|
||||
* This is done as an API function so that changes to the
|
||||
* internals of the scsi mid-layer won't require wholesale
|
||||
* changes to drivers that use this feature.
|
||||
* There is no timer nor any other means by which the requests get unblocked
|
||||
* other than the low-level driver calling scsi_unblock_requests(). This is done
|
||||
* as an API function so that changes to the internals of the scsi mid-layer
|
||||
* won't require wholesale changes to drivers that use this feature.
|
||||
*/
|
||||
void scsi_unblock_requests(struct Scsi_Host *shost)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue