€•BD      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ/translations/zh_CN/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/zh_TW/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/it_IT/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/ja_JP/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/ko_KR/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/sp_SP/RCU/NMI-RCU”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒtarget”“”)”}”(hŒ.. _NMI_rcu_doc:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œnmi-rcu-doc”uh1h¡h KhhhžhhŸŒ9/var/lib/git/docbuild/linux/Documentation/RCU/NMI-RCU.rst”ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ)Using RCU to Protect Dynamic NMI Handlers”h]”hŒ)Using RCU to Protect Dynamic NMI Handlers”…””}”(hh·hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhh²hžhhŸh¯h KubhŒ	paragraph”“”)”}”(hXB  Although RCU is usually used to protect read-mostly data structures,
it is possible to use RCU to provide dynamic non-maskable interrupt
handlers, as well as dynamic irq handlers.  This document describes
how to do this, drawing loosely from Zwane Mwaikambo's NMI-timer
work in an old version of "arch/x86/kernel/traps.c".”h]”hXH  Although RCU is usually used to protect read-mostly data structures,
it is possible to use RCU to provide dynamic non-maskable interrupt
handlers, as well as dynamic irq handlers.  This document describes
how to do this, drawing loosely from Zwane Mwaikamboâ€™s NMI-timer
work in an old version of â€œarch/x86/kernel/traps.câ€.”…””}”(hhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hŒTThe relevant pieces of code are listed below, each followed by a
brief explanation::”h]”hŒSThe relevant pieces of code are listed below, each followed by a
brief explanation:”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhŒliteral_block”“”)”}”(hŒRstatic int dummy_nmi_callback(struct pt_regs *regs, int cpu)
{
        return 0;
}”h]”hŒRstatic int dummy_nmi_callback(struct pt_regs *regs, int cpu)
{
        return 0;
}”…””}”hhåsbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1hãhŸh¯h Khh²hžhubhÆ)”}”(hŒÇThe dummy_nmi_callback() function is a "dummy" NMI handler that does
nothing, but returns zero, thus saying that it did nothing, allowing
the NMI handler to take the default machine-specific action::”h]”hŒÊThe dummy_nmi_callback() function is a â€œdummyâ€ NMI handler that does
nothing, but returns zero, thus saying that it did nothing, allowing
the NMI handler to take the default machine-specific action:”…””}”(hhõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhä)”}”(hŒ8static nmi_callback_t nmi_callback = dummy_nmi_callback;”h]”hŒ8static nmi_callback_t nmi_callback = dummy_nmi_callback;”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”hóhôuh1hãhŸh¯h Khh²hžhubhÆ)”}”(hŒTThis nmi_callback variable is a global function pointer to the current
NMI handler::”h]”hŒSThis nmi_callback variable is a global function pointer to the current
NMI handler:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhä)”}”(hX  void do_nmi(struct pt_regs * regs, long error_code)
{
        int cpu;

        nmi_enter();

        cpu = smp_processor_id();
        ++nmi_count(cpu);

        if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
                default_do_nmi(regs);

        nmi_exit();
}”h]”hX  void do_nmi(struct pt_regs * regs, long error_code)
{
        int cpu;

        nmi_enter();

        cpu = smp_processor_id();
        ++nmi_count(cpu);

        if (!rcu_dereference_sched(nmi_callback)(regs, cpu))
                default_do_nmi(regs);

        nmi_exit();
}”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”hóhôuh1hãhŸh¯h Khh²hžhubhÆ)”}”(hX}  The do_nmi() function processes each NMI.  It first disables preemption
in the same way that a hardware irq would, then increments the per-CPU
count of NMIs.  It then invokes the NMI handler stored in the nmi_callback
function pointer.  If this handler returns zero, do_nmi() invokes the
default_do_nmi() function to handle a machine-specific NMI.  Finally,
preemption is restored.”h]”hX}  The do_nmi() function processes each NMI.  It first disables preemption
in the same way that a hardware irq would, then increments the per-CPU
count of NMIs.  It then invokes the NMI handler stored in the nmi_callback
function pointer.  If this handler returns zero, do_nmi() invokes the
default_do_nmi() function to handle a machine-specific NMI.  Finally,
preemption is restored.”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K-hh²hžhubhÆ)”}”(hX@  In theory, rcu_dereference_sched() is not needed, since this code runs
only on i386, which in theory does not need rcu_dereference_sched()
anyway.  However, in practice it is a good documentation aid, particularly
for anyone attempting to do something similar on Alpha or on systems
with aggressive optimizing compilers.”h]”hX@  In theory, rcu_dereference_sched() is not needed, since this code runs
only on i386, which in theory does not need rcu_dereference_sched()
anyway.  However, in practice it is a good documentation aid, particularly
for anyone attempting to do something similar on Alpha or on systems
with aggressive optimizing compilers.”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K4hh²hžhubhŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hŒ…Quick Quiz:
Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?
”h]”(hŒterm”“”)”}”(hŒQuick Quiz:”h]”hŒQuick Quiz:”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jT  hŸh¯h K;hjP  ubhŒ
definition”“”)”}”(hhh]”hÆ)”}”(hŒxWhy might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?”h]”hŒxWhy might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?”…””}”(hji  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K;hjf  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jd  hjP  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jN  hŸh¯h K;hjK  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jI  hh²hžhhŸh¯h NubhÆ)”}”(hŒ3:ref:`Answer to Quick Quiz <answer_quick_quiz_NMI>`”h]”h)”}”(hj‹  h]”hŒinline”“”)”}”(hj‹  h]”hŒAnswer to Quick Quiz”…””}”(hj’  hžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j  hj  ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”ŒRCU/NMI-RCU”Œ	refdomain”j  Œreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆŒ	reftarget”Œanswer_quick_quiz_nmi”uh1hhŸh¯h K=hj‰  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K=hh²hžhubhÆ)”}”(hŒ'Back to the discussion of NMI and RCU::”h]”hŒ&Back to the discussion of NMI and RCU:”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K?hh²hžhubhä)”}”(hŒfvoid set_nmi_callback(nmi_callback_t callback)
{
        rcu_assign_pointer(nmi_callback, callback);
}”h]”hŒfvoid set_nmi_callback(nmi_callback_t callback)
{
        rcu_assign_pointer(nmi_callback, callback);
}”…””}”hjÅ  sbah}”(h]”h ]”h"]”h$]”h&]”hóhôuh1hãhŸh¯h KAhh²hžhubhÆ)”}”(hX0  The set_nmi_callback() function registers an NMI handler.  Note that any
data that is to be used by the callback must be initialized up -before-
the call to set_nmi_callback().  On architectures that do not order
writes, the rcu_assign_pointer() ensures that the NMI handler sees the
initialized values::”h]”hX/  The set_nmi_callback() function registers an NMI handler.  Note that any
data that is to be used by the callback must be initialized up -before-
the call to set_nmi_callback().  On architectures that do not order
writes, the rcu_assign_pointer() ensures that the NMI handler sees the
initialized values:”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KFhh²hžhubhä)”}”(hŒ_void unset_nmi_callback(void)
{
        rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
}”h]”hŒ_void unset_nmi_callback(void)
{
        rcu_assign_pointer(nmi_callback, dummy_nmi_callback);
}”…””}”hjá  sbah}”(h]”h ]”h"]”h$]”h&]”hóhôuh1hãhŸh¯h KLhh²hžhubhÆ)”}”(hX'  This function unregisters an NMI handler, restoring the original
dummy_nmi_handler().  However, there may well be an NMI handler
currently executing on some other CPU.  We therefore cannot free
up any data structures used by the old NMI handler until execution
of it completes on all other CPUs.”h]”hX'  This function unregisters an NMI handler, restoring the original
dummy_nmi_handler().  However, there may well be an NMI handler
currently executing on some other CPU.  We therefore cannot free
up any data structures used by the old NMI handler until execution
of it completes on all other CPUs.”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KQhh²hžhubhÆ)”}”(hŒIOne way to accomplish this is via synchronize_rcu(), perhaps as
follows::”h]”hŒHOne way to accomplish this is via synchronize_rcu(), perhaps as
follows:”…””}”(hjý  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KWhh²hžhubhä)”}”(hŒ<unset_nmi_callback();
synchronize_rcu();
kfree(my_nmi_data);”h]”hŒ<unset_nmi_callback();
synchronize_rcu();
kfree(my_nmi_data);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”hóhôuh1hãhŸh¯h KZhh²hžhubhÆ)”}”(hXh  This works because (as of v4.20) synchronize_rcu() blocks until all
CPUs complete any preemption-disabled segments of code that they were
executing.
Since NMI handlers disable preemption, synchronize_rcu() is guaranteed
not to return until all ongoing NMI handlers exit.  It is therefore safe
to free up the handler's data as soon as synchronize_rcu() returns.”h]”hXj  This works because (as of v4.20) synchronize_rcu() blocks until all
CPUs complete any preemption-disabled segments of code that they were
executing.
Since NMI handlers disable preemption, synchronize_rcu() is guaranteed
not to return until all ongoing NMI handlers exit.  It is therefore safe
to free up the handlerâ€™s data as soon as synchronize_rcu() returns.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K^hh²hžhubhÆ)”}”(hŒŠImportant note: for this to work, the architecture in question must
invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.”h]”hŒŠImportant note: for this to work, the architecture in question must
invoke nmi_enter() and nmi_exit() on NMI entry and exit, respectively.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kehh²hžhubh¢)”}”(hŒ.. _answer_quick_quiz_NMI:”h]”h}”(h]”h ]”h"]”h$]”h&]”h­Œanswer-quick-quiz-nmi”uh1h¡h Khhh²hžhhŸh¯ubjJ  )”}”(hhh]”jO  )”}”(hX  Answer to Quick Quiz:
Why might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?

