Initramfs development

From postmarketOS
Revision as of 06:53, 7 December 2019 by Afontain (talk | contribs) (Mention that `mkinitfs` is a thing)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This article explains how to modify the postmarketOS initramfs scripts, for which the source can be found in the postmarketos-mkinitfs pmaport. There's another page about adding a device specific initramfs hook.

We have two initramfs files

After the installation, you will have two initramfs files in your device's /boot folder.

% ls ~/.local/var/pmbootstrap/chroot_rootfs_samsung-i9100/boot
initramfs-samsung-i9100  initramfs-samsung-i9100-extra  vmlinuz-samsung-i9100

Regular Linux distributions only have one initramfs file. We have split it into two to work around the size limitations, that some devices have. The regular initramfs is relatively small (~1.5 mb, and we could make it smaller if necessary!) and loads the contents of the initramfs-extra from the pmOS boot partition during the boot process.

The pmOS boot partition is a subpartition of the system partition (SD cards: simply a real partition on the SD card), so we can make it almost as big as we want.

Recommended development workflow

  • Only do one small change at a time
  • Rebuild and test on device (pmbootstrap initfs, pmbootstrap flasher flash_kernel)
  • When it works, version your change with git
  • Repeat

When you change too much, it will simply not work and you most likely will have no idea why it does not work. Go back to the last working version and do smaller changes at a time.

Regenerating the two initramfs from the phone

You can regenerate both initramfs, even if the first is in a boot.img by running as root

 mkinitfs -o /boot/initramfs-your-device

Tips and tricks

% pmbootstrap initfs --help
usage: pmbootstrap initfs [-h]
                          {hook_ls,hook_add,hook_del,ls,build,extract} ...

positional arguments:
  {hook_ls,hook_add,hook_del,ls,build,extract}
    hook_ls             list available and installed hook packages
    hook_add            add a hook package
    hook_del            uninstall a hook package
    ls                  list initramfs contents
    build               (re)build the initramfs
    extract             extract the initramfs to a temporary folder

optional arguments:
  -h, --help            show this help message and exit

Troubleshooting

My device reboots with my customized init script

This is probably caused by a syntax error. Use shellcheck to check your scripts for syntax errors. You could also loop forever or spawn a shell (if you have a hardware keyboard or serial cable connected) at some point for debugging (while true; do sleep 1; done) and use the telnet shell to test the commands, that are failing, interactively.

No log output on serial!

By default, all output from the initramfs get redirected to /pmOS_init.log. If you want the output through the debug cable you need to add PMOS_NO_OUTPUT_REDIRECT to your kernel command line.