README.autoboot 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. SPDX-License-Identifier: GPL-2.0+
  2. /*
  3. * (C) Copyright 2001
  4. * Dave Ellis, SIXNET, dge@sixnetio.com
  5. *
  6. */
  7. Using autoboot configuration options
  8. ====================================
  9. The basic autoboot configuration options are documented in the main
  10. U-Boot README. See it for details. They are:
  11. bootdelay
  12. bootcmd
  13. CONFIG_BOOTDELAY
  14. CONFIG_BOOTCOMMAND
  15. Some additional options that make autoboot safer in a production
  16. product are documented here.
  17. Why use them?
  18. -------------
  19. The basic autoboot feature allows a system to automatically boot to
  20. the real application (such as Linux) without a user having to enter
  21. any commands. If any key is pressed before the boot delay time
  22. expires, U-Boot stops the autoboot process, gives a U-Boot prompt
  23. and waits forever for a command. That's a good thing if you pressed a
  24. key because you wanted to get the prompt.
  25. It's not so good if the key press was a stray character on the
  26. console serial port, say because a user who knows nothing about
  27. U-Boot pressed a key before the system had time to boot. It's even
  28. worse on an embedded product that doesn't have a console during
  29. normal use. The modem plugged into that console port sends a
  30. character at the wrong time and the system hangs, with no clue as to
  31. why it isn't working.
  32. You might want the system to autoboot to recover after an external
  33. configuration program stops autoboot. If the configuration program
  34. dies or loses its connection (modems can disconnect at the worst
  35. time) U-Boot will patiently wait forever for it to finish.
  36. These additional configuration options can help provide a system that
  37. boots when it should, but still allows access to U-Boot.
  38. What they do
  39. ------------
  40. CONFIG_BOOT_RETRY_TIME
  41. CONFIG_BOOT_RETRY_MIN
  42. "bootretry" environment variable
  43. These options determine what happens after autoboot is
  44. stopped and U-Boot is waiting for commands.
  45. CONFIG_BOOT_RETRY_TIME must be defined to enable the boot
  46. retry feature. If the environment variable "bootretry" is
  47. found then its value is used, otherwise the retry timeout is
  48. CONFIG_BOOT_RETRY_TIME. CONFIG_BOOT_RETRY_MIN is optional and
  49. defaults to CONFIG_BOOT_RETRY_TIME. All times are in seconds.
  50. If the retry timeout is negative, the U-Boot command prompt
  51. never times out. Otherwise it is forced to be at least
  52. CONFIG_BOOT_RETRY_MIN seconds. If no valid U-Boot command is
  53. entered before the specified time the boot delay sequence is
  54. restarted. Each command that U-Boot executes restarts the
  55. timeout.
  56. If CONFIG_BOOT_RETRY_TIME < 0 the feature is there, but
  57. doesn't do anything unless the environment variable
  58. "bootretry" is >= 0.
  59. CONFIG_AUTOBOOT_KEYED
  60. CONFIG_AUTOBOOT_KEYED_CTRLC
  61. CONFIG_AUTOBOOT_PROMPT
  62. CONFIG_AUTOBOOT_DELAY_STR
  63. CONFIG_AUTOBOOT_STOP_STR
  64. "bootdelaykey" environment variable
  65. "bootstopkey" environment variable
  66. These options give more control over stopping autoboot. When
  67. they are used a specific character or string is required to
  68. stop or delay autoboot.
  69. Define CONFIG_AUTOBOOT_KEYED (no value required) to enable
  70. this group of options. CONFIG_AUTOBOOT_DELAY_STR,
  71. CONFIG_AUTOBOOT_STOP_STR or both should be specified (or
  72. specified by the corresponding environment variable),
  73. otherwise there is no way to stop autoboot.
  74. CONFIG_AUTOBOOT_PROMPT is displayed before the boot delay
  75. selected by CONFIG_BOOTDELAY starts. If it is not defined
  76. there is no output indicating that autoboot is in progress.
  77. Note that CONFIG_AUTOBOOT_PROMPT is used as the (only)
  78. argument to a printf() call, so it may contain '%' format
  79. specifications, provided that it also includes, sepearated by
  80. commas exactly like in a printf statement, the required
  81. arguments. It is the responsibility of the user to select only
  82. such arguments that are valid in the given context. A
  83. reasonable prompt could be defined as
  84. #define CONFIG_AUTOBOOT_PROMPT \
  85. "autoboot in %d seconds\n",bootdelay
  86. If CONFIG_AUTOBOOT_DELAY_STR or "bootdelaykey" is specified
  87. and this string is received from console input before
  88. autoboot starts booting, U-Boot gives a command prompt. The
  89. U-Boot prompt will time out if CONFIG_BOOT_RETRY_TIME is
  90. used, otherwise it never times out.
  91. If CONFIG_AUTOBOOT_STOP_STR or "bootstopkey" is specified and
  92. this string is received from console input before autoboot
  93. starts booting, U-Boot gives a command prompt. The U-Boot
  94. prompt never times out, even if CONFIG_BOOT_RETRY_TIME is
  95. used.
  96. The string recognition is not very sophisticated. If a
  97. partial match is detected, the first non-matching character
  98. is checked to see if starts a new match. There is no check
  99. for a shorter partial match, so it's best if the first
  100. character of a key string does not appear in the rest of the
  101. string.
  102. The CONFIG_AUTOBOOT_KEYED_CTRLC #define allows for the boot
  103. sequence to be interrupted by ctrl-c, in addition to the
  104. "bootdelaykey" and "bootstopkey". Setting this variable
  105. provides an escape sequence from the limited "password"
  106. strings.
  107. CONFIG_AUTOBOOT_ENCRYPTION
  108. "bootstopkeysha256" environment variable
  109. - Hash value of the input which unlocks the device and
  110. stops autoboot.
  111. This option allows a string to be entered into U-Boot to stop the
  112. autoboot. The string itself is hashed and compared against the hash
  113. in the environment variable 'bootstopkeysha256'. If it matches then
  114. boot stops and a command-line prompt is presented.
  115. This provides a way to ship a secure production device which can also
  116. be accessed at the U-Boot command line.
  117. CONFIG_RESET_TO_RETRY
  118. (Only effective when CONFIG_BOOT_RETRY_TIME is also set)
  119. After the countdown timed out, the board will be reset to restart
  120. again.
  121. CONFIG_AUTOBOOT_USE_MENUKEY
  122. CONFIG_AUTOBOOT_MENUKEY
  123. If this key is pressed to stop autoboot, then the commands in the
  124. environment variable 'menucmd' will be executed before boot starts.
  125. For example, 33 means "!" in ASCII, so pressing ! at boot would take
  126. this action.