[PATCH] dt-bindings: chosen: document rng-seed property

[PATCH] dt-bindings: chosen: document rng-seed property

[Jason A. Donenfeld]

Document the /chosen/rng-seed property, which has existed for quite some
time but without an entry in this file.

Fixes: 428826f5358c ("fdt: add support for rng-seed")
Cc: Hsin-Yi Wang <hsinyi@chromium.org>
Cc: Kees Cook <keescook@chromium.org>
Cc: Rob Herring <robh@kernel.org>
Cc: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reported-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
---
 Documentation/devicetree/bindings/chosen.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
index 1cc3aa10dcb1..49b175e133b2 100644
--- a/Documentation/devicetree/bindings/chosen.txt
+++ b/Documentation/devicetree/bindings/chosen.txt
@@ -7,6 +7,21 @@ arguments. Data in the chosen node does not represent the hardware.
 
 The following properties are recognized:
 
+rng-seed
+--------
+
+This property is used to initialize the kernel's random number generator at
+the earliest possible opportunity, and will be credited if CONFIG_RANDOM_
+TRUST_BOOTLOADER is set. All hardware that has an opportunity to set this
+with high quality randomness is encouraged to do so. It is parsed as a byte
+array, which should be at least 32 bytes long:
+
+/ {
+	chosen {
+		rng-seed = <... random bytes ...>;
+	};
+};
+
 
 kaslr-seed
 -----------
-- 
2.35.1

Re: [PATCH] dt-bindings: chosen: document rng-seed property

[Hsin-Yi Wang]

On Mon, Jun 27, 2022 at 11:21 PM Jason A. Donenfeld <Jason@zx2c4.com> wrote:
>
> Document the /chosen/rng-seed property, which has existed for quite some
> time but without an entry in this file.
>
> Fixes: 428826f5358c ("fdt: add support for rng-seed")
> Cc: Hsin-Yi Wang <hsinyi@chromium.org>
> Cc: Kees Cook <keescook@chromium.org>
> Cc: Rob Herring <robh@kernel.org>
> Cc: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Reported-by: Geert Uytterhoeven <geert@linux-m68k.org>
> Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
> ---
It's currently documented in
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/chosen.yaml

https://lore.kernel.org/lkml/CAL_Jsq+uSdk9YNbUW35yjN3q8-3FDobrxHmBpy=4RKmCfnB0KQ@mail.gmail.com/


>  Documentation/devicetree/bindings/chosen.txt | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
> index 1cc3aa10dcb1..49b175e133b2 100644
> --- a/Documentation/devicetree/bindings/chosen.txt
> +++ b/Documentation/devicetree/bindings/chosen.txt
> @@ -7,6 +7,21 @@ arguments. Data in the chosen node does not represent the hardware.
>
>  The following properties are recognized:
>
> +rng-seed
> +--------
> +
> +This property is used to initialize the kernel's random number generator at
> +the earliest possible opportunity, and will be credited if CONFIG_RANDOM_
> +TRUST_BOOTLOADER is set. All hardware that has an opportunity to set this
> +with high quality randomness is encouraged to do so. It is parsed as a byte
> +array, which should be at least 32 bytes long:
> +
> +/ {
> +       chosen {
> +               rng-seed = <... random bytes ...>;
> +       };
> +};
> +
>
>  kaslr-seed
>  -----------
> --
> 2.35.1
>

Re: [PATCH] dt-bindings: chosen: document rng-seed property

[Jason A. Donenfeld]

Hi Hsin-Yi,

On Tue, Jun 28, 2022 at 11:39:38AM +0800, Hsin-Yi Wang wrote:
> On Mon, Jun 27, 2022 at 11:21 PM Jason A. Donenfeld <Jason@zx2c4.com> wrote:
> >
> > Document the /chosen/rng-seed property, which has existed for quite some
> > time but without an entry in this file.
> >
> > Fixes: 428826f5358c ("fdt: add support for rng-seed")
> > Cc: Hsin-Yi Wang <hsinyi@chromium.org>
> > Cc: Kees Cook <keescook@chromium.org>
> > Cc: Rob Herring <robh@kernel.org>
> > Cc: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> > Reported-by: Geert Uytterhoeven <geert@linux-m68k.org>
> > Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
> > ---
> It's currently documented in
> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/chosen.yaml
> 
> https://lore.kernel.org/lkml/CAL_Jsq+uSdk9YNbUW35yjN3q8-3FDobrxHmBpy=4RKmCfnB0KQ@mail.gmail.com/

Well, let's see. That email says:

