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