[PATCH 1/3] docs: scsi: fix typo

[PATCH 1/3] docs: scsi: fix typo

[André Almeida]

"Busses" is the third person conjugation of verb "to buss" in the
present tense. "Buses" is the plural of bus, as in "serial bus".

Signed-off-by: André Almeida <andrealmeid@collabora.com>
---
 Documentation/driver-api/scsi.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst
index 64b231d125e0..349ac8a55214 100644
--- a/Documentation/driver-api/scsi.rst
+++ b/Documentation/driver-api/scsi.rst
@@ -18,7 +18,7 @@ optical drives, test equipment, and medical devices) to a host computer.
 
 Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
 out of use, the SCSI command set is more widely used than ever to
-communicate with devices over a number of different busses.
+communicate with devices over a number of different buses.
 
 The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
 peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
-- 
2.23.0

[PATCH 2/3] scsi: core: remove trailing whitespaces

[André Almeida]

Remove all trailing whitespaces from scsi_lib.c

Signed-off-by: André Almeida <andrealmeid@collabora.com>
---
 drivers/scsi/scsi_lib.c | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index 11e64b50497f..8565bee31922 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -401,7 +401,7 @@ static void scsi_single_lun_run(struct scsi_device *current_sdev)
 		spin_unlock_irqrestore(shost->host_lock, flags);
 		scsi_kick_queue(sdev->request_queue);
 		spin_lock_irqsave(shost->host_lock, flags);
-	
+
 		scsi_device_put(sdev);
 	}
  out:
@@ -995,7 +995,7 @@ static blk_status_t scsi_init_sgtable(struct request *req,
 			SCSI_INLINE_SG_CNT)))
 		return BLK_STS_RESOURCE;
 
-	/* 
+	/*
 	 * Next, walk the list, and fill in the addresses and sizes of
 	 * each segment.
 	 */
@@ -2019,7 +2019,7 @@ scsi_mode_select(struct scsi_device *sdev, int pf, int sp, int modepage,
 		real_buffer[1] = data->medium_type;
 		real_buffer[2] = data->device_specific;
 		real_buffer[3] = data->block_descriptor_length;
-		
+
 
 		cmd[0] = MODE_SELECT;
 		cmd[4] = len;
@@ -2103,7 +2103,7 @@ scsi_mode_sense(struct scsi_device *sdev, int dbd, int modepage,
 		if (scsi_sense_valid(sshdr)) {
 			if ((sshdr->sense_key == ILLEGAL_REQUEST) &&
 			    (sshdr->asc == 0x20) && (sshdr->ascq == 0)) {
-				/* 
+				/*
 				 * Invalid command operation code
 				 */
 				sdev->use_10_for_ms = 0;
@@ -2205,7 +2205,7 @@ scsi_device_set_state(struct scsi_device *sdev, enum scsi_device_state state)
 			goto illegal;
 		}
 		break;
-			
+
 	case SDEV_RUNNING:
 		switch (oldstate) {
 		case SDEV_CREATED:
@@ -2488,7 +2488,7 @@ EXPORT_SYMBOL_GPL(sdev_evt_send_simple);
  *	(which must be a legal transition).  When the device is in this
  *	state, only special requests will be accepted, all others will
  *	be deferred.  Since special requests may also be requeued requests,
- *	a successful return doesn't guarantee the device will be 
+ *	a successful return doesn't guarantee the device will be
  *	totally quiescent.
  *
  *	Must be called with user context, may sleep.
@@ -2614,10 +2614,10 @@ int scsi_internal_device_block_nowait(struct scsi_device *sdev)
 			return err;
 	}
 
-	/* 
+	/*
 	 * The device has transitioned to SDEV_BLOCK.  Stop the
 	 * block layer from calling the midlayer with this device's
-	 * request queue. 
+	 * request queue.
 	 */
 	blk_mq_quiesce_queue_nowait(q);
 	return 0;
@@ -2652,7 +2652,7 @@ static int scsi_internal_device_block(struct scsi_device *sdev)
 
 	return err;
 }
- 
+
 void scsi_start_queue(struct scsi_device *sdev)
 {
 	struct request_queue *q = sdev->request_queue;
-- 
2.23.0

[PATCH 3/3] scsi: core: change function comments to kernel-doc style

[André Almeida]

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.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
---
 drivers/scsi/scsi_lib.c | 166 +++++++++++++++-------------------------
 1 file changed, 61 insertions(+), 105 deletions(-)

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index 8565bee31922..980e713aa187 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -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 - Insert a command in the midlevel 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)
 {
@@ -499,17 +488,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)
 {
@@ -900,34 +883,27 @@ 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
- *
- * 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.
+/**
+ * scsi_io_completion - Completion processing for block device I/O requests.
+ * @cmd:	command that is finished.
+ * @good_bytes:	command reply bytes.
+ *
+ * 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.
  */
 void scsi_io_completion(struct scsi_cmnd *cmd, unsigned int good_bytes)
 {
@@ -1006,16 +982,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 initialize 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)
 {
@@ -1886,21 +1860,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)
 {
@@ -1908,25 +1874,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 from being 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)
 {
-- 
2.23.0

Re: [PATCH 1/3] docs: scsi: fix typo

[Joe Perches]

On Wed, 2019-09-11 at 17:37 -0300, André Almeida wrote:
> "Busses" is the third person conjugation of verb "to buss" in the
> present tense. "Buses" is the plural of bus, as in "serial bus".

busses and buses are both acceptable plurals of bus

https://www.dictionary.com/browse/bus

Re: [PATCH 1/3] docs: scsi: fix typo

[André Almeida]

On 9/11/19 6:10 PM, Joe Perches wrote:
> On Wed, 2019-09-11 at 17:37 -0300, André Almeida wrote:
>> "Busses" is the third person conjugation of verb "to buss" in the
>> present tense. "Buses" is the plural of bus, as in "serial bus".
> 
> busses and buses are both acceptable plurals of bus
> 
> https://www.dictionary.com/browse/bus
> 

Thanks for the feedback! I used this reference[1] for writing my commit
message, but I believe we can leave the way it is now.

Thanks,
	André

[1] https://writingexplained.org/buses-or-busses-difference

Re: [PATCH 2/3] scsi: core: remove trailing whitespaces

[Bart Van Assche]

On 9/11/19 9:37 PM, André Almeida wrote:
> Remove all trailing whitespaces from scsi_lib.c

I don't like patches that only change whitespace if no significant
functional changes are included in the same patch series. Such patches
namely pollute the change history, make the output of git log -p and git
blame harder to follow and also cause big trouble for anyone who wants
to rebase his or her own tree with outstanding patches.

Bart.

Re: [PATCH 3/3] scsi: core: change function comments to kernel-doc style

[Bart Van Assche]

On 9/11/19 9:37 PM, André Almeida wrote:
> +/**
> + * scsi_queue_insert - Insert a command in the midlevel 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.
>   */

What is the midlevel queue? I don't know anyone who still uses that
terminology today. Since the switch to scsi-mq we have software queues
(if no I/O scheduler has been configured), scheduler queue(s) (if an I/O
scheduler has been configured) and hardware queues.

> +/**
> + * scsi_io_completion - Completion processing for block device I/O requests.
> + * @cmd:	command that is finished.

That looks inconsistent: the function description refers to block device
I/O requests while what is being completed is a SCSI command.

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

I am not aware of any function in the kernel tree that has the name
scsi_requeue_command().

Thanks,

Bart.