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   CONFIG_AUTOBOOT_DELAY_STR2
  82   CONFIG_AUTOBOOT_STOP_STR2
  83
  84   "bootdelaykey"  environment variable
  85   "bootstopkey"   environment variable
  86   "bootdelaykey2" environment variable
  87   "bootstopkey2"  environment variable
  88
  89         These options give more control over stopping autoboot. When
  90         they are used a specific character or string is required to
  91         stop or delay autoboot.
  92
  93         Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
  94         this group of options.  CONFIG_AUTOBOOT_DELAY_STR,
  95         CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
  96         specified by the corresponding environment variable),
  97         otherwise there is no way to stop autoboot.
  98
  99         CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay
 100         selected by CONFIG_BOOTDELAY starts. If it is not defined
 101         there is no output indicating that autoboot is in progress.
 102
 103         Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
 104         argument to a printf() call, so it may contain '%' format
 105         specifications, provided that it also includes, sepearated by
 106         commas exactly like in a printf statement, the required
 107         arguments. It is the responsibility of the user to select only
 108         such arguments that are valid in the given context. A
 109         reasonable prompt could be defined as
 110
 111                 #define CONFIG_AUTOBOOT_PROMPT \
 112                         "autoboot in %d seconds\n",bootdelay
 113
 114         If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
 115         and this string is received from console input before
 116         autoboot starts booting, U-Boot gives a command prompt. The
 117         U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
 118         used, otherwise it never times out.
 119
 120         If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
 121         this string is received from console input before autoboot
 122         starts booting, U-Boot gives a command prompt. The U-Boot
 123         prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
 124         used.
 125
 126         The string recognition is not very sophisticated. If a
 127         partial match is detected, the first non-matching character
 128         is checked to see if starts a new match. There is no check
 129         for a shorter partial match, so it's best if the first
 130         character of a key string does not appear in the rest of the
 131         string.
 132
 133         Using the CONFIG_AUTOBOOT_DELAY_STR2 #define or the
 134         "bootdelaykey2" environment variable and/or the
 135         CONFIG_AUTOBOOT_STOP_STR2 #define or the "bootstopkey"
 136         environment variable you can specify a second, alternate
 137         string (which allows you to have two "password" strings).
 138
 139         The CONFIG_AUTOBOOT_KEYED_CTRLC #define allows for the boot
 140         sequence to be interrupted by ctrl-c, in addition to the
 141         "bootdelaykey" and "bootstopkey". Setting this variable
 142         provides an escape sequence from the limited "password"
 143         strings.
 144
 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.