Jump to content

Apple M-series Macs (apple-mac-aarch64)

From postmarketOS Wiki
Apple Apple M-series Macs
Apple M-series Mac devices running postmarketOS
Apple M-series Mac devices running postmarketOS
Manufacturer Apple
Name Apple M-series Macs
Codename generic-apple-mac
Model Various (MacBooks, Mac Mini)
Released 2020
Type generic
Hardware
Chipset Apple M1
Apple M2
Apple M3
Apple M4
CPU ARM64 (4-12 cores
varies by model)
GPU Apple GPU (7-40 cores, varies by model)
Display Varies by model (13.3" to 32" displays, or headless)
Storage 256GB-8TB SSD (varies by model)
Memory 8GB-128GB unified memory (varies by model)
Architecture aarch64
Software
Original software
The software and version the device was shipped with.
macOS 11.0+ (varies by model)
Extended version
The most recent supported version from the manufacturer.
macOS
FOSS bootloader yes
postmarketOS
Category testing
Pre-built images
Whether pre-built images are available from the postmarketOS Installation page.
no
Mainline
Instead of a Linux kernel fork, it is possible to run (Close to) Mainline.
yes
Device package device-generic-apple-mac out-of-tree
Kernel package linux-asahi
Firmware package -
Initial MR
Initial merge request.
pmaports!7048
Features
Battery
Whether charging and battery level reporting work.
Works
Screen
Whether the display works; ideally with sleep mode and brightness control.
Works
Keyboard
Whether the built-in physical keyboard works.
Works
Touchpad
Whether the built-in touchpad works.
Works
Multimedia
3D Acceleration
Works
Audio
Audio playback, microphone, headset and buttons.
Works
Camera
Works
Connectivity
WiFi
Works
Bluetooth
Works
Miscellaneous
FDE
Full disk encryption and unlocking with unl0kr.
Works
USB-A
Whether the full-sized USB-A port works.
Works
HDMI/DP
Video and audio output with HDMI or DisplayPort.
Partial
U-Boot
Secondary Bootloader
Whether it is possible to chainload U-Boot from stock bootloader.
Works
Mainline
Whether latest upstream versions of U-Boot are not broken and it is possible to use them.
Works
Internal Storage
Whether it is possible to boot from internal storage (e.g. eMMC or UFS).
Works
USB Host
Whether it is possible to boot from a USB storage or connect a keyboard.
Works
USB Peripheral
Whether it is possible to use device as a peripheral in U-Boot, e.g. for fastboot mode.
Works
Display
Works
Keyboard
Works
Note Note: This is a generic device package that supports multiple Apple M-series Mac models.
Note Note:For Intel-based Apple Mac support see the Generic x86 64 (generic-x86 64) port

Contributors

Users owning this device

Supported Models

This generic device package has only been tested on a very limited number of models, however in theory it should work with devices supported by the Asahi Linux project. For up to date status, see the Asahi Linux documentation for supported models and features.

Installation

Prerequisites

Before installing postmarketOS, you need to set up a basic UEFI environment using the Asahi Linux installer:

  1. Run the Asahi installer from macOS
  1. Choose the "UEFI only" installation option
  1. Allocate desired space for Linux

Using pmbootstrap

Warning WARNING: Do not use pmbootstrap install --disk or otherwise cat/dd the image created by pmbootstrap to install postmarketOS to the local storage device! Doing so will overwrite required Apple/APFS partitions and will require wiping the disk to recover. You have been warned!

Follow Installation/Using pmbootstrap. When asked for the device's vendor/codename, select apple as the vendor and mac-aarch64 as the codename.

External Boot (USB)

postmarketOS can be booted from USB drives:

  1. Create a bootable USB stick:
$ pmbootstrap install --disk /path/to/usb/stick
  1. Reboot, U-Boot should detect and boot from the USB stick if there is no other Linux OS installed to local storage.

If U-boot fails to find the USB stick, try running usb reset from the U-Boot command-line.

If there is another Linux OS installed to local storage and U-Boot boots it instead of the USB stick, you can use the `eficonfig` utility from the U-Boot command-line to change the EFI boot order in U-Boot so that it tries to boot from USB first.

Note Note: Support for using the OS Installer is WIP

Installing on internal drive

At this point, if you've followed the above instructions, you are able to boot postmarketOS from a USB drive, and your Mac's internal drive has a large partition of unallocated space. This is sub-ideal, as closing the laptop or any usb disconnection issues will cause your system to be nonworking.

All you need to get postmarketOS running from the internal drive is to create two postmarketOS partitions in this empty space (boot and root). It's still very easy for you to overwrite your recovery, OS, and bootloader, and need to do a restore, so be very careful not to do that, because that is a much worse place than where you started.

Create partitions

Make two partitions in the unallocated space. The first should be 256 MiB. The second should be the remaining space.

Create images
 pmbootstrap install --split

will create two separate images that you might want to use.

Write images to the partitions

Do not use Gnome Disks to do this. Gnome Disks makes it way too easy to overwrite the whole disk, rather than just write your image to a partition of it. Don't make the same mistake of those who went before you!

The boot image that gets created may actually be bad. It has the wrong sector size (if you flash it, you'll end up seeing "FAT sector size mismatch (fs=512, dev=4096)". For this reason, the following instructions will suggest to copy your current /boot with rsync, then modify it so it points to the correct root and boot partitions.

 # See your partitions, identify them
 lsblk 

The following instructions will assume /dev/nvme0n1p6 is your boot partition, and /dev/nvme0n1p7 is your root partition.

 # Copy the root image to the newest partition
 dd if=./.local/var/pmbootstrap/chroot_native/home/pmos/rootfs/apple-mac-aarch64-root.img of=/dev/nvme0n1p7 bs=4M
 
 # Format as fat32 with expected label
 sudo mkfs.fat -F 32 /dev/nvme0n1p6 -n pmOS_boot
 # mount it
 sudo mkdir /mnt/new_boot
 sudo mount /dev/nvme0n1p6 /mnt/new_boot
 # Copy files from your current /boot into this new boot
 sudo rsync -vax /boot/ /mnt/new_boot
 # Edit pmos.conf to set the correct root_uuid
 # Note the UUID of your boot partition
 ls -lah /dev/disk/by-uuid | grep nvme0n1p7
 vi /mnt/new_boot/loader/entries/pmos.conf
 # change pmos_root_uuid to what was noted above. Otherwise, you'll end up with pmos not being able to find your root drive.
 # you should also change pmos_boot_uuid to the one for nvme0n1p6

at some point, you'll want to run resize2fs over your root file system.

MacOS / Recovery APFS Restoration

idevicerestore can be used to recover MacOS and the recovery APFS partition, e.g. if they are accidentally wiped:

$ doas apk add idevicerestore

There's an excellent guide for how to enter DFU mode and use idevicerestore on the Fedora remix wiki.

If this fails, you can always try the Apple support URL which appears on the screen (instructions require another macOS device), or take it to a nearby Apple store for a restore. (In any case, the technical process takes about 30 minutes).

Miscellaneous

Enabling the notch

The top notch on Macbooks can be re-enabled by adding appledrm.show_notch=1 to the kernel command line

Just make a file in /etc/kernel-cmdline.d/ with that line according to https://docs.postmarketos.org/pmaports/main/kernel-cmdline.html

Then run sudo mkinitfs

Swapping Fn and Ctrl keys

On Macbooks, the left Fn and Ctrl keys can be swapped by adding hid_apple.swap_fn_leftctrl=1 to the kernel command line

There are a few more keyboard remapping/swaps that can be configured as well, see modinfo hid_apple output for more information.

Bootloader

Apple M-series Macs use a complex boot chain: Apple firmware → m1n1 stage 1 → m1n1 stage 2 → U-Boot → systemd-boot/GRUB → Linux

m1n1

m1n1 is the bootloader developed by the Asahi Linux project to bridge Apple's boot ecosystem to standard Linux boot. It performs hardware initialization and chainloads U-Boot. This is packaged in Alpine Linux as m1n1.

U-Boot

U-Boot provides UEFI services and can boot from external media. It enables standard PC-like boot behavior. This is packaged in Alpine Linux as u-boot-asahi.

Known issues

A list of known issues can be found in the pmaports repository


See also