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