[PATCH v2 07/17] kexec: Add documentation for KHO

[Alexander Graf]

On 17.01.24 17:54, Rob Herring wrote:
> On Wed, Jan 17, 2024 at 8:02 AM Alexander Graf <graf at amazon.com> wrote:
>>
>> On 03.01.24 19:48, Rob Herring wrote:
>>> On Fri, Dec 22, 2023 at 12:52 PM Alexander Graf <graf at amazon.com> wrote:
>>>> With KHO in place, let's add documentation that describes what it is and
>>>> how to use it.
>>>>
>>>> Signed-off-by: Alexander Graf <graf at amazon.com>
>>>> ---
>>>>    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.
> 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).


I understand and agree - it's been confusing to pretty much everyone who 
was looking at KHO so far. Unfortunately I'm terrible at naming. Do you 
happen to have a good suggestion? :)


>
>>> 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].


Oooh, thanks a lot for the pointer! I'll add them :)


Alex





Amazon Development Center Germany GmbH
Krausenstr. 38
10117 Berlin
Geschaeftsfuehrung: Christian Schlaeger, Jonathan Weiss
Eingetragen am Amtsgericht Charlottenburg unter HRB 149173 B
Sitz: Berlin
Ust-ID: DE 289 237 879