lkml.org 
[lkml]   [2017]   [Jun]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v2 29/31] io_ordering.txt: standardize document format
    Date
    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>
    ---
    Documentation/io_ordering.txt | 62 +++++++++++++++++++++++--------------------
    1 file changed, 33 insertions(+), 29 deletions(-)

    diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.txt
    index 9faae6f26d32..2ab303ce9a0d 100644
    --- a/Documentation/io_ordering.txt
    +++ b/Documentation/io_ordering.txt
    @@ -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
    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
    @@ -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
    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: val = readl(my_status);
    -CPU A: ...
    -CPU A: writel(newval, ring_ptr);
    -CPU A: spin_unlock_irqrestore(&dev_lock, flags)
    - ...
    -CPU B: spin_lock_irqsave(&dev_lock, flags)
    -CPU B: val = readl(my_status);
    -CPU B: ...
    -CPU B: writel(newval2, ring_ptr);
    -CPU B: spin_unlock_irqrestore(&dev_lock, flags)
    - ...
    + ...
    + CPU A: spin_lock_irqsave(&dev_lock, flags)
    + CPU A: val = readl(my_status);
    + CPU A: ...
    + CPU A: writel(newval, ring_ptr);
    + CPU A: spin_unlock_irqrestore(&dev_lock, flags)
    + ...
    + CPU B: spin_lock_irqsave(&dev_lock, flags)
    + CPU B: val = readl(my_status);
    + CPU B: ...
    + CPU B: writel(newval2, ring_ptr);
    + CPU B: spin_unlock_irqrestore(&dev_lock, flags)
    + ...

    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: val = readl(my_status);
    -CPU A: ...
    -CPU A: writel(newval, ring_ptr);
    -CPU A: (void)readl(safe_register); /* maybe a config register? */
    -CPU A: spin_unlock_irqrestore(&dev_lock, flags)
    - ...
    -CPU B: spin_lock_irqsave(&dev_lock, flags)
    -CPU B: val = readl(my_status);
    -CPU B: ...
    -CPU B: writel(newval2, ring_ptr);
    -CPU B: (void)readl(safe_register); /* maybe a config register? */
    -CPU B: spin_unlock_irqrestore(&dev_lock, flags)
    + ...
    + CPU A: spin_lock_irqsave(&dev_lock, flags)
    + CPU A: val = readl(my_status);
    + CPU A: ...
    + CPU A: writel(newval, ring_ptr);
    + CPU A: (void)readl(safe_register); /* maybe a config register? */
    + CPU A: spin_unlock_irqrestore(&dev_lock, flags)
    + ...
    + CPU B: spin_lock_irqsave(&dev_lock, flags)
    + CPU B: val = readl(my_status);
    + CPU B: ...
    + CPU B: writel(newval2, ring_ptr);
    + CPU B: (void)readl(safe_register); /* maybe a config register? */
    + CPU B: spin_unlock_irqrestore(&dev_lock, flags)

    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
    --
    2.9.4
    \
     
     \ /
      Last update: 2017-06-17 17:44    [W:3.141 / U:0.004 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site