[PATCH v4 14/14] Documentation: KHO: Add memblock bindings

[Mike Rapoport]

On Sun, Feb 09, 2025 at 11:29:41AM +0100, Krzysztof Kozlowski wrote:
> On 06/02/2025 14:27, Mike Rapoport wrote:
> > From: "Mike Rapoport (Microsoft)" <rppt at kernel.org>
> > 
> > We introduced KHO into Linux: A framework that allows Linux to pass
> > metadata and memory across kexec from Linux to Linux. KHO reuses fdt
> > as file format and shares a lot of the same properties of firmware-to-
> > Linux boot formats: It needs a stable, documented ABI that allows for
> > forward and backward compatibility as well as versioning.
> 
> Please use subject prefixes matching the subsystem. You can get them for
> example with `git log --oneline -- DIRECTORY_OR_FILE` on the directory
> your patch is touching. For bindings, the preferred subjects are
> explained here:
> https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
 
These are not devicetree binding for communicating data from firmware to
the kernel. These bindings are specific to KHO which is perfectly
reflected by the subject.

Just a brief reminder from v2 discussion:
(https://lore.kernel.org/linux-mm/20231222193607.15474-1-graf@amazon.com/)

"For quick reference: KHO is a new mechanism this patch set introduces 
which allows Linux to pass arbitrary memory and metadata between kernels 
on kexec. I'm reusing FDTs to implement the hand over protocol, as 
Linux-to-Linux boot communication holds very similar properties to 
firmware-to-Linux boot communication. So this binding is not about 
hardware; it's about preserving Linux subsystem state across kexec.

For more details, please refer to the KHO documentation which is part of 
patch 7 of this patch set: 
https://lore.kernel.org/lkml/20231222195144.24532-2-graf@amazon.com/"

and

"This is our own data structure for KHO that just happens to again 
contain a DT structure. The reason is simple: I want a unified, 
versioned, introspectable data format that is cross platform so you 
don't need to touch every architecture specific boot passing logic every 
time you want to add a tiny piece of data."
 
> > As first user of KHO, we introduced memblock which can now preserve
> > memory ranges reserved with reserve_mem command line options contents
> > across kexec, so you can use the post-kexec kernel to read traces from
> > the pre-kexec kernel.
> > 
> > This patch adds memblock schemas similar to "device" device tree ones to
> > a new kho bindings directory. This allows us to force contributors to
> > document the data that moves across KHO kexecs and catch breaking change
> > during review.
> > 
> > Co-developed-by: Alexander Graf <graf at amazon.com>
> > Signed-off-by: Alexander Graf <graf at amazon.com>
> > Signed-off-by: Mike Rapoport (Microsoft) <rppt at kernel.org>
> > ---
> >  .../kho/bindings/memblock/reserve_mem.yaml    | 41 ++++++++++++++++++
> >  .../bindings/memblock/reserve_mem_map.yaml    | 42 +++++++++++++++++++
> >  2 files changed, 83 insertions(+)
> >  create mode 100644 Documentation/kho/bindings/memblock/reserve_mem.yaml
> >  create mode 100644 Documentation/kho/bindings/memblock/reserve_mem_map.yaml
> > 
> > diff --git a/Documentation/kho/bindings/memblock/reserve_mem.yaml b/Documentation/kho/bindings/memblock/reserve_mem.yaml
> > new file mode 100644
> > index 000000000000..7b01791b10b3
> > --- /dev/null
> > +++ b/Documentation/kho/bindings/memblock/reserve_mem.yaml
> > @@ -0,0 +1,41 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/memblock/reserve_mem.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Memblock reserved memory
> > +
> > +maintainers:
> > +  - Mike Rapoport <rppt at kernel.org>
> > +
> > +description: |
> > +  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.
> > +
> > +examples:
> > +  - |
> > +    reserve_mem {
> 
> Again, do not introduce own coding style.
> 
> I don't understand why do you need this in the first place. There is
> already reserved-memory block.

Because these regions are not "... designed for the special usage by
various device drivers" and should not be exclude by the operating system
from normal usage. 
 
> Best regards,
> Krzysztof

-- 
Sincerely yours,
Mike.