Jump to content

Partition Layout: Difference between revisions

From postmarketOS Wiki
Exkc (talk | contribs)
No edit summary
 
(46 intermediate revisions by 11 users not shown)
Line 1: Line 1:
=== General partition layout (installation image) ===
{{note|this article is about pmOS partition infrastructure and has little to do with Android Partition layout. For the latter, see [https://source.android.com/docs/core/architecture/partitions the Android documentation] and the wiki pages for [[Android AB Slots]] and [[Android_dynamic_partitions]].}}
{{note|The postmarketOS initramfs detects the partitions by their partition label.}}
<pre class="shell">/dev/installp1 # label: pmOS_boot (contains kernel, initramfs, initramfs-extra)
/dev/installp2 # label: pmOS_root (encrypted, unless --no-fde is specified)</pre>


=== SD card ===


This is the least awkward layout - both partitions from above get directly created on the SD card. If your device has a sdcard slot, it is recommended to use it. Because then you don't wear down the internal flash storage of the device and don't need to worry about the phone's internal storage partition layout.


Usage:
A postmarketOS installation consists of two partitions, the boot and the root partition. This distinction was made to support FDE (full disk encryption). With FDE, the entire root partition gets encrypted, and the only non-encrypted part remains the boot partition (which does not hold any personal data).


<pre class="shell">$ ./pmbootstrap.py install --sdcard /dev/mmcblkX</pre>
<syntaxhighlight lang="shell">
=== Android internal storage ===
p1 # label: pmOS_boot (boot partition which contains kernel, initramfs, initramfs-extra)
p2 # label: pmOS_root (root partition which contains everything else, can be encrypted)
</syntaxhighlight>


We don't want to modify the partition layout on the internal storage of Android systems. Because this seems somewhat risky, and then users couldn't simply install another ROM such as LineageOS anymore. So we came up with the following:
Due to the wide range of devices we support, there are a few variations of where these partitions will be exactly after installing postmarketOS.


The Android internal storage is already partitioned - the layout seems to be different for every device, as well as the numbers they have assigned. But most notably the devices have the following partitions:
=== Use the whole storage device ===
{{note| pmOS_boot and pmOS_root has to be labeled in the file system. The postmarketOS initramfs checks those partiton label via file system, not the gpt partition table.Also boot-deloy would specify the uuid of those partition via boot flag if the uuid of those partition is specified in <code>/etc/fstab</code>.If the uuid of those partition is specified via boot flag , the postmarketOS initramfs  would check the uuid instead of the label.}}
Both partitions are directly written to the storage device (SD card, eMMC, ...), for example <code>/dev/mmcblk0p1</code> and <code>/dev/mmcblk0p2</code>.


<pre>boot
This is always done with SD cards. With the eMMC (internal storage), this is only done if it the factory OS can be flashed back without relying on a specific partitioning layout. (This is not possible with Android, see [[#Subpartitions|subpartitions]] below.)
system
userdata</pre>
We usually flash a <code>boot.img</code> file (which is the kernel + initramfs) to Android's <code>boot</code> partition (see also: [[deviceinfo_flash_methods]]) - because that is what works and what all other ROMs do. Now the interesting part is the system partition, where we flash our installation image. But the installation image already has a partition layout and own partitions! So you will have '''subpartitions'''. In the end, it will look like this:


<pre class="shell">systemp1 # pmOS boot partition, only initramfs-extra gets used from there
A typical SD card installation:
systemp2 # pmOS (un)encrypted root filesystem</pre>
<syntaxhighlight lang="shell-session">
The initramfs (in the <code>boot.img</code> file!) will automatically find and mount the pmOS boot and root partition, load the <code>initramfs-extra</code> (which contains additional files, it was split to save space) and take care of booting through until [https://github.com/postmarketOS/pmbootstrap/wiki/Glossary#openrc OpenRC] takes over.
$ pmbootstrap init
$ pmbootstrap install --sdcard=/dev/path-to-sdcard-device
</syntaxhighlight>


The <code>userdata</code> partition is not used yet (proposal to do that is in [https://github.com/postmarketOS/pmbootstrap/issues/60 #60]). But as we are pretty flexible, you can also flash pmOS to the <code>userdata</code> partition, if it has more space and you can't fit it on the <code>system</code> partition. The initramfs will detect it anyway. Just make sure, that you don't have it flashed to ''both'' partitions!<br />
A typical eMMC installation (you would flash the resulting image with a tool like [https://wiki.pine64.org/index.php/PinePhone#Flashing_eMMC_using_Jumpdrive Jumpdrive]):
To flash to the <code>userdata</code> partition instead of the <code>system</code> partition, use <code>pmbootstrap flasher flash_system --partition=USERDATA</code>.
<syntaxhighlight lang="shell-session">
$ pmbootstrap init
$ pmbootstrap install
$ pmbootstrap export  # create a symlink to the rootfs image file for further usage
</syntaxhighlight>


=== Future ideas ===
=== Subpartitions ===


{{note|See also: Allow booting from an image file (/data/postmarketOS.img) instead of flashing to a partition ({{github|953}})}}
Android (and other factory OS) require a specific partition layout. In order to make it feasible for the user to switch back to Android on their device, we install postmarketOS only into an existing partition.
For example, a typical Android installation consists of (see also [https://source.android.com/docs/core/architecture/partitions the Android docs]):
* boot
* system
* userdata
* (more partitions with firmware etc.)


There might be scenarios, in which the partition type of the <code>system</code> partition can not be changed through the flasher, because it only allows [https://en.wikipedia.org/wiki/YAFFS2 yaffs2] or simg with ext4 support (during research for the mozilla flame, we found that to be the case ([https://github.com/postmarketOS/pmbootstrap/issues/299 #299]) - however, it also has an SD slot, so we did not continue this way ([https://github.com/postmarketOS/pmbootstrap/issues/337 #337])).


A proposal we have for that case, is to have one big ext4/yaffs partition, and include the whole system image file inside that. Then we would adjust the initramfs code to find the boot and root partitions inside that, and teach it how to resize the whole thing to the maximum partition size. We already did some experiments, and so far everything worked (talk to drebrez or ollieparanoid).
{{note|As of now , pmOS only support subpartition on  the system* (Any partition that has prefix of system like system_a system_b system) partition or userdata partition.Also system* and userdata has to be labeled in the gpt partition table. The postmarketOS initramfs checks those partiton label via  gpt partition table , not the file system. }}
{{note|system* partition partition doesn't have to be traditional partition.they also can be [[Android dynamic partitions]].pmOS would map those Android dynamic partitions into  block device druing boot}}
 
Therefore ,  pmOS would have to split that partition into 2 two Subpartitions :
*  Subpartition 1 : Labeled at pmOS_boot which is the boot partition
*  Subpartition 2 : Labeled at pmOS_root which is the root partition
 
 
 
Example:
<syntaxhighlight lang="shell-session">
$ pmbootstrap init
$ pmbootstrap install
$ pmbootstrap flasher flash_kernel
$ pmbootstrap flasher flash_rootfs
</syntaxhighlight>
 
That the <code>flash_kernel</code> command fills Android's boot partition with a boot.img file, that consists of the Linux kernel and initramfs from postmarketOS. The files are duplicated on the postmarketOS boot partition, but not used from there (due to usually android bootloader only boot boot.ing from the Android's boot partition)Some Android devices have a strict size limit for this boot.img file, which is why we load additional files from the initramfs-extra file from the postmarketOS boot partition.
 
That the <code>flash_kernel</code> command fills system* partition or userdata partition with pmOS 's Subpartitions.
 
=== Stowaway  ===
It is a way to storage pmOS in a folder that is in the phone's data partition.
 
 
 
==== Pick a different subpartition ====
While on some devices, the system partition is bigger than the userdata partition, it is the other way around on others. So it is possible to switch to the userdata partition with <code>pmbootstrap flasher flash_rootfs --partition userdata</code>. To clear a previous postmarketOS installation from the system partition, use <code>fastboot format system</code> (otherwise, the initramfs may boot into the wrong installation!).
 
=== On-device installer ===
The on-device installer starts with three partitions (boot, reserved space, installer). It installs postmarketOS into the reserved space, and removes the third partition, so in the end it looks like the regular boot and root partition layout. Details are in the [[on-device installer]] article.
== See also ==
* [[Boot process]], in particular how the partitions for boot and root are determined
* {{issue|953}}: idea to boot from an image file (did not go anywhere, open a new issue if you are interested in implementing this)
* [[deviceinfo_flash_methods|Deviceinfo: flash methods]]
* [[Dual Booting/WiP #Stowaway]]
* [[Android dynamic partitions]]
[[Category:Technical Reference]]
__NOTOC__

Latest revision as of 09:52, 9 October 2024

Note this article is about pmOS partition infrastructure and has little to do with Android Partition layout. For the latter, see the Android documentation and the wiki pages for Android AB Slots and Android_dynamic_partitions.


A postmarketOS installation consists of two partitions, the boot and the root partition. This distinction was made to support FDE (full disk encryption). With FDE, the entire root partition gets encrypted, and the only non-encrypted part remains the boot partition (which does not hold any personal data).

p1 # label: pmOS_boot (boot partition which contains kernel, initramfs, initramfs-extra)
p2 # label: pmOS_root (root partition which contains everything else, can be encrypted)

Due to the wide range of devices we support, there are a few variations of where these partitions will be exactly after installing postmarketOS.

Use the whole storage device

Note pmOS_boot and pmOS_root has to be labeled in the file system. The postmarketOS initramfs checks those partiton label via file system, not the gpt partition table.Also boot-deloy would specify the uuid of those partition via boot flag if the uuid of those partition is specified in /etc/fstab.If the uuid of those partition is specified via boot flag , the postmarketOS initramfs would check the uuid instead of the label.

Both partitions are directly written to the storage device (SD card, eMMC, ...), for example /dev/mmcblk0p1 and /dev/mmcblk0p2.

This is always done with SD cards. With the eMMC (internal storage), this is only done if it the factory OS can be flashed back without relying on a specific partitioning layout. (This is not possible with Android, see subpartitions below.)

A typical SD card installation:

$ pmbootstrap init
$ pmbootstrap install --sdcard=/dev/path-to-sdcard-device

A typical eMMC installation (you would flash the resulting image with a tool like Jumpdrive):

$ pmbootstrap init
$ pmbootstrap install
$ pmbootstrap export  # create a symlink to the rootfs image file for further usage

Subpartitions

Android (and other factory OS) require a specific partition layout. In order to make it feasible for the user to switch back to Android on their device, we install postmarketOS only into an existing partition. For example, a typical Android installation consists of (see also the Android docs):

  • boot
  • system
  • userdata
  • (more partitions with firmware etc.)


Note As of now , pmOS only support subpartition on the system* (Any partition that has prefix of system like system_a system_b system) partition or userdata partition.Also system* and userdata has to be labeled in the gpt partition table. The postmarketOS initramfs checks those partiton label via gpt partition table , not the file system.
Note system* partition partition doesn't have to be traditional partition.they also can be Android dynamic partitions.pmOS would map those Android dynamic partitions into block device druing boot

Therefore , pmOS would have to split that partition into 2 two Subpartitions :

  • Subpartition 1 : Labeled at pmOS_boot which is the boot partition
  • Subpartition 2 : Labeled at pmOS_root which is the root partition


Example:

$ pmbootstrap init
$ pmbootstrap install
$ pmbootstrap flasher flash_kernel
$ pmbootstrap flasher flash_rootfs

That the flash_kernel command fills Android's boot partition with a boot.img file, that consists of the Linux kernel and initramfs from postmarketOS. The files are duplicated on the postmarketOS boot partition, but not used from there (due to usually android bootloader only boot boot.ing from the Android's boot partition)Some Android devices have a strict size limit for this boot.img file, which is why we load additional files from the initramfs-extra file from the postmarketOS boot partition.

That the flash_kernel command fills system* partition or userdata partition with pmOS 's Subpartitions.

Stowaway

It is a way to storage pmOS in a folder that is in the phone's data partition.


Pick a different subpartition

While on some devices, the system partition is bigger than the userdata partition, it is the other way around on others. So it is possible to switch to the userdata partition with pmbootstrap flasher flash_rootfs --partition userdata. To clear a previous postmarketOS installation from the system partition, use fastboot format system (otherwise, the initramfs may boot into the wrong installation!).

On-device installer

The on-device installer starts with three partitions (boot, reserved space, installer). It installs postmarketOS into the reserved space, and removes the third partition, so in the end it looks like the regular boot and root partition layout. Details are in the on-device installer article.

See also