Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Subject: Re: [PATCH 3/3] scsi: core: change function comments to kernel-doc
 style
To:     =?UTF-8?Q?Andr=c3=a9_Almeida?= <andrealmeid@collabora.com>,
        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
References: <20190911203735.1332398-1-andrealmeid@collabora.com>
 <20190911203735.1332398-3-andrealmeid@collabora.com>
From:   Bart Van Assche <bvanassche@acm.org>
Message-ID: <19eb6b7f-0a62-0e2a-c108-27887b825767@acm.org>
Date:   Thu, 12 Sep 2019 15:03:44 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.8.0
MIME-Version: 1.0
In-Reply-To: <20190911203735.1332398-3-andrealmeid@collabora.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 8BIT
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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.