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

7 Created: 2019-06-20
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.
94   Format the NOR as it is currently done for a system that supports UBI: a fixed
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.
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
128   small FS is placed at the beginning of the partition to contain any artifacts
129   that must be accessed by U-Boot.
131   This file system will be selected from ext2, FAT12, and cramfs, as these are
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
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
151   needed, partition 1 can remain unallocated.
155   The read-write filesystem occupies partition 4.
157   If in the future there is demand for additional partitions, partition can be
158   moved into an extended partition in a future code update.
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:
167   - Volume management: LVM. This allows for dynamic partition/removal, similar
170     able to resize the partition if needed. In addition, UBI volume management
174   - Partitioning: If the eMMC is used to store the boot loader, a ext4 (or vfat)
175     partition would hold the FIT image containing the kernel, initrd and device
176     tree. This volume would be mounted as /boot. This allows U-Boot to load the
177     kernel since it doesn't have support for LVM. After the boot partition,
179     logical volumes, instead of fixed-size partitions. This provides flexibility
180     for cases where the contents of a partition outgrow a fixed size. This also
184   - Initramfs: Use an initramfs, which is the default in OpenBMC, to boot the
189     rootfs volume to be mounted, instead of using the U-Boot environments.
191   - Mount points: For firmware images such as BIOS that currently reside in
196   - Provisioning: Since the LVM userspace tools don't offer an offline mode,
199     file into tmpfs from an external source to flash the volume. The rootfs file
202     build process to setup the LVM volume and create the image file.
209 - openbmc/linux: Kernel changes to support the eMMC chip and its filesystem.
210 - openbmc/openbmc: Changes to create an eMMC image.
211 - openbmc/openpower-pnor-code-mgmt: Changes to support updating the new
213 - openbmc/phosphor-bmc-code-mgmt: Changes to support updating the new
218 Verify OpenBMC functionality in a system containing an eMMC. This system could
221 [pre-init script]:
222 …https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/preinit-mounts/prein…