xref: /openbmc/u-boot/doc/README.autoboot (revision 5b1d7137)
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        If "%d" is included, it is replaced by the number of seconds
118        remaining before autoboot will start, but it does not count
119        down the seconds. "autoboot in %d seconds\n" is a reasonable
120        prompt.
121
122        If CONFIG_AUTOBOOT_DELAY_STR or bootdelaykey is specified and
123        this string is received from console input before autoboot
124        starts booting, U-Boot gives a command prompt. The U-Boot
125        prompt will time out if CONFIG_BOOT_RETRY_TIME is used,
126        otherwise it never times out.
127
128        If CONFIG_AUTOBOOT_STOP_STR or bootstopkey is specified and
129        this string is received from console input before autoboot
130        starts booting, U-Boot gives a command prompt. The U-Boot
131        prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
132        used.
133
134        The string recognition is not very sophisticated. If a
135        partial match is detected, the first non-matching character
136        is checked to see if starts a new match. There is no check
137        for a shorter partial match, so it's best if the first
138        character of a key string does not appear in the rest of the
139        string.
140
141        Using the CONFIG_AUTOBOOT_DELAY_STR2 /  bootdelaykey2  and/or
142        CONFIG_AUTOBOOT_STOP_STR2   /   bootstopkey  #defines  and/or
143        environment variables you can  specify  a  second,  alternate
144        string (which allows you to haw two "password" strings).
145
146  CONFIG_ZERO_BOOTDELAY_CHECK
147
148        If this option is defined, you can stop the autoboot process
149        by hitting a key even in that case when "bootdelay" has been
150        set to 0. You can set "bootdelay" to a negative value to
151        prevent the check for console input.
152
153  CONFIG_RESET_TO_RETRY
154
155        (Only effective when CONFIG_BOOT_RETRY_TIME is also set)
156        After the countdown timed out, the board will be reset to restart
157        again.
158
159