diff mbox

[v3,1/3] devicetree: of: Add bindings for chosen node, stdout-path

Message ID 1417110967-16284-2-git-send-email-leif.lindholm@linaro.org (mailing list archive)
State New, archived
Headers show

Commit Message

Leif Lindholm Nov. 27, 2014, 5:56 p.m. UTC
Add a global binding for the chosen node.
Include a description of the stdout-path, and an explicit statement on
its extra options in the context of a UART console.

Opening description stolen from www.devicetree.org, and part of the
remaining text provided by Mark Rutland.

Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
---
 Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/chosen.txt

Comments

Mark Rutland Nov. 27, 2014, 6:41 p.m. UTC | #1
On Thu, Nov 27, 2014 at 05:56:05PM +0000, Leif Lindholm wrote:
> Add a global binding for the chosen node.
> Include a description of the stdout-path, and an explicit statement on
> its extra options in the context of a UART console.
> 
> Opening description stolen from www.devicetree.org, and part of the
> remaining text provided by Mark Rutland.
> 
> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
> ---
>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>  1 file changed, 42 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
> 
> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
> new file mode 100644
> index 0000000..9cd74e9
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/chosen.txt
> @@ -0,0 +1,42 @@
> +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.
> +
> +
> +stdout-path property
> +--------------------
> +
> +Device trees may specify the device to be used for boot console output
> +with a stdout-path property under /chosen, as described in ePAPR, 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 format supported by uart_parse_options() is the
> +expected one. In this case, the format of the string is:

Please drop the mention of uart_parse_options and just describe the
format. Linux internal details are irrelevant to the contract of the
binding.

Otherwise this looks good to me!

Thanks,
Mark.

> +
> +	<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
> -- 
> 1.7.10.4
> 
>
Grant Likely Nov. 28, 2014, 12:22 a.m. UTC | #2
On Thu, 27 Nov 2014 18:41:33 +0000
, Mark Rutland <mark.rutland@arm.com>
 wrote:
> On Thu, Nov 27, 2014 at 05:56:05PM +0000, Leif Lindholm wrote:
> > Add a global binding for the chosen node.
> > Include a description of the stdout-path, and an explicit statement on
> > its extra options in the context of a UART console.
> > 
> > Opening description stolen from www.devicetree.org, and part of the
> > remaining text provided by Mark Rutland.
> > 
> > Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
> > ---
> >  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
> >  1 file changed, 42 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/chosen.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
> > new file mode 100644
> > index 0000000..9cd74e9
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/chosen.txt
> > @@ -0,0 +1,42 @@
> > +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.
> > +
> > +
> > +stdout-path property
> > +--------------------
> > +
> > +Device trees may specify the device to be used for boot console output
> > +with a stdout-path property under /chosen, as described in ePAPR, 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 format supported by uart_parse_options() is the
> > +expected one. In this case, the format of the string is:
> 
> Please drop the mention of uart_parse_options and just describe the
> format. Linux internal details are irrelevant to the contract of the
> binding.
> 
> Otherwise this looks good to me!

I've fixed it up and merged it. No need to respin. Thanks!

g.
Frank Rowand Dec. 3, 2014, 2:24 a.m. UTC | #3
On 11/27/2014 9:56 AM, Leif Lindholm wrote:
> Add a global binding for the chosen node.
> Include a description of the stdout-path, and an explicit statement on
> its extra options in the context of a UART console.
> 
> Opening description stolen from www.devicetree.org, and part of the
> remaining text provided by Mark Rutland.
> 
> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
> ---
>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>  1 file changed, 42 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
> 
> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
> new file mode 100644
> index 0000000..9cd74e9
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/chosen.txt
> @@ -0,0 +1,42 @@
> +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.
> +
> +
> +stdout-path property

The code in patch 3/3 adds the extra options feature to the properties:

  stdout-path
  linux,stdout-path
  stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]

> +--------------------
> +
> +Device trees may specify the device to be used for boot console output
> +with a stdout-path property under /chosen, as described in ePAPR, 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 format supported by uart_parse_options() is the
> +expected one. In this case, the format of the string is:
> +
> +	<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
>
Grant Likely Dec. 3, 2014, 3:12 p.m. UTC | #4
On Wed, Dec 3, 2014 at 2:24 AM, Frank Rowand <frowand.list@gmail.com> wrote:
> On 11/27/2014 9:56 AM, Leif Lindholm wrote:
>> Add a global binding for the chosen node.
>> Include a description of the stdout-path, and an explicit statement on
>> its extra options in the context of a UART console.
>>
>> Opening description stolen from www.devicetree.org, and part of the
>> remaining text provided by Mark Rutland.
>>
>> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
>> ---
>>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>>  1 file changed, 42 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
>>
>> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
>> new file mode 100644
>> index 0000000..9cd74e9
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/chosen.txt
>> @@ -0,0 +1,42 @@
>> +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.
>> +
>> +
>> +stdout-path property
>
> The code in patch 3/3 adds the extra options feature to the properties:
>
>   stdout-path
>   linux,stdout-path
>   stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]

I don't understand what you mean here. Are you suggesting a change to
this patch? Is there something deficient in it?

g.

>
>> +--------------------
>> +
>> +Device trees may specify the device to be used for boot console output
>> +with a stdout-path property under /chosen, as described in ePAPR, 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 format supported by uart_parse_options() is the
>> +expected one. In this case, the format of the string is:
>> +
>> +     <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
>>
>
Frank Rowand Dec. 3, 2014, 7:46 p.m. UTC | #5
On 12/3/2014 7:12 AM, Grant Likely wrote:
> On Wed, Dec 3, 2014 at 2:24 AM, Frank Rowand <frowand.list@gmail.com> wrote:
>> On 11/27/2014 9:56 AM, Leif Lindholm wrote:
>>> Add a global binding for the chosen node.
>>> Include a description of the stdout-path, and an explicit statement on
>>> its extra options in the context of a UART console.
>>>
>>> Opening description stolen from www.devicetree.org, and part of the
>>> remaining text provided by Mark Rutland.
>>>
>>> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
>>> ---
>>>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>>>  1 file changed, 42 insertions(+)
>>>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
>>>
>>> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
>>> new file mode 100644
>>> index 0000000..9cd74e9
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/chosen.txt
>>> @@ -0,0 +1,42 @@
>>> +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.
>>> +
>>> +
>>> +stdout-path property
>>
>> The code in patch 3/3 adds the extra options feature to the properties:
>>
>>   stdout-path
>>   linux,stdout-path
>>   stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]
> 
> I don't understand what you mean here. Are you suggesting a change to
> this patch? Is there something deficient in it?

Assuming that the code change in patch 3 is as desired, then the chosen.txt
documentation applies to all three properties, not just stdout-path.  So
yes, a change is suggested for the documentation.

-Frank
Grant Likely Dec. 3, 2014, 9:45 p.m. UTC | #6
On Wed, Dec 3, 2014 at 7:46 PM, Frank Rowand <frowand.list@gmail.com> wrote:
> On 12/3/2014 7:12 AM, Grant Likely wrote:
>> On Wed, Dec 3, 2014 at 2:24 AM, Frank Rowand <frowand.list@gmail.com> wrote:
>>> On 11/27/2014 9:56 AM, Leif Lindholm wrote:
>>>> Add a global binding for the chosen node.
>>>> Include a description of the stdout-path, and an explicit statement on
>>>> its extra options in the context of a UART console.
>>>>
>>>> Opening description stolen from www.devicetree.org, and part of the
>>>> remaining text provided by Mark Rutland.
>>>>
>>>> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
>>>> ---
>>>>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>>>>  1 file changed, 42 insertions(+)
>>>>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
>>>> new file mode 100644
>>>> index 0000000..9cd74e9
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/chosen.txt
>>>> @@ -0,0 +1,42 @@
>>>> +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.
>>>> +
>>>> +
>>>> +stdout-path property
>>>
>>> The code in patch 3/3 adds the extra options feature to the properties:
>>>
>>>   stdout-path
>>>   linux,stdout-path
>>>   stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]
>>
>> I don't understand what you mean here. Are you suggesting a change to
>> this patch? Is there something deficient in it?
>
> Assuming that the code change in patch 3 is as desired, then the chosen.txt
> documentation applies to all three properties, not just stdout-path.  So
> yes, a change is suggested for the documentation.

how about if this is added:

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.

g.
Frank Rowand Dec. 3, 2014, 11:07 p.m. UTC | #7
On 12/3/2014 1:45 PM, Grant Likely wrote:
> On Wed, Dec 3, 2014 at 7:46 PM, Frank Rowand <frowand.list@gmail.com> wrote:
>> On 12/3/2014 7:12 AM, Grant Likely wrote:
>>> On Wed, Dec 3, 2014 at 2:24 AM, Frank Rowand <frowand.list@gmail.com> wrote:
>>>> On 11/27/2014 9:56 AM, Leif Lindholm wrote:
>>>>> Add a global binding for the chosen node.
>>>>> Include a description of the stdout-path, and an explicit statement on
>>>>> its extra options in the context of a UART console.
>>>>>
>>>>> Opening description stolen from www.devicetree.org, and part of the
>>>>> remaining text provided by Mark Rutland.
>>>>>
>>>>> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
>>>>> ---
>>>>>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
>>>>>  1 file changed, 42 insertions(+)
>>>>>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
>>>>>
>>>>> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
>>>>> new file mode 100644
>>>>> index 0000000..9cd74e9
>>>>> --- /dev/null
>>>>> +++ b/Documentation/devicetree/bindings/chosen.txt
>>>>> @@ -0,0 +1,42 @@
>>>>> +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.
>>>>> +
>>>>> +
>>>>> +stdout-path property
>>>>
>>>> The code in patch 3/3 adds the extra options feature to the properties:
>>>>
>>>>   stdout-path
>>>>   linux,stdout-path
>>>>   stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]
>>>
>>> I don't understand what you mean here. Are you suggesting a change to
>>> this patch? Is there something deficient in it?
>>
>> Assuming that the code change in patch 3 is as desired, then the chosen.txt
>> documentation applies to all three properties, not just stdout-path.  So
>> yes, a change is suggested for the documentation.
> 
> how about if this is added:
> 
> 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.
> 
> g.
> 

Yep, perfect.

-Frank
Grant Likely Dec. 4, 2014, 10:39 a.m. UTC | #8
On Wed, 03 Dec 2014 15:07:49 -0800
, Frank Rowand <frowand.list@gmail.com>
 wrote:
> On 12/3/2014 1:45 PM, Grant Likely wrote:
> > On Wed, Dec 3, 2014 at 7:46 PM, Frank Rowand <frowand.list@gmail.com> wrote:
> >> On 12/3/2014 7:12 AM, Grant Likely wrote:
> >>> On Wed, Dec 3, 2014 at 2:24 AM, Frank Rowand <frowand.list@gmail.com> wrote:
> >>>> On 11/27/2014 9:56 AM, Leif Lindholm wrote:
> >>>>> Add a global binding for the chosen node.
> >>>>> Include a description of the stdout-path, and an explicit statement on
> >>>>> its extra options in the context of a UART console.
> >>>>>
> >>>>> Opening description stolen from www.devicetree.org, and part of the
> >>>>> remaining text provided by Mark Rutland.
> >>>>>
> >>>>> Signed-off-by: Leif Lindholm <leif.lindholm@linaro.org>
> >>>>> ---
> >>>>>  Documentation/devicetree/bindings/chosen.txt |   42 ++++++++++++++++++++++++++
> >>>>>  1 file changed, 42 insertions(+)
> >>>>>  create mode 100644 Documentation/devicetree/bindings/chosen.txt
> >>>>>
> >>>>> diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
> >>>>> new file mode 100644
> >>>>> index 0000000..9cd74e9
> >>>>> --- /dev/null
> >>>>> +++ b/Documentation/devicetree/bindings/chosen.txt
> >>>>> @@ -0,0 +1,42 @@
> >>>>> +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.
> >>>>> +
> >>>>> +
> >>>>> +stdout-path property
> >>>>
> >>>> The code in patch 3/3 adds the extra options feature to the properties:
> >>>>
> >>>>   stdout-path
> >>>>   linux,stdout-path
> >>>>   stdout  [if (IS_ENABLED(CONFIG_PPC) ... ]
> >>>
> >>> I don't understand what you mean here. Are you suggesting a change to
> >>> this patch? Is there something deficient in it?
> >>
> >> Assuming that the code change in patch 3 is as desired, then the chosen.txt
> >> documentation applies to all three properties, not just stdout-path.  So
> >> yes, a change is suggested for the documentation.
> > 
> > how about if this is added:
> > 
> > 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.
> > 
> > g.
> > 
> 
> Yep, perfect.

Great, thanks. Merged.

g.
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt
new file mode 100644
index 0000000..9cd74e9
--- /dev/null
+++ b/Documentation/devicetree/bindings/chosen.txt
@@ -0,0 +1,42 @@ 
+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.
+
+
+stdout-path property
+--------------------
+
+Device trees may specify the device to be used for boot console output
+with a stdout-path property under /chosen, as described in ePAPR, 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 format supported by uart_parse_options() is the
+expected one. In this case, the format of the string is:
+
+	<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