Deviceinfo flash methods
Here is a guide on how to find the correct value for
deviceinfo_flash_method, and some pitfalls you need to look out for depending on your flasher application. Please note, that all flasher mode implementations on the phones
listed here are proprietary (even if the flashing software is open source). But they are hard to replace (if we can do that at all), so we will use them for now to flash pmOS on the devices.
Boot your phone into the bootloader menu. Usually this can be done by holding
Volume Down and the
Power button, until something changes on the screen, then only holding the
Volume Down button until the menu appears. It should say either "Fastboot mode" or "Odin mode", read the appropriate section below. If
you don't know the combination for your device, please search the Internet. (It is also a good idea to write this combination to your device's pmOS wiki page, so we can look it up quickly.)
Most Android devices are compatible with the open source fastboot protocol. That is good, because we simply can use the fastboot application to flash them, and no one needs to reverse engineer the protocol. You are done here, if you have a
fastboot compatible device.
This uses a proprietary flashing protocol from Samsung. There has been great effort put into Heimdall, an open source program that tries to be compatible to the odin protocol. But it does not work perfectly yet, and some devices are not supported at all.
So first check if your device also supports fastboot - some Samsung devices (such as the Galaxy Nexus) actually have both protocols (you would need to press another key combination to enter fastboot mode - search the Internet for the supported flash modes of your device). If you can use fastboot, please do so.
For postmarketOS we're going to use Heimdall, but we use it in two different configurations -
heimdall-bootimg. You will need to find out the correct one for your device.
Isorec or bootimg?
boot.img file contains a Linux kernel and an initramfs, along with some other configuration, such as the kernel command line. Some Samsung devices support these
boot.img files, while others only support flashing a kernel with a baked-in initramfs. To find out what your device has, download a known working image for your device (e.g. from the vendor, or a LineageOS ROM, ...). Usually they come in zip files. Extract the zip file, and you will find a
boot.img inside. Run the command
file on that to find out, whether it is a real
boot.img file, or just a
file boot.img # real boot.img file -> use heimdall-bootimg Android bootimg, kernel, ramdisk, page size: 2048
file boot.img # actually a vmlinuz file -> use heimdall-isorec boot.img: Linux kernel ARM boot executable zImage (little-endian)
When using that flasher, make sure that you also add
mkbootimg to your
depends line in the
APKBUILD, and that you set
deviceinfo_generate_bootimg in your
deviceinfo file to
To generate a working boot.img, in the
deviceinfo you also need to specify the variables for the various offset, follow this guide to find the correct values for your device.
Usually the initramfs would get packed into the vmlinuz file, when it has no support for the
boot.img format. But this is a problem for postmarketOS, because we want to generate the initramfs explicitly after compiling the kernel, like it is done in typical Linux distributions.
So what we do instead, is putting the real initramfs on the recovery partition (or any other free partition, such as "kernel2", but the name comes from "isolated recovery" and was coined by Lanchon). The initramfs baked into the kernel only extracts the real initramfs, and executes its init script.
You will need to adjust the
init script of your kernel's built in initramfs to point to the right partition. See this section for reference.
In case you can't get it working with Heimdall, you could use the proprietary Odin program for Windows (e.g. in a VM) and flash from there. To do that, run the following commands to export all generated files from
pmbootstrap and create an Odin-compatible tar file:
pmbootstrap install pmbootstrap flasher export --odin
It would be great if you could record your flashing session with a USB sniffer and send it to the Heimdall developers (as ticket) or even implement support for your device in Heimdall yourself (C++ knowledge required). Please expand this wiki page on how to actually sniff the USB traffic, if you do that.
Recovery mode (adb)
When all methods above fail (e.g. because fastboot does not allow you to flash the system partition or kernel), there is still the possibility to flash postmarketOS to your device as long as you can get into a recovery mode, and "sideload" a recovery zip file onto your device. In order to do that, you will need a recovery system installed on your phone, TWRP is recommended.
To generate a recovery zip file and flash it, execute the following:
pmbootstrap install --android-recovery-zip
- boot your device into TWRP
- swipe to allow modifications (if you get asked for that)
- click on "Advanced" / "ADB Sideload"
- swipe to start sideload
pmbootstrap flasher --method adb sideload
The correct flasher is
0xffff (which reverse engineered Nokia's proprietary flashing protocol). Right now we do not have abstracted it in the pmbootstrap config (so
pmbootstrap flasher flash_kernel etc. will not work). That is because the Maemo devices have an SD card slot, and it is possible to install uboot on them - so flashing was not really required yet. But it is easy to extend the config to implement that abstraction when it is needed.
Simply edit the
0xffff part in
pmb/config/__init__.py (and please make a pull-request after you have tested it).