# NOTE: Structure changes from 2023-01-10

Please read the [Deprecated Behaviour README](./OLD-BEHAVIOUR-DEPRECATION.md) 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](https://github.com/linux-surface/linux-surface/tree/master/patches).

## 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/`](./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](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.

The kernel-specific derivations are under the [`common/kernel/`](./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`](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.

## 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.

# 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.
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:
- https://github.com/linux-surface/kernel/commit/22ef83836c4aa89e9eb98de9b47ed24b6c2a1d45

_*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:
- 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