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>

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>
Mathieu Desnoyers · Linus Torvalds
1 parent bf2cdef306
Showing 1 changed file with 23 additions and 0 deletions Side-by-side Diff
Documentation/local_ops.txt
@@ -68,6 +68,29 @@
   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>
...	...	@@ -68,6 +68,29 @@
68	68	variable can be read when reading some _other_ cpu's variables.
69	69
70	70
	71	+* Rules to follow when using local atomic operations
	72	+
	73	+- Variables touched by local ops must be per cpu variables.
	74	+- _Only_ the CPU owner of these variables must write to them.
	75	+- This CPU can use local ops from any context (process, irq, softirq, nmi, ...)
	76	+ to update its local_t variables.
	77	+- Preemption (or interrupts) must be disabled when using local ops in
	78	+ process context to make sure the process won't be migrated to a
	79	+ different CPU between getting the per-cpu variable and doing the
	80	+ actual local op.
	81	+- When using local ops in interrupt context, no special care must be
	82	+ taken on a mainline kernel, since they will run on the local CPU with
	83	+ preemption already disabled. I suggest, however, to explicitly
	84	+ disable preemption anyway to make sure it will still work correctly on
	85	+ -rt kernels.
	86	+- Reading the local cpu variable will provide the current copy of the
	87	+ variable.
	88	+- Reads of these variables can be done from any CPU, because updates to
	89	+ "long", aligned, variables are always atomic. Since no memory
	90	+ synchronization is done by the writer CPU, an outdated copy of the
	91	+ variable can be read when reading some _other_ cpu's variables.
	92	+
	93	+
71	94	* How to use local atomic operations
72	95
73	96	#include <linux/percpu.h>