From mboxrd@z Thu Jan 1 00:00:00 1970 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 D5E58C47258 for ; Wed, 17 Jan 2024 16:55:05 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 5C33D6B0103; Wed, 17 Jan 2024 11:55:05 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 54A2D6B0109; Wed, 17 Jan 2024 11:55:05 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3EB336B0113; Wed, 17 Jan 2024 11:55:05 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0014.hostedemail.com [216.40.44.14]) by kanga.kvack.org (Postfix) with ESMTP id 287C76B0103 for ; Wed, 17 Jan 2024 11:55:05 -0500 (EST) Received: from smtpin14.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id E0E2E160CF4 for ; Wed, 17 Jan 2024 16:55:04 +0000 (UTC) X-FDA: 81689402928.14.E14D0E6 Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by imf29.hostedemail.com (Postfix) with ESMTP id 2FA66120018 for ; Wed, 17 Jan 2024 16:55:01 +0000 (UTC) Authentication-Results: imf29.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=RDEL+tAQ; spf=pass (imf29.hostedemail.com: domain of robh+dt@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=robh+dt@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1705510502; 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=qvJADnd/s/6NDb8oWZQZjhw+Cxh71lIq46Nlv28m7Js=; b=B/uMASOQXR7UVsuMIaXHrgWZBmEFHJAV0KS0530AZJLzuieX6L4jY23KOdTeI4FNm3M/e5 J/MZs5bgjily1J/xWtxmyDXEhWLONqBXhFyRxvI18usWAYeNoe+u+Nsal/b9kK46oy7FOO 0+BhTmhyuIsj3t263DopHCFHL/3Rl9U= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1705510502; a=rsa-sha256; cv=none; b=piEQUEDmwtMFfGBAgYtVCqZmpE9wJT4yxlvSm4ZDCyV1zDU8GQdOJtDLKiPF4zHZ31X2JA mgN2d2DUwQDssU7DvO0tik5PKMp1PzmD+EbGD1h8DUE0XxQAz1LNRen+vQKxIh7ntrK/CA UQ9nT0iirmKWb4V2EHDb3cr/3JVjTz0= ARC-Authentication-Results: i=1; imf29.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=RDEL+tAQ; spf=pass (imf29.hostedemail.com: domain of robh+dt@kernel.org designates 145.40.73.55 as permitted sender) smtp.mailfrom=robh+dt@kernel.org; dmarc=pass (policy=none) header.from=kernel.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id CAEBDCE1CA9 for ; Wed, 17 Jan 2024 16:54:58 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id D2BFEC43390 for ; Wed, 17 Jan 2024 16:54:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1705510497; bh=icda5nsBxvN2zQNuUU8kfCVX7lRfPCzR7ERj2A/6N3o=; h=References:In-Reply-To:From:Date:Subject:To:Cc:From; b=RDEL+tAQiDrYDr+k2xTfms4oEQr9XgsKC5vawe89f6tpAZWWoNmBtps93TrYJqQek 3bKmLBnV99czurDhu/ihnOg362ETeHvOrSW+EiElOkLBhQmavBqO9DYaXDzF8VnBty 23GrfO8YV1Wy29k52RqUvmdxWWLfAhwv+v/US8vSNiXJU0p4UsjrVZAmOw3wLH+W2h jdKuWcDvUTENMvP/2pS+SPVZLzfnbeFZYcFEVRD5EJh+pzXfMlXHb0g3w0Dtr9ox5w JQRw9QiBq41GX7SWHEV9LHBrA6KvbRMwY8zZm6apDkbkMMWc3E1y4KOa1VVxhLNbMW piwwQ4rJTi9rA== Received: by mail-lj1-f180.google.com with SMTP id 38308e7fff4ca-2cdebb968feso12679341fa.1 for ; Wed, 17 Jan 2024 08:54:57 -0800 (PST) X-Gm-Message-State: AOJu0YxS8hdpV16kxzOF1wELustwqgb+F/vGiwQskx4AlYxxBx41QmXj RxzrQyNvIDR97nSZf7vPxUuNQNKsC9E68/VpOA== X-Google-Smtp-Source: AGHT+IE1jgfkJTBfpZ+F4Qzd8uKAwaxoFhnJYLyCjbq9zXmhEnH+sTN071x2CqqdMwDg1wusyGKF4SkodcMKgVdt/Us= X-Received: by 2002:a2e:bd02:0:b0:2cc:d864:1260 with SMTP id n2-20020a2ebd02000000b002ccd8641260mr5936076ljq.62.1705510496033; Wed, 17 Jan 2024 08:54:56 -0800 (PST) MIME-Version: 1.0 References: <20231222193607.15474-1-graf@amazon.com> <20231222195144.24532-1-graf@amazon.com> <20231222195144.24532-2-graf@amazon.com> In-Reply-To: From: Rob Herring Date: Wed, 17 Jan 2024 10:54:43 -0600 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: [PATCH v2 07/17] kexec: Add documentation for KHO To: Alexander Graf Cc: linux-kernel@vger.kernel.org, linux-trace-kernel@vger.kernel.org, linux-mm@kvack.org, devicetree@vger.kernel.org, linux-arm-kernel@lists.infradead.org, kexec@lists.infradead.org, linux-doc@vger.kernel.org, x86@kernel.org, Eric Biederman , "H. Peter Anvin" , Andy Lutomirski , Peter Zijlstra , Steven Rostedt , Andrew Morton , Mark Rutland , Tom Lendacky , Ashish Kalra , James Gowans , Stanislav Kinsburskii , arnd@arndb.de, pbonzini@redhat.com, madvenka@linux.microsoft.com, Anthony Yznaga , Usama Arif , David Woodhouse , Benjamin Herrenschmidt Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 2FA66120018 X-Rspam-User: X-Stat-Signature: nbxp5dnuxtwyfh6pq8so9uhopdjbk7oz X-Rspamd-Server: rspam03 X-HE-Tag: 1705510501-995836 X-HE-Meta: U2FsdGVkX19UWfPquxlYZDDKDSJMVUPanI5P50sXlcmROisprfmDeAq7buZbAmIUOjIb1y3GnjQY7BJOTy5smHBFo8CF/HKgI6wQBsYPfAXIE+o1dZYuFyJwFmL9WIUQ/bj0jUvieptMWx2jsMAnsUIA8MTjkFCLtOJNWexI3Ggp/na1mR4+HOz5INnw8u6FX27sVWCgZOXMLMDoD5wsD+J1Xfh2CCWvTzpEUfd+3r3FjzdNOVc0LqulMGJjK5i5TY7x9WtXm0QfTjkrCQjsgXKoCCUnQExEZeqK5WfIfIw4ho0S25puS4umMJodPZYjgrlqUU9BhyXgYJYTDX2Nc9uXKAevDpL6PYMF5rkULYB5K5B5kujTAIZCjWqi4oEyU846NlYctu3zPbgwfBpEhurmR/AtLvB+3cii7Lg4oYONn9YxZLs7KvQNm1TY4c66IRmLG5nbRcdrkBVqDedWumza31VxvMqkGUdfHxsP8/UvU3TK+2Uitf7sdSMw+2PgpTMxdVZTuzLHlyzv3F47g5WJdgLTi8VGfW8Deu69jOn8O61jnXp+rmJaZFzI4z4qd0UeKR62oLa2sU/2r4UhT7hPG1rNUOAX4A6qqLAGqqCeYL4XI83INKuPY1nAzyI/tB2ZXkrcAKJVgaUgQF5JHxNigOmsHlHADjMpn5z1scg4gErpdcTevMF6FS4XwGc2/5GC3yGvC6JGhDdFMqCoi1pcDtpyqBOAOY4Ji8ZOWgBPRpFXgLG6TL/sbr7nUNGK+N1L/FHuoj8WZjVBaJ+R4wjBui39xFWfCbe6nidG/5S03/GjEc1Qi7+DNW3gx3tn/oh1aj2IW1pgrSzM54Vw6sX5P7Bp2TaYmpxHyLuIS3RNjXp2Iy/gMI+bBoLAsGN6g+WohrPzGtKoZBQeKQ2MZfJCuxJu9STOLiurcpnjcOEhyajQ7LiF8oEF8ssSKrEh6axGJ2wZ8WhZTwtBMDw OXOi4jhJ lZlAN++LN44u1kXMtk+Ty9LihzY1rol2B1DAaPbrfnTwhVXBcJTYWBixw4FtprEGSQq3SfRnS64ZiYYf3tgmkCNmC1kQoEKq2i7pJBjUC9alFS9H8LqEEM4zgcRNxcMsJoqQmqgjsIMCimqhQ4Shh+i7ogouJrt2AE+3waKoP+2QRS/IoJwFbjmleRLKw+fgkkBuZUzuOx5hBIqG0wWu9ks3RIXwT2snD5sqRNPk3ulAHEbPMC0w9K6wwkStDAf3CSTlAbUjuBjNAutS+5fj1u1mI9R3fCan6qIY5rCvKjm92LvY= 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: On Wed, Jan 17, 2024 at 8:02=E2=80=AFAM Alexander Graf wr= ote: > > > On 03.01.24 19:48, Rob Herring wrote: > > > > On Fri, Dec 22, 2023 at 12:52=E2=80=AFPM Alexander Graf wrote: > >> With KHO in place, let's add documentation that describes what it is a= nd > >> 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/concep= ts.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 > >> + > >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > >> +Kexec Handover Concepts > >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > >> + > >> +Kexec HandOver (KHO) is a mechanism that allows Linux to preserve sta= te - > >> +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 tha= t > >> +describes the state of the system. Device drivers can register to KHO= to > >> +serialize their state before kexec. After KHO, device drivers can rea= d > >> +the device tree and extract previous state. Can you avoid calling anything "device tree" as much as possible. We can't avoid the format is FDT/DTB, but otherwise none of this is Devicetree as most folks know it. Sure, there can be trees of devices which are not Devicetree, but this is neither. You could have used BSON or any hierarchical key-value pair serialization format just as easily (if we already had a parser in the kernel). > > How does this work with kexec when there is also the FDT for the h/w? > > The h/w FDT has a /chosen property pointing to this FDT blob? > > > Yep, exactly. Those properties need to be documented here[1]. [...] > >> +KHO introduces a new concept to its device tree: ``mem`` properties. = A > >> +``mem`` property can inside any subnode in the device tree. When pres= ent, > >> +it contains an array of physical memory ranges that the new kernel mu= st mark > >> +as reserved on boot. It is recommended, but not required, to make the= se ranges > >> +as physically contiguous as possible to reduce the number of array el= ements :: > >> + > >> + 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 us= ing memory > >> +from the previous execution. > >> + > >> +The KHO device tree follows the in-Linux schema requirements. Any ele= ment in > >> +the device tree is documented via device tree schema yamls that expla= in what > >> +data gets transferred. > > If this is all separate, then I think the schemas should be too. And > > then from my (DT maintainer) perspective, you can do whatever you want > > here (like FIT images). The dtschema tools are pretty much only geared > > for "normal" DTs. A couple of problems come to mind. You can't exclude > > or change standard properties. The decoding of the DTB to run > > validation assumes big endian. We could probably split things up a > > bit, but you may be better off just using jsonschema directly. I'm not > > even sure running validation here would that valuable. You have 1 > > source of code generating the DT and 1 consumer. Yes, there's > > different kernel versions to deal with, but it's not 100s of people > > creating 1000s of DTs with 100s of nodes. > > > > You might look at the netlink stuff which is using its own yaml syntax > > to generate code and jsonschema is used to validate the yaml. > > > I'm currently a lot more interested in the documentation aspect than in > the validation, yeah. So I think for v3, I'll just throw the schemas > into the Documentation/kho directory without any validation. We can > worry about that later :) I'll regret that when I get patches fixing them, but okay. Rob [1] https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/= chosen.yaml