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