User:Rory/PINE64 QuartzPro64/Installing Gentoo

From Gentoo Wiki
Jump to:navigation Jump to:search
The QuartzPro64 may be booted from either the eMMC device or a micro-SDHC card, however it is HIGHLY ADVISED to use a micro-SDHC card until you are absolutely sure that you have a working configuration. The eMMC device is soldered on the board, and the recovery process using the rkdeveloptool will not be covered in this page if you make a mistake. The process to use the eMMC is the same as using microSDHC once you have a system booting from the micro-SDHC with the exception of the device name.

What you will need

  • A micro-SDHC card, capacity of at least 4GB is recommended.
  • A micro-SDHC reader/writer for use with your Linux host
  • A USB cable to use a serial port as console; either USB-C to USB-C or USB-C to USB-A depending on your environment

Notes on micro-SDHC card brand sensitivity

There are currently compatibility issues with certain micro-SDHC card brands/models. This is thought to be due to either incorrect voltage regulator settings or reset timing in the handoff between U-Boot and the Linux kernel. SanDisk ultra 16GB cards have been shown to exhibit this issue; the problem manifests itself as timeout/busy messages for mmc1 when booting Linux:
root #dmesg
[    3.772758] mmc_host mmc1: Timeout sending command (cmd 0x202000 arg 0x0 status 0x80202000)
[    3.810511] mmc1: error -110 whilst initialising SD card
[    4.310983] dwmmc_rockchip fe2c0000.mmc: Busy; trying anyway
[    4.811481] mmc_host mmc1: Timeout sending command (cmd 0x202000 arg 0x0 status 0x80202000)
[    4.825983] mmc_host mmc1: Bus speed (slot 0) = 300000Hz (slot req 300000Hz, actual 300000HZ div = 0)
[    5.349543] dwmmc_rockchip fe2c0000.mmc: Busy; trying anyway
[    5.850045] mmc_host mmc1: Timeout sending command (cmd 0x202000 arg 0x0 status 0x80202000)
[    5.864729] mmc_host mmc1: Bus speed (slot 0) = 200000Hz (slot req 200000Hz, actual 200000HZ div = 0)
[    6.390953] dwmmc_rockchip fe2c0000.mmc: Busy; trying anyway
[    6.891457] mmc_host mmc1: Timeout sending command (cmd 0x202000 arg 0x0 status 0x80202000)
Recommended micro-SDHC cards are: Silicon Power that say "3D NAND" on the front ("Superior Pro" series) and Kingston Canvas Go! Plus cards. Kingston Canvas Go! Plus cards have been proven to work.

Pre-made image availability

For convenience, or if you do not want to build your own kernel, there are two pre-built images available for download that may be copied to a micro-SDHC card of at least 4GB capacity. The two images contain the boot loader, U-Boot, an EFI partition with a Linux kernel, and a root partition with the Gentoo stage3 environment. The difference in the two images is whether you want a little endian (most common) or big endian environment. The images may be downloaded from:

qp64be.flash.image.gz <= big endian environment

qp64.flash.image.gz <= little endian environment (What you probably want)

Once you have downloaded and uncompressed either of these images you may use dd or any other tool you like to copy the image to your micro-SDHC card

root #dd if=./qp64.flash.image of=/dev/sdX

Where to get Stage 3 tarballs

If you want a little endian environment (the most common), you may download stage3 tarballs directly from the Gentoo site; almost everyone should download from:

If you REALLY want a big-endian environment, you will need to get stage 3 from this public download area:

Please be sure to download the latest stage3 tarball for the most stable results...

Note that for the remainder of this tutorial we will consider only openrc environments. Be sure to download the correct Stage3 tarball!

Installing Gentoo Linux

Until networking and sshd are configured, you will need to use a serial port console for the initial configuration/installation. You must connect to the board's USB-C debug port and configure your terminal software to use 1500000 baud, 8 data bits, no parity bits, and 1 stop bit (8N1).

The fast way

The fastest way to install Gentoo is to use my premade images (above). You will not need to compile your own kernel prior to installation (you can do so after installation if you need/want to), and you can skip all the steps below in "The harder (but not too hard) way"

1) Insert the micro-SDHC card that was flashed with my bootable image into the QuartzPro64

2) Power on the QuartzPro64 (you should see boot messages on the serial port console, followed by a login prompt)

3) Login as root. There is no password.

4) Manually setup network parameters…

root #ifconfig eth0 <IP_ADDR> broadcast <BROADCAST> netmask <NETMASK> up
  (e.g.: ifconfig eth0 broadcast netmask up)
root #route add default gw <GATEWAY>
  (e.g. route add default gw
root #nano -w /etc/resolv.conf
  add line nameserver <NAMESERVER>}
  (e.g. nameserver

5) Partition the desired root device… mmcblk0, sda, nvme0…

root #fdisk /dev/<root device>

6) Initialize the root filesystem

root #Mkfs.ext4 /dev/<root device partition>

7) Mount the new filesystem

root #mount /dev/{root device partition} /mnt

8) Enter the new root filesystem

root #cd /mnt

9) check/set date

10) scp, wget, or curl to copy stage3 tarball to /mnt

11) Unpack the stage3 tarball

root #tar xpf <stage3 tarball>

12) Prepare DNS for chroot

root #cp /etc/resolv.conf /mnt/etc/resolv.conf

13) Copy inittab to enable serial console

root #cp /etc/inittab /mnt/etc/inittab

14) prep for chroot

root #mount --types proc /proc /mnt/proc
root #mount --rbind /sys /mnt/sys
root #mount --make-rslave /mnt/sys
root #mount --rbind /dev /mnt/dev
root #mount --make-rslave /mnt/dev
root #mount --bind /run /mnt/run
root #mount --make-slave /mnt/run

15) chroot

root #chroot /mnt /bin/bash
root #source /etc/profile

16) Update Gentoo data

root #emerge-webrsync

17) configure locales (enable your local, i.e. en_US...)

root #nano /etc/locale.gen
root #locale-gen
root #eselect locale list
root #eselect locale set <your locale>

18) Resync; you may need to romove the timestamp file if warned

root #emerge-webrsync

19) Update the world...

root #emerge –-ask -–verbose -–update -–deep -–newuse @world

20) Set your timezone (i.e. "US/Pacific")

root #echo “<your timezone>” > /etc/timezone

21) Configure timezone data

root #emerge --config sys-libs/timezone-data

22) Update your environment

root #env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

23) Add your root device to fstab

root #nano /etc/fstab
/dev/<root partition> / ext4 noatime 0 0

24) set host and domain names

root #nano /etc/conf.d/hostname
root #nano /etc/conf.d/net

25) Install dhcpcd

root #emerge --ask net-misc/dhcpcd

26) Add dhcpcd to default run level

root #rc-update add dhcpcd default

27) Start the DHCP client daemon

root #rc-service dhcpcd start

28) Set the root password (edit /etc/security/passwdqc if rules too strict; enforce=none)

root #passwd

29) Enable sshd in default run level

root #rc-update add sshd default

30) Add DOS filesystem tools

root #emerge --ask sys-fs/dosfstools

31) Add a normal user so you can ssh in...

root #useradd –m –G users,wheel –s /bin/bash <username>

32) Set a password for the normal user

root #passwd <username>

33) Mount the EFI partition of the micro-SDHC card

root #mount /dev/mmcblk1p4 /mnt

34) Edit the boot configuration file

root #nano /mnt/extlinux/extlinux.conf
add a new entry for your new root device
reboot and select your new entry
if everything goes well, set it as the default

You now may ssh into the system and the serial port console is no longer needed...

The harder (but not too hard) way

This section assumes that since you want to build all this from scratch, you did the same for U-Boot as outlined on this page:

Installing U-Boot

Furthermore it assumes that you have already partitioned the micro-SDHC as described and copied both the boot loader and U-Boot image to the card.

Building the kernel

Until all the patches for the QuartzPro64 make it into the mainline kernel, Neggles' repository seems like the defacto standard. It is located at:

Building the kernel is beyond the scope of this document... but the general rules apply. If you want to build the big endian kernel without using my prebuilt image as the base you will need to setup a cross development environment - again beyond the scope of this tutorial.

After building the kernel, you will need to locate both the kernel Image file and the dtb file for the QuartzPro64. From the top of the kernel source directory the respective paths are:

arch/arm64/boot/Image and arch/arm64/boot/dts/rockchip/rk3588-quartzpro64.dtb

Setting up the EFI filesystem

1) Format the micro-SDHC card partition previously created...

root #mkfs.vfat -n "EFI" /dev/sdXp4

2) Mount the newly formatted partition

root #mount /dev/sdXp4 /mnt

3) create a few directories

root #mkdir -p /mnt/extlinux
root #mkdir -p /mnt/dtbs/rockchip

4) copy the Linux kernel Image file to the EFI partition

root #cp {your linux dir path}/arch/arm64/boot/Image /mnt/Image.qp64

5) copy the dtb file you built to the EFIU partition

root #cp {your linux dir path}/arch/arm64/boot/dts/rockchip/rk3588-quartzpro64.dtb /mnt/dtbs/rockchip/qp64.dtb

6) Create a boot configuration file

root #nano /mnt/extlinux/extlinux.conf
FILE /mnt/extlinux/extlinux.confRK3588 example extlinux.conf
default 10
 menu title QuartzPro64 Boot Menu
 prompt 0
 timeout 100

 label 10
 menu label Boot installation image
 linux /Image.qp64
 fdt /dtbs/rockchip/qp64.dtb
 append earlycon=uart8250,mmio32,0xfeb50000 console=ttyS2,1500000n8 loglevel=8 root=/dev/mmcblk1p5 rw rootwait

7) unmount the EFI partition

root #umount /mnt

Setting up the root filesystem

8) Create the root filesystem

root #mkfs.ext4 -T small /dev/sdX5

9) Download a Stage3 tarball (either from gentoo or the big endian site)

10) Mount the root filesystem and enter it

root #mount /dev/sdX5 /mnt
root #cd /mnt

11) unpack the stage3 tarball

root #tar xpf <path to your stage 3 tarball>

12) Add entries for serial port console and remove problematic line...

root #nano /mnt/etc/inittab
s2:12345:respawn:/sbin/agetty ttyS2 vt100
#f0:12345:respawn:/sbin/agetty 9600 ttyAMA0 vt100

13) Remove root password

root #nano /mnt/etc/shadow

14) exit the root filesystem and unmount it

root #cd /
root #umount /mnt

At this point your micro-SDHC should be a bootable Stage3 environment without a root password. You may now install Gentoo by following the steps in "The Fast Way" above

Supported root devices

Currently the following devices have been tested as root devices:

  • microSDHC
  • eMMC
  • SATA disks (HDD or SSD)

Note that only SATA port 0 is currently supported; if you need more than one SATA device a 5 port SATA expander with 3 disks has been proven to work... 5 disks will probably work; it has just not been tested yet. USB support is "not quite working", however it is expected in the future.

Note that it is easy to configure and select from multiple installed kernels and root environments...

root #mount /dev/mmcblk1p4 /mnt
root #cd /mnt/extlinux
root #nano extlinux.conf

This file contains examples of several different root devices as well as defining a default choice for unattended boot.