Re: io_ordering.rst vs. memory-barriers.txt

[Arnd Bergmann]

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@xxxxxxxxxxxxxxxxx/
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