Initramfs/Inspecting: Difference between revisions
To enable functionality from initramfs-extra, run the following commands in the shell |
Enabling initramfr debug shell seems to be button "Volume Up", not "Volume Down". |
||
(30 intermediate revisions by 21 users not shown) | |||
Line 1: | Line 1: | ||
{{ | {{subpages|Initramfs}} | ||
This page explains how to connect to your device when it has booted to the [[Initramfs-development|initramfs]] by | 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 === | |||
< | The debug shell can be enabled by adding <code>pmos.debug-shell</code> to the kernel cmdline, or by holding {{button|Volume Up}} 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"> | |||
/ # 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" | |||
</syntaxhighlight> | |||
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"> | |||
$ 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. | |||
</syntaxhighlight> | |||
You may also connect via telnet: | |||
<syntaxhighlight lang="shell-session"> | |||
$ telnet 172.16.42.1 | $ telnet 172.16.42.1 | ||
Trying 172.16.42.1... | Trying 172.16.42.1... | ||
Line 14: | Line 55: | ||
Escape character is '^]'. | 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. | |||
</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> 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.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. | |||
=== Enable initramfs-extra === | === Enable initramfs-extra === | ||
To enable functionality from initramfs-extra, run the following commands in the shell: | To enable functionality from <code>initramfs-extra</code>, run the following commands in the telnet shell: | ||
< | <syntaxhighlight lang="shell-session"> | ||
. | # . /usr/share/misc/source_deviceinfo | ||
mount_boot_partition | # mount_boot_partition /boot | ||
extract_initramfs_extra | Mount boot partition (/dev/dm-0) | ||
</ | # extract_initramfs_extra /boot/initramfs-extra | ||
Extract /boot/initramfs-extra | |||
24128 blocks | |||
</syntaxhighlight> | |||
=== Disable the debug shell === | |||
If you added the debug-shell hook and are rebuilding the initramfs on your PC, uninstall it with | |||
= | <syntaxhighlight lang="shell-session"> | ||
$ pmbootstrap initfs hook_del debug-shell | |||
$ pmbootstrap flasher flash_kernel | |||
</syntaxhighlight> | |||
Otherwise, simply remove the <code>pmos.debug-shell</code> argument from your kernel cmdline. | |||
=== Tips and tricks === | === Tips and tricks === | ||
* [ | * [[Initramfs development]] has more generalize information about working with initfs. | ||
* [https://web.archive.org/web/20230924150444/www.microhowto.info/howto/copy_a_file_from_one_machine_to_another_using_netcat.html copy files to/from the initramfs with <code>nc</code> while it is running] | |||
[[Category:Guide]] |
Latest revision as of 20:03, 13 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 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 , 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
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
nc
while it is running