[people/ms/u-boot.git] / doc / README.autoboot

/*
 * (C) Copyright 2001
 * Dave Ellis, SIXNET, dge@sixnetio.com
 *
 * SPDX-License-Identifier:	GPL-2.0+ 
 */

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

  "bootretry" environment variable

	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
	retry feature. If the environment variable "bootretry" is
	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
	"bootretry" is >= 0.

  CONFIG_AUTOBOOT_KEYED
  CONFIG_AUTOBOOT_PROMPT
  CONFIG_AUTOBOOT_DELAY_STR
  CONFIG_AUTOBOOT_STOP_STR
  CONFIG_AUTOBOOT_DELAY_STR2
  CONFIG_AUTOBOOT_STOP_STR2

  "bootdelaykey"  environment variable
  "bootstopkey"	  environment variable
  "bootdelaykey2" environment variable
  "bootstopkey2"  environment variable

	These options give more control over stopping autoboot. When
	they are used a specific character or string is required to
	stop or delay autoboot.

	Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
	this group of options.	CONFIG_AUTOBOOT_DELAY_STR,
	CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
	specified by the corresponding environment variable),
	otherwise there is no way to stop autoboot.

	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.

	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

	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.

	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.

	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.

	Using the CONFIG_AUTOBOOT_DELAY_STR2 #define or the
	"bootdelaykey2" environment variable and/or the
	CONFIG_AUTOBOOT_STOP_STR2 #define or the "bootstopkey"
	environment variable you can specify a second, alternate
	string (which allows you to have two "password" strings).

  CONFIG_ZERO_BOOTDELAY_CHECK

	If this option is defined, you can stop the autoboot process
	by hitting a key even in that case when "bootdelay" has been
	set to 0. You can set "bootdelay" to a negative value to
	prevent the check for console input.

  CONFIG_RESET_TO_RETRY

	(Only effective when CONFIG_BOOT_RETRY_TIME is also set)
	After the countdown timed out, the board will be reset to restart
	again.
Commit	Line	Data
cc1c8a13 WD	1	/*
	2	* (C) Copyright 2001
	3	* Dave Ellis, SIXNET, dge@sixnetio.com
	4	*
1a459660	5	* SPDX-License-Identifier: GPL-2.0+
cc1c8a13 WD	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
e1599e83	54	"bootretry" environment variable
cc1c8a13	55
8bde7f77 WD	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
e1599e83	60	retry feature. If the environment variable "bootretry" is
8bde7f77 WD	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
e1599e83	74	"bootretry" is >= 0.
cc1c8a13 WD	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
e1599e83	83	"bootdelaykey" environment variable
8b74bf31	84	"bootstopkey" environment variable
e1599e83 WD	85	"bootdelaykey2" environment variable
e1599e83 WD	86	"bootstopkey2" environment variable
cc1c8a13	87
8bde7f77 WD	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.
cc1c8a13 WD	91
cc1c8a13 WD	92	Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
8b74bf31	93	this group of options. CONFIG_AUTOBOOT_DELAY_STR,
cc1c8a13 WD	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
8bde7f77 WD	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.
f2302d44 SR	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
8bde7f77	112
8b74bf31 WD	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.
8bde7f77	118
8b74bf31 WD	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.
8bde7f77 WD	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
8b74bf31 WD	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).
cc1c8a13 WD	137
	138	CONFIG_ZERO_BOOTDELAY_CHECK
	139
8bde7f77 WD	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.
cc1c8a13 WD	144
	145	CONFIG_RESET_TO_RETRY
	146
8bde7f77 WD	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.