This is a noob-friendly guide on how to mainline patches to mainline linux for the pinephone pro (short form: ppp). This should help you get your first patch into the Linux kernel! Any questions? Ask away!
What does “mainlining” mean exactly? An Android or Linux device usually has some drivers to make peripherals (eg. touchscreen, battery, etc.) work. The problem is that these devices usually run an outdated Linux kernel. That means you are constantly rebasing and testing changes on top of mainline Linux. Anything breaks, and it’s up to you to fix it. It’s quite exhausting.
Instead we want to push these changes so that we can get the community to help maintain it for us. Any breakages that happen after our commit, and all we would have to do is report it upstream (providing important details like when the first problem started happened, etc.) and let whoever introduced the breaking bug fix it for us. It’s quite nice as we can start focusing on other things!
Luckily for us, the ppp is running a close to mainline Linux kernel. If you look at the commits, there are only a couple commits (114 commits!) on top of 6.13. Let’s change that to 0!
This guide could probably be generalized for other devices, but for now let’s focus on the Pinephone Pro. Let’s break this down into distinct steps: Build, Test, Upstream, Iterate.
Build
Let’s setup your environment first. Each distro is unique but the requirements to build the linux kernel is the same. Essentially you will need these packages listed in makedepends installed on your machine. Install these via your package manager.
Next, let’s get the Linux kernel tree! Note: This is a clone of the linux kernel tree. GitHub is not where Linux kernel development is done
git clone https://github.com/torvalds/linux.git
Now we also want to get the ppp’s kernel as well. To make the clone faster this time, we want to cd into the cloned mainline tree we just got, and then we want to fetch the ppp tree in the mainline tree. They share commits so it’ll be a faster clone this time.
cd linux
git remote add ppp https://gitlab.com/pine64-org/linux.git
git fetch ppp
git switch linux-pinephonepro-6.13.y
Nice! We got our environment setup now. Let’s try building the kernel!
There are many mainline building tools out there. There is pmbootstrap (the one we are using today), mkosi, T2 SDE, Yocto, Buildroot, and you can even just do a simple Linux+busybox initramfs if you’d like! Use whatever tool you’d like (although you probably aren’t reading this if you know of another tool). pmbootstrap is good enough for our purposes and one of the easier setups to run mainline linux on arm devices.
Let’s start with the ppp’s close-to-mainline kernel. We want to make sure that our setup actually works before we actually start pushing commits upstream.
Building and Flashing Steps:
# Assuming you somehow moved away from the linux directory you cloned. Make sure you are on the linux-pinephonepro-6.13.y branch!
cd linux && \
# I zap because chroot frequently gets corrupted on my machine... you don't need to do this if it's not required.
pmbootstrap -y zap -a && \
# Let's copy the Linux configuration that pmOS uses into our tree
wget https://gitlab.postmarketos.org/postmarketOS/pmaports/-/raw/master/device/community/linux-pine64-pinephonepro/config-pine64-pinephonepro.aarch64 -O arch/arm64/configs/ppp_defconfig
# We build using clang and output into .output. We build for arm64 with all the cores on our system. We configure Linux with ppp_defconfig, add/remove any configs we want, then build.
make LLVM=1 O=.output ARCH=arm64 -j$(nproc) ppp_defconfig menuconfig all && \
# Useful for our editors as if we need to edit anything in the Linux tree, there will be type hints available
./scripts/clang-tools/gen_compile_commands.py -d .output/ && \
# Once our kernel build successfully, we tell pmbootstrap to use it
pmbootstrap build --envkernel linux-pine64-pinephonepro && \
# We force a ppp device build to use our new kernel
pmbootstrap build --force device-pine64-pinephonepro && \
# We walk through pmbootstrap install
pmbootstrap install && \
# We install the new package via https://wiki.postmarketos.org/wiki/PINE64_PinePhone_Pro_(pine64-pinephonepro)#Internal_storage_(eMMC)
pmbootstrap install --fde --sdcard=
# Once you have a base image installed, you can use this instead to update the kernel on an existing system
# pmbootstrap sideload linux-pine64-pinephonepro
If this works, great! Go back to your computer and do:
# We use v6.15 here, but this should be the latest Linux stable release. The reason we do stable and not tip is so that maintainers can easily apply it to their tree
git checkout v6.15
git switch -c ppp_mainline
# Now doing git log should give you Linux stable release by Torvalds!
git log
Unfortunately, there isn’t really an easy step-by-step guide on how to apply downstream patches. What you want to do is see what patch in downstream you would like to mainline, cherry-pick that into the mainline tree and build it according to Building and Flashing Steps referenced above. There might be other patches that depend on the patch you would like to mainline. Use your best judgement!
Test
Once you flash the ppp with the new kernel, can you do the thing that the commit said you could now do? Or was it already possible in mainline linux? If it’s new and it works, congrats! Let’s try to upstream it.
Upstream
Now that we have a working patch, let’s upstream it. We’ll use these 2 nice guides on how to upstream patches. I suggest you give these a watch:
Here’s the notes from the videos for quick reference:
# First time
b4 prep -n <label> -f <tag>
# Follow up (Make changes first)
b4 trailers -u
b4 prep --edit-cover # Update what you changed
rm -rf /tmp/tosend && b4 send -o /tmp/tosend && hx /tmp/tosend
./scripts/checkpatch.pl /tmp/tosend/*
b4 prep --compare-to v#
b4 prep --auto-to-cc
b4 prep --check
b4 send --reflect
b4 send
One note: DO NOT rewrite the original author’s signed off by or any other tags. If there is none, add a signed off by with the original author and put your signed off by afterwards. You want to give credit where credit’s due. No exceptions.
Iterate
No doubt you will get feedback on this patch. That’s okay! Ask questions, and show interest that you want to get this patch merged in.
Once some people have put their reviewed by tags and there is no more feedback, the series will undoubtably go quiet. Don’t worry, they aren’t ignoring you, that is just how the patches are accepted. Once a new kernel is released (in this case 6.17, since 6.16-rc1 is already out), that is when your patch will go in. If you don’t get an ack email around this time, make sure to resend your patch or email within the previous patch to ask what happened. Communication is important!
Once Your Patch is in
Congrats! After a couple months long process, you have finally gotten your patch accepted into mainline Linux. I hope you continue your mainlining journey! There are still many devices running close to mainline 
The goal of this guide is to show kernel veterns that helping kernel newbies is well worth the effort. You can get tedious tasks off your plate, and kernel newbies can have an easy entry into kernel hacking. Hopefully others write similar guides to their devices. Feel free to steal this :D.
A Note about PINE64
Unfortunately, I’m of the opinion at this point that PINE64 is not worth buying hardware from. They have made millions from selling hardware and (I believe) have not adequately given back to the community.
- Contributing to PinePhone kernel development → megi only received 1100 EUR from Pine64, pennies compared to traditional software engineers (especially since megi helped PINE64 earn millions in hardware sales with the sheer number of kernel commits they have done)
- Why I left PINE64
- PINE64 has let its community down
- Maybe more that I don’t know about
It comes as no surprise to me that a company that relies on slave labor to make the hardware for their phone, also expects slave labor for the software of their phone as well. There was a lot riding on this experimental project (Linus Tech Tips was even excited about this project!) yet years later the ppp is barely useable as a mainline Linux smartphone (battery, charging, camera, maybe more still dysfunctional?).
Maybe Fairphone or some other company can steal the spotlight from PINE64 and truly invest into individual developers committed to making mobile Linux a reality. Sort of how Valve is revolutionizing Linux gaming. For that, take a book from Valve’s playbook and invest back into the community that believed in you in the first place.
Why am I wanting to mainline this phone now? Because it’s been a couple years that PINE64 can’t really claim my or other progress as their own. If they do, they’ll look a bit crazy since the progress was glacial slow. The reason I want to mainline is that I just want a nice Linux mainline phone.
Comments, Questions, Concerns?
Ask away! I will update this post if others have insightful comments/questions. We’re here to help each other (hopefully :P)!