From patchwork Wed Sep 11 20:37:33 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Andr=C3=A9_Almeida?= X-Patchwork-Id: 11141863 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id A337F14E5 for ; Wed, 11 Sep 2019 20:38:51 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 8AA6F2082C for ; Wed, 11 Sep 2019 20:38:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729157AbfIKUis (ORCPT ); Wed, 11 Sep 2019 16:38:48 -0400 Received: from bhuna.collabora.co.uk ([46.235.227.227]:60500 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728998AbfIKUis (ORCPT ); Wed, 11 Sep 2019 16:38:48 -0400 Received: from [127.0.0.1] (localhost [127.0.0.1]) (Authenticated sender: tonyk) with ESMTPSA id DD8FB28D82F From: =?utf-8?q?Andr=C3=A9_Almeida?= To: linux-kernel@vger.kernel.org, linux-scsi@vger.kernel.org, linux-doc@vger.kernel.org Cc: corbet@lwn.net, kernel@collabora.com, krisman@collabora.com, jejb@linux.ibm.com, martin.petersen@oracle.com, =?utf-8?q?Andr=C3=A9_Almeid?= =?utf-8?q?a?= Subject: [PATCH 1/3] docs: scsi: fix typo Date: Wed, 11 Sep 2019 17:37:33 -0300 Message-Id: <20190911203735.1332398-1-andrealmeid@collabora.com> X-Mailer: git-send-email 2.23.0 MIME-Version: 1.0 Sender: linux-scsi-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-scsi@vger.kernel.org "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 --- 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 `__ is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 From patchwork Wed Sep 11 20:37:34 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Andr=C3=A9_Almeida?= X-Patchwork-Id: 11141865 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id AD55E14E5 for ; Wed, 11 Sep 2019 20:38:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 94E3C2082C for ; Wed, 11 Sep 2019 20:38:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730616AbfIKUiw (ORCPT ); Wed, 11 Sep 2019 16:38:52 -0400 Received: from bhuna.collabora.co.uk ([46.235.227.227]:60512 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728998AbfIKUiv (ORCPT ); Wed, 11 Sep 2019 16:38:51 -0400 Received: from [127.0.0.1] (localhost [127.0.0.1]) (Authenticated sender: tonyk) with ESMTPSA id AD7D728D854 From: =?utf-8?q?Andr=C3=A9_Almeida?= To: linux-kernel@vger.kernel.org, linux-scsi@vger.kernel.org, linux-doc@vger.kernel.org Cc: corbet@lwn.net, kernel@collabora.com, krisman@collabora.com, jejb@linux.ibm.com, martin.petersen@oracle.com, =?utf-8?q?Andr=C3=A9_Almeid?= =?utf-8?q?a?= Subject: [PATCH 2/3] scsi: core: remove trailing whitespaces Date: Wed, 11 Sep 2019 17:37:34 -0300 Message-Id: <20190911203735.1332398-2-andrealmeid@collabora.com> X-Mailer: git-send-email 2.23.0 In-Reply-To: <20190911203735.1332398-1-andrealmeid@collabora.com> References: <20190911203735.1332398-1-andrealmeid@collabora.com> MIME-Version: 1.0 Sender: linux-scsi-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-scsi@vger.kernel.org Remove all trailing whitespaces from scsi_lib.c Signed-off-by: André Almeida --- 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; From patchwork Wed Sep 11 20:37:35 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Andr=C3=A9_Almeida?= X-Patchwork-Id: 11141867 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5F5E41599 for ; Wed, 11 Sep 2019 20:39:00 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 3C8F32082C for ; Wed, 11 Sep 2019 20:39:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730632AbfIKUi4 (ORCPT ); Wed, 11 Sep 2019 16:38:56 -0400 Received: from bhuna.collabora.co.uk ([46.235.227.227]:60520 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728998AbfIKUi4 (ORCPT ); Wed, 11 Sep 2019 16:38:56 -0400 Received: from [127.0.0.1] (localhost [127.0.0.1]) (Authenticated sender: tonyk) with ESMTPSA id 4562228D86C From: =?utf-8?q?Andr=C3=A9_Almeida?= To: linux-kernel@vger.kernel.org, linux-scsi@vger.kernel.org, linux-doc@vger.kernel.org Cc: corbet@lwn.net, kernel@collabora.com, krisman@collabora.com, jejb@linux.ibm.com, martin.petersen@oracle.com, =?utf-8?q?Andr=C3=A9_Almeid?= =?utf-8?q?a?= Subject: [PATCH 3/3] scsi: core: change function comments to kernel-doc style Date: Wed, 11 Sep 2019 17:37:35 -0300 Message-Id: <20190911203735.1332398-3-andrealmeid@collabora.com> X-Mailer: git-send-email 2.23.0 In-Reply-To: <20190911203735.1332398-1-andrealmeid@collabora.com> References: <20190911203735.1332398-1-andrealmeid@collabora.com> MIME-Version: 1.0 Sender: linux-scsi-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-scsi@vger.kernel.org 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 --- 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) {