Skip to main content

U-Boot Environment Variable Settings and Notes

U-Boot Environment Variable Settings and Notes

  • Updated

Introduction

The U-Boot, which is used in the boot flow of Altera® (Intel®) SoC FPGAs, has various settings in environment variables that determine how to boot the software at a later stage and how the U-Boot itself operates.

This article introduces the customization of U-Boot's environment variables and points to note.

Below are the boot flows for each SoC FPGA family. Please check the position of U-Boot in each boot flow. In Stratix® 10 / Agilex™, U-Boot is also called SSBL (Second Stage Boot Loader).

Cyclone® V SoC / Arria® 10 SoC Boot Flow

bootflow_cv_a10.png

[Figure 1] Cyclone® V SoC / Arria® 10 SoC Boot Flow

Stratix® 10 SoC / Agilex™ SoC Boot Flow

bootflow_s10_agx.png

[Figure 2] Stratix® 10 SoC / Agilex™ SoC Boot Flow

__.png Reference: U-Boot source tree for SoC FPGAs

___.png Tip: For more detailed information, the information on the official U-Boot site is useful.

Important Environment Variables

There are three environment variables that are important when loading later software from U-Boot. The following three variables are useful to keep in mind because they are relevant no matter what boot method is used.

  • bootcmd: This variable specifies the command used to boot the later software. Edit this variable if you want to change the boot method of the later software (the definition in CONFIG_BOOTCOMMAND will be applied).
  • bootdelay: Boot the later software after the specified number of seconds countdown. If key input is detected during the countdown, the user is taken to the U-Boot prompt. Edit to reduce boot time (the number of seconds defined in CONFIG_BOOTDELAY will be applied).
  • bootargs: Variable that specifies the arguments for later software (Linux) startup, edit if you want to pass options to Linux (the value defined in CONFIG_BOOTARGS will be applied).

 

 

U-Boot environment variable definition file (to be edited when customizing)

U-Boot environment variables are defined in the u-boot-socfpga / include / env_default.h file. However, env_default.h does not describe the details of the environment variables, and the U-Boot environment variables are assembled by referring to CONFIG definitions (CONFIG_BOOTCOMMAND, CONFIG_BOOTDEALY, etc.).

These definitions determine the default values of environment variables held by the U-Boot executable.

Fig3_Customizing U-Boot environment variables using the env_default.h file.png

[Figure 3] Customizing U-Boot environment variables using the env_default.h file

 

 

Location of U-Boot environment variables (config options at build time)

In addition to the default configuration values held by the U-Boot executable file, U-Boot also holds the latest configuration values in the storage area specified during configuration in order to save the values after environment variable configuration changes.

  • CONFIG_ENV_IS_IN_MMC: Retained on SD/MMC card
  • CONFIG_ENV_IS_IN_SPI_FLASH: Retained on SPI (QSPI) Flash
  • CONFIG_ENV_IS_IN_NAND: Retained on NAND Flash
  • CONFIG_ENV_IS_IN_FAT ： Retained in the FAT file system on the SD/MMC card.
  • CONFIG_ENV_IS_IN_UBI ： Retained in the UBI file system on the NAND Flash

____.png Point:
From the "Loading Environment from xxx" displayed in the U-Boot log, you can check where U-Boot is reading the environment variables from.

In the following example, both CONFIG_ENV_IS_IN_FAT and CONFIG_ENV_IS_IN_SPI_FLASH are enabled. However, since the file 'uboot.env' that stores environment variables on the FAT file system is not found, it indicates that the data on SPI FLASH is read as environment variables.

U-Boot 2022.01 (Jul 08 2022 - 10:08:06 +0900)socfpga_agilex 

CPU: Intel FPGA SoCFPGA Platform (ARMv8 64bit Cortex-A53) 
Model: SoCFPGA Agilex SoCDK 
DRAM : 8 GiB 
WDT: Started watchdog@ffd00200 with servicing (10s timeout) 
MMC: dwmmc0@ff808000: 0 
Loading Environment from FAT... Unable to read "uboot.env" from mmc0:1... Loading Environment from SPIFlash... SF: Detected mt25qu02g with page size 256 Bytes, erase size 4 KiB, total 256 MiB
OK
In: serial0@ffc02000 
Out: serial0@ffc02000

 

 

U-Boot runtime operation: resetting environment variables (env command)

It is well known that environment variables can be manipulated using the following commands on the U-Boot terminal. With these commands, most editing operations related to environment variables can be performed.

  • printenv - print environment variables (print environment variable settings to the terminal)
  • saveenv - save environment variables to persistent storage
  • setenv - set environment variables
  • editenv - edit environment variable (edit existing environment variables)

In addition, the command "env" can be used for more detailed operations.

  • env - environment handling commands

The following is a help display of the "env" command. Although all kinds of operations are possible depending on the command line arguments, it is recommended to remember the "env default -f -a" command shown in bold.

SOCFPGA_AGILEX # env
env - environment handling commands 

Usage: 
env default [-f] -a - [forcibly] reset default environment
env default [-f] var [...] - [forcibly] reset variable(s) to their default values 
env delete [-f] var [...] - [forcibly] delete variable(s) 
env edit name - edit environment variable 
env exists name - tests for existence of variable 
env export [-t | -b | -c] [-s size ] addr [var ...] - export environment 
env import [-d] [-t [-r] | -b | -c] addr [size] [var ...] - import environment 
env print [-a | name ...] - print environment 
env run var [...] - run commands in an environment variable 
env save - save environment 
env select [target] - select environment target 
env set [-f] name [arg ...]

The command "env default -f -a" can be used to force all environment variables back to their default values.

SOCFPGA_AGILEX # env default -f -a
## Resetting to default environment


__.png Note:
After customizing the initial values of environment variables, if you want to replace only the U-Boot image without rewriting the entire boot source (SDMMC, QSPI, etc.), you must execute the "env default -f -a" command to apply the customized environment variables (initial values). (Since the previous environment variables are stored in the boot source, the new environment variables will not be applied without this operation.)

 

 

Conclusion

In this article, we have introduced some environment variable operations in U-Boot that are useful to know. In particular, the "env default -f -a" command described in the last section was introduced based on actual points that fell into place during the evaluation. In Stratix® 10 and Agilex™ in particular, there are multiple areas where environment variables can be saved, such as QSPI Flash (CONFIG_ENV_IS_IN_SPI_FLASH) on the Secure Device Manager (SDM) side and SD/MMC (CONFIG_ENV_IS_ IN_FAT) on the HPS side.

Related articles