Re: [U-Boot] [PATCH] Document config_distro_bootcmd environment variables for interactive booting.
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(+)
config_distro_bootcmd.h defines a common boot environment for multiple platforms, including several environment variables that are intended for interactive use by an end-user. Document which variables are considered public interfaces that must remain compatible in future u-boot versions.
Signed-off-by: Karsten Merker merker@debian.org --- doc/README.distro | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)
diff --git a/doc/README.distro b/doc/README.distro index dd0f1c7..0308a4c 100644 --- a/doc/README.distro +++ b/doc/README.distro @@ -1,6 +1,7 @@ /* * (C) Copyright 2014 Red Hat Inc. * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. + * Copyright (C) 2015 K. Merker merker@debian.org * * SPDX-License-Identifier: GPL-2.0+ */ @@ -339,3 +340,49 @@ scan_dev_for_scripts:
If you want to disable boot.scr on all disks, set the value to something innocuous, e.g. setenv scan_dev_for_scripts true. + + +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. + +If the target is a storage device, the format of the target is always +<device type><device number>, e.g. mmc0. Specifying the device number is +mandatory for storage devices, even if only support for a single instance +of the storage device is actually implemented. + +For network targets (dhcp, pxe), only the device type gets specified; +they do not have a device number. + +Examples: + + - run bootcmd_usb0 + boots from the first USB mass storage device + + - run bootcmd_mmc1 + boots from the second MMC device + + - run bootcmd_pxe + boots by tftp using a pxelinux.cfg + +The list of possible targets consists of: + +- network targets + * dhcp + * pxe + +- storage targets (to which a device number must be appended) + * mmc + * sata + * scsi + * ide + * usb + +Other *boot* variables than the ones defined above are only for internal use +of the boot environment and are not guaranteed to exist or work in the same +way in future u-boot versions. In particular the <device type>_boot +variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation +detail and must not be used as a public interface.
On 03/21/2015 07:15 AM, Karsten Merker wrote:
config_distro_bootcmd.h defines a common boot environment for multiple platforms, including several environment variables that are intended for interactive use by an end-user. Document which variables are considered public interfaces that must remain compatible in future u-boot versions.
Acked-by: Stephen Warren swarren@nvidia.com
On Sat, Mar 21, 2015 at 02:15:38PM +0100, Karsten Merker wrote:
config_distro_bootcmd.h defines a common boot environment for multiple platforms, including several environment variables that are intended for interactive use by an end-user. Document which variables are considered public interfaces that must remain compatible in future u-boot versions.
Signed-off-by: Karsten Merker merker@debian.org Acked-by: Stephen Warren swarren@nvidia.com
Applied to u-boot/master, thanks!
participants (3)
-
Karsten Merker -
Stephen Warren -
Tom Rini