The caller to set_nmi_callback() might well have
initialized some data that is to be used by the new NMI
handler.  In this case, the rcu_dereference_sched() would
be needed, because otherwise a CPU that received an NMI
just after the new handler was set might see the pointer
to the new NMI handler, but the old pre-initialized
version of the handler's data.

This same sad story can happen on other CPUs when using
a compiler with aggressive pointer-value speculation
optimizations.  (But please don't!)

More important, the rcu_dereference_sched() makes it
clear to someone reading the code that the pointer is
being protected by RCU-sched.”h]”(jU  )”}”(hŒAnswer to Quick Quiz:”h]”hŒAnswer to Quick Quiz:”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jT  hŸh¯h KzhjC  ubje  )”}”(hhh]”(hÆ)”}”(hŒxWhy might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?”h]”hŒxWhy might the rcu_dereference_sched() be necessary on Alpha, given that the code referenced by the pointer is read-only?”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KkhjU  ubhÆ)”}”(hXf  The caller to set_nmi_callback() might well have
initialized some data that is to be used by the new NMI
handler.  In this case, the rcu_dereference_sched() would
be needed, because otherwise a CPU that received an NMI
just after the new handler was set might see the pointer
to the new NMI handler, but the old pre-initialized
version of the handler's data.”h]”hXh  The caller to set_nmi_callback() might well have
initialized some data that is to be used by the new NMI
handler.  In this case, the rcu_dereference_sched() would
be needed, because otherwise a CPU that received an NMI
just after the new handler was set might see the pointer
to the new NMI handler, but the old pre-initialized
version of the handlerâ€™s data.”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KmhjU  ubhÆ)”}”(hŒThis same sad story can happen on other CPUs when using
a compiler with aggressive pointer-value speculation
optimizations.  (But please don't!)”h]”hŒ’This same sad story can happen on other CPUs when using
a compiler with aggressive pointer-value speculation
optimizations.  (But please donâ€™t!)”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KuhjU  ubhÆ)”}”(hŒˆMore important, the rcu_dereference_sched() makes it
clear to someone reading the code that the pointer is
being protected by RCU-sched.”h]”hŒˆMore important, the rcu_dereference_sched() makes it
clear to someone reading the code that the pointer is
being protected by RCU-sched.”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KyhjU  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jd  hjC  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jN  hŸh¯h Kzhj@  ubah}”(h]”j?  ah ]”h"]”Œanswer_quick_quiz_nmi”ah$]”h&]”uh1jI  hh²hžhhŸh¯h NŒexpect_referenced_by_name”}”j   j5  sŒexpect_referenced_by_id”}”j?  j5  subeh}”(h]”(Œ)using-rcu-to-protect-dynamic-nmi-handlers”h®eh ]”h"]”(Œ)using rcu to protect dynamic nmi handlers”Œnmi_rcu_doc”eh$]”h&]”uh1h°hhhžhhŸh¯h Kj£  }”j­  h£sj¥  }”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£aj?  ]”j5  auŒnameids”}”(j­  h®j¬  j©  j   j?  uŒ	nametypes”}”(j­  ˆj¬  ‰j   ˆuh}”(h®h²j©  h²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”“”)”}”(hhh]”hÆ)”}”(hhh]”hŒ1Hyperlink target "nmi-rcu-doc" is not referenced.”…””}”hj@  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhj=  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h¯Œline”Kuh1j;  ubj<  )”}”(hhh]”hÆ)”}”(hhh]”hŒ;Hyperlink target "answer-quick-quiz-nmi" is not referenced.”…””}”hj[  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhjX  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jU  Œsource”h¯Œline”Khuh1j;  ubeŒtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.