Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Feedback-ID: i56a14606:Fastmail
User-Agent: Cyrus-JMAP/3.7.0-alpha0-1115-g8b801eadce-fm-20221102.001-g8b801ead
Mime-Version: 1.0
Message-Id: <488b4fa6-c146-4c0b-9fdf-ff1ef56e5448@app.fastmail.com>
In-Reply-To: <e43b20a4-58f9-1f0e-cd08-9defd494c49f@gmail.com>
References: <1924eda8-aea6-da64-04a7-35f3327a7f4f@cybernetics.com>
 <bb6dfd57-0a46-9aa5-050f-40e207bd44f4@cybernetics.com>
 <e43b20a4-58f9-1f0e-cd08-9defd494c49f@gmail.com>
Date:   Wed, 09 Nov 2022 10:38:55 +0100
From:   "Arnd Bergmann" <arnd@arndb.de>
To:     "Akira Yokosawa" <akiyks@gmail.com>,
        "Tony Battersby" <tonyb@cybernetics.com>,
        "Will Deacon" <will@kernel.org>, "Jonathan Corbet" <corbet@lwn.net>
Cc:     "Alan Stern" <stern@rowland.harvard.edu>,
        "Andrea Parri" <parri.andrea@gmail.com>,
        "Peter Zijlstra" <peterz@infradead.org>,
        "Boqun Feng" <boqun.feng@gmail.com>,
        "Nicholas Piggin" <npiggin@gmail.com>,
        "David Howells" <dhowells@redhat.com>,
        "Jade Alglave" <j.alglave@ucl.ac.uk>,
        "Luc Maranget" <luc.maranget@inria.fr>,
        "Paul E. McKenney" <paulmck@kernel.org>,
        "Daniel Lustig" <dlustig@nvidia.com>,
        "Joel Fernandes" <joel@joelfernandes.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        Linux-Arch <linux-arch@vger.kernel.org>
Subject: Re: io_ordering.rst vs. memory-barriers.txt
Content-Type: text/plain
Precedence: bulk

On Wed, Nov 9, 2022, at 01:28, Akira Yokosawa wrote:

> From quick glance of io_ordering.rst's git history, contents of this file
> is never updated since the beginning of Git history (v2.6.12.rc2).
>
> Which strongly suggests that you can ignore io_ordering.rst.
>
I managed to track the origin of the document further to a bitkeeper
pull request and a patch on the ia64 mailing list:

https://lore.kernel.org/all/200304091927.h39JRob0010157@napali.hpl.hp.com/
https://marc.info/?l=git-commits-head&m=104992658231313&w=1

While the document that was added here (and survives to this day)
talks about MMIO (writel), the code changes in this patch appear
to be only about PIO (outl), so I suspect that it already mixed
things up at the time.

> PS:
> Do we need to keep that outdated document???
>
> I think Documentation/driver-api/device-io.rst is the one properly
> maintained.

I think we need to have one location that properly documents
what can and cannot go wrong with posted writel() vs spinlock.
At the moment, device-io.rst refers to this one saying:

  "Note that posted writes are not strictly ordered against a spinlock,
  see Documentation/driver-api/io_ordering.rst."

The same document recently gained a section on ioremap_np() that
explains some of this better, and it also contradicts io_ordering.rst
by saying

   "A driver author must issue a read from the same device to ensure
   that writes have occurred in the specific cases the author cares."

which I think implies that the "problem" example in io_ordering.rst
is actually fine as long as "my_status" and "ring_ptr" are part
of the same device: while the writel() can still leak past the
spin_unlock(), it won't ever bypass the spin_lock()+readl() on
another CPU, right?

      Arnd