Difference between revisions of "Mainlining"

From postmarketOS
Jump to navigation Jump to search
m (more LBRY links)
m (another LBRYs links)
Line 81: Line 81:
* Introduction into ARM architecture, 2017 (46:33) [https://www.youtube.com/watch?v=NNol7fRGo2E Youtube] [https://lbry.tv/@PortingLinuxPhones:5/A-tour-of-the-ARM-architecture-and-its-Linux-support,-2017 LBRY]
* Introduction into ARM architecture, 2017 (46:33) [https://www.youtube.com/watch?v=NNol7fRGo2E Youtube] [https://lbry.tv/@PortingLinuxPhones:5/A-tour-of-the-ARM-architecture-and-its-Linux-support,-2017 LBRY]
* Device Tree (DT) introduction, 2013 (1:12:14) [https://www.youtube.com/watch?v=m_NyYEBxfn8 Youtube] [https://lbry.tv/@PortingLinuxPhones:5/Device-Tree-for-Dummies!---Thomas-Petazzoni,-Free-Electrons LBRY]
* Device Tree (DT) introduction, 2013 (1:12:14) [https://www.youtube.com/watch?v=m_NyYEBxfn8 Youtube] [https://lbry.tv/@PortingLinuxPhones:5/Device-Tree-for-Dummies!---Thomas-Petazzoni,-Free-Electrons LBRY]
* [https://www.youtube.com/watch?v=PgQezmlst0w Device Tree: present, past, future, 2018] (37:28)
* Device Tree: present, past, future, 2018 (37:28) [https://www.youtube.com/watch?v=PgQezmlst0w Youtube] [https://lbry.tv/@PortingLinuxPhones:5/Device-Tree--Past,-Present,-and-Future,-2018 LBRY]
* [https://www.youtube.com/watch?v=LPG4EkXK9Us ARM64 SoC Linux Support Check-List, 2017] (42:38) ''Very useful step-by-step guide what should be done to bring in SoC support''
* ARM64 SoC Linux Support Check-List, 2017 (42:38) [https://www.youtube.com/watch?v=LPG4EkXK9Us Youtube] [https://lbry.tv/ARM64-SoC-Linux-Support-Check-List-(2017) LBRY]''Very useful step-by-step guide what should be done to bring in SoC support''
* [https://www.youtube.com/watch?v=RBB6qKLUpd8 Upstreaming ARM64 SoC's easier than before, 2019] (19:03)
* Upstreaming ARM64 SoC's easier than before, 2019 (19:03) [https://www.youtube.com/watch?v=RBB6qKLUpd8 Youtube] [https://lbry.tv/SAN19-219-Upstreaming-ARM64-SoC's-easier-than-before LBRY]
* [https://people.kernel.org/linusw/how-the-arm32-kernel-starts How the ARM32 kernel starts] by [[Special:Contributions/Linusw|Linus Walleij]]
* [https://people.kernel.org/linusw/how-the-arm32-kernel-starts How the ARM32 kernel starts] by [[Special:Contributions/Linusw|Linus Walleij]]

Revision as of 16:17, 19 September 2020

Mainlining is the process of replacing the kernel provided by the device vendor (the "downstream" kernel), with a version close to the actively developed version released on kernel.org (the "mainline" kernel). It involves porting (and most importantly: cleaning up) device-specific code from the downstream kernel to the mainline kernel. For some SoCs, common support already exists in mainline, so you can focus on device-specific components.


Mainlining is a fairly complicated process, especially if you're one of the first to start work on a given SoC. However through community effort there is a growing number of SoCs that have increasingly stable mainline ports (see below). In general it is relatively simple to take your existing Android kernel and boot it without any of the Android blobs, however from that point it can be a lot of working to create a working system and at the end of it you don't receive any security patches or general improvements.

Apart from purely practical insufficiencies, the cold hard truth is that the downstream code is simply not meant to be maintained or get used outside Android. The code quality is often several magnitudes worse, which makes maintenance rather complicated. Often large parts of the drivers are moved into proprietary parts in Android userspace - which are generally impossible to use without emulating the expected Android environment. At the end, the effort to make such drivers work properly on long term is often as much as rewriting them properly for mainline.

Successfully mainlining an SoC or device means that you benefit from every improvement the Linux kernel has to offer, you can run a fairly standard Linux distro (in theory even any Linux distro) and benefit from kernel updates and improvements without needing to compile your own kernel or deal with frustrating patches. A notable easy-to-notice benefit of running mainline is minimal-effort-needed GPU support for almost all GPUs (except PowerVR unfortunately), which is needed for using modern phone DEs like Plasma Mobile or Phosh with acceptable performance. Lastly, mainlining is a terrific learning opportunity that you will never regret.

If your device's SoC is in the list below there's a very decent chance that you can get the same functionality working on your device and eventually upstream your patches to the kernel, helping to build a solid base for other devices too!

TODO Explain process for previous devices that now run mainline quite well


Supported SoCs

Some SoCs are already supported quite well and are used for some devices in postmarketOS. Getting started with one of these might be easier for you, because you can get help from others working with the same SoC. The feature matrix below shows which features are already supported for a particular SoC. The pages for each SoC will provide more information, plus hints how to get started and who you can contact.

  • CPU: SMP (bring up secondary CPU cores), CPU frequency scaling, CPUidle
  • Storage: eMMC, SD cards, UFS, ...
  • Video: Hardware-accelerated video de/encoding
  • Modem: Calls, SMS, Internet
  • Unavailable (-) means that such a feature is not built directly into SoC. For example, WiFi/BT are also often used through SDIO/UART which can be chosen independently from the SoC.

Note: The statuses displayed below signify if a particular feature was tested on a device by someone in the postmarketOS community - not necessarily the components supported in the mainline kernel.

SoC Arch Year UART USB Storage Display CPU GPU Pinctrl I²C Audio Video Thermal WiFi BT Modem Camera
Allwinner A64 aarch64 2015 Y Y Y Y P P Y Y Y Y - - - Y
Intel Bay Trail x86_64 2013 Y Y Y Y Y Y Y Y Y Y Y - - - N
Nvidia Tegra 2 armv7 2010 Y Y Y Y Y P Y Y Y Y Y Y Y N P
Nvidia Tegra 3 armv7 2011 Y Y Y Y Y P Y Y Y Y Y Y Y N P
Qualcomm MSM8916 aarch64 2014 Y Y Y Y Y Y Y Y Y Y Y Y Y Y P
Qualcomm MSM8939 aarch64 2014 Y Y Y P Y Y Y Y Y Y
Qualcomm MSM8953 aarch64 2016 Y Y Y Y Y Y Y Y Y Y Y P Y P P
Qualcomm MSM8974 armv7 2013 Y Y Y Y P P Y Y Y Y Y P
Qualcomm MSM8996 aarch64 2016 Y Y P Y P Y Y Y Y Y - -
Qualcomm MSM8998 aarch64 2017 Y Y P P N Y Y Y Y Y P
Qualcomm SDM630 aarch64 2017 Y P Y P P Y Y P P
Qualcomm SDM636 aarch64 2017 Y P Y P Y Y
Qualcomm SDM660 aarch64 2017 Y P P P Y
Qualcomm SDM845 aarch64 2018 Y Y Y Y Y Y Y Y Y Y Y Y P N
Qualcomm SM8150 aarch64 2019 Y Y Y P Y Y Y
Rockchip RK3399 aarch64 2016 Y Y Y Y Y Y Y Y Y Y Y - - -
Samsung Exynos 8895 aarch64 2017 Y Y
ST-Ericsson NovaThor U8500 armv7 2011 Y Y Y Y Y Y Y Y Y - -
Texas Instruments OMAP44xx armv7 2011 Y Y P Y Y Y Y

Getting help

Mainlining related to postmarketOS is primarily discussed in the #postmarketOS-mainline channel. For one of the SoCs above there should be someone around who is able to help you to some extent. Note that you will be on your own for some of the problems - there are often device specific problems or components that no one has experience with yet.

Below are some more chat channels / mailing list that may be helpful for further help or if you want to work on a SoC that is not listed above (yet!):

SoC Where to ask for help
#postmarketOS-mainline (SoC-specific questions might be limited to those listed above)
Exynos #replicant on Freenode (ask forkbomb, Putti)
OMAP3 ask @pavelm, linux-omap@vger.kernel.org
Qualcomm (msm...) ##linux-msm on Freenode, linux-arm-msm@vger.kernel.org
Tegra ask @okias, ##tegra on Freenode, linux-tegra@vger.kernel.org

Getting Started

  • Collect as much information about your device as you can: downstream kernel sources, specifications, schematics (can be sometimes found with your favorite search engine) are all going to prove invaluable when attempting to port a device to mainline.
  • Serial debugging will be helpful especially in the beginning (before USB or network is working). Some devices expose it through the USB port or the audio jack; others have test points available on the mainboard.
  • Choose a kernel tree:
    • Mainline: (the last kernel version released by Linus Torvalds) Usually a good compromise of being recent, yet quite stable. torvalds/linux.git
    • linux-next: A collection of recently merged changes from many subsystems; use this if you are working on a very recent SoC. next/linux-next.git
    • There may be more WIP changes available in Linux kernel trees specific to your SoC.
  • Compiling kernels with envkernel.sh is very useful to integrate kernel development into postmarketOS.
  • If you are attempting to port to a SoC listed above, check the SoC wiki page for further help and instructions.
  • Do not attempt to copy any code as-is from downstream. In general this won't work, and most importantly: it won't be accepted for inclusion into the mainline kernel upstream.
    • Instead, try to understand what the downstream code does, and rewrite it from scratch for mainline by looking at similar code.

Materials to look into

This section include many useful sources to help you with mainlining as possible.


  • Introduction into how mainlining is done (52:37) Youtube LBRY


Specific topics:

Writing device trees:

Submitting patches:

See also

  • Mainlining Guide (very generic, parts are slowly incorporated into this page)
  • MSM8916 Mainlining (specific to MSM8916, but might be helpful for similar Qualcomm SoCs)
  • pmaports#175 Google Galaxy Nexus (samsung-maguro): Mainlining progress (initial tricks with RAM and some sleep calls before the reboots in the code to figure out where it was failing will also be useful for other devices)
  • pmaports#153 Google Pixel 3 XL (google-crosshatch): mainlining attempt: progress and questions (useful for newer SoCs, useful info about force-reboot code, stub dtbo partition)