redonkable
/
alistair23-linux
1
0
Fork 0
Code Releases Activity

io_ordering.txt: standardize document format 

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Add a title;
- mark literal-blocks as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
hifive-unleashed-5.1
Mauro Carvalho Chehab 2017-05-14 14:45:35 -03:00 committed by Jonathan Corbet
parent 9cf5116d5b
commit 0e95c85341
1 changed files with 33 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
Documentation/io_ordering.txt
View File

@ -1,3 +1,7 @@
==============================================
Ordering I/O writes to memory-mapped addresses
==============================================
On some platforms, so-called memory-mapped I/O is weakly ordered. On such On some platforms, so-called memory-mapped I/O is weakly ordered. On such
platforms, driver writers are responsible for ensuring that I/O writes to platforms, driver writers are responsible for ensuring that I/O writes to
memory-mapped addresses on their device arrive in the order intended. This is memory-mapped addresses on their device arrive in the order intended. This is
@ -8,39 +12,39 @@ critical section of code protected by spinlocks. This would ensure that
subsequent writes to I/O space arrived only after all prior writes (much like a subsequent writes to I/O space arrived only after all prior writes (much like a
memory barrier op, mb(), only with respect to I/O). memory barrier op, mb(), only with respect to I/O).
A more concrete example from a hypothetical device driver: A more concrete example from a hypothetical device driver::
... ...
CPU A: spin_lock_irqsave(&dev_lock, flags) CPU A: spin_lock_irqsave(&dev_lock, flags)
CPU A: val = readl(my_status); CPU A: val = readl(my_status);
CPU A: ... CPU A: ...
CPU A: writel(newval, ring_ptr); CPU A: writel(newval, ring_ptr);
CPU A: spin_unlock_irqrestore(&dev_lock, flags) CPU A: spin_unlock_irqrestore(&dev_lock, flags)
... ...
CPU B: spin_lock_irqsave(&dev_lock, flags) CPU B: spin_lock_irqsave(&dev_lock, flags)
CPU B: val = readl(my_status); CPU B: val = readl(my_status);
CPU B: ... CPU B: ...
CPU B: writel(newval2, ring_ptr); CPU B: writel(newval2, ring_ptr);
CPU B: spin_unlock_irqrestore(&dev_lock, flags) CPU B: spin_unlock_irqrestore(&dev_lock, flags)
... ...
In the case above, the device may receive newval2 before it receives newval, In the case above, the device may receive newval2 before it receives newval,
which could cause problems. Fixing it is easy enough though: which could cause problems. Fixing it is easy enough though::
... ...
CPU A: spin_lock_irqsave(&dev_lock, flags) CPU A: spin_lock_irqsave(&dev_lock, flags)
CPU A: val = readl(my_status); CPU A: val = readl(my_status);
CPU A: ... CPU A: ...
CPU A: writel(newval, ring_ptr); CPU A: writel(newval, ring_ptr);
CPU A: (void)readl(safe_register); /* maybe a config register? */ CPU A: (void)readl(safe_register); /* maybe a config register? */
CPU A: spin_unlock_irqrestore(&dev_lock, flags) CPU A: spin_unlock_irqrestore(&dev_lock, flags)
... ...
CPU B: spin_lock_irqsave(&dev_lock, flags) CPU B: spin_lock_irqsave(&dev_lock, flags)
CPU B: val = readl(my_status); CPU B: val = readl(my_status);
CPU B: ... CPU B: ...
CPU B: writel(newval2, ring_ptr); CPU B: writel(newval2, ring_ptr);
CPU B: (void)readl(safe_register); /* maybe a config register? */ CPU B: (void)readl(safe_register); /* maybe a config register? */
CPU B: spin_unlock_irqrestore(&dev_lock, flags) CPU B: spin_unlock_irqrestore(&dev_lock, flags)
Here, the reads from safe_register will cause the I/O chipset to flush any Here, the reads from safe_register will cause the I/O chipset to flush any
pending writes before actually posting the read to the chipset, preventing pending writes before actually posting the read to the chipset, preventing