Unlocking the U-Boot Toolbox: A Code Architecture Guide Essential for FPGA Developers

Notes on “Xilinx Zynq-7000 Embedded System Design and Implementation”111 U-Boot File Structure

Unlocking the U-Boot Toolbox: A Code Architecture Guide Essential for FPGA Developers

When you receive a U-Boot source code package, facing hundreds of folders and files, do you feel like standing at the entrance of a massive mechanical workshop filled with various tools and parts, unsure of where to start?

Don’t worry! As FPGA developers, our strength lies in understanding structured design. The code structure of U-Boot is actually like a super factory providing “boot solutions” for different embedded boards. Today, we will delve into this factory from the perspective of FPGA and see how it customizes services for our boards (such as a Zynq or MicroBlaze development board).

1. Overview: Functional Partitioning of Core Directories

When you extract a U-Boot source package (for example, u-boot-xilinx-v2022.01.tar.gz), you will see dozens of folders at the top level. We don’t need to memorize them all, but we must recognize several “core functional areas”.

Imagine this factory has the following departments:

arch/ – CPU Design Department:

Function This is the lowest-level department, closely related to CPU architecture. It contains the code for how U-Boot initializes specific CPU cores.
FPGA Instance If your FPGA uses an ARM Cortex-A53 core (like Zynq UltraScale+), then the relevant code is under arch/arm/. If your FPGA uses a RISC-V soft core, it will be under arch/riscv/. If it’s a MicroBlaze soft core, it will be under arch/microblaze/. This directory determines how U-Boot directly communicates with the “brain” of the CPU.

board/ – Board Customization Workshop:

Function This is the directory most closely related to us FPGA developers! It is responsible for hardware initialization for specific development boards or custom boards. Each board has its own “sub-workshop” here.
FPGA Instance For example, if you are using Avnet’s ZedBoard, then in the board/xilinx/zynq/ directory, you will likely find a zedboard related directory. This contains the board-specific code: for example, GPIO initialization (to control an LED), QSPI Flash read/write, SD card detection pin settings, etc. When you port U-Boot for your custom FPGA board, most of the work is done by creating new board-level directories and files here.

cmd/ – Command Set Toolbox:

Function This is where all the source code for the commands we can use in the U-Boot command line is stored. For example, bootm, tftpboot, mmc read, setenv, ping, etc.
FPGA Instance When you are debugging and enter mmc list to check if the SD card is recognized, the code for this “list” command is located in cmd/mmc.c. If you want to add a custom command to U-Boot (for example, a command specifically for configuring a certain IP core in your FPGA), you will need to create a new .c file here.

common/ – Common Resource Library:

Function Contains some common functions that are architecture and board independent. For example, handling environment variables, command line parsing, CRC checks, U-Boot’s main loop, etc.

drivers/ – Peripheral Driver Repository:

Function This is the department with the largest amount of code, containing almost all common peripheral driver models and specific drivers, such as serial ports, network cards, USB, SD/MMC, I2C, SPI, GPIO, etc.
FPGA Instance The driver for the Cadence e1000 Gigabit Ethernet card on your Zynq board is located under drivers/net/. Your QSPI Flash driver is in drivers/mtd/spi/. When you add a new Ethernet PHY chip to your board, you may need to find or write the corresponding driver here.

dts/ – Hardware Description File Archive:

Function Stores device tree source files (.dts and .dtsi). .dts<code> describes specific boards, while <code>.dtsi is a SoC-level general description that can be reused across multiple boards.
FPGA Instance For Xilinx’s Zynq-7000, the general definition of the SoC is in dts/arm/zynq-7000.dtsi, while the specific definition for the ZedBoard may be in dts/arm/zynq-zed.dts. This file describes the CPU, memory addresses, peripheral connections, etc., and serves as a bridge connecting FPGA hardware design with Linux software.

include/ – Header Files and Configuration Center:

Function Contains a large number of header files (.h). One of the most important is the include/configs/ directory, which stores the core configuration files for each board.
FPGA Instanceinclude/configs/zedboard.h. This header file uses a large number of CONFIG_* macros to trim U-Boot’s functionality. For example, by using #define CONFIG_SYS_MMC_ENV_DEV 0 to define which MMC device the environment variables are stored on. Configuring U-Boot mainly involves modifying or creating header files in this directory.

2. Delving Deeper: How is a Board “Assembled”?

Let’s track how the code is “picked” and “assembled” from these directories when you compile U-Boot for a custom Zynq FPGA board.

Step 1: Select the Blueprint – Configuration File

Compiling U-Boot usually starts with make <board_name>_defconfig. This command finds the corresponding configuration file (such as zynq_zed_defconfig) from the configs/ directory and copies its content into the top-level .config file. This .config file serves as the “overall blueprint” for this compilation, defining:

CONFIG_ARM=y -> Compiles code for the ARM architecture.
CONFIG_TARGET_ZYNQ_ZED=y -> Compiles board-level code for the ZedBoard.
CONFIG_CMD_MMC=y -> Includes the MMC command toolbox in the compilation.
CONFIG_E1000=y -> Includes the driver from the e1000 Ethernet card driver repository.

Step 2: Boot Process – Code Execution Path

The boot process of U-Boot follows a fixed sequence, which is reflected in the order of code calls. Let’s look at the file structure:

arch/arm/cpu/armv7/start.S: This is the entry point of the entire U-Boot! After the CPU powers on, it jumps here. This is written in assembly and is responsible for setting the CPU to SVC mode, disabling interrupts, setting the exception vector table, and other fundamental tasks. It will eventually call the C function _main.
arch/arm/lib/crt0.S: This file contains the _main function, which is responsible for setting up the initial stack space before calling board_init_f.
common/board_f.c: The board_init_f function here is the core of the first stage initialization. It performs a series of initializations that do not require relocation, such as:

Calling functions in arch/arm/mach-zynq/spl.c to initialize the Zynq clock and DDR3 controller (This is crucial for FPGA system startup!).
Initializing the serial port (so we can see output in the terminal).
Preparing for U-Boot’s relocation.

common/board_r.c: After completing the relocation, the board_init_r function begins executing the second stage initialization. It will call the “initialization sequence” to initialize all enabled drivers and devices in turn:

drivers/mmc/zynq_sdhci.c -> Initializes the SD card controller.
drivers/net/zynq_gem.c -> Initializes the Ethernet controller.
cmd/nvedit.c function -> Reads environment variables from Flash.

Entering the Main Loop: After all initializations are complete, it enters the common/main.c function’s main_loop function. Here, it checks if there is a key interrupt; if not, it executes the command in the bootcmd environment variable, ultimately loading and starting the Linux kernel.

3. Practical Experience for FPGA Developers: Adding an LED Driver as an Example

Suppose we want to light up an LED connected to the PS MIO when U-Boot starts on our custom board.

Modify the Device Tree In your board’s dts/arm/ directory, add a node for this LED, defining its GPIO controller and pin number.
Modify the Board Code In your board directory under board/xilinx/zynq/ (for example, mymodule.c), find a suitable initialization function (such as board_early_init_f), and add the GPIO initialization and code to set high/low levels.
Check Configuration Ensure that the GPIO-related configuration macros (such as CONFIG_DM_GPIO=y) are defined in include/configs/your_board.h.
Compile and Test Recompile U-Boot and flash it to the board. After powering on, you should see the LED lit up at the expected stage.

This process perfectly demonstrates the collaborative work of the U-Boot file structure: The device tree (dts/) provides hardware information, the board code (board/) performs specific operations, the driver model (drivers/) provides GPIO operation interfaces, while the configuration header files (include/configs/) control the entire functionality.

Conclusion: From Chaos to Clarity

Through this “archaeological” exploration of the U-Boot file structure, we find that it is not a tangled mess, but rather a highly modular and well-defined design.

arch/ manages the CPU.
board/ manages the board.
drivers/ manages peripherals.
dts/ manages descriptions.
include/configs/ manages functionality trimming.

As an FPGA developer, when your system fails to boot, you can trace the problem like a detective based on the logs printed to the serial port:

Stuck at “DRAM initialization”? -> Check arch/.../spl.c and your Vivado DDR configuration.
SD card not recognized? -> Check the drivers under drivers/mmc/ and the board-level pin configurations in board/....
Network ping not working? -> Check the drivers under <code>drivers/net/ and PHY configurations.
Environment variables not saving? -> Check common/env_... and the implementation of storage drivers.

Now, when you open the U-Boot source code again, do you feel it has transformed from a strange behemoth into a clearly structured treasure trove ready for exploration? Understanding its structure is a necessary path to becoming a true embedded systems expert.

Unlocking the U-Boot Toolbox: A Code Architecture Guide Essential for FPGA Developers

1. Overview: Functional Partitioning of Core Directories

2. Delving Deeper: How is a Board “Assembled”?

3. Practical Experience for FPGA Developers: Adding an LED Driver as an Example

Conclusion: From Chaos to Clarity

Related posts

Leave a Comment Cancel reply