environment.rst 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. Environment Variables
  3. =====================
  4. U-Boot supports user configuration using Environment Variables which
  5. can be made persistent by saving to Flash memory.
  6. Environment Variables are set using "setenv", printed using
  7. "printenv", and saved to Flash using "saveenv". Using "setenv"
  8. without a value can be used to delete a variable from the
  9. environment. As long as you don't save the environment you are
  10. working with an in-memory copy. In case the Flash area containing the
  11. environment is erased by accident, a default environment is provided.
  12. Some configuration options can be set using Environment Variables.
  13. Text-based Environment
  14. ----------------------
  15. The default environment for a board is created using a `.env` environment file
  16. using a simple text format. The base filename for this is defined by
  17. `CONFIG_ENV_SOURCE_FILE`, or `CONFIG_SYS_BOARD` if that is empty.
  18. The file must be in the board directory and have a .env extension, so
  19. assuming that there is a board vendor, the resulting filename is therefore::
  20. board/<vendor>/<board>/<CONFIG_ENV_SOURCE_FILE>.env
  21. or::
  22. board/<vendor>/<board>/<CONFIG_SYS_BOARD>.env
  23. This is a plain text file where you can type your environment variables in
  24. the form `var=value`. Blank lines and multi-line variables are supported.
  25. The conversion script looks for a line that starts in column 1 with a string
  26. and has an equals sign immediately afterwards. Spaces before the = are not
  27. permitted. It is a good idea to indent your scripts so that only the 'var='
  28. appears at the start of a line.
  29. To add additional text to a variable you can use `var+=value`. This text is
  30. merged into the variable during the make process and made available as a
  31. single value to U-Boot. Variables can contain `+` characters but in the unlikely
  32. event that you want to have a variable name ending in plus, put a backslash
  33. before the `+` so that the script knows you are not adding to an existing
  34. variable but assigning to a new one::
  35. maximum\+=value
  36. This file can include C-style comments. Blank lines and multi-line
  37. variables are supported, and you can use normal C preprocessor directives
  38. and CONFIG defines from your board config also.
  39. For example, for snapper9260 you would create a text file called
  40. `board/bluewater/snapper9260.env` containing the environment text.
  41. Example::
  42. stdout=serial
  43. #ifdef CONFIG_LCD
  44. stdout+=,lcd
  45. #endif
  46. bootcmd=
  47. /* U-Boot script for booting */
  48. if [ -z ${tftpserverip} ]; then
  49. echo "Use 'setenv tftpserverip a.b.c.d' to set IP address."
  50. fi
  51. usb start; setenv autoload n; bootp;
  52. tftpboot ${tftpserverip}:
  53. bootm
  54. failed=
  55. /* Print a message when boot fails */
  56. echo CONFIG_SYS_BOARD boot failed - please check your image
  57. echo Load address is CONFIG_SYS_LOAD_ADDR
  58. If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then
  59. the old-style C environment is used instead. See below.
  60. Old-style C environment
  61. -----------------------
  62. Traditionally, the default environment is created in `include/env_default.h`,
  63. and can be augmented by various `CONFIG` defines. See that file for details. In
  64. particular you can define `CONFIG_EXTRA_ENV_SETTINGS` in your board file
  65. to add environment variables.
  66. Board maintainers are encouraged to migrate to the text-based environment as it
  67. is easier to maintain. The distro-board script still requires the old-style
  68. environment but work is underway to address this.
  69. List of environment variables
  70. -----------------------------
  71. This is most-likely not complete:
  72. baudrate
  73. see CONFIG_BAUDRATE
  74. bootdelay
  75. see CONFIG_BOOTDELAY
  76. bootcmd
  77. see CONFIG_BOOTCOMMAND
  78. bootargs
  79. Boot arguments when booting an RTOS image
  80. bootfile
  81. Name of the image to load with TFTP
  82. bootm_low
  83. Memory range available for image processing in the bootm
  84. command can be restricted. This variable is given as
  85. a hexadecimal number and defines lowest address allowed
  86. for use by the bootm command. See also "bootm_size"
  87. environment variable. Address defined by "bootm_low" is
  88. also the base of the initial memory mapping for the Linux
  89. kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and
  90. bootm_mapsize.
  91. bootm_mapsize
  92. Size of the initial memory mapping for the Linux kernel.
  93. This variable is given as a hexadecimal number and it
  94. defines the size of the memory region starting at base
  95. address bootm_low that is accessible by the Linux kernel
  96. during early boot. If unset, CONFIG_SYS_BOOTMAPSZ is used
  97. as the default value if it is defined, and bootm_size is
  98. used otherwise.
  99. bootm_size
  100. Memory range available for image processing in the bootm
  101. command can be restricted. This variable is given as
  102. a hexadecimal number and defines the size of the region
  103. allowed for use by the bootm command. See also "bootm_low"
  104. environment variable.
  105. bootstopkeysha256, bootdelaykey, bootstopkey
  106. See README.autoboot
  107. updatefile
  108. Location of the software update file on a TFTP server, used
  109. by the automatic software update feature. Please refer to
  110. documentation in doc/README.update for more details.
  111. autoload
  112. if set to "no" (any string beginning with 'n'),
  113. "bootp" will just load perform a lookup of the
  114. configuration from the BOOTP server, but not try to
  115. load any image using TFTP
  116. autostart
  117. if set to "yes", an image loaded using the "bootp",
  118. "rarpboot", "tftpboot" or "diskboot" commands will
  119. be automatically started (by internally calling
  120. "bootm")
  121. If set to "no", a standalone image passed to the
  122. "bootm" command will be copied to the load address
  123. (and eventually uncompressed), but NOT be started.
  124. This can be used to load and uncompress arbitrary
  125. data.
  126. fdt_high
  127. if set this restricts the maximum address that the
  128. flattened device tree will be copied into upon boot.
  129. For example, if you have a system with 1 GB memory
  130. at physical address 0x10000000, while Linux kernel
  131. only recognizes the first 704 MB as low memory, you
  132. may need to set fdt_high as 0x3C000000 to have the
  133. device tree blob be copied to the maximum address
  134. of the 704 MB low memory, so that Linux kernel can
  135. access it during the boot procedure.
  136. If this is set to the special value 0xFFFFFFFF then
  137. the fdt will not be copied at all on boot. For this
  138. to work it must reside in writable memory, have
  139. sufficient padding on the end of it for u-boot to
  140. add the information it needs into it, and the memory
  141. must be accessible by the kernel.
  142. fdtcontroladdr
  143. if set this is the address of the control flattened
  144. device tree used by U-Boot when CONFIG_OF_CONTROL is
  145. defined.
  146. initrd_high
  147. restrict positioning of initrd images:
  148. If this variable is not set, initrd images will be
  149. copied to the highest possible address in RAM; this
  150. is usually what you want since it allows for
  151. maximum initrd size. If for some reason you want to
  152. make sure that the initrd image is loaded below the
  153. CONFIG_SYS_BOOTMAPSZ limit, you can set this environment
  154. variable to a value of "no" or "off" or "0".
  155. Alternatively, you can set it to a maximum upper
  156. address to use (U-Boot will still check that it
  157. does not overwrite the U-Boot stack and data).
  158. For instance, when you have a system with 16 MB
  159. RAM, and want to reserve 4 MB from use by Linux,
  160. you can do this by adding "mem=12M" to the value of
  161. the "bootargs" variable. However, now you must make
  162. sure that the initrd image is placed in the first
  163. 12 MB as well - this can be done with::
  164. setenv initrd_high 00c00000
  165. If you set initrd_high to 0xFFFFFFFF, this is an
  166. indication to U-Boot that all addresses are legal
  167. for the Linux kernel, including addresses in flash
  168. memory. In this case U-Boot will NOT COPY the
  169. ramdisk at all. This may be useful to reduce the
  170. boot time on your system, but requires that this
  171. feature is supported by your Linux kernel.
  172. ipaddr
  173. IP address; needed for tftpboot command
  174. loadaddr
  175. Default load address for commands like "bootp",
  176. "rarpboot", "tftpboot", "loadb" or "diskboot"
  177. loads_echo
  178. see CONFIG_LOADS_ECHO
  179. serverip
  180. TFTP server IP address; needed for tftpboot command
  181. bootretry
  182. see CONFIG_BOOT_RETRY_TIME
  183. bootdelaykey
  184. see CONFIG_AUTOBOOT_DELAY_STR
  185. bootstopkey
  186. see CONFIG_AUTOBOOT_STOP_STR
  187. ethprime
  188. controls which interface is used first.
  189. ethact
  190. controls which interface is currently active.
  191. For example you can do the following::
  192. => setenv ethact FEC
  193. => ping 192.168.0.1 # traffic sent on FEC
  194. => setenv ethact SCC
  195. => ping 10.0.0.1 # traffic sent on SCC
  196. ethrotate
  197. When set to "no" U-Boot does not go through all
  198. available network interfaces.
  199. It just stays at the currently selected interface.
  200. netretry
  201. When set to "no" each network operation will
  202. either succeed or fail without retrying.
  203. When set to "once" the network operation will
  204. fail when all the available network interfaces
  205. are tried once without success.
  206. Useful on scripts which control the retry operation
  207. themselves.
  208. npe_ucode
  209. set load address for the NPE microcode
  210. silent_linux
  211. If set then Linux will be told to boot silently, by
  212. changing the console to be empty. If "yes" it will be
  213. made silent. If "no" it will not be made silent. If
  214. unset, then it will be made silent if the U-Boot console
  215. is silent.
  216. tftpsrcp
  217. If this is set, the value is used for TFTP's
  218. UDP source port.
  219. tftpdstp
  220. If this is set, the value is used for TFTP's UDP
  221. destination port instead of the Well Know Port 69.
  222. tftpblocksize
  223. Block size to use for TFTP transfers; if not set,
  224. we use the TFTP server's default block size
  225. tftptimeout
  226. Retransmission timeout for TFTP packets (in milli-
  227. seconds, minimum value is 1000 = 1 second). Defines
  228. when a packet is considered to be lost so it has to
  229. be retransmitted. The default is 5000 = 5 seconds.
  230. Lowering this value may make downloads succeed
  231. faster in networks with high packet loss rates or
  232. with unreliable TFTP servers.
  233. tftptimeoutcountmax
  234. maximum count of TFTP timeouts (no
  235. unit, minimum value = 0). Defines how many timeouts
  236. can happen during a single file transfer before that
  237. transfer is aborted. The default is 10, and 0 means
  238. 'no timeouts allowed'. Increasing this value may help
  239. downloads succeed with high packet loss rates, or with
  240. unreliable TFTP servers or client hardware.
  241. tftpwindowsize
  242. if this is set, the value is used for TFTP's
  243. window size as described by RFC 7440.
  244. This means the count of blocks we can receive before
  245. sending ack to server.
  246. vlan
  247. When set to a value < 4095 the traffic over
  248. Ethernet is encapsulated/received over 802.1q
  249. VLAN tagged frames.
  250. bootpretryperiod
  251. Period during which BOOTP/DHCP sends retries.
  252. Unsigned value, in milliseconds. If not set, the period will
  253. be either the default (28000), or a value based on
  254. CONFIG_NET_RETRY_COUNT, if defined. This value has
  255. precedence over the valu based on CONFIG_NET_RETRY_COUNT.
  256. memmatches
  257. Number of matches found by the last 'ms' command, in hex
  258. memaddr
  259. Address of the last match found by the 'ms' command, in hex,
  260. or 0 if none
  261. mempos
  262. Index position of the last match found by the 'ms' command,
  263. in units of the size (.b, .w, .l) of the search
  264. zbootbase
  265. (x86 only) Base address of the bzImage 'setup' block
  266. zbootaddr
  267. (x86 only) Address of the loaded bzImage, typically
  268. BZIMAGE_LOAD_ADDR which is 0x100000
  269. Image locations
  270. ---------------
  271. The following image location variables contain the location of images
  272. used in booting. The "Image" column gives the role of the image and is
  273. not an environment variable name. The other columns are environment
  274. variable names. "File Name" gives the name of the file on a TFTP
  275. server, "RAM Address" gives the location in RAM the image will be
  276. loaded to, and "Flash Location" gives the image's address in NOR
  277. flash or offset in NAND flash.
  278. *Note* - these variables don't have to be defined for all boards, some
  279. boards currently use other variables for these purposes, and some
  280. boards use these variables for other purposes.
  281. ================= ============== ================ ==============
  282. Image File Name RAM Address Flash Location
  283. ================= ============== ================ ==============
  284. u-boot u-boot u-boot_addr_r u-boot_addr
  285. Linux kernel bootfile kernel_addr_r kernel_addr
  286. device tree blob fdtfile fdt_addr_r fdt_addr
  287. ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr
  288. ================= ============== ================ ==============
  289. Automatically updated variables
  290. -------------------------------
  291. The following environment variables may be used and automatically
  292. updated by the network boot commands ("bootp" and "rarpboot"),
  293. depending the information provided by your boot server:
  294. ========= ===================================================
  295. Variable Notes
  296. ========= ===================================================
  297. bootfile see above
  298. dnsip IP address of your Domain Name Server
  299. dnsip2 IP address of your secondary Domain Name Server
  300. gatewayip IP address of the Gateway (Router) to use
  301. hostname Target hostname
  302. ipaddr See above
  303. netmask Subnet Mask
  304. rootpath Pathname of the root filesystem on the NFS server
  305. serverip see above
  306. ========= ===================================================
  307. Special environment variables
  308. -----------------------------
  309. There are two special Environment Variables:
  310. serial#
  311. contains hardware identification information such as type string and/or
  312. serial number
  313. ethaddr
  314. Ethernet address
  315. These variables can be set only once (usually during manufacturing of
  316. the board). U-Boot refuses to delete or overwrite these variables
  317. once they have been set once.
  318. Also:
  319. ver
  320. Contains the U-Boot version string as printed
  321. with the "version" command. This variable is
  322. readonly (see CONFIG_VERSION_VARIABLE).
  323. Please note that changes to some configuration parameters may take
  324. only effect after the next boot (yes, that's just like Windoze :-).
  325. Callback functions for environment variables
  326. --------------------------------------------
  327. For some environment variables, the behavior of u-boot needs to change
  328. when their values are changed. This functionality allows functions to
  329. be associated with arbitrary variables. On creation, overwrite, or
  330. deletion, the callback will provide the opportunity for some side
  331. effect to happen or for the change to be rejected.
  332. The callbacks are named and associated with a function using the
  333. U_BOOT_ENV_CALLBACK macro in your board or driver code.
  334. These callbacks are associated with variables in one of two ways. The
  335. static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
  336. in the board configuration to a string that defines a list of
  337. associations. The list must be in the following format::
  338. entry = variable_name[:callback_name]
  339. list = entry[,list]
  340. If the callback name is not specified, then the callback is deleted.
  341. Spaces are also allowed anywhere in the list.
  342. Callbacks can also be associated by defining the ".callbacks" variable
  343. with the same list format above. Any association in ".callbacks" will
  344. override any association in the static list. You can define
  345. CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
  346. ".callbacks" environment variable in the default or embedded environment.
  347. If CONFIG_REGEX is defined, the variable_name above is evaluated as a
  348. regular expression. This allows multiple variables to be connected to
  349. the same callback without explicitly listing them all out.
  350. The signature of the callback functions is::
  351. int callback(const char *name, const char *value, enum env_op op, int flags)
  352. * name - changed environment variable
  353. * value - new value of the environment variable
  354. * op - operation (create, overwrite, or delete)
  355. * flags - attributes of the environment variable change, see flags H_* in
  356. include/search.h
  357. The return value is 0 if the variable change is accepted and 1 otherwise.