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

7 Created: 2019-06-20
18 based on AST2400 and AST2500, but there is no design for managed NAND.
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
63   mount can be used. On the other hand, the /etc directory has content delivered
65   configuration content on a factory reset.
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.
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
117   and data in the filesystem, and therefore provides stronger guarantees on the
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
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
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:
167   - Volume management: LVM. This allows for dynamic partition/removal, similar
174   - Partitioning: If the eMMC is used to store the boot loader, a ext4 (or vfat)
176     tree. This volume would be mounted as /boot. This allows U-Boot to load the
179     logical volumes, instead of fixed-size partitions. This provides flexibility
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
193     the same paths as to prevent changes to the applications that rely on the
196   - Provisioning: Since the LVM userspace tools don't offer an offline mode,
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
221 [pre-init script]:
222 …https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/preinit-mounts/prein…