local_t Documentation update 2
PATCH 1/1 local_t Documentation update 2
local_t Documentation update 2
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."
It applies on top of 2.6.23-rc3-mm1.
--- Documentation/local_ops.txt | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/local_ops.txt +23 -0
@@ -45,6 +45,29 @@ long fails. The definition looks like : typedef struct { atomic_long_t a; } local_t; +* 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>
Signature · 3 lines
Mathieu Desnoyers Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68
Quoted 10 lines · Mathieu Desnoyers
local_tDocumentation update 2Grant 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_tcan 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."
Quoted 4 lines
It applies on top of 2.6.23-rc3-mm1.
Signed-off-by Mathieu Desnoyers <[email protected]>CC Grant Grundler <[email protected]>
thanks!
grant
Quoted 43 lines
--- Documentation/local_ops.txt | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)Index:
linux-2.6-lttng/Documentation/local_ops.txt
===================================================================Documentation/local_ops.txt +23
-0@@ -45,6 +45,29 @@ long fails. The definition looks like : typedef struct { atomic_long_t a; } local_t; +* 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>Signature · 4 lines
-- Mathieu Desnoyers Computer Engineering Ph.D. Student, Ecole Polytechnique de Montreal OpenPGP key fingerprint: 8CD5 52C3 8E3C 4140 715F BA06 3F25 A8FE 3BAE 9A68