locking/memory-barriers.txt: Improve documentation for writel() example
Subsystems (3)
PATCH v3 1/1 locking/memory-barriers.txt: Improve documentation for writel() example
The cited commit describes that when using writel(), explcit wmb() is not needed. wmb() is an expensive barrier. writel() uses the needed platform specific 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")
---
changelog:v2->v3:
- removed redundant description for writeX()
- updated text for alignment and smaller change lines
- updated commit log with blank line before signed-off-by line v1->v2:
- Further improved description of writel() example
- changed commit subject from 'usage' to 'example' v0->v1:
- Corrected to mention I/O barrier instead of dma_wmb().
- removed numbered references in commit log
- corrected typo 'explcit' to 'explicit' in commit log
--- Documentation/memory-barriers.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/memory-barriers.txt +3 -2
@@ -1927,10 +1927,11 @@ There are some more advanced barrier functions: before we read the data from the descriptor, and the dma_wmb() allows us to guarantee the data is written to the descriptor before the device can see it now has ownership. The dma_mb() implies both a dma_rmb() and - a dma_wmb(). Note that, when using writel(), a prior wmb() is not needed + a dma_wmb(). Note that, when using writel(), a prior barrier is not needed to guarantee that the cache coherent memory writes have completed before writing to the MMIO region. The cheaper writel_relaxed() does not provide - this guarantee and must not be used here. + this guarantee and must not be used here. Hence, writeX() is always + preferred. See the subsection "Kernel I/O barrier effects" for more information on relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for
Signature · 1 line
2.26.2
Akira Yokosawa
reviewerHi,
Quoted 33 lines · Parav Pandit
The cited commit describes that when using
writel(), explcitwmb()is not needed.wmb()is an expensive barrier.writel()uses the needed platform specific barrier instead of expensivewmb().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 <[email protected]>---
changelog:v2->v3:
- removed redundant description forwriteX()
- updated text for alignment and smaller change lines
- updated commit log with blank line before signed-off-by linev1->v2:
- Further improved description ofwritel()example
- changed commit subject from 'usage' to 'example'v0->v1:
- Corrected to mention I/O barrier instead ofdma_wmb().
- removed numbered references in commit log
- corrected typo 'explcit' to 'explicit' in commit log--- Documentation/memory-barriers.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/memory-barriers.txt +0
-0
Documentation/memory-barriers.txt There are some more advanced barrier functions: · line 1934
Quoted 10 lines
Documentation/memory-barriers.txt +3
-2@@ -1927,10 +1927,11 @@ There are some more advanced barrier functions: before we read the data from the descriptor, and the dma_wmb() allows us to guarantee the data is written to the descriptor before the device can see it now has ownership. The dma_mb() implies both a dma_rmb() and - a dma_wmb(). Note that, when using writel(), a prior wmb() is not needed + a dma_wmb(). Note that, when using writel(), a prior barrier is not needed to guarantee that the cache coherent memory writes have completed before writing to the MMIO region. The cheaper writel_relaxed() does not provide - this guarantee and must not be used here. + this guarantee and must not be used here. Hence, writeX() is always + preferred.
So I assumed that this last sentence would be removed altogether. Can you explain the intention of adding it?
IMHO, "preferred" doesn't mean anything in this document.
Thanks, Akira
Quoted 3 lines
Documentation/memory-barriers.txt +0
-0See the subsection "Kernel I/O barrier effects" for more information on relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for
Quoted 52 lines
From: Akira Yokosawa <[email protected]>
Sent: Thursday, October 6, 2022 6:01 PMHi,
Documentation/memory-barriers.txt There are some more advanced barrier
Quoted 35 lines · Parav Pandit
The cited commit describes that when using
writel(), explcitwmb()is not needed.wmb()is an expensive barrier.writel()uses the needed platform specific barrier instead of expensivewmb().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 <[email protected]>---
changelog:v2->v3:
- removed redundant description forwriteX()
- updated text for alignment and smaller change lines
- updated commit log with blank line before signed-off-by linev1->v2:
- Further improved description ofwritel()example
- changed commit subject from 'usage' to 'example'v0->v1:
- Corrected to mention I/O barrier instead ofdma_wmb().
- removed numbered references in commit log
- corrected typo 'explcit' to 'explicit' in commit log--- Documentation/memory-barriers.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/memory-barriers.txt +0
-0@@ -1927,10 +1927,11 @@ There are some more advanced barrierfunctions:
Documentation/memory-barriers.txt There are some more advanced barrier · line 1927
Quoted 1 line
Documentation/memory-barriers.txt +0
-0before we read the data from the descriptor, and the dma_wmb()allows
Documentation/memory-barriers.txt There are some more advanced barrier · line 1929
Quoted 2 lines
Documentation/memory-barriers.txt +0
-0us to guarantee the data is written to the descriptor before the device can see it now has ownership. The dma_mb() implies both a
dma_rmb()andDocumentation/memory-barriers.txt There are some more advanced barrier · line 1930
Quoted 1 line
Documentation/memory-barriers.txt +0
-1- a dma_wmb(). Note that, when using writel(), a prior wmb() is notneeded
Documentation/memory-barriers.txt There are some more advanced barrier · line 1932
Quoted 3 lines
Documentation/memory-barriers.txt +2
-0+ a dma_wmb(). Note that, when using writel(), a prior barrier is + not needed to guarantee that the cache coherent memory writes have completed
Quoted 9 lines
before
Documentation/memory-barriers.txt There are some more advanced barrier · line 1933
Quoted 1 line
Documentation/memory-barriers.txt +0
-0writing to the MMIO region. The cheaper writel_relaxed() does notprovide
Documentation/memory-barriers.txt There are some more advanced barrier functions: · line 1934
Quoted 3 lines
Documentation/memory-barriers.txt +2
-1- this guarantee and must not be used here. + this guarantee and must not be used here. Hence, writeX() is always + preferred.So I assumed that this last sentence would be removed altogether. Can you explain the intention of adding it?
Just to highlight to developers to use of writeX() over _relaxed() variant. But I think it redundant given above explanation of non-guarantee.
Quoted 1 line
IMHO, "preferred" doesn't mean anything in this document.
Dropping the last sentence in v4.
Thanks