> Already documented here[1]. I've been meaning to delete chosen.txt so
> that's a bit more obvious.
> 
> I realize it's a bit harder to find what's documented where. Long term
> we'd like to generate documentation from the schema and integrate as
> part of the spec. Short term, it would be quite trivial to make a 'am
> I documented' utility.

That sounds reasonable. But when was that email written? April 2, 2020.
That's 817 days ago.

So I call BS on this being a continued justification for rejecting this
patch (which apparently was submitted by Florian over two years ago
too). Rob clearly hasn't followed through. So please apply this patch so
that chosen.txt remains maintained.

Later if he moves forward with his plan, then no harm done, since the
file will be deleted anyway.

Sometimes it's best to reassess things based on the reality of the
situation, you know?

Jason

Re: [PATCH] dt-bindings: chosen: document rng-seed property

[Krzysztof Kozlowski]

On 28/06/2022 17:23, Jason A. Donenfeld wrote:
> Hi Hsin-Yi,
> 
> On Tue, Jun 28, 2022 at 11:39:38AM +0800, Hsin-Yi Wang wrote:
>> On Mon, Jun 27, 2022 at 11:21 PM Jason A. Donenfeld <Jason@zx2c4.com> wrote:
>>>
>>> Document the /chosen/rng-seed property, which has existed for quite some
>>> time but without an entry in this file.
>>>
>>> Fixes: 428826f5358c ("fdt: add support for rng-seed")
>>> Cc: Hsin-Yi Wang <hsinyi@chromium.org>
>>> Cc: Kees Cook <keescook@chromium.org>
>>> Cc: Rob Herring <robh@kernel.org>
>>> Cc: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>>> Reported-by: Geert Uytterhoeven <geert@linux-m68k.org>
>>> Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
>>> ---
>> It's currently documented in
>> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/chosen.yaml
>>
>> https://lore.kernel.org/lkml/CAL_Jsq+uSdk9YNbUW35yjN3q8-3FDobrxHmBpy=4RKmCfnB0KQ@mail.gmail.com/
> 
> Well, let's see. That email says:
> 
>> Already documented here[1]. I've been meaning to delete chosen.txt so
>> that's a bit more obvious.
>>
>> I realize it's a bit harder to find what's documented where. Long term
>> we'd like to generate documentation from the schema and integrate as
>> part of the spec. Short term, it would be quite trivial to make a 'am
>> I documented' utility.
> 
> That sounds reasonable. But when was that email written? April 2, 2020.
> That's 817 days ago.

817 days And the field is documented, so nothing to do here regarding
"rng-seed".


> So I call BS on this being a continued justification for rejecting this
> patch (which apparently was submitted by Florian over two years ago
> too). 

Because patch is not needed and is already done....

> Rob clearly hasn't followed through.

You got there link to repo, what do you need more to follow? Remove the
chosen.txt? Sure - submit a separate patch.

>  So please apply this patch so
> that chosen.txt remains maintained.

Instead submit a patch removing it. There is no particular point to
duplicate bindings and dt-schema is the core here, the main one.

> 
> Later if he moves forward with his plan, then no harm done, since the
> file will be deleted anyway.
> 
> Sometimes it's best to reassess things based on the reality of the
> situation, you know?


Best regards,
Krzysztof

Re: [PATCH] dt-bindings: chosen: document rng-seed property

[Jason A. Donenfeld]

Hi Krzysztof,

On Tue, Jun 28, 2022 at 05:26:45PM +0200, Krzysztof Kozlowski wrote:
> Instead submit a patch removing it. There is no particular point to
> duplicate bindings and dt-schema is the core here, the main one.

Okay, will do.

Jason

[PATCH] dt-bindings: chosen: remove

[Jason A. Donenfeld]

Apparently this is no longer maintained and undesired. Remove it.

Link: https://lore.kernel.org/lkml/c8dddfe6-6385-ed34-e789-9f845c8a32bd@linaro.org/
Link: https://lore.kernel.org/lkml/CAL_Jsq+uSdk9YNbUW35yjN3q8-3FDobrxHmBpy=4RKmCfnB0KQ@mail.gmail.com/
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
---
 Documentation/devicetree/bindings/chosen.txt | 137 -------------------
 1 file changed, 137 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/chosen.txt

diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
deleted file mode 100644
index 1cc3aa10dcb1..000000000000
--- a/Documentation/devicetree/bindings/chosen.txt
+++ /dev/null
@@ -1,137 +0,0 @@
-The chosen node
----------------
-
-The chosen node does not represent a real device, but serves as a place
-for passing data between firmware and the operating system, like boot
-arguments. Data in the chosen node does not represent the hardware.
-
-The following properties are recognized:
-
-
-kaslr-seed
------------
-
-This property is used when booting with CONFIG_RANDOMIZE_BASE as the
-entropy used to randomize the kernel image base address location. Since
-it is used directly, this value is intended only for KASLR, and should
-not be used for other purposes (as it may leak information about KASLR
-offsets). It is parsed as a u64 value, e.g.
-
-/ {
-	chosen {
-		kaslr-seed = <0xfeedbeef 0xc0def00d>;
-	};
-};
-
-Note that if this property is set from UEFI (or a bootloader in EFI
-mode) when EFI_RNG_PROTOCOL is supported, it will be overwritten by
-the Linux EFI stub (which will populate the property itself, using
-EFI_RNG_PROTOCOL).
-
-stdout-path
------------
-
-Device trees may specify the device to be used for boot console output
-with a stdout-path property under /chosen, as described in the Devicetree
-Specification, e.g.
-
-/ {
-	chosen {
-		stdout-path = "/serial@f00:115200";
-	};
-
-	serial@f00 {
-		compatible = "vendor,some-uart";
-		reg = <0xf00 0x10>;
-	};
-};
-
-If the character ":" is present in the value, this terminates the path.
-The meaning of any characters following the ":" is device-specific, and
-must be specified in the relevant binding documentation.
-
-For UART devices, the preferred binding is a string in the form:
-
-	<baud>{<parity>{<bits>{<flow>}}}
-
-where
-
-	baud	- baud rate in decimal
-	parity	- 'n' (none), 'o', (odd) or 'e' (even)
-	bits	- number of data bits
-	flow	- 'r' (rts)
-
-For example: 115200n8r
-
-Implementation note: Linux will look for the property "linux,stdout-path" or
-on PowerPC "stdout" if "stdout-path" is not found.  However, the
-"linux,stdout-path" and "stdout" properties are deprecated. New platforms
-should only use the "stdout-path" property.
-
-linux,booted-from-kexec
------------------------
-
-This property is set (currently only on PowerPC, and only needed on
-book3e) by some versions of kexec-tools to tell the new kernel that it
-is being booted by kexec, as the booting environment may differ (e.g.
-a different secondary CPU release mechanism)
-
-linux,usable-memory-range
--------------------------
-
-This property holds a base address and size, describing a limited region in
-which memory may be considered available for use by the kernel. Memory outside
-of this range is not available for use.
-
-This property describes a limitation: memory within this range is only
-valid when also described through another mechanism that the kernel
-would otherwise use to determine available memory (e.g. memory nodes
-or the EFI memory map). Valid memory may be sparse within the range.
-e.g.
-
-/ {
-	chosen {
-		linux,usable-memory-range = <0x9 0xf0000000 0x0 0x10000000>;
-	};
-};
-
-The main usage is for crash dump kernel to identify its own usable
-memory and exclude, at its boot time, any other memory areas that are
-part of the panicked kernel's memory.
-
-While this property does not represent a real hardware, the address
-and the size are expressed in #address-cells and #size-cells,
-respectively, of the root node.
-
-linux,elfcorehdr
-----------------
-
-This property holds the memory range, the address and the size, of the elf
-core header which mainly describes the panicked kernel's memory layout as
-PT_LOAD segments of elf format.
-e.g.
-
-/ {
-	chosen {
-		linux,elfcorehdr = <0x9 0xfffff000 0x0 0x800>;
-	};
-};
-
-While this property does not represent a real hardware, the address
-and the size are expressed in #address-cells and #size-cells,
-respectively, of the root node.
-
-linux,initrd-start and linux,initrd-end
----------------------------------------
-
-These properties hold the physical start and end address of an initrd that's
-loaded by the bootloader. Note that linux,initrd-start is inclusive, but
-linux,initrd-end is exclusive.
-e.g.
-
-/ {
-	chosen {
-		linux,initrd-start = <0x82000000>;
-		linux,initrd-end = <0x82800000>;
-	};
-};
-- 
2.35.1

Re: [PATCH] dt-bindings: chosen: remove

[Rob Herring]

On Tue, 28 Jun 2022 17:33:54 +0200, Jason A. Donenfeld wrote:
> Apparently this is no longer maintained and undesired. Remove it.
> 
> Link: https://lore.kernel.org/lkml/c8dddfe6-6385-ed34-e789-9f845c8a32bd@linaro.org/
> Link: https://lore.kernel.org/lkml/CAL_Jsq+uSdk9YNbUW35yjN3q8-3FDobrxHmBpy=4RKmCfnB0KQ@mail.gmail.com/
> Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
> ---
>  Documentation/devicetree/bindings/chosen.txt | 137 -------------------
>  1 file changed, 137 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/chosen.txt
> 

Applied, thanks!