Re: [PATCH 14/25] Docs: kernel-hacking: Rewrite local_irq_{disable,enable,save,restore}

[Michael Witten <mfwitten@xxxxxxxxx>]

On Wed, Mar 3, 2010 at 12:01, Jonathan Corbet <corbet@xxxxxxx> wrote:
> On Sat, 27 Feb 2010 07:10:57 +0000
> Michael Witten <mfwitten@xxxxxxxxx> wrote:
>
>> +    to respond to hard interrupts. Consequently, in the simplest case,
>> +    a block of code can be rendered atomic by placing
>> +    <function>local_irq_disable()</function> before the block and
>> +    <function>local_irq_enable()</function> after the block.
>> +   </para>
>
> But disabling interrupts does not, in itself, make code atomic,
> please don't say that.

Could you offer language that is more suitable?

Perhaps the words 'atomic' and 'atomicity' could be replaced with
'locally atomic' and 'local atomicity':

diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl
index 9453235..68ae82d 100644
--- a/Documentation/DocBook/kernel-hacking.tmpl
+++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -688,9 +688,9 @@ printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
     with the assurance that the corresponding local CPU won't be interrupted
     until it has completed executing that sequence of instructions; under
     these needs, such a sequence of instructions is considered as a whole to
-    be <firstterm>atomic</firstterm> (that is, 'indivisible'). The routines
-    discussed here are helpful in creating such
-    <firstterm>atomicity</firstterm>.
+    be <firstterm>locally atomic</firstterm> (that is, 'indivisible' on the
+    corresponding local CPU). The routines discussed here are helpful in
+    creating such <firstterm>local atomicity</firstterm>.
    </para>
 
    <para>
@@ -700,23 +700,23 @@ printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
     to ignore hard interrupts; by executing
     <function>local_irq_enable()</function>, a local CPU is instructed
     to respond to hard interrupts. Consequently, in the simplest case,
-    a block of code can be rendered atomic by placing
+    a block of code can be rendered locally atomic by placing
     <function>local_irq_disable()</function> before the block and
     <function>local_irq_enable()</function> after the block.
    </para>
 
    <para>
-    However, what if one such atomic block calls a function that runs
-    another such atomic block? In that case, this latter atomic block
+    However, what if one such locally atomic block calls a function that runs
+    another such locally atomic block? In that case, this latter block
     might run <function>local_irq_enable()</function>
-    before the first atomic block finishes, thereby ruining the atomicity
+    before the first block finishes, thereby ruining the local atomicity
     of the first block.
    </para>
 
    <para>
     This problem can be solved by noting whether a local CPU is already
-    ignoring hard interrupts when entering an atomic block and then restoring
-    that same status upon exiting the atomic block, all of which
+    ignoring hard interrupts when entering a locally atomic block, and then
+    restoring that same status upon exiting the block, all of which
     can be achieved by replacing
     <function>local_irq_{disable,enable}()</function> with
     <function>local_irq_{save,restore}(<varname>flags</varname>)</function>
@@ -759,7 +759,7 @@ printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
     then that local CPU will continue to ignore hard interrupts when the
     corresponding
     <function>local_irq_restore(<varname>flags</varname>)</function> is
-    used, thereby allowing for the nesting of atomic blocks. However,
+    used, thereby allowing for the nesting of locally atomic blocks. However,
     if a local CPU is responding to hard interrupts when
     <function>local_irq_save(<varname>flags</varname>)</function> is used,
     then that local CPU will once again respond to hard interrupts when
@@ -783,7 +783,8 @@ printk(KERN_INFO "my ip: %pI4\n", &amp;ipaddress);
 
    <para>
     There are also other means by which kernel code can achieve synchronization
-    and atomicity through locking mechanisms.
+    and atomicity through locking mechanisms, and they are especially important
+    for code that may run concurrently across multiple CPUs.
    </para>
   </sect1>
 

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html