€•*@Œ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”Œ&/translations/zh_CN/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ&/translations/zh_TW/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ&/translations/it_IT/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ&/translations/ja_JP/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ&/translations/ko_KR/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ&/translations/sp_SP/core-api/kho/index”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ)SPDX-License-Identifier: GPL-2.0-or-later”h]”hŒ)SPDX-License-Identifier: GPL-2.0-or-later”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒ@/var/lib/git/docbuild/linux/Documentation/core-api/kho/index.rst”h KubhŒtarget”“”)”}”(hŒ.. _kho-concepts:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œ kho-concepts”uh1h´h KhhhžhhŸh³ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒKexec Handover Subsystem”h]”hŒKexec Handover Subsystem”…””}”(hhÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhhÄhžhhŸh³h KubhÃ)”}”(hhh]”(hÈ)”}”(hŒOverview”h]”hŒOverview”…””}”(hhÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhh×hžhhŸh³h K ubhŒ paragraph”“”)”}”(hŒKexec HandOver (KHO) is a mechanism that allows Linux to preserve memory regions, which could contain serialized system states, across kexec.”h]”hŒKexec HandOver (KHO) is a mechanism that allows Linux to preserve memory regions, which could contain serialized system states, across kexec.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K hh×hžhubhé)”}”(hŒêKHO uses :ref:`flattened device tree (FDT) ` to pass information about the preserved state from pre-exec kernel to post-kexec kernel and :ref:`scratch memory regions ` to ensure integrity of the preserved memory.”h]”(hŒ KHO uses ”…””}”(hhøhžhhŸNh Nubh)”}”(hŒ,:ref:`flattened device tree (FDT) `”h]”hŒinline”“”)”}”(hjh]”hŒflattened device tree (FDT)”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1jhjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œcore-api/kho/index”Œ refdomain”jŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆŒ reftarget”Œkho_fdt”uh1hhŸh³h KhhøubhŒ] to pass information about the preserved state from pre-exec kernel to post-kexec kernel and ”…””}”(hhøhžhhŸNh Nubh)”}”(hŒ+:ref:`scratch memory regions `”h]”j)”}”(hj+h]”hŒscratch memory regions”…””}”(hj-hžhhŸNh Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jhj)ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jŒ refdomain”j7Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆj#Œ kho_scratch”uh1hhŸh³h KhhøubhŒ- to ensure integrity of the preserved memory.”…””}”(hhøhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhµ)”}”(hŒ .. _kho_fdt:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒkho-fdt”uh1h´h Khh×hžhhŸh³ubeh}”(h]”Œoverview”ah ]”h"]”Œoverview”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K ubhÃ)”}”(hhh]”(hÈ)”}”(hŒKHO FDT”h]”hŒKHO FDT”…””}”(hjihžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjfhžhhŸh³h Kubhé)”}”(hŒÙEvery KHO kexec carries a KHO specific flattened device tree (FDT) blob that describes the preserved state. The FDT includes properties describing preserved memory regions and nodes that hold subsystem specific state.”h]”hŒÙEvery KHO kexec carries a KHO specific flattened device tree (FDT) blob that describes the preserved state. The FDT includes properties describing preserved memory regions and nodes that hold subsystem specific state.”…””}”(hjwhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjfhžhubhé)”}”(hŒÓThe preserved memory regions contain either serialized subsystem states, or in-memory data that shall not be touched across kexec. After KHO, subsystems can retrieve and restore the preserved state from KHO FDT.”h]”hŒÓThe preserved memory regions contain either serialized subsystem states, or in-memory data that shall not be touched across kexec. After KHO, subsystems can retrieve and restore the preserved state from KHO FDT.”…””}”(hj…hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjfhžhubhé)”}”(hŒeSubsystems participating in KHO can define their own format for state serialization and preservation.”h]”hŒeSubsystems participating in KHO can define their own format for state serialization and preservation.”…””}”(hj“hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjfhžhubhé)”}”(hŒ²KHO FDT and structures defined by the subsystems form an ABI between pre-kexec and post-kexec kernels. This ABI is defined by header files in ``include/linux/kho/abi`` directory.”h]”(hŒŽKHO FDT and structures defined by the subsystems form an ABI between pre-kexec and post-kexec kernels. This ABI is defined by header files in ”…””}”(hj¡hžhhŸNh NubhŒliteral”“”)”}”(hŒ``include/linux/kho/abi``”h]”hŒinclude/linux/kho/abi”…””}”(hj«hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©hj¡ubhŒ directory.”…””}”(hj¡hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K"hjfhžhubhŒcompound”“”)”}”(hhh]”hŒtoctree”“”)”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”hjŒentries”]”NŒcore-api/kho/abi”†”aŒ includefiles”]”jÕaŒmaxdepth”KŒcaption”NŒglob”‰Œhidden”‰Œ includehidden”‰Œnumbered”KŒ titlesonly”‰Œ rawentries”]”uh1jÈhŸh³h K&hjÅubah}”(h]”h ]”Œtoctree-wrapper”ah"]”h$]”h&]”uh1jÃhjfhžhhŸh³h Nubhµ)”}”(hŒ.. _kho_scratch:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒ kho-scratch”uh1h´h K+hjfhžhhŸh³ubeh}”(h]”(j]Œid1”eh ]”h"]”(Œkho fdt”Œkho_fdt”eh$]”h&]”uh1hÂhhÄhžhhŸh³h KŒexpect_referenced_by_name”}”jújSsŒexpect_referenced_by_id”}”j]jSsubhÃ)”}”(hhh]”(hÈ)”}”(hŒScratch Regions”h]”hŒScratch Regions”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjhžhhŸh³h K.ubhé)”}”(hX4To boot into kexec, we need to have a physically contiguous memory range that contains no handed over memory. Kexec then places the target kernel and initrd into that region. The new kernel exclusively uses this region for memory allocations before during boot up to the initialization of the page allocator.”h]”hX4To boot into kexec, we need to have a physically contiguous memory range that contains no handed over memory. Kexec then places the target kernel and initrd into that region. The new kernel exclusively uses this region for memory allocations before during boot up to the initialization of the page allocator.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K0hjhžhubhé)”}”(hX“We guarantee that we always have such regions through the scratch regions: On first boot KHO allocates several physically contiguous memory regions. Since after kexec these regions will be used by early memory allocations, there is a scratch region per NUMA node plus a scratch region to satisfy allocations requests that do not require particular NUMA node assignment. By default, size of the scratch region is calculated based on amount of memory allocated during boot. The ``kho_scratch`` kernel command line option may be used to explicitly define size of the scratch regions. The scratch regions are declared as CMA when page allocator is initialized so that their memory can be used during system lifetime. CMA gives us the guarantee that no handover pages land in that region, because handover pages must be at a static physical memory location and CMA enforces that only movable pages can be located inside.”h]”(hXÜWe guarantee that we always have such regions through the scratch regions: On first boot KHO allocates several physically contiguous memory regions. Since after kexec these regions will be used by early memory allocations, there is a scratch region per NUMA node plus a scratch region to satisfy allocations requests that do not require particular NUMA node assignment. By default, size of the scratch region is calculated based on amount of memory allocated during boot. The ”…””}”(hj hžhhŸNh Nubjª)”}”(hŒ``kho_scratch``”h]”hŒ kho_scratch”…””}”(hj(hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©hj ubhX¨ kernel command line option may be used to explicitly define size of the scratch regions. The scratch regions are declared as CMA when page allocator is initialized so that their memory can be used during system lifetime. CMA gives us the guarantee that no handover pages land in that region, because handover pages must be at a static physical memory location and CMA enforces that only movable pages can be located inside.”…””}”(hj hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K5hjhžhubhé)”}”(hXÊAfter KHO kexec, we ignore the ``kho_scratch`` kernel command line option and instead reuse the exact same region that was originally allocated. This allows us to recursively execute any amount of KHO kexecs. Because we used this region for boot memory allocations and as target memory for kexec blobs, some parts of that memory region may be reserved. These reservations are irrelevant for the next KHO, because kexec can overwrite even the original kernel.”h]”(hŒAfter KHO kexec, we ignore the ”…””}”(hj@hžhhŸNh Nubjª)”}”(hŒ``kho_scratch``”h]”hŒ kho_scratch”…””}”(hjHhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©hj@ubhXœ kernel command line option and instead reuse the exact same region that was originally allocated. This allows us to recursively execute any amount of KHO kexecs. Because we used this region for boot memory allocations and as target memory for kexec blobs, some parts of that memory region may be reserved. These reservations are irrelevant for the next KHO, because kexec can overwrite even the original kernel.”…””}”(hj@hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KChjhžhubhµ)”}”(hŒ.. _kho-finalization-phase:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒkho-finalization-phase”uh1h´h KJhjhžhhŸh³ubeh}”(h]”(Œscratch-regions”jóeh ]”h"]”(Œscratch regions”Œ kho_scratch”eh$]”h&]”uh1hÂhhÄhžhhŸh³h K.jý}”jqjésjÿ}”jójésubhÃ)”}”(hhh]”(hÈ)”}”(hŒKHO finalization phase”h]”hŒKHO finalization phase”…””}”(hjyhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjvhžhhŸh³h KMubhé)”}”(hX—To enable user space based kexec file loader, the kernel needs to be able to provide the FDT that describes the current kernel's state before performing the actual kexec. The process of generating that FDT is called serialization. When the FDT is generated, some properties of the system may become immutable because they are already written down in the FDT. That state is called the KHO finalization phase.”h]”hX™To enable user space based kexec file loader, the kernel needs to be able to provide the FDT that describes the current kernel’s state before performing the actual kexec. The process of generating that FDT is called serialization. When the FDT is generated, some properties of the system may become immutable because they are already written down in the FDT. That state is called the KHO finalization phase.”…””}”(hj‡hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KOhjvhžhubeh}”(h]”(jjŒid2”eh ]”h"]”(Œkho finalization phase”Œkho-finalization-phase”eh$]”h&]”uh1hÂhhÄhžhhŸh³h KMjý}”j›j`sjÿ}”jjj`subhÃ)”}”(hhh]”(hÈ)”}”(hŒSee Also”h]”hŒSee Also”…””}”(hj£hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj hžhhŸh³h KWubhŒ bullet_list”“”)”}”(hhh]”hŒ list_item”“”)”}”(hŒ:doc:`/admin-guide/mm/kho`”h]”hé)”}”(hjºh]”h)”}”(hjºh]”j)”}”(hjºh]”hŒ/admin-guide/mm/kho”…””}”(hjÂhžhhŸNh Nubah}”(h]”h ]”(jŒstd”Œstd-doc”eh"]”h$]”h&]”uh1jhj¿ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jŒ refdomain”jÌŒreftype”Œdoc”Œ refexplicit”‰Œrefwarn”ˆj#Œ/admin-guide/mm/kho”uh1hhŸh³h KYhj¼ubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KYhj¸ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¶hj³hžhhŸh³h Nubah}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j±hŸh³h KYhj hžhubeh}”(h]”Œsee-also”ah ]”h"]”Œsee also”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KWubeh}”(h]”(Œkexec-handover-subsystem”hÁeh ]”h"]”(Œkexec handover subsystem”Œ kho-concepts”eh$]”h&]”uh1hÂhhhžhhŸh³h Kjý}”jh¶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]]”jSajó]”jéajj]”j`auŒnameids”}”(jhÁjÿjüjcj`júj]jùjöjqjójpjmj›jjjšj—j÷jôuŒ nametypes”}”(jˆjÿ‰jc‰júˆjù‰jqˆjp‰j›ˆjš‰j÷‰uh}”(hÁhÄjühÄj`h×j]jfjöjfjójjmjjjjvj—jvjô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”“”}”j6Ks…”R”Œparse_messages”]”Œtransform_messages”]”(hŒsystem_message”“”)”}”(hhh]”hé)”}”(hhh]”hŒ2Hyperlink target "kho-concepts" is not referenced.”…””}”hj•sbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhj’ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1jubj‘)”}”(hhh]”hé)”}”(hhh]”hŒ-Hyperlink target "kho-fdt" is not referenced.”…””}”hj°sbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhj­ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jªŒsource”h³Œline”Kuh1jubj‘)”}”(hhh]”hé)”}”(hhh]”hŒ1Hyperlink target "kho-scratch" is not referenced.”…””}”hjÊsbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhjÇubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”jªŒsource”h³Œline”K+uh1jubj‘)”}”(hhh]”hé)”}”(hhh]”hŒ