doc/usage/environment.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Environment Variables
   4 =====================
   5
   6 U-Boot supports user configuration using environment variables which
   7 can be made persistent by saving to persistent storage, for example flash
   8 memory.
   9
  10 Environment variables are set using "env set" (alias "setenv"), printed using
  11 "env print" (alias "printenv"), and saved to persistent storage using
  12 "env save" (alias "saveenv"). Using "env set"
  13 without a value can be used to delete a variable from the
  14 environment. As long as you don't save the environment, you are
  15 working with an in-memory copy. In case the Flash area containing the
  16 environment is erased by accident, a default environment is provided.
  17
  18 See :doc:`cmd/env` for details.
  19
  20 Some configuration is controlled by Environment Variables, so that setting the
  21 variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading
  22 from tftp).
  23
  24 Text-based Environment
  25 ----------------------
  26
  27 The default environment for a board is created using a `.env` environment file
  28 using a simple text format. The base filename for this is defined by
  29 `CONFIG_ENV_SOURCE_FILE`, or `CONFIG_SYS_BOARD` if that is empty.
  30
  31 The file must be in the board directory and have a .env extension, so
  32 assuming that there is a board vendor, the resulting filename is therefore::
  33
  34    board/<vendor>/<board>/<CONFIG_ENV_SOURCE_FILE>.env
  35
  36 or::
  37
  38    board/<vendor>/<board>/<CONFIG_SYS_BOARD>.env
  39
  40 This is a plain text file where you can type your environment variables in
  41 the form `var=value`. Blank lines and multi-line variables are supported.
  42 The conversion script looks for a line that starts in column 1 with a string
  43 and has an equals sign immediately afterwards. Spaces before the = are not
  44 permitted. It is a good idea to indent your scripts so that only the 'var='
  45 appears at the start of a line.
  46
  47 To add additional text to a variable you can use `var+=value`. This text is
  48 merged into the variable during the make process and made available as a
  49 single value to U-Boot. Variables can contain `+` characters but in the unlikely
  50 event that you want to have a variable name ending in plus, put a backslash
  51 before the `+` so that the script knows you are not adding to an existing
  52 variable but assigning to a new one::
  53
  54     maximum\+=value
  55
  56 This file can include C-style comments. Blank lines and multi-line
  57 variables are supported, and you can use normal C preprocessor directives
  58 and CONFIG defines from your board config also.
  59
  60 For example, for snapper9260 you would create a text file called
  61 `board/bluewater/snapper9260.env` containing the environment text.
  62
  63 Example::
  64
  65     stdout=serial
  66     #ifdef CONFIG_LCD
  67     stdout+=,lcd
  68     #endif
  69     bootcmd=
  70         /* U-Boot script for booting */
  71
  72         if [ -z ${tftpserverip} ]; then
  73             echo "Use 'setenv tftpserverip a.b.c.d' to set IP address."
  74         fi
  75
  76         usb start; setenv autoload n; bootp;
  77         tftpboot ${tftpserverip}:
  78         bootm
  79     failed=
  80         /* Print a message when boot fails */
  81         echo CONFIG_SYS_BOARD boot failed - please check your image
  82         echo Load address is CONFIG_SYS_LOAD_ADDR
  83
  84 If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then
  85 the old-style C environment is used instead. See below.
  86
  87 Old-style C environment
  88 -----------------------
  89
  90 Traditionally, the default environment is created in `include/env_default.h`,
  91 and can be augmented by various `CONFIG` defines. See that file for details. In
  92 particular you can define `CONFIG_EXTRA_ENV_SETTINGS` in your board file
  93 to add environment variables.
  94
  95 Board maintainers are encouraged to migrate to the text-based environment as it
  96 is easier to maintain. The distro-board script still requires the old-style
  97 environment but work is underway to address this.
  98
  99
 100 List of environment variables
 101 -----------------------------
 102
 103 Some device configuration options can be set using environment variables. In
 104 many cases the value in the default environment comes from a CONFIG option - see
 105 `include/env_default.h`) for this.
 106
 107 This is most-likely not complete:
 108
 109 baudrate
 110     Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRATE (which
 111     defaults to 115200).
 112
 113 bootdelay
 114     Delay before automatically running bootcmd. During this time the user
 115     can choose to enter the shell (or the boot menu if
 116     CONFIG_AUTOBOOT_MENU_SHOW=y):
 117
 118     - 0 to autoboot with no delay, but you can stop it by key input.
 119     - -1 to disable autoboot.
 120     - -2 to autoboot with no delay and not check for abort
 121
 122     The default value is defined by CONFIG_BOOTDELAY.
 123     The value of 'bootdelay' is overridden by the /config/bootdelay value in
 124     the device-tree if CONFIG_OF_CONTROL=y.
 125
 126 bootcmd
 127     The command that is run if the user does not enter the shell during the
 128     boot delay.
 129
 130 bootargs
 131     Command line arguments passed when booting an operating system or binary
 132     image
 133
 134 bootfile
 135     Name of the image to load with TFTP
 136
 137 bootm_low
 138     Memory range available for image processing in the bootm
 139     command can be restricted. This variable is given as
 140     a hexadecimal number and defines lowest address allowed
 141     for use by the bootm command. See also "bootm_size"
 142     environment variable. Address defined by "bootm_low" is
 143     also the base of the initial memory mapping for the Linux
 144     kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and
 145     bootm_mapsize.
 146
 147 bootm_mapsize
 148     Size of the initial memory mapping for the Linux kernel.
 149     This variable is given as a hexadecimal number and it
 150     defines the size of the memory region starting at base
 151     address bootm_low that is accessible by the Linux kernel
 152     during early boot.  If unset, CONFIG_SYS_BOOTMAPSZ is used
 153     as the default value if it is defined, and bootm_size is
 154     used otherwise.
 155
 156 bootm_size
 157     Memory range available for image processing in the bootm
 158     command can be restricted. This variable is given as
 159     a hexadecimal number and defines the size of the region
 160     allowed for use by the bootm command. See also "bootm_low"
 161     environment variable.
 162
 163 bootstopkeysha256, bootdelaykey, bootstopkey
 164     See README.autoboot
 165
 166 updatefile
 167     Location of the software update file on a TFTP server, used
 168     by the automatic software update feature. Please refer to
 169     documentation in doc/README.update for more details.
 170
 171 autoload
 172     if set to "no" (any string beginning with 'n'),
 173     "bootp" and "dhcp" will just load perform a lookup of the
 174     configuration from the BOOTP server, but not try to
 175     load any image.
 176
 177 autostart
 178     if set to "yes", an image loaded using the "bootp", "dhcp",
 179     "rarpboot", "tftpboot" or "diskboot" commands will
 180     be automatically started (by internally calling
 181     "bootm")
 182
 183     If unset, or set to "1"/"yes"/"true" (case insensitive, just the first
 184     character is enough), a standalone image
 185     passed to the "bootm" command will be copied to the load address
 186     (and eventually uncompressed), but NOT be started.
 187     This can be used to load and uncompress arbitrary
 188     data.
 189
 190 fdt_high
 191     if set this restricts the maximum address that the
 192     flattened device tree will be copied into upon boot.
 193     For example, if you have a system with 1 GB memory
 194     at physical address 0x10000000, while Linux kernel
 195     only recognizes the first 704 MB as low memory, you
 196     may need to set fdt_high as 0x3C000000 to have the
 197     device tree blob be copied to the maximum address
 198     of the 704 MB low memory, so that Linux kernel can
 199     access it during the boot procedure.
 200
 201     If this is set to the special value 0xffffffff (32-bit machines) or
 202     0xffffffffffffffff (64-bit machines) then
 203     the fdt will not be copied at all on boot.  For this
 204     to work it must reside in writable memory, have
 205     sufficient padding on the end of it for u-boot to
 206     add the information it needs into it, and the memory
 207     must be accessible by the kernel.
 208
 209 fdtcontroladdr
 210     if set this is the address of the control flattened
 211     device tree used by U-Boot when CONFIG_OF_CONTROL is
 212     defined.
 213
 214 initrd_high
 215     restrict positioning of initrd images:
 216     If this variable is not set, initrd images will be
 217     copied to the highest possible address in RAM; this
 218     is usually what you want since it allows for
 219     maximum initrd size. If for some reason you want to
 220     make sure that the initrd image is loaded below the
 221     CONFIG_SYS_BOOTMAPSZ limit, you can set this environment
 222     variable to a value of "no" or "off" or "0".
 223     Alternatively, you can set it to a maximum upper
 224     address to use (U-Boot will still check that it
 225     does not overwrite the U-Boot stack and data).
 226
 227     For instance, when you have a system with 16 MB
 228     RAM, and want to reserve 4 MB from use by Linux,
 229     you can do this by adding "mem=12M" to the value of
 230     the "bootargs" variable. However, now you must make
 231     sure that the initrd image is placed in the first
 232     12 MB as well - this can be done with::
 233
 234         setenv initrd_high 00c00000
 235
 236     If you set initrd_high to 0xffffffff (32-bit machines) or
 237     0xffffffffffffffff (64-bit machines), this is an
 238     indication to U-Boot that all addresses are legal
 239     for the Linux kernel, including addresses in flash
 240     memory. In this case U-Boot will NOT COPY the
 241     ramdisk at all. This may be useful to reduce the
 242     boot time on your system, but requires that this
 243     feature is supported by your Linux kernel.
 244
 245 ipaddr
 246     IP address; needed for tftpboot command
 247
 248 loadaddr
 249     Default load address for commands like "bootp",
 250     "rarpboot", "tftpboot", "loadb" or "diskboot"
 251
 252 loads_echo
 253     see CONFIG_LOADS_ECHO
 254
 255 serverip
 256     TFTP server IP address; needed for tftpboot command
 257
 258 bootretry
 259     see CONFIG_BOOT_RETRY_TIME
 260
 261 bootdelaykey
 262     see CONFIG_AUTOBOOT_DELAY_STR
 263
 264 bootstopkey
 265     see CONFIG_AUTOBOOT_STOP_STR
 266
 267 ethprime
 268     controls which network interface is used first.
 269
 270 ethact
 271     controls which interface is currently active.
 272     For example you can do the following::
 273
 274     => setenv ethact FEC
 275     => ping 192.168.0.1 # traffic sent on FEC
 276     => setenv ethact SCC
 277     => ping 10.0.0.1 # traffic sent on SCC
 278
 279 ethrotate
 280     When set to "no" U-Boot does not go through all
 281     available network interfaces.
 282     It just stays at the currently selected interface. When unset or set to
 283     anything other than "no", U-Boot does go through all
 284     available network interfaces.
 285
 286 netretry
 287     When set to "no" each network operation will
 288     either succeed or fail without retrying.
 289     When set to "once" the network operation will
 290     fail when all the available network interfaces
 291     are tried once without success.
 292     Useful on scripts which control the retry operation
 293     themselves.
 294
 295 silent_linux
 296     If set then Linux will be told to boot silently, by
 297     adding 'console=' to its command line. If "yes" it will be
 298     made silent. If "no" it will not be made silent. If
 299     unset, then it will be made silent if the U-Boot console
 300     is silent.
 301
 302 tftpsrcp
 303     If this is set, the value is used for TFTP's
 304     UDP source port.
 305
 306 tftpdstp
 307     If this is set, the value is used for TFTP's UDP
 308     destination port instead of the default port 69.
 309
 310 tftpblocksize
 311     Block size to use for TFTP transfers; if not set,
 312     we use the TFTP server's default block size
 313
 314 tftptimeout
 315     Retransmission timeout for TFTP packets (in milli-
 316     seconds, minimum value is 1000 = 1 second). Defines
 317     when a packet is considered to be lost so it has to
 318     be retransmitted. The default is 5000 = 5 seconds.
 319     Lowering this value may make downloads succeed
 320     faster in networks with high packet loss rates or
 321     with unreliable TFTP servers.
 322
 323 tftptimeoutcountmax
 324     maximum count of TFTP timeouts (no
 325     unit, minimum value = 0). Defines how many timeouts
 326     can happen during a single file transfer before that
 327     transfer is aborted. The default is 10, and 0 means
 328     'no timeouts allowed'. Increasing this value may help
 329     downloads succeed with high packet loss rates, or with
 330     unreliable TFTP servers or client hardware.
 331
 332 tftpwindowsize
 333     if this is set, the value is used for TFTP's
 334     window size as described by RFC 7440.
 335     This means the count of blocks we can receive before
 336     sending ack to server.
 337
 338 vlan
 339     When set to a value < 4095 the traffic over
 340     Ethernet is encapsulated/received over 802.1q
 341     VLAN tagged frames.
 342
 343     Note: This appears not to be used in U-Boot. See `README.VLAN`.
 344
 345 bootpretryperiod
 346     Period during which BOOTP/DHCP sends retries.
 347     Unsigned value, in milliseconds. If not set, the period will
 348     be either the default (28000), or a value based on
 349     CONFIG_NET_RETRY_COUNT, if defined. This value has
 350     precedence over the value based on CONFIG_NET_RETRY_COUNT.
 351
 352 memmatches
 353     Number of matches found by the last 'ms' command, in hex
 354
 355 memaddr
 356     Address of the last match found by the 'ms' command, in hex,
 357     or 0 if none
 358
 359 mempos
 360     Index position of the last match found by the 'ms' command,
 361     in units of the size (.b, .w, .l) of the search
 362
 363 zbootbase
 364     (x86 only) Base address of the bzImage 'setup' block
 365
 366 zbootaddr
 367     (x86 only) Address of the loaded bzImage, typically
 368     BZIMAGE_LOAD_ADDR which is 0x100000
 369
 370
 371 Image locations
 372 ---------------
 373
 374 The following image location variables contain the location of images
 375 used in booting. The "Image" column gives the role of the image and is
 376 not an environment variable name. The other columns are environment
 377 variable names. "File Name" gives the name of the file on a TFTP
 378 server, "RAM Address" gives the location in RAM the image will be
 379 loaded to, and "Flash Location" gives the image's address in NOR
 380 flash or offset in NAND flash.
 381
 382 *Note* - these variables don't have to be defined for all boards, some
 383 boards currently use other variables for these purposes, and some
 384 boards use these variables for other purposes.
 385
 386 Also note that most of these variables are just a commonly used set of variable
 387 names, used in some other variable definitions, but are not hard-coded anywhere
 388 in U-Boot code.
 389
 390 ================= ============== ================ ==============
 391 Image             File Name      RAM Address      Flash Location
 392 ================= ============== ================ ==============
 393 Linux kernel      bootfile       kernel_addr_r    kernel_addr
 394 device tree blob  fdtfile        fdt_addr_r       fdt_addr
 395 ramdisk           ramdiskfile    ramdisk_addr_r   ramdisk_addr
 396 ================= ============== ================ ==============
 397
 398
 399 Automatically updated variables
 400 -------------------------------
 401
 402 The following environment variables may be used and automatically
 403 updated by the network boot commands ("bootp" and "rarpboot"),
 404 depending the information provided by your boot server:
 405
 406 =========  ===================================================
 407 Variable   Notes
 408 =========  ===================================================
 409 bootfile   see above
 410 dnsip      IP address of your Domain Name Server
 411 dnsip2     IP address of your secondary Domain Name Server
 412 gatewayip  IP address of the Gateway (Router) to use
 413 hostname   Target hostname
 414 ipaddr     See above
 415 netmask    Subnet Mask
 416 rootpath   Pathname of the root filesystem on the NFS server
 417 serverip   see above
 418 =========  ===================================================
 419
 420
 421 Special environment variables
 422 -----------------------------
 423
 424 There are two special Environment Variables:
 425
 426 serial#
 427     contains hardware identification information such as type string and/or
 428     serial number
 429 ethaddr
 430     Ethernet address. If CONFIG_REGEX=y, also eth*addr (where * is an integer).
 431
 432 These variables can be set only once (usually during manufacturing of
 433 the board). U-Boot refuses to delete or overwrite these variables
 434 once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the board
 435 configuration.
 436
 437 Also:
 438
 439 ver
 440     Contains the U-Boot version string as printed
 441     with the "version" command. This variable is
 442     readonly (see CONFIG_VERSION_VARIABLE).
 443
 444 Please note that changes to some configuration parameters may take
 445 only effect after the next boot (yes, that's just like Windows).
 446
 447
 448 External environment file
 449 -------------------------
 450
 451 The `CONFIG_USE_DEFAULT_ENV_FILE` option provides a way to bypass the
 452 environment generation in U-Boot. If enabled, then `CONFIG_DEFAULT_ENV_FILE`
 453 provides the name of a file which is converted into the environment,
 454 completely bypassing the standard environment variables in `env_default.h`.
 455
 456 The format is the same as accepted by the mkenvimage tool, with lines containing
 457 key=value pairs. Blank lines and lines beginning with # are ignored.
 458
 459 Future work may unify this feature with the text-based environment, perhaps
 460 moving the contents of `env_default.h` to a text file.
 461
 462 Implementation
 463 --------------
 464
 465 See :doc:`../develop/environment` for internal development details.