Commit ea941016 authored by André Almeida's avatar André Almeida Committed by Martin K. Petersen
Browse files

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: default avatarAndré Almeida <andrealmeid@collabora.com>
Signed-off-by: default avatarMartin K. Petersen <martin.petersen@oracle.com>
parent 04ee8a01

drivers/scsi/scsi_lib.c

+62 −107
Original line number Diff line number Diff line
@@ -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()

 *

 * Purpose:     Insert a command in the midlevel queue.

 *

 * 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.

/**

 * 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.

 *

 * Returns:     Nothing.

 * 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:       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()

 *

 * Purpose:     Initialize cmd fields related to error handling.

 *

 * Arguments:   cmd	- command that is ready to be queued.

/**

 * scsi_init_cmd_errh - Initialize cmd fields related to error handling.

 * @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()

 *

 * Purpose:    Select a proper request queue to serve next

 *

 * Arguments:  q       - last request's queue

 *

 * Returns:     Nothing

/**

 * scsi_run_queue - Select a proper request queue to serve next.

 * @q:  last request's queue

 *

 * 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,31 +879,24 @@ static int scsi_io_completion_nz_result(struct scsi_cmnd *cmd, int result, 
	return result;

}



/*

 * Function:    scsi_io_completion()

 *

 * Purpose:     Completion processing for block device I/O requests.

 *

 * Arguments:   cmd   - command that is finished.

 *

 * Lock status: Assumed that no lock is held upon entry.

 *

 * Returns:     Nothing

/**

 * scsi_io_completion - Completion processing for SCSI commands.

 * @cmd:	command that is finished.

 * @good_bytes:	number of processed bytes.

 *

 * 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:

 * 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.

 *   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.

 *

 *		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.

 *   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.

 *

 *   c) We can call scsi_end_request() with blk_stat other than

 *	BLK_STS_OK, to fail the remainder of the request.
@@ -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()

 *

 * Purpose:     SCSI I/O initialize function.

 *

 * Arguments:   cmd   - Command descriptor we wish to initialize

/**

 * scsi_init_io - SCSI I/O initialization function.

 * @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()

 *

 * 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.

/**

 * scsi_block_requests - Utility function used by low-level drivers to prevent

 * further commands from being queued to the device.

 * @shost:  host in question

 *

 * 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()

 *

 * 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.

/**

 * scsi_unblock_requests - Utility function used by low-level drivers to allow

 * further commands to be queued to the device.

 * @shost:  host in question

 *

 * 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)

{