xref: /freebsd/sys/contrib/device-tree/Bindings/chosen.txt (revision 354d7675fe12ace9cde344cb79c7ded792802f88)
1c66ec88fSEmmanuel VadotThe chosen node
2c66ec88fSEmmanuel Vadot---------------
3c66ec88fSEmmanuel Vadot
4c66ec88fSEmmanuel VadotThe chosen node does not represent a real device, but serves as a place
5c66ec88fSEmmanuel Vadotfor passing data between firmware and the operating system, like boot
6c66ec88fSEmmanuel Vadotarguments. Data in the chosen node does not represent the hardware.
7c66ec88fSEmmanuel Vadot
8c66ec88fSEmmanuel VadotThe following properties are recognized:
9c66ec88fSEmmanuel Vadot
10c66ec88fSEmmanuel Vadot
11c66ec88fSEmmanuel Vadotkaslr-seed
12c66ec88fSEmmanuel Vadot-----------
13c66ec88fSEmmanuel Vadot
14c66ec88fSEmmanuel VadotThis property is used when booting with CONFIG_RANDOMIZE_BASE as the
15c66ec88fSEmmanuel Vadotentropy used to randomize the kernel image base address location. Since
16c66ec88fSEmmanuel Vadotit is used directly, this value is intended only for KASLR, and should
17c66ec88fSEmmanuel Vadotnot be used for other purposes (as it may leak information about KASLR
18c66ec88fSEmmanuel Vadotoffsets). It is parsed as a u64 value, e.g.
19c66ec88fSEmmanuel Vadot
20c66ec88fSEmmanuel Vadot/ {
21c66ec88fSEmmanuel Vadot	chosen {
22c66ec88fSEmmanuel Vadot		kaslr-seed = <0xfeedbeef 0xc0def00d>;
23c66ec88fSEmmanuel Vadot	};
24c66ec88fSEmmanuel Vadot};
25c66ec88fSEmmanuel Vadot
26c66ec88fSEmmanuel VadotNote that if this property is set from UEFI (or a bootloader in EFI
27c66ec88fSEmmanuel Vadotmode) when EFI_RNG_PROTOCOL is supported, it will be overwritten by
28c66ec88fSEmmanuel Vadotthe Linux EFI stub (which will populate the property itself, using
29c66ec88fSEmmanuel VadotEFI_RNG_PROTOCOL).
30c66ec88fSEmmanuel Vadot
31c66ec88fSEmmanuel Vadotstdout-path
32c66ec88fSEmmanuel Vadot-----------
33c66ec88fSEmmanuel Vadot
34c66ec88fSEmmanuel VadotDevice trees may specify the device to be used for boot console output
35c66ec88fSEmmanuel Vadotwith a stdout-path property under /chosen, as described in the Devicetree
36c66ec88fSEmmanuel VadotSpecification, e.g.
37c66ec88fSEmmanuel Vadot
38c66ec88fSEmmanuel Vadot/ {
39c66ec88fSEmmanuel Vadot	chosen {
40c66ec88fSEmmanuel Vadot		stdout-path = "/serial@f00:115200";
41c66ec88fSEmmanuel Vadot	};
42c66ec88fSEmmanuel Vadot
43c66ec88fSEmmanuel Vadot	serial@f00 {
44c66ec88fSEmmanuel Vadot		compatible = "vendor,some-uart";
45c66ec88fSEmmanuel Vadot		reg = <0xf00 0x10>;
46c66ec88fSEmmanuel Vadot	};
47c66ec88fSEmmanuel Vadot};
48c66ec88fSEmmanuel Vadot
49c66ec88fSEmmanuel VadotIf the character ":" is present in the value, this terminates the path.
50c66ec88fSEmmanuel VadotThe meaning of any characters following the ":" is device-specific, and
51c66ec88fSEmmanuel Vadotmust be specified in the relevant binding documentation.
52c66ec88fSEmmanuel Vadot
53c66ec88fSEmmanuel VadotFor UART devices, the preferred binding is a string in the form:
54c66ec88fSEmmanuel Vadot
55c66ec88fSEmmanuel Vadot	<baud>{<parity>{<bits>{<flow>}}}
56c66ec88fSEmmanuel Vadot
57c66ec88fSEmmanuel Vadotwhere
58c66ec88fSEmmanuel Vadot
59c66ec88fSEmmanuel Vadot	baud	- baud rate in decimal
60c66ec88fSEmmanuel Vadot	parity	- 'n' (none), 'o', (odd) or 'e' (even)
61c66ec88fSEmmanuel Vadot	bits	- number of data bits
62c66ec88fSEmmanuel Vadot	flow	- 'r' (rts)
63c66ec88fSEmmanuel Vadot
64c66ec88fSEmmanuel VadotFor example: 115200n8r
65c66ec88fSEmmanuel Vadot
66c66ec88fSEmmanuel VadotImplementation note: Linux will look for the property "linux,stdout-path" or
67c66ec88fSEmmanuel Vadoton PowerPC "stdout" if "stdout-path" is not found.  However, the
68c66ec88fSEmmanuel Vadot"linux,stdout-path" and "stdout" properties are deprecated. New platforms
69c66ec88fSEmmanuel Vadotshould only use the "stdout-path" property.
70c66ec88fSEmmanuel Vadot
71c66ec88fSEmmanuel Vadotlinux,booted-from-kexec
72c66ec88fSEmmanuel Vadot-----------------------
73c66ec88fSEmmanuel Vadot
74c66ec88fSEmmanuel VadotThis property is set (currently only on PowerPC, and only needed on
75c66ec88fSEmmanuel Vadotbook3e) by some versions of kexec-tools to tell the new kernel that it
76c66ec88fSEmmanuel Vadotis being booted by kexec, as the booting environment may differ (e.g.
77c66ec88fSEmmanuel Vadota different secondary CPU release mechanism)
78c66ec88fSEmmanuel Vadot
79c66ec88fSEmmanuel Vadotlinux,usable-memory-range
80c66ec88fSEmmanuel Vadot-------------------------
81c66ec88fSEmmanuel Vadot
82*354d7675SEmmanuel VadotThis property holds a base address and size, describing a limited region in
83*354d7675SEmmanuel Vadotwhich memory may be considered available for use by the kernel. Memory outside
84*354d7675SEmmanuel Vadotof this range is not available for use.
85c66ec88fSEmmanuel Vadot
86c66ec88fSEmmanuel VadotThis property describes a limitation: memory within this range is only
87c66ec88fSEmmanuel Vadotvalid when also described through another mechanism that the kernel
88c66ec88fSEmmanuel Vadotwould otherwise use to determine available memory (e.g. memory nodes
89c66ec88fSEmmanuel Vadotor the EFI memory map). Valid memory may be sparse within the range.
90c66ec88fSEmmanuel Vadote.g.
91c66ec88fSEmmanuel Vadot
92c66ec88fSEmmanuel Vadot/ {
93c66ec88fSEmmanuel Vadot	chosen {
94c66ec88fSEmmanuel Vadot		linux,usable-memory-range = <0x9 0xf0000000 0x0 0x10000000>;
95c66ec88fSEmmanuel Vadot	};
96c66ec88fSEmmanuel Vadot};
97c66ec88fSEmmanuel Vadot
98c66ec88fSEmmanuel VadotThe main usage is for crash dump kernel to identify its own usable
99c66ec88fSEmmanuel Vadotmemory and exclude, at its boot time, any other memory areas that are
100c66ec88fSEmmanuel Vadotpart of the panicked kernel's memory.
101c66ec88fSEmmanuel Vadot
102c66ec88fSEmmanuel VadotWhile this property does not represent a real hardware, the address
103c66ec88fSEmmanuel Vadotand the size are expressed in #address-cells and #size-cells,
104c66ec88fSEmmanuel Vadotrespectively, of the root node.
105c66ec88fSEmmanuel Vadot
106c66ec88fSEmmanuel Vadotlinux,elfcorehdr
107c66ec88fSEmmanuel Vadot----------------
108c66ec88fSEmmanuel Vadot
109*354d7675SEmmanuel VadotThis property holds the memory range, the address and the size, of the elf
110*354d7675SEmmanuel Vadotcore header which mainly describes the panicked kernel's memory layout as
111*354d7675SEmmanuel VadotPT_LOAD segments of elf format.
112c66ec88fSEmmanuel Vadote.g.
113c66ec88fSEmmanuel Vadot
114c66ec88fSEmmanuel Vadot/ {
115c66ec88fSEmmanuel Vadot	chosen {
116c66ec88fSEmmanuel Vadot		linux,elfcorehdr = <0x9 0xfffff000 0x0 0x800>;
117c66ec88fSEmmanuel Vadot	};
118c66ec88fSEmmanuel Vadot};
119c66ec88fSEmmanuel Vadot
120c66ec88fSEmmanuel VadotWhile this property does not represent a real hardware, the address
121c66ec88fSEmmanuel Vadotand the size are expressed in #address-cells and #size-cells,
122c66ec88fSEmmanuel Vadotrespectively, of the root node.
123c66ec88fSEmmanuel Vadot
124c66ec88fSEmmanuel Vadotlinux,initrd-start and linux,initrd-end
125c66ec88fSEmmanuel Vadot---------------------------------------
126c66ec88fSEmmanuel Vadot
127c66ec88fSEmmanuel VadotThese properties hold the physical start and end address of an initrd that's
128c66ec88fSEmmanuel Vadotloaded by the bootloader. Note that linux,initrd-start is inclusive, but
129c66ec88fSEmmanuel Vadotlinux,initrd-end is exclusive.
130c66ec88fSEmmanuel Vadote.g.
131c66ec88fSEmmanuel Vadot
132c66ec88fSEmmanuel Vadot/ {
133c66ec88fSEmmanuel Vadot	chosen {
134c66ec88fSEmmanuel Vadot		linux,initrd-start = <0x82000000>;
135c66ec88fSEmmanuel Vadot		linux,initrd-end = <0x82800000>;
136c66ec88fSEmmanuel Vadot	};
137c66ec88fSEmmanuel Vadot};
138