Installing ArchLinuxARM with UEFI on the MACCHIATObin - 2021-08-31

So I've decided to write this little guide because of how much I've suffered to get this to work, and how absolutely broken the MACCHIATObin documentation is. Actually, just their website in general is broken. Marvell, please get your act together with your website. It's not as if you're modifying it all that often, so stop breaking things.

With that out of the way, let's get to business.

Requirements

Aside from the MACCHIATObin itself (which I believe should be fairly obvious), you're also going to want the following:

SD card (maybe a few)
USB storage device
USB to micro-USB cable
12V power supply
ATX power supply
Graphics card (I'm using the NVidia GT 710)
Hard drive
SATA cable
Monitor
USB keyboard

Prepare ArchLinuxARM U-Boot SD Card

It's very possible you'll run into issues later when installing UEFI onto the SPI, so it's good to have an SD card that you can boot from, so as to have access to a prompt. For this, I suggest going through the entire U-Boot install instructions provided by ArchLinuxARM.^[1] I also suggest paying attention to the DIP switch or jumper settings, and pay attention to which are for SD card and SPI boot. This should appear on the board, and in the ArchLinuxARM documentation it shows the settings for SD card boot, but I'll repeat both here:

	Switches/Jumpers
Boot Type	1	2	3	4	5	6
SD Card	OFF	ON	ON	ON	OFF	ON
SPI	OFF	OFF	OFF	ON	ON	OFF

Use this as a guide for whenever I refer to booting from SD card or from the SPI.

Install UEFI on SPI

The documentation for this can properly be found on the Solid Run Developer Center^[2], but I'll be repeating here, mostly because I've had issues with a few of the options.

Firstly, regarding the different options for obtaining a flash image, I'll just say that I've tried the docker image, and I've tried compiling natively on the MACCHIATObin, but both of these ran into issues. The docker image ran into a syntax error^[3] and the native build had some issues when running Python tests, namely with codec.lookup('ucs-2'), saying it couldn't find the codec. Ultimately both errors are Python problems. Coincidence? I think not! But I'll forget about my disliking of Python for now and get on with this guide.

So really, the best option is to use the pre-built binary, which is SPI specific.^[4] Once you have this, you're gonna want to save it to the USB storage device using a FAT32 formatted partition. If you're reading this sort of guide you should already know how to format a USB storage device, but I'll remind you that you don't only have to format the partition with mkfs.vfat -F 32 <partition>, but you actually also have to set the partition type to FAT32 when creating the partition with fdisk (or similar tools). I say this because I forgot to do this, and wasted some time here.

Once you have this done, copy the image binary onto the newly formatted storage device. You can either keep the name of uefi-mcbin-spi.bin or you can change it to flash-image.bin, which is the filename used in the Solid Run documentation for flashing to SPI from U-Boot. Your choice, just make sure to take it into consideration. I'll use uefi-mcbin-spi.bin since that's what I used anyways.

Now that this is done, it's time to flash the image to the SPI. To do this, insert the USB storage device into the USB 3.0 slot on the MACCHIATObin, and insert the SD card with ArchLinuxARM (and U-Boot) into the SD card slot. Set the jumpers to boot from the SD card. Connect to the MACCHIATObin via serial USB. Finally, boot the machine and make sure to interrupt the boot process (when prompted) to enter the U-Boot console. From here, we'll be running the instructions for installing an image to the SPI Flash via U-Boot found in the documentation,^[5] modifying, of course, for the filename:

usb start
load usb 0:1 $kernel_addr_r uefi-mcbin-spi.bin
sf probe
sf write $kernel_addr_r 0 0x$filesize

To test to see if this has worked, turn off the MACCHIATObin, switch the jumpers to boot from SPI, and check to see if you get a UEFI prompt. This should appear not only if you start up in a serial console, but also on a screen if you have everything hooked up with the graphics card. If you do see a prompt, then all has worked as expected. If you don't, try doing this process a few more times. It gave me some weird errors the first few times I tried, and then magically it started working after what must've been the third time.

Installing ArchLinuxARM

I wanted to note that I have uploaded a video to Odysee demonstrating how to do this step.^[10]

Preparing the Installation Media

Since we're going for a desktop setup, the ideal is to install the entire OS onto a hard drive connected via one of the SATA ports. The issue here isn't so much the installation itself, but the live OS used to install it. The reason is that ArchLinuxARM does not currently provide images, much less images configured for UEFI boot. If the SD card we've used earlier provides access to an internet connection as well as to the hard drive you wish to install on, then use that. If not, you'll have to get a live image of some other distribution to boot from that supports UEFI and can access the hard drive. In my case, I used the Debian ARM64 image (not netinst!).^[6] Since it is an installation media, I had to install it from a USB stick onto a SD card to finally work from the SD card to install ArchLinuxARM to the hard drive.

Regardless of the image you choose to use, make sure you can install the Arch Install Scripts (usually arch-install-scripts), as it's going to make your life easier to use genfstab and arch-chroot.

Installation & Configuration

If you're familiar with the installation process of normal ArchLinux (amd64) or some other more manual installation process, such as Gentoo, then from this point on everything should be quite familiar. First, partition the hard drive with the partitions you want and format them; then mount the partitions in the structure you want (e.g. home partition mounted as /mnt/home); finally we populate the filesystem with the files we want. Whereas the ArchLinux Installation Guide tells us to use pacstrap, it doesn't make much sense for us to use this. So instead, we'll be using the tarball provided by ArchLinuxARM for aarch64 platforms.^[7] Simply extract the tarball over the mounted root directory to populate everything. This step replaces pacstrap. After this you can basically follow the ArchLinux Installation Guide^[8] The only step that will be different is when we install our boot loader.

Installing the Boot Loader (GRUB)

This step has a small trick to it. The process is for the most part exactly the same as what is described in the instructions found on the ArchWiki,^[9] with an extra step right before running the grub-mkconfig command.

If you try running grub-mkconfig, you'll notice that it doesn't create any entries for the OS we've just installed. This is because the kernel in ArchLinuxARM uses the filename Image, which the image finder of grub-mkconfig doesn't recognize. As you can imagine, this can be solved by just making a simple symbolic link to the kernel file with a filename that is recognized. In my case, I simply created a link named vmlinuz-linux as appears on my x86_64 machine:

cd /boot
ln -s Image vmlinuz-linux

Reboot

At this point, the OS should be properly installed, and you should be able to reboot the machine into ArchLinuxARM from UEFI on your MACCHIATObin. Do make sure to remove whatever live media you were using for the installation.

Happy hacking!

References

Last updated: 2021-11-16