blob: 91dc07b17bce42bf929dedb7f9ce48bc3dc56961 [file] [log] [blame]
Simon Glassaef523a2021-10-21 21:08:45 -06001.. SPDX-License-Identifier: GPL-2.0+
2
3Environment Variables
4=====================
5
Simon Glass420febd2021-10-21 21:08:50 -06006U-Boot supports user configuration using environment variables which
Simon Glass341c7ea2021-10-21 21:08:49 -06007can be made persistent by saving to persistent storage, for example flash
8memory.
Simon Glassaef523a2021-10-21 21:08:45 -06009
Simon Glass420febd2021-10-21 21:08:50 -060010Environment variables are set using "env set" (alias "setenv"), printed using
Simon Glass341c7ea2021-10-21 21:08:49 -060011"env print" (alias "printenv"), and saved to persistent storage using
12"env save" (alias "saveenv"). Using "env set"
Simon Glassaef523a2021-10-21 21:08:45 -060013without a value can be used to delete a variable from the
Simon Glass341c7ea2021-10-21 21:08:49 -060014environment. As long as you don't save the environment, you are
Simon Glassaef523a2021-10-21 21:08:45 -060015working with an in-memory copy. In case the Flash area containing the
16environment is erased by accident, a default environment is provided.
17
Patrick Delaunayaa5f43a2022-04-14 19:07:05 +020018See :doc:`cmd/env` for details.
19
Simon Glass341c7ea2021-10-21 21:08:49 -060020Some configuration is controlled by Environment Variables, so that setting the
21variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading
22from tftp).
Simon Glassaef523a2021-10-21 21:08:45 -060023
Simon Glass7327fe72021-10-21 21:08:46 -060024Text-based Environment
25----------------------
26
27The default environment for a board is created using a `.env` environment file
28using 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
31The file must be in the board directory and have a .env extension, so
32assuming that there is a board vendor, the resulting filename is therefore::
33
34 board/<vendor>/<board>/<CONFIG_ENV_SOURCE_FILE>.env
35
36or::
37
38 board/<vendor>/<board>/<CONFIG_SYS_BOARD>.env
39
40This is a plain text file where you can type your environment variables in
41the form `var=value`. Blank lines and multi-line variables are supported.
42The conversion script looks for a line that starts in column 1 with a string
43and has an equals sign immediately afterwards. Spaces before the = are not
44permitted. It is a good idea to indent your scripts so that only the 'var='
45appears at the start of a line.
46
47To add additional text to a variable you can use `var+=value`. This text is
48merged into the variable during the make process and made available as a
49single value to U-Boot. Variables can contain `+` characters but in the unlikely
50event that you want to have a variable name ending in plus, put a backslash
51before the `+` so that the script knows you are not adding to an existing
52variable but assigning to a new one::
53
54 maximum\+=value
55
56This file can include C-style comments. Blank lines and multi-line
57variables are supported, and you can use normal C preprocessor directives
58and CONFIG defines from your board config also.
59
60For example, for snapper9260 you would create a text file called
61`board/bluewater/snapper9260.env` containing the environment text.
62
63Example::
64
65 stdout=serial
Simon Glass52cb5042022-10-18 07:46:31 -060066 #ifdef CONFIG_VIDEO
Simon Glass395bcf22022-10-16 15:59:22 -060067 stdout+=,vidconsole
Simon Glass7327fe72021-10-21 21:08:46 -060068 #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
84If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then
85the old-style C environment is used instead. See below.
86
87Old-style C environment
88-----------------------
89
90Traditionally, the default environment is created in `include/env_default.h`,
91and can be augmented by various `CONFIG` defines. See that file for details. In
Tom Rinic9edebe2022-12-04 10:03:50 -050092particular you can define `CFG_EXTRA_ENV_SETTINGS` in your board file
Simon Glass7327fe72021-10-21 21:08:46 -060093to add environment variables.
94
95Board maintainers are encouraged to migrate to the text-based environment as it
96is easier to maintain. The distro-board script still requires the old-style
Simon Glassb0eba692023-07-30 21:01:44 -060097environments, so use :doc:`../develop/bootstd` instead.
Simon Glass7327fe72021-10-21 21:08:46 -060098
99
100List of environment variables
101-----------------------------
102
Simon Glass420febd2021-10-21 21:08:50 -0600103Some device configuration options can be set using environment variables. In
104many cases the value in the default environment comes from a CONFIG option - see
Simon Glass341c7ea2021-10-21 21:08:49 -0600105`include/env_default.h`) for this.
106
Simon Glass7327fe72021-10-21 21:08:46 -0600107This is most-likely not complete:
Simon Glassaef523a2021-10-21 21:08:45 -0600108
Heinrich Schuchardtaa5ffb32022-09-10 09:16:37 +0200109autostart
110 If set to "yes" (actually any string starting with 1, y, Y, t, or T) an
111 image loaded with one of the commands listed below will be automatically
112 started by internally invoking the bootm command.
113
114 * bootelf - Boot from an ELF image in memory
115 * bootp - boot image via network using BOOTP/TFTP protocol
116 * dhcp - boot image via network using DHCP/TFTP protocol
117 * diskboot - boot from ide device
118 * nboot - boot from NAND device
119 * nfs - boot image via network using NFS protocol
120 * rarpboot - boot image via network using RARP/TFTP protocol
121 * scsiboot - boot from SCSI device
122 * tftpboot - boot image via network using TFTP protocol
123 * usbboot - boot from USB device
124
125 If the environment variable autostart is not set to a value starting with
126 1, y, Y, t, or T, an image passed to the "bootm" command will be copied to
127 the load address (and eventually uncompressed), but NOT be started.
128 This can be used to load and uncompress arbitrary data.
129
Simon Glassaef523a2021-10-21 21:08:45 -0600130baudrate
Simon Glass420febd2021-10-21 21:08:50 -0600131 Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRATE (which
132 defaults to 115200).
Simon Glassaef523a2021-10-21 21:08:45 -0600133
134bootdelay
Simon Glass420febd2021-10-21 21:08:50 -0600135 Delay before automatically running bootcmd. During this time the user
136 can choose to enter the shell (or the boot menu if
137 CONFIG_AUTOBOOT_MENU_SHOW=y):
138
139 - 0 to autoboot with no delay, but you can stop it by key input.
140 - -1 to disable autoboot.
141 - -2 to autoboot with no delay and not check for abort
142
143 The default value is defined by CONFIG_BOOTDELAY.
144 The value of 'bootdelay' is overridden by the /config/bootdelay value in
145 the device-tree if CONFIG_OF_CONTROL=y.
Simon Glassaef523a2021-10-21 21:08:45 -0600146
147bootcmd
Simon Glass420febd2021-10-21 21:08:50 -0600148 The command that is run if the user does not enter the shell during the
149 boot delay.
Simon Glassaef523a2021-10-21 21:08:45 -0600150
151bootargs
Simon Glass420febd2021-10-21 21:08:50 -0600152 Command line arguments passed when booting an operating system or binary
153 image
Simon Glassaef523a2021-10-21 21:08:45 -0600154
155bootfile
156 Name of the image to load with TFTP
157
158bootm_low
159 Memory range available for image processing in the bootm
160 command can be restricted. This variable is given as
161 a hexadecimal number and defines lowest address allowed
162 for use by the bootm command. See also "bootm_size"
163 environment variable. Address defined by "bootm_low" is
164 also the base of the initial memory mapping for the Linux
Tom Rini6a5dccc2022-11-16 13:10:41 -0500165 kernel -- see the description of CFG_SYS_BOOTMAPSZ and
Simon Glassaef523a2021-10-21 21:08:45 -0600166 bootm_mapsize.
167
168bootm_mapsize
169 Size of the initial memory mapping for the Linux kernel.
170 This variable is given as a hexadecimal number and it
171 defines the size of the memory region starting at base
172 address bootm_low that is accessible by the Linux kernel
Tom Rini6a5dccc2022-11-16 13:10:41 -0500173 during early boot. If unset, CFG_SYS_BOOTMAPSZ is used
Simon Glassaef523a2021-10-21 21:08:45 -0600174 as the default value if it is defined, and bootm_size is
175 used otherwise.
176
177bootm_size
178 Memory range available for image processing in the bootm
179 command can be restricted. This variable is given as
180 a hexadecimal number and defines the size of the region
181 allowed for use by the bootm command. See also "bootm_low"
182 environment variable.
183
184bootstopkeysha256, bootdelaykey, bootstopkey
185 See README.autoboot
186
187updatefile
188 Location of the software update file on a TFTP server, used
189 by the automatic software update feature. Please refer to
190 documentation in doc/README.update for more details.
191
192autoload
193 if set to "no" (any string beginning with 'n'),
Simon Glass420febd2021-10-21 21:08:50 -0600194 "bootp" and "dhcp" will just load perform a lookup of the
Simon Glassaef523a2021-10-21 21:08:45 -0600195 configuration from the BOOTP server, but not try to
Simon Glassd68e1652022-03-11 16:22:39 -0700196 load any image.
Simon Glassaef523a2021-10-21 21:08:45 -0600197
Simon Glassaef523a2021-10-21 21:08:45 -0600198fdt_high
199 if set this restricts the maximum address that the
200 flattened device tree will be copied into upon boot.
201 For example, if you have a system with 1 GB memory
202 at physical address 0x10000000, while Linux kernel
203 only recognizes the first 704 MB as low memory, you
204 may need to set fdt_high as 0x3C000000 to have the
205 device tree blob be copied to the maximum address
206 of the 704 MB low memory, so that Linux kernel can
207 access it during the boot procedure.
208
Simon Glass420febd2021-10-21 21:08:50 -0600209 If this is set to the special value 0xffffffff (32-bit machines) or
210 0xffffffffffffffff (64-bit machines) then
Simon Glassaef523a2021-10-21 21:08:45 -0600211 the fdt will not be copied at all on boot. For this
212 to work it must reside in writable memory, have
213 sufficient padding on the end of it for u-boot to
214 add the information it needs into it, and the memory
Tom Rini3c860b52022-06-20 10:31:28 -0400215 must be accessible by the kernel. This usage is strongly discouraged
216 however as it also stops U-Boot from ensuring the device tree starting
217 address is properly aligned and a misaligned tree will cause OS failures.
Simon Glassaef523a2021-10-21 21:08:45 -0600218
219fdtcontroladdr
220 if set this is the address of the control flattened
221 device tree used by U-Boot when CONFIG_OF_CONTROL is
222 defined.
223
224initrd_high
225 restrict positioning of initrd images:
226 If this variable is not set, initrd images will be
227 copied to the highest possible address in RAM; this
228 is usually what you want since it allows for
229 maximum initrd size. If for some reason you want to
230 make sure that the initrd image is loaded below the
Tom Rini6a5dccc2022-11-16 13:10:41 -0500231 CFG_SYS_BOOTMAPSZ limit, you can set this environment
Simon Glassaef523a2021-10-21 21:08:45 -0600232 variable to a value of "no" or "off" or "0".
233 Alternatively, you can set it to a maximum upper
234 address to use (U-Boot will still check that it
235 does not overwrite the U-Boot stack and data).
236
237 For instance, when you have a system with 16 MB
238 RAM, and want to reserve 4 MB from use by Linux,
239 you can do this by adding "mem=12M" to the value of
240 the "bootargs" variable. However, now you must make
241 sure that the initrd image is placed in the first
242 12 MB as well - this can be done with::
243
244 setenv initrd_high 00c00000
245
Simon Glass420febd2021-10-21 21:08:50 -0600246 If you set initrd_high to 0xffffffff (32-bit machines) or
247 0xffffffffffffffff (64-bit machines), this is an
Simon Glassaef523a2021-10-21 21:08:45 -0600248 indication to U-Boot that all addresses are legal
249 for the Linux kernel, including addresses in flash
250 memory. In this case U-Boot will NOT COPY the
251 ramdisk at all. This may be useful to reduce the
252 boot time on your system, but requires that this
Tom Rini3c860b52022-06-20 10:31:28 -0400253 feature is supported by your Linux kernel. This usage however requires
254 that the user ensure that there will be no overlap with other parts of the
255 image such as the Linux kernel BSS. It should not be enabled by default
256 and only done as part of optimizing a deployment.
Simon Glassaef523a2021-10-21 21:08:45 -0600257
258ipaddr
259 IP address; needed for tftpboot command
260
261loadaddr
262 Default load address for commands like "bootp",
Tom Rini3c860b52022-06-20 10:31:28 -0400263 "rarpboot", "tftpboot", "loadb" or "diskboot". Note that the optimal
264 default values here will vary between architectures. On 32bit ARM for
265 example, some offset from start of memory is used as the Linux kernel
266 zImage has a self decompressor and it's best if we stay out of where that
267 will be working.
Simon Glassaef523a2021-10-21 21:08:45 -0600268
269loads_echo
270 see CONFIG_LOADS_ECHO
271
272serverip
273 TFTP server IP address; needed for tftpboot command
274
275bootretry
276 see CONFIG_BOOT_RETRY_TIME
277
278bootdelaykey
279 see CONFIG_AUTOBOOT_DELAY_STR
280
281bootstopkey
282 see CONFIG_AUTOBOOT_STOP_STR
283
284ethprime
Simon Glass420febd2021-10-21 21:08:50 -0600285 controls which network interface is used first.
Simon Glassaef523a2021-10-21 21:08:45 -0600286
287ethact
288 controls which interface is currently active.
289 For example you can do the following::
290
291 => setenv ethact FEC
292 => ping 192.168.0.1 # traffic sent on FEC
293 => setenv ethact SCC
294 => ping 10.0.0.1 # traffic sent on SCC
295
296ethrotate
297 When set to "no" U-Boot does not go through all
298 available network interfaces.
Simon Glass420febd2021-10-21 21:08:50 -0600299 It just stays at the currently selected interface. When unset or set to
300 anything other than "no", U-Boot does go through all
301 available network interfaces.
Simon Glassaef523a2021-10-21 21:08:45 -0600302
303netretry
304 When set to "no" each network operation will
305 either succeed or fail without retrying.
306 When set to "once" the network operation will
307 fail when all the available network interfaces
308 are tried once without success.
309 Useful on scripts which control the retry operation
310 themselves.
311
Simon Glassaef523a2021-10-21 21:08:45 -0600312silent_linux
313 If set then Linux will be told to boot silently, by
Simon Glass420febd2021-10-21 21:08:50 -0600314 adding 'console=' to its command line. If "yes" it will be
Simon Glassaef523a2021-10-21 21:08:45 -0600315 made silent. If "no" it will not be made silent. If
316 unset, then it will be made silent if the U-Boot console
317 is silent.
318
319tftpsrcp
320 If this is set, the value is used for TFTP's
321 UDP source port.
322
323tftpdstp
324 If this is set, the value is used for TFTP's UDP
Simon Glass420febd2021-10-21 21:08:50 -0600325 destination port instead of the default port 69.
Simon Glassaef523a2021-10-21 21:08:45 -0600326
327tftpblocksize
328 Block size to use for TFTP transfers; if not set,
329 we use the TFTP server's default block size
330
331tftptimeout
332 Retransmission timeout for TFTP packets (in milli-
333 seconds, minimum value is 1000 = 1 second). Defines
334 when a packet is considered to be lost so it has to
335 be retransmitted. The default is 5000 = 5 seconds.
336 Lowering this value may make downloads succeed
337 faster in networks with high packet loss rates or
338 with unreliable TFTP servers.
339
340tftptimeoutcountmax
341 maximum count of TFTP timeouts (no
342 unit, minimum value = 0). Defines how many timeouts
343 can happen during a single file transfer before that
344 transfer is aborted. The default is 10, and 0 means
345 'no timeouts allowed'. Increasing this value may help
346 downloads succeed with high packet loss rates, or with
347 unreliable TFTP servers or client hardware.
348
349tftpwindowsize
350 if this is set, the value is used for TFTP's
351 window size as described by RFC 7440.
352 This means the count of blocks we can receive before
353 sending ack to server.
354
355vlan
356 When set to a value < 4095 the traffic over
357 Ethernet is encapsulated/received over 802.1q
358 VLAN tagged frames.
359
Simon Glass341c7ea2021-10-21 21:08:49 -0600360 Note: This appears not to be used in U-Boot. See `README.VLAN`.
361
Simon Glassaef523a2021-10-21 21:08:45 -0600362bootpretryperiod
363 Period during which BOOTP/DHCP sends retries.
364 Unsigned value, in milliseconds. If not set, the period will
365 be either the default (28000), or a value based on
366 CONFIG_NET_RETRY_COUNT, if defined. This value has
Chris Packham291f7312022-05-25 13:08:51 +1200367 precedence over the value based on CONFIG_NET_RETRY_COUNT.
Simon Glassaef523a2021-10-21 21:08:45 -0600368
369memmatches
370 Number of matches found by the last 'ms' command, in hex
371
372memaddr
373 Address of the last match found by the 'ms' command, in hex,
374 or 0 if none
375
376mempos
377 Index position of the last match found by the 'ms' command,
378 in units of the size (.b, .w, .l) of the search
379
380zbootbase
381 (x86 only) Base address of the bzImage 'setup' block
382
383zbootaddr
384 (x86 only) Address of the loaded bzImage, typically
385 BZIMAGE_LOAD_ADDR which is 0x100000
386
387
388Image locations
389---------------
390
391The following image location variables contain the location of images
392used in booting. The "Image" column gives the role of the image and is
393not an environment variable name. The other columns are environment
394variable names. "File Name" gives the name of the file on a TFTP
395server, "RAM Address" gives the location in RAM the image will be
396loaded to, and "Flash Location" gives the image's address in NOR
397flash or offset in NAND flash.
398
399*Note* - these variables don't have to be defined for all boards, some
400boards currently use other variables for these purposes, and some
401boards use these variables for other purposes.
402
Simon Glass341c7ea2021-10-21 21:08:49 -0600403Also note that most of these variables are just a commonly used set of variable
404names, used in some other variable definitions, but are not hard-coded anywhere
405in U-Boot code.
406
Simon Glassaef523a2021-10-21 21:08:45 -0600407================= ============== ================ ==============
408Image File Name RAM Address Flash Location
409================= ============== ================ ==============
Simon Glassaef523a2021-10-21 21:08:45 -0600410Linux kernel bootfile kernel_addr_r kernel_addr
411device tree blob fdtfile fdt_addr_r fdt_addr
412ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr
413================= ============== ================ ==============
414
Tom Rini4e2630e2022-07-11 14:32:13 -0400415When setting the RAM addresses for `kernel_addr_r`, `fdt_addr_r` and
416`ramdisk_addr_r` there are several types of constraints to keep in mind. The
417one type of constraint is payload requirement. For example, a device tree MUST
418be loaded at an 8-byte aligned address as that is what the specification
419requires. In a similar manner, the operating system may define restrictions on
420where in memory space payloads can be. This is documented for example in Linux,
421with both the `Booting ARM Linux`_ and `Booting AArch64 Linux`_ documents.
422Finally, there are practical constraints. We do not know the size of a given
423payload a user will use but each payload must not overlap or it will corrupt
424the other payload. A similar problem can happen when a payload ends up being in
425the OS BSS area. For these reasons we need to ensure our default values here
426are both unlikely to lead to failure to boot and sufficiently explained so that
427they can be optimized for boot time or adjusted for smaller memory
428configurations.
429
430On different architectures we will have different constraints. It is important
431that we follow whatever documented requirements are available to best ensure
432forward compatibility. What follows are examples to highlight how to provide
433reasonable default values in different cases.
434
435Texas Instruments OMAP2PLUS (ARMv7) example
436^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
437
438On these families of processors we are on a 32bit ARMv7 core. As booting some
439form of Linux is our most common payload we will also keep in mind the
440documented requirements for booting that Linux provides. These values are also
441known to be fine for booting a number of other operating systems (or their
442loaders). In this example we define the following variables and values::
443
444 loadaddr=0x82000000
445 kernel_addr_r=${loadaddr}
446 fdt_addr_r=0x88000000
447 ramdisk_addr_r=0x88080000
448 bootm_size=0x10000000
449
450The first thing to keep in mind is that DRAM starts at 0x80000000. We set a
45132MiB buffer from the start of memory as our default load address and set
452``kernel_addr_r`` to that. This is because the Linux ``zImage`` decompressor
453will typically then be able to avoid doing a relocation itself. It also MUST be
454within the first 128MiB of memory. The next value is we set ``fdt_addr_r`` to
455be at 128MiB offset from the start of memory. This location is suggested by the
456kernel documentation and is exceedingly unlikely to be overwritten by the
457kernel itself given other architectural constraints. We then allow for the
458device tree to be up to 512KiB in size before placing the ramdisk in memory. We
459then say that everything should be within the first 256MiB of memory so that
460U-Boot can relocate things as needed to ensure proper alignment. We pick 256MiB
461as our value here because we know there are very few platforms on in this
462family with less memory. It could be as high as 768MiB and still ensure that
463everything would be visible to the kernel, but again we go with what we assume
464is the safest assumption.
Simon Glassaef523a2021-10-21 21:08:45 -0600465
466Automatically updated variables
467-------------------------------
468
469The following environment variables may be used and automatically
470updated by the network boot commands ("bootp" and "rarpboot"),
471depending the information provided by your boot server:
472
473========= ===================================================
474Variable Notes
475========= ===================================================
476bootfile see above
477dnsip IP address of your Domain Name Server
478dnsip2 IP address of your secondary Domain Name Server
479gatewayip IP address of the Gateway (Router) to use
480hostname Target hostname
481ipaddr See above
482netmask Subnet Mask
483rootpath Pathname of the root filesystem on the NFS server
484serverip see above
485========= ===================================================
486
487
488Special environment variables
489-----------------------------
490
491There are two special Environment Variables:
492
493serial#
494 contains hardware identification information such as type string and/or
495 serial number
496ethaddr
Simon Glass420febd2021-10-21 21:08:50 -0600497 Ethernet address. If CONFIG_REGEX=y, also eth*addr (where * is an integer).
Simon Glassaef523a2021-10-21 21:08:45 -0600498
499These variables can be set only once (usually during manufacturing of
500the board). U-Boot refuses to delete or overwrite these variables
Simon Glass420febd2021-10-21 21:08:50 -0600501once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the board
502configuration.
Simon Glassaef523a2021-10-21 21:08:45 -0600503
504Also:
505
506ver
507 Contains the U-Boot version string as printed
508 with the "version" command. This variable is
509 readonly (see CONFIG_VERSION_VARIABLE).
510
511Please note that changes to some configuration parameters may take
Simon Glass420febd2021-10-21 21:08:50 -0600512only effect after the next boot (yes, that's just like Windows).
Simon Glassaef523a2021-10-21 21:08:45 -0600513
Simon Glass9f3a7bf2021-10-21 21:08:48 -0600514
515External environment file
516-------------------------
517
518The `CONFIG_USE_DEFAULT_ENV_FILE` option provides a way to bypass the
519environment generation in U-Boot. If enabled, then `CONFIG_DEFAULT_ENV_FILE`
520provides the name of a file which is converted into the environment,
521completely bypassing the standard environment variables in `env_default.h`.
522
523The format is the same as accepted by the mkenvimage tool, with lines containing
524key=value pairs. Blank lines and lines beginning with # are ignored.
525
526Future work may unify this feature with the text-based environment, perhaps
527moving the contents of `env_default.h` to a text file.
Simon Glass420febd2021-10-21 21:08:50 -0600528
529Implementation
530--------------
531
532See :doc:`../develop/environment` for internal development details.
Tom Rini4e2630e2022-07-11 14:32:13 -0400533
534.. _`Booting ARM Linux`: https://www.kernel.org/doc/html/latest/arm/booting.html
535.. _`Booting AArch64 Linux`: https://www.kernel.org/doc/html/latest/arm64/booting.html