diff options
Diffstat (limited to 'Documentation/memory-barriers.txt')
| -rw-r--r-- | Documentation/memory-barriers.txt | 39 |
1 files changed, 24 insertions, 15 deletions
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 06f80e3785c5..61b7317bcf2e 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -88,7 +88,6 @@ CONTENTS (*) The effects of the cpu cache. - - Cache coherency. - Cache coherency vs DMA. - Cache coherency vs MMIO. @@ -396,6 +395,11 @@ Memory barriers come in four basic varieties: (2) Address-dependency barriers (historical). + [!] This section is marked as HISTORICAL: it covers the long-obsolete + smp_read_barrier_depends() macro, the semantics of which are now + implicit in all marked accesses. For more up-to-date information, + including how compiler transformations can sometimes break address + dependencies, see Documentation/RCU/rcu_dereference.rst. An address-dependency barrier is a weaker form of read barrier. In the case where two loads are performed such that the second depends on the @@ -556,6 +560,11 @@ There are certain things that the Linux kernel memory barriers do not guarantee: ADDRESS-DEPENDENCY BARRIERS (HISTORICAL) ---------------------------------------- +[!] This section is marked as HISTORICAL: it covers the long-obsolete +smp_read_barrier_depends() macro, the semantics of which are now implicit +in all marked accesses. For more up-to-date information, including +how compiler transformations can sometimes break address dependencies, +see Documentation/RCU/rcu_dereference.rst. As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for DEC Alpha, which means that about the only people who need to pay attention @@ -667,8 +676,6 @@ include/linux/rcupdate.h. This permits the current target of an RCU'd pointer to be replaced with a new modified target, without the replacement target appearing to be incompletely initialised. -See also the subsection on "Cache Coherency" for a more thorough example. - CONTROL DEPENDENCIES -------------------- @@ -1910,7 +1917,8 @@ There are some more advanced barrier functions: 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 - 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 and uses a descriptor status value to indicate if the descriptor belongs @@ -1931,22 +1939,21 @@ There are some more advanced barrier functions: /* assign ownership */ 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); } - 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 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 - 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. + a dma_wmb(). - 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. + Note that the dma_*() barriers do not provide any ordering guarantees for + accesses to MMIO regions. See the later "KERNEL I/O BARRIER EFFECTS" + subsection for more information about I/O accessors and MMIO ordering. (*) pmem_wmb(); @@ -1966,7 +1973,7 @@ There are some more advanced barrier functions: (*) io_stop_wc(); For memory accesses with write-combining attributes (e.g. those returned - by ioremap_wc(), the CPU may wait for prior accesses to be merged with + by ioremap_wc()), the CPU may wait for prior accesses to be merged with subsequent ones. io_stop_wc() can be used to prevent the merging of write-combining memory accesses before this macro with those after it when such wait has performance implications. @@ -2175,9 +2182,11 @@ set_current_state() may be wrapped by: which therefore also imply a general memory barrier after setting the state. The whole sequence above is available in various canned forms, all of which -interpolate the memory barrier in the right place: +interpolate the memory barrier in the right place, for example: wait_event(); + wait_event_cmd(); + wait_event_exclusive_cmd(); wait_event_interruptible(); wait_event_interruptible_exclusive(); wait_event_interruptible_timeout(); |