From nobody Wed Dec 17 15:53:11 2025 Received: from mail-pg1-f201.google.com (mail-pg1-f201.google.com [209.85.215.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 290D32417C3 for ; Tue, 9 Dec 2025 02:53:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1765248807; cv=none; b=jtq8GZ/QJACBWxupGXMOO7m6Mqpoz1iNOVSFz8c+TrQvTDLUayBXIRZv4V64RWfEwZqhNbPwUbyIFKNpFlkzWpSAdn8SokGbl2LlGKpMQr9BSiRRRB3BbZtN9AokcT5TKKkuUYGln8H+JA8uGXhWMd9mrcm8URMGtcDFy5Y+B+8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1765248807; c=relaxed/simple; bh=mCMxsIa1KDuECd7Rg+wDaBGgcd033/bEktdfoyHVBcU=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Content-Type; b=GA+S0qfFhcv3TVYL3LI02E/8Xo+/hC9G4ZRsV7ENfIQ+QncXds1okK0Uv2rJaBTDtwgiXUMVP7Qt9h4smFwSL+kC12GV+BTzwPg/d2J6+N3OBl/NqIBj3sCybfvAdq8BTdD0mRG+xw73YCy8iWJilILXIvVuXRYc6CECKU/SPVw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--jasonmiu.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=py3HVJ0P; arc=none smtp.client-ip=209.85.215.201 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--jasonmiu.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="py3HVJ0P" Received: by mail-pg1-f201.google.com with SMTP id 41be03b00d2f7-bde2d88e5e3so8902343a12.2 for ; Mon, 08 Dec 2025 18:53:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1765248804; x=1765853604; darn=vger.kernel.org; h=to:from:subject:message-id:references:mime-version:in-reply-to:date :from:to:cc:subject:date:message-id:reply-to; bh=fWGLthrm17VZY/kZ1kLIqDTWzrsbdUmIFsSZPiZHtvE=; b=py3HVJ0PtLZVLBSDo7xUmUUa0Hmhs8T7Sq3HuSbBnTYUNgBOjxch+GkC55hLtTG39D yOp0ALVV5WNi0t+93LYXamvzLP58xtUFeP7QToTX1FKOQ/eyDzJwS6ybu4gwJ0P9VyW7 jAD1V/cLXO+GeTvV1ILl7WfLOTHAzV2vtrIcDe6tEewB9+e6eGqK0EfaP65ZlV3arCQC kR/P8gwG3wJ9K0GfVTwZLU94Z3IGKC3DSWs11m9fulS5UzVqSlkvdnLSi+ASH56B7sFk aNQDThdDOw7DYqfHJ59yYR/QVMAX7C58nRD8eQkGew5DuckCdonSKt62mtxBzoVTAqhT TjQA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1765248804; x=1765853604; h=to:from:subject:message-id:references:mime-version:in-reply-to:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=fWGLthrm17VZY/kZ1kLIqDTWzrsbdUmIFsSZPiZHtvE=; b=Y4sVbFiZtVY8bPpE8OQFLlMH292pVdAUVhrf+qT16Pu2zGNb8u8QkxiYGkmDz5erF+ wCiNvWlQ+I26AfqqV59p+ew5Tgrsp5Oz+QBpozwv7XaU716h6sxLMvIQd88KYfYlgLgb FgmuH8FbBjuVEqXzPAHJ/nOY53VNLP2XIFRcZ+yStuV0h2z5wDm/Dow5+oP3BvILK3Mu 5ivF8dvbAM1nUPAefxXU68VUwjXtb1dlNLharKCbRJ52OHvkAjAI3VL76Tp2OL38INep bcPBoYm/8xC4K7dx5iXMaB5pGPwnqelqWbACST7wksYkyK7dbq86vnE7GzuP0ZdbA0Kk ARQQ== X-Forwarded-Encrypted: i=1; AJvYcCWFxsNfCIvHvKmesoPVZxu7lEoT7FSYFR5bUsZ2KzC6ctHU/QAMTcFpNBX3Ar6ZlWwT1TbfNL7H/bQs5LE=@vger.kernel.org X-Gm-Message-State: AOJu0YwGs3R7JorE6Tg8WnYksYnkkuEqdVQu/g8SdAa92Yt7l5bV+Lmq 084XlXwCQZzETCPHoaPOf0GayQbjVnWxhRF1NSToMhfMmSRDpKQubGf7lR4CZ2bEAJeIwkL3+xk fih6YrAcn7d5Xwg== X-Google-Smtp-Source: AGHT+IHyxGM7ePub6HtjfYLSj9a32LyEArxp8bNWTTEEpgKO73sIN1+lLEyaFKDD5eGgrDeN43lBdlTkHO7++g== X-Received: from dlbui24.prod.google.com ([2002:a05:7022:3d18:b0:11d:cdd1:432c]) (user=jasonmiu job=prod-delivery.src-stubby-dispatcher) by 2002:a05:7022:689c:b0:119:e56b:9582 with SMTP id a92af1059eb24-11e0315e218mr6523139c88.7.1765248804236; Mon, 08 Dec 2025 18:53:24 -0800 (PST) Date: Mon, 8 Dec 2025 18:53:13 -0800 In-Reply-To: <20251209025317.3846938-1-jasonmiu@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20251209025317.3846938-1-jasonmiu@google.com> X-Mailer: git-send-email 2.52.0.223.gf5cc29aaa4-goog Message-ID: <20251209025317.3846938-2-jasonmiu@google.com> Subject: [PATCH v3 1/4] kho: Introduce KHO FDT ABI header From: Jason Miu To: Alexander Graf , Andrew Morton , Baoquan He , Changyuan Lyu , David Matlack , David Rientjes , Jason Gunthorpe , Jason Miu , Mike Rapoport , Pasha Tatashin , Pratyush Yadav , kexec@lists.infradead.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Introduce the `include/linux/kho/abi/kexec_handover.h` header file, which defines the stable ABI for the KHO mechanism. This header specifies how preserved data is passed between kernels using an FDT. The ABI contract includes the FDT structure, node properties, and the "kho-v1" compatible string. By centralizing these definitions, this header serves as the foundational agreement for inter-kernel communication of preserved states, ensuring forward compatibility and preventing misinterpretation of data across kexec transitions. Since the ABI definitions are now centralized in the header files, the YAML files that previously described the FDT interfaces are redundant. These redundant files have therefore been removed. Signed-off-by: Jason Miu --- Documentation/core-api/kho/bindings/kho.yaml | 43 ---------- .../core-api/kho/bindings/sub-fdt.yaml | 27 ------ Documentation/core-api/kho/concepts.rst | 13 +++ Documentation/core-api/kho/fdt.rst | 79 +++-------------- include/linux/kho/abi/kexec_handover.h | 84 +++++++++++++++++++ kernel/liveupdate/kexec_handover.c | 19 ++--- 6 files changed, 116 insertions(+), 149 deletions(-) delete mode 100644 Documentation/core-api/kho/bindings/kho.yaml delete mode 100644 Documentation/core-api/kho/bindings/sub-fdt.yaml create mode 100644 include/linux/kho/abi/kexec_handover.h diff --git a/Documentation/core-api/kho/bindings/kho.yaml b/Documentation/c= ore-api/kho/bindings/kho.yaml deleted file mode 100644 index 11e8ab7b219d..000000000000 --- a/Documentation/core-api/kho/bindings/kho.yaml +++ /dev/null @@ -1,43 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -title: Kexec HandOver (KHO) root tree - -maintainers: - - Mike Rapoport - - Changyuan Lyu - -description: | - System memory preserved by KHO across kexec. - -properties: - compatible: - enum: - - kho-v1 - - preserved-memory-map: - description: | - physical address (u64) of an in-memory structure describing all pres= erved - folios and memory ranges. - -patternProperties: - "$[0-9a-f_]+^": - $ref: sub-fdt.yaml# - description: physical address of a KHO user's own FDT. - -required: - - compatible - - preserved-memory-map - -additionalProperties: false - -examples: - - | - kho { - compatible =3D "kho-v1"; - preserved-memory-map =3D <0xf0be16 0x1000000>; - - memblock { - fdt =3D <0x80cc16 0x1000000>; - }; - }; diff --git a/Documentation/core-api/kho/bindings/sub-fdt.yaml b/Documentati= on/core-api/kho/bindings/sub-fdt.yaml deleted file mode 100644 index b9a3d2d24850..000000000000 --- a/Documentation/core-api/kho/bindings/sub-fdt.yaml +++ /dev/null @@ -1,27 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -title: KHO users' FDT address - -maintainers: - - Mike Rapoport - - Changyuan Lyu - -description: | - Physical address of an FDT blob registered by a KHO user. - -properties: - fdt: - description: | - physical address (u64) of an FDT blob. - -required: - - fdt - -additionalProperties: false - -examples: - - | - memblock { - fdt =3D <0x80cc16 0x1000000>; - }; diff --git a/Documentation/core-api/kho/concepts.rst b/Documentation/core-a= pi/kho/concepts.rst index d626d1dbd678..e96893937286 100644 --- a/Documentation/core-api/kho/concepts.rst +++ b/Documentation/core-api/kho/concepts.rst @@ -72,3 +72,16 @@ Public API =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D .. kernel-doc:: kernel/liveupdate/kexec_handover.c :export: + +Internal API +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +.. kernel-doc:: kernel/liveupdate/kexec_handover_internal.h + +.. kernel-doc:: kernel/liveupdate/kexec_handover.c + :internal: + +.. kernel-doc:: kernel/liveupdate/kexec_handover_debugfs.c + :internal: + +.. kernel-doc:: kernel/liveupdate/kexec_handover_debug.c + :internal: diff --git a/Documentation/core-api/kho/fdt.rst b/Documentation/core-api/kh= o/fdt.rst index 62505285d60d..4e080ccc420e 100644 --- a/Documentation/core-api/kho/fdt.rst +++ b/Documentation/core-api/kho/fdt.rst @@ -4,77 +4,18 @@ KHO FDT =3D=3D=3D=3D=3D=3D=3D =20 -KHO uses the flattened device tree (FDT) container format and libfdt -library to create and parse the data that is passed between the -kernels. The properties in KHO FDT are stored in native format. -It includes the physical address of an in-memory structure describing -all preserved memory regions, as well as physical addresses of KHO users' -own FDTs. Interpreting those sub FDTs is the responsibility of KHO users. +Kexec Handover ABI +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -KHO nodes and properties -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +KHO uses the FDT to pass data between kernels. The exact structure of +this FDT is a stable contract between kernels and is documented +directly in the ABI header file. =20 -Property ``preserved-memory-map`` ---------------------------------- +.. kernel-doc:: include/linux/kho/abi/kexec_handover.h + :doc: Kexec Handover ABI =20 -KHO saves a special property named ``preserved-memory-map`` under the root= node. -This node contains the physical address of an in-memory structure for KHO = to -preserve memory regions across kexec. - -Property ``compatible`` ------------------------ - -The ``compatible`` property determines compatibility between the kernel -that created the KHO FDT and the kernel that attempts to load it. -If the kernel that loads the KHO FDT is not compatible with it, the entire -KHO process will be bypassed. - -Property ``fdt`` ----------------- - -Generally, a KHO user serialize its state into its own FDT and instructs -KHO to preserve the underlying memory, such that after kexec, the new kern= el -can recover its state from the preserved FDT. - -A KHO user thus can create a node in KHO root tree and save the physical a= ddress -of its own FDT in that node's property ``fdt`` . - -Examples +See Also =3D=3D=3D=3D=3D=3D=3D=3D =20 -The following example demonstrates KHO FDT that preserves two memory -regions created with ``reserve_mem`` kernel command line parameter:: - - /dts-v1/; - - / { - compatible =3D "kho-v1"; - - preserved-memory-map =3D <0x40be16 0x1000000>; - - memblock { - fdt =3D <0x1517 0x1000000>; - }; - }; - -where the ``memblock`` node contains an FDT that is requested by the -subsystem memblock for preservation. The FDT contains the following -serialized data:: - - /dts-v1/; - - / { - compatible =3D "memblock-v1"; - - n1 { - compatible =3D "reserve-mem-v1"; - start =3D <0xc06b 0x4000000>; - size =3D <0x04 0x00>; - }; - - n2 { - compatible =3D "reserve-mem-v1"; - start =3D <0xc067 0x4000000>; - size =3D <0x04 0x00>; - }; - }; +- :doc:`/admin-guide/mm/kho` +- :doc:`/core-api/kho/concepts` diff --git a/include/linux/kho/abi/kexec_handover.h b/include/linux/kho/abi= /kexec_handover.h new file mode 100644 index 000000000000..d78df2d44cb6 --- /dev/null +++ b/include/linux/kho/abi/kexec_handover.h @@ -0,0 +1,84 @@ +/* SPDX-License-Identifier: GPL-2.0-only */ + +/* + * Copyright (C) 2023 Alexander Graf + * Copyright (C) 2025 Microsoft Corporation, Mike Rapoport + * Copyright (C) 2025 Google LLC, Changyuan Lyu + * Copyright (C) 2025 Google LLC, Jason Miu + */ + +#ifndef _LINUX_KHO_ABI_KEXEC_HANDOVER_H +#define _LINUX_KHO_ABI_KEXEC_HANDOVER_H + +/** + * DOC: Kexec Handover ABI + * + * This header defines the stable ABI for passing preserved data from one = kernel + * to the next using a Flattened Device Tree (FDT). The first kernel creat= es 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, no= de + * 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 pro= vided + * the compatibility version is incremented; however, backward/forward + * compatibility is only guaranteed for kernels supporting the same ABI ve= rsion. + * + * 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 t= hat + * need to persist across the kexec transition. The subsequent kernel th= en + * parses this FDT to locate and restore the preserved data.:: + * + * / { + * compatible =3D "kho-v1"; + * + * preserved-memory-map =3D <0x...>; + * + * { + * fdt =3D <0x...>; + * }; + * + * { + * fdt =3D <0x...>; + * }; + * ... ... + * { + * fdt =3D <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 (): + * Subnodes can also be added to the root node to + * describe other preserved data blobs. The + * 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. + */ + +/* The compatible string for the KHO FDT root node. */ +#define KHO_FDT_COMPATIBLE "kho-v1" + +/* The FDT property for the preserved memory map. */ +#define KHO_FDT_MEMORY_MAP_PROP_NAME "preserved-memory-map" + +/* The FDT property for sub-FDTs. */ +#define KHO_FDT_SUB_TREE_PROP_NAME "fdt" + +#endif /* _LINUX_KHO_ABI_KEXEC_HANDOVER_H */ diff --git a/kernel/liveupdate/kexec_handover.c b/kernel/liveupdate/kexec_h= andover.c index 9dc51fab604f..d3d02a9ea391 100644 --- a/kernel/liveupdate/kexec_handover.c +++ b/kernel/liveupdate/kexec_handover.c @@ -15,6 +15,7 @@ #include #include #include +#include #include #include #include @@ -33,10 +34,7 @@ #include "../kexec_internal.h" #include "kexec_handover_internal.h" =20 -#define KHO_FDT_COMPATIBLE "kho-v1" -#define PROP_PRESERVED_MEMORY_MAP "preserved-memory-map" -#define PROP_SUB_FDT "fdt" - +/* The magic token for preserved pages */ #define KHO_PAGE_MAGIC 0x4b484f50U /* ASCII for 'KHOP' */ =20 /* @@ -378,7 +376,7 @@ static void kho_update_memory_map(struct khoser_mem_chu= nk *first_chunk) void *ptr; u64 phys; =20 - ptr =3D fdt_getprop_w(kho_out.fdt, 0, PROP_PRESERVED_MEMORY_MAP, NULL); + ptr =3D fdt_getprop_w(kho_out.fdt, 0, KHO_FDT_MEMORY_MAP_PROP_NAME, NULL); =20 /* Check and discard previous memory map */ phys =3D get_unaligned((u64 *)ptr); @@ -468,7 +466,7 @@ static bool __init kho_mem_deserialize(const void *fdt) u64 mem; int len; =20 - mem_ptr =3D fdt_getprop(fdt, 0, PROP_PRESERVED_MEMORY_MAP, &len); + mem_ptr =3D fdt_getprop(fdt, 0, KHO_FDT_MEMORY_MAP_PROP_NAME, &len); if (!mem_ptr || len !=3D sizeof(u64)) { pr_err("failed to get preserved memory bitmaps\n"); return false; @@ -733,7 +731,8 @@ int kho_add_subtree(const char *name, void *fdt) goto out_pack; } =20 - err =3D fdt_setprop(root_fdt, off, PROP_SUB_FDT, &phys, sizeof(phys)); + err =3D fdt_setprop(root_fdt, off, KHO_FDT_SUB_TREE_PROP_NAME, + &phys, sizeof(phys)); if (err < 0) goto out_pack; =20 @@ -764,7 +763,7 @@ void kho_remove_subtree(void *fdt) const u64 *val; int len; =20 - val =3D fdt_getprop(root_fdt, off, PROP_SUB_FDT, &len); + val =3D fdt_getprop(root_fdt, off, KHO_FDT_SUB_TREE_PROP_NAME, &len); if (!val || len !=3D sizeof(phys_addr_t)) continue; =20 @@ -1310,7 +1309,7 @@ int kho_retrieve_subtree(const char *name, phys_addr_= t *phys) if (offset < 0) return -ENOENT; =20 - val =3D fdt_getprop(fdt, offset, PROP_SUB_FDT, &len); + val =3D fdt_getprop(fdt, offset, KHO_FDT_SUB_TREE_PROP_NAME, &len); if (!val || len !=3D sizeof(*val)) return -EINVAL; =20 @@ -1330,7 +1329,7 @@ static __init int kho_out_fdt_setup(void) err |=3D fdt_finish_reservemap(root); err |=3D fdt_begin_node(root, ""); err |=3D fdt_property_string(root, "compatible", KHO_FDT_COMPATIBLE); - err |=3D fdt_property(root, PROP_PRESERVED_MEMORY_MAP, &empty_mem_map, + err |=3D fdt_property(root, KHO_FDT_MEMORY_MAP_PROP_NAME, &empty_mem_map, sizeof(empty_mem_map)); err |=3D fdt_end_node(root); err |=3D fdt_finish(root); --=20 2.52.0.223.gf5cc29aaa4-goog