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