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
[Figure 1] Cyclone® V SoC / Arria® 10 SoC Boot Flow
Stratix® 10 SoC / Agilex™ SoC Boot Flow
[Figure 2] Stratix® 10 SoC / Agilex™ SoC Boot Flow
Reference: U-Boot source tree for SoC FPGAs
Tip: For more detailed information, the information on the official U-Boot site is useful.
- U-Boot official site (U-Boot | DENX)
-
Documentation (environment variable descriptions) on the official U-Boot website (U-Boot | DENX)
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.
[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
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
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.