aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/volatile-considered-harmful.txt
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2007-06-23 20:16:41 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-06-24 11:59:11 -0400
commit0faa45480261a52323fe88bfab6aea1e8eb87b65 (patch)
treebccf0b743fdb226fb615f5afc8a6cb473fff5a30 /Documentation/volatile-considered-harmful.txt
parent4c18a325645bf98850ca84037fff05de1836e785 (diff)
"volatile considered harmful"
Encourage developers to avoid the volatile type class in kernel code. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/volatile-considered-harmful.txt')
-rw-r--r--Documentation/volatile-considered-harmful.txt119
1 files changed, 119 insertions, 0 deletions
diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt
new file mode 100644
index 000000000000..10c2e411cca8
--- /dev/null
+++ b/Documentation/volatile-considered-harmful.txt
@@ -0,0 +1,119 @@
1Why the "volatile" type class should not be used
2------------------------------------------------
3
4C programmers have often taken volatile to mean that the variable could be
5changed outside of the current thread of execution; as a result, they are
6sometimes tempted to use it in kernel code when shared data structures are
7being used. In other words, they have been known to treat volatile types
8as a sort of easy atomic variable, which they are not. The use of volatile in
9kernel code is almost never correct; this document describes why.
10
11The key point to understand with regard to volatile is that its purpose is
12to suppress optimization, which is almost never what one really wants to
13do. In the kernel, one must protect shared data structures against
14unwanted concurrent access, which is very much a different task. The
15process of protecting against unwanted concurrency will also avoid almost
16all optimization-related problems in a more efficient way.
17
18Like volatile, the kernel primitives which make concurrent access to data
19safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent
20unwanted optimization. If they are being used properly, there will be no
21need to use volatile as well. If volatile is still necessary, there is
22almost certainly a bug in the code somewhere. In properly-written kernel
23code, volatile can only serve to slow things down.
24
25Consider a typical block of kernel code:
26
27 spin_lock(&the_lock);
28 do_something_on(&shared_data);
29 do_something_else_with(&shared_data);
30 spin_unlock(&the_lock);
31
32If all the code follows the locking rules, the value of shared_data cannot
33change unexpectedly while the_lock is held. Any other code which might
34want to play with that data will be waiting on the lock. The spinlock
35primitives act as memory barriers - they are explicitly written to do so -
36meaning that data accesses will not be optimized across them. So the
37compiler might think it knows what will be in shared_data, but the
38spin_lock() call, since it acts as a memory barrier, will force it to
39forget anything it knows. There will be no optimization problems with
40accesses to that data.
41
42If shared_data were declared volatile, the locking would still be
43necessary. But the compiler would also be prevented from optimizing access
44to shared_data _within_ the critical section, when we know that nobody else
45can be working with it. While the lock is held, shared_data is not
46volatile. When dealing with shared data, proper locking makes volatile
47unnecessary - and potentially harmful.
48
49The volatile storage class was originally meant for memory-mapped I/O
50registers. Within the kernel, register accesses, too, should be protected
51by locks, but one also does not want the compiler "optimizing" register
52accesses within a critical section. But, within the kernel, I/O memory
53accesses are always done through accessor functions; accessing I/O memory
54directly through pointers is frowned upon and does not work on all
55architectures. Those accessors are written to prevent unwanted
56optimization, so, once again, volatile is unnecessary.
57
58Another situation where one might be tempted to use volatile is
59when the processor is busy-waiting on the value of a variable. The right
60way to perform a busy wait is:
61
62 while (my_variable != what_i_want)
63 cpu_relax();
64
65The cpu_relax() call can lower CPU power consumption or yield to a
66hyperthreaded twin processor; it also happens to serve as a memory barrier,
67so, once again, volatile is unnecessary. Of course, busy-waiting is
68generally an anti-social act to begin with.
69
70There are still a few rare situations where volatile makes sense in the
71kernel:
72
73 - The above-mentioned accessor functions might use volatile on
74 architectures where direct I/O memory access does work. Essentially,
75 each accessor call becomes a little critical section on its own and
76 ensures that the access happens as expected by the programmer.
77
78 - Inline assembly code which changes memory, but which has no other
79 visible side effects, risks being deleted by GCC. Adding the volatile
80 keyword to asm statements will prevent this removal.
81
82 - The jiffies variable is special in that it can have a different value
83 every time it is referenced, but it can be read without any special
84 locking. So jiffies can be volatile, but the addition of other
85 variables of this type is strongly frowned upon. Jiffies is considered
86 to be a "stupid legacy" issue (Linus's words) in this regard; fixing it
87 would be more trouble than it is worth.
88
89 - Pointers to data structures in coherent memory which might be modified
90 by I/O devices can, sometimes, legitimately be volatile. A ring buffer
91 used by a network adapter, where that adapter changes pointers to
92 indicate which descriptors have been processed, is an example of this
93 type of situation.
94
95For most code, none of the above justifications for volatile apply. As a
96result, the use of volatile is likely to be seen as a bug and will bring
97additional scrutiny to the code. Developers who are tempted to use
98volatile should take a step back and think about what they are truly trying
99to accomplish.
100
101Patches to remove volatile variables are generally welcome - as long as
102they come with a justification which shows that the concurrency issues have
103been properly thought through.
104
105
106NOTES
107-----
108
109[1] http://lwn.net/Articles/233481/
110[2] http://lwn.net/Articles/233482/
111
112CREDITS
113-------
114
115Original impetus and research by Randy Dunlap
116Written by Jonathan Corbet
117Improvements via coments from Satyam Sharma, Johannes Stezenbach, Jesper
118 Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan
119 Richter.