Commit 289e1c89 authored by Parav Pandit's avatar Parav Pandit Committed by Paul E. McKenney

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

The cited commit describes that when using writel(), explicit wmb()
is not needed. wmb() is an expensive barrier. writel() uses the needed
platform specific barrier instead of wmb().

writeX() section of "KERNEL I/O BARRIER EFFECTS" already describes
ordering of I/O accessors with MMIO writes.

Hence add the comment for pseudo code of writel() and remove confusing
text around writel() and wmb().

commit 5846581e ("locking/memory-barriers.txt: Fix broken DMA vs. MMIO ordering example")
Co-developed-by: default avatarWill Deacon <will@kernel.org>
Signed-off-by: default avatarWill Deacon <will@kernel.org>
Signed-off-by: default avatarParav Pandit <parav@nvidia.com>
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 1b929c02
...@@ -1910,7 +1910,8 @@ There are some more advanced barrier functions: ...@@ -1910,7 +1910,8 @@ There are some more advanced barrier functions:
These are for use with consistent memory to guarantee the ordering These are for use with consistent memory to guarantee the ordering
of writes or reads of shared memory accessible to both the CPU and a of writes or reads of shared memory accessible to both the CPU and a
DMA capable device. DMA capable device. See Documentation/core-api/dma-api.rst file for more
information about consistent memory.
For example, consider a device driver that shares memory with a device For example, consider a device driver that shares memory with a device
and uses a descriptor status value to indicate if the descriptor belongs and uses a descriptor status value to indicate if the descriptor belongs
...@@ -1931,22 +1932,21 @@ There are some more advanced barrier functions: ...@@ -1931,22 +1932,21 @@ There are some more advanced barrier functions:
/* assign ownership */ /* assign ownership */
desc->status = DEVICE_OWN; desc->status = DEVICE_OWN;
/* notify device of new descriptors */ /* Make descriptor status visible to the device followed by
* notify device of new descriptor
*/
writel(DESC_NOTIFY, doorbell); writel(DESC_NOTIFY, doorbell);
} }
The dma_rmb() allows us guarantee the device has released ownership The dma_rmb() allows us to guarantee that the device has released ownership
before we read the data from the descriptor, and the dma_wmb() allows 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 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 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().
to guarantee that the cache coherent memory writes have completed before
writing to the MMIO region. The cheaper writel_relaxed() does not provide Note that the dma_*() barriers do not provide any ordering guarantees for
this guarantee and must not be used here. accesses to MMIO regions. See the later "KERNEL I/O BARRIER EFFECTS"
subsection for more information about I/O accessors and MMIO ordering.
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
more information on consistent memory.
(*) pmem_wmb(); (*) pmem_wmb();
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment