1# OpenBMC Flash Layout and Filesystem Documentation 2 3This file is focused on providing information about the flash setup that the 4code update application requires to be supported out-of-the-box, which includes 5how the Linux filesystem is setup, filesystem layouts, overlays, boot options, 6and how code update updates the flash modules and boots the new image. See 7[code-update.md](code-update.md) for details about code update interfaces. 8 9## Design considerations 10 11### Boot loading and init 12 13For system initialization and bootstrap, [Das U-Boot][] was selected as the 14bootloader. 15 16After basic initialization of the system, the bootloader may present a prompt 17and/or start automatic boot. The commands and/or data to select the boot image 18are stored in the bootloader environment. The bootloader copies the compressed 19kernel, initrd image, and device tree into memory, and then transfers control to 20the kernel. The kernel initializes itself and the system using the information 21passed in the device tree, including the flash partitions and the kernel command 22line embedded in the tree. 23 24### Runtime management 25 26For runtime management, the [systemd][] system and service manager was chosen 27for its configuration, dependency, and triggered action support, as well as its 28robust recovery. 29 30Before starting execution, systemd requires the root filesystem and all binaries 31to be mounted. The filesystems for /dev, /sys, and /proc may be mounted before 32starting systemd. Reference the [systemd File Hierarchy Requirements][]. 33 34### Root filesystem 35 36For storage of the root filesystem, a read-only volume was selected. This allows 37the majority of the filesystem content, including all executables and static 38data files, to be stored in a read-only filesystem image. Replacing read-only 39filesystem images allows the space used by the content to be confirmed at build 40time and allows the selection of compressed filesystems that do not support 41mutations. 42 43An effort has been made to adhere to the Filesystem Hierarchy Standard [FHS][]. 44Specifically data ephemeral to the current boot is stored in /run and most 45application data is stored under /var. Some information continues to be stored 46in the system configuration data directory /etc; this is mostly traditionally 47configuration such as network addresses, user identification, and ssh host keys. 48 49To conserve flash space, squashfs with xz compression was selected to store the 50read-only filesystem content. This applies to systems with limited attached 51flash storage (see the JFFS2 and UBI options below), not eMMC. 52 53To load the root filesystem, the initramfs locates and mounts the squashfs and 54writable filesystems, merges them with overlayfs, performs a chroot into the 55result and starts systemd. Alternatively, information to find the active image 56for the BMC can be stored in the U-Boot environment, and an init script can 57mount the images then start systemd. This choice depends on the platform 58implementation, and details are located in the Supported Filesystem Choices 59section below. 60 61## Supported Filesystem Choices 62 63OpenBMC supports code update for the following types of filesystems. Additional 64information is given for each filesystem such as how the filesystem is stored on 65flash, how the filesystem is instantiated during system boot/init, and how code 66update handles the filesystem. 67 68### Writable Filesystem Options 69 70#### JFFS2 on MTD partition 71 72The majority of the filesystem is stored in a read-only squashfs in an MTD 73partition using the block emulation driver (mtdblock). A second MTD partition is 74mounted read-write using the JFFS2 filesystem. This read-write filesystem is 75mounted over the entire filesystem space allowing all files and directories to 76be written. 77 78This filesystem stack requires the mounts to be performed from an initramfs. The 79initramfs is composed of a basic system based on busybox and three custom 80scripts (init, shutdown, and update) that locate the MTD partitions by name. 81These scripts are installed by [obmc-phosphor-initfs][]. 82 83In code update mode, the squashfs image and white-listed files from the 84read-write filesystem are copied into RAM by the initramfs and used to assemble 85the root overlayfs instance, leaving the flash free to be modified by installing 86images at runtime. An orderly shutdown writes remaining images to like-named raw 87MTD partitions and white listed files to the writable overlay filesystem. 88Alternatively, if code update mode was not selected, the image updates must be 89delayed until the partitions are unmounted during an orderly shutdown. 90 91This is the default filesystem in OpenBMC. It is used in several BMC systems 92based around the AST2400 and AST2500 system-on-chip controllers from Aspeed 93Technology. These SOCs support 1 and 2 GB of DDR RAM, while the attached flash 94storage is typically in the 10s of MB, so staging the filesystem to RAM is not 95an issue. 96 97#### UBI on MTD partition 98 99The majority of the filesystem is stored in a read-only squashfs in a static UBI 100volume using the UBI block emulation driver (ubiblock). To store updates to 101files, a UBIFS volume is used for /var and mounted over the /etc and /home 102directories using overlayfs. These mounts are performed by the `init` script 103installed by the [preinit-mounts][] package before `systemd` is started. 104Selecting UBI allows the writes to the read-write overlay to be distributed over 105the full UBI area instead of just the read-write MTD partition. 106 107The environment for Das U-boot continues to be stored at fixed sectors in the 108flash. The Das U-boot environment contains enough MTD partition definition to 109read UBI volumes in a UBI device in the same flash. The bootcmd script loads a 110kernel from a FIT image and pass it to bootargs to locate and mount the squashfs 111in the paired UBI volume. 112 113This option is enabled via the `obmc-ubi-fs` OpenBMC distro feature. Used in the 114same BMC subsystems as the JFFS2 ones, but targeted for configurations that have 115enough flash storage to store at least 2 copies of the filesystem. This can be 116accomplished with dual flash storage. Some controllers, such as those in the 117AST2500, allow booting from an alternate flash on failure and this UBI option 118supports this feature. For this support, a copy of each kernel is stored on each 119flash and the U-Boot environment selects which kernel to use. 120 121#### ext4 on eMMC 122 123This is a work in progress. See the [eMMC Design Document][]. 124 125### Auxiliary Filesystems 126 127A tmpfs is used for /tmp, /run, and similar, while /dev, /proc, and /sys are 128supported by their normal kernel special filesystems, as specified by the FHS. 129 130## Other 131 132Additional Bitbake layer configurations exist for Raspberry Pi and x86 QEMU 133machines, but are provided primarily for code development and exploration. Code 134update for these environments is not supported. 135 136[das u-boot]: https://www.denx.de/wiki/U-Boot 137[systemd]: 138 https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md 139[systemd file hierarchy requirements]: 140 https://www.freedesktop.org/wiki/Software/systemd/FileHierarchy/ 141[fhs]: https://refspecs.linuxfoundation.org/fhs.shtml 142[obmc-phosphor-initfs]: 143 https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/initrdscripts/obmc-phosphor-initfs.bb 144[preinit-mounts]: 145 https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/preinit-mounts 146[emmc design document]: 147 https://github.com/openbmc/docs/blob/master/architecture/code-update/emmc-storage-design.md 148