# How to set up Linux dual-boot on a MacBook Pro

* 1. [Partitioning and bootloader setup](#Partitioningandbootloadersetup)
* 2. [Installation](#Installation)
* 3. [After installation](#Afterinstallation)
	* 3.1. [Fixing the bootloader](#Fixingthebootloader)
	* 3.2. [Fixing Wi-Fi and wireless drivers:](#FixingWiFi)
	* 3.3. [Fixing the mouse touchpad and the Touch Bar](#FixingthemousetouchpadandtheTouchBar)
	* 3.4. [Fixing Suspend/Hybernation](#FixingSuspend)
* 4. [Additional resources:](#Additionalresources)

##  1. <a name='Partitioningandbootloadersetup'></a>Partitioning and bootloader setup

* Partition your drive using the Disk Utility (hold <kbd>Command</kbd> + <kbd>R</kbd> during startup and select "Disk Utility")
* Create a new partition (NOT Volume, important!) with at least 50GB of space and preferrably the Ext4 filesystem so it's recognized by the Linux installer
* On OS X El Capitan and later disable SIP (System Integrity Protection):
  - Restart your Mac and hold <kbd>Command</kbd> + <kbd>R</kbd> again to get into Recovery mode.
  - Open the Terminal and enter the following:
    ```sh
    $ csrutil disable
    ```
  - Restart your Mac
  - Once you have the Mac desktop back, [download rEFInd from SourceForge](https://sourceforge.net/projects/refind/) at rEFInd beta, an EFI boot manager utility. Open the downloaded refind-bin-0.12.0 (or later) folder  and install rEFInd with the `./refind-install` file
  - Optional but recommended: Go back to Recovery mode and re-enable SIP by entering the following in Terminal:
    ```sh
    $ csrutil enable
    ```
More details here: https://www.lifewire.com/dual-boot-linux-and-mac-os-4125733

##  2. <a name='Installation'></a>Installation

* Plug in the live USB installation media with your Linux distribution
* Now when you boot your Mac, you should get the rEFInd bootloader screen. 
* Select the **Boot EFI\boot\...** entry (rEFInd) to boot from your Linux USB
* Proceed with installation. When asked for `Installation type`, choose `Something else` and manually configure the partitioning scheme on the partition you reserved previously.
* I recommend the following swap and root partitions: https://www.maketecheasier.com/install-dual-boot-ubuntu-mac/

***

##  3. <a name='Afterinstallation'></a>After installation

###  3.1. <a name='Fixingthebootloader'></a>Fixing the bootloader

After installation, Ubuntu (GRUB) will likely take over as the main bootloader and boot automatically into Linux, without giving you the option to boot into MacOS.
To change the bootloader priority back to rEFInd for dual booting, use `efibootmgr`.

You will get output similar to this:

```sh
$ sudo efibootmgr 
BootCurrent: 0080
BootOrder: 0000, 0080, 0081
Boot0000* ubuntu
Boot0080* Mac OS X
Boot0081* Mac OS X
Boot0082* 
BootFFFF*
```

If you're not seeing rEFInd already, you can determine the boot partition it's on with `sudo efibootmgr -v` and then change the boot order accordingly. In my case with:
```sh
$ sudo efibootmgr -o 0080,0000,0081
```
to set the boot priority in order of: rEFInd, Ubuntu, MacOS

For more details see: https://www.rodsbooks.com/refind/bootcoup.html#efibootmgr

###  3.2. <a name='FixingWiFi'></a>Fixing Wi-Fi and wireless drivers:

With Apple using Broadcom hardware for networking, there is a good chance your wireless won't work on Linux out of the box.
This is most easily resolved if you have internet access either via ethernet cable or USB/Bluetooth tethering from your phone.
This issue is a little more complex since it can depend on the exact version and revision of your Broadcom network card. These are the steps that worked for me:


```sh
$ sudo apt-get purge bcmwl-kernel-source
$ sudo apt update
$ sudo update-pciids
$ sudo apt install firmware-b43-installer
$ sudo reboot
$ sudo iwconfig wlp2s0 txpower 10dBm
```

To dig into more details to find out which Broadcom card you have and which drivers you might need, see:
* https://askubuntu.com/questions/55868/installing-broadcom-wireless-drivers and
* https://bugzilla.kernel.org/show_bug.cgi?id=193121


###  3.3. <a name='FixingthemousetouchpadandtheTouchBar'></a>Fixing the mouse touchpad and the Touch Bar

For the newer MacBook Pros with the upper Touch Bar, this most likely won't work out of the box, and possibly neither will your mouse touchpad. The instructions below are specific to Debian/Ubuntu distros. For others, see this guide: https://gist.github.com/roadrunner2/1289542a748d9a104e7baec6a92f9cd7#keyboardtouchpadtouchbar

To get everything working, do this:
```sh
$ sudo apt install linux-headers-generic dkms
# Prepare for the modules to be included in the ramdisk (so they are loaded early during boot):
$ cat <<EOF | sudo tee -a /etc/initramfs-tools/modules
# drivers for keyboard+touchpad
applespi
apple-ib-tb
intel_lpss_pci
spi_pxa2xx_platform
EOF
# get and build the drivers
$ git clone https://github.com/roadrunner2/macbook12-spi-driver.git
$ cd macbook12-spi-driver
$ git checkout touchbar-driver-hid-driver
$ sudo ln -s `pwd` /usr/src/applespi-0.1
$ sudo dkms install applespi/0.1
```

Next we need to set the proper dpi for the touchpad and adjust the sensitivity (download the [61-evdev-local.hwdb](#file-61-evdev-local-hwdb), [61-libinput-local.hwdb](#file-61-libinput-local-hwdb), and [local-overrides.quirks](#file-local-overrides-quirks) from this gist - the `61-evdev-local.hwdb` is only needed for udev < 242, the `61-libinput-local.hwdb` is needed for libinput versions < 1.12, the `local-overrides.quirks` for libinput versions >= 1.12):

```sh
# if 'udevadm --version' less than 242:
$ sudo cp <the-downloaded-61-evdev-local.hwdb> /etc/udev/hwdb.d/61-evdev-local.hwdb
# if 'libinput --version' less than 1.12:
$ sudo cp <the-downloaded-61-libinput-local.hwdb> /etc/udev/hwdb.d/61-libinput-local.hwdb
# if 'libinput --version' 1.12 or later:
$ sudo mkdir /etc/libinput # if it doesn't exist
$ curl https://gist.githubusercontent.com/roadrunner2/1289542a748d9a104e7baec6a92f9cd7/raw/3d46a8ae6576fffa816edd53e78fa9cba27198e3/local-overrides.quirks > local-overrides.quirks
$ sudo mv local-overrides.quirks /etc/libinput/
$ sudo systemd-hwdb update
```

You can test the drivers by loading them and their dependencies:
```
sudo modprobe intel_lpss_pci spi_pxa2xx_platform applespi apple-ib-tb
```

Finally, reboot to make sure it all works correctly:
```
sudo reboot
```

###  3.4. <a name='FixingSuspend'></a>Fixing Suspend/Hybernation

To get the Suspend functionality to work at least somewhat we need to disable the `d3cold` PCIe power state for the NVMe controller to successfully wake up again by setting `sys/bus/pci/devices/0000\:01\:00.0/d3cold_allowed` to `0` using `echo 0 > /sys/bus/pci/devices/0000\:01\:00.0/d3cold_allowed`: https://github.com/Dunedan/mbp-2016-linux#suspend--hibernation

Unfortunately, this variable gets reset on every startup, so I added the command to root's (must be root!) crontab with `@reboot`:
```sh
$ sudo crontab -e
@reboot bash -c "echo 0 > /sys/bus/pci/devices/0000\:01\:00.0/d3cold_allowed"
```




***

##  4. <a name='Additionalresources'></a>Additional resources:
* State of Linux on the MacBook Pro: https://github.com/Dunedan/mbp-2016-linux#suspend--hibernation
* Drivers: https://gist.github.com/roadrunner2/1289542a748d9a104e7baec6a92f9cd7