2023-01-09 22:57:32 -05:00
# NOTE: Structure changes from 2023-01-10
2023-05-01 21:57:22 -04:00
Please read the [Deprecated Behaviour README ](./OLD-BEHAVIOUR-DEPRECATION.md ) to understand how some structural changes to
2023-01-09 22:57:32 -05:00
the code might affect you!
2023-01-10 05:05:27 -05:00
# Derivations for Microsoft Surface notebooks
2021-01-23 01:36:37 -05:00
These derivatives use the patches from the [linux-surface repo ](https://github.com/linux-surface/linux-surface/tree/master/patches ).
2023-01-10 05:05:27 -05:00
## Importing
By preference, there will already be a specialised module for your model's configuration.
2023-01-10 07:54:53 -05:00
e.g. The `microsoft/surface/surface-go` module configures for the Surface Go.
2023-01-10 05:05:27 -05:00
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/` ](./common/ ) directory.
This includes the patched kernel build modules, as well as tools and service like `IPTSd` and `surface-control` .
### Kernel
2021-01-23 01:36:37 -05:00
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 ](https://github.com/linux-surface/linux-surface/wiki/Supported-Devices-and-Features#feature-matrix )
provides details on which devices are supported on which types of machine.
2023-01-10 05:05:27 -05:00
The kernel-specific derivations are under the [`common/kernel/` ](./common/kernel/ ) sub-directory.
2021-01-23 01:36:37 -05:00
In order to simplify maintenance of the Nix code, only the most-recent kernel patch-set is expected
to be maintained in this repo.
2021-03-05 21:29:13 -05:00
_*NOTE:*_ Some built-in Kernel config items need to be set, that aren't set by default:
2021-01-23 01:36:37 -05:00
- https://github.com/linux-surface/surface-aggregator-module/wiki/Testing-and-Installing
2023-01-10 05:05:27 -05:00
### Support Tools
2021-01-23 01:36:37 -05:00
### IPTS
2023-01-10 05:05:27 -05:00
Enable this with the `microsoft-surface.ipts.enable = true;` config option.
2021-01-23 01:36:37 -05:00
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`
2021-02-02 19:13:14 -05:00
#### surface-control
2023-01-10 05:05:27 -05:00
Enable this with the `config.microsoft-surface.surface-control.enable = true;` config option.
2021-02-02 19:13:14 -05:00
For controlling the performance modes and other aspects of the device, the [`surface-control` ](https://github.com/linux-surface/surface-control ) tool is included.
To be able to control the performance mode without using `sudo` , add your user to the `surface-control` group.
2021-01-23 01:36:37 -05:00
2023-01-10 05:05:27 -05:00
## 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/` ](./surface-go/firmware/ath-10k/ )
module will replace the default firmware with the updated firmware.
2021-01-23 01:36:37 -05:00
# ToDo's Not Done
See: [TODO.org ](./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.
2021-02-22 23:48:50 -05:00
You will see messages like "Can't ping firmware".
2021-01-23 01:36:37 -05:00
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.
2023-01-10 05:05:27 -05:00
The derivative in `surface-go/firmware/ath10k/` can configure this, with the
`config.hardware.microsoft-surface.firmware.surface-go-ath10k.replace = true` config option.
2021-02-23 00:06:06 -05:00
2021-03-05 21:29:13 -05:00
_*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.
2021-02-23 00:06:06 -05:00
This is the only way (currently) to force the driver to use the new firmware.
2021-02-08 23:17:27 -05:00
For more details, see: https://github.com/linux-surface/linux-surface/wiki/Surface-Go#wifi-firmware
2021-03-05 21:29:13 -05:00
_*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:
- https://github.com/linux-surface/kernel/commit/22ef83836c4aa89e9eb98de9b47ed24b6c2a1d45
_*NOTE:*_ There was an attempt to get this firmware incorporated into the aggregate `board-2.bin` ,
2021-02-22 23:48:50 -05:00
but (as of this writing) the request appears to have been ignored:
- https://github.com/linux-surface/linux-surface/issues/41
2021-01-23 01:36:37 -05:00
References:
- https://github.com/jakeday/linux-surface/issues/441
- https://www.reddit.com/r/SurfaceLinux/comments/e8quqg/surface_go_official_wifi_fix/
- https://hackmd.io/@dasgeek/ryA5i5Dor
- https://github.com/thebitstick/surfacego-wifi
- https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/ath10k
- https://wireless.wiki.kernel.org/en/users/drivers/ath10k/firmware
