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