doc/README.autoboot

   1 /*
   2  * (C) Copyright 2001
   3  * Dave Ellis, SIXNET, dge@sixnetio.com
   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
  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.
  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
 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.
 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
 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
 118         Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
 119         argument to a printf() call, so it may contain '%' format
 120         specifications, provided that it also includes, sepearated by
 121         commas exactly like in a printf statement, the required
 122         arguments. It is the responsibility of the user to select only
 123         such arguments that are valid in the given context. A
 124         reasonable prompt could be defined as
 125
 126                 #define CONFIG_AUTOBOOT_PROMPT \
 127                         "autoboot in %d seconds\n",bootdelay
 128
 129         If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
 130         and this string is received from console input before
 131         autoboot starts booting, U-Boot gives a command prompt. The
 132         U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
 133         used, otherwise it never times out.
 134
 135         If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
 136         this string is received from console input before autoboot
 137         starts booting, U-Boot gives a command prompt. The U-Boot
 138         prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
 139         used.
 140
 141         The string recognition is not very sophisticated. If a
 142         partial match is detected, the first non-matching character
 143         is checked to see if starts a new match. There is no check
 144         for a shorter partial match, so it's best if the first
 145         character of a key string does not appear in the rest of the
 146         string.
 147
 148         Using the CONFIG_AUTOBOOT_DELAY_STR2 #define or the
 149         "bootdelaykey2" environment variable and/or the
 150         CONFIG_AUTOBOOT_STOP_STR2 #define or the "bootstopkey"
 151         environment variable you can specify a second, alternate
 152         string (which allows you to have two "password" strings).
 153
 154   CONFIG_ZERO_BOOTDELAY_CHECK
 155
 156         If this option is defined, you can stop the autoboot process
 157         by hitting a key even in that case when "bootdelay" has been
 158         set to 0. You can set "bootdelay" to a negative value to
 159         prevent the check for console input.
 160
 161   CONFIG_RESET_TO_RETRY
 162
 163         (Only effective when CONFIG_BOOT_RETRY_TIME is also set)
 164         After the countdown timed out, the board will be reset to restart
 165         again.