From postmarketOS
Revision as of 18:36, 9 May 2019 by HenriDellal (talk | contribs) (→‎Kernel doesn't even boot: Describe "bad boot image header" error)
Jump to navigation Jump to search

This page is about systematically debugging new postmarketOS device ports, where the kernel successfully compiles, but booting it appears not to be working at all. As always, please extend with everything you find out.


  • Make sure you have created a wiki page for your device
  • Document everything you have tried out there, so when the next person with the same device comes along, it is possible to start from the work you have already done.

General tips

  • When everything fails: Try different kernel sources for your device
    • Ideally you would use the kernel sources, that have been used to build a known working (Android) ROM or recovery image (e.g. TWRP) for your device
      • Make sure that you are really able to boot that known working kernel with Android/TWRP etc.
    • For Android devices, if the usual LineageOS kernel does not work, try to find another one through GitHub search and on XDA
  • Ask in IRC/Matrix
  • Open an issue (and link to it from your device's wiki page)
  • Make a serial cable and look at the output of the bootloader
  • If there is a similar device, that already has a postmarketOS port, take a look at its aport to see if it does anything special.
  • Extract the TWRP boot.img, and the initramfs inside it (with unpackbootimg and cpio)
    • Look through all the rc files, there might be some useful comment or some line like write /sys/class/xxx/yyy/enable 1

Does the kernel boot?

Even if it looks like your device does nothing (e.g. still displaying the OEM logo or displaying a black screen), it can be that the kernel is actually booted. So unless you know for sure that it does not boot at all (because it directly reboots), try the following to get clarity:

  • Check if you have a new network interface (run ip a or ifconfig)
  • Check the output of lsusb (before plugging the device in, then while it is in the bootloader mode, and finally after you have booted pmOS)
  • Check what dmesg says after booting
  • Run with an initramfs hook, that signalizes a successful boot with LEDs and the vibrator:
$ pmbootstrap initfs hook_add maximum-attention
$ pmbootstrap flasher boot
(or however you boot the kernel/initramfs)
  • Try to read dmesg after rebooting:
    • Immediately entering flash mode after the reboot
    • Boot a custom recovery such as TWRP
    • read /proc/last_kmsg or /sys/fs/pstore/console-ramoops to see if it booted at all, and what caused the reboot
    • more on that topic is here and here

Depending on whether your kernel is booted or not, read on in the appropriate section below. If it turns out, that your kernel is booted, and you have a network interface and get an IP address, then you probably only need to get your display working.

Kernel boots without network interface

echo 4 > /sys/devices/platform/android_usb/usb_function_switch
  • It is possible to dump the sysfs from an initramfs hook to a partition on the device, and read it out and comparing with another system (such as TWRP).
  • See the initramfs hooks examples.

postmarketOS is stuck somewhere in the boot process

  • Do you have the system partition flashed to your device (or put it on an SD card and inserted it)?
    • If the initramfs can not find the boot partition, it will display an error splash screen and wait forever.
    • That means, if your screen does not work yet, it will just appear to be stuck and the SSH server will not come up.

Run the initramfs script line by line

Install the debug shell initramfs hook to get a telnet shell directly from the initramfs. As soon as you are in the initramfs shell, open in your browser, and execute it line by line to figure out where it fails. The functions you are calling (mount_boot_partition etc.) are defined

$ . /
$ . /etc/deviceinfo
(the lines until 'mount_boot_partition' can be skipped, as they have already been executed when the usb-shell hook is running)
$ mount_boot_partition
$ extract_initramfs_extra /boot/initramfs-*-extra
$ start_charging_mode

Can ping to device, but SSH says "connection refused"

It might be that fsck fails on a partition: try telnetting into initramfs, mount the root partition, and comment out the boot partition in /etc/fstab, then try booting (#1511). If that is the cause of the error, it should also be fixed by re-flashing the postmarketOS rootfs (might be easier).

If that does not help

  • If you have powered off the device while it was not fully booted yet, it could be that you killed it while it was generating SSH keys. That means, it may have empty files instead of actual keys, so they will not get generated again, but also SSHD fails to start. When this could be the case with your issue, try to flash again and make sure that you do not turn off the device during the boot process this time.
  • If the initramfs script seems to be working fine, chances are that the error happens as OpenRC runs. See #1582 for steps to log OpenRC's output to kmesg

Kernel doesn't even boot

  • Check the output of the bootloader with a serial cable if you have one.
    • Making such a cable takes some time, and it isn't even known how to do it for all devices. So if you don't have such a cable, try other methods.
  • Double-check that you have used the right defconfig
  • Android bootimg issues:
    • Make sure that pmbootstrap bootimg_analyze outputs the same values, that you have put in your deviceinfo
    • Analyze a bootimg file, for which you have verified that it boots on your device (with TWRP or Android).
    • If you have a QCDT device, check out QCDT debugging
    • use extract-dtb and unpackbootimg (both packaged in postmarketOS) to compare the dtb files appended to the kernel and boot.img file (compare the postmarketOS version against the one from a known working ROM or recovery OS such as TWRP)
  • A less systematic approach is booting the postmarketOS initramfs with a prebuilt kernel. This is listed for the sake of completeness, but building another kernel from source (like in the porting guide) is probably more fruitful and over a much cleaner approach.
  • If you get bad boot image header error trying to boot from SD card, it may be that fastboot mode on the device doesn't allow fastboot boot usage. Run fastboot boot boot.img where boot.img can be a recovery image or working boot image from stock or custom firmware. If you get the same error, you should flash kernel on device with pmbootstrap flasher flash_kernel.
  • Alpine Linux' armhf architecture requires armv6 with FPU #1203

See also