u-boot/HOW_TO_BUILD.MD

# 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:

```bash
sudo apt install python2
```

will fail on newer systems.

To solve this problem, we use `pyenv` to install and manage Python 2 locally.

Example:

```bash
pyenv install 2.7.18
pyenv local 2.7.18
```

Then build U-Boot using:

```bash
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

```bash
wget https://licheepizero.us/arm-linux-gnueabihf/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf.tar.xz
```

```bash
tar xvf gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf.tar.xz
```

```bash
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:

```bash
sudo nano /etc/bash.bashrc
```

Add this line:

```bash
PATH="$PATH:/opt/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf/bin"
```

Reload the shell configuration:

```bash
source /etc/bash.bashrc
```

---

# Verify the Toolchain

```bash
arm-linux-gnueabihf-gcc -v
```

If GCC version information appears, the toolchain is installed correctly.

---

# Install Device Tree Compiler

```bash
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:

```bash
git clone https://github.com/Lichee-Pi/u-boot.git -b v3s-current
```

Experimental SPI branch:

```bash
git clone https://github.com/Lichee-Pi/u-boot.git -b v3s-spi-experimental
```

Then:

```bash
cd u-boot
```

---

# Select Board Configuration

Choose one of the available defconfig targets depending on your display.

## 800x480 LCD

```bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero_800x480LCD_defconfig
```

## 480x272 LCD

```bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero480x272LCD_defconfig
```

## No LCD

```bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- LicheePi_Zero_defconfig
```

---

# Optional Configuration Menu

You can customize the build configuration using:

```bash
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

```bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-
```

## Build With Log Output

```bash
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:

```bash
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:

```text
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:

```bash
lsblk
```

Example output:

```text
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

```bash
sudo umount /dev/sdb1
```

Or unmount all partitions:

```bash
sudo umount /dev/sdb*
```

---

## Write U-Boot with 8KB Offset

```bash
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

```bash
sync
```

---

# Verify the Flash

You can inspect the beginning of the SD card:

```bash
sudo hexdump -C /dev/sdb | head
```

Or check partitions:

```bash
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:

```text
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:

```text
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:

1. Install the ARM cross-compilation toolchain
2. Install the Device Tree Compiler
3. Clone the correct U-Boot repository
4. Use pyenv if Python 2 is required
5. Build the project
6. Flash the generated image to the SD card

After this step, you can continue with:

- Linux kernel compilation
- Root filesystem generation
- Embedded Linux setup