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;
Date:   Fri, 18 Oct 2019 09:39:20 -0600
From:   Jonathan Corbet <corbet@lwn.net>
To:     Shaokun Zhang <zhangshaokun@hisilicon.com>
Cc:     <linux-doc@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
        Jens Axboe <axboe@kernel.dk>
Subject: Re: [PATCH] docs: block: Remove blk_init_queue related description
Message-ID: <20191018093920.6fbc8141@lwn.net>
In-Reply-To: <1571061002-25998-1-git-send-email-zhangshaokun@hisilicon.com>
References: <1571061002-25998-1-git-send-email-zhangshaokun@hisilicon.com>
Organization: LWN.net
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Mon, 14 Oct 2019 21:50:02 +0800
Shaokun Zhang <zhangshaokun@hisilicon.com> wrote:

> blk_init_queue has been removed since commit <a1ce35fa4985>
> ("block: remove dead elevator code"), Let's cleanup the description
> in the biodoc.rst document.
> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Jens Axboe <axboe@kernel.dk>
> Signed-off-by: Shaokun Zhang <zhangshaokun@hisilicon.com>

So I applied this, then changed my mind and unapplied it; I think it's the
wrong fix.

>  Documentation/block/biodoc.rst | 10 ----------
>  1 file changed, 10 deletions(-)
> 
> diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst
> index b964796ec9c7..a19081d88349 100644
> --- a/Documentation/block/biodoc.rst
> +++ b/Documentation/block/biodoc.rst
> @@ -1013,11 +1013,6 @@ request_fn execution which it means that lots of older drivers
>  should still be SMP safe. Drivers are free to drop the queue
>  lock themselves, if required. Drivers that explicitly used the
>  io_request_lock for serialization need to be modified accordingly.
> -Usually it's as easy as adding a global lock::
> -
> -	static DEFINE_SPINLOCK(my_driver_lock);
> -
> -and passing the address to that lock to blk_init_queue().

This is a section about coping with the removal of the io_request_lock,
which happened in 2.5, prior to the git era.  I think it is probably safe
to say that there are no relevant drivers that still need to be updated
for this particular change.

>  5.2 64 bit sector numbers (sector_t prepares for 64 bit support)
>  ----------------------------------------------------------------
> @@ -1071,11 +1066,6 @@ right thing to use is bio_endio(bio) instead.
>  If the driver is dropping the io_request_lock from its request_fn strategy,
>  then it just needs to replace that with q->queue_lock instead.
>  
> -As described in Sec 1.1, drivers can set max sector size, max segment size
> -etc per queue now. Drivers that used to define their own merge functions i
> -to handle things like this can now just use the blk_queue_* functions at
> -blk_init_queue time.
> -
>  Drivers no longer have to map a {partition, sector offset} into the
>  correct absolute location anymore, this is done by the block layer, so
>  where a driver received a request ala this before::

Here, too.  We're talking about teaching drivers how to use bios.

My suggested fix is to just remove both sections from the document
entirely; neither is relevant in 2019.

Even better, of course, would be to pass through this document and bring
it up to current practice in general; there is certain to be a lot more in
need of fixing here.

Thanks,

jon