Home | History | Annotate | Download | only in doc
      1 SPDX-License-Identifier: GPL-2.0+
      2 /*
      3  * (C) Copyright 2001
      4  * Dave Ellis, SIXNET, dge (a] sixnetio.com
      5  *
      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   CONFIG_RESET_TO_RETRY
    136 
    137 	(Only effective when CONFIG_BOOT_RETRY_TIME is also set)
    138 	After the countdown timed out, the board will be reset to restart
    139 	again.
    140