Ӵsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget)/translations/zh_CN/core-api/kho/conceptsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/zh_TW/core-api/kho/conceptsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/it_IT/core-api/kho/conceptsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ja_JP/core-api/kho/conceptsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ko_KR/core-api/kho/conceptsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/sp_SP/core-api/kho/conceptsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h)SPDX-License-Identifier: GPL-2.0-or-laterh]h)SPDX-License-Identifier: GPL-2.0-or-later}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhC/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts.rsthKubhtarget)}(h.. _kho-concepts:h]h}(h]h ]h"]h$]h&]refid kho-conceptsuh1hhKhhhhhhubhsection)}(hhh](htitle)}(hKexec Handover Conceptsh]hKexec Handover Concepts}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hKexec HandOver (KHO) is a mechanism that allows Linux to preserve memory regions, which could contain serialized system states, across kexec.h]hKexec HandOver (KHO) is a mechanism that allows Linux to preserve memory regions, which could contain serialized system states, across kexec.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h It introduces multiple concepts:h]h It introduces multiple concepts:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hhh](h)}(hKHO FDTh]hKHO FDT}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hX:Every KHO kexec carries a KHO specific flattened device tree (FDT) blob that describes preserved memory regions. These regions contain either serialized subsystem states, or in-memory data that shall not be touched across kexec. After KHO, subsystems can retrieve and restore preserved memory regions from KHO FDT.h]hX:Every KHO kexec carries a KHO specific flattened device tree (FDT) blob that describes preserved memory regions. These regions contain either serialized subsystem states, or in-memory data that shall not be touched across kexec. After KHO, subsystems can retrieve and restore preserved memory regions from KHO FDT.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hX*KHO only uses the FDT container format and libfdt library, but does not adhere to the same property semantics that normal device trees do: Properties are passed in native endianness and standardized properties like ``regs`` and ``ranges`` do not exist, hence there are no ``#...-cells`` properties.h](hKHO only uses the FDT container format and libfdt library, but does not adhere to the same property semantics that normal device trees do: Properties are passed in native endianness and standardized properties like }(hjhhhNhNubhliteral)}(h``regs``h]hregs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and }(hjhhhNhNubj)}(h ``ranges``h]hranges}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh" do not exist, hence there are no }(hjhhhNhNubj)}(h``#...-cells``h]h #...-cells}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh properties.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hZKHO is still under development. The FDT schema is unstable and would change in the future.h]hZKHO is still under development. The FDT schema is unstable and would change in the future.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]kho-fdtah ]h"]kho fdtah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hScratch Regionsh]hScratch Regions}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphhhhhKubh)}(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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hjphhubh)}(hXWe 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](hXWe 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 }(hjhhhNhNubj)}(h``kho_scratch``h]h kho_scratch}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK&hjphhubh)}(hXAfter 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](hAfter KHO kexec, we ignore the }(hjhhhNhNubj)}(h``kho_scratch``h]h kho_scratch}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjphhubh)}(h.. _kho-finalization-phase:h]h}(h]h ]h"]h$]h&]hkho-finalization-phaseuh1hhK;hjphhhhubeh}(h]scratch-regionsah ]h"]scratch regionsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hKHO finalization phaseh]hKHO finalization phase}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK>ubh)}(hXTo 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]hXTo 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjhhubeh}(h](jid1eh ]h"](kho finalization phasekho-finalization-phaseeh$]h&]uh1hhhhhhhhK>expect_referenced_by_name}jjsexpect_referenced_by_id}jjsubh)}(hhh](h)}(h Public APIh]h Public API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKHubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](singlekho_restore_folio (C function)c.kho_restore_foliohNtauh1jhjhhhNhNubhdesc)}(hhh](hdesc_signature)}(h3struct folio * kho_restore_folio (phys_addr_t phys)h]hdesc_signature_line)}(h1struct folio *kho_restore_folio(phys_addr_t phys)h](hdesc_sig_keyword)}(hstructh]hstruct}(hjChhhNhNubah}(h]h ]kah"]h$]h&]uh1jAhj=hhh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKubhdesc_sig_space)}(h h]h }(hjUhhhNhNubah}(h]h ]wah"]h$]h&]uh1jShj=hhhjRhKubh)}(hhh]h desc_sig_name)}(hfolioh]hfolio}(hjihhhNhNubah}(h]h ]nah"]h$]h&]uh1jghjdubah}(h]h ]h"]h$]h&] refdomaincreftype identifier reftargetjkmodnameN classnameN c:parent_keysphinx.domains.c LookupKey)}data]j ASTIdentifier)}jkho_restore_foliosbc.kho_restore_folioasbuh1hhj=hhhjRhKubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj=hhhjRhKubhdesc_sig_punctuation)}(h*h]h*}(hjhhhNhNubah}(h]h ]pah"]h$]h&]uh1jhj=hhhjRhKubh desc_name)}(hkho_restore_folioh]jh)}(hjh]hkho_restore_folio}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubah}(h]h ](sig-namedescnameeh"]h$]h&]hhuh1jhj=hhhjRhKubhdesc_parameterlist)}(h(phys_addr_t phys)h]hdesc_parameter)}(hphys_addr_t physh](h)}(hhh]jh)}(h phys_addr_th]h phys_addr_t}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjmodnameN classnameNjj)}j]jc.kho_restore_folioasbuh1hhjubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjubjh)}(hphysh]hphys}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhj=hhhjRhKubeh}(h]h ]h"]h$]h&]hh add_permalinkuh1j;sphinx_line_type declaratorhj7hhhjRhKubah}(h]j.ah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1j5hjRhKhj2hhubh desc_content)}(hhh]h)}(h.recreates the folio from the preserved memory.h]h.recreates the folio from the preserved memory.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKhj:hhubah}(h]h ]h"]h$]h&]uh1j8hj2hhhjRhKubeh}(h]h ](jfunctioneh"]h$]h&]domainjobjtypejUdesctypejUnoindex noindexentrynocontentsentryuh1j0hhhjhNhNubh container)}(h**Parameters** ``phys_addr_t phys`` physical address of the folio. **Return** pointer to the struct folio on success, NULL on failure.h](h)}(h**Parameters**h]hstrong)}(hjgh]h Parameters}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjeubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKhjaubhdefinition_list)}(hhh]hdefinition_list_item)}(h4``phys_addr_t phys`` physical address of the folio. h](hterm)}(h``phys_addr_t phys``h]j)}(hjh]hphys_addr_t phys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKhjubh definition)}(hhh]h)}(hphysical address of the folio.h]hphysical address of the folio.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjaubh)}(h **Return**h]jj)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKhjaubh)}(h8pointer to the struct folio on success, NULL on failure.h]h8pointer to the struct folio on success, NULL on failure.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chKhjaubeh}(h]h ] kernelindentah"]h$]h&]uh1j_hjhhhNhNubj )}(hhh]h}(h]h ]h"]h$]h&]entries](j,kho_add_subtree (C function)c.kho_add_subtreehNtauh1jhjhhhNhNubj1)}(hhh](j6)}(hPint kho_add_subtree (struct kho_serialization *ser, const char *name, void *fdt)h]j<)}(hOint kho_add_subtree(struct kho_serialization *ser, const char *name, void *fdt)h](hdesc_sig_keyword_type)}(hinth]hint}(hjhhhNhNubah}(h]h ]ktah"]h$]h&]uh1jhj hhh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMAubjT)}(h h]h }(hj"hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj hhhj!hMAubj)}(hkho_add_subtreeh]jh)}(hkho_add_subtreeh]hkho_add_subtree}(hj4hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj0ubah}(h]h ](jjeh"]h$]h&]hhuh1jhj hhhj!hMAubj)}(h<(struct kho_serialization *ser, const char *name, void *fdt)h](j)}(hstruct kho_serialization *serh](jB)}(hjEh]hstruct}(hjPhhhNhNubah}(h]h ]jNah"]h$]h&]uh1jAhjLubjT)}(h h]h }(hj]hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjLubh)}(hhh]jh)}(hkho_serializationh]hkho_serialization}(hjnhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjkubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjpmodnameN classnameNjj)}j]j)}jj6sbc.kho_add_subtreeasbuh1hhjLubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjLubj)}(hjh]h*}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjLubjh)}(hserh]hser}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjLubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjHubj)}(hconst char *nameh](jB)}(hconsth]hconst}(hjhhhNhNubah}(h]h ]jNah"]h$]h&]uh1jAhjubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjubj)}(hcharh]hchar}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjubj)}(hjh]h*}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubjh)}(hnameh]hname}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjHubj)}(h void *fdth](j)}(hvoidh]hvoid}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubjT)}(h h]h }(hj.hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjubj)}(hjh]h*}(hj<hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubjh)}(hfdth]hfdt}(hjIhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjHubeh}(h]h ]h"]h$]h&]hhuh1jhj hhhj!hMAubeh}(h]h ]h"]h$]h&]hhj*uh1j;j+j,hjhhhj!hMAubah}(h]jah ](j0j1eh"]h$]h&]j5j6)j7huh1j5hj!hMAhjhhubj9)}(hhh]h)}(h:record the physical address of a sub FDT in KHO root tree.h]h:record the physical address of a sub FDT in KHO root tree.}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMAhjphhubah}(h]h ]h"]h$]h&]uh1j8hjhhhj!hMAubeh}(h]h ](jfunctioneh"]h$]h&]jYjjZjj[jj\j]j^uh1j0hhhjhNhNubj`)}(hX**Parameters** ``struct kho_serialization *ser`` serialization control object passed by KHO notifiers. ``const char *name`` name of the sub tree. ``void *fdt`` the sub tree blob. **Description** Creates a new child node named **name** in KHO root FDT and records the physical address of **fdt**. The pages of **fdt** must also be preserved by KHO for the new kernel to retrieve it after kexec. A debugfs blob entry is also created at ``/sys/kernel/debug/kho/out/sub_fdts/**name**``. **Return** 0 on success, error code on failureh](h)}(h**Parameters**h]jj)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMEhjubj)}(hhh](j)}(hX``struct kho_serialization *ser`` serialization control object passed by KHO notifiers. h](j)}(h!``struct kho_serialization *ser``h]j)}(hjh]hstruct kho_serialization *ser}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMBhjubj)}(hhh]h)}(h5serialization control object passed by KHO notifiers.h]h5serialization control object passed by KHO notifiers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMBhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhMBhjubj)}(h+``const char *name`` name of the sub tree. h](j)}(h``const char *name``h]j)}(hjh]hconst char *name}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMChjubj)}(hhh]h)}(hname of the sub tree.h]hname of the sub tree.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMChjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjhMChjubj)}(h!``void *fdt`` the sub tree blob. h](j)}(h ``void *fdt``h]j)}(hj&h]h void *fdt}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMDhj ubj)}(hhh]h)}(hthe sub tree blob.h]hthe sub tree blob.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;hMDhj<ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj;hMDhjubeh}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]jj)}(hjah]h Description}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1jihj_ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMFhjubh)}(hCreates a new child node named **name** in KHO root FDT and records the physical address of **fdt**. The pages of **fdt** must also be preserved by KHO for the new kernel to retrieve it after kexec.h](hCreates a new child node named }(hjwhhhNhNubjj)}(h**name**h]hname}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjwubh5 in KHO root FDT and records the physical address of }(hjwhhhNhNubjj)}(h**fdt**h]hfdt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjwubh. The pages of }(hjwhhhNhNubjj)}(h**fdt**h]hfdt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjwubhM must also be preserved by KHO for the new kernel to retrieve it after kexec.}(hjwhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMFhjubh)}(hXA debugfs blob entry is also created at ``/sys/kernel/debug/kho/out/sub_fdts/**name**``.h](h(A debugfs blob entry is also created at }(hjhhhNhNubj)}(h/``/sys/kernel/debug/kho/out/sub_fdts/**name**``h]h+/sys/kernel/debug/kho/out/sub_fdts/**name**}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMJhjubh)}(h **Return**h]jj)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMMhjubh)}(h#0 on success, error code on failureh]h#0 on success, error code on failure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMMhjubeh}(h]h ] kernelindentah"]h$]h&]uh1j_hjhhhNhNubj )}(hhh]h}(h]h ]h"]h$]h&]entries](j,kho_preserve_folio (C function)c.kho_preserve_foliohNtauh1jhjhhhNhNubj1)}(hhh](j6)}(h,int kho_preserve_folio (struct folio *folio)h]j<)}(h+int kho_preserve_folio(struct folio *folio)h](j)}(hinth]hint}(hj$hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMubjT)}(h h]h }(hj3hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj hhhj2hMubj)}(hkho_preserve_folioh]jh)}(hkho_preserve_folioh]hkho_preserve_folio}(hjEhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjAubah}(h]h ](jjeh"]h$]h&]hhuh1jhj hhhj2hMubj)}(h(struct folio *folio)h]j)}(hstruct folio *folioh](jB)}(hjEh]hstruct}(hjahhhNhNubah}(h]h ]jNah"]h$]h&]uh1jAhj]ubjT)}(h h]h }(hjnhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj]ubh)}(hhh]jh)}(hfolioh]hfolio}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj|ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjmodnameN classnameNjj)}j]j)}jjGsbc.kho_preserve_folioasbuh1hhj]ubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj]ubj)}(hjh]h*}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj]ubjh)}(hfolioh]hfolio}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj]ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjYubah}(h]h ]h"]h$]h&]hhuh1jhj hhhj2hMubeh}(h]h ]h"]h$]h&]hhj*uh1j;j+j,hjhhhj2hMubah}(h]jah ](j0j1eh"]h$]h&]j5j6)j7huh1j5hj2hMhjhhubj9)}(hhh]h)}(hpreserve a folio across kexec.h]hpreserve a folio across kexec.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjhhubah}(h]h ]h"]h$]h&]uh1j8hjhhhj2hMubeh}(h]h ](jfunctioneh"]h$]h&]jYjjZjj[jj\j]j^uh1j0hhhjhNhNubj`)}(h**Parameters** ``struct folio *folio`` folio to preserve. **Description** Instructs KHO to preserve the whole folio across kexec. The order will be preserved as well. **Return** 0 on success, error code on failureh](h)}(h**Parameters**h]jj)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubj)}(hhh]j)}(h+``struct folio *folio`` folio to preserve. h](j)}(h``struct folio *folio``h]j)}(hj%h]hstruct folio *folio}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj#ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubj)}(hhh]h)}(hfolio to preserve.h]hfolio to preserve.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:hMhj;ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj:hMhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h**Description**h]jj)}(hj`h]h Description}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1jihj^ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubh)}(h\Instructs KHO to preserve the whole folio across kexec. The order will be preserved as well.h]h\Instructs KHO to preserve the whole folio across kexec. The order will be preserved as well.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubh)}(h **Return**h]jj)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jihjubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubh)}(h#0 on success, error code on failureh]h#0 on success, error code on failure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjubeh}(h]h ] kernelindentah"]h$]h&]uh1j_hjhhhNhNubj )}(hhh]h}(h]h ]h"]h$]h&]entries](j,kho_preserve_phys (C function)c.kho_preserve_physhNtauh1jhjhhhNhNubj1)}(hhh](j6)}(h5int kho_preserve_phys (phys_addr_t phys, size_t size)h]j<)}(h4int kho_preserve_phys(phys_addr_t phys, size_t size)h](j)}(hinth]hint}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjhhh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMubjT)}(h h]h }(hjhhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjhhhjhMubj)}(hkho_preserve_physh]jh)}(hkho_preserve_physh]hkho_preserve_phys}(hjhhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjubah}(h]h ](jjeh"]h$]h&]hhuh1jhjhhhjhMubj)}(h(phys_addr_t phys, size_t size)h](j)}(hphys_addr_t physh](h)}(hhh]jh)}(h phys_addr_th]h phys_addr_t}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetj modnameN classnameNjj)}j]j)}jjsbc.kho_preserve_physasbuh1hhj ubjT)}(h h]h }(hj, hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj ubjh)}(hphysh]hphys}(hj: hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhj ubj)}(h size_t sizeh](h)}(hhh]jh)}(hsize_th]hsize_t}(hjV hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjS ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetjX modnameN classnameNjj)}j]j( c.kho_preserve_physasbuh1hhjO ubjT)}(h h]h }(hjt hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShjO ubjh)}(hsizeh]hsize}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghjO ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhj ubeh}(h]h ]h"]h$]h&]hhuh1jhjhhhjhMubeh}(h]h ]h"]h$]h&]hhj*uh1j;j+j,hjhhhjhMubah}(h]jah ](j0j1eh"]h$]h&]j5j6)j7huh1j5hjhMhjhhubj9)}(hhh]h)}(h4preserve a physically contiguous range across kexec.h]h4preserve a physically contiguous range across kexec.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj hhubah}(h]h ]h"]h$]h&]uh1j8hjhhhjhMubeh}(h]h ](jfunctioneh"]h$]h&]jYjjZj j[j j\j]j^uh1j0hhhjhNhNubj`)}(hX **Parameters** ``phys_addr_t phys`` physical address of the range. ``size_t size`` size of the range. **Description** Instructs KHO to preserve the memory range from **phys** to **phys** + **size** across kexec. **Return** 0 on success, error code on failureh](h)}(h**Parameters**h]jj)}(hj h]h Parameters}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubj)}(hhh](j)}(h4``phys_addr_t phys`` physical address of the range. h](j)}(h``phys_addr_t phys``h]j)}(hj h]hphys_addr_t phys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubj)}(hhh]h)}(hphysical address of the range.h]hphysical address of the range.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj hMhj ubj)}(h#``size_t size`` size of the range. h](j)}(h``size_t size``h]j)}(hj& h]h size_t size}(hj( hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$ ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubj)}(hhh]h)}(hsize of the range.h]hsize of the range.}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj; hMhj< ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj; hMhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubh)}(h**Description**h]jj)}(hja h]h Description}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj_ ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubh)}(h]Instructs KHO to preserve the memory range from **phys** to **phys** + **size** across kexec.h](h0Instructs KHO to preserve the memory range from }(hjw hhhNhNubjj)}(h**phys**h]hphys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihjw ubh to }(hjw hhhNhNubjj)}(h**phys**h]hphys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihjw ubh + }(hjw hhhNhNubjj)}(h**size**h]hsize}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihjw ubh across kexec.}(hjw hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubh)}(h **Return**h]jj)}(hj h]hReturn}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubh)}(h#0 on success, error code on failureh]h#0 on success, error code on failure}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj ubeh}(h]h ] kernelindentah"]h$]h&]uh1j_hjhhhNhNubj )}(hhh]h}(h]h ]h"]h$]h&]entries](j,!kho_retrieve_subtree (C function)c.kho_retrieve_subtreehNtauh1jhjhhhNhNubj1)}(hhh](j6)}(h>int kho_retrieve_subtree (const char *name, phys_addr_t *phys)h]j<)}(h=int kho_retrieve_subtree(const char *name, phys_addr_t *phys)h](j)}(hinth]hint}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMubjT)}(h h]h }(hj hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj hhhj hMubj)}(hkho_retrieve_subtreeh]jh)}(hkho_retrieve_subtreeh]hkho_retrieve_subtree}(hj$ hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj ubah}(h]h ](jjeh"]h$]h&]hhuh1jhj hhhj hMubj)}(h%(const char *name, phys_addr_t *phys)h](j)}(hconst char *nameh](jB)}(hjh]hconst}(hj@ hhhNhNubah}(h]h ]jNah"]h$]h&]uh1jAhj< ubjT)}(h h]h }(hjM hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj< ubj)}(hcharh]hchar}(hj[ hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj< ubjT)}(h h]h }(hji hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj< ubj)}(hjh]h*}(hjw hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj< ubjh)}(hnameh]hname}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj< ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhj8 ubj)}(hphys_addr_t *physh](h)}(hhh]jh)}(h phys_addr_th]h phys_addr_t}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj ubah}(h]h ]h"]h$]h&] refdomainjreftypej reftargetj modnameN classnameNjj)}j]j)}jj& sbc.kho_retrieve_subtreeasbuh1hhj ubjT)}(h h]h }(hj hhhNhNubah}(h]h ]j`ah"]h$]h&]uh1jShj ubj)}(hjh]h*}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj ubjh)}(hphysh]hphys}(hj hhhNhNubah}(h]h ]jtah"]h$]h&]uh1jghj ubeh}(h]h ]h"]h$]h&]noemphhhuh1jhj8 ubeh}(h]h ]h"]h$]h&]hhuh1jhj hhhj hMubeh}(h]h ]h"]h$]h&]hhj*uh1j;j+j,hj hhhj hMubah}(h]j ah ](j0j1eh"]h$]h&]j5j6)j7huh1j5hj hMhj hhubj9)}(hhh]h)}(h)retrieve a preserved sub FDT by its name.h]h)retrieve a preserved sub FDT by its name.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj hhubah}(h]h ]h"]h$]h&]uh1j8hj hhhj hMubeh}(h]h ](jfunctioneh"]h$]h&]jYjjZj j[j j\j]j^uh1j0hhhjhNhNubj`)}(hXT**Parameters** ``const char *name`` the name of the sub FDT passed to kho_add_subtree(). ``phys_addr_t *phys`` if found, the physical address of the sub FDT is stored in **phys**. **Description** Retrieve a preserved sub FDT named **name** and store its physical address in **phys**. **Return** 0 on success, error code on failureh](h)}(h**Parameters**h]jj)}(hj' h]h Parameters}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj% ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj! ubj)}(hhh](j)}(hJ``const char *name`` the name of the sub FDT passed to kho_add_subtree(). h](j)}(h``const char *name``h]j)}(hjF h]hconst char *name}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjD ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj@ ubj)}(hhh]h)}(h4the name of the sub FDT passed to kho_add_subtree().h]h4the name of the sub FDT passed to kho_add_subtree().}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[ hMhj\ ubah}(h]h ]h"]h$]h&]uh1jhj@ ubeh}(h]h ]h"]h$]h&]uh1jhj[ hMhj= ubj)}(h[``phys_addr_t *phys`` if found, the physical address of the sub FDT is stored in **phys**. h](j)}(h``phys_addr_t *phys``h]j)}(hj h]hphys_addr_t *phys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj} ubah}(h]h ]h"]h$]h&]uh1jh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhjy ubj)}(hhh]h)}(hDif found, the physical address of the sub FDT is stored in **phys**.h](h;if found, the physical address of the sub FDT is stored in }(hj hhhNhNubjj)}(h**phys**h]hphys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhj hMhj ubah}(h]h ]h"]h$]h&]uh1jhjy ubeh}(h]h ]h"]h$]h&]uh1jhj hMhj= ubeh}(h]h ]h"]h$]h&]uh1jhj! ubh)}(h**Description**h]jj)}(hj h]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj! ubh)}(hWRetrieve a preserved sub FDT named **name** and store its physical address in **phys**.h](h#Retrieve a preserved sub FDT named }(hj hhhNhNubjj)}(h**name**h]hname}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubh# and store its physical address in }(hj hhhNhNubjj)}(h**phys**h]hphys}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj! ubh)}(h **Return**h]jj)}(hj h]hReturn}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jihj ubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj! ubh)}(h#0 on success, error code on failureh]h#0 on success, error code on failure}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/core-api/kho/concepts:73: ./kernel/kexec_handover.chMhj! ubeh}(h]h ] kernelindentah"]h$]h&]uh1j_hjhhhNhNubeh}(h] public-apiah ]h"] public apiah$]h&]uh1hhhhhhhhKHubeh}(h](kexec-handover-conceptsheh ]h"](kexec handover concepts kho-conceptseh$]h&]uh1hhhhhhhhKj }jQ hsj }hhsubeh}(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_handlerjy error_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.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_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_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}(h]haj]jaunameids}(jQ hjP jM jmjjjjjjjjjH jE u nametypes}(jQ jP jmjjjjH uh}(hhjM hjjhjjpjjjjjE jj.j7jjjjjjj j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j KsRparse_messages]transform_messages](hsystem_message)}(hhh]h)}(hhh]h2Hyperlink target "kho-concepts" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1j ubj )}(hhh]h)}(hhh]h