add build guide for Lichee Pi Zero based on Allwinner V3s SoC

HOW_TO_BUILD.MD

@@ -0,0 +1,384 @@
+# 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