Building a Custom Mainline Linux Kernel System on the Orange Pi PC | | Updated Sunday, August 6th 2017, 09:21 |
- Build the cross compiler
- Build U-Boot
- Partition the SD card and install U-Boot
- Build the Linux kernel
- Install it and the Arch Root FS onto the SD Card
- Fun and profit :)
Notes
Each time make is invoked to actually compile a program, add -j<num-of-proc> to significantly improve compile times.
The following conventions are used to display commands:
$ foobar % After this character, it is just a comment
# Execute me as root
This is the contents of a file or a note
Prerequisites
This tutorial is written to be followed on an Arch Linux host. While the fundamental steps remain the same with other distributions such as Ubuntu, some parts, especially regarding the installation of the cross compiler, may vary. Here's a short list of requirements and recommendations for following this tutorial. You need ...
- an Orange Pi PC (duh!). The tutorial may also be applicable to other boards, but I can not verify that.
- a USB to serial (3.3V) converter.
- an afternoon of time if you already have some experience. Otherwise plan an entire day.
- to be comfortable with Google. As with everything as freaky as compiling your own kernel from scratch, you will run into problems.
- to be genuinely interested in the topic. If you just need a running system, get a precompiled image.
The following parts are not necessary, but make this work definitely easier. You should have ...
- a fast Internet connection. You will be downloading a lot of data.
- a fast computer. Compiling takes a while, especially building the cross toolchain.
To follow this tutorial, connect to the UART of the Orange Pi PC at a rate of 115200 Baud. The GND/RX/TX pins are located between the power and HDMI jack in that order [1]. Any serial terminal client will work, for example screen:
Make sure you have the proper udev rule for your USB to serial converter so that access as user is possible. For example:
Building the Cross Compiler
In order to compile software for the Orange Pi, or any ARM system for that matter, on your main computer, you will need a so called cross toolchain. This toolchain needs to supply various tools, such as the compiler, linker, assembler and utilities to process binary files beside a few more. Luckily, there is a really great tool called crosstool-ng which does the job of collecting and installing the toolchain for us [2].
In Arch Linux, crosstool-ng can be easily installed using these commands:
$ tar xvf crosstool-ng-git.tar.gz
$ cd crosstool-ng-git
$ makepkg -s
$ sudo pacman -U <file>
Now, you should have the command ct-ng on your computer.
To build the actual toolchain, create a directory to contain the configuration of it. The target for the installation will be a different directory. In this directory, execute the ct-ng menuconfig command.
$ cd toolchain
$ ct-ng menuconfig
This opens a graphical interface to configure the toolchain. Make sure you set the following options:
Target options --> Target Architecture : arm
Target options --> Use specific FPU : vfp
Target options --> Floating point: hardware (FPU)
Target options --> Use EABI : *
Target options --> append 'hf' to the tuple (EXPERIMENTAL) : *
Toolchain options --> Tuple's vendor string : opi
Operating System --> Target OS : linux
Operating System --> Linux kernel version : [select latest]
C compiler --> C compiler : gcc
C compiler --> gcc version : 5.3.0
C compiler --> C++ : *
As crosstool-ng constantly changes, some of these settings may be deprecated by now. So, for example, you can try to select newer versions of the tools and add more features if desired.
Next, to build the toolchain, enter
. This process takes quite some time, so grab a cup of coffee and return to, hopefully, see a toolchain in the above selected build (prefix) directory. If any errors occur, change the version of gcc and try again. Also make sure that crosstool-ng is current.
Setting Up the Build Environment
After the toolchain has been built, it needs to be "enabled". If the toolchain has been built into a directory outside of the system path, it needs to be added to it first. Then, all compile scripts need to be told to compile for ARM and to use the cross toolchain. This can be accomplished using:
$ export ARCH=arm
$ export CROSS_COMPILE=arm-opi-linux-gnueabihf-
As this needs to be done for each newly opened terminal, it is useful to write these commands into a script and execute is using
before working on the project.
To verify that it worked, try to execute the following commands. Each command should print something other than an error message.
[...]
gcc version a.b.c date
$ echo $ARCH|grep arm
arm
$ echo $CROSS_COMPILE|grep arm
arm-opi-linux-gnueabihf-
Building U-Boot
Das U-Boot is the boot loader that we are going to use on the Orange Pi PC. The boot loader is responsible for initializing the hardware of the system (kind of like the BIOS/UEFI in a PC) and starting the actual operating system. U-Boot allows to boot the Orange Pi from either SD card (mmc), USB-Stick or from the network. This chapter explains how to configure, build and install U-Boot onto the SD card.
Before beginning with this chapter, make sure that the environment is configured properly as explained in the previous chapter.
U-Boot is available from the git repository at DENX [3]. As the Orange Pi PC is fully supported in their master branch, its compilation is straightforward.
$ cd u-boot
$ make orangepi_pc_defconfig
$ make
This step produces a u-boot-sunxi-with-spl.bin file, which contains the compiled bootloader. The next step explains how it can be installed onto the SD card so that the Orange Pi PC can boot from it.
SD Card and U-Boot
As the Orange Pi PC directly boots a sector on the SD card, installation is not as simple as copying a file to the card. Instead, a card image needs to be carefully crafted in regard to where partition and raw data are placed. Thankfully, codekipper on the orangepi.org forums provided all required information to create this image [4].
The first step is to create the partitioning of the SD card. To do this, execute the following commands. Replace /dev/sdX with the device name of your SD card. Verify this number very carefully. Failing to do so may result in absolute destruction of your current host installation or even data on currently connected devices! Things after the % do not need to be typed as they are just comments to explain what is going on. All commands need to be executed as root.
# fdisk /dev/sdX
: n
: p
: 2048 % Clearance for the boot loader code
: +15M % Size of the boot partition
: n
: p
: 2
: 32768
: [enter] % Use rest of card for the root FS
: p
: w
You may decrease the size of the root FS partition to make SD card images smaller. This can, although more complicated, also be changed after the fact.
These steps create the partition table. Next, the partitions need to be configured as file systems. The boot loader uses a vfat file system, the kernel uses ext4. Before executing these steps, unplug and replug your SD card to make sure the kernel uses the latest partition table.
# mkfs.ext4 /dev/sdX2
After the partitions are created, it is time to copy the U-Boot binary into the correct place. As already mentioned, it does not go into one of the file systems, but rather into the blank space at the beginning of the card. This can be done by issuing
# sync
from the U-Boot build directory.
At this step, you can take the card and plug it into the Orange Pi PC. After power cycling, the UART console should show the U-Boot console. Press enter to interrupt startup and enter ? to see the version number of the U-Boot release you just compiled. Congratulations!
Building the Linux Kernel
In this step, we will build the Linux kernel itself. It is the most likely step to change over time as the current stable version of the kernel is still missing many of the required features. Information about the status of the so called sunxi drivers in the mainline kernel can be found on their wiki [5]. The stable version of the kernel at the point of writing this post is 4.7.2 (see update below!). This version still lacks support for USB and the Ethernet PHY among some other minor modules. Therefore, the latest development build needs to be obtained. This can be achieved using:
$ cd linux
$ git checkout v4.8-rc4
Update August 2017: As of Linux Kernel 4.13, Ethernet is supported out of the box using the stmmac driver. This makes the following patching steps unnecessary. Make sure to use git checkout v4.13 or newer to get the supported version.
As this version still lacks the networking drivers, these need to be patched in manually. To do this, follow these steps:
$ git pull ethdriver
$ git merge ethdriver/sun8i-emac-wip-v3
If a newer version of the kernel than 4.7.2 is available, try compiling it without any patches first. Directly check out the latest stable release using the following command after cloning the kernel.
Follow the tutorial with this version. Should the resulting system lack Ethernet support, try to apply the patch as noted above.
The next step is to configure the kernel. The INSTALL_MOD_PATH is the path where to place run-time loadable kernel modules. These are required when creating the root FS.
$ make sunxi_defconfig % Load default config for the SoC
$ make menuconfig
and change the following settings:
Device Drivers --> Network device support --> Ethernet driver support --> Allwinner sun8i EMAC support : *
for Kernel 4.13 and above, choose the following driver instead of the Allwinner sun8i EMAC (also enable the sun8i suboption):
Then, to compile the kernel, enter
$ make modules_install
Installing the Kernel and Arch Root File System
First, mount both partitions from the SD card. This tutorial assumes they are mounted to
/dev/sdX2 -> /mnt/sdX2
To install the Kernel onto the SD card, the uImage along with the device tree and the boot script need to be copied onto the previously created VFAT partition. The boot script, written as a U-Boot script, looks as follows [4]:
setenv fdt_high ffffffff
#Settings for booting from the card.
setenv loadkernel fatload mmc 0 \$kernel_addr_r uImage
setenv loaddtb fatload mmc 0 \$fdt_addr_r sun8i-h3-orangepi-pc.dtb
setenv bootargs console=ttyS0,115200 earlyprintk root=/dev/mmcblk0p2 rootwait
setenv uenvcmd run loadkernel \&\& run loaddtb \&\& bootm \$kernel_addr_r - \$fdt_addr_r
run uenvcmd
Write these lines to a file called boot.cmd and run the following command. Copy the resulting boot.scr file to the root of the FAT partition.
Next, copy the previously created <build-root>/linux/arch/arm/boot/uImage file to the same directory on the SD card. To complete the installation of the kernel, the <build-root>/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb file needs to be placed next to the kernel as well.
Finally, the last step is to install the Arch Linux root FS [6]. To do this, download the latest version of alarm. Again, make sure that you are in the right directory before issuing the tar command.
# cd /mnt/sdX2
# tar xvf /path/to/ArchLinuxARM-armv7-latest.tar.gz
$ sync
Optionally, if kernel modules were selected to be built, copy the directory structure from the $INSTALL_MOD_PATH to /mnt/sdX2/lib/modules/<kernel-version>/.
That's it! You're done. Now properly unmount the SD card, put it into your Orange Pi PC and power it up. You should see Arch booting after a few seconds. The default login is root:root.
Linux alarm 4.8.0-rc4-00210-ge81e8f2 #1 SMP Sun Sep 4 18:04:02 CEST 2016 armv7l GNU/Linux
Final Steps
By default, the root file system is read only. To make it writable for a single session, the following command can be used on the Orange Pi PC:
To make the system automatically remount the root file system on startup, create the /etc/fstab file with the following content:
Also, ensure that Arch Linux is up to date by issuing pacman -Syu.
Closing Remarks
Hopefully, this article has helped you to get started building your own Linux system from scratch for the Orange Pi PC. With small changes, this tutorial also applies to many other single-board computers.
As already noted above, this tutorial only takes server use into account. For GPU support, additional drivers and packages are required. This may be covered in a future post.
Thanks for reading and have fun with your new Arch Linux on the Orange Pi PC!
Sources:
[1]: https://linux-sunxi.org/Orange_Pi_PC#Locating_the_UART
[2]: http://crosstool-ng.org/
[3]: http://www.denx.de/wiki/U-Boot
[4]: http://www.orangepi.org/orangepibbsen/forum.php?mod=viewthread&tid=119
[5]: http://linux-sunxi.org/Linux_mainlining_effort#Status_Matrix
[6]: https://archlinuxarm.org/
