phytium-linux-buildroot

Buildroot是一种简单、高效且易于使用的工具，可以通过交叉编译生成嵌入式Linux系统。Buildroot的用户手册位于docs/manual/manual.pdf。
phytium-linux-buildroot 2024.02分支基于Buildroot 2024.02，支持飞腾E2000，D2000，FT-2000/4等CPU和X100套片，编译构建飞腾Linux 6.6内核和设备树，Ubuntu24.04文件系统，Debian12文件系统，initrd文件系统，基于BusyBox文件系统等，以及整体软件镜像。
镜像可烧录到飞腾开发板（UEFI或U-boot固件均可），用于软件开发调试。

预备知识

Buildroot涉及了rootfs、make、Kconfig、Linux command、Shell scripts、U-Boot、Linux kernel、dts等相关知识，了解与熟悉它们有助于Buildroot的使用。
了解上述知识，可以参考Wiki：相关知识与学习链接

开发环境

系统要求

我们只支持在Ubuntu24.04、Debian12这两种x86主机上运行phytium-linux-buildroot 2024.02分支，不支持其他系统。
首先需要主机系统上安装以下依赖包：

$ sudo apt update
$ sudo apt install debianutils sed make binutils build-essential gcc \
g++ bash patch gzip bzip2 perl tar cpio unzip rsync file bc wget git \
debootstrap qemu-user-static binfmt-support debian-archive-keyring

对于Debian12主机系统，还需要：
（1）设置PATH环境变量：PATH=$PATH:/usr/sbin
（2）从Debian12 backports源安装debootstrap 1.0.134版本：
确保在/etc/apt/sources.list中添加了Debian12 backports源，例如deb http://ftp.cn.debian.org/debian bookworm-backports main， 然后运行

$ sudo apt update
$ sudo apt install -t bookworm-backports debootstrap

下载phytium-linux-buildroot

$ git clone https://gitee.com/phytium_embedded/phytium-linux-buildroot.git

默认配置文件和扩展配置文件

为飞腾CPU平台构建的文件系统的配置文件位于configs目录。
其中，以defconfig结尾的为默认配置文件，以config结尾的为扩展配置文件。
defconfig可以和config文件进行组合，用以扩展特定的功能，但要注意不能随意组合。

defconfig

在phytium-linux-buildroot根目录下执行$ make list-defconfigs，返回configs目录中的defconfig配置文件。

$ cd xxx/phytium-linux-buildroot
$ make list-defconfigs

其中以phytium开头的为飞腾相关的defconfig配置文件，包含：

phytium_debian_defconfig      - Build for debian system
phytium_defconfig             - Build for busybox minimal system
phytium_initrd_defconfig      - Build for initrd
phytium_ubuntu_defconfig      - Build for ubuntu system

config

config文件是功能扩展配置文件，具体的文件及功能如下：

config	功能
linux_xxx.config	内核配置文件，含有linux 6.6 rt内核版本
desktop.config	XFCE桌面
e2000_optee.config	Phytium-optee

配置文件的组合

defconfig可以和config文件进行组合，用以扩展特定的功能，defconfig与config的组合关系如下：

deconfig	config
phytium_ubuntu_defconfig	linux_xxx.config、desktop.config、e2000_optee.config
phytium_debian_defconfig	linux_xxx.config、desktop.config、e2000_optee.config
phytium_defconfig	linux_xxx.config、e2000_optee.config
phytium_initrd_defconfig

编译文件系统

编译默认配置的文件系统

（1）加载defconfig
$ make phytium_xxx_defconfig
其中phytium_xxx_defconfig为以下文件系统之一：

phytium_ubuntu_defconfig
phytium_debian_defconfig
phytium_defconfig

（2）编译
$ make
（3）镜像的输出位置
生成的根文件系统、内核、img 镜像位于output/images目录。

img 镜像

目前buildroot支持编译img 镜像（disk.img），生成的img 镜像位于output/images目录。img 镜像包含了根文件系统、内核、设备树和GRUB。 使用img 镜像安装系统，不需要像之前那样将存储设备手动分区再拷贝文件，只需要将disk.img文件写入存储设备即可。

支持的功能

更换文件系统的linux内核版本

