Deviceinfo flash methods

Introduction

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.

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.

`fastboot`

The standard Fastboot flasher using Android boot images. Use this for Fastboot unless you know what you are doing.

`fastboot-bootpart`

Some devices provide a Fastboot interface but using Android boot images is not practical for them (e.g. because they support booting from FAT32 partitions directly). This can be implemented using --split (separate image files for boot and rootfs). The fastboot-bootpart flash method allows flashing the split image files using Fastboot.

The boot partition filesystem is flashed to deviceinfo_flash_fastboot_partition_kernel (without packing it into an Android boot image).

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)

file boot.img # probably a dzImage file used in Tizen -> use heimdall-isorec, keep reading
boot.img: data

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. See this section for reference. Note that this init script expects initramfs compressed in lzop format, which is only generated by pmbootstrap export --odin command. If you only executed pmbootstrap export, then the resulting initramfs is still in gzip format, so decompress and recompress into lzop format if you want to flash it.

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 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
run pmbootstrap flasher --method adb sideload

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

Tizen

Samsung's Tizen devices use dzImage, basically vmlinuz plus combined dtb files with a custom header. Because the format does not support embedding a separate initramfs, you need to flash initramfs in another partition and use heimdall-isorec. tizen-mkdzimage^PMOS can generate the dzImage file for Tizen-based smartphones (Z1 to Z4) and smartwatches. See Samsung Z1 (samsung-kiran) for the example.

MTKClient

Some devices with MediaTek SOCs do not have readily available flashing methods. As such, the reverse-engineered MTKClient can exploit quirks in the SOC to gain access to device partitions. This method is generally used for Android devices that either have fastboot disabled in the bootloader or have trouble with issuing fastboot commands. This does not mean that non-Android devices cannot use this method. If you have a device with a MediaTek SOC, it might be possible that MTKClient will still support your device.