Jump to content

Initramfs/Inspecting: Difference between revisions

From postmarketOS Wiki
Samcday (talk | contribs)
Update nc tutorial with archive.org link
Jakko (talk | contribs)
It was supposed to be "Volume Down" for the initramfs debug shell, even though it's buggy (issue pmaports#3627).
Tag: Manual revert
 
(7 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{note|This is considered a '''security hole'''. Only use it for debugging, and uninstall the debug-shell hook afterwards.}}
{{subpages|Initramfs}}
{{note|TODO: add description about <code>pmbootstrap initfs hooks_ls</code>}}
 
This page explains how to connect to your device when it has booted to the [[Initramfs-development|initramfs]] by installing the '''debug-shell''' hook. 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.
This page explains how to connect to your device when it has booted to the [[Initramfs-development|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 ===
=== Enable the debug shell ===


For devices that the kernel is flashed separately do the following:
The debug shell can be enabled by adding <code>pmos.debug-shell</code> to the kernel cmdline, or by holding {{button|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 {{button|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 <code>boot.img</code>, this can be done by adding <code>deviceinfo_kernel_cmdline="pmos.debug-shell"</code> (or editing the existing option) to the deviceinfo file in pmaports and running <code>pmbootstrap flasher boot</code>.
 
For devices booting with GRUB or systemd-boot, hold {{button|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 <code>pmbootstrap chroot -r</code> [[Installation/Using_pmbootstrap|after building an image]], edit <code>/etc/deviceinfo</code>, uncomment <code>deviceinfo_kernel_cmdline_append</code> and add <code>pmos.debug-shell</code>, it should look something like the following:
 
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap initfs hook_add debug-shell
/ # cat /etc/deviceinfo
$ pmbootstrap flasher flash_kernel # or however you flash/boot the kernel
# 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"
</syntaxhighlight>
</syntaxhighlight>


If you only need to flash <code>rootfs</code> for your device (e.g. you use <code>lk2nd</code>) do the following instead:
Make sure you run <code>mkinitfs</code> 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 <code>sudo dmesg -w</code> on your host PC and look for the most recently appeared '''ttyACM''' device, likely '''ttyACM0''', then connect as follows:
 
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap install --add postmarketos-mkinitfs-hook-debug-shell
$ picocom -b 115200 /dev/ttyACM0
$ pmbootstrap flasher flash_rootfs
 
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.
</syntaxhighlight>
</syntaxhighlight>


=== Using the debug shell ===
You may also connect via telnet:
 
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ telnet 172.16.42.1
$ telnet 172.16.42.1
Line 24: Line 55:
Escape character is '^]'.
Escape character is '^]'.


Type 'pmos_continue_boot' to continue booting:
 
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.
</syntaxhighlight>
</syntaxhighlight>


If the telnet command does not work out of the box, read [[connect via USB Networking in the Initramfs]].
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 <code>evtest</code>, <code>fftest</code> and <code>fbdebug</code> are available (see {{MR|1358}}).
In the debug shell, the additional programs <code>evtest</code>, <code>fftest</code> and <code>fbdebug</code> can be made available by also installing the debug-shell hook (the <code>postmarketos-mkinitfs-hook-debug-shell</code> package) (see {{MR|1358}}).


To step through the boot process, you can execute commands in order listed in [https://gitlab.com/postmarketOS/pmaports/-/blob/master/main/postmarketos-initramfs/init.sh postmarketos-initramfs/init.sh], starting with the line <code>mount_boot_partition /boot</code> and below (everything above it was already executed before entering debug-shell).
To step through the boot process, you can execute commands in order listed in [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/blob/master/main/postmarketos-initramfs/init.sh postmarketos-initramfs/init.sh], starting with the line <code>mount_subpartitions</code> 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 <code>pmos_continue_boot</code> command. This will close the telnet connection and continue the boot process.
To continue the boot process as normal, run the <code>pmos_continue_boot</code> command. This will close the telnet connection and continue the boot process.
Line 40: Line 80:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
# . /usr/share/misc/source_deviceinfo
# . /usr/share/misc/source_deviceinfo
# . /init_functions.sh
# mount_boot_partition /boot
# mount_boot_partition /boot
Mount boot partition (/dev/dm-0)
Mount boot partition (/dev/dm-0)
Line 50: Line 89:
=== Disable the debug shell ===
=== Disable the debug shell ===


For devices that flash the kernel partition separately:
If you added the debug-shell hook and are rebuilding the initramfs on your PC, uninstall it with


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
Line 57: Line 96:
</syntaxhighlight>
</syntaxhighlight>


For devices that only need to flash the <code>rootfs</code> re-run <code>pmbootstrap install</code> without adding the <code>postmarketos-mkinitfs-hook-debug-shell</code> package.
Otherwise, simply remove the <code>pmos.debug-shell</code> argument from your kernel cmdline.


=== Tips and tricks ===
=== Tips and tricks ===

Latest revision as of 10:48, 30 March 2025

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