defconfig中的内核版本默认是linux 6.6。我们支持在编译文件系统时将内核版本更换为linux 6.6 rt。
关于linux内核的信息请参考：https://gitee.com/phytium_embedded/phytium-linux-kernel
更换内核版本的操作步骤为：
（1）使用phytium_debian_defconfig、phytium_ubuntu_defconfig或phytium_defconfig作为基础配置项，合并支持其他内核版本的配置：
$ ./support/kconfig/merge_config.sh configs/phytium_xxx_defconfig configs/linux_6.6_rt.config
（2）编译
$ make
（3）镜像的输出位置
生成的根文件系统、内核、img 镜像位于output/images目录。

支持XFCE桌面

（1）使用phytium_debian_defconfig或phytium_ubuntu_defconfig作为基础配置项，合并支持desktop的配置：
$ ./support/kconfig/merge_config.sh configs/phytium_xxx_defconfig configs/desktop.config
（2）编译
$ make
（3）镜像的输出位置
生成的根文件系统、内核位于output/images 目录。

支持Phytium-optee

Phytium-optee只支持E2000开发板，关于Phytium-optee的信息请参考：https://gitee.com/phytium_embedded/phytium-optee
defconfig默认不编译Phytium-optee，如果需要编译Phytium-optee请执行：
（1）使用phytium_debian_defconfig、phytium_ubuntu_defconfig或phytium_defconfig作为基础配置项，合并支持optee的配置：
$ ./support/kconfig/merge_config.sh configs/phytium_xxx_defconfig configs/e2000_optee.config
目前Phytium-optee支持的E2000开发板有E2000D DEMO和E2000Q DEMO。
（2）编译
$ make
（3）镜像的输出位置
生成的根文件系统、内核、TEE OS位于output/images目录。
后续部署及使用方法，请参考https://gitee.com/phytium_embedded/phytium-embedded-docs/tree/master/optee

initrd

initrd支持E2000和D2000开发板，如果需要使用initrd，请按照以下步骤编译：
（1）配置及编译initrd

$ make phytium_initrd_defconfig 
$ make 

（2）将编译好的initrd备份保存
$ cp ./output/images/rootfs.cpio.gz ~/initrd

清理编译结果

（1）$ make clean
删除所有编译结果，包括output目录下的所有内容。当编译完一个文件系统后，编译另一个文件系统前，需要执行此命令。
（2）$ make distclean
重置buildroot，删除所有编译结果、下载目录以及配置。

树外构建

默认情况下，buildroot生成的所有内容都存储在buildroot源码目录的output目录。然而，buildroot也支持树外构建。树外构建允许使用除output以外的其他输出目录。 使用树外构建时，buildroot的.config和临时文件也存储在输出目录中。这意味着使用相同的buildroot源码树，只要使用不同的输出目录，可以并行运行多个构建。
使用树外构建进行配置的方式有以下三种：
（1）在buildroot源码目录运行，使用O变量指定输出目录：
$ make O=xxx/foo-output phytium_xxx_defconfig
（2）在一个空的输出目录运行，需要指定O变量和buildroot源码树的路径：
$ mkdir xxx/foo-output
$ cd xxx/foo-output
$ make -C xxx/phytium-linux-buildroot/ O=$(pwd) phytium_xxx_defconfig
（3）对于使用merge_config.sh合并配置文件的情况，在buildroot源码目录运行：
$ mkdir xxx/foo-output
$ ./support/kconfig/merge_config.sh -O xxx/foo-output configs/phytium_xxx_defconfig configs/xxx.config

运行上述命令之一，buildroot会在输出目录中创建一个Makefile，所以在输出目录中再次运行make时，不再需要指定O变量和buildroot源码树的路径。
因此配置完成后，编译的命令为：
$ cd xxx/foo-output
$ make

buildroot中修改内核进行编译

buildroot中编译内核源码的目录是output/build/linux-<version>，如果在该目录对内核进行了修改（例如修改内核配置或源码）， 当运行make clean后该目录会被删除，所以在该目录中直接修改内核是不合适的。
因此，buildroot对于这种情况提供了一种机制：<PKG>_OVERRIDE_SRCDIR机制。
操作方法是，创建一个叫做local.mk的文件，其内容是：

$ cat local.mk 
LINUX_OVERRIDE_SRCDIR = /home/xxx/linux-kernel

将local.mk文件和buildroot的.config文件放在同一个目录下，对于树内构建是顶层的buildroot源码目录，对于树外构建是树外构建的输出目录。
LINUX_OVERRIDE_SRCDIR指定了一个本地的内核源码目录，这样buildroot就不会去下载、解压、打补丁内核源码了，而是使用LINUX_OVERRIDE_SRCDIR 指定的内核源码目录。
这样开发人员首先在LINUX_OVERRIDE_SRCDIR指定的目录对内核进行修改，然后运行make linux-rebuild或make linux-reconfigure即可。 该命令首先将LINUX_OVERRIDE_SRCDIR中的内核源码同步到output/build/linux-custom目录，然后进行配置、编译、安装。
如果想要编译、安装内核，并重新生成系统镜像，请运行make linux-rebuild all。

在开发板上启动系统

安装系统

可以通过手动分区的方式安装系统，将存储设备分区、格式化后，再将buildroot生成的文件拷贝到对应的分区； 也可以使用img 镜像安装系统，这种方式不需要手动将存储设备分区再拷贝文件，只需要将disk.img文件写入存储设备即可。

手动分区安装系统

（1）主机端将存储设备分成两个分区（以主机识别设备名为/dev/sdb 为例，请按实际识别设备名更改）
$ sudo fdisk /dev/sdb
这将启动fdisk程序，在其中输入命令：

输入g创建GPT分区表；
输入n创建分区，需要创建两个分区；
输入t将第一个分区的分区类型修改为'EFI System'；
输入p打印分区表，确保输出中包含'Disklabel type: gpt'及第一个分区的类型为'EFI System'；
输入w将分区表写入磁盘并退出。

（2）格式化分区

$ sudo mkfs.vfat /dev/sdb1
$ sudo mkfs.ext4 /dev/sdb2

（3）将内核、设备树和GRUB拷贝到第一个分区（EFI分区），将根文件系统拷贝到第二个分区（根分区）

$ sudo mount /dev/sdb1 /mnt
$ sudo cp xxx/phytium-linux-buildroot/output/images/Image /mnt
$ sudo cp xxx/phytium-linux-buildroot/output/images/pe2204-demo-ddr4.dtb /mnt（用于U-Boot启动）
$ sudo cp -r xxx/phytium-linux-buildroot/output/images/efi-part/EFI/ /mnt（用于UEFI启动）
$ sync
$ sudo umount /dev/sdb1
$ sudo mount /dev/sdb2 /mnt
$ sudo cp xxx/phytium-linux-buildroot/output/images/rootfs.tar /mnt
$ cd /mnt
$ sudo tar xvf rootfs.tar
$ sync
$ cd ~
$ sudo umount /dev/sdb2

使用img 镜像安装系统

将img 镜像（disk.img）写入存储设备：
$ sudo dd if=xxx/phytium-linux-buildroot/output/images/disk.img of=/dev/sdb bs=1M
$ sync

启动系统

U-Boot启动系统

安装系统后，将存储设备接到开发板，启动开发板电源，串口输出U-Boot命令行，设置U-Boot环境变量来启动系统。
SATA盘：

=>setenv bootargs console=ttyAMA1,115200  audit=0 earlycon=pl011,0x2800d000 root=/dev/sda2 rw cma=256M;
=>saveenv;
=>fatload scsi 0:1 0x90100000 Image;
=>fatload scsi 0:1 0x90000000 pe2204-demo-ddr4.dtb;
=>booti 0x90100000 - 0x90000000

U盘：

=>setenv bootargs console=ttyAMA1,115200  audit=0 earlycon=pl011,0x2800d000 root=/dev/sda2 rootdelay=5 rw cma=256M;
=>saveenv;
=>usb start
=>fatload usb 0:1 0x90100000 Image;
=>fatload usb 0:1 0x90000000 pe2204-demo-ddr4.dtb;
=>booti 0x90100000 - 0x90000000

注：由于执行了saveenv命令，下次启动时不用执行第一条setenv bootargs命令。

UEFI启动系统

如果是使用img 镜像安装系统，将存储设备接到开发板，启动开发板电源，即可自动启动系统。
如果是通过手动分区的方式安装系统，安装系统后，还需要在主机端配置存储设备的EFI分区中的/EFI/BOOT/grub.cfg文件，确保菜单条目中内核命令行参数root的值为根分区（这里是第二个分区）。
（1）通过分区UUID
获取第二个分区的UUID：
$ sudo blkid -s PARTUUID -o value /dev/sdb2
将grub.cfg中root的值设置为"root=PARTUUID=xxx"，xxx为分区UUID的值。
（2）通过设备名
将grub.cfg中root的值设置为"root=/dev/sda2"。
然后将存储设备接到开发板，启动开发板电源，自动启动系统。

注意：如果使用UEFI中的ACPI表或设备树文件启动有问题，可以使用img 镜像中的设备树，使用方法参考Wiki： UEFI+DTB启动系统

登录

Ubuntu和Debian系统包含了超级用户root，和一个普通用户user，密码和用户名相同，busybox最小系统只需要输入用户名root。

编译内核模块

关于如何编译内核外部模块，可参考https://www.kernel.org/doc/html/latest/kbuild/modules.html

交叉编译内核模块

使用工具链来交叉编译内核模块，工具链位于output/host/bin，工具链的sysroot为 output/host/aarch64-buildroot-linux-gnu/sysroot。
交叉编译内核外部模块的命令为：

$ make ARCH=arm64 \
CROSS_COMPILE=/home/xxx/phytium-linux-buildroot/output/host/bin/aarch64-none-linux-gnu- \
-C /home/xxx/phytium-linux-buildroot/output/build/linux-xxx/ \
M=$PWD \
modules

开发板上编译内核模块

利用linux-headers可以在开发板上进行内核模块编译，软链接/lib/modules/xxx/build指向linux-headers。
在开发板上编译内核外部模块的命令为：
make -C /lib/modules/xxx/build M=$PWD modules

buildroot编译新的应用软件

本节简单介绍如何通过buildroot交叉编译能运行在开发板上的应用软件，完整的教程请参考buildroot用户手册manual.pdf。

buildroot软件包介绍

buildroot中所有用户态的软件包都在package目录，每个软件包有自己的目录package/<pkg>，其中<pkg>是小写的软件包名。这个目录包含：
（1）Config.in文件，用Kconfig语言编写，描述了包的配置选项。
（2）<pkg>.mk文件，用make编写，描述了包如何构建，即从哪里获取源码，如何编译和安装等。
（3）<pkg>.hash文件，提供hash值，检查下载文件的完整性，如检查下载的软件包源码是否完整，这个文件是可选的。
（4）*.patch文件，在编译之前应用于源码的补丁文件，这个文件是可选的。
（5）可能对包有用的其他文件。

编写buildroot软件包

首先创建软件包的目录package/<pkg>，然后编写该软件包中的文件。
buildroot中的软件包基本上由Config.in和<pkg>.mk两个文件组成。关于如何编写这两个文件，可以参考buildroot用户手册，这里简单概括一下。
（1）Config.in文件中必须包含启用或禁用该包的选项，而且必须命名为BR2_PACKAGE_<PKG>，其中<PKG>是大写的软件包名，这个选项的值是布尔类型。 也可以定义其他功能选项来进一步配置该软件包。然后还必须在package/Config.in文件中包含该文件：
source "package/<pkg>/Config.in"
（2）<pkg>.mk文件看起来不像普通的Makefile文件，而是一连串的变量定义，而且必须以大写的包名作为变量的前缀。最后以调用软件包的基础设施（package infrastructure）结束。变量告诉软件包的基础设施要做什么。
对于使用手写Makefile来编译的软件源码，在<pkg>.mk中调用generic-package基础设施。generic-package基础设施实现了包的下载、提取、打补丁。 而配置、编译和安装由<pkg>.mk文件描述。<pkg>.mk文件中可以设置的变量及其含义，请参考buildroot用户手册。

编译软件包

（1）单独编译软件包

$ cd xxx/phytium-linux-buildroot
$ make <pkg>

编译结果在output/build/<pkg>-<version>

（2）将软件包编译进根文件系统

在phytium_xxx_defconfig中添加一行BR2_PACKAGE_<PKG>=y
$ make phytium_xxx_defconfig
$ make

FAQ

1、下载Ubuntu及Debian太慢或报错？
目前下载Ubuntu及Debian的源为清华大学镜像，如果遇到下载很慢，或者下载报错： E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing? 从而导致编译的带Xfce桌面的系统没有桌面等问题， 请将清华源更换为中科大源，即将以下文件

board/phytium/common/post-custom-skeleton-ubuntu.sh
board/phytium/common/ubuntu-package-installer
board/phytium/common/post-custom-skeleton-debian-11.sh
board/phytium/common/debian-package-installer

中的mirrors.tuna.tsinghua.edu.cn改为mirrors.ustc.edu.cn

2、在Ubuntu或Debian上安装完cpufreq-utils，CPU调频模式不再是performance。
安装了cpufreq-utils以后，会同时安装一个/etc/init.d/cpufrequtils脚本，这个脚本在启动后会将cpufreq的模式设置为ondemand动态调频。 可以把这个脚本改一下：将ENABLE改为false，便不会修改cpufreq策略，或者将GOVERNOR=“performance”。