User:Knuxify/Draft:Porting guide/Kernel package
The next step of the porting process is to package the Linux kernel. Depending on the choice of a downstream or mainline kernel, the process will be different.
Downstream or (close to) mainline kernel
postmarketOS, being a Linux distribution, uses Linux as its kernel. However, there's a distinction between the original kernel provided by the manufacturer, and the standard upstream Linux kernel.
Downstream (vendor) kernel
The downstream/vendor kernel is the Linux kernel source provided by the manufacturer of the device. It's usually many versions out of date and comes with limited support.
The lifecycle of a vendor kernel is as follows:
- The SoC vendor creates a fork of the Linux kernel (typically based on the Android Common Kernel) with their own SoC drivers added to it.
- The device manufacturer creates their own fork of that kernel with their own device-specific changes.
- Neither of the two upstream the changes to the Linux kernel. Oftentimes, the kernel is only upgraded a few times before device support is dropped.
In the case of Android devices, vendor kernels are made to run Android, and often assume that an Android HAL (hardware abstraction layer) and Android-only vendor blobs will handle many components like audio, modem, camera, GPU acceleration and others. Since the HAL is not present on postmarketOS, vendor kernels provide limited functionality.
Nonetheless, the downstream kernel is a common starting point for new ports; in many cases, where the chip isn't supported in mainline Linux or its support is poor, it's the only option easily available to new porters.
New devices running the downstream kernel go to the downstream
category (see Device categorization).
(Close-to) mainline kernel
In contrast, a (close-to) mainline kernel is based on the upstream Linux kernel and actively maintained by the community. Since it's meant to accommodate a proper Linux userspace, you can expect that more features, like GPU acceleration, will work (and others can be made to work in the future).
However, making a device work with the mainline kernel is a much more involved process. The upstream kernel must have drivers for the SoC in your device and its components (like Wi-Fi/Bluetooth chip, touchscreen controller, display panel, sensors...). Then, a DTS (device tree source/definition) needs to be written to describe your device.
Getting everything to work on mainline is a process that can take anywhere from a few hours (for well-supported devices, where you only need to write a DTS) to even months (in cases where all drivers need to be written from scratch).
New devices running the mainline kernel go to the testing
category.
Which one should I choose?
If your device's SoC has good mainline support, go with mainline. Despite the scary warning above, mainlining devices with well-supported SoCs is usually a very streamlined process, and will allow you to get a device working much more quickly, with more features and without the hassle of getting the downstream kernel to compile.
There are dedicated step-by-step mainlining guides for various mainline-supported SoCs. They are usually linked from the wiki page for the SoC - find yours in the Mainlining#Supported SoCs table. If there is no such guide for your device's SoC, you can ask for advice on Matrix - see the channels listed in Mainlining#Getting help. A generic Mainlining Guide also exists.
If your device's SoC is not supported in mainline, continue with the downstream kernel.
TODO: Make this nicer |