architecture/code-update/emmc-storage-design.md

7 Created: 2019-06-20
12 filesystem type, partitioning, volume management, boot options and
22 - Security: Ability to enforce read-only, verification of official/signed images
25 - Updatable: Ensure that the filesystem design allows for an effective and
28 - Simplicity: Make the system easy to understand, so that it is easy to develop,
31 - Code reuse: Try to use something that already exists instead of re-inventing
36 - The eMMC image layout and characteristics are specified in a meta layer. This
41 - Code update: Support two versions on flash. This allows a known good image to
44 - GPT partitioning for the eMMC User Data Area: This is chosen over dynamic
48 - Initramfs: An initramfs is needed to run sgdisk on first boot to move the
54 - Read-only and read-write filesystem: ext4. This is a stable and widely used
57 - Filesystem layout: The root filesystem is hosted in a read-only volume. The
58   /var directory is mounted in a read-write volume that persists through code
60   ssh keys, so it is a bind mount to a directory in the read-write volume. A
67         +------------------+ +-----------------------------+
68         | Read-only volume | | Read-write volume           |
69         |------------------| |-----------------------------|
73         | /etc  +------------->/var/etc-work/  (overlayfs) |
75         | /home +------------->/var/home-work/ (bind mount)|
78         +------------------+ +-----------------------------+
80 - Provisioning: OpenBMC will produce as a build artifact a flashable eMMC image
85 - Store U-Boot and the Linux kernel in a separate SPI NOR flash device, since
86   SOCs such as the AST2500 do not support executing U-Boot from an eMMC. In
87   addition, having the Linux kernel on the NOR saves from requiring U-Boot
88   support for the eMMC. The U-Boot and kernel are less than 10MB in size, so a
92   U-Boot or the kernel failed to run.
95   MTD partition for U-Boot, one for its environment, and a UBI volume spanning
97   partition. This approach allows the re-use of the existing code update
100   existing U-Boot environment approach.
102   Static MTD partitions could be created to store the kernel images, but
107   The AST2600 supports executing U-Boot from the eMMC, so that provides the
108   flexibility of just having the eMMC chip on a system, or still have U-Boot in
111 - Filesystem: f2fs (Flash-Friendly File System). The f2fs is an up-and-coming
120 - All Code update artifacts combined into a single image.
123   works or not, with no additional fragments lying around. U-Boot has one choice
124   to make - which image to load, and one piece of information to forward to the
127   To reduce boot time by limiting IO reading unneeded sectors into memory, a
129   that must be accessed by U-Boot.
132   all supported in both the Linux kernel and U-Boot. (If we desire the U-Boot
133   environment to be per-side, then choose one of ext2 or FAT12 (squashfs support
134   has not been merged, it was last updated in 2018 -- two years ago).
136 - No initramfs: It may be possible to boot the rootfs by passing the UUID of the
137   logical volume to the kernel, although a [pre-init script][] will likely still
141 - FAT MBR partitioning: FAT is a simple and well understood partition table
142   format. There is space for 4 independent partitions. Alternatively one slot
143   can be chained into extended partitions, but each partition in the chan
144   depends on the prior partition. Four partitions may be sufficient to meet the
145   initial demand for a shared (single) boot filesystem design (boot, rofs-a,
146   rofs-b, and read-write). Additional partitions would be needed for a dual boot
149   If common space is needed for the U-Boot environment, is is redundantly stored
150   as file in partition 1. The U-Boot SPL will be located here. If this is not
155   The read-write filesystem occupies partition 4.
157   If in the future there is demand for additional partitions, partition can be
160 - Device Mapper: The eMMC is divided using the device-mapper linear target,
162   physically repartition since the device-mapper devices expose logical blocks.
163   This is achieved by changing the device-mapper configuration table entries
166 - Logical Volumes:
168   - Volume management: LVM. This allows for dynamic partition/removal, similar
175   - Partitioning: If the eMMC is used to store the boot loader, a ext4 (or vfat)
177     tree. This volume would be mounted as /boot. This allows U-Boot to load the
178     kernel since it doesn't have support for LVM. After the boot partition,
180     logical volumes, instead of fixed-size partitions. This provides flexibility
185   - Initramfs: Use an initramfs, which is the default in OpenBMC, to boot the
187     additional boot actions are needed, such as mounting overlays. It also
189     volume(s). To boot the rootfs, the initramfs would search for the desired
190     rootfs volume to be mounted, instead of using the U-Boot environments.
192   - Mount points: For firmware images such as BIOS that currently reside in
197   - Provisioning: Since the LVM userspace tools don't offer an offline mode,
210 - openbmc/linux: Kernel changes to support the eMMC chip and its filesystem.
211 - openbmc/openbmc: Changes to create an eMMC image.
212 - openbmc/openpower-pnor-code-mgmt: Changes to support updating the new
214 - openbmc/phosphor-bmc-code-mgmt: Changes to support updating the new
222 [pre-init script]:
223 …https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/preinit-mounts/prein…