This is a repository for all the tweaks and tricks required to get Gentoo Linux installed on a Microsoft Surface Pro 3.

The process for this was heavily cribbed from this Winero article, but with the addition of making things work in Gentoo as well as other bits of research found elsewhere over time.

• Use SystemRescueCD as it supports booting from EFI which is necessary as the Surface Pro 3 doesn't have a fallback BIOS mode. If you want to use a pure Gentoo build, then the utility Rufus can be used to make an EFI-compatible USB stick from the Gentoo Live ISO.
• Do not remove the Windows partition. Instead, resize it, either with a Windows-based partitioner, or with gparted. If your windows partition is encrypted with bitlocker, you will need to use the disklocker utility to access it.

Note: disklocker is in beta and may destroy your data! Though this has been shown to work just fine for some users, your mileage may vary.

• You need to keep Windows on there, unless you're super-brave and/or overconfident. At the very least you'll need it if you ever want firmware updates, but more likely you'll want it to boot into when things go wrong with your Linux setup.

You Will Need:

• A USB keyboard
• Either a USB hub or a Micro SD card

1. Disable SecureBoot. Unless you'd like to go through the effort of figuring out how to get it working in Linux, it's probably best just to turn this off. You can do this by booting into the UEFI via windows, or by the following "secret handshake":

   1. Turn off your Surface
   2. Hold down the volume-up rocker
   3. While holding down the volume-up rocker push the power button once
   4. Wait until you see the Surface startup logo, then let go of the volume.

   Once in there, you can turn off SecureBoot. Note that from here-on-in, if you've updated your firmware, the Surface logo will be on an ugly red field at boot time. It's annoying I know. Blame Microsoft.

2. Follow SystemRescueCD's instructions for putting it on a USB stick. Use these instructions to put it either on a USB stick (in your USB hub), or onto your Micro SD. If you want to use a Gentoo Live ISO, use Rufus and be sure to select the EFI compatible GPT partition format.

3. Boot into Windows and use it to boot off of the USB or SD card

4. Start the gui. I know it sounds silly, but the command line stuff doesn't seem to like the wifi adapter, and the USB ethernet adapter proved to be flaky as well. Gentoo's Live ISO also doesn't work with wifi, but does with the docking station Ethernet.

5. Use the gui to connect to your wifi.

6. Open a terminal and follow the Gentoo installation handbook, (or Sakaki's excellent guide) using the following partitioning scheme:

   /dev/sda1       2048    739327    737280  360M Windows recovery environment
   /dev/sda2     739328   1148927    409600  200M EFI System
   /dev/sda3    1148928   1411071    262144  128M Microsoft reserved
   /dev/sda4    1411072 103811071 102400000 48.8G Microsoft basic data
   /dev/sda5  103811072 500117503 396306432  189G Linux filesystem
   

   Be sure to use gparted or gdisk), as you'll need to support GPT.

7. Emerge dev-vcs/git and then checkout the Marvell repo of drivers and such to somewhere out-of-the-way. Then create a symlink so your kernel sources can find it:

   # emerge dev-vcs/git
   # git clone git://git.marvell.com/mwifiex-firmware.git /opt/mwifiex-firmware/
   # ln -s /opt/mwifiex-firmware/mrvl /lib/firmware/mrvl
   

8. Continue with the install, and when you get to the kernel compilation step, emerge gentoo-sources and then copy the relevant .config file from this repo into /usr/src/linux/.

9. Patch your kernel. Instructions for doing this depend on the kernel version you're using and can be found in the README in the kernel folder.

10. Run make oldconfig just in case.

11. Build and install your new kernel. This will take about an hour since the current .config we've got still needs some customisation for this device:

    # make -j5 && make -j5 modules_install && make install
    

12. Do the rest of the install, making sure to install GRUB with:

    # grub2-install --target=x86_64-efi
    

    and then configure it to use your new kernel(s) with:

    # grup2-mkconfig -o /boot/grub/grub.cfg
    

    Note that Sakaki's scripts do this for you if you're following his build guide for EFI.

13. Finally, you need to emerge efibootmgr and run the following command to configure your shiny new toy:

    # emerge sys-boot/efibootmgr
    # efibootmgr --bootorder 0000,0002,0001
    

I opted for a Systemd setup, so while I can declare that the above works for me, if you're using OpenRC, your mileage may vary. Regardless, once you've got a functional system, there are still a few things to do:

The Surface Pro 3 EFI bios has an annoying bug. On boot it seems to scan the USB bus and create a new EFI boot entry for any device it finds, even if one exists already with the same GPT partition UUID. The new entry overrides the correct existing entry with an incorrect one. This means that you may have to resort to moving the linux files onto the internal EFI partition, as documented in Sakaki's guide mentioned above.

The first thing you'll notice when you start up any GUI environment is that everything is really small. This is because your Surface Pro 3 has HiDPI support (aka retina display) and your GUI hasn't been configured to understand that yet.

Take a look at Arch Wiki's HiDPI page for more info on what you can do to make things readable. Currently, Firefox looks great, as do many GNOME apps. Some stuff... not so much.

If you have issues with the display waking up after taking sleep/hibernate:

emerge -av x11-drivers/xf86-video-intel

Place this in /etc/X11/xorg.conf.d/20-intel.conf

Section "Device"
        Identifier	"Intel Graphics"
        Driver          "Intel"
        Option          "AccelMethod"   "sna"
EndSection

If you followed the above steps, everything you need should be available, you just need to turn on Bluetooth:

# systemctl start bluetooth
# systemctl enable bluetooth

Check out the Gentoo Bluetooth Guide for more info.

You'll find that pairing the pen with your Surface is easy, but my experience has been that once paired, it disconnects almost immediately. Tips on what's going on here are appreciated.

It's a tablet right? It'd be nice if it could act like one. For this, Xorg already does everything you need with its xinput and xrandr utilities, you just need a script to do the work for you:

• emerge xinput You'll need this for the supplied script to work
• Copy or symlink the rotate script in this repo at usr/local/bin/rotate into your own /usr/local/bin/ directory
• Copy or symlink the rotate.desktop file in this repo at home/user/.local/share/applications/rotate.desktop to ${HOME}/.local/share/applications/rotate.desktop.

Now you can rotate the screen simply by typing rotate in a shell, or running the rotate.desktop file in GNOME or KDE.

Provided that you've followed all of the above instructions, the touchscreen should work most of the time. For some reason, it can occasionally flake out and stop working. This can be especially annoying if you've detached the keyboard and can't tell the Surface to restart.

The fix however is quite simple, and there's a script in this repo to automatically fix it for you. The best way to make use of this is to place this script in /usr/local/bin and then map a key combination like Win+VolumeUp to executing it. Then if the touchscreen ever cuts out, you can hold VolumeUp and touch the Windows logo and like magic you'll have your touchscreen back.

As of the latest kernel in this repository, most features of the Surface are supported:

• Touchscreen
• TypeCover keys
• TypeCover touchpad
• Windows button
• Power button
• Cameras
• Pen with the evdev config from the X11 directory

• External display with Docking Station mDisplayPort (use xrandr to configure)
• Docking Station ethernet
• Docking Station audio

Sensors work if read from the "raw" devices but fail if buffered reads are used.

Oh Noes! What Have I Done?!?

The thing you really have to worry about is a kernel panic while (a) not using Grub, or with a really short timeout. If you've configured EFI to boot with Linux first, it simply won't boot from USB or Windows at start time. In fact, while fiddling with efibootmgr I found that often even with USB first in the boot order, it would ignore bootable USB media and just boot the second item -- Linux in my case.

The fix for this is a "magic handshake": you need to:

1. Turn off your Surface
2. Hold down the volume-up rocker
3. While holding down the volume-down rocker push the power button once
4. Wait until you see the Surface startup logo, then let go of the volume.

This might work. If it doesn't, I suggest variations on the above. Try the volume-down button, try holding the power button longer, etc. You should also try booting into the UEFI and fiddling with the options there, including turning SecureBoot on and off. I can't remember which combination of these have worked in the past, but eventually, this button mashing results in an overwriting of the boot order with boot-to-windows as the default. Now you can start up with SystemRescueCD and fix whatever you broke.

Pull requests are welcome. In fact, they'd be downright awesome.

• There's a similar project for Arch Linux that might help with writing new patches for gentoo-sources.

I've cobbled this repo together through tutorials online and patches submitted to /r/SurfaceLinux. I haven't always been very good at attributing credit for these works, but I'll try to do better in the future.

• The initial tutorial for installing Debian on the Surface Pro 3
• The Xorg config and multitouch patch were provided by felipeota
• The button patches were found on the kernel testing branch [1] [2]
• The battery patch was on the kernel.org mailing list
• Multiple pull requests and help have been supplied by cydergoth
• A series of kernel patches for v4.6.1 were taken from matthewwardop's repo