aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMathieu Desnoyers <mathieu.desnoyers@polymtl.ca>2007-11-05 14:50:54 -0800
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-11-05 15:12:32 -0800
commite1265205c0ee3919c3f2c750662630154c8faab2 (patch)
tree904809bdacafb24d82d69c564251c3967ded9986
parentbf2cdef30667d0d3d09c6934c95d1fb87c43345a (diff)
local_t Documentation update
Grant Grundler was asking for more detail about correct usage of local atomic operations and suggested adding the resulting summary to local_ops.txt. "Please add a bit more detail. If DaveM is correct (he normally is), then there must be limits on how the local_t can be used in the kernel process and interrupt contexts. I'd like those rules spelled out very clearly since it's easy to get wrong and tracking down such a bug is quite painful." Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca> Signed-off-by: Grant Grundler <grundler@parisc-linux.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r--Documentation/local_ops.txt23
1 files changed, 23 insertions, 0 deletions
diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt
index 4269a1105b3..1a45f11e645 100644
--- a/Documentation/local_ops.txt
+++ b/Documentation/local_ops.txt
@@ -68,6 +68,29 @@ typedef struct { atomic_long_t a; } local_t;
variable can be read when reading some _other_ cpu's variables.
+* Rules to follow when using local atomic operations
+
+- Variables touched by local ops must be per cpu variables.
+- _Only_ the CPU owner of these variables must write to them.
+- This CPU can use local ops from any context (process, irq, softirq, nmi, ...)
+ to update its local_t variables.
+- Preemption (or interrupts) must be disabled when using local ops in
+ process context to make sure the process won't be migrated to a
+ different CPU between getting the per-cpu variable and doing the
+ actual local op.
+- When using local ops in interrupt context, no special care must be
+ taken on a mainline kernel, since they will run on the local CPU with
+ preemption already disabled. I suggest, however, to explicitly
+ disable preemption anyway to make sure it will still work correctly on
+ -rt kernels.
+- Reading the local cpu variable will provide the current copy of the
+ variable.
+- Reads of these variables can be done from any CPU, because updates to
+ "long", aligned, variables are always atomic. Since no memory
+ synchronization is done by the writer CPU, an outdated copy of the
+ variable can be read when reading some _other_ cpu's variables.
+
+
* How to use local atomic operations
#include <linux/percpu.h>