Kexec Handover ABI

Core Kexec Handover ABI

Kexec Handover uses the ABI defined below for passing preserved data from one kernel to the next. The ABI uses Flattened Device Tree (FDT) format. The first kernel creates an FDT which is then passed to the next kernel during a kexec handover.

This interface is a contract. Any modification to the FDT structure, node properties, compatible string, or the layout of the data structures referenced here constitutes a breaking change. Such changes require incrementing the version number in KHO_FDT_COMPATIBLE to prevent a new kernel from misinterpreting data from an older kernel. Changes are allowed provided the compatibility version is incremented. However, backward/forward compatibility is only guaranteed for kernels supporting the same ABI version.

FDT Structure Overview:

The FDT serves as a central registry for physical addresses of preserved data structures and sub-FDTs. The first kernel populates this FDT with references to memory regions and other FDTs that need to persist across the kexec transition. The subsequent kernel then parses this FDT to locate and restore the preserved data.:

/ {
    compatible = "kho-v1";

    preserved-memory-map = <0x...>;

    <subnode-name-1> {
        fdt = <0x...>;
    };

    <subnode-name-2> {
        fdt = <0x...>;
    };
          ... ...
    <subnode-name-N> {
        fdt = <0x...>;
    };
};
Root KHO Node (/):

  • compatible: “kho-v1”

    Indentifies the overall KHO ABI version.

  • preserved-memory-map: u64

    Physical memory address pointing to the root of the preserved memory map data structure.

Subnodes (<subnode-name-N>):

Subnodes can also be added to the root node to describe other preserved data blobs. The <subnode-name-N> is provided by the subsystem that uses KHO for preserving its data.

  • fdt: u64

    Physical address pointing to a subnode FDT blob that is also being preserved.

vmalloc preservation ABI

The Kexec Handover ABI for preserving vmalloc’ed memory is defined by a set of structures and helper macros. The layout of these structures is a stable contract between kernels and is versioned by the KHO_FDT_COMPATIBLE string.

The preservation is managed through a main descriptor struct kho_vmalloc, which points to a linked list of struct kho_vmalloc_chunk structures. These chunks contain the physical addresses of the preserved pages, allowing the next kernel to reconstruct the vmalloc area with the same content and layout. Helper macros are also defined for storing and loading pointers within these structures.

memblock preservation ABI

Memblock can serialize its current memory reservations created with reserve_mem command line option across kexec through KHO. The post-KHO kernel can then consume these reservations and they are guaranteed to have the same physical address.

The state is serialized using Flattened Device Tree (FDT) format. Any modification to the FDT structure, node properties, or the compatible strings constitutes a breaking change. Such changes require incrementing the version number in the relevant _COMPATIBLE string to prevent a new kernel from misinterpreting data from an old kernel.

Changes are allowed provided the compatibility version is incremented. However, backward/forward compatibility is only guaranteed for kernels supporting the same ABI version.

FDT Structure Overview:

The entire memblock state is encapsulated within a single KHO entry named “memblock”. This entry contains an FDT with the following layout:

/ {
        compatible = "memblock-v1";

        n1 {
                compatible = "reserve-mem-v1";
                start = <0xc06b 0x4000000>;
                size = <0x04 0x00>;
        };
};

Main memblock node (/):

  • compatible: “memblock-v1” Identifies the overall memblock ABI version.

reserved_mem node:

These nodes describe all reserve_mem regions.

  • compatible: “reserve-mem-v1”

    Identifies the ABI version of reserve_mem descriptions

  • start: u64

    Physical address of the reserved memory region.

  • size: u64

    size in bytes of the reserved memory region.

See Also