Zsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}(hhparenthuba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget/translations/zh_CN/RCU/lockdepmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}(hhhh2ubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget/translations/zh_TW/RCU/lockdepmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}(hhhhFubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget/translations/it_IT/RCU/lockdepmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}(hhhhZubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget/translations/ja_JP/RCU/lockdepmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}(hhhhnubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget/translations/ko_KR/RCU/lockdepmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}(hhhhubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget/translations/sp_SP/RCU/lockdepmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}(hhhhubah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh9/var/lib/git/docbuild/linux/Documentation/RCU/lockdep.rsthKubhsection)}(hhh](htitle)}(hRCU and lockdep checkingh]hRCU and lockdep checking}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXzAll flavors of RCU have lockdep checking available, so that lockdep is aware of when each task enters and leaves any flavor of RCU read-side critical section. Each flavor of RCU is tracked separately (but note that this is not the case in 2.6.32 and earlier). This allows lockdep's tracking to include RCU state, which can sometimes help when debugging deadlocks and the like.h]hX|All flavors of RCU have lockdep checking available, so that lockdep is aware of when each task enters and leaves any flavor of RCU read-side critical section. Each flavor of RCU is tracked separately (but note that this is not the case in 2.6.32 and earlier). This allows lockdep’s tracking to include RCU state, which can sometimes help when debugging deadlocks and the like.}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hOIn addition, RCU provides the following primitives that check lockdep's state::h]hPIn addition, RCU provides the following primitives that check lockdep’s state:}(hNIn addition, RCU provides the following primitives that check lockdep's state:hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(hX rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh. rcu_read_lock_sched_held() for RCU-sched. rcu_read_lock_any_held() for any of normal RCU, RCU-bh, and RCU-sched. srcu_read_lock_held() for SRCU. rcu_read_lock_trace_held() for RCU Tasks Trace.h]hX rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh. rcu_read_lock_sched_held() for RCU-sched. rcu_read_lock_any_held() for any of normal RCU, RCU-bh, and RCU-sched. srcu_read_lock_held() for SRCU. rcu_read_lock_trace_held() for RCU Tasks Trace.}(hhhhubah}(h]h ]h"]h$]h&]hhuh1hhhhKhhhhubh)}(hThese functions are conservative, and will therefore return 1 if they aren't certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set). This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false positives when lockdep is disabled.h]hThese functions are conservative, and will therefore return 1 if they aren’t certain (for example, if CONFIG_DEBUG_LOCK_ALLOC is not set). This prevents things like WARN_ON(!rcu_read_lock_held()) from giving false positives when lockdep is disabled.}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hrIn addition, a separate kernel config parameter CONFIG_PROVE_RCU enables checking of rcu_dereference() primitives:h]hrIn addition, a separate kernel config parameter CONFIG_PROVE_RCU enables checking of rcu_dereference() primitives:}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hhh]hdefinition_list)}(hhh](hdefinition_list_item)}(h=rcu_dereference(p): Check for RCU read-side critical section.h](hterm)}(hrcu_dereference(p):h]hrcu_dereference(p):}(hj(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK hj ubh definition)}(hhh]h)}(h)Check for RCU read-side critical section.h]h)Check for RCU read-side critical section.}(hj;hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hj6ubah}(h]h ]h"]h$]h&]uh1j4hj ubeh}(h]h ]h"]h$]h&]uh1jhhhK hjubj)}(hCrcu_dereference_bh(p): Check for RCU-bh read-side critical section.h](j%)}(hrcu_dereference_bh(p):h]hrcu_dereference_bh(p):}(hjYhjWhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK"hjSubj5)}(hhh]h)}(h,Check for RCU-bh read-side critical section.h]h,Check for RCU-bh read-side critical section.}(hjjhjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjeubah}(h]h ]h"]h$]h&]uh1j4hjSubeh}(h]h ]h"]h$]h&]uh1jhhhK"hjubj)}(hIrcu_dereference_sched(p): Check for RCU-sched read-side critical section.h](j%)}(hrcu_dereference_sched(p):h]hrcu_dereference_sched(p):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK$hjubj5)}(hhh]h)}(h/Check for RCU-sched read-side critical section.h]h/Check for RCU-sched read-side critical section.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK$hjubj)}(hCsrcu_dereference(p, sp): Check for SRCU read-side critical section.h](j%)}(hsrcu_dereference(p, sp):h]hsrcu_dereference(p, sp):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK&hjubj5)}(hhh]h)}(h*Check for SRCU read-side critical section.h]h*Check for SRCU read-side critical section.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hjubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK&hjubj)}(hrcu_dereference_check(p, c): Use explicit check expression "c" along with rcu_read_lock_held(). This is useful in code that is invoked by both RCU readers and updaters.h](j%)}(hrcu_dereference_check(p, c):h]hrcu_dereference_check(p, c):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK*hjubj5)}(hhh]h)}(hUse explicit check expression "c" along with rcu_read_lock_held(). This is useful in code that is invoked by both RCU readers and updaters.h]hUse explicit check expression “c” along with rcu_read_lock_held(). This is useful in code that is invoked by both RCU readers and updaters.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hjubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK*hjubj)}(hrcu_dereference_bh_check(p, c): Use explicit check expression "c" along with rcu_read_lock_bh_held(). This is useful in code that is invoked by both RCU-bh readers and updaters.h](j%)}(hrcu_dereference_bh_check(p, c):h]hrcu_dereference_bh_check(p, c):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK.hjubj5)}(hhh]h)}(hUse explicit check expression "c" along with rcu_read_lock_bh_held(). This is useful in code that is invoked by both RCU-bh readers and updaters.h]hUse explicit check expression “c” along with rcu_read_lock_bh_held(). This is useful in code that is invoked by both RCU-bh readers and updaters.}(hj&hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hj!ubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK.hjubj)}(hrcu_dereference_sched_check(p, c): Use explicit check expression "c" along with rcu_read_lock_sched_held(). This is useful in code that is invoked by both RCU-sched readers and updaters.h](j%)}(h"rcu_dereference_sched_check(p, c):h]h"rcu_dereference_sched_check(p, c):}(hjDhjBhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK2hj>ubj5)}(hhh]h)}(hUse explicit check expression "c" along with rcu_read_lock_sched_held(). This is useful in code that is invoked by both RCU-sched readers and updaters.h]hUse explicit check expression “c” along with rcu_read_lock_sched_held(). This is useful in code that is invoked by both RCU-sched readers and updaters.}(hjUhjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjPubah}(h]h ]h"]h$]h&]uh1j4hj>ubeh}(h]h ]h"]h$]h&]uh1jhhhK2hjubj)}(hsrcu_dereference_check(p, c): Use explicit check expression "c" along with srcu_read_lock_held(). This is useful in code that is invoked by both SRCU readers and updaters.h](j%)}(hsrcu_dereference_check(p, c):h]hsrcu_dereference_check(p, c):}(hjshjqhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK6hjmubj5)}(hhh]h)}(hUse explicit check expression "c" along with srcu_read_lock_held(). This is useful in code that is invoked by both SRCU readers and updaters.h]hUse explicit check expression “c” along with srcu_read_lock_held(). This is useful in code that is invoked by both SRCU readers and updaters.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjubah}(h]h ]h"]h$]h&]uh1j4hjmubeh}(h]h ]h"]h$]h&]uh1jhhhK6hjubj)}(hArcu_dereference_raw(p): Don't check. (Use sparingly, if at all.)h](j%)}(hrcu_dereference_raw(p):h]hrcu_dereference_raw(p):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK8hjubj5)}(hhh]h)}(h)Don't check. (Use sparingly, if at all.)h]h+Don’t check. (Use sparingly, if at all.)}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK8hjubj)}(hSrcu_dereference_raw_check(p): Don't do lockdep at all. (Use sparingly, if at all.)h](j%)}(hrcu_dereference_raw_check(p):h]hrcu_dereference_raw_check(p):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK:hjubj5)}(hhh]h)}(h5Don't do lockdep at all. (Use sparingly, if at all.)h]h7Don’t do lockdep at all. (Use sparingly, if at all.)}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK;hjubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK:hjubj)}(hrcu_dereference_protected(p, c): Use explicit check expression "c", and omit all barriers and compiler constraints. This is useful when the data structure cannot change, for example, in code that is invoked only by updaters.h](j%)}(h rcu_dereference_protected(p, c):h]h rcu_dereference_protected(p, c):}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhK?hjubj5)}(hhh]h)}(hUse explicit check expression "c", and omit all barriers and compiler constraints. This is useful when the data structure cannot change, for example, in code that is invoked only by updaters.h]hUse explicit check expression “c”, and omit all barriers and compiler constraints. This is useful when the data structure cannot change, for example, in code that is invoked only by updaters.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hj ubah}(h]h ]h"]h$]h&]uh1j4hjubeh}(h]h ]h"]h$]h&]uh1jhhhK?hjubj)}(hrcu_access_pointer(p): Return the value of the pointer and omit all barriers, but retain the compiler constraints that prevent duplicating or coalescing. This is useful when testing the value of the pointer itself, for example, against NULL. h](j%)}(hrcu_access_pointer(p):h]hrcu_access_pointer(p):}(hj/hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hhhKEhj)ubj5)}(hhh]h)}(hReturn the value of the pointer and omit all barriers, but retain the compiler constraints that prevent duplicating or coalescing. This is useful when testing the value of the pointer itself, for example, against NULL.h]hReturn the value of the pointer and omit all barriers, but retain the compiler constraints that prevent duplicating or coalescing. This is useful when testing the value of the pointer itself, for example, against NULL.}(hj@hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhj;ubah}(h]h ]h"]h$]h&]uh1j4hj)ubeh}(h]h ]h"]h$]h&]uh1jhhhKEhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhhhNhNubh)}(hThe rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. For a moderately ornate example, consider the following::h]hThe rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. For a moderately ornate example, consider the following:}(hThe rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. For a moderately ornate example, consider the following:hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhhhhubh)}(hfile = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) || atomic_read(&files->count) == 1);h]hfile = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) || atomic_read(&files->count) == 1);}(hhhjsubah}(h]h ]h"]h$]h&]hhuh1hhhhKKhhhhubh)}(hThis expression picks up the pointer "fdt->fd[fd]" in an RCU-safe manner, and, if CONFIG_PROVE_RCU is configured, verifies that this expression is used in:h]hThis expression picks up the pointer “fdt->fd[fd]” in an RCU-safe manner, and, if CONFIG_PROVE_RCU is configured, verifies that this expression is used in:}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhhhhubhenumerated_list)}(hhh](h list_item)}(h0An RCU read-side critical section (implicit), orh]h)}(hjh]h0An RCU read-side critical section (implicit), or}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hwith files->file_lock held, orh]h)}(hjh]hwith files->file_lock held, or}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hon an unshared files_struct. h]h)}(hon an unshared files_struct.h]hon an unshared files_struct.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhhhhhhhKSubh)}(hXIn case (1), the pointer is picked up in an RCU-safe manner for vanilla RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater code, it could instead be written as follows::h]hXIn case (1), the pointer is picked up in an RCU-safe manner for vanilla RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater code, it could instead be written as follows:}(hXIn case (1), the pointer is picked up in an RCU-safe manner for vanilla RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater code, it could instead be written as follows:hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKWhhhhubh)}(hfile = rcu_dereference_protected(fdt->fd[fd], lockdep_is_held(&files->file_lock) || atomic_read(&files->count) == 1);h]hfile = rcu_dereference_protected(fdt->fd[fd], lockdep_is_held(&files->file_lock) || atomic_read(&files->count) == 1);}(hhhjubah}(h]h ]h"]h$]h&]hhuh1hhhhK^hhhhubh)}(hXThis would verify cases #2 and #3 above, and furthermore lockdep would complain even if this was used in an RCU read-side critical section unless one of these two cases held. Because rcu_dereference_protected() omits all barriers and compiler constraints, it generates better code than do the other flavors of rcu_dereference(). On the other hand, it is illegal to use rcu_dereference_protected() if either the RCU-protected pointer or the RCU-protected data that it points to can change concurrently.h]hXThis would verify cases #2 and #3 above, and furthermore lockdep would complain even if this was used in an RCU read-side critical section unless one of these two cases held. Because rcu_dereference_protected() omits all barriers and compiler constraints, it generates better code than do the other flavors of rcu_dereference(). On the other hand, it is illegal to use rcu_dereference_protected() if either the RCU-protected pointer or the RCU-protected data that it points to can change concurrently.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhhhhubh)}(hXLike rcu_dereference(), when lockdep is enabled, RCU list and hlist traversal primitives check for being called from within an RCU read-side critical section. However, a lockdep expression can be passed to them as a additional optional argument. With this lockdep expression, these traversal primitives will complain only if the lockdep expression is false and they are called from outside any RCU read-side critical section.h]hXLike rcu_dereference(), when lockdep is enabled, RCU list and hlist traversal primitives check for being called from within an RCU read-side critical section. However, a lockdep expression can be passed to them as a additional optional argument. With this lockdep expression, these traversal primitives will complain only if the lockdep expression is false and they are called from outside any RCU read-side critical section.}(hjhjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhhhhubh)}(hFor example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. It is thus implemented as follows::h]hFor example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. It is thus implemented as follows:}(hFor example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. It is thus implemented as follows:hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhhhhubh)}(h#define for_each_pwq(pwq, wq) list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node, lock_is_held(&(wq->mutex).dep_map))h]h#define for_each_pwq(pwq, wq) list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node, lock_is_held(&(wq->mutex).dep_map))}(hhhj/ubah}(h]h ]h"]h$]h&]hhuh1hhhhKuhhhhubeh}(h]rcu-and-lockdep-checkingah ]h"]rcu and lockdep checkingah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjherror_encodingUTF-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confapep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacefile_insertion_enabled raw_enabledKline_length_limitM'syntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_link embed_imagesenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}jBj?s nametypes}jBNsh}j?hs footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.