[J-u-boot.git] / doc / README.autoboot

/*
 * (C) Copyright 2001
 * Dave Ellis, SIXNET, [email protected]
 *
 * See file CREDITS for list of people who contributed to this
 * project.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 * MA 02111-1307 USA
 */

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.
	If "%d" is included, it is replaced by the number of seconds
	remaining before autoboot will start, but it does not count
	down the seconds. "autoboot in %d seconds\n" is a reasonable
	prompt.

	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 /  bootdelaykey2  and/or
	CONFIG_AUTOBOOT_STOP_STR2   /   bootstopkey  #defines  and/or
	environment variables 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, [email protected]
	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
	24	Using autoboot configuration options
	25	====================================
	26
	27	The basic autoboot configuration options are documented in the main
	28	U-Boot README. See it for details. They are:
	29
	30	bootdelay
	31	bootcmd
	32	CONFIG_BOOTDELAY
	33	CONFIG_BOOTCOMMAND
	34
	35	Some additional options that make autoboot safer in a production
	36	product are documented here.
	37
	38	Why use them?
	39	-------------
	40
	41	The basic autoboot feature allows a system to automatically boot to
	42	the real application (such as Linux) without a user having to enter
	43	any commands. If any key is pressed before the boot delay time
	44	expires, U-Boot stops the autoboot process, gives a U-Boot prompt
	45	and waits forever for a command. That's a good thing if you pressed a
	46	key because you wanted to get the prompt.
	47
	48	It's not so good if the key press was a stray character on the
	49	console serial port, say because a user who knows nothing about
	50	U-Boot pressed a key before the system had time to boot. It's even
	51	worse on an embedded product that doesn't have a console during
	52	normal use. The modem plugged into that console port sends a
	53	character at the wrong time and the system hangs, with no clue as to
	54	why it isn't working.
	55
	56	You might want the system to autoboot to recover after an external
	57	configuration program stops autoboot. If the configuration program
	58	dies or loses its connection (modems can disconnect at the worst
	59	time) U-Boot will patiently wait forever for it to finish.
	60
	61	These additional configuration options can help provide a system that
	62	boots when it should, but still allows access to U-Boot.
	63
	64	What they do
65	------------
66
67	CONFIG_BOOT_RETRY_TIME
68	CONFIG_BOOT_RETRY_MIN
69
70	bootretry environment variable
71
8bde7f77 WD	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.
cc1c8a13 WD	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
8bde7f77 WD	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.
cc1c8a13 WD	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
8bde7f77 WD	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
8564acf9	144	string (which allows you to have two "password" strings).
cc1c8a13 WD	145
	146	CONFIG_ZERO_BOOTDELAY_CHECK
	147
8bde7f77 WD	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.
cc1c8a13 WD	152
	153	CONFIG_RESET_TO_RETRY
	154
8bde7f77 WD	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.