Troubleshooting:boot

From postmarketOS
Jump to: navigation, 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.

Preparation

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

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.
  • Install the debug shell initramfs hook to get a telnet shell directly from the initramfs
    • Try to run the lines from the init script manually to see where it fails (see aports/main/postmarketos-mkinitfs/init.sh.in in the pmbootstrap code)
  • 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.

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.
  • Alpine Linux' armhf architecture requires armv6 with FPU #1203

See also