View source for Quartz64 UEFI with U-Boot

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

 sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
** Tested on 2023-07-28 by [[User:CounterPillow]] on a Quartz64 Model B, installer booted from USB3 thumb drive. Installer has about 1 minute of showing a black screen until things appear on HDMI.
** Note: Installer overwrites U-Boot if installing on the U-Boot medium even with offset! Flashing U-Boot again after installation works.
** Note: Some concerning panfrost clk errors in dmesg and KDE Plasma Desktop defaults to X11 for now, not a good user experience
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)
** Tested on 2023-07-29 by [[User:CounterPillow]] on a Quartz64 Model B, Ubuntu 22.04.2 LTS, installer booted from USB3 thumb drive. Only installer boot tested, no installation performed.
** Note: You '''need''' to choose the HWE kernel in GRUB over Serial Console for 22.04 LTS, otherwise the installer won't boot
** Note: Does not allow setting an offset for partitions, so can't use the same medium for both u-boot and root
** Note: Some concerning panfrost clk errors in dmesg while installer boots, unsure if GPU will be happy

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (block 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]