|
|
(18 intermediate revisions by 13 users not shown) |
Line 1: |
Line 1: |
| == Introduction ==
| | #REDIRECT [[Mainlining_Guide]] |
| We want to get as many devices working with one shared kernel package (based on [https://kernel.org upstream]). Making a device boot with the upstream kernel is commonly referred to as <i>mainlining</i>.
| |
|
| |
|
| === Why bother? ===
| |
| Carrying around forks of the kernel is not sustainable as it becomes impossible to provide security patches after a short time. The only way to truly fix this for a device is mainlining it.
| |
|
| |
|
| === Kernel packaging === | | == Introduction == |
| That package is <code>linux-postmarketos-stable</code>. For devices, which are in the kernel's <code>mainline</code> release, but not yet in <code>stable</code> (see [https://www.kernel.org/category/releases.html kernel releases]), we also have <code>linux-postmarketos-mainline</code>. It is even allowed to carry temporary patches around on top of these kernels, as long as work is being done to get them upstreamed properly. The kernel packages based on the official one are in <code>aports/main/postmarketos-linux*</code>, while the device-specific forks are in <code>aports/device/linux-*</code>.
| |
|
| |
|
| To make the kernel work with multiple devices, it no longer appends the <code>dtb</code> file to the kernel image. Instead, it puts all <code>dtb</code> files for the current architecture in <code>/usr/share/dtb</code>. The <code>postmarketos-mkinitfs</code> package appends the <code>dtb</code> file defined in the [[deviceinfo]] to the linux image in the boot partition.
| |
|
| |
|
| == Device tree source (ARM architecture) ==
| |
| To make your device boot, you will need a device tree source (<code>dts</code>) file (which will get compiled to a <code>dtb</code> mentioned above). Check the <code>arch/arm/boot/dts</code> (replace <code>arm</code> with your architecture) folder in the kernel source code for relevant files ([https://elixir.bootlin.com/linux/latest/source/arch/arm/boot/dts browse online]) with your device's codename. The general file naming is <code>$chipset_vendor-$chipset-$vendor-$codename.dts</code>.
| |
|
| |
|
| Examples: | | Examples: |
Line 22: |
Line 15: |
|
| |
|
| == Enable the mainline kernel for a new device == | | == Enable the mainline kernel for a new device == |
| ''Before proceeding, make sure that you know that your device is supported by the mainline kernel. Otherwise use the source code of a vendor's fork of the kernel, which is known to work as described in the [[porting guide]].''
| |
|
| |
|
| # run <code>pmbootstrap.py menuconfig linux-postmarketos</code> and adjust the kernel config to add the drivers for the device if they are not enabled yet. Set as much drivers to build as external module as possible so the main vmlinuz filesize doesn't increase too much. | | |
| | # |
| # Set the kernel dependency to <code>linux-postmarketos</code> in the APKBUILD for the device package if you want to make it the default kernel ([https://github.com/postmarketOS/pmbootstrap/issues/91#issuecomment-318825285 more information]). | | # Set the kernel dependency to <code>linux-postmarketos</code> in the APKBUILD for the device package if you want to make it the default kernel ([https://github.com/postmarketOS/pmbootstrap/issues/91#issuecomment-318825285 more information]). |
| # Add the name of the generated dtb file (without path or extension) to the <code>deviceinfo_dtb</code> file in the deviceinfo file. | | # Add the name of the generated dtb file (without path or extension) to the <code>deviceinfo_dtb</code> file in the deviceinfo file. |
|
| |
|
| A good example of a device using a mainline kernel is the <code>device-nokia-rx51</code> package. | | A good example of a device using a mainline kernel is the <code>device-nokia-n900</code> package. |
| | |
| == Porting drivers from a Linux fork to the mainline kernel ==
| |
| | |
| ''This is a massive amount of work, and you will need C knowledge, as well as knowledge about [https://kernelnewbies.org/KernelHacking how to contribute to the kernel]. It is probably a very frustrating path, so make sure that you are either up to that or consider contributing in pmOS in another, from a developers point of view, more enjoyable way. Documentation from our side is also pretty thin on this, so if you actually work on this, please expand it. Thanks!''
| |
| | |
| If you never worked on kernel before, you may want to help with some simple driver on already-working device. Nokia N900 should be easy, Nokia N9, N950 and Motorola Droid 4 are a bit harder. You might also try to revive support for something older, Nokia N770, N800 or N810 may not be too hard. Next in difficulty is unsupported phone based on supported SoC. TI OMAPs have pretty good support, so Samsung i9100g might be good target... Preparing mainline support for new SoC may be too much work for individual developer.
| |
| | |
| === Preparation ===
| |
| | |
| * Select a device where support is doable. Get a suitable one if necessary.
| |
| * Get a working [[Serial-debugging|serial cable]]
| |
| * Find out hardware details about your device, such as CPU, GPU, display, ...
| |
| * Find out which drivers are missing from mainline.
| |
| * Configure bootloader
| |
| | |
| === Boot with serial output and shell ===
| |
| | |
| You probably need to copy over the device tree source, from which the <code>dtb</code> file gets generated, to the mainline kernel. ''Please expand this.''
| |
| | |
| === Links ===
| |
| * [[Mainlining FAQ]] various information collected from #postmarketOS
| |
| * [[Qualcomm mainline porting]]
| |
| * Blog about [http://elektranox.org/droid4/ mainline kernel support for the Motorola Droid 4]
| |
| * [https://github.com/freedreno/freedreno/wiki/DSI-Panel-Driver-Porting Freedreno wiki: Display driver porting]
| |
| * [http://elixir.free-electrons.com/linux/v3.17/source/include/video/mipi_display.h#L28 List of DTSI -> panel driver function translations]
| |
| * [https://github.com/postmarketOS/pmbootstrap/issues/91 #91: "The Mainline Kernel"]
| |
| * [http://n900.elektranox.org/index.html Debian on N900]
| |
| * [https://developer.sonymobile.com/open-devices/how-to-build-and-flash-a-linux-kernel/how-to-build-mainline-linux-for-xperia-devices/ Build Mainline for Xperia devices]
| |
| * [https://forum.xda-developers.com/android/software-hacking/reference-how-to-upstream-android-kernel-t3626913 How to get an Android kernel up to date with Linux upstream]
| |
| * [https://nickdesaulniers.github.io/blog/2017/05/16/submitting-your-first-patch-to-the-linux-kernel-and-responding-to-feedback/ Submitting your first patch to the Linux kernel and responding to feedback]
| |
| * [http://kroah.com/log/blog/2018/02/05/linux-kernel-release-model/ Linux Kernel Release Model] (reasons why we should all be using mainlined kernels)
| |
| * [https://talk.maemo.org/showthread.php?t=99357 Documenting devices with mainline Linux support]
| |
| * [https://elinux.org/Device_Tree_Reference Device Tree reference on elinux.org]
| |
| * [https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree Documentation of devicetree bindings]
| |