[U-Boot] Document the format of the console environment variable

config_distro_bootcmd.h defines a common boot environment for
multiple platforms.  Document the format of the console
environment variable to allow the use of generic boot scripts
on all supported platforms.

Signed-off-by: Karsten Merker <merker@debian.org>
---
 doc/README.distro |    9 +++++++++
 1 file changed, 9 insertions(+)

Hi,

On 29-03-15 17:55, Karsten Merker wrote:
> config_distro_bootcmd.h defines a common boot environment for
> multiple platforms.  Document the format of the console
> environment variable to allow the use of generic boot scripts
> on all supported platforms.
>
> Signed-off-by: Karsten Merker <merker@debian.org>

Maybe add something that distros are not encouraged to use this ?

At least on Fedora we do not want to use it, as adding
console=${console} to bootargs on systems with both video-output
(e.g. hdmi out) and a serial port will cause boot messages to
only be shown on the serial port as that is where the /dev/console
then points.

Whereas when using the devicetree chosen/stdout-path property (which
can be set either by u-boot or in the dts with the kernel),
the kernel will use both /dev/tty0 (so the hdmi out) and the serial
port pointed to by chosen/stdout as console, showing boot messages
on both, and systemd will still automatically spawn a getty on the
serial console.

Regards,

Hans




> ---
>   doc/README.distro |    9 +++++++++
>   1 file changed, 9 insertions(+)
>
> diff --git a/doc/README.distro b/doc/README.distro
> index 0308a4c..3f7ee85 100644
> --- a/doc/README.distro
> +++ b/doc/README.distro
> @@ -201,6 +201,15 @@ variables be set. Default values for these variables are often hard-coded into
>   CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
>   the user doesn't have to configure them.
>
> +console:
> +
> +  Mandatory. The default console device to be passed to the Linux kernel.
> +
> +  The console device is specified in accordance with the guidelines
> +  described in Documentation/serial-console.txt in the Linux kernel sources.
> +  If the device is a serial port, the console variable must specify the
> +  console baudrate in addition to the console device, e.g. "ttyS0,115200".
> +
>   fdt_addr:
>
>     Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
>

On Mon, Mar 30, 2015 at 09:06:10AM +0200, Hans de Goede wrote:
> On 29-03-15 17:55, Karsten Merker wrote:
> >config_distro_bootcmd.h defines a common boot environment for
> >multiple platforms.  Document the format of the console
> >environment variable to allow the use of generic boot scripts
> >on all supported platforms.
> >
> >Signed-off-by: Karsten Merker <merker@debian.org>
> 
> Maybe add something that distros are not encouraged to use this ?
> 
> At least on Fedora we do not want to use it, as adding
> console=${console} to bootargs on systems with both video-output
> (e.g. hdmi out) and a serial port will cause boot messages to
> only be shown on the serial port as that is where the /dev/console
> then points.
> 
> Whereas when using the devicetree chosen/stdout-path property (which
> can be set either by u-boot or in the dts with the kernel),
> the kernel will use both /dev/tty0 (so the hdmi out) and the serial
> port pointed to by chosen/stdout as console, showing boot messages
> on both, and systemd will still automatically spawn a getty on the
> serial console.

Hello,

I am unsure whether I am missing something here, so please
correct me if I am wrong:

AFAIK using the stdout-path property is only supported by
recent kernels and grepping through the current mainline kernel
git shows it to be predefined only in a fraction of the dts files.

I have just run some tests on a Banana Pi:
When using u-boot v2014.10 (which is what Debian will ship in the
upcoming "Jessie" release), no stdout-path property gets set, and
I get no serial console when I do not pass a console parameter to
the kernel. When using the same kernel with current u-boot git
(2015.04-rc4), a stdout-path property gets set, so this
functionality seems to have been added to u-boot only recently. 
Is this correct?

If my previous assumptions are correct, leaving out the console
parameter only works when both u-boot and the kernel are fairly
recent.

What I currently do not understand is why the kernel will - as
you wrote above - use both /dev/tty0 and the serial console in
parallel when the serial console device is passed via the
stdout-path property, but not when the same device is passed via
the console parameter.  Shouldn't the result be the same in both
cases?

Does u-boot automatically adjust the stdout-path property that is
passed to the kernel based on the current console-device used by
u-boot (sorry, I cannot test that currently due to lack of a
HDMI-capable display)?

Regards,
Karsten

On Mon, Mar 30, 2015 at 09:21:18PM +0200, Karsten Merker wrote:
> On Mon, Mar 30, 2015 at 09:06:10AM +0200, Hans de Goede wrote:
> > On 29-03-15 17:55, Karsten Merker wrote:
> > >config_distro_bootcmd.h defines a common boot environment for
> > >multiple platforms.  Document the format of the console
> > >environment variable to allow the use of generic boot scripts
> > >on all supported platforms.
> > >
> > >Signed-off-by: Karsten Merker <merker@debian.org>
> > 
> > Maybe add something that distros are not encouraged to use this ?
> > 
> > At least on Fedora we do not want to use it, as adding
> > console=${console} to bootargs on systems with both video-output
> > (e.g. hdmi out) and a serial port will cause boot messages to
> > only be shown on the serial port as that is where the /dev/console
> > then points.
> > 
> > Whereas when using the devicetree chosen/stdout-path property (which
> > can be set either by u-boot or in the dts with the kernel),
> > the kernel will use both /dev/tty0 (so the hdmi out) and the serial
> > port pointed to by chosen/stdout as console, showing boot messages
> > on both, and systemd will still automatically spawn a getty on the
> > serial console.
> 
> Hello,
> 
> I am unsure whether I am missing something here, so please
> correct me if I am wrong:
> 
> AFAIK using the stdout-path property is only supported by
> recent kernels and grepping through the current mainline kernel
> git shows it to be predefined only in a fraction of the dts files.
> 
> I have just run some tests on a Banana Pi:
> When using u-boot v2014.10 (which is what Debian will ship in the
> upcoming "Jessie" release), no stdout-path property gets set, and
> I get no serial console when I do not pass a console parameter to
> the kernel. When using the same kernel with current u-boot git
> (2015.04-rc4), a stdout-path property gets set, so this
> functionality seems to have been added to u-boot only recently. 
> Is this correct?
> 
> If my previous assumptions are correct, leaving out the console
> parameter only works when both u-boot and the kernel are fairly
> recent.
> 
> What I currently do not understand is why the kernel will - as
> you wrote above - use both /dev/tty0 and the serial console in
> parallel when the serial console device is passed via the
> stdout-path property, but not when the same device is passed via
> the console parameter.  Shouldn't the result be the same in both
> cases?
> 
> Does u-boot automatically adjust the stdout-path property that is
> passed to the kernel based on the current console-device used by
> u-boot (sorry, I cannot test that currently due to lack of a
> HDMI-capable display)?

Hello Hans,
may I ping you on this topic?

I have just been looking through the mainline kernel commit logs
and stumbled over the following entries:

commit bb8ef2fbb836c159ba847757123b8e33284406f8
Author: Linus Torvalds <torvalds@linux-foundation.org>
Date:   Sat Mar 21 12:33:01 2015 -0700
[...]
     - revert setting stdout-path as preferred console.  This caused
       regressions in PowerMACs and other systems.
[...]

commit f64255b5072d9c46cef8655d51cf7e10285abed7
Author: Peter Hurley <peter@hurleysoftware.com>
Date:   Tue Mar 17 16:46:33 2015 -0400

    Revert "of: Fix premature bootconsole disable with 'stdout-path'"
    
    This reverts commit 2fa645cb2703d9b3786d850db815414dfeefa51d.
    
    The assumption that at least 1 preferred console will be registered
    when the stdout-path property is set is invalid, which can result
    in _no_ consoles.

commit 2fa645cb2703d9b3786d850db815414dfeefa51d
Author: Peter Hurley <peter@hurleysoftware.com>
Date:   Sun Mar 1 12:21:22 2015 -0500

    of: Fix premature bootconsole disable with 'stdout-path'
    
    Support for devicetree serial consoles via 'stdout-path' causes
    bootconsoles to be disabled when the vt dummy console loads, since
    there is no preferred console (the preferred console is not added
    until the device is probed).
    
    Ensure there is at least a preferred console, even if never matched.

I am not deeply enough in the topic to understand the full
picture, but this gives me the impression that it is perhaps too
early to rely solely on stdout-path, although I really like the
idea behind it.  Comments welcome :-).

Regards,
Karsten