beenull/linux-surface
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Update README

Browse source
This commit is contained in:
Maximilian Luz 2019-12-09 21:57:41 +01:00
parent d2445656d9
commit 51ba311b8e
No known key found for this signature in database
GPG key ID: 70EC0937F6C26F02
1 changed files with 69 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
README.md
View file

@ -1,6 +1,7 @@
# Linux Surface
Linux running on the Microsoft Surface devices . Follow the instructions below to install the latest kernel and config files.
Linux running on the Microsoft Surface devices.
Follow the instructions below to install the latest kernel and config files.
### Supported Devices
@ -9,10 +10,12 @@ Linux running on the Microsoft Surface devices . Follow the instructions below t
* Surface Go
* Surface Laptop
* Surface Laptop 2
* Surface Laptop 3
* Surface Pro 3
* Surface Pro 4
* Surface Pro 2017
* Surface Pro 6
* Surface Pro 7
* Surface Studio
### What's Working
@ -28,8 +31,8 @@ Linux running on the Microsoft Surface devices . Follow the instructions below t
* Power Button
* Volume Buttons
* SD Card Reader
* Cameras (partial support, disabled for now)
* Hibernate
* S2Idle (suspend)
* Sensors (accelerometer, gyroscope, ambient light sensor)
* Battery Readings
* Docking/Undocking Tablet and Keyboard
@ -40,104 +43,94 @@ Linux running on the Microsoft Surface devices . Follow the instructions below t
### What's NOT Working
* Dedicated Nvidia GPU (if you have a performance base on a Surface Book 1, otherwise onboard works fine)
* Cameras (not fully supported yet)
* Dedicated Nvidia GPU (Surface Book 1 with Performance Base)
* Connected Standby is not supported yet
### Disclaimer
* For the most part, things are tested on a Surface Book. While most things are reportedly fully working on other devices, your mileage may vary. Please look at the issues list for possible exceptions.
### Download Pre-built Kernel and Headers
* For the most part, things are tested on a Surface Book 2.
While most things are reportedly fully working on other devices, your mileage may vary.
Please look at the issues list for possible exceptions.
The setup.sh script in the below Instructions will handle downloading these for you. Otherwise, you may still download them directly (not recommended as you will want to run the setup.sh script).
## Installation and Setup
Downloads for ubuntu based distros (other distros will need to compile from source using the included patches):
For a more detailed installation and setup guide, please refer to the corresponding [Wiki page][wiki-setup].
There, you may also find device-specific caveats.
A short overview of the process is provided below.
https://github.com/jakeday/linux-surface/releases
This repository is aimed at Debian based distributions (Ubuntu, Pop!_OS, elementary OS, ...).
Releases are provided for both, Debian and Arch Linux based distributions, but if you're running Arch, you may want to consider looking at [this][arch-linux-surface] project instead, or [here][fedora-linux-surface] if you're running Fedora.
These releases can be found here: https://github.com/qzed/linux-surface/releases.
You will need to download the image, headers and libc-dev deb files for the version you want to install.
You may also want to consider setting up one of the [package repositories][wiki-repos] to obtain automatic updates.
After the installation, you should have a look at the [post-installation notes][wiki-setup-post], specifically you may want to set up [secure-boot][wiki-secure-boot] and install the proprietary firmware package (usually named `linux-firmware`) if you have not done so already.
### Instructions
The following setup instructions re for Debian based systems (Debian, Ubuntu, Pop!_OS, elementary OS, ...).
If you're running something else, you may need to adapt them for your distribution (have a look at the setup.sh script for more information).
0. (Prep) Install Dependencies:
```
1. Before you can actually start, you will need to install some required packages.
On Debian based distributions, you can do this by simply running
```
sudo apt install git curl wget sed
```
1. Clone the linux-surface repo:
```
git clone --depth 1 https://github.com/jakeday/linux-surface.git ~/linux-surface
```
2. Change directory to linux-surface repo:
```
cd ~/linux-surface
```
3. Run setup script:
```
sudo sh setup.sh
```
4. Reboot on installed kernel.
```
The setup script will handle installing the latest kernel for you. You can also choose to download any version you want and install yourself:
Install the headers, kernel and libc-dev (make sure you cd to your download location first):
```
sudo dpkg -i linux-headers-[VERSION].deb linux-image-[VERSION].deb linux-libc-dev-[VERSION].deb
```
2. Clone this repository.
To save some time, you can use the `--depth 1` flag.
```
git clone --depth 1 https://github.com/qzed/linux-surface.git
```
If you want to update this git repository later on, e.g. for re-running the `setup.sh` script, you can simply run `git pull` inside the repository.
### Compiling the Kernel from Source
3. Next, change into the `linux-surface` directory (`cd linux-surface`) and run the setup script via
```
sudo ./setup.sh
```
Follow the instructions and make your choices.
If you have/intend to set up the kernel and libwacom package via one of the package repositories, say `no` to installing them.
Alternatively, you can also install them manually via (for Debian)
```
sudo dpkg -i linux-headers-[VERSION].deb linux-image-[VERSION].deb linux-libc-dev-[VERSION].deb
```
after downloading these files from the [releases][releases] section of this repo.
#### For Debian-Based Systems
4. Finally, you will need to re-boot your system and boot into the linux-surface kernel.
Please make sure that you actually boot in the right kernel via `uname -a` before opening any issues.
This should give you a version string containing `surface`.
If not, you may need to configure your bootloader.
For this, please refer to the instructions provided by your bootloader and/or distribution.
If you don't want to use the pre-built kernel and headers, you can compile the kernel yourself following these steps:
0. (Prep) Install the required packages for compiling the kernel:
```
sudo apt install build-essential binutils-dev libncurses5-dev libssl-dev ccache bison flex libelf-dev
```
1. Clone the mainline stable kernel repo:
```
git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git ~/linux-stable
```
2. Go into the linux-stable directory:
```
cd ~/linux-stable
```
3. Checkout the version of the kernel you wish to target (replacing with your target version):
```
git checkout v5.y.z
```
4. Apply the kernel patches from the linux-surface repo (this one, and assuming you cloned it to ~/linux-surface):
```
for i in ~/linux-surface/patches/[VERSION]/*.patch; do patch -p1 < $i; done
```
5. Use config for kernel series (may need to manually change for your distro):
```
cp ~/linux-surface/configs/[VERSION]/config .config
```
6. Compile the kernel and headers (for ubuntu, refer to the build guide for your distro):
```
make -j `getconf _NPROCESSORS_ONLN` deb-pkg LOCALVERSION=-linux-surface
```
7. Install the headers, kernel and libc-dev:
```
sudo dpkg -i linux-headers-[VERSION].deb linux-image-[VERSION].deb linux-libc-dev-[VERSION].deb
```
If you want to compile the kernel yourself (e.g. if your distribution is not supported), please have a look at the [wiki][wiki-compiling].
#### For Arch-Based Systems
Have a look at [this](https://github.com/dmhacker/arch-linux-surface) repository.
## Additional Information
### Signing the kernel for Secure Boot
Please consult the [SIGNING.md](SIGNING.md).
### NOTES
### Notes
* If you are getting stuck at boot when loading the ramdisk, you need to install the Processor Microcode Firmware for Intel CPUs (usually found under Additional Drivers in Software and Updates).
* Do not install TLP! It can cause slowdowns, laggy performance, and occasional hangs! You have been warned.
* If you chose to use hibernate over suspend, please follow the instructions [here](https://fitzcarraldoblog.wordpress.com/2018/07/14/configuring-lubuntu-18-04-to-enable-hibernation-using-a-swap-file/).
* If you chose to use hibernate over suspend, please follow the instructions [here][hibernate-setup].
### Support
If you have an issue with the kernel, please feel free to create on issue here to track it. If you have questions or need support, please use our [Gitter Community](https://gitter.im/linux-surface)!
If you have an issue, please have a look at [jakeday/linux-surface][jakeday-issues] and create a new issue if it is not already being discussed.
If you have an issue that is directly related to the kernel patches (and not configuration- or setup-related), you can also open an issue at [qzed/linux-surface-kernel][linux-surface-kernel].
If you have questions or need support, please use our [Gitter Community][gitter]!
For development related questions and discussions, please consider joining our IRC channel on freenode (`freenode/##linux-surface`).
[wiki-setup]: https://github.com/qzed/linux-surface/wiki/Installation-and-Setup
[wiki-setup-post]: https://github.com/qzed/linux-surface/wiki/Installation-and-Setup#post-installation
[wiki-repos]: https://github.com/qzed/linux-surface/wiki/Package-Repositories
[wiki-secure-boot]: https://github.com/qzed/linux-surface/wiki/Secure-Boot
[wiki-compiling]: https://github.com/qzed/linux-surface/wiki/Installation-and-Setup#compiling-the-kernel-from-source
[arch-linux-surface]: https://github.com/dmhacker/arch-linux-surface
[fedora-linux-surface]: https://github.com/StollD/fedora-linux-surface/
[gitter]: https://gitter.im/linux-surface
[hibernate-setup]: https://github.com/qzed/linux-surface/wiki/Secure-Boot
[jakeday-issues]: https://github.com/jakeday/linux-surface/issues
[linux-surface-kernel]: https://github.com/qzed/linux-surface-kernel/