Jump to content

Initramfs: Difference between revisions

From postmarketOS Wiki
Exkc (talk | contribs)
No edit summary
Update with new boot flow following pma!5636
Line 1: Line 1:
[https://gitlab.com/postmarketOS/pmaports/-/tree/master/main/postmarketos-initramfs Initramfs] consists of busybox, a shell script and very few other command-line programs.  
[https://gitlab.com/postmarketOS/pmaports/-/tree/master/main/postmarketos-initramfs Initramfs] consists of busybox, a shell script and very few other command-line programs.  


[https://gitlab.com/postmarketOS/postmarketos-mkinitfs postmarketos-mkinitfs] generates the initramfs .
[https://gitlab.com/postmarketOS/postmarketos-mkinitfs postmarketos-mkinitfs] generates the initramfs.


After then , postmarketos-mkinitfs would run [https://gitlab.com/postmarketOS/boot-deploy boot-deploy] and boot-deploy would pack kernel and initramfs into a suitable format  and generate config for the bootloader if necessary.
After then, postmarketos-mkinitfs would run [https://gitlab.com/postmarketOS/boot-deploy boot-deploy] and boot-deploy would pack kernel and initramfs into a suitable format  and generate config for the bootloader if necessary. Some devices with small boot partitions may need to generate an <code>initramfs-extra</code> by setting <code>deviceinfo_create_initfs_extra=true</code>.


The initramfs takes care of many things during the early booting phase, such as setting up [[USB Network|USB networking]], resizing the root partition. Some of the tasks are listed in detail here, for others refer to the source code for now and consider expanding this article. Furthermore, the initramfs supports hooks (which may be used to work around device specific quirks, for example).
The initramfs takes care of many things during the early booting phase, such as setting up [[USB Network|USB networking]], resizing the root partition on first boot, unlocking the root filesystem if full disk encryption is enabled, and more. Some of the tasks are listed in detail here, for others refer to the source code for now and consider expanding this article. Furthermore, the initramfs supports hooks, which may be used to work around device specific quirks, for example.


Here is a list of the boot process related to initramfs:
Here is a list of the boot process related to initramfs:


* Enable <code>set -x</code> if the verbose-initfs hook exists
* Load device config from the deviceinfo file
* Load deviceinfo data
* Initialize busybox
* Create busybox symlinks
* Mount /dev, /proc, and /sys
* Mount <code>/dev</code>, <code>/proc</code> and <code>/sys</code>
* Configure logging
* Redirect stdout to <code>/pmOS_init.log</code> and to the kernel log (dmesg)
* Enable USB networking support for debug in the initramfs, if applicable
* Modprobe modules listed in deviceinfo
 
* Enable mdev (busybox replacement for udev)
If the device is using an <code>initramfs-extra</code>, then the initramfs will:
* Map subpartitions to block device
 
* Wait for /dev/fb0 to appear (if not disabled in deviceinfo) and set the framebuffer mode
* Attempt to mount any subpartitions that exist
* Execute hooks
* Detect and mount the postmarketOS boot partition and extract the archive
* Show loading splash
* Run mdev to detect/initialize devices
* Start usb networking
* Execute <code>jump_init_2nd</code> to continue booting with the steps below as if it were using a single unified initramfs
* Find and mount the partition with the <code>pmOS_boot</code> label if not show "Boot partition not found" splash
 
* Unpack initramfs-extra from the boot partition if not show  "Initramfs-extra not found" splash
If the device is using a single unified initramfs archive, then:
* Search for a partition with the label <code>pmOS_root</code>
 
* Try to resize the partition containing the root filesystem to the maximum size
* Run hooks
* Start  [[Unl0kr]] if the rootfs is a luks partition
* Launch debug shell if key combo is used
* Resize the root filesystem to match the partition it is in
* Find, unlock(if necessary), and mount the postmarketOS root partition. This may also run fsck on filesystems
* Mount the root filesystem
* Run cleanup hooks
* Kill all processes running in the initramfs and pivot root to the real rootfs
* Switch to the root filesystem, exiting the initramfs, and continue booting the OS


=== Find the boot and root partitions ===
=== Find the boot and root partitions ===
Line 43: Line 43:


=== Load initramfs-extra ===
=== Load initramfs-extra ===
Some Android devices require a very small initramfs, because otherwise the resulting <code>boot.img</code> file is too big for the Android boot partition. Therefore, we have split the initramfs into two parts, the tiny initramfs that is potentially placed in such a <code>boot.img</code> file (depending on the bootloader). And the initramfs-extra, which can hold bigger binaries, such as the UI to unlock an encrypted root partition ([[Unl0kr]]).
Some Android devices require a very small initramfs, because otherwise the resulting <code>boot.img</code> file is too big for the Android boot partition. Therefore, it's possible to split the initramfs into two parts, the tiny initramfs that is potentially placed in such a <code>boot.img</code> file (depending on the bootloader). And the initramfs-extra, which can hold bigger binaries, such as the UI to unlock an encrypted root partition ([[Unl0kr]]). mkinitfs can be instructed to split the archive by setting the <code>deviceinfo_create_initfs_extra</code>


=== Switch root ===
=== Switch root ===

Revision as of 16:16, 31 October 2024

Initramfs consists of busybox, a shell script and very few other command-line programs.

postmarketos-mkinitfs generates the initramfs.

After then, postmarketos-mkinitfs would run boot-deploy and boot-deploy would pack kernel and initramfs into a suitable format and generate config for the bootloader if necessary. Some devices with small boot partitions may need to generate an initramfs-extra by setting deviceinfo_create_initfs_extra=true.

The initramfs takes care of many things during the early booting phase, such as setting up USB networking, resizing the root partition on first boot, unlocking the root filesystem if full disk encryption is enabled, and more. Some of the tasks are listed in detail here, for others refer to the source code for now and consider expanding this article. Furthermore, the initramfs supports hooks, which may be used to work around device specific quirks, for example.

Here is a list of the boot process related to initramfs:

  • Load device config from the deviceinfo file
  • Initialize busybox
  • Mount /dev, /proc, and /sys
  • Configure logging
  • Enable USB networking support for debug in the initramfs, if applicable

If the device is using an initramfs-extra, then the initramfs will:

  • Attempt to mount any subpartitions that exist
  • Detect and mount the postmarketOS boot partition and extract the archive
  • Run mdev to detect/initialize devices
  • Execute jump_init_2nd to continue booting with the steps below as if it were using a single unified initramfs

If the device is using a single unified initramfs archive, then:

  • Run hooks
  • Launch debug shell if key combo is used
  • Find, unlock(if necessary), and mount the postmarketOS root partition. This may also run fsck on filesystems
  • Run cleanup hooks
  • Switch to the root filesystem, exiting the initramfs, and continue booting the OS

Find the boot and root partitions

Due to the various possible partition layouts, the initramfs script has to look in various places for the postmarketOS boot and root partitions.

boot partition:

  • pmos_boot kernel parameter (from the device specific bootloader)
  • Any partition or subpartition with the pmOS_boot label

root partition:

  • pmos_root kernel parameter (from the device specific bootloader)
  • Any partition or subpartition with the pmOS_root label
  • Any partition or subpartition that is encrypted

Load initramfs-extra

Some Android devices require a very small initramfs, because otherwise the resulting boot.img file is too big for the Android boot partition. Therefore, it's possible to split the initramfs into two parts, the tiny initramfs that is potentially placed in such a boot.img file (depending on the bootloader). And the initramfs-extra, which can hold bigger binaries, such as the UI to unlock an encrypted root partition (Unl0kr). mkinitfs can be instructed to split the archive by setting the deviceinfo_create_initfs_extra

Switch root

Note It will look like this, once pmaports#664 is resolved.

At the end of the initramfs script, the root partition is mounted at /sysroot, and the boot partition is mounted at /sysroot/boot. The latter is done, so Init does not need to figure out the correct boot partition later on. Afterwards, the busybox command switch_root is called to switch over and pass control to Init.

See also

Internal pages