readme: refresh #1190
+83
−36
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,87 @@ | ||
| # Linux-tkg | ||
|
|
||
| This repository provides scripts to automatically download, patch and compile any version ≥ 5.4 of the Linux Kernel. | ||
|
|
||
| `linux-tkg` also ships with a selection of patches that can improve the desktop/gaming experience: most can be toggled by editing the [customization.cfg](./customization.cfg) file, or by simply following the interactive install script. | ||
|
|
||
| - [Linux-tkg](#linux-tkg) | ||
| - [Important information](#important-information) | ||
| - [Customization options](#customization-options) | ||
| - [Default tweaks](#default-tweaks) | ||
| - [CPU task schedulers](#cpu-task-schedulers) | ||
| - [Runtime scheduler change: sched-ext](#runtime-scheduler-change-sched-ext) | ||
| - [Build-time default scheduler](#build-time-default-scheduler) | ||
| - [Optional tweaks](#optional-tweaks) | ||
| - [Bring your own patches](#bring-your-own-patches) | ||
| - [Install procedure](#install-procedure) | ||
| - [Arch \& derivatives](#arch--derivatives) | ||
| - [DEB and RPM based distributions](#deb-and-rpm-based-distributions) | ||
| - [Generic install](#generic-install) | ||
| - [Gentoo](#gentoo) | ||
|
|
||
| ## Important information | ||
|
|
||
| - **Non-pacman distros support can be considered experimental. You're invited to report issues you might encounter with it.** | ||
| - **If your distro isn't using systemd, please set _configfile="running-kernel" in customization.cfg or you might end up with a non-bootable kernel** | ||
| - Building recent linux kernels with GCC will require ~20-25GB of disk space. Using llvm/clang, LTO, ccache and/or enabling more drivers in the defconfig will push that requirement higher, so make sure you have enough free space on the volume you're using to build. | ||
| - Nvidia drivers might need to be patched to cleanly build/work on latest kernels. | ||
| - For Arch users: [Frogging-Family nvidia-all](https://github.com/Frogging-Family/nvidia-all) is there for that :frog: | ||
|
|
||
|
Collaborator
Author
There was a problem hiding this comment. I removed this bullet point entirely too 🤔
Member
There was a problem hiding this comment. The 20-25GB disk space requirement was added because people kept opening issues about compilation failures "while they had more than enough disk space", and in the end they had like 10GB free or something before building. Same story when building in ramfs with 16GB machines. The Nvidia stuff will break, so not sure why you'd remove that entirely. It could be updated though, with their "open" module and maybe a warning regarding recent releases and RC kernels. The <5.9 thing can indeed go now that 5.4 LTS is gone.
Collaborator
Author
There was a problem hiding this comment. ah no, I was only talking about the very last bullet point: the rest didn't get removed, it's just that github didn't see the text as "moved" further down or something |
||
| ## Customization options | ||
|
|
||
| Most customizations can be toggled by: | ||
|
|
||
| - Editing the variables in [customization.cfg](./customization.cfg), those values can be overridden by (in increasing priority) | ||
| - An external config file, as defined the `_EXT_CONFIG_PATH` variable (defaults to `~/.config/frogminer/linux-tkg.cfg`) | ||
| - Setting the variables in the shell environment. | ||
| - Following the interactive install script (it does _not_ prompt for all of them). | ||
|
|
||
| ### Default tweaks | ||
|
|
||
| These tweaks cannot be disabled with a toggle and come default-enabled. | ||
|
|
||
| - Memory management and swapping tweaks | ||
| - Scheduling tweaks | ||
| - `CFS/EEVDF` tweaks | ||
| - Using the ["Cake"](https://www.bufferbloat.net/projects/codel/wiki/CakeTechnical/) network queue management system | ||
| - Using `vm.max_map_count=16777216` by default | ||
| - Cherry-picked patches from [Clear Linux's patchset](https://github.com/clearlinux-pkgs/linux) | ||
| - Default `intel_pstate=passive` kernel option for Intel CPUs | ||
| - Default frequency scaling aggressiveness with kernel ≥ 5.5 is conservative, which results in stutters and poor performance in low/medium load scenarios (for better power saving). | ||
| - `intel_pstate=passive` make's use of the `acpi_cpufreq` governor passthrough, keeping full support for turbo frequencies. | ||
| - It's combined with our aggressive `ondemand` governor by default for good performance while still preserving power. | ||
|
Comment on lines
+49
to
+52
Collaborator
Author
There was a problem hiding this comment. @Tk-Glitch how about we put here, in the "Default tweaks" section ? It doesn't feel that important for me to be in the "important information" top-of-readme position 🤔 |
||
|
|
||
| ### CPU task schedulers | ||
|
|
||
| Since a computer runs more "tasks" than there are cores, a CPU task scheduler is the algorithm that decides which one runs when, for how long, on which core. Those decisions can have an impact on throughput (how many things get done globally per unit of time), and latency (how long tasks have to wait before running again). Gaming is generally more sensitive to latency and some schedulers can be more more adapted for that. | ||
|
|
||
| #### Runtime scheduler change: sched-ext | ||
|
|
||
| Starting kernel ≥ 6.12, it's possible to switch CPU schedulers at runtime while keeping the kernel's built-in default scheduler one as fallback/backup, using [sched-ext](https://github.com/sched-ext/scx). | ||
|
|
||
| `sched-ext` offers various schedulers, `LAVD` is geared towards gaming workloads and used by Steam's Deck handheld console. | ||
|
|
||
| Arch users get scx schedulers from the `scx-scheds` package or on the [AUR](https://aur.archlinux.org/packages/scx-scheds-git) thanks to @sirlucjan. | ||
|
|
||
| For persistence of the chosen runtime scheduler upon reboots: | ||
|
|
||
| - set scheduler in `/etc/default/scx` | ||
| - enable the `scx` service `systemctl enable scx`. | ||
|
|
||
| #### Build-time default scheduler | ||
|
|
||
| [EEVDF](https://lwn.net/Articles/925371/) is the only CPU scheduler available in the "vanilla" kernel sources ≥ 6.6. Whereas [CFS](https://en.wikipedia.org/wiki/Completely_Fair_Scheduler) for earlier kernel versions. | ||
|
|
||
| Alternative default schedulers are optionally available in linux-tkg at build time: | ||
|
|
||
| - BORE (Burst-Oriented Response Enhancer) by Masahito Suzuki - CFS/EEVDF based : [code repository](https://github.com/firelzrd/bore-scheduler) | ||
| - Project C / PDS & BMQ by Alfred Chen: [blog](http://cchalpha.blogspot.com/ ), [code repository](https://gitlab.com/alfredchen/projectc) | ||
| - MuQSS by Con Kolivas : [blog](http://ck-hack.blogspot.com/), [code repository](https://github.com/ckolivas/linux) | ||
| - Undead PDS : TkG's port of the pre-Project C "PDS-mq" scheduler by Alfred Chen. While PDS-mq got dropped with kernel 5.1 in favor of its BMQ evolution/rework, it wasn't on par with PDS-mq in gaming. "U" PDS still performed better in some cases than other schedulers, so it's been kept undead for a while. | ||
|
|
||
| These alternative schedulers may offer a better performance/latency ratio in some scenarios. The availability of each scheduler depends on the chosen Kernel version: the script will display what's available on a per-version basis. | ||
|
|
||
| ### Optional tweaks | ||
|
|
||
| The `customization.cfg` file offers many toggles for extra tweaks: | ||
|
|
||
|
|
@@ -58,16 +98,23 @@ The `customization.cfg` file offers many toggles for extra tweaks: | |
| - Provide own kernel `.config` file | ||
| - ... | ||
|
|
||
| ### Bring your own patches | ||
|
|
||
| To apply your own patches with `linux-tkg`: | ||
|
|
||
| - Create a `linuxXY-tkg-userpatches` folder at the root of the clone | ||
| - where `X` and `Y` specify the kernel version the patches applies to. | ||
| - Examples: `linux65-tkg-userpatches`, `linux618-tkg-userpatches` | ||
| - Set `_user_patches=true` in your customization file. | ||
| - Drop your patches within that folder the `.mypatch` extension. | ||
|
|
||
| The install script will then find them, and ask if you want to apply each patch. | ||
|
|
||
| ## Install procedure | ||
|
|
||
| For all the supported linux distributions, `linux-tkg` has to be cloned with `git`. Since it keeps a clone of the kernel's sources within (`linux-src-git`, created during the first build after a fresh clone), it is recommended to keep the cloned `linux-tkg` folder and simply update it with `git pull`, the install script does the necessary cleanup at every run. | ||
|
|
||
| ### Arch & derivatives | ||
|
|
||
| ```shell | ||
| git clone https://github.com/Frogging-Family/linux-tkg.git | ||
|
|
@@ -80,13 +127,13 @@ The script will use a slightly modified Arch config from the `linux-tkg-config` | |
|
|
||
| **Note:** the `base-devel` package group is expected to be installed, see [here](https://wiki.archlinux.org/title/Makepkg) for more information. | ||
|
|
||
| ### DEB and RPM based distributions | ||
|
|
||
| The interactive `install.sh` script will create, depending on the selected distro, `.deb` or `.rpm` packages, move them in the the subfolder `DEBS` or `RPMS` then prompts to install them with the distro's package manager. | ||
|
|
||
| - `.deb` packages: for Debian, Ubuntu... | ||
| - `.rpm` packages: Fedora, RHEL, SUSE... | ||
|
|
||
| ```shell | ||
| git clone https://github.com/Frogging-Family/linux-tkg.git | ||
| cd linux-tkg | ||
|
|
@@ -104,7 +151,7 @@ cd path/to/linux-tkg | |
|
|
||
| The script will use a slightly modified Arch config from the `linux-tkg-config` folder, it can be changed through the `_configfile` variable in `customization.cfg`. | ||
|
|
||
| ### Generic install | ||
|
|
||
| The interactive `install.sh` script can be used to perform a "Generic" install by choosing `Generic` when prompted. It git clones the kernel tree in the `linux-src-git` folder, patches the code and edits a `.config` file in it. The commands to do are the following: | ||
|
|
||
|
|
@@ -139,7 +186,7 @@ sudo make install | |
| - [arch](https://wiki.archlinux.org/title/Kernel-install) | ||
| - [gentoo](https://wiki.gentoo.org/wiki/Installkernel) | ||
|
|
||
| ### Gentoo | ||
|
|
||
| The interactive `install.sh` script supports Gentoo by following the same procedure as `Generic`, with minor additions | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I removed this comment entirely thinking is outdated, but I am still seeing a default
intel_pstate=passivein thecustomization.cfgfor the kernel command line. Input welcomeThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Afaik the intel_pstate=passive thing is still needed (and even exacerbated from the feedback I got) for best perf on Intel CPUs on low/medium loads, which games tend to be for the most part.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's keep it! Maybe you have a shorter version ? it's a top of the readme and it feels like too much details at that point, maybe redirect to "Default tweaks" subsection and write more there then.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion here #1190 (comment)