Convert the existing text binding to YAML.

The description has been change to reflect the possibility of coreboot
inserting the node itself.

The example has been modified to compile and pass validation without
any errors. A comment was added to note what the firmware actually
emits.

Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
---
 .../devicetree/bindings/firmware/coreboot.txt | 33 ----------
 .../bindings/firmware/coreboot.yaml           | 60 +++++++++++++++++++
 2 files changed, 60 insertions(+), 33 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/firmware/coreboot.txt
 create mode 100644 Documentation/devicetree/bindings/firmware/coreboot.yaml

diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt
deleted file mode 100644
index 4c955703cea8..000000000000
--- a/Documentation/devicetree/bindings/firmware/coreboot.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-COREBOOT firmware information
-
-The device tree node to communicate the location of coreboot's memory-resident
-bookkeeping structures to the kernel. Since coreboot itself cannot boot a
-device-tree-based kernel (yet), this node needs to be inserted by a
-second-stage bootloader (a coreboot "payload").
-
-Required properties:
- - compatible: Should be "coreboot"
- - reg: Address and length of the following two memory regions, in order:
-	1.) The coreboot table. This is a list of variable-sized descriptors
-	that contain various compile- and run-time generated firmware
-	parameters. It is identified by the magic string "LBIO" in its first
-	four bytes.
-	See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
-	details.
-	2.) The CBMEM area. This is a downward-growing memory region used by
-	coreboot to dynamically allocate data structures that remain resident.
-	It may or may not include the coreboot table as one of its members. It
-	is identified by a root node descriptor with the magic number
-	0xc0389481 that resides in the topmost 8 bytes of the area.
-	See coreboot's src/include/imd.h for details.
-
-Example:
-	firmware {
-		ranges;
-
-		coreboot {
-			compatible = "coreboot";
-			reg = <0xfdfea000 0x264>,
-			      <0xfdfea000 0x16000>;
-		}
-	};
diff --git a/Documentation/devicetree/bindings/firmware/coreboot.yaml b/Documentation/devicetree/bindings/firmware/coreboot.yaml
new file mode 100644
index 000000000000..568afd1abb92
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/coreboot.yaml
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/coreboot.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: COREBOOT firmware information
+
+maintainers:
+  - Julius Werner <jwerner@chromium.org>
+
+description:
+  The device tree node to communicate the location of coreboot's
+  memory-resident bookkeeping structures to the kernel. Coreboot's
+  FIT image payload can insert the node into the device tree. If a
+  second-stage bootloader (a coreboot "payload") is used, then it
+  is responsible for inserting the node.
+
+properties:
+  compatible:
+    const: coreboot
+  reg:
+    description: Address and length of the following two memory regions
+    items:
+      - description:
+          The coreboot table. This is a list of variable-sized descriptors
+          that contain various compile- and run-time generated firmware
+          parameters. It is identified by the magic string "LBIO" in its first
+          four bytes.
+
+          See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
+          details.
+      - description:
+          The CBMEM area. This is a downward-growing memory region used by
+          coreboot to dynamically allocate data structures that remain resident.
+          It may or may not include the coreboot table as one of its members. It
+          is identified by a root node descriptor with the magic number
+          0xc0389481 that resides in the topmost 8 bytes of the area.
+
+          See coreboot's src/include/imd.h for details.
+
+required:
+  - compatible
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    firmware {
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges;
+
+        /* Firmware actually emits "coreboot" node without unit name */
+        coreboot@fdfea000 {
+            compatible = "coreboot";
+            reg = <0xfdfea000 0x264>, <0xfdfea000 0x16000>;
+        };
+    };
-- 
2.52.0.460.gd25c4c69ec-goog

On Tue, Nov 25, 2025 at 02:48:49PM +0800, Chen-Yu Tsai wrote:
> Convert the existing text binding to YAML.
> 
> The description has been change to reflect the possibility of coreboot
> inserting the node itself.
> 
> The example has been modified to compile and pass validation without
> any errors. A comment was added to note what the firmware actually
> emits.
> 
> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> ---
>  .../devicetree/bindings/firmware/coreboot.txt | 33 ----------
>  .../bindings/firmware/coreboot.yaml           | 60 +++++++++++++++++++
>  2 files changed, 60 insertions(+), 33 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/firmware/coreboot.txt
>  create mode 100644 Documentation/devicetree/bindings/firmware/coreboot.yaml
> 
> diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt
> deleted file mode 100644
> index 4c955703cea8..000000000000
> --- a/Documentation/devicetree/bindings/firmware/coreboot.txt
> +++ /dev/null
> @@ -1,33 +0,0 @@
> -COREBOOT firmware information
> -
> -The device tree node to communicate the location of coreboot's memory-resident
> -bookkeeping structures to the kernel. Since coreboot itself cannot boot a
> -device-tree-based kernel (yet), this node needs to be inserted by a
> -second-stage bootloader (a coreboot "payload").
> -
> -Required properties:
> - - compatible: Should be "coreboot"
> - - reg: Address and length of the following two memory regions, in order:
> -	1.) The coreboot table. This is a list of variable-sized descriptors
> -	that contain various compile- and run-time generated firmware
> -	parameters. It is identified by the magic string "LBIO" in its first
> -	four bytes.
> -	See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
> -	details.
> -	2.) The CBMEM area. This is a downward-growing memory region used by
> -	coreboot to dynamically allocate data structures that remain resident.
> -	It may or may not include the coreboot table as one of its members. It
> -	is identified by a root node descriptor with the magic number
> -	0xc0389481 that resides in the topmost 8 bytes of the area.
> -	See coreboot's src/include/imd.h for details.
> -
> -Example:
> -	firmware {
> -		ranges;
> -
> -		coreboot {
> -			compatible = "coreboot";
> -			reg = <0xfdfea000 0x264>,
> -			      <0xfdfea000 0x16000>;
> -		}
> -	};
> diff --git a/Documentation/devicetree/bindings/firmware/coreboot.yaml b/Documentation/devicetree/bindings/firmware/coreboot.yaml
> new file mode 100644
> index 000000000000..568afd1abb92
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/firmware/coreboot.yaml
> @@ -0,0 +1,60 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/firmware/coreboot.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: COREBOOT firmware information

Coreboot

> +
> +maintainers:
> +  - Julius Werner <jwerner@chromium.org>
> +
> +description:
> +  The device tree node to communicate the location of coreboot's
> +  memory-resident bookkeeping structures to the kernel. Coreboot's
> +  FIT image payload can insert the node into the device tree. If a
> +  second-stage bootloader (a coreboot "payload") is used, then it
> +  is responsible for inserting the node.
> +
> +properties:
> +  compatible:
> +    const: coreboot

Blank line (it is always here, there is no example without, which makes
me wonder which file you took as starting point)

> +  reg:
> +    description: Address and length of the following two memory regions

Drop description, redundant.

> +    items:
> +      - description:
> +          The coreboot table. This is a list of variable-sized descriptors
> +          that contain various compile- and run-time generated firmware
> +          parameters. It is identified by the magic string "LBIO" in its first
> +          four bytes.
> +
> +          See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
> +          details.
> +      - description:
> +          The CBMEM area. This is a downward-growing memory region used by
> +          coreboot to dynamically allocate data structures that remain resident.
> +          It may or may not include the coreboot table as one of its members. It
> +          is identified by a root node descriptor with the magic number
> +          0xc0389481 that resides in the topmost 8 bytes of the area.
> +
> +          See coreboot's src/include/imd.h for details.
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    firmware {
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges;
> +
> +        /* Firmware actually emits "coreboot" node without unit name */
> +        coreboot@fdfea000 {
> +            compatible = "coreboot";
> +            reg = <0xfdfea000 0x264>, <0xfdfea000 0x16000>;

That's the same address in both places, so the same one entry. You need
two distinctive addresses or binding needs changes to have only one item
as well.

Best regards,
Krzysztof

On Tue, Nov 25, 2025 at 6:08 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On Tue, Nov 25, 2025 at 02:48:49PM +0800, Chen-Yu Tsai wrote:
> > Convert the existing text binding to YAML.
> >
> > The description has been change to reflect the possibility of coreboot
> > inserting the node itself.
> >
> > The example has been modified to compile and pass validation without
> > any errors. A comment was added to note what the firmware actually
> > emits.
> >
> > Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> > ---
> >  .../devicetree/bindings/firmware/coreboot.txt | 33 ----------
> >  .../bindings/firmware/coreboot.yaml           | 60 +++++++++++++++++++
> >  2 files changed, 60 insertions(+), 33 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/firmware/coreboot.txt
> >  create mode 100644 Documentation/devicetree/bindings/firmware/coreboot.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt
> > deleted file mode 100644
> > index 4c955703cea8..000000000000
> > --- a/Documentation/devicetree/bindings/firmware/coreboot.txt
> > +++ /dev/null
> > @@ -1,33 +0,0 @@
> > -COREBOOT firmware information
> > -
> > -The device tree node to communicate the location of coreboot's memory-resident
> > -bookkeeping structures to the kernel. Since coreboot itself cannot boot a
> > -device-tree-based kernel (yet), this node needs to be inserted by a
> > -second-stage bootloader (a coreboot "payload").
> > -
> > -Required properties:
> > - - compatible: Should be "coreboot"
> > - - reg: Address and length of the following two memory regions, in order:
> > -     1.) The coreboot table. This is a list of variable-sized descriptors
> > -     that contain various compile- and run-time generated firmware
> > -     parameters. It is identified by the magic string "LBIO" in its first
> > -     four bytes.
> > -     See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
> > -     details.
> > -     2.) The CBMEM area. This is a downward-growing memory region used by
> > -     coreboot to dynamically allocate data structures that remain resident.
> > -     It may or may not include the coreboot table as one of its members. It
> > -     is identified by a root node descriptor with the magic number
> > -     0xc0389481 that resides in the topmost 8 bytes of the area.
> > -     See coreboot's src/include/imd.h for details.
> > -
> > -Example:
> > -     firmware {
> > -             ranges;
> > -
> > -             coreboot {
> > -                     compatible = "coreboot";
> > -                     reg = <0xfdfea000 0x264>,
> > -                           <0xfdfea000 0x16000>;
> > -             }
> > -     };
> > diff --git a/Documentation/devicetree/bindings/firmware/coreboot.yaml b/Documentation/devicetree/bindings/firmware/coreboot.yaml
> > new file mode 100644
> > index 000000000000..568afd1abb92
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/firmware/coreboot.yaml
> > @@ -0,0 +1,60 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/firmware/coreboot.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: COREBOOT firmware information
>
> Coreboot

OK. Side note, coreboot is stylized in all lowercase letters.
Should I follow that or just use standard English rules?

> > +
> > +maintainers:
> > +  - Julius Werner <jwerner@chromium.org>
> > +
> > +description:
> > +  The device tree node to communicate the location of coreboot's
> > +  memory-resident bookkeeping structures to the kernel. Coreboot's
> > +  FIT image payload can insert the node into the device tree. If a
> > +  second-stage bootloader (a coreboot "payload") is used, then it
> > +  is responsible for inserting the node.
> > +
> > +properties:
> > +  compatible:
> > +    const: coreboot
>
> Blank line (it is always here, there is no example without, which makes
> me wonder which file you took as starting point)

I actually converted the existing text file directly, copying
boilerplate, i.e. the top few lines, from another file.

> > +  reg:
> > +    description: Address and length of the following two memory regions
>
> Drop description, redundant.

Ack.

> > +    items:
> > +      - description:
> > +          The coreboot table. This is a list of variable-sized descriptors
> > +          that contain various compile- and run-time generated firmware
> > +          parameters. It is identified by the magic string "LBIO" in its first
> > +          four bytes.
> > +
> > +          See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
> > +          details.
> > +      - description:
> > +          The CBMEM area. This is a downward-growing memory region used by
> > +          coreboot to dynamically allocate data structures that remain resident.
> > +          It may or may not include the coreboot table as one of its members. It
> > +          is identified by a root node descriptor with the magic number
> > +          0xc0389481 that resides in the topmost 8 bytes of the area.
> > +
> > +          See coreboot's src/include/imd.h for details.
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    firmware {
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        ranges;
> > +
> > +        /* Firmware actually emits "coreboot" node without unit name */
> > +        coreboot@fdfea000 {
> > +            compatible = "coreboot";
> > +            reg = <0xfdfea000 0x264>, <0xfdfea000 0x16000>;
>
> That's the same address in both places, so the same one entry. You need
> two distinctive addresses or binding needs changes to have only one item
> as well.

The description does mention that the latter block can include the
former. It's really up to the firmware. If you like I can include
two examples to cover both cases.


ChenYu

On 25/11/2025 11:41, Chen-Yu Tsai wrote:
>>> diff --git a/Documentation/devicetree/bindings/firmware/coreboot.yaml b/Documentation/devicetree/bindings/firmware/coreboot.yaml
>>> new file mode 100644
>>> index 000000000000..568afd1abb92
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/firmware/coreboot.yaml
>>> @@ -0,0 +1,60 @@
>>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>>> +%YAML 1.2
>>> +---
>>> +$id: http://devicetree.org/schemas/firmware/coreboot.yaml#
>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>> +
>>> +title: COREBOOT firmware information
>>
>> Coreboot
> 
> OK. Side note, coreboot is stylized in all lowercase letters.
> Should I follow that or just use standard English rules?

Just choose one. Here was capitals, but in description not. Preferably
Coreboot or coreboot


> 
>>> +
>>> +maintainers:
>>> +  - Julius Werner <jwerner@chromium.org>
>>> +
>>> +description:
>>> +  The device tree node to communicate the location of coreboot's
>>> +  memory-resident bookkeeping structures to the kernel. Coreboot's
>>> +  FIT image payload can insert the node into the device tree. If a
>>> +  second-stage bootloader (a coreboot "payload") is used, then it
>>> +  is responsible for inserting the node.
>>> +
>>> +properties:
>>> +  compatible:
>>> +    const: coreboot
>>
>> Blank line (it is always here, there is no example without, which makes
>> me wonder which file you took as starting point)
> 
> I actually converted the existing text file directly, copying
> boilerplate, i.e. the top few lines, from another file.
> 
>>> +  reg:
>>> +    description: Address and length of the following two memory regions
>>
>> Drop description, redundant.
> 
> Ack.
> 
>>> +    items:
>>> +      - description:
>>> +          The coreboot table. This is a list of variable-sized descriptors
>>> +          that contain various compile- and run-time generated firmware
>>> +          parameters. It is identified by the magic string "LBIO" in its first
>>> +          four bytes.
>>> +
>>> +          See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
>>> +          details.
>>> +      - description:
>>> +          The CBMEM area. This is a downward-growing memory region used by
>>> +          coreboot to dynamically allocate data structures that remain resident.
>>> +          It may or may not include the coreboot table as one of its members. It
>>> +          is identified by a root node descriptor with the magic number
>>> +          0xc0389481 that resides in the topmost 8 bytes of the area.
>>> +
>>> +          See coreboot's src/include/imd.h for details.
>>> +
>>> +required:
>>> +  - compatible
>>> +  - reg
>>> +
>>> +additionalProperties: false
>>> +
>>> +examples:
>>> +  - |
>>> +    firmware {
>>> +        #address-cells = <1>;
>>> +        #size-cells = <1>;
>>> +        ranges;
>>> +
>>> +        /* Firmware actually emits "coreboot" node without unit name */
>>> +        coreboot@fdfea000 {
>>> +            compatible = "coreboot";
>>> +            reg = <0xfdfea000 0x264>, <0xfdfea000 0x16000>;
>>
>> That's the same address in both places, so the same one entry. You need
>> two distinctive addresses or binding needs changes to have only one item
>> as well.
> 
> The description does mention that the latter block can include the
> former. It's really up to the firmware. If you like I can include
> two examples to cover both cases.

Lovely, I don't think we should accept growing this binding at all until
coreboot fixes this mess (duplicated entry and missing unit address).


Best regards,
Krzysztof

> >>> +title: COREBOOT firmware information
> >>
> >> Coreboot
> >
> > OK. Side note, coreboot is stylized in all lowercase letters.
> > Should I follow that or just use standard English rules?
>
> Just choose one. Here was capitals, but in description not. Preferably
> Coreboot or coreboot

coreboot should always be written all lowercase, even at the start of
a sentence (i.e. "...bookkeeping structures to the kernel. coreboot's
FIT image payload can insert..."). Not sure why I wrote it in caps in
the heading here, that was never really correct, not even back then.

> >>> +  The device tree node to communicate the location of coreboot's
> >>> +  memory-resident bookkeeping structures to the kernel. Coreboot's
> >>> +  FIT image payload can insert the node into the device tree. If a

nit: Not really sure what "coreboot's FIT image payload" is supposed
to be? Do you mean "coreboot's FIT image code"? (The file is just
called fit_payload.c because the FIT image takes the place of the
usual coreboot payload, but the code that does the device tree
stitching itself is still coreboot proper.) To make the point you're
trying to make here, why not just say: "This node may be inserted
either by coreboot itself or by a second-stage bootloader (a coreboot
"payload"), depending on where the kernel device tree is finalized."

> >>> +        /* Firmware actually emits "coreboot" node without unit name */
> >>> +        coreboot@fdfea000 {
> >>> +            compatible = "coreboot";
> >>> +            reg = <0xfdfea000 0x264>, <0xfdfea000 0x16000>;
> >>
> >> That's the same address in both places, so the same one entry. You need
> >> two distinctive addresses or binding needs changes to have only one item
> >> as well.
> >
> > The description does mention that the latter block can include the
> > former. It's really up to the firmware. If you like I can include
> > two examples to cover both cases.
>
> Lovely, I don't think we should accept growing this binding at all until
> coreboot fixes this mess (duplicated entry and missing unit address).

As Chen-Yu said, the second region usually contains the first. It is
possible (in fact tends to be common on many platforms, because the
coreboot table is often the last region added to the downward-growing
CBMEM) for the start addresses to match. That is not an error or a
"duplicate", they're still describing two different things.

We can start adding the @<address> part if you want but it hasn't
really been relevant in practice since there will always be only one
coreboot in the system anyway. As far as I understand, node names are
just informational in the device tree and the compatible string is
what identifies the actual binding. Since bootloaders on older
platforms often don't get updated, it is probably still a good idea to
 mention that in a comment like Chen-Yu did here even if we change it.