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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <19eb6b7f-0a62-0e2a-c108-27887b825767@acm.org>
Date:   Thu, 12 Sep 2019 15:03:44 +0100
From:   Bart Van Assche <bvanassche@....org>
To:     André Almeida <andrealmeid@...labora.com>,
        linux-kernel@...r.kernel.org, linux-scsi@...r.kernel.org,
        linux-doc@...r.kernel.org
Cc:     corbet@....net, kernel@...labora.com, krisman@...labora.com,
        jejb@...ux.ibm.com, martin.petersen@...cle.com
Subject: Re: [PATCH 3/3] scsi: core: change function comments to kernel-doc
 style

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.