User:Immolo/Sandbox/PearSilicon

Warning
This article is in very early stages so may be incorrect in places. This install should only be attempted by experienced users who are willing to fix the documentation as they go.

Gentoo now provides bootable media with Apple Silicon support. Installing Gentoo on Apple Silicon follows a similar process to doing so on common amd64 hardware, this article will guide the user on the specifics of installing Gentoo Linux on Apple Silicon based hardware.

The only major deviation from the Handbook is the need to use the asahi-gentoosupport package to automate the installation of the kernel, GRUB, Asahi ebuild repository, m1n1, and U-Boot.

Note
Attempting to install the previously-mentioned packages manually is not recommended: it would take longer than bootstrapping the rest of the system combined. Such a manual installation is not supported by Gentoo.

Important
This guide will currently assume that the user is familiar with the Asahi Linux installer! Please help Gentoo to fix this.

Important prerequisite information

Please do not use genkernel or other custom initramfs generators. The only supported initramfs generator is dracut. The sys-apps/asahi-configs package will be installed to supply the necessary configuration files to make dracut work seamlessly.

Note
U-Boot's USB stack is still severely lacking, so it's likely that many peripherals won't reliably work, such as specific USB sticks or keyboards. Unfortunately, there is nothing that can be done about this currently and the workaround is to try different USB devices until finding one that will work.

Set up the Asahi U-Boot Environment

The first step to install Gentoo on Apple Sillicon it to use the Asahi Installer to set up the minimal m1n1 + U-boot UEFI environment. Ensure that the installer is set to leave an appropriate amount of free space that will be required for the Gentoo system.

It may be easier to simply use the Fedora Asahi Remix Minimal installation option, as this will guarantee that space is reserved for the root filesystem.

Important
Do not move on until fully "completing" the Asahi installation.

Bootable media for installation

Acquire the appropriate Gentoo bootable media

Grab the latest bootable media image file from https://distfiles.gentoo.org/releases/arm64/autobuilds/current-install-arm64-minimal/. These images are provided by Gentoo's RelEng project.

Appropriately transfer (aka "flash", "burn", etc.) the bootable media image file to a USB storage device.

Boot into the bootable installation media

Note to editors

disclaimer: there was a lot of guess work in all the changes I made to this doc, there is a fair chance that all I did is break it... the following sections are probably the worst, I may well have wildly misunderstood the procedure here. so: dragons, but work in progress, and immolo: feel free to revert to before I touched it, in the worst case :D -- ris

Now that Asahi is installed, it can be used to get the target machine to boot from the newly prepared USB device.

Connect the bootable installation media USB device.

Start the the target machine, U-Boot will enumerate USB devices on the system, pausing two seconds to allow the automatic boot sequence to be interrupted, if required.

Case 1: following a m1n1 + U-Boot installation

If the option m1n1 + U-Boot installation was chosen, then it should be safe to just let booting proceed.

If luck has it that U-Boot plays nicely with the USB stick, the machine should now boot GRUB from the bootable media.

Case 2: following a complete Asahi operating system installation

If installed from one of the complete operating system images, then the boot process will need to be interrupted (watch carefully for the two second window!) to force U-Boot to boot from the correct USB storage peripheral.

Once U-Boot's automatic boot sequence is interrupted, run this series of commands:

U-BOOT Firmare #setenv boot_targets "usb" U-BOOT Firmare #setenv bootmeths "efi" U-BOOT Firmare #boot

If U-Boot plays nicely with the USB stick, the machine should now boot GRUB from the bootable media.

Continue Gentoo installation

From here, simply follow the Gentoo Handbook for amd64, up until the section for kernel installation.

Warning
When partitioning the machine, it is absolutely vital that the user does not alter any partitions other than the space reserved for the rootfs. This includes the EFI System Partition set up by the Asahi Installer. The user is free to partition the rootfs space in any manner they wish, but do not modify any other structure on the disk. It will most likely require a DFU restore of the Mac if this is ignored.

Install Asahi support files

Merge Git, then clone chadmed/asahi-gentoosupport from GitHub and finally run ./install.sh, which will automatically:

Install the Asahi ebuild repository, which provides the kernel, boot tooling and (possibly) patched packages.
Install the sys-apps/asahi-meta package, which will pull in all the Asahi-specific goodies necessary for booting, including a distribution kernel.
Install and update GRUB.

Run, consecutively:

root #emerge --ask --verbose dev-vcs/git

root #git clone https://github.com/chadmed/asahi-gentoosupport.git

root #cd asahi-gentoosupport

root #./install.sh

Follow the prompts. It will be possible to skip the setup of GRUB, the kernel, and the boot tooling, which can be a bit of a hassle on these machines and may leave with an unbootable Linux setup.

Finalize the install

Finish off the rest of the Gentoo install procedure by following the rest of the handbook, reboot, and have fun!

Maintenance

Getting and applying system updates is a little more involved than a totally "vanilla" Gentoo installation: the Asahi overlay must be kept synchronized and the system firmware must always be updated correctly.

Updating U-Boot and m1n1

When updating the U-Boot or m1n1 packages, Portage will only install the resultant binaries to /usr/lib/asahi-boot/. This is both a security and a reliability measure.

m1n1 ships with a script, update-m1n1, which must be run as root every time the kernel, U-Boot, or m1n1 itself is updated. This script is responsible for collecting the m1n1, U-Boot and Devicetree blobs, packaging them up into a single binary object, and installing it on the EFI System Partition.

For more information on how this works and why it must work this way, consult Open OS ecosystem on Apple Silicon Macs.

Upgrading the kernel

When running through a kernel upgrade, it is extremely important that the Stage 2 m1n1 payload is updated at the same time. m1n1 Stage 2 contains the Devicetree blobs required for the kernel to find the hardware, probe it properly, and boot the system.

Devicetrees are not stable, and a kernel upgrade with new DTs may result in an unbootable system, loss of function, or missing out on a newly enabled feature. To make sure this does not occur, after every kernel upgrade it is imperative to run:

root #update-m1n1

Note for developers and advanced users: It is also possible to install multiple kernels, and make use of eselect kernel to swap the symlink to /usr/src/linux. This is supported, however eselect kernel set and update-m1n1 must be run before every reboot into different kernel. This is to ensure that the system will always boot with the correct DTBs.

Syncing the Asahi overlay

In order to receive Asahi-specific updates, ensure that the Asahi overlay remains synchronized. Portage will do this with emerge --sync, but not with emerge-webrsync.

To synchronize the overlay manually, before trying to update, run:

root #emaint -r asahi sync

No other steps are necessary to make sure that packages are updated, just update the system like normal.