xref: /openbmc/u-boot/doc/README.autoboot (revision a71d45d7)
1/*
2 * (C) Copyright 2001
3 * Dave Ellis, SIXNET, dge@sixnetio.com
4 *
5 * See file CREDITS for list of people who contributed to this
6 * project.
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License as
10 * published by the Free Software Foundation; either version 2 of
11 * the License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 * MA 02111-1307 USA
22 */
23
24Using autoboot configuration options
25====================================
26
27The basic autoboot configuration options are documented in the main
28U-Boot README. See it for details. They are:
29
30  bootdelay
31  bootcmd
32  CONFIG_BOOTDELAY
33  CONFIG_BOOTCOMMAND
34
35Some additional options that make autoboot safer in a production
36product are documented here.
37
38Why use them?
39-------------
40
41The basic autoboot feature allows a system to automatically boot to
42the real application (such as Linux) without a user having to enter
43any commands. If any key is pressed before the boot delay time
44expires, U-Boot stops the autoboot process, gives a U-Boot prompt
45and waits forever for a command. That's a good thing if you pressed a
46key because you wanted to get the prompt.
47
48It's not so good if the key press was a stray character on the
49console serial port, say because a user who knows nothing about
50U-Boot pressed a key before the system had time to boot. It's even
51worse on an embedded product that doesn't have a console during
52normal use. The modem plugged into that console port sends a
53character at the wrong time and the system hangs, with no clue as to
54why it isn't working.
55
56You might want the system to autoboot to recover after an external
57configuration program stops autoboot. If the configuration program
58dies or loses its connection (modems can disconnect at the worst
59time) U-Boot will patiently wait forever for it to finish.
60
61These additional configuration options can help provide a system that
62boots when it should, but still allows access to U-Boot.
63
64What they do
65------------
66
67  CONFIG_BOOT_RETRY_TIME
68  CONFIG_BOOT_RETRY_MIN
69
70  "bootretry" environment variable
71
72	These options determine what happens after autoboot is
73	stopped and U-Boot is waiting for commands.
74
75	CONFIG_BOOT_RETRY_TIME must be defined to enable the boot
76	retry feature. If the environment variable "bootretry" is
77	found then its value is used, otherwise the retry timeout is
78	CONFIG_BOOT_RETRY_TIME. CONFIG_BOOT_RETRY_MIN is optional and
79	defaults to CONFIG_BOOT_RETRY_TIME. All times are in seconds.
80
81	If the retry timeout is negative, the U-Boot command prompt
82	never times out. Otherwise it is forced to be at least
83	CONFIG_BOOT_RETRY_MIN seconds. If no valid U-Boot command is
84	entered before the specified time the boot delay sequence is
85	restarted. Each command that U-Boot executes restarts the
86	timeout.
87
88	If CONFIG_BOOT_RETRY_TIME < 0 the feature is there, but
89	doesn't do anything unless the environment variable
90	"bootretry" is >= 0.
91
92  CONFIG_AUTOBOOT_KEYED
93  CONFIG_AUTOBOOT_PROMPT
94  CONFIG_AUTOBOOT_DELAY_STR
95  CONFIG_AUTOBOOT_STOP_STR
96  CONFIG_AUTOBOOT_DELAY_STR2
97  CONFIG_AUTOBOOT_STOP_STR2
98
99  "bootdelaykey"  environment variable
100  "bootstopkey"	  environment variable
101  "bootdelaykey2" environment variable
102  "bootstopkey2"  environment variable
103
104	These options give more control over stopping autoboot. When
105	they are used a specific character or string is required to
106	stop or delay autoboot.
107
108	Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
109	this group of options.	CONFIG_AUTOBOOT_DELAY_STR,
110	CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
111	specified by the corresponding environment variable),
112	otherwise there is no way to stop autoboot.
113
114	CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay
115	selected by CONFIG_BOOTDELAY starts. If it is not defined
116	there is no output indicating that autoboot is in progress.
117
118	Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
119	argument to a printf() call, so it may contain '%' format
120	specifications, provided that it also includes, sepearated by
121	commas exactly like in a printf statement, the required
122	arguments. It is the responsibility of the user to select only
123	such arguments that are valid in the given context. A
124	reasonable prompt could be defined as
125
126		#define CONFIG_AUTOBOOT_PROMPT \
127			"autoboot in %d seconds\n",bootdelay
128
129	If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
130	and this string is received from console input before
131	autoboot starts booting, U-Boot gives a command prompt. The
132	U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
133	used, otherwise it never times out.
134
135	If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
136	this string is received from console input before autoboot
137	starts booting, U-Boot gives a command prompt. The U-Boot
138	prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
139	used.
140
141	The string recognition is not very sophisticated. If a
142	partial match is detected, the first non-matching character
143	is checked to see if starts a new match. There is no check
144	for a shorter partial match, so it's best if the first
145	character of a key string does not appear in the rest of the
146	string.
147
148	Using the CONFIG_AUTOBOOT_DELAY_STR2 #define or the
149	"bootdelaykey2" environment variable and/or the
150	CONFIG_AUTOBOOT_STOP_STR2 #define or the "bootstopkey"
151	environment variable you can specify a second, alternate
152	string (which allows you to have two "password" strings).
153
154  CONFIG_ZERO_BOOTDELAY_CHECK
155
156	If this option is defined, you can stop the autoboot process
157	by hitting a key even in that case when "bootdelay" has been
158	set to 0. You can set "bootdelay" to a negative value to
159	prevent the check for console input.
160
161  CONFIG_RESET_TO_RETRY
162
163	(Only effective when CONFIG_BOOT_RETRY_TIME is also set)
164	After the countdown timed out, the board will be reset to restart
165	again.
166