From 9d4505d4e11afd3c7037b74d87ace16fb047de06 Mon Sep 17 00:00:00 2001 From: mexisme Date: Tue, 10 Jan 2023 23:05:27 +1300 Subject: [PATCH] Update README --- README.md | 2 +- flake.nix | 1 + .../surface/OLD-BEHAVIOUR-DEPRECATION.md | 10 ++++ microsoft/surface/README.md | 46 ++++++++++++++----- 4 files changed, 47 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 7fc7517..3306655 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,7 @@ See code for all available configurations. | [MSI GS60 2QE](msi/gs60) | `` | | [MSI GL62/CX62](msi/gl62) | `` | | [Microsoft Surface Pro 3](microsoft/surface-pro/3) | `` | -| [Microsoft Surface Range (Deprecated)](microsoft/surface) | `` | +| [Microsoft Surface Range (Common Modules)](microsoft/surface/common)| `` | | [Omen en00015p](omen/en00015p) | `` | | [One-Netbook OneNetbook 4](onenetbook/4) | `` | | [Panasonic Let's Note CF-LX4 ](panasonic/letsnote/cf-lx4) | `` | diff --git a/flake.nix b/flake.nix index 67aeeb4..87acc3e 100644 --- a/flake.nix +++ b/flake.nix @@ -131,6 +131,7 @@ lenovo-yoga-6-13ALC6 = import ./lenovo/yoga/6/13ALC6; letsnote-cf-lx4 = import ./panasonic/letsnote/cf-lx4; microsoft-surface = import ./microsoft/surface; + microsoft-surface-common = import ./microsoft/surface/common; microsoft-surface-pro-3 = import ./microsoft/surface-pro/3; msi-gs60 = import ./msi/gs60; msi-gl62 = import ./msi/gl62; diff --git a/microsoft/surface/OLD-BEHAVIOUR-DEPRECATION.md b/microsoft/surface/OLD-BEHAVIOUR-DEPRECATION.md index 1519a83..e93a81d 100644 --- a/microsoft/surface/OLD-BEHAVIOUR-DEPRECATION.md +++ b/microsoft/surface/OLD-BEHAVIOUR-DEPRECATION.md @@ -11,6 +11,16 @@ models, and they would fail gracefully enough that we could mostly ignore warnin Now, however --- as-of 2023-01-10 --- we have a much wider variety of chipsets, incl. models with some of the newer AMD CPUs, and this is breaking small things in annoying ways for more people. +## How to update + +By preference, there will already be a specialised module for your model's configuration. + +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. + ## Changes ### Model Specialisations diff --git a/microsoft/surface/README.md b/microsoft/surface/README.md index 6238eb6..6b16cdf 100644 --- a/microsoft/surface/README.md +++ b/microsoft/surface/README.md @@ -1,13 +1,28 @@ # NOTE: Structure changes from 2023-01-10 -Please read the [Deprecated Behaviour README](./deprecated/README.md) to understand how some structural changes to +Please read the [Deprecated Behaviour README](./OLD-BEHAVIOUR-DEPRECATED.md) to understand how some structural changes to the code might affect you! -# Derivatives for Microsoft Surface notebooks +# 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). -## Kernel +## Importing + +By preference, there will already be a specialised module for your model's configuration. + +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. @@ -16,21 +31,19 @@ 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 `kernel/` sub-directory. +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 -## Firmware, Drivers and Support Tools - -### WiFi - -For the Surface Go, please see the "Issues" sections below. +### 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 @@ -49,10 +62,21 @@ kernel-space driver into events for the HID / input sub-system. #### 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) @@ -73,8 +97,8 @@ 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 `firmware/surface-go/ath10k/` can configure this, if you set the option -`config.hardware.microsoft-surface.firmware.surface-go-ath10k.replace` to `true`. +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.