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