Linux kernel backports package
This package provides backport support for drivers from newer kernels down to older kernels. It currently backports the following subsystems:
- Wireless
- WWAN
This package provides the latest Linux kernel subsystem enhancements for kernels 4.14 and above.
Documentation
This package is documented online and has more-up-to date information online than on this README file. You should read the wiki page and not rely on this README!
https://backports.wiki.kernel.org
How to Build
The driver backporting process involves two main steps. First, the code from the repository, along with compatible Linux kernel sources, is used to generate a backports package. The backports repository contains the necessary code to adapt upstream Linux drivers and subsystem sources. The generated backports package can then be compiled against any supported kernel version. The project provides pre-generated backports packages.
If you are using a pre-generated backports package, follow the section [on building backports against your Linux kernel](##Build backports). If you want to generate a new backports tar from the Linux kernel sources, refer to the [Generate backports](##Generate backports) section.
Pre-generated backport packages are located here: https://backports.wiki.kernel.org/index.php/Releases
The main repository is located here: https://git.kernel.org/pub/scm/linux/kernel/git/backports/backports.git/
Generate Backports
This step generates a backports package from the code in the backports repository combined with the Linux kernel sources. It copies the drivers from the Linux kernel sources, patches them, and adds extra compatibility code to ensure they work with older kernel versions.
The Coccinelle spatch tool is required for this step.
To generate a backports package, run the gentree.py script as follows:
./gentree.py <kernel tree> <output directory>
<kernel tree> points to the sources of a matching Linux kernel.
<output directory> is the directory where the resulting backports package will be written.
As the upstream Linux kernel changes frequently, use matching versions for compatibility. The backports package is tagged with the same version as the matching kernel version. If a different combination is used, modifications might be necessary.
This process can also be done inside a container. The GitHub CI generates
the ghcr.io/hauke/backports container for this step. It contains all
supported kernel versions for easy testing.
To start the container, use the following command:
podman run -v ~/linux/linux-clean:/linux:ro -v ~/backports/backports:/backports:rw -it ghcr.io/hauke/backports /bin/bash
Inside the container, run:
cd /backports
./gentree.py /linux/ /backports-6.1.100
Build Backports
This section explains how to configure and build a pre-generated backports package against a supported kernel. The official pre-generated tar files have names like this: backports-6.1.97-1.tar.xz. This example is a backports package built from Linux kernel 6.1.97 and can be built against all supported kernel versions, in this case, any Linux kernel between versions 4.14 and 6.1. We test builds against the most recent minor version of every kernel version in between.
Configuring
First, select the drivers you need. Backports uses the configuration system
from the Linux kernel. You can either use make menuconfig to select individual
drivers or use the prepared defconfigurations like make defconfig-wifi. See
the defconfigs folder for more options. To select everything, use
make allyesconfig. By default, all code is built as kernel modules.
It is recommended to use a defconfig.
The drivers from backports conflict with the drivers provided by your kernel. You cannot load the mac80211 framework from both the kernel and backports simultaneously because they export symbols with the same names.
Building
After configuring, simply run make to compile against the currently
installed kernel.
To compile against a different kernel, define KLIB and KLIB_BUILD like this:
make KLIB=/ksrc-backports/lib/modules/5.15.148-0515148-generic/build/ KLIB_BUILD=/ksrc-backports/lib/modules/5.15.148-0515148-generic/build/
Running make install will install the kernel modules.
Testing
We perform automatic build tests against the most recent Linux stable minor version of all kernel versions in between. GitHub Actions are used for testing. Currently, we do not have the resources for automatic runtime tests.
License
This work is a subset of the Linux kernel as such we keep the kernel's Copyright practice. Some files have their own copyright and in those cases the license is mentioned in the file. All additional work made to building this package is licensed under the GPLv2.
Backporting preference for EXPORT_SYMBOL_GPL() and proprietary drivers
This framework was designed by intent since its inception only for upstream Linux kernel drivers to avoid excuses about the difficulty to support upstream Linux kernel development while also supporting users on older kernels. To ensure the intent is respected currently all symbols that we do work on to backport are exported via EXPORT_SYMBOL_GPL() as we do work to backport them for the supported kernels. By using EXPORT_SYMBOL_GPL() we make it clear that if you use the backported symbols your software is considered derivative works of the Linux kernel.
Comprendes, Mendes?