User:Rory/PINE64 QuartzPro64/Installing Gentoo

'''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
 * 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
 * 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. I have personally encountered this using SanDisk ultra 16GB cards; the problem manifests itself as timeout/busy messages for mmc1 when booting Linux:

[   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. I personally have successfully used the Kingston Canvas Go! Plus cards.'''

Pre-made image availability
For convenience, or if you do not want to build your own kernel, I have uploaded two images 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:

https://drive.google.com/drive/u/1/folders/1hPSGv482IAx_Co0X_1stnLlOjWWJgqLZ

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

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:

https://www.gentoo.org/downloads/

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

https://drive.google.com/drive/u/1/folders/1SkPsBLyJg3B_RUBif4uwAi7YF3W_cVsq

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… ifconfig eth0 ${IP_ADDR} broadcast ${BROADCAST} netmask ${NETMASK} up  (e.g.: ifconfig eth0 172.17.1.149 broadcast 172.17.1.255 netmask 255.255.255.0 up) route add default gw ${GATEWAY}   (e.g. route add default gw 172.17.1.1) nano -w /etc/resolv.conf   add line nameserver ${NAMESERVER}   (nameserver 172.17.1.1) 5) Partition the desired root device… mmcblk0, sda, nvme0…

6) Mkfs.ext4 /dev/{root device partition}

7) mount /dev/{root device partition} /mnt

8) cd /mnt

9) check/set date

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

11) tar xpf {stage3 tarball}

12) cp /etc/resolv.conf /mnt/etc/resolv.conf

13) cp /etc/inittab /mnt/etc/inittab

14) prep for chroot mount --types proc /proc /mnt/proc mount --rbind /sys /mnt/sys mount --make-rslave /mnt/sys mount --rbind /dev /mnt/dev mount --make-rslave /mnt/dev mount --bind /run /mnt/run mount --make-slave /mnt/run 15) chroot chroot /mnt /bin/bash source /etc/profile 16) emerge-webrsync

17) configure locales nano /etc/locale.gen (enable en_US) locale-gen eselect locale list eselect locale set (number of en_US.utf8; probably 6) 18) emerge-webrsync ( may need to remove timestamp file if warned)

19) emerge –-ask -–verbose -–update -–deep -–newuse @world

20) echo “US/Pacific” > /etc/timezone (substitute for your timezone)

21) emerge --config sys-libs/timezone-data

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

23) nano /etc/fstab (add entry for root device)

24) set host and domain names nano /etc/conf.d/hostname  hostname=”qp64” nano /etc/conf.d/net   dns_domain_lo=”home.arpa” 25) emerge --ask net-misc/dhcpcd

26) rc-update add dhcpcd default

27) rc-service dhcpcd start

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

29) rc-update add sshd default

30) emerge --ask sys-fs/dosfstools

31) useradd –m –G users,wheel –s /bin/bash {username}

32) passwd {username} (set password for normal user)

33) mount /dev/mmcblk1p4 /mnt (mount the efi partition)

34) 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:

PINE64_QuartzPro64/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:

https://github.com/neggles/linux-quartz64

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... mkfs.vfat -n "EFI" /dev/sdXp4 2) Mount the newly formatted partition mount /dev/sdXp4 /mnt 3) create a few directories mkdir -p /mnt/extlinux mkdir -p /mnt/dtbs/rockchip 4) copy the Linux kernel Image file to the EFI partition cp {your linux dir path}/arch/arm64/boot/Image /mnt/Image.qp64 5) copy the dtb file you built to the EFIU partition cp {your linux dir path}/arch/arm64/boot/dts/rockchip/rk3588-quartzpro64.dtb /mnt/dtbs/rockchip/qp64.dtb 6) nano /mnt/extlinux/extlinux.conf (below is an example)

7) unmount the EFI partition umount /mnt

Setting up the root filesystem
8) Create the root filesystem mkfs.ext4 -T small /dev/sdX5 9) Download a Stage3 tarball (either from gentoo or my big endian site)

10) Mount the root filesystem and enter it mount /dev/sdX5 /mnt cd /mnt 11) unpack the stage3 tarball tar xpf {path to your stage 3 tarball} 12) nano /mnt/etc/inittab (add the serial console and comment out one line) s2:12345:respawn:/sbin/agetty ttyS2 vt100 #f0:12345:respawn:/sbin/agetty 9600 ttyAMA0 vt100 13) nano /mnt/etc/shadow (remove the root password) root::10770:0::::: 14) exit the root filesystem and unmount it cd / 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: Note that only SATA port 0 is currently supported; if you need more than one SATA device I have successfully used a 5 port SATA expander with 3 disks... I am confident it will support all 5, but I have not tested this. USB support is "not quite working", however it is expected in the future.
 * microSDHC
 * eMMC
 * SATA disks (HDD or SSD)
 * SATA disks (HDD or SSD)
 * SATA disks (HDD or SSD)

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

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

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