README.autoboot 5.02 KB
Newer Older
wdenk's avatar
wdenk committed
1 2 3 4
/*
 * (C) Copyright 2001
 * Dave Ellis, SIXNET, dge@sixnetio.com
 *
5
 * SPDX-License-Identifier:	GPL-2.0+
wdenk's avatar
wdenk committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
 */

Using autoboot configuration options
====================================

The basic autoboot configuration options are documented in the main
U-Boot README. See it for details. They are:

  bootdelay
  bootcmd
  CONFIG_BOOTDELAY
  CONFIG_BOOTCOMMAND

Some additional options that make autoboot safer in a production
product are documented here.

Why use them?
-------------

The basic autoboot feature allows a system to automatically boot to
the real application (such as Linux) without a user having to enter
any commands. If any key is pressed before the boot delay time
expires, U-Boot stops the autoboot process, gives a U-Boot prompt
and waits forever for a command. That's a good thing if you pressed a
key because you wanted to get the prompt.

It's not so good if the key press was a stray character on the
console serial port, say because a user who knows nothing about
U-Boot pressed a key before the system had time to boot. It's even
worse on an embedded product that doesn't have a console during
normal use. The modem plugged into that console port sends a
character at the wrong time and the system hangs, with no clue as to
why it isn't working.

You might want the system to autoboot to recover after an external
configuration program stops autoboot. If the configuration program
dies or loses its connection (modems can disconnect at the worst
time) U-Boot will patiently wait forever for it to finish.

These additional configuration options can help provide a system that
boots when it should, but still allows access to U-Boot.

What they do
------------

  CONFIG_BOOT_RETRY_TIME
  CONFIG_BOOT_RETRY_MIN

54
  "bootretry" environment variable
wdenk's avatar
wdenk committed
55

wdenk's avatar
wdenk committed
56 57 58 59
	These options determine what happens after autoboot is
	stopped and U-Boot is waiting for commands.

	CONFIG_BOOT_RETRY_TIME must be defined to enable the boot
60
	retry feature. If the environment variable "bootretry" is
wdenk's avatar
wdenk committed
61 62 63 64 65 66 67 68 69 70 71 72 73
	found then its value is used, otherwise the retry timeout is
	CONFIG_BOOT_RETRY_TIME. CONFIG_BOOT_RETRY_MIN is optional and
	defaults to CONFIG_BOOT_RETRY_TIME. All times are in seconds.

	If the retry timeout is negative, the U-Boot command prompt
	never times out. Otherwise it is forced to be at least
	CONFIG_BOOT_RETRY_MIN seconds. If no valid U-Boot command is
	entered before the specified time the boot delay sequence is
	restarted. Each command that U-Boot executes restarts the
	timeout.

	If CONFIG_BOOT_RETRY_TIME < 0 the feature is there, but
	doesn't do anything unless the environment variable
74
	"bootretry" is >= 0.
wdenk's avatar
wdenk committed
75 76

  CONFIG_AUTOBOOT_KEYED
77
  CONFIG_AUTOBOOT_KEYED_CTRLC
wdenk's avatar
wdenk committed
78 79 80 81
  CONFIG_AUTOBOOT_PROMPT
  CONFIG_AUTOBOOT_DELAY_STR
  CONFIG_AUTOBOOT_STOP_STR

82
  "bootdelaykey"  environment variable
wdenk's avatar
wdenk committed
83
  "bootstopkey"	  environment variable
wdenk's avatar
wdenk committed
84

wdenk's avatar
wdenk committed
85 86 87
	These options give more control over stopping autoboot. When
	they are used a specific character or string is required to
	stop or delay autoboot.
wdenk's avatar
wdenk committed
88 89

	Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
wdenk's avatar
wdenk committed
90
	this group of options.	CONFIG_AUTOBOOT_DELAY_STR,
wdenk's avatar
wdenk committed
91 92 93 94
	CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
	specified by the corresponding environment variable),
	otherwise there is no way to stop autoboot.

wdenk's avatar
wdenk committed
95 96 97
	CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay
	selected by CONFIG_BOOTDELAY starts. If it is not defined
	there is no output indicating that autoboot is in progress.
Stefan Roese's avatar
Stefan Roese committed
98 99 100 101 102 103 104 105 106 107 108

	Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
	argument to a printf() call, so it may contain '%' format
	specifications, provided that it also includes, sepearated by
	commas exactly like in a printf statement, the required
	arguments. It is the responsibility of the user to select only
	such arguments that are valid in the given context. A
	reasonable prompt could be defined as

		#define CONFIG_AUTOBOOT_PROMPT \
			"autoboot in %d seconds\n",bootdelay
wdenk's avatar
wdenk committed
109

wdenk's avatar
wdenk committed
110 111 112 113 114
	If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
	and this string is received from console input before
	autoboot starts booting, U-Boot gives a command prompt. The
	U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
	used, otherwise it never times out.
wdenk's avatar
wdenk committed
115

wdenk's avatar
wdenk committed
116 117 118 119 120
	If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
	this string is received from console input before autoboot
	starts booting, U-Boot gives a command prompt. The U-Boot
	prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
	used.
wdenk's avatar
wdenk committed
121 122 123 124 125 126 127 128

	The string recognition is not very sophisticated. If a
	partial match is detected, the first non-matching character
	is checked to see if starts a new match. There is no check
	for a shorter partial match, so it's best if the first
	character of a key string does not appear in the rest of the
	string.

129 130 131 132 133 134
	The CONFIG_AUTOBOOT_KEYED_CTRLC #define allows for the boot
	sequence to be interrupted by ctrl-c, in addition to the
	"bootdelaykey" and "bootstopkey". Setting this variable
	provides an escape sequence from the limited "password"
	strings.

wdenk's avatar
wdenk committed
135 136
  CONFIG_RESET_TO_RETRY

wdenk's avatar
wdenk committed
137 138 139
	(Only effective when CONFIG_BOOT_RETRY_TIME is also set)
	After the countdown timed out, the board will be reset to restart
	again.