Initramfs/Inspecting
This page explains how to connect to your device when it has booted to the initramfs by enabling the debug-shell. This is useful if you want to know more about the boot process, simply inspect the initramfs or if you want to debug why something doesn't work.
Enable the debug shell
The debug shell can be enabled by adding pmos.debug-shell to the kernel cmdline, or by holding Volume Down during boot. If using the button method, you must wait until after the device bootloader finishes and Linux has started booting (usually the display flickering or displaying the tux penguins is a good indicator of this). If using a device with a keyboard, you may also press Left ctrl, though this has been reported to be somewhat unreliable due to when the keyboard drivers load.
If your device doesn't boot yet, and you're building an Android boot.img, this can be done by adding deviceinfo_kernel_cmdline="pmos.debug-shell" (or editing the existing option) to the deviceinfo file in pmaports and running pmbootstrap flasher boot.
For devices booting with GRUB or systemd-boot, hold e during boot to get to a prompt to edit the cmdline.
For all devices
In the device rootfs (either on a shell on your real device, or via pmbootstrap chroot -r after building an image, edit /etc/deviceinfo, uncomment deviceinfo_kernel_cmdline_append and add pmos.debug-shell, it should look something like the following:
/ # cat /etc/deviceinfo
# Override settings from /usr/share/deviceinfo/deviceinfo with this file.
# After modifying: Some settings require running "mkinitfs" as root and/or
# a reboot to apply.
# Reference: https://postmarketos.org/deviceinfo
# Examples:
deviceinfo_kernel_cmdline_append="pmos.debug-shell PMOS_NOSPLASH"
# deviceinfo_usb_network_function="ncm.usb0"
Make sure you run mkinitfs after editing the file!
Using the debug shell
The debug shell will spawn a getty (an interactive shell) on all available/enabled consoles, if your device has a working USB port, it will also create a serial gadget device in addition to the usual network gadget. On Linux this can be accessed via any serial monitor, but picocom is suggested (it should be available via your package manager). Check sudo dmesg -w on your host PC and look for the most recently appeared ttyACM device, likely ttyACM0, then connect as follows:
$ picocom -b 115200 /dev/ttyACM0
postmarketOS debug shell
https://postmarketos.org/debug-shell
Device: QEMU amd64 (qemu-amd64)
Kernel: 6.9.5-0-edge
OS ver: edge
initrd: 3.1.0-r1
Run 'pmos_continue_boot' to continue booting.
You may also connect via telnet:
$ telnet 172.16.42.1
Trying 172.16.42.1...
Connected to 172.16.42.1.
Escape character is '^]'.
postmarketOS debug shell
https://postmarketos.org/debug-shell
Device: QEMU amd64 (qemu-amd64)
Kernel: 6.9.5-0-edge
OS ver: edge
initrd: 3.1.0-r1
Run 'pmos_continue_boot' to continue booting.
If the telnet command does not work out of the box, read connect via USB Networking in the Initramfs.
In the debug shell, the additional programs evtest, fftest and fbdebug can be made available by also installing the debug-shell hook (the postmarketos-mkinitfs-hook-debug-shell package) (see !1358).
To step through the boot process, you can execute commands in order listed in postmarketos-initramfs/init.sh, starting with the line mount_subpartitions and below (everything above it was already executed before entering debug-shell). Make sure the commands are available, see the first 2 commands in the next section.
To continue the boot process as normal, run the pmos_continue_boot command. This will close the telnet connection and continue the boot process.
Enable initramfs-extra
To enable functionality from initramfs-extra, run the following commands in the telnet shell:
# . /usr/share/misc/source_deviceinfo
# mount_boot_partition /boot
Mount boot partition (/dev/dm-0)
# extract_initramfs_extra /boot/initramfs-extra
Extract /boot/initramfs-extra
24128 blocks
Disable the debug shell
If you added the debug-shell hook and are rebuilding the initramfs on your PC, uninstall it with
$ pmbootstrap initfs hook_del debug-shell
$ pmbootstrap flasher flash_kernel
Otherwise, simply remove the pmos.debug-shell argument from your kernel cmdline.
Tips and tricks
- Initramfs development has more generalize information about working with initfs.
- copy files to/from the initramfs with
ncwhile it is running