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

[Bart Van Assche <bvanassche@acm.org>]

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.