History

mexisme 8e6d03d349 Update OLD-BEHAVIOUR-DEPRECATION.md		2023-01-11 02:32:24 +13:00
..
common	Merge remote-tracking branch 'upstream/master' into microsoft/surface/specialisation/common-files	2023-01-10 22:29:13 +13:00
surface-go	Update Surface Go to depend on other PC modules	2023-01-11 02:24:06 +13:00
surface-pro-intel	fixup! Update Surface Pro 3 to reference microsoft/surface/surface-pro-intel	2023-01-11 02:25:48 +13:00
default.nix	Use the module assertions option, instead	2023-01-11 01:39:03 +13:00
OLD-BEHAVIOUR-DEPRECATION.md	Update OLD-BEHAVIOUR-DEPRECATION.md	2023-01-11 02:32:24 +13:00
README.md	Update README.md to reference surface-go module	2023-01-11 01:54:53 +13:00
TODO.org	Merge branch 'up/master' into microsoft/surface/firmware-surface-go	2021-03-06 22:18:02 +13:00

README.md

NOTE: Structure changes from 2023-01-10

Please read the Deprecated Behaviour README to understand how some structural changes to the code might affect you!

Derivations for Microsoft Surface notebooks

These derivatives use the patches from the linux-surface repo.

Importing

By preference, there will already be a specialised module for your model's configuration. e.g. The microsoft/surface/surface-go module configures for the Surface Go.

If not, the microsoft/surface/common/ module can also be imported directly, and the options provided can be used in your own system's configuration.

Alternatively, you can create a new specialisation for your model under microsoft/surface configured for that model.

Common Modules

Most shared / common modules are under the common/ directory. This includes the patched kernel build modules, as well as tools and service like IPTSd and surface-control.

Kernel

The kernel needs several patches to make it work correctly with some of the hardware on various Surface models, e.g. keyboard/trackpad, camera, wifi.

Not all hardware is fully supported, but the linux-surface feature matrix provides details on which devices are supported on which types of machine.

The kernel-specific derivations are under the common/kernel/ sub-directory. In order to simplify maintenance of the Nix code, only the most-recent kernel patch-set is expected to be maintained in this repo.

NOTE: Some built-in Kernel config items need to be set, that aren't set by default:

https://github.com/linux-surface/surface-aggregator-module/wiki/Testing-and-Installing

Support Tools

IPTS

Enable this with the microsoft-surface.ipts.enable = true; config option.

IPTS is used on most of the Surface range, except for Surface Go and Surface Laptop 3 (AMD version).

Older kernels used specialised firmware which used a method that's no longer supported by the more-recent kernels.

Newer kernels use the kernel-space intel-precise-touch driver and user-space ipstd daemon.

The iptsd daemon works with the intel-precise-touch driver to convert raw touch data from the kernel-space driver into events for the HID / input sub-system.

https://github.com/linux-surface/iptsd
https://github.com/linux-surface/intel-precise-touch
- NOTE: The patches from this repo are included in the above kernel patches, already.

DTX, `surface-control`

surface-control

Enable this with the config.microsoft-surface.surface-control.enable = true; config option.

For controlling the performance modes and other aspects of the device, the surface-control tool is included.

To be able to control the performance mode without using sudo, add your user to the surface-control group.

Firmware and Drivers

WiFi on Surface Go

For the Surface Go, please see the "Issues" sections below.

Including the microsoft/surface/surface-go/firmware/ath-10k/ module will replace the default firmware with the updated firmware.

ToDo's Not Done

See: TODO.org

Issues

TLP daemon

TLP is known to cause problems on Surface unless correctly configured. See: https://github.com/linux-surface/linux-surface/blob/master/README.md

Wifi Firmware for Surface Go

On the Surface Go, the standard firmware from the official Linux Firmware repo has issues with the ath10k QCA6174 Wifi device. You will see messages like "Can't ping firmware".

The most effective fix to-date is to remove the board-2.bin file or replace it with a copy of the board.bin file.

The derivative in surface-go/firmware/ath10k/ can configure this, with the config.hardware.microsoft-surface.firmware.surface-go-ath10k.replace = true config option.

NOTE: This is destructive, as it deletes all the board.bin and board-2.bin files for the ath10k QCA6174 device, and replaces them with KillerNetworking's version. This is the only way (currently) to force the driver to use the new firmware.

For more details, see: https://github.com/linux-surface/linux-surface/wiki/Surface-Go#wifi-firmware

NOTE: There's some work to patch the kernel to make it easier to override which firmware file to use for QCA6174, which would obviate this more-destructuve approach:

22ef83836c

NOTE: There was an attempt to get this firmware incorporated into the aggregate board-2.bin, but (as of this writing) the request appears to have been ignored:

https://github.com/linux-surface/linux-surface/issues/41

References: