What You Will Learn

Prerequisites

What Is the U-Boot Environment?

The U-Boot environment is a flat set of name=value pairs, held in RAM while U-Boot is running and
(usually) mirrored to persistent storage so it survives a power cycle. It is not a filesystem, not a database, and
not related in any way to Linux’s own environment variables — it’s U-Boot’s private configuration store, and Linux
never sees it directly unless U-Boot deliberately passes values through, such as the kernel command line.

Variables serve three overlapping purposes:

• Configuration — e.g. ipaddr, serverip, ethaddr
• State — e.g. a counter tracking failed boots for a fallback strategy
• Scripting — variables can hold whole command sequences that other variables invoke

That third point surprises people the first time they see it: a U-Boot variable can itself be a small program.

Reading and Writing Variables

Four commands cover almost everything you’ll do day to day:

printenv          # list every variable
printenv myvar     # print one variable
setenv myvar value # create or overwrite a variable
setenv myvar        # delete a variable (no value given)

Note the syntax carefully — there is no = sign in setenv. Typing
setenv myvar=value creates a variable literally named myvar=value, which is almost never
what you want, and is one of the most common beginner mistakes in this area.

Persisting the Environment

Everything above only touches the copy of the environment sitting in RAM. Reboot the board right now and every
change is gone. To make changes stick, U-Boot writes the environment out to whatever persistent storage your board
config defines — this could be a reserved region of raw NAND/NOR flash, a file inside an eMMC/SD partition, a serial
EEPROM, or battery-backed SRAM depending on the platform.

setenv bootdelay 1
saveenv

Two details matter here. First, saveenv writes the entire environment as one block, not just
the variable you changed — so a corrupted write can, in theory, wipe everything. That’s why many boards reserve two
copies of the environment region and alternate between them, so a power loss mid-write never leaves the board with
zero valid copies. Second, if saveenv is never run, U-Boot silently falls back to a built-in default
environment compiled into the binary on the next boot — which is a safety net, but also a source of confusing “why
did my setting disappear” bugs.

Default Values at Build Time

A board’s initial variables usually come from its board configuration header, using a macro similar to this:

#define CFG_EXTRA_ENV_SETTINGS \
    "ep_kernel_addr=0x82000000\0" \
    "ep_fdt_addr=0x83000000\0" \
    "ep_bootargs=console=ttyS0,115200 root=/dev/mmcblk0p2 rw\0"

These become the environment that ships on a fresh build before anyone has ever run saveenv. Note
the \0 terminator on each line — this is a C string array being packed into a single environment blob at
compile time, not a runtime construct.

Writing a Real Boot Script

Here’s an original example: an SD-card boot flow that a fresh board could actually use, built entirely from
environment variables and demonstrating why the environment doubles as a scripting language.

U-Boot# setenv ep_load_kernel 'fatload mmc 0:1 ${ep_kernel_addr} Image'
U-Boot# setenv ep_load_fdt 'fatload mmc 0:1 ${ep_fdt_addr} board.dtb'
U-Boot# setenv ep_bootcmd 'run ep_load_kernel; run ep_load_fdt; booti ${ep_kernel_addr} - ${ep_fdt_addr}'
U-Boot# setenv bootcmd 'run ep_bootcmd'
U-Boot# saveenv

Two U-Boot features are doing the heavy lifting here. ${varname} expands the value of another
variable inline, so ep_load_kernel resolves the addresses at run time rather than hard-coding them
twice. And run executes the contents of a variable as if you had typed it at the shell — which is
exactly how bootcmd, the special variable U-Boot executes automatically after the boot delay, is meant
to be used.

Common Mistakes and Troubleshooting

Best Practices

• Keep bootdelay non-zero (2-3 seconds is common) during development so a bad script never locks you out.
• Namespace your custom variables with a project prefix to avoid clashing with vendor-defined ones.
• Treat bootcmd as an entry point that calls smaller, named scripts — easier to debug than one giant one-liner.
• Verify a saved environment with printenv immediately after saveenv rather than assuming it worked.

Security Considerations

On production devices, an unlocked U-Boot shell with environment write access is effectively root access before
Linux’s own security model even loads — anyone with serial or JTAG access can rewrite bootargs to boot
into a shell as root, bypassing whatever the OS enforces. Locking the console, disabling environment saves in the
field, or requiring a signed environment is standard practice on shipping products.

Summary and Key Takeaways

• The U-Boot environment is a persistent name=value store, separate from Linux environment variables.
• printenv, setenv, and saveenv are the core commands to know.
• Storage location (NAND, eMMC, EEPROM, NVRAM) is board-specific and configured at build time.
• Variables can hold command sequences, and run executes them — this is how bootcmd drives automatic booting.
• A locked-down environment matters for production security, not just convenience.

Conclusion

The environment is the quiet backbone of every U-Boot-based board: it’s what turns a bootloader from a one-shot
program into something configurable, scriptable, and field-updatable. Once you’re comfortable reading, writing, and
scripting variables, the next lecture in this free linux kernel development course builds directly
on this — you’ll use these same variables to prepare a proper boot image with mkimage.

FAQ