aboutsummarylogtreecommitdiffstats
path: root/README.md
blob: 99fa7769b6807de8eedc561bcecfa3d88ab8beeb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

## `linux-xanmod-rog`

This is an Arch linux `linux-xanmod-edge` derived kernel with hardware enablement patches for ASUS ROG laptops.

Project repo: https://gitlab.com/arglebargle-arch/xanmod-rog-PKGBUILD

See the project commit log for full version history and changes.

[[_TOC_]]

### Major changes vs `linux-xanmod-edge`

  * Xanmod-rog builds for the `x86-64-v3` μarch target by default, this boosts kernel performance by ~10-15%
  * Xanmod-rog builds with the `schedutil` CPU frqeuency scaling governor active, this dramatically improves power
      efficiency on battery
  * All ROG laptop hardware enablement patches found in `linux-g14` and the lukenukem/asus-linux COPR are included
  * We carry the latest upstream bug fixes and improvements to AMD S0ix support on Zen2 and newer laptops
  * We carry a number of hand-picked enhancements from mainline linux-next and other sources to improve performance
  * We skip building some drivers (infiniband, nouveau, PCMCIA, etc) to cut update compile times by 15-25%

### Suspend problems

  - Suspend on AMD systems using modern hybrid sleep (usually S0i3) is a little dodgy, this kernel package includes
      current work collected from various kernel mailing lists and any useful patches collected from the amdgpu issue
      tracker to mitigate these issues but you may still encounter the occasional problem. If you're willing to help
      improve this feature visit the [amdgpu issue tracker][2] and participate in crash data collection and testing.

      Xanmod-rog builds with most useful s0ix kernel cmdline flags enabled at compile time, any dmesg or kernel journal
      logs captured during a failure should be useful. See the included [capture_stb.sh](capture_stb.sh) script if a
      developer asks you to supply SmartTrace Buffer (STB) logs during a suspend failure, the script will gather them
      for you automatically during every suspend. These STB logs can be found in /root/amd-stb-captures/.

  - All ASUS GA503Q laptop models have an ACPI DSDT table bug that prevents these machines from suspending correctly.
      Errors generated by this will look like the following in `dmesg` or the system journal and suspend attempts will
      fail:

      ```log
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: I/O 460 QID 3 timeout, aborting
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: I/O 461 QID 3 timeout, aborting
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: I/O 462 QID 3 timeout, aborting
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: I/O 463 QID 3 timeout, aborting
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: I/O 0 QID 0 timeout, reset controller
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: Abort status: 0x371
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: Abort status: 0x371
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: Abort status: 0x371
      Jun 19 18:56:26 arch-zephyrus kernel: nvme nvme0: Abort status: 0x371
      ```

      If you're experiencing this yourself *please* go make a vendor support ticket with ASUS and ask them to fix their
      BIOS. Visit the project page below to generate an ACPI override ramdisk that works around the issue while you wait
      for ASUS to publish a fixed BIOS:

      https://gitlab.com/smbruce/GA503QR-StorageD3Enable-DSDT-Patch

### Performance and Power Consumption

  - Upstream Xanmod builds with the `performance` CPU frequency scaling governor set as the boot-time default; this is
      great for performance but reduces battery run-time significantly when used on laptops. Since this kernel package
      is primarily targeted at ROG laptop users I've switched the build config to use `schedutil` for power efficiency
      instead.

      In my testing of the amd-pstate driver the `ondemand` governor scales as well or better than `performance` under
      load while remaining almost as power efficient as `schedutil` for general desktop use. Consider booting with the
      kernel command line parameter `cpufreq.default_governor=ondemand` to make `ondemand` your default if performance
      is more important to you than battery run-time.

  #### Quick mode-switching from the shell

  - Shell aliases are an easy way to control frequency governor and performance mode switching. You can use
      powerprofilesctl directly if you like but the aliases will alow you to switch governors as well as profiles. Here
      are some examples of mode switching commands I've uesd with my ASUS machines, these are handy to have even if you
      don't use them often:

      ###### for amd-pstate machines without governor switching:

      Using `powerprofilesctl launch` allows the power profiles daemon to automatically switch performance modes back to
      the prior state when your command is finished running. This method is especially convenient because it doesn't
      require any `sudo` calls.

      * `alias boostrun='powerprofilesctl launch -p performance'`

        Use: `boostrun <your command>`

      ###### with governor switching and asusctl >= 4.0.0

      * `alias goboost='(set -x; powerprofilesctl set performance; sudo cpupower frequency-set -g ondemand >&/dev/null;)'`
      * `alias gonormal='(set -x; powerprofilesctl set balanced; sudo cpupower frequency-set -g schedutil >&/dev/null;)'`
      * `alias gosilent='(set -x; powerprofilesctl set power-saver; sudo cpupower frequency-set -g schedutil >&/dev/null;)'`

        Use: `goboost; <your command>; gonormal`

      ###### with governor switching and asusctl <= 3.7.2: 

      * `alias goboost='(set -x; asusctl profile boost -t true -f boost; sudo cpupower frequency-set -g performance >&/dev/null;)'`
      * `alias gonormal='(set -x; asusctl profile normal -t true -f normal; sudo cpupower frequency-set -g schedutil >&/dev/null;)'`
      * `alias gosilent='(set -x; asusctl profile silent -t false -f silent; sudo cpupower frequency-set -g schedutil >&/dev/null;)'`

        Use: `goboost; <your command>; gonormal`

### Kernel Customization

  - Place a script named `myconfig` in the package directory or at `$HOME/.config/linux-xanmod-rog/myconfig` to make
      minor changes to the kernel configuration during build. See the comments near the end of the prepare() section in
      the PKGBUILD. You can find example config customizations done in [xanmod-rog-config](xanmod-rog-config).

  - We now build for the `x86-64-v3` target by default; this supports Haswell era and newer CPUs and should be ~10%
      more performant than a generic `x86_64` build while maintaining wide compatibility. This supports all recent ROG
      laptops, including Intel machines. Use this if you may want to boot your kernel on other machines in the future.

  - See the included [choose-gcc-optimization.sh](choose-gcc-optimization.sh) script for a complete list of μarch
      targets. Other useful targets include:

    * `_microarchitecture=14 makepkg ...` Zen2 optimization; AMD 4000 series CPUs, 2020 AMD ROG laptops
    * `_microarchitecture=15 makepkg ...` Zen3 optimization; most AMD 5000 series CPUs, 2021 AMD ROG laptops
    * `_microarchitecture=38 makepkg ...` Skylake optimization; Use this on [Comet Lake][1] machines
    * `_microarchitecture=92 makepkg ...` x86-64-v2; compatible with most machines from 2008 onward
    * `_microarchitecture=93 makepkg ...` x86-64-v3; package default, most machines from 2013/2014 onward are supported
    * `_microarchitecture=98 makepkg ...` Intel -march=native
    * `_microarchitecture=99 makepkg ...` AMD -march=native 

  - Building using Clang ThinLTO is well tested and stable but may not be compatible with some DKMS modules. Users of
      older versions of DKMS (pre 3.0.2) will need to patch their DKMS script to build modules for LLVM built kernels.

      You'll want to be careful to build both your kernel and any DKMS modules using the same major version of Clang and
      lld or you may encounter module build errors. If you've recently updated your LLVM tools (Clang, lld, etc) and
      DKMS modules fail to build you'll want to re-build your kernel package to update your kernel headers, modules
      should build successfully after.

      See the included [patch-dkms-for-llvm-clang-support.patch](patch-dkms-for-llvm-clang-support.patch) if your
      version of DKMS doesn't support LLVM builds.

  - Building with `-O3` compiler optimization is supported, though the performance gain over `-O2 -march=native` or 
      Clang ThinLTO is slim.

### Acknowledgements

Many thanks to Joan Figueras for his `linux-xanmod` and `linux-xanmod-edge` packages on the AUR, this kernel package
wouldn't be possible without his work.

[1]: https://wiki.gentoo.org/wiki/Safe_CFLAGS#Skylake.2C_Kaby_Lake.2C_Kaby_Lake_R.2C_Coffee_Lake.2C_Comet_Lake
[2]: https://gitlab.freedesktop.org/drm/amd/-/issues?label_name[]=s0ix
[3]: https://github.com/dell/dkms/issues/124
[//]: # ( vim: set tw=120: )