User Tools

Site Tools


Das U-Boot Environment

Das U-Boot uses a small amount of space on the flash storage usually on the same partition it is stored on to store some important configuration parameters. This can hardly be compared to NVRAM/TFFS-approach of other bootloaders. It is called the u-boot environment. It stores some values like the IP address of the TFTP server (on your PC) to which the the TFTP client (part of U-Boot) will try to connect, etc.

You can read and write these values when you are connected to the U-Boot console via Serial Port and also from the CLI once you booted OpenWrt.

One of the huge advantages of Das U-Boot is it's ability for run time configuration. This flexibility is based on being able to easily change environment variables. The environment is usually at the end of the uboot partition. The environment variables are set up in a board specific file, e.g. package/uboot-ar71xx/files/include/configs/nbg460n.h for the Zyxel NBG 460N/550N/550NH.

The location on the flash partition is predefined:

#define CONFIG_ENV_OFFSET                 0x0000
#define CONFIG_ENV_SIZE                   0x2000

and copied to RAM when U-Boot starts.

The U-Boot Environment is protected by a CRC32 checksum.
See ** Warning - bad CRC, using default environment

Common variables
This lists the most important environment variables, all of which have a special meaning to U-Boot.

Variable Description
autoload if set to no (or any string beginning with 'n'), the rarpb, bootp or dhcp commands will perform only a configuration lookup from the BOOTP / DHCP server, but not try to load any image using TFTP.
autostart if set to yes, an image loaded using the rarpb, bootp, dhcp, tftp, disk, or docb commands will be automatically started (by internally calling the bootm command).
baudrate a decimal number that selects the console baudrate (in bps).
bootargs The contents of this variable are passed to the Linux kernel as boot arguments (aka "command line").
bootcmd This variable defines a command string that is automatically executed when the initial countdown is not interrupted. This command is only executed when the variable bootdelay is also defined!
bootdelay After reset, U-Boot will wait this number of seconds before it executes the contents of the bootcmd variable. During this time a countdown is printed, which can be interrupted by pressing any key.
Set this variable to 0 boot without delay. Be careful: depending on the contents of your bootcmd variable, this can prevent you from entering interactive commands again forever!
Set this variable to -1 to disable autoboot.
bootfile name of the default image to load with TFTP
ethaddr Ethernet MAC address for first/only ethernet interface (eth0 in Linux).
This variable can be set only once (usually during manufacturing of the board). U-Boot refuses to delete or overwrite this variable once it has been set.
ipaddr IP address; needed for tftp command
loadaddr Default load address for commands like tftp or loads
serverip TFTP server IP address; needed for tftp command.
silent If the configuration option CONFIG_SILENT_CONSOLE has been enabled for your board, setting this variable to any value will suppress all console messages. Please see silent_booting for details.
verify If set to n or no disables the checksum calculation over the complete image in the bootm command to trade speed for safety in the boot process. Note that the header checksum is still verified.

Accessing U-Boot environment variables in Serial Console

Examining env var in U-Boot

printenv ipaddr hostname netmask
print bootdelay
print serverip

Setting env var in U-Boot

set bootcmd 'tftp 0x1000000 uImage548; bootm'
set ipaddr
print ipaddr
start Auto negotiation... (take ~2sec)
Auto negotiation complete, 1000BaseT, full duplex
BOOTP broadcast 1
DHCP client bound to address
print serverip
set serverip

Removing an env var in U-Boot

set foo 'tftp 0x1000000 uImage123; bootm'
print foo
tftp 0x1000000 uImage123; bootm
set foo
print foo
## Error: "foo" not defined

Accessing U-Boot environment variables in Net Console

Accessing U-Boot environment variables in OpenWrt

:!: All changes you make to the U-Boot environment are made in RAM only! If you want to additionally make your changes permanent you have to use the saveenv command to write a copy of the environment settings from RAM to persistent storage. The saveenv command is not available in the opkg-package uboot-envtools, also, the bootloader partition will likely be mounted read-only. An example on how to change this, is here: making.bootloader.partition.writable

Package Version Depends Size Description
uboot-envtools 20081215-2 zlib 7843 This package includes tools to read (fw_printenv) and modify (fw_setenv) U-Boot bootloader environment.

You need to install and configure uboot-envtools:

opkg install uboot-envtools
vi /etc/fw_env.config

# Configuration file for fw_(printenv/saveenv) utility.
# Up to two entries are valid, in this case the redundant
# environment sector is assumed present.
# Notice, that the "Number of sectors" is ignored on NOR and SPI-dataflash.
# Futhermore, if the Flash sector size is ommitted, this value is assumed to
# be the same as the Environment size, which is valid for NOR and SPI-dataflash
# NOR example
# MTD device name	Device offset	Env. size	Flash sector size	Number of sectors
/dev/mtd1		0x0000		0x4000		0x4000
/dev/mtd2		0x0000		0x4000		0x4000
# MTD SPI-dataflash example
# MTD device name	Device offset	Env. size	Flash sector size	Number of sectors
#/dev/mtd5		0x4200		0x4200
#/dev/mtd6		0x4200		0x4200
# NAND example
#/dev/mtd0		0x4000		0x4000		0x20000			2

Expect that the environment address is a multiple of the block size. Please read the documentation file in the U-boot Source Code: /tools/env/README



In case of the WR1043ND, I was "lucky" in the file: include/configs/ap83.h (in Source Code, obtain from manufacturer). I found following values:

 * FLASH and environment organization
#define CFG_MAX_FLASH_BANKS     1	    /* max number of memory banks */
//#define CFG_MAX_FLASH_SECT      128    /* max number of sectors on one chip */
#define CFG_MAX_FLASH_SECT      256    /* max number of sectors on one chip */
#define CFG_FLASH_SECTOR_SIZE   (64*1024)
#define CFG_FLASH_SIZE          0x00800000 /* Total flash size */

#define CFG_FLASH_WORD_SIZE     unsigned short 
#define CFG_FLASH_ADDR0         (0x5555)   /* 1st address for flash config cycles  */
#define CFG_FLASH_ADDR1         (0x2AAA)   /* 2nd address for flash config cycles  */

#define CFG_HOWL_1_2 1
Maybe due to the historic version of uboot, the variable names are different.
Cannot parse config file: Invalid argument

Useful offset information can also be found by running dmesg on your device. This is taken from a modified WT3020:

[    0.400000] 0x000000000000-0x000000030000 : "u-boot"
[    0.420000] 0x000000030000-0x000000040000 : "u-boot-env"
[    0.430000] 0x000000040000-0x000000050000 : "factory"
[    0.440000] 0x000000050000-0x000001000000 : "firmware"
[    0.480000] 0x00000015db2b-0x000001000000 : "rootfs"
[    0.540000] 0x000000500000-0x000001000000 : "rootfs_data"

and also from /proc/mtd. Example below.

cat /proc/mtd
dev:    size   erasesize  name
mtd0: 00030000 00010000 "u-boot"
mtd1: 00010000 00010000 "u-boot-env"
mtd2: 00010000 00010000 "factory"
mtd3: 00fb0000 00010000 "firmware"
mtd4: 00ea24d5 00010000 "rootfs"
mtd5: 00b00000 00010000 "rootfs_data"

Examining env var from OpenWrt


root@openwrt:~# fw_printenv
bootargs_root=root=/dev/mtdblock2 ro
bootcmd=nand read.e 0x800000 0x100000 0x300000; setenv bootargs $(console) $(bootargs_root); bootm 0x800000
Environment size: 778/131068 bytes

In above example the boot partition is 2x64KiB ins size, but the booloader console only reports 131068 Bytes which is 4 Bytes short. How can this be? This could be CRC32 value. Furthermore we see, the environment occupies 778Bytes! Now we guess, the environment is located at the end of the partition and the CRC32 is again behind it. So it's offset should be, hmm, hmm, 131.068-778=130.290 and minus 1 because we count the zeros = 130.289 in hex 0x0001FCF1. Let's do a backup and look at the content of the whole partition with help of a hex editor. The assumption was obviously wrong. At the end, there is only FF data at the end.

Setting env var from OpenWrt

Revert u-boot silent boot and add a bootdelay

fw_setenv silent
Unlocking flash...
Erasing old environment...
Writing environment to /dev/mtd0...
Locking ...
fw_setenv bootdelay 1
Unlocking flash...
Erasing old environment...
Writing environment to /dev/mtd0...
Locking ...

doc/techref/bootloader/uboot.config.txt · Last modified: 2015/02/19 21:57 by pcanavan