GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing docs.kernel.org — Kexec Handover Subsystem — The Linux Kernel documentation Kexec Handover Subsystem¶Overview¶Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory regions, which could contain serialized system states, across kexec. KHO uses flattened device tree (FDT) to pass information about the preserved state from pre-exec kernel to post-kexec kernel and boot memory regions to ensure integrity of the preserved memory. KHO FDT¶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. 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. Subsystems participating in KHO can define their own format for state serialization and preservation. 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
Boot Memory Regions¶To 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. We guarantee that we always have such regions through the boot memory 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
boot memory region per NUMA node plus a boot memory region to satisfy
allocations requests that do not require particular NUMA node assignment. By
default, size of the boot memory region is calculated based on amount of memory
allocated during boot. The After KHO kexec, we ignore the Kexec Handover Radix Tree¶This is a radix tree implementation for tracking numeric keys across kexec transitions. It was developed for the KHO preserved memory map but is designed for broader use by any subsystem that needs to track keys. Conceptually speaking, the data structure is similar to a set. It tracks the presence or absence of numeric keys. The radix tree is a multi-level tree where leaf nodes are bitmaps representing individual keys. For the KHO preserved memory map, to allow pages of different sizes (orders) to be stored efficiently in a single tree, it uses a unique key encoding scheme. Each key is an unsigned long that combines a page’s physical address and its order. Client code is responsible for allocating the root node of the tree, initializing the mutex lock, and managing its lifecycle. It must use the tree data structures defined in the KHO ABI, include/linux/kho/abi/kexec_handover.h. Public API¶
Parameters
Description This function traverses the radix tree based on the key provided. It sets the corresponding bit in the leaf bitmap to mark the key as present. If intermediate nodes do not exist along the path, they are allocated and added to the tree. NOTE Currently only keys of width up to Return 0 on success, or a negative error code on failure.
Parameters
Description This function traverses the radix tree and clears the bit corresponding to the key, effectively removing it from the tree. It does not free the tree’s intermediate nodes, even if they become empty.
Parameters
Description Initialize the radix tree with the given root node. If root is Return 0 on success, -errno on failure.
Parameters
Description Walk tree and free all its nodes.
Parameters
Description This function walks the radix tree, searching from the top level down to the lowest level (level 0), invoking the appropriate callbacks. Return 0 if the walk completed the specified tree, or the non-zero return value from the callback that stopped the walk. Parameters
Return pointer to the
Parameters
Description Restore a contiguous list of order 0 pages that was preserved with
Return the first page on success, NULL on failure.
Parameters
Description Creates a new child node named name in KHO root FDT and records the physical address of blob. The pages of blob must also be preserved by KHO for the new kernel to retrieve it after kexec. A debugfs blob entry is also created at
Return 0 on success, error code on failure Parameters
Description Instructs KHO to preserve the whole folio across kexec. The order will be preserved as well. Return 0 on success, error code on failure Parameters
Description Instructs KHO to unpreserve a folio that was preserved by
Parameters
Description Preserve a contiguous list of order 0 pages. Must be restored using
Return 0 on success, error code on failure Parameters
Description Instructs KHO to unpreserve nr_pages contiguous pages starting from page.
This must be called with the same page and nr_pages as the corresponding
Parameters
Description Instructs KHO to preserve the area in vmalloc address space at ptr. The physical pages mapped at ptr will be preserved and on successful return preservation will hold the physical address of a structure that describes the preservation. NOTE The memory allocated with Return 0 on success, error code on failure
Parameters
Description Instructs KHO to unpreserve the area in vmalloc address space that was
previously preserved with
Parameters
Description Recreates an area in vmalloc address space and populates it with memory that
was preserved using Return pointer to the area in the vmalloc address space, NULL on failure.
Parameters
Description Allocates a physically contiguous block of zeroed pages that is large enough to hold size bytes. The allocated memory is then registered with KHO for preservation across a kexec. Note The actual allocated size will be rounded up to the nearest power-of-two page boundary. return A virtual pointer to the allocated and preserved memory on success,
or an
Parameters
Description Unregisters the memory from KHO preservation and frees the underlying
pages back to the system. This function should be called to clean up
memory allocated with
Parameters
Description This function is intended to be called in the new kernel (post-kexec)
to take ownership of and free a memory region that was preserved by the
old kernel using It first restores the pages from KHO (using their physical address) and then frees the pages back to the new kernel’s page allocator.
Parameters
Description This function checks if the current kernel was loaded through a kexec operation with KHO enabled, by verifying that a valid KHO FDT was passed. Note This function returns reliable results only after
Return true if booted via KHO-enabled kexec, false otherwise
Parameters
Description Retrieve a preserved sub blob named name and store its physical address in phys and optionally its size in size. Return 0 on success, error code on failure KHO Serialization Blocks API¶KHO provides a mechanism to preserve stateful data across a kexec handover by serializing it into memory blocks, and provides the common infrastructure for managing these blocks. Each block consists of a header (
Definition: struct kho_block {
struct list_head list;
struct kho_block_header_ser *ser;
};
Members
Definition: struct kho_block_set {
struct list_head blocks;
long nblocks;
u64 head_pa;
size_t entry_size;
u64 count_per_block;
bool incoming;
};
Members
Note Synchronization and locking are the responsibility of the caller. The block set structure itself is not internally synchronized.
Definition: struct kho_block_set_it {
struct kho_block_set *bs;
struct kho_block *block;
u64 i;
};
Members
Parameters
Parameters
Return The physical address of the first block header, or 0 if empty.
Parameters
Return True if there are no blocks in the set, false otherwise.
Parameters
Parameters
Description Dynamically preallocates and links preserved memory blocks if the target entry count exceeds the current total capacity of the set, ensuring they are available during serialization/deserialization. Context Caller must hold a lock protecting the block set. Return 0 on success, or a negative errno on failure.
Parameters
Description Releases and unallocates redundant preserved memory blocks. Checks if the last block in the set can be removed because the remaining entry count is fully accommodated by the preceding blocks. Note It is the caller’s responsibility to ensure that entries are removed in the reverse order of their insertion. Because shrinking destroys the last block in the set, removing entries in any other order would corrupt active data. Context Caller must hold a lock protecting the block set.
Parameters
Description Restores a serialized block set from a given physical address. The caller is responsible for ensuring that the block set bs has been allocated and initialized prior to calling this function. Return 0 on success, or a negative errno on failure.
Parameters
Parameters
Parameters
Parameters
Description Reserves a slot in the current block during state serialization to add a new entry, advancing the internal index. If the current block is full, it automatically moves to the next block in the set. Return A pointer to the reserved entry slot, or NULL if the block set’s capacity is fully exhausted.
Parameters
Description Iterates through previously written entries during state deserialization, respecting the actual count stored in each block’s header. Return A pointer to the next serialized entry, or NULL if all serialized entries have been read.
Parameters
Description If the current index is at the start of a block, it automatically moves to the end of the previous block. Return A pointer to the previous entry slot, or NULL if at the very beginning of the block set. See Also¶ |
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |