RE: [PATCH v1] locking/memory-barriers.txt: Improve documentation for writel() usage

[Parav Pandit]

> From: Akira Yokosawa <akiyks@xxxxxxxxx>
> Sent: Friday, September 30, 2022 8:41 AM
> 
> Hi,
> 
> On Fri, 30 Sep 2022 05:03:55 +0300, Parav Pandit wrote:
> > The cited commit describes that when using writel(), explcit wmb() is
> > not needed. wmb() is an expensive barrier. writel() uses the needed
> > I/O barrier instead of expensive wmb().
> >
> > Hence update the example to be more accurate that matches the current
> > implementation.
> >
> > commit 5846581e3563 ("locking/memory-barriers.txt: Fix broken DMA vs.
> > MMIO ordering example")
> > Signed-off-by: Parav Pandit <parav@xxxxxxxxxx>
> >
> > ---
> > changelog:
> > v0->v1:
> > - Corrected to mention I/O barrier instead of dma_wmb().
> I don't think dma_wmb() and wmb() belong to "I/O barrier" as far as
> memory-barriers.txt is concerned. 

Well, in kernel code for ARM in [1] writel() issues _iowmb() I/O write memory barrier that maps to wmb().
But I agree that in describing the example of interest in this document, it is better to stay away from the detail description and let writeX() explain it.

[1] https://elixir.bootlin.com/linux/latest/source/arch/arm/include/asm/io.h#L290

> They are listed in the "CPU MEMORY
> BARRIERS" section. dma_wmb() belongs to "advanced barrier functions".
> 
> You see, writel() is one of the functions listed in the "KERNEL I/O BARRIER
> EFFECTS" section.
> 
> Please be consistent with the word choice of the doc you are modifying, so
> that any further confusion can be avoided in this infamously hard-to-follow
> document. :-)
>
I understood.
I will rephrase it as "Note that, when using writel(), a prior barrier is not needed"...