From patchwork Fri Dec 22 19:51:34 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alexander Graf X-Patchwork-Id: 13503756 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id DED46C41535 for ; Fri, 22 Dec 2023 19:52:05 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 817706B0092; Fri, 22 Dec 2023 14:52:05 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 7C77D6B0093; Fri, 22 Dec 2023 14:52:05 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 66A516B0095; Fri, 22 Dec 2023 14:52:05 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 546576B0092 for ; Fri, 22 Dec 2023 14:52:05 -0500 (EST) Received: from smtpin29.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id 2E78E1A0E6E for ; Fri, 22 Dec 2023 19:52:05 +0000 (UTC) X-FDA: 81595500210.29.5EB6763 Received: from smtp-fw-52004.amazon.com (smtp-fw-52004.amazon.com [52.119.213.154]) by imf07.hostedemail.com (Postfix) with ESMTP id 23F2440026 for ; Fri, 22 Dec 2023 19:52:02 +0000 (UTC) Authentication-Results: imf07.hostedemail.com; dkim=pass header.d=amazon.com header.s=amazon201209 header.b=sRTTzQ0R; spf=pass (imf07.hostedemail.com: domain of "prvs=71347c2e1=graf@amazon.de" designates 52.119.213.154 as permitted sender) smtp.mailfrom="prvs=71347c2e1=graf@amazon.de"; dmarc=pass (policy=quarantine) header.from=amazon.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1703274723; a=rsa-sha256; cv=none; b=dLT/aR8S/k5L9GVuU3Q46XYWZ+rhtQXvxNqV+4/YS3J6zJkzQnOKSmGnzYJ5bgDH33njzk hJFD7KvxigGYRqsmT+lmhoVz/hqgWT8kFPEJpBRMa0LbajeJ2p97gpMtQU8nrxXkeNAiSn e8Y/WG1XWp+PfgQg34q5GPcGmR5eAw8= ARC-Authentication-Results: i=1; imf07.hostedemail.com; dkim=pass header.d=amazon.com header.s=amazon201209 header.b=sRTTzQ0R; spf=pass (imf07.hostedemail.com: domain of "prvs=71347c2e1=graf@amazon.de" designates 52.119.213.154 as permitted sender) smtp.mailfrom="prvs=71347c2e1=graf@amazon.de"; dmarc=pass (policy=quarantine) header.from=amazon.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1703274723; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=Wy3QrJqbxk6W3Bwc5BKomfQATEZZd0nBtswCXV4R7vM=; b=BL3sLmChNMXp5G/GSqnCvLjwBdg0MQnFh7uqzYC7VseX/tubwSwIfl/nzAUewTGJ9r78hk /jBqHRDhUkJV1IYEJ9Yw346NQUOaWfS19QmxjLcc6C4FzncDaUbFSM/92v0MLBcDHo5K0a 3K0mO7DsoXLYg75R/hIMU8eXB1MKxYQ= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amazon.com; i=@amazon.com; q=dns/txt; s=amazon201209; t=1703274723; x=1734810723; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=Wy3QrJqbxk6W3Bwc5BKomfQATEZZd0nBtswCXV4R7vM=; b=sRTTzQ0R+cvUWMJHeZ/1z8Ns9v1K1H0nVdac2SEbYRghJ2Dn3pjXm2sL LRxhKiSPA9SfIj0eCgbknn4jgD89gC8gORk3FulOtMJfLFaPCQJLurWcV JDEbDeDHj6vr5PiIjHwz2CZIv5LCZnpF//ggejWl+Fmqlg17sNvGZeEAP M=; X-IronPort-AV: E=Sophos;i="6.04,297,1695686400"; d="scan'208";a="174097101" Received: from iad12-co-svc-p1-lb1-vlan2.amazon.com (HELO email-inbound-relay-iad-1d-m6i4x-e651a362.us-east-1.amazon.com) ([10.43.8.2]) by smtp-border-fw-52004.iad7.amazon.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 22 Dec 2023 19:52:01 +0000 Received: from smtpout.prod.us-west-2.prod.farcaster.email.amazon.dev (iad7-ws-svc-p70-lb3-vlan3.iad.amazon.com [10.32.235.38]) by email-inbound-relay-iad-1d-m6i4x-e651a362.us-east-1.amazon.com (Postfix) with ESMTPS id 6EDEC8053C; Fri, 22 Dec 2023 19:51:54 +0000 (UTC) Received: from EX19MTAUWA001.ant.amazon.com [10.0.7.35:11667] by smtpin.naws.us-west-2.prod.farcaster.email.amazon.dev [10.0.56.23:2525] with esmtp (Farcaster) id 7869ce95-383d-43dc-8bf7-e44da388af62; Fri, 22 Dec 2023 19:51:53 +0000 (UTC) X-Farcaster-Flow-ID: 7869ce95-383d-43dc-8bf7-e44da388af62 Received: from EX19D020UWC004.ant.amazon.com (10.13.138.149) by EX19MTAUWA001.ant.amazon.com (10.250.64.204) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1118.40; Fri, 22 Dec 2023 19:51:53 +0000 Received: from dev-dsk-graf-1a-5ce218e4.eu-west-1.amazon.com (10.253.83.51) by EX19D020UWC004.ant.amazon.com (10.13.138.149) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1118.40; Fri, 22 Dec 2023 19:51:49 +0000 From: Alexander Graf To: CC: , , , , , , , Eric Biederman , "H. Peter Anvin" , Andy Lutomirski , Peter Zijlstra , "Rob Herring" , Steven Rostedt , "Andrew Morton" , Mark Rutland , "Tom Lendacky" , Ashish Kalra , James Gowans , Stanislav Kinsburskii , , , , Anthony Yznaga , Usama Arif , David Woodhouse , Benjamin Herrenschmidt Subject: [PATCH v2 07/17] kexec: Add documentation for KHO Date: Fri, 22 Dec 2023 19:51:34 +0000 Message-ID: <20231222195144.24532-2-graf@amazon.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20231222195144.24532-1-graf@amazon.com> References: <20231222193607.15474-1-graf@amazon.com> <20231222195144.24532-1-graf@amazon.com> MIME-Version: 1.0 X-Originating-IP: [10.253.83.51] X-ClientProxiedBy: EX19D032UWA002.ant.amazon.com (10.13.139.81) To EX19D020UWC004.ant.amazon.com (10.13.138.149) X-Rspamd-Server: rspam08 X-Rspamd-Queue-Id: 23F2440026 X-Stat-Signature: wrrsyr635z8xgpzwndjgmfyd8q6z4xjj X-Rspam-User: X-HE-Tag: 1703274722-445606 X-HE-Meta: U2FsdGVkX1+ALCDieoySgD2WaX5N64taYcdP1Fxt4qxlsDuHhhiXVAejP14bPZg9z4FSxF/9IfVslTZZJ3iFIsOiC11+LUFyh5XPbF28tI6cQqgNsUA3kNwcFW/GaVeI4CaVCJaoqrfaOIPNY2F0VgOdy1HnTtBm7roYzgVgm+jPMc+ttFO3Pral3g58DLvK1MVZAP1ahRKKUFYq7RsPdyqiWlWbmjxxSrIwelPCz8gDF5UpPwV+j1BAAUv9a5VT14QYWLHe8DdadykgxlyoH/J3YF1953ExhmHBMDAoDbpAofwxAUBV0NuQIKyNgpweEPIra08KyAj7o8480SdLwh05NNemoo3BKc8s+emYX6pjeVMsXh50AFUmA9h8vRm+wC9JOSQhjf6jw+1h6EzO8qyzF/y8Bb5gXOXuj4zacusK55vNUXN0zdfF3USzBkvgsYHJkOi5f8rtCVD4fn+RkzWcmSBZZ90aqNiaCqAGDflEltr6pe+xaCEN2PCPcK6qyF7fGcCM/AGwSNUMJa8Fl8AASN5Vsi67vyuxf9u1ct2UxKcXI2+g5LjcItLz7QhEppW6vWh638jZrOfGmBcjzmbapkE1co62t+shTGmTbF4dOZHcpd6Am/unR1TkpuIpVS8tEBVw16szisZDqoPqpch+/65s/68Xb+hBRWrM/YoE1AFWO64LBkdDIomMPDlcLqm3XRQu/TcEuYFLL7TlnNC5n3jtKlzmCX8PSUYYn10aAtjTXYaFE5kIkP0gxoT/JbE6kfVvOmLN92stMmUfJFjMkit1Ay5kSjP5eYyPXtnOzLBHFdcRtf9afpB9F12jABXqvKXfnCD9iJEXgX0rtvNVplOpcKJiPjbVIxrKtq2ADAwziY6SLmNx+hgTXJS2lXxruGjUm72LQcAt2iTe0g6PWoHfJsI2F++XNiXB68ZjPIQpcSwWFuGlgt4Q291iD+DbobuctEOqcWAXQOh xFvKtZPR mV6ZR5J7+pWIItNip8h5DUE5kpnfXWT2xpiB1+ewdqj+UPIoXYGYd3OJg2RPVynsWlo5zF8sBmgxp7jgC6x4cT7U4g0do4hXT6ahUpGRBn3+2DIrGqMfHTYm9V4g0mxpDY0dTc8BG4g6wzHZek4dWLcn2D/s4sJkveGiRNQ7z5lA1W7lMoVM1TGWpLT692wjWsV5ZY9RnMsiLySqHrobrTtj0tqAy0UBS2xzook7+6/gczz4lC6gD808Pf6stW6VBe3tk95Tpmow/5AerRNbqfeSH3N9Wb3W+1n9lOnOjj8Rw3/3DG6uIuG7K0rqoD6SLyqzXplYxvi7nzIocPgEegPEoVM7ZTc2G7vixPy+VpASyaHefxPOuUwR4hNjT3QFhkBRh9vt3P8+ht1ELb2ehz1wI2663U4sfmACZdlnkr65Kfb6wNdO2PYGY3/3fJuiRmmsWqOY4MCfZDBf5z9ddGyjREBseEu9rBB1Lor9fp0zcmw0/zz6DbmbMduQYgZcZeOy8FWVJCnG5xxhLwr8k58SktcR+edgeN8jLMtDFDBWNGlwpAC191A5IBX6APEaFu9P0p+jTXKGdIDbkliaQwnt3k1wPiWWM3P9O2M+lCwq0inXyEYaeeE8npw== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: With KHO in place, let's add documentation that describes what it is and how to use it. Signed-off-by: Alexander Graf --- Documentation/kho/concepts.rst | 88 ++++++++++++++++++++++++++++++++ Documentation/kho/index.rst | 19 +++++++ Documentation/kho/usage.rst | 57 +++++++++++++++++++++ Documentation/subsystem-apis.rst | 1 + 4 files changed, 165 insertions(+) create mode 100644 Documentation/kho/concepts.rst create mode 100644 Documentation/kho/index.rst create mode 100644 Documentation/kho/usage.rst diff --git a/Documentation/kho/concepts.rst b/Documentation/kho/concepts.rst new file mode 100644 index 000000000000..8e4fe8c57865 --- /dev/null +++ b/Documentation/kho/concepts.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +======================= +Kexec Handover Concepts +======================= + +Kexec HandOver (KHO) is a mechanism that allows Linux to preserve state - +arbitrary properties as well as memory locations - across kexec. + +It introduces multiple concepts: + +KHO Device Tree +--------------- + +Every KHO kexec carries a KHO specific flattened device tree blob that +describes the state of the system. Device drivers can register to KHO to +serialize their state before kexec. After KHO, device drivers can read +the device tree and extract previous state. + +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. + +KHO introduces a new concept to its device tree: ``mem`` properties. A +``mem`` property can inside any subnode in the device tree. When present, +it contains an array of physical memory ranges that the new kernel must mark +as reserved on boot. It is recommended, but not required, to make these ranges +as physically contiguous as possible to reduce the number of array elements :: + + struct kho_mem { + __u64 addr; + __u64 len; + }; + +After boot, drivers can call the kho subsystem to transfer ownership of memory +that was reserved via a ``mem`` property to themselves to continue using memory +from the previous execution. + +The KHO device tree follows the in-Linux schema requirements. Any element in +the device tree is documented via device tree schema yamls that explain what +data gets transferred. + +Mem cache +--------- + +The new kernel needs to know about all memory reservations, but is unable to +parse the device tree yet in early bootup code because of memory limitations. +To simplify the initial memory reservation flow, the old kernel passes a +preprocessed array of physically contiguous reserved ranges to the new kernel. + +These reservations have to be separate from architectural memory maps and +reservations because they differ on every kexec, while the architectural ones +get passed directly between invocations. + +The less entries this cache contains, the faster the new kernel will boot. + +Scratch Region +-------------- + +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 it ingests the mem cache. + +We guarantee that we always have such a region through the scratch region: On +first boot, you can pass the ``kho_scratch`` kernel command line option. When +it is set, Linux allocates a CMA region of the given size. 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. + +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 irrenevant for +the next KHO, because kexec can overwrite even the original kernel. + +KHO active phase +---------------- + +To enable user space based kexec file loader, the kernel needs to be able to +provide the device tree that describes the previous kernel's state before +performing the actual kexec. The process of generating that device tree is +called serialization. When the device tree is generated, some properties +of the system may become immutable because they are already written down +in the device tree. That state is called the KHO active phase. diff --git a/Documentation/kho/index.rst b/Documentation/kho/index.rst new file mode 100644 index 000000000000..5e7eeeca8520 --- /dev/null +++ b/Documentation/kho/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +======================== +Kexec Handover Subsystem +======================== + +.. toctree:: + :maxdepth: 1 + + concepts + usage + +.. only:: subproject and html + + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/kho/usage.rst b/Documentation/kho/usage.rst new file mode 100644 index 000000000000..5efa2a58f9c3 --- /dev/null +++ b/Documentation/kho/usage.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +==================== +Kexec Handover Usage +==================== + +Kexec HandOver (KHO) is a mechanism that allows Linux to preserve state - +arbitrary properties as well as memory locations - across kexec. + +This document expects that you are familiar with the base KHO +:ref:`Documentation/kho/concepts.rst `. If you have not read +them yet, please do so now. + +Prerequisites +------------- + +KHO is available when the ``CONFIG_KEXEC_KHO`` config option is set to y +at compile team. Every KHO producer has its own config option that you +need to enable if you would like to preserve their respective state across +kexec. + +To use KHO, please boot the kernel with the ``kho_scratch`` command +line parameter set to allocate a scratch region. For example +``kho_scratch=512M`` will reserve a 512 MiB scratch region on boot. + +Perform a KHO kexec +------------------- + +Before you can perform a KHO kexec, you need to move the system into the +:ref:`Documentation/kho/concepts.rst ` :: + + $ echo 1 > /sys/kernel/kho/active + +After this command, the KHO device tree is available in ``/sys/kernel/kho/dt``. + +Next, load the target payload and kexec into it. It is important that you +use the ``-s`` parameter to use the in-kernel kexec file loader, as user +space kexec tooling currently has no support for KHO with the user space +based file loader :: + + # kexec -l Image --initrd=initrd -s + # kexec -e + +The new kernel will boot up and contain some of the previous kernel's state. + +For example, if you enabled ``CONFIG_FTRACE_KHO``, the new kernel will contain +the old kernel's trace buffers in ``/sys/kernel/debug/tracing/trace``. + +Abort a KHO exec +---------------- + +You can move the system out of KHO active phase again by calling :: + + $ echo 1 > /sys/kernel/kho/active + +After this command, the KHO device tree is no longer available in +``/sys/kernel/kho/dt``. diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index 930dc23998a0..8207b6514d87 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -86,3 +86,4 @@ Storage interfaces misc-devices/index peci/index wmi/index + kho/index