€•RSŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ7/translations/zh_CN/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ7/translations/zh_TW/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ7/translations/it_IT/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ7/translations/ja_JP/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ7/translations/ko_KR/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ7/translations/sp_SP/process/volatile-considered-harmful”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒtarget”“”)”}”(hŒ .. _volatile_considered_harmful:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œvolatile-considered-harmful”uh1h¡h KhhhžhhŸŒQ/var/lib/git/docbuild/linux/Documentation/process/volatile-considered-harmful.rst”ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ0Why the "volatile" type class should not be used”h]”hŒ4Why the “volatile†type class should not be used”…””}”(hh·hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhh²hžhhŸh¯h KubhŒ paragraph”“”)”}”(hXºC programmers have often taken volatile to mean that the variable could be changed outside of the current thread of execution; as a result, they are sometimes tempted to use it in kernel code when shared data structures are being used. In other words, they have been known to treat volatile types as a sort of easy atomic variable, which they are not. The use of volatile in kernel code is almost never correct; this document describes why.”h]”hXºC programmers have often taken volatile to mean that the variable could be changed outside of the current thread of execution; as a result, they are sometimes tempted to use it in kernel code when shared data structures are being used. In other words, they have been known to treat volatile types as a sort of easy atomic variable, which they are not. The use of volatile in kernel code is almost never correct; this document describes why.”…””}”(hhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hX¢The key point to understand with regard to volatile is that its purpose is to suppress optimization, which is almost never what one really wants to do. In the kernel, one must protect shared data structures against unwanted concurrent access, which is very much a different task. The process of protecting against unwanted concurrency will also avoid almost all optimization-related problems in a more efficient way.”h]”hX¢The key point to understand with regard to volatile is that its purpose is to suppress optimization, which is almost never what one really wants to do. In the kernel, one must protect shared data structures against unwanted concurrent access, which is very much a different task. The process of protecting against unwanted concurrency will also avoid almost all optimization-related problems in a more efficient way.”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hX¡Like volatile, the kernel primitives which make concurrent access to data safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent unwanted optimization. If they are being used properly, there will be no need to use volatile as well. If volatile is still necessary, there is almost certainly a bug in the code somewhere. In properly-written kernel code, volatile can only serve to slow things down.”h]”hX¡Like volatile, the kernel primitives which make concurrent access to data safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent unwanted optimization. If they are being used properly, there will be no need to use volatile as well. If volatile is still necessary, there is almost certainly a bug in the code somewhere. In properly-written kernel code, volatile can only serve to slow things down.”…””}”(hhãhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hŒ)Consider a typical block of kernel code::”h]”hŒ(Consider a typical block of kernel code:”…””}”(hhñhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhŒ literal_block”“”)”}”(hŒrspin_lock(&the_lock); do_something_on(&shared_data); do_something_else_with(&shared_data); spin_unlock(&the_lock);”h]”hŒrspin_lock(&the_lock); do_something_on(&shared_data); do_something_else_with(&shared_data); spin_unlock(&the_lock);”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1hÿhŸh¯h Khh²hžhubhÆ)”}”(hXQIf all the code follows the locking rules, the value of shared_data cannot change unexpectedly while the_lock is held. Any other code which might want to play with that data will be waiting on the lock. The spinlock primitives act as memory barriers - they are explicitly written to do so - meaning that data accesses will not be optimized across them. So the compiler might think it knows what will be in shared_data, but the spin_lock() call, since it acts as a memory barrier, will force it to forget anything it knows. There will be no optimization problems with accesses to that data.”h]”hXQIf all the code follows the locking rules, the value of shared_data cannot change unexpectedly while the_lock is held. Any other code which might want to play with that data will be waiting on the lock. The spinlock primitives act as memory barriers - they are explicitly written to do so - meaning that data accesses will not be optimized across them. So the compiler might think it knows what will be in shared_data, but the spin_lock() call, since it acts as a memory barrier, will force it to forget anything it knows. There will be no optimization problems with accesses to that data.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K#hh²hžhubhÆ)”}”(hXŒIf shared_data were declared volatile, the locking would still be necessary. But the compiler would also be prevented from optimizing access to shared_data _within_ the critical section, when we know that nobody else can be working with it. While the lock is held, shared_data is not volatile. When dealing with shared data, proper locking makes volatile unnecessary - and potentially harmful.”h]”hXŒIf shared_data were declared volatile, the locking would still be necessary. But the compiler would also be prevented from optimizing access to shared_data _within_ the critical section, when we know that nobody else can be working with it. While the lock is held, shared_data is not volatile. When dealing with shared data, proper locking makes volatile unnecessary - and potentially harmful.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K-hh²hžhubhÆ)”}”(hX$The volatile storage class was originally meant for memory-mapped I/O registers. Within the kernel, register accesses, too, should be protected by locks, but one also does not want the compiler "optimizing" register accesses within a critical section. But, within the kernel, I/O memory accesses are always done through accessor functions; accessing I/O memory directly through pointers is frowned upon and does not work on all architectures. Those accessors are written to prevent unwanted optimization, so, once again, volatile is unnecessary.”h]”hX(The volatile storage class was originally meant for memory-mapped I/O registers. Within the kernel, register accesses, too, should be protected by locks, but one also does not want the compiler “optimizing†register accesses within a critical section. But, within the kernel, I/O memory accesses are always done through accessor functions; accessing I/O memory directly through pointers is frowned upon and does not work on all architectures. Those accessors are written to prevent unwanted optimization, so, once again, volatile is unnecessary.”…””}”(hj-hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K4hh²hžhubhÆ)”}”(hŒ©Another situation where one might be tempted to use volatile is when the processor is busy-waiting on the value of a variable. The right way to perform a busy wait is::”h]”hŒ¨Another situation where one might be tempted to use volatile is when the processor is busy-waiting on the value of a variable. The right way to perform a busy wait is:”…””}”(hj;hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K=hh²hžhubj)”}”(hŒ3while (my_variable != what_i_want) cpu_relax();”h]”hŒ3while (my_variable != what_i_want) cpu_relax();”…””}”hjIsbah}”(h]”h ]”h"]”h$]”h&]”jjuh1hÿhŸh¯h KAhh²hžhubhÆ)”}”(hXThe cpu_relax() call can lower CPU power consumption or yield to a hyperthreaded twin processor; it also happens to serve as a compiler barrier, so, once again, volatile is unnecessary. Of course, busy- waiting is generally an anti-social act to begin with.”h]”hXThe cpu_relax() call can lower CPU power consumption or yield to a hyperthreaded twin processor; it also happens to serve as a compiler barrier, so, once again, volatile is unnecessary. Of course, busy- waiting is generally an anti-social act to begin with.”…””}”(hjWhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KDhh²hžhubhÆ)”}”(hŒOThere are still a few rare situations where volatile makes sense in the kernel:”h]”hŒOThere are still a few rare situations where volatile makes sense in the kernel:”…””}”(hjehžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KIhh²hžhubhŒ block_quote”“”)”}”(hX—- The above-mentioned accessor functions might use volatile on architectures where direct I/O memory access does work. Essentially, each accessor call becomes a little critical section on its own and ensures that the access happens as expected by the programmer. - Inline assembly code which changes memory, but which has no other visible side effects, risks being deleted by GCC. Adding the volatile keyword to asm statements will prevent this removal. - The jiffies variable is special in that it can have a different value every time it is referenced, but it can be read without any special locking. So jiffies can be volatile, but the addition of other variables of this type is strongly frowned upon. Jiffies is considered to be a "stupid legacy" issue (Linus's words) in this regard; fixing it would be more trouble than it is worth. - Pointers to data structures in coherent memory which might be modified by I/O devices can, sometimes, legitimately be volatile. A ring buffer used by a network adapter, where that adapter changes pointers to indicate which descriptors have been processed, is an example of this type of situation. ”h]”hŒ bullet_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hXThe above-mentioned accessor functions might use volatile on architectures where direct I/O memory access does work. Essentially, each accessor call becomes a little critical section on its own and ensures that the access happens as expected by the programmer. ”h]”hÆ)”}”(hXThe above-mentioned accessor functions might use volatile on architectures where direct I/O memory access does work. Essentially, each accessor call becomes a little critical section on its own and ensures that the access happens as expected by the programmer.”h]”hXThe above-mentioned accessor functions might use volatile on architectures where direct I/O memory access does work. Essentially, each accessor call becomes a little critical section on its own and ensures that the access happens as expected by the programmer.”…””}”(hj„hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KLhj€ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~hj{ubj)”}”(hŒ¾Inline assembly code which changes memory, but which has no other visible side effects, risks being deleted by GCC. Adding the volatile keyword to asm statements will prevent this removal. ”h]”hÆ)”}”(hŒ½Inline assembly code which changes memory, but which has no other visible side effects, risks being deleted by GCC. Adding the volatile keyword to asm statements will prevent this removal.”h]”hŒ½Inline assembly code which changes memory, but which has no other visible side effects, risks being deleted by GCC. Adding the volatile keyword to asm statements will prevent this removal.”…””}”(hjœhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KQhj˜ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~hj{ubj)”}”(hX‚The jiffies variable is special in that it can have a different value every time it is referenced, but it can be read without any special locking. So jiffies can be volatile, but the addition of other variables of this type is strongly frowned upon. Jiffies is considered to be a "stupid legacy" issue (Linus's words) in this regard; fixing it would be more trouble than it is worth. ”h]”hÆ)”}”(hXThe jiffies variable is special in that it can have a different value every time it is referenced, but it can be read without any special locking. So jiffies can be volatile, but the addition of other variables of this type is strongly frowned upon. Jiffies is considered to be a "stupid legacy" issue (Linus's words) in this regard; fixing it would be more trouble than it is worth.”h]”hX‡The jiffies variable is special in that it can have a different value every time it is referenced, but it can be read without any special locking. So jiffies can be volatile, but the addition of other variables of this type is strongly frowned upon. Jiffies is considered to be a “stupid legacy†issue (Linus’s words) in this regard; fixing it would be more trouble than it is worth.”…””}”(hj´hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KUhj°ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~hj{ubj)”}”(hX*Pointers to data structures in coherent memory which might be modified by I/O devices can, sometimes, legitimately be volatile. A ring buffer used by a network adapter, where that adapter changes pointers to indicate which descriptors have been processed, is an example of this type of situation. ”h]”hÆ)”}”(hX)Pointers to data structures in coherent memory which might be modified by I/O devices can, sometimes, legitimately be volatile. A ring buffer used by a network adapter, where that adapter changes pointers to indicate which descriptors have been processed, is an example of this type of situation.”h]”hX)Pointers to data structures in coherent memory which might be modified by I/O devices can, sometimes, legitimately be volatile. A ring buffer used by a network adapter, where that adapter changes pointers to indicate which descriptors have been processed, is an example of this type of situation.”…””}”(hjÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K\hjÈubah}”(h]”h ]”h"]”h$]”h&]”uh1j~hj{ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jyhŸh¯h KLhjuubah}”(h]”h ]”h"]”h$]”h&]”uh1jshŸh¯h KLhh²hžhubhÆ)”}”(hX1For most code, none of the above justifications for volatile apply. As a result, the use of volatile is likely to be seen as a bug and will bring additional scrutiny to the code. Developers who are tempted to use volatile should take a step back and think about what they are truly trying to accomplish.”h]”hX1For most code, none of the above justifications for volatile apply. As a result, the use of volatile is likely to be seen as a bug and will bring additional scrutiny to the code. Developers who are tempted to use volatile should take a step back and think about what they are truly trying to accomplish.”…””}”(hjîhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kbhh²hžhubhÆ)”}”(hŒ²Patches to remove volatile variables are generally welcome - as long as they come with a justification which shows that the concurrency issues have been properly thought through.”h]”hŒ²Patches to remove volatile variables are generally welcome - as long as they come with a justification which shows that the concurrency issues have been properly thought through.”…””}”(hjühžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khhh²hžhubh±)”}”(hhh]”(h¶)”}”(hŒ References”h]”hŒ References”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhj hžhhŸh¯h KnubhÆ)”}”(hŒ$[1] https://lwn.net/Articles/233481/”h]”(hŒ[1] ”…””}”(hjhžhhŸNh NubhŒ reference”“”)”}”(hŒ https://lwn.net/Articles/233481/”h]”hŒ https://lwn.net/Articles/233481/”…””}”(hj%hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j'uh1j#hjubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kphj hžhubhÆ)”}”(hŒ$[2] https://lwn.net/Articles/233482/”h]”(hŒ[2] ”…””}”(hj:hžhhŸNh Nubj$)”}”(hŒ https://lwn.net/Articles/233482/”h]”hŒ https://lwn.net/Articles/233482/”…””}”(hjBhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jDuh1j#hj:ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Krhj hžhubeh}”(h]”Œ references”ah ]”h"]”Œ references”ah$]”h&]”uh1h°hh²hžhhŸh¯h Knubh±)”}”(hhh]”(h¶)”}”(hŒCredits”h]”hŒCredits”…””}”(hjbhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhj_hžhhŸh¯h KuubhÆ)”}”(hŒ-Original impetus and research by Randy Dunlap”h]”hŒ-Original impetus and research by Randy Dunlap”…””}”(hjphžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kwhj_hžhubhÆ)”}”(hŒWritten by Jonathan Corbet”h]”hŒWritten by Jonathan Corbet”…””}”(hj~hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kyhj_hžhubhÆ)”}”(hŒImprovements via comments from Satyam Sharma, Johannes Stezenbach, Jesper Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan Richter.”h]”hŒImprovements via comments from Satyam Sharma, Johannes Stezenbach, Jesper Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan Richter.”…””}”(hjŒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K{hj_hžhubeh}”(h]”Œcredits”ah ]”h"]”Œcredits”ah$]”h&]”uh1h°hh²hžhhŸh¯h Kuubeh}”(h]”(Œ.why-the-volatile-type-class-should-not-be-used”h®eh ]”h"]”(Œ0why the "volatile" type class should not be used”Œvolatile_considered_harmful”eh$]”h&]”uh1h°hhhžhhŸh¯h KŒexpect_referenced_by_name”}”j¨h£sŒexpect_referenced_by_id”}”h®h£subeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¯uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hµNŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÒŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¯Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”h®]”h£asŒnameids”}”(j¨h®j§j¤j\jYjŸjœuŒ nametypes”}”(j¨ˆj§‰j\‰jŸ‰uh}”(h®h²j¤h²jYj jœj_uŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hÆ)”}”(hhh]”hŒAHyperlink target "volatile-considered-harmful" is not referenced.”…””}”hj<sbah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhj9ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h¯Œline”Kuh1j7ubaŒ transformer”NŒ include_log”]”Œ decoration”Nhžhub.