Skip to contentSkip to conversation

dt-bindings: chosen: document rng-seed property

PATCH In review Jason A. Donenfeld 4 participants 7 messages Jun 27, 2022 – Jul 1, 2022 Device tree bindings

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 dt-bindings: chosen: document rng-seed property

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 <[email protected]>
Cc Kees Cook <[email protected]>
Cc Rob Herring <[email protected]>
Cc Krzysztof Kozlowski <[email protected]>
---
 Documentation/devicetree/bindings/chosen.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
Documentation/devicetree/bindings/chosen.txt +15 -0
index 1cc3aa10dcb1..49b175e133b2 100644
@@ -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
 -----------
Signature · 1 line
2.35.1
#1 lore raw
Quoted 4 lines · Jason A. Donenfeld

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

Quoted 8 lines
Fixes 428826f5358c ("fdt: add support for rng-seed")
Cc Hsin-Yi Wang <[email protected]>
Cc Kees Cook <[email protected]>
Cc Rob Herring <[email protected]>
Cc Krzysztof Kozlowski <[email protected]>

---

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/

Quoted 32 lines
 Documentation/devicetree/bindings/chosen.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
Documentation/devicetree/bindings/chosen.txt +15 -1
index 1cc3aa10dcb1..49b175e133b2 100644
@@ -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

#2 lore raw

Hi Hsin-Yi,

Quoted 13 lines · Hsin-Yi Wang
Quoted 4 lines · Jason A. Donenfeld

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

Quoted 8 lines
Fixes 428826f5358c ("fdt: add support for rng-seed")
Cc Hsin-Yi Wang <[email protected]>
Cc Kees Cook <[email protected]>
Cc Rob Herring <[email protected]>
Cc Krzysztof Kozlowski <[email protected]>

---

Quoted 4 lines

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:

Quoted 7 lines

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

#3 lore raw
Quoted 26 lines · Jason A. Donenfeld

Hi Hsin-Yi,

Quoted 13 lines · Hsin-Yi Wang
Quoted 4 lines · Jason A. Donenfeld

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

Quoted 8 lines
Fixes 428826f5358c ("fdt: add support for rng-seed")
Cc Hsin-Yi Wang <[email protected]>
Cc Kees Cook <[email protected]>
Cc Rob Herring <[email protected]>
Cc Krzysztof Kozlowski <[email protected]>

---

Quoted 4 lines

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:

Quoted 3 lines

Already documented here[1]. I've been meaning to delete chosen.txt so that's a bit more obvious.

Quoted 7 lines
Quoted 4 lines

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

Quoted 3 lines

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

Quoted 1 line

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.

Quoted 2 lines

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.

Quoted 6 lines

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

#4 lore raw

Hi Krzysztof,

Quoted 2 lines · Krzysztof Kozlowski

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

#5 lore raw

PATCH 1/1 dt-bindings: chosen: remove

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

---
 Documentation/devicetree/bindings/chosen.txt | 137 -------------------
 1 file changed, 137 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/chosen.txt
Documentation/devicetree/bindings/chosen.txt deleted +0 -137
deleted file mode 100644
index 1cc3aa10dcb1..000000000000
@@ -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>;
-	};
-};
Signature · 1 line
2.35.1
maintainer Applied
#6 lore raw

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

Quoted 10 lines · Jason A. Donenfeld

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

---
 Documentation/devicetree/bindings/chosen.txt | 137 -------------------
 1 file changed, 137 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/chosen.txt

Applied, thanks!