postmarketOS

deviceinfo_flash_methods

Introduction

Here is a guide on how to find the correct value for deviceinfo_flash_methods, 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.

Android

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.)

Fastboot mode

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.

Odin mode

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-isorec and heimdall-bootimg. You will need to find out the correct one for your device.

Isorec or bootimg?

A 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 vmlinuz file:

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)

heimdall-bootimg

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 "true". 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.

heimdall-isorec

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. Use the linux-samsung-i9100 package for reference.

Odin

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.

Maemo

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).