[U-Boot] Document config_distro_bootcmd environment variables for interactive booting.

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

On 03/19/2015 01:41 PM, Karsten Merker wrote:

A brief description would be nice.

> diff --git a/doc/README.distro b/doc/README.distro

> +Interactively booting from a specific device at the u-boot prompt
> +=================================================================
> +
> +For interactively booting from a user-selected device at the u-boot command
> +prompt, the environment provides predefined bootcmd_<target> variables for
> +every target defined in boot_targets, which can be run be the user.
> +
> +Examples:
> +
> + - run bootcmd_usb0
> +   boots from the first USB mass storage device
> +
> + - run bootcmd_mmc1
> +   boots from the second MMC device

Should we enumerate all the possible device types, e.g. include 
bootcmd_sata0, bootcmd_ide0, ...?

We should definitely mention that bootcmd_usb is an internal 
implementation detail even though bootcmd_usb0 is a command that we 
intend users to run. In the text, perhaps rephrase bootcmd_<target> as 
bootcmd_<devtype><devnum>, and note that <devnum> is not optional in the 
command name?

On Thu, Mar 19, 2015 at 01:53:14PM -0600, Stephen Warren wrote:

> >+Interactively booting from a specific device at the u-boot prompt
> >+=================================================================
> >+
> >+For interactively booting from a user-selected device at the u-boot command
> >+prompt, the environment provides predefined bootcmd_<target> variables for
> >+every target defined in boot_targets, which can be run be the user.
> >+
> >+Examples:
> >+
> >+ - run bootcmd_usb0
> >+   boots from the first USB mass storage device
> >+
> >+ - run bootcmd_mmc1
> >+   boots from the second MMC device
> 
> Should we enumerate all the possible device types, e.g. include
> bootcmd_sata0, bootcmd_ide0, ...?

Hm, I suppose that depends on whether there is such a thing as
definitve list of all possible device types on all platforms and
how many elements are in this list.  Are functionally equivalent
devices named the same on all platforms, i.e. is a PATA
interface always ide0, or could it be ide0 on one platform and
pata0 on another?

> We should definitely mention that bootcmd_usb is an internal
> implementation detail even though bootcmd_usb0 is a command that we
> intend users to run.

Ok, I'll address that in a V2 of the patch (probably sometime
tomorrow).

> In the text, perhaps rephrase bootcmd_<target> as
> bootcmd_<devtype><devnum>, and note that <devnum> is not optional in the
> command name?

I had thought about explictly using devtype and devnum, but there
are device types such as pxe which do not have a devnum, so I
chose to use the generic <target> designation instead. I can
change that, but it might cause confusion so that a user would
try to use something like "run bootcmd_pxe0" which would not
work. I would therefore prefer the generic <target> designation.

Regards,
Karsten

On 03/19/2015 02:53 PM, Karsten Merker wrote:
> On Thu, Mar 19, 2015 at 01:53:14PM -0600, Stephen Warren wrote:
>
>>> +Interactively booting from a specific device at the u-boot prompt
>>> +=================================================================
>>> +
>>> +For interactively booting from a user-selected device at the u-boot command
>>> +prompt, the environment provides predefined bootcmd_<target> variables for
>>> +every target defined in boot_targets, which can be run be the user.
>>> +
>>> +Examples:
>>> +
>>> + - run bootcmd_usb0
>>> +   boots from the first USB mass storage device
>>> +
>>> + - run bootcmd_mmc1
>>> +   boots from the second MMC device
>>
>> Should we enumerate all the possible device types, e.g. include
>> bootcmd_sata0, bootcmd_ide0, ...?
>
> Hm, I suppose that depends on whether there is such a thing as
> definitve list of all possible device types on all platforms and
> how many elements are in this list.  Are functionally equivalent
> devices named the same on all platforms, i.e. is a PATA
> interface always ide0, or could it be ide0 on one platform and
> pata0 on another?

The list is limited to the macros that are set up in 
config_distro_bootcmd.h. At least for the device types supported there, 
and the set of platforms which use that header so far, a particular 
device type is always named the same on all platforms.

I'd expect a patch that added a new device type to the header to update 
the list in the documentation.

>> In the text, perhaps rephrase bootcmd_<target> as
>> bootcmd_<devtype><devnum>, and note that <devnum> is not optional in the
>> command name?
>
> I had thought about explictly using devtype and devnum, but there
> are device types such as pxe which do not have a devnum, so I
> chose to use the generic <target> designation instead. I can
> change that, but it might cause confusion so that a user would
> try to use something like "run bootcmd_pxe0" which would not
> work. I would therefore prefer the generic <target> designation.

Ah yes. Perhaps continue to use <target> and then explain that when 
<target> is a storage device that can have multiple instances, the 
format of <target> must be <devtype><devnum>, but in other cases (pxe, 
dhcp), it is just a standalone name?

Changes since V1:

- Explicitly define the target format for storage and network targets
- Include a list of all valid bootcmd targets which are currently supported
- Make the commit log more verbose

Karsten Merker (1):
  Document config_distro_bootcmd environment variables for interactive
    booting.

 doc/README.distro |   47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)