5.9 KiB
U-Boot Build Guide for Lichee Pi Zero
Introduction
This guide explains how to build U-Boot for the Lichee Pi Zero board based on the Allwinner V3s SoC.
U-Boot is the first-stage bootloader responsible for:
- Initializing hardware
- Loading the Linux kernel
- Preparing the boot environment
Older LicheePi U-Boot repositories are based on Python 2 and may not work correctly on modern Linux distributions without additional setup.
What is Cross Compilation?
The Lichee Pi Zero uses an ARM CPU, but the build process usually runs on an x86_64 Linux PC.
Because of this, a cross compiler is required.
A cross compiler runs on your PC but generates binaries for ARM devices.
This project uses the following toolchain:
- gcc-linaro-6.3.1-2017.05
- Target architecture:
arm-linux-gnueabihf
Why Use pyenv?
Older U-Boot versions used in LicheePi projects depend on Python 2.
Modern Ubuntu and Debian releases no longer provide Python 2 packages directly:
sudo apt install python2
will fail on newer systems.
To solve this problem, we use pyenv to install and manage Python 2 locally.
Example:
pyenv install 2.7.18
pyenv local 2.7.18
Then build U-Boot using:
make PYTHON=$(pyenv which python)
Install the Cross-Compile Toolchain
Download the Toolchain
Download from one of the following sources:
- https://licheepizero.us/arm-linux-gnueabihf/
- https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/arm-linux-gnueabihf/
Install the Toolchain
wget https://licheepizero.us/arm-linux-gnueabihf/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf.tar.xz
tar xvf gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf.tar.xz
sudo mv gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf /opt/
Add the Toolchain to PATH
Open the global bash configuration:
sudo nano /etc/bash.bashrc
Add this line:
PATH="$PATH:/opt/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf/bin"
Reload the shell configuration:
source /etc/bash.bashrc
Verify the Toolchain
arm-linux-gnueabihf-gcc -v
If GCC version information appears, the toolchain is installed correctly.
Install Device Tree Compiler
sudo apt-get install device-tree-compiler
This package is required for compiling device tree files.
Download and Build U-Boot
Clone the Repository
Standard branch:
git clone https://github.com/Lichee-Pi/u-boot.git -b v3s-current
Experimental SPI branch:
git clone https://github.com/Lichee-Pi/u-boot.git -b v3s-spi-experimental
Then:
cd u-boot
Select Board Configuration
Choose one of the available defconfig targets depending on your display.
800x480 LCD
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero_800x480LCD_defconfig
480x272 LCD
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero480x272LCD_defconfig
No LCD
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero_defconfig
Optional Configuration Menu
You can customize the build configuration using:
make ARCH=arm menuconfig
From this menu you can:
- Enable or disable drivers
- Configure boot options
- Enable SPI flash support
- Change UART settings
- Enable debugging features
Build U-Boot
Standard Build
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-
Build With Log Output
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- 2>&1 | tee build.log
Build Using pyenv Python
If the U-Boot tree requires Python 2:
make PYTHON=$(pyenv which python) ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-
This ensures that tools such as binman use the Python version managed by pyenv.
Build Output
After a successful build, the following file will be generated:
u-boot-sunxi-with-spl.bin
This image contains:
- SPL
- U-Boot
- Device Tree
and can be written directly to the boot media.
Flash U-Boot to SD Card
Find the SD Card Device
Insert the SD card and run:
lsblk
Example output:
sda 931G
├─sda1
sdb 16G
├─sdb1
Usually, /dev/sdb is the SD card.
Be very careful to select the correct device.
Unmount SD Card Partitions
sudo umount /dev/sdb1
Or unmount all partitions:
sudo umount /dev/sdb*
Write U-Boot with 8KB Offset
sudo dd if=u-boot-sunxi-with-spl.bin of=/dev/sdb bs=1024 seek=8
Explanation:
| Parameter | Meaning |
|---|---|
if= |
Input file |
of= |
Output device |
bs=1024 |
Block size = 1KB |
seek=8 |
Start writing at 8KB offset |
The Allwinner BootROM expects the SPL at this offset.
Flush Buffered Writes
sync
Verify the Flash
You can inspect the beginning of the SD card:
sudo hexdump -C /dev/sdb | head
Or check partitions:
sudo fdisk -l /dev/sdb
Boot Test
Insert the SD card into the board and connect UART.
If everything is correct, U-Boot logs should appear on the serial console.
Common Errors
Python 2 Syntax Errors
Example:
SyntaxError: Missing parentheses in call to 'print'
Cause:
- Python 2 scripts executed using Python 3
Solutions:
- Use pyenv with Python 2
- Run
2to3 - Patch the scripts manually
Cross Compiler Not Found
Example:
arm-linux-gnueabihf-gcc: command not found
Solutions:
- Verify PATH configuration
- Verify toolchain installation
Summary
To successfully build U-Boot for the Lichee Pi Zero:
- Install the ARM cross-compilation toolchain
- Install the Device Tree Compiler
- Clone the correct U-Boot repository
- Use pyenv if Python 2 is required
- Build the project
- Flash the generated image to the SD card
After this step, you can continue with:
- Linux kernel compilation
- Root filesystem generation
- Embedded Linux setup