Jump to content

Troubleshooting on-device issues/Booting problems: Difference between revisions

From postmarketOS Wiki
See also: HTC isn't playing nice
Add resource for Qualcomm LK Boot Loader resource
Line 59: Line 59:
* {{github|1203}} HTC Wildfire not booting
* {{github|1203}} HTC Wildfire not booting
* {{github|99}} HTC Droid DNA (dlx) not booting
* {{github|99}} HTC Droid DNA (dlx) not booting
* [https://developer.qualcomm.com/qfile/28821/lm80-p0436-1_little_kernel_boot_loader_overview.pdf Qualcomm LK Boot Loader Overview]

Revision as of 04:44, 6 February 2018

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.

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)
    • If the entry disappears, it got stuck while booting.
  • Check what dmesg says after booting

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

The postmarketOS initramfs is able to configure two different USB systems in the kernel in order to let your PC talk to your phone via networking. One of them has to be enabled (exclusively?):

You can use grep on your kernel config to check which of these options are enabled or not (option=y means it is enabled). If you want to change the options, don't modify the file directly, but use pmbootstrap menuconfig (usage instructions). Otherwise the dependencies in that configuration file will not get resolved properly and cause other issues.

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)

Kernel doesn't even boot

  • Check the output of the bootloader with a serial cable if you have one.
    • Making such a kernel 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
  • 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.

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.

See also