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