Basic Setup - linux-surface/surface-pro-x GitHub Wiki

Installation

While installation should work with any recent ACPI-based installer (bar some features like WiFi and NVME access), a patched disk image is the easiest way to go.

Via Patched Arch Linux AArch64 Disk Image

We provide a small helper to automatically create a patched disk image at https://github.com/linux-surface/aarch64-arch-mkimg. This assumes that you have access to a Linux host (preferably x86 with Docker support), from which you can run the script.

First, use the default profile to create a bare-bones installer image, as described in the README of that repository. Flash the image to a USB stick and boot from that. Note that you will need to disable secure boot. Further, note that booting may seem to get stuck at two points: First, while loading the initramfs and second, shortly later while extracting it. Both may take some time, so be patient. If you encounter a black screen for longer than 20 seconds, you may need to force-reboot (this is a known issue with the display not coming back up after switching from simplefb to the GPU-based framebuffer).

Once you see the login prompt, you can either login as root/root or alarm/alarm. From there, you can follow the basic Arch Linux installation guide, with the additions noted below. In particular, you will need to install custom kernel and patched firmware packages, set up GRUB to load the device tree and set kernel parameters (see e.g. this for an example config), and manually create a UEFI boot entry via efibootmgr. For WiFi, you will need to install additional packages and set up services. Refer to the WiFi page for more details.

Via ACPI Mode

Basic installation to a USB drive should work with any recent kernel by booting it in ACPI mode, you, however, will need to specify efi=novamap on the kernel command line.

Installation to the NVME drive requires reverting commit 8fd4391ee717 ("arm64: PCI: Exclude ACPI "consumer" resources from host bridge windows") to enable NVME support in ACPI mode. If you plan on installing to the NVME, you will therefore either need a patched installation kernel or use a bootstrap process by installing to a USB first and then moving the installation to the NVME.

Note that booting in ACPI mode only provides basic support. This essentially means: Basic framebuffer, USB, and, if patched NVME only. Neither WiFi, the internal keyboard, touch, nor GPU acceleration will work. This will not change for the foreseeable future as focus is on enabling support via device trees (DT).

Packages

Pre-built Arch Linux AArch64 kernel and firmware packages are provided in our Package Repository. The packages you need to install are:

  • linux-surface: Linux kernel with patches for Surface Pro X
  • linux-surface-headers: Linux kernel headers with patches for Surface Pro X
  • linux-firmware-msft-surface-pro-x: Base firmware.
  • linux-firmware-msft-surface-pro-x-qcom: Qualcomm-specific firmware.

For WiFi, you will need to install additional (external) packages, as described in the WiFi section.

Kernel Command Line Parameters

The following kernel command line parameters must be set:

  • efi=novamap to prevent lockups during early boot (for both ACPI and DT boot)
  • clk_ignore_unused to prevent disabling of unused clocks during early boot, causing lock-ups (for DT only)

Initram

Including extra modules in the initramfs may be required when you want to boot form USB.

USB Support

For USB support (if not built into the kernel):

  • phy-qcom-qmp
  • phy-qcom-snps-femto-v2
  • dwc3-qcom

For storage (if not included automatically):

  • uas
  • usb_storage

Manual UEFI Boot Entry

The efibootmgr tool can (as of v5.19-rc7) be used to create boot entries manually. See various documentation online on how to use it. In case it fails, make sure you have efivarfs mounted, e.g. via mount -l. You can mount efivarfs via

mount -t efivarfs none none /sys/firmware/efi/efivars

Alternatively, a new boot entry can be added manually from an EFI shell (which can, for example, be obtained from https://archlinux.org/packages/extra/any/edk2-shell/). From the shell, an entry can be added via

bcfg boot add 0 FS0:\EFI\Grub\grubx64.efi GRUB

where 0 is the entry index (zero indicating it will be added as first entry), FS0:\EFI\Grub\grubx64.efi is the path to the EFI executable to launch (adjust this as needed), and GRUB is the entry name. You can verify all current boot entries via

bcfg boot dump -v

Notes: You can use the cd and dir commands to navigate. Drives are selected with their name, e.g. by stating FS0: (without any command).