[PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Chen-Yu Tsai]

Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
insert device specific properties into the coreboot firmware node when
there are valid values.

Document these properties in the binding.

Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
---
 Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt
index 4c955703cea8..0d04ea482aa9 100644
--- a/Documentation/devicetree/bindings/firmware/coreboot.txt
+++ b/Documentation/devicetree/bindings/firmware/coreboot.txt
@@ -21,6 +21,15 @@ Required properties:
 	0xc0389481 that resides in the topmost 8 bytes of the area.
 	See coreboot's src/include/imd.h for details.
 
+Optional properties:
+- board-id: Contains the board revision number.
+- ram-code: Contains the board's DRAM configuration type.
+- sku-id: Contains the device variant SKU ID.
+- fw-config: Contains the device variant FW config value.
+
+The optional properties are only populated if the values parsed by coreboot
+are valid.
+
 Example:
 	firmware {
 		ranges;
-- 
2.52.0.rc1.455.g30608eb744-goog

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Krzysztof Kozlowski]

On 19/11/2025 08:11, Chen-Yu Tsai wrote:
> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
> insert device specific properties into the coreboot firmware node when
> there are valid values.
> 
> Document these properties in the binding.
> 
> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> ---
>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 

TXT files cannot receive new properties. You need to first convert to DT
schema.

Best regards,
Krzysztof

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Chen-Yu Tsai]

On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
> > Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
> > insert device specific properties into the coreboot firmware node when
> > there are valid values.
> >
> > Document these properties in the binding.
> >
> > Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> > ---
> >  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> >
>
> TXT files cannot receive new properties. You need to first convert to DT
> schema.

OK. Let me look into this.

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Krzysztof Kozlowski]

On 19/11/2025 08:32, Chen-Yu Tsai wrote:
> On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
>>> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
>>> insert device specific properties into the coreboot firmware node when
>>> there are valid values.
>>>
>>> Document these properties in the binding.
>>>
>>> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
>>> ---
>>>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
>>>  1 file changed, 9 insertions(+)
>>>
>>
>> TXT files cannot receive new properties. You need to first convert to DT
>> schema.
> 
> OK. Let me look into this.

After the conversion you will hit another problem - you need vendor
prefixes for these, because only generic properties can come without
them. Otherwise (without vendor prefix) these would define the type for
all other bindings, which probably is not what we want.

Best regards,
Krzysztof

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Chen-Yu Tsai]

On Wed, Nov 19, 2025 at 4:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 19/11/2025 08:32, Chen-Yu Tsai wrote:
> > On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >>
> >> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
> >>> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
> >>> insert device specific properties into the coreboot firmware node when
> >>> there are valid values.
> >>>
> >>> Document these properties in the binding.
> >>>
> >>> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> >>> ---
> >>>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
> >>>  1 file changed, 9 insertions(+)
> >>>
> >>
> >> TXT files cannot receive new properties. You need to first convert to DT
> >> schema.
> >
> > OK. Let me look into this.
>
> After the conversion you will hit another problem - you need vendor
> prefixes for these, because only generic properties can come without
> them. Otherwise (without vendor prefix) these would define the type for
> all other bindings, which probably is not what we want.

I understand the concern. But given it's specifically under the
/firmware/coreboot node, which is inserted by coreboot, doesn't that
already serve as a namespace or vendor prefix?

FWIW the ship has already sailed for naming. The first three properties
were added to depthcharge [1] and coreboot [2] in 2018. The last property
was added to depthcharge in 2023 [3]. That is what has shipped in immutable
firmware on ARM-based Chromebooks since the RK3399 days. The coreboot
change was presumably added for other devices.

This change only serves to document what the firmware already provides.
Whether they should be grandfathered in or not doesn't change what the
firmware already does; it just makes it more well known. It's not going
to have any effect on validation either, as the properties are supposed
to be inserted by the bootloader, not added statically to dts files.

Presumably we can update the code to use a new name, but we still have
to live with the old names for up to 10 years.


ChenYu

[1] https://crrev.com/c/1028728
[2] https://review.coreboot.org/c/coreboot/+/28104
[3] https://crrev.com/c/4975217

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Krzysztof Kozlowski]

On 19/11/2025 09:54, Chen-Yu Tsai wrote:
> On Wed, Nov 19, 2025 at 4:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> On 19/11/2025 08:32, Chen-Yu Tsai wrote:
>>> On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>>>
>>>> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
>>>>> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
>>>>> insert device specific properties into the coreboot firmware node when
>>>>> there are valid values.
>>>>>
>>>>> Document these properties in the binding.
>>>>>
>>>>> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
>>>>> ---
>>>>>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
>>>>>  1 file changed, 9 insertions(+)
>>>>>
>>>>
>>>> TXT files cannot receive new properties. You need to first convert to DT
>>>> schema.
>>>
>>> OK. Let me look into this.
>>
>> After the conversion you will hit another problem - you need vendor
>> prefixes for these, because only generic properties can come without
>> them. Otherwise (without vendor prefix) these would define the type for
>> all other bindings, which probably is not what we want.
> 
> I understand the concern. But given it's specifically under the
> /firmware/coreboot node, which is inserted by coreboot, doesn't that
> already serve as a namespace or vendor prefix?

Unfortunately not or not completely. Properties have single type
globally (with exceptions). This means whatever you write here for
board-id will affect every possible future board-id property.

> 
> FWIW the ship has already sailed for naming. The first three properties
> were added to depthcharge [1] and coreboot [2] in 2018. The last property
> was added to depthcharge in 2023 [3]. That is what has shipped in immutable
> firmware on ARM-based Chromebooks since the RK3399 days. The coreboot
> change was presumably added for other devices.
> 
> This change only serves to document what the firmware already provides.
> Whether they should be grandfathered in or not doesn't change what the
> firmware already does; it just makes it more well known. It's not going
> to have any effect on validation either, as the properties are supposed
> to be inserted by the bootloader, not added statically to dts files.

If you convince Rob then it's fine, but I don't want to accept
downstream solutions just because they exist. This opens the door for
every vendor to implement what they want and later ask for forgiveness
("oh it is already there and we cannot change shipped devices"). I mean,
this was fine back 2010, but that was 15 years ago.

Best regards,
Krzysztof

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Chen-Yu Tsai]

On Wed, Nov 19, 2025 at 5:26 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 19/11/2025 09:54, Chen-Yu Tsai wrote:
> > On Wed, Nov 19, 2025 at 4:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >>
> >> On 19/11/2025 08:32, Chen-Yu Tsai wrote:
> >>> On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >>>>
> >>>> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
> >>>>> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
> >>>>> insert device specific properties into the coreboot firmware node when
> >>>>> there are valid values.
> >>>>>
> >>>>> Document these properties in the binding.
> >>>>>
> >>>>> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
> >>>>> ---
> >>>>>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
> >>>>>  1 file changed, 9 insertions(+)
> >>>>>
> >>>>
> >>>> TXT files cannot receive new properties. You need to first convert to DT
> >>>> schema.
> >>>
> >>> OK. Let me look into this.
> >>
> >> After the conversion you will hit another problem - you need vendor
> >> prefixes for these, because only generic properties can come without
> >> them. Otherwise (without vendor prefix) these would define the type for
> >> all other bindings, which probably is not what we want.
> >
> > I understand the concern. But given it's specifically under the
> > /firmware/coreboot node, which is inserted by coreboot, doesn't that
> > already serve as a namespace or vendor prefix?
>
> Unfortunately not or not completely. Properties have single type
> globally (with exceptions). This means whatever you write here for
> board-id will affect every possible future board-id property.

IIUC you mean it applies to every "board-id" property that is under
a node that matches the compatible "coreboot"?

Is there any way to limit the match also by path (and not just node name,
which I know is possible)? If we can limit the scope then maybe it works
out?

Or perhaps you are worried that some other new binding with a broader
scope defines "board-id" and thus conflicts with this one?

> >
> > FWIW the ship has already sailed for naming. The first three properties
> > were added to depthcharge [1] and coreboot [2] in 2018. The last property
> > was added to depthcharge in 2023 [3]. That is what has shipped in immutable
> > firmware on ARM-based Chromebooks since the RK3399 days. The coreboot
> > change was presumably added for other devices.
> >
> > This change only serves to document what the firmware already provides.
> > Whether they should be grandfathered in or not doesn't change what the
> > firmware already does; it just makes it more well known. It's not going
> > to have any effect on validation either, as the properties are supposed
> > to be inserted by the bootloader, not added statically to dts files.
>
> If you convince Rob then it's fine, but I don't want to accept
> downstream solutions just because they exist. This opens the door for
> every vendor to implement what they want and later ask for forgiveness
> ("oh it is already there and we cannot change shipped devices"). I mean,
> this was fine back 2010, but that was 15 years ago.

I completely understand, and yes this does have that feel to it.
But FWIW the change is in upstream coreboot.


Thanks
ChenYu

Re: [PATCH] dt-bindings: firmware: coreboot: Document optional device specific properties

[Krzysztof Kozlowski]

On 19/11/2025 10:36, Chen-Yu Tsai wrote:
> On Wed, Nov 19, 2025 at 5:26 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> On 19/11/2025 09:54, Chen-Yu Tsai wrote:
>>> On Wed, Nov 19, 2025 at 4:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>>>
>>>> On 19/11/2025 08:32, Chen-Yu Tsai wrote:
>>>>> On Wed, Nov 19, 2025 at 3:13 PM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>>>>>
>>>>>> On 19/11/2025 08:11, Chen-Yu Tsai wrote:
>>>>>>> Coreboot, or the ChromeOS second stage bootloader, depthcharge, will
>>>>>>> insert device specific properties into the coreboot firmware node when
>>>>>>> there are valid values.
>>>>>>>
>>>>>>> Document these properties in the binding.
>>>>>>>
>>>>>>> Signed-off-by: Chen-Yu Tsai <wenst@chromium.org>
>>>>>>> ---
>>>>>>>  Documentation/devicetree/bindings/firmware/coreboot.txt | 9 +++++++++
>>>>>>>  1 file changed, 9 insertions(+)
>>>>>>>
>>>>>>
>>>>>> TXT files cannot receive new properties. You need to first convert to DT
>>>>>> schema.
>>>>>
>>>>> OK. Let me look into this.
>>>>
>>>> After the conversion you will hit another problem - you need vendor
>>>> prefixes for these, because only generic properties can come without
>>>> them. Otherwise (without vendor prefix) these would define the type for
>>>> all other bindings, which probably is not what we want.
>>>
>>> I understand the concern. But given it's specifically under the
>>> /firmware/coreboot node, which is inserted by coreboot, doesn't that
>>> already serve as a namespace or vendor prefix?
>>
>> Unfortunately not or not completely. Properties have single type
>> globally (with exceptions). This means whatever you write here for
>> board-id will affect every possible future board-id property.
> 
> IIUC you mean it applies to every "board-id" property that is under
> a node that matches the compatible "coreboot"?

Type applies to every board-id property.

> 
> Is there any way to limit the match also by path (and not just node name,
> which I know is possible)? If we can limit the scope then maybe it works
> out?
> 
> Or perhaps you are worried that some other new binding with a broader
> scope defines "board-id" and thus conflicts with this one?

Yes. You basically define now type for all "board-id"s.

> 
>>>
>>> FWIW the ship has already sailed for naming. The first three properties
>>> were added to depthcharge [1] and coreboot [2] in 2018. The last property
>>> was added to depthcharge in 2023 [3]. That is what has shipped in immutable
>>> firmware on ARM-based Chromebooks since the RK3399 days. The coreboot
>>> change was presumably added for other devices.
>>>
>>> This change only serves to document what the firmware already provides.
>>> Whether they should be grandfathered in or not doesn't change what the
>>> firmware already does; it just makes it more well known. It's not going
>>> to have any effect on validation either, as the properties are supposed
>>> to be inserted by the bootloader, not added statically to dts files.
>>
>> If you convince Rob then it's fine, but I don't want to accept
>> downstream solutions just because they exist. This opens the door for
>> every vendor to implement what they want and later ask for forgiveness
>> ("oh it is already there and we cannot change shipped devices"). I mean,
>> this was fine back 2010, but that was 15 years ago.
> 
> I completely understand, and yes this does have that feel to it.
> But FWIW the change is in upstream coreboot.

Oh, that is something coreboot should fix - I went to their repo and:

git grep board-id

and there are no bindings (no ABI documentation), which could imply they
use Linux bindings (great!) but then this should have been sent to DT
Linux list for review and included in the kernel bindings.

I understand this is a different case than vendor doing whatever they
want in downstream, but still it is a similar one - "project is doing
whatever they want inside" - and it does not make me happy.


Best regards,
Krzysztof