Skip to contentSkip to conversation

locking/memory-barriers.txt: Improve documentation for writel() example

PATCH Superseded Parav Pandit 2 participants 3 messages Oct 6, 2022 – Oct 10, 2022

Subsystems (3)

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

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
index 832b5d36e279..8952fd86c6e6 100644
@@ -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
#1 lore raw

Hi,

Quoted 33 lines · Parav Pandit

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 +0 -0
index 832b5d36e279..8952fd86c6e6 100644

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 -0
      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
#2 lore raw
Quoted 52 lines

From: Akira Yokosawa <[email protected]>
Sent: Thursday, October 6, 2022 6:01 PM

Hi,

Documentation/memory-barriers.txt There are some more advanced barrier

Quoted 35 lines · Parav Pandit

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 +0 -0
index 832b5d36e279..8952fd86c6e6 100644
@@ -1927,10 +1927,11 @@ There are some more advanced barrier

functions:

Documentation/memory-barriers.txt There are some more advanced barrier · line 1927

Quoted 1 line
Documentation/memory-barriers.txt +0 -0
      before 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 -0
      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

Documentation/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 not

needed

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 -0
      writing to the MMIO region.  The cheaper writel_relaxed() does not

provide

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