1e66d8631SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2e66d8631SMauro Carvalho Chehab 3e66d8631SMauro Carvalho Chehab====================================== 4e66d8631SMauro Carvalho ChehabEnhanced Read-Only File System - EROFS 5e66d8631SMauro Carvalho Chehab====================================== 6e66d8631SMauro Carvalho Chehab 7e66d8631SMauro Carvalho ChehabOverview 8e66d8631SMauro Carvalho Chehab======== 9e66d8631SMauro Carvalho Chehab 10e66d8631SMauro Carvalho ChehabEROFS file-system stands for Enhanced Read-Only File System. Different 11e66d8631SMauro Carvalho Chehabfrom other read-only file systems, it aims to be designed for flexibility, 12e66d8631SMauro Carvalho Chehabscalability, but be kept simple and high performance. 13e66d8631SMauro Carvalho Chehab 14e66d8631SMauro Carvalho ChehabIt is designed as a better filesystem solution for the following scenarios: 15e66d8631SMauro Carvalho Chehab 16e66d8631SMauro Carvalho Chehab - read-only storage media or 17e66d8631SMauro Carvalho Chehab 18e66d8631SMauro Carvalho Chehab - part of a fully trusted read-only solution, which means it needs to be 19e66d8631SMauro Carvalho Chehab immutable and bit-for-bit identical to the official golden image for 20e66d8631SMauro Carvalho Chehab their releases due to security and other considerations and 21e66d8631SMauro Carvalho Chehab 22e66d8631SMauro Carvalho Chehab - hope to save some extra storage space with guaranteed end-to-end performance 23e66d8631SMauro Carvalho Chehab by using reduced metadata and transparent file compression, especially 24e66d8631SMauro Carvalho Chehab for those embedded devices with limited memory (ex, smartphone); 25e66d8631SMauro Carvalho Chehab 26e66d8631SMauro Carvalho ChehabHere is the main features of EROFS: 27e66d8631SMauro Carvalho Chehab 28e66d8631SMauro Carvalho Chehab - Little endian on-disk design; 29e66d8631SMauro Carvalho Chehab 30e66d8631SMauro Carvalho Chehab - Currently 4KB block size (nobh) and therefore maximum 16TB address space; 31e66d8631SMauro Carvalho Chehab 32e66d8631SMauro Carvalho Chehab - Metadata & data could be mixed by design; 33e66d8631SMauro Carvalho Chehab 34e66d8631SMauro Carvalho Chehab - 2 inode versions for different requirements: 35e66d8631SMauro Carvalho Chehab 36e66d8631SMauro Carvalho Chehab ===================== ============ ===================================== 37e66d8631SMauro Carvalho Chehab compact (v1) extended (v2) 38e66d8631SMauro Carvalho Chehab ===================== ============ ===================================== 39e66d8631SMauro Carvalho Chehab Inode metadata size 32 bytes 64 bytes 40e66d8631SMauro Carvalho Chehab Max file size 4 GB 16 EB (also limited by max. vol size) 41e66d8631SMauro Carvalho Chehab Max uids/gids 65536 4294967296 42e66d8631SMauro Carvalho Chehab File change time no yes (64 + 32-bit timestamp) 43e66d8631SMauro Carvalho Chehab Max hardlinks 65536 4294967296 44e66d8631SMauro Carvalho Chehab Metadata reserved 4 bytes 14 bytes 45e66d8631SMauro Carvalho Chehab ===================== ============ ===================================== 46e66d8631SMauro Carvalho Chehab 47e66d8631SMauro Carvalho Chehab - Support extended attributes (xattrs) as an option; 48e66d8631SMauro Carvalho Chehab 49e66d8631SMauro Carvalho Chehab - Support xattr inline and tail-end data inline for all files; 50e66d8631SMauro Carvalho Chehab 51e66d8631SMauro Carvalho Chehab - Support POSIX.1e ACLs by using xattrs; 52e66d8631SMauro Carvalho Chehab 5346f2e044SGao Xiang - Support transparent data compression as an option: 5446f2e044SGao Xiang LZ4 algorithm with the fixed-sized output compression for high performance. 55e66d8631SMauro Carvalho Chehab 56e66d8631SMauro Carvalho ChehabThe following git tree provides the file system user-space tools under 57e66d8631SMauro Carvalho Chehabdevelopment (ex, formatting tool mkfs.erofs): 58e66d8631SMauro Carvalho Chehab 59e66d8631SMauro Carvalho Chehab- git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git 60e66d8631SMauro Carvalho Chehab 61e66d8631SMauro Carvalho ChehabBugs and patches are welcome, please kindly help us and send to the following 62e66d8631SMauro Carvalho Chehablinux-erofs mailing list: 63e66d8631SMauro Carvalho Chehab 64e66d8631SMauro Carvalho Chehab- linux-erofs mailing list <linux-erofs@lists.ozlabs.org> 65e66d8631SMauro Carvalho Chehab 66e66d8631SMauro Carvalho ChehabMount options 67e66d8631SMauro Carvalho Chehab============= 68e66d8631SMauro Carvalho Chehab 69e66d8631SMauro Carvalho Chehab=================== ========================================================= 70e66d8631SMauro Carvalho Chehab(no)user_xattr Setup Extended User Attributes. Note: xattr is enabled 71e66d8631SMauro Carvalho Chehab by default if CONFIG_EROFS_FS_XATTR is selected. 72e66d8631SMauro Carvalho Chehab(no)acl Setup POSIX Access Control List. Note: acl is enabled 73e66d8631SMauro Carvalho Chehab by default if CONFIG_EROFS_FS_POSIX_ACL is selected. 74e66d8631SMauro Carvalho Chehabcache_strategy=%s Select a strategy for cached decompression from now on: 75e66d8631SMauro Carvalho Chehab 76e66d8631SMauro Carvalho Chehab ========== ============================================= 77e66d8631SMauro Carvalho Chehab disabled In-place I/O decompression only; 78e66d8631SMauro Carvalho Chehab readahead Cache the last incomplete compressed physical 79e66d8631SMauro Carvalho Chehab cluster for further reading. It still does 80e66d8631SMauro Carvalho Chehab in-place I/O decompression for the rest 81e66d8631SMauro Carvalho Chehab compressed physical clusters; 82e66d8631SMauro Carvalho Chehab readaround Cache the both ends of incomplete compressed 83e66d8631SMauro Carvalho Chehab physical clusters for further reading. 84e66d8631SMauro Carvalho Chehab It still does in-place I/O decompression 85e66d8631SMauro Carvalho Chehab for the rest compressed physical clusters. 86e66d8631SMauro Carvalho Chehab ========== ============================================= 8706252e9cSGao Xiangdax={always,never} Use direct access (no page cache). See 8806252e9cSGao Xiang Documentation/filesystems/dax.rst. 8906252e9cSGao Xiangdax A legacy option which is an alias for ``dax=always``. 90e66d8631SMauro Carvalho Chehab=================== ========================================================= 91e66d8631SMauro Carvalho Chehab 92e66d8631SMauro Carvalho ChehabOn-disk details 93e66d8631SMauro Carvalho Chehab=============== 94e66d8631SMauro Carvalho Chehab 95e66d8631SMauro Carvalho ChehabSummary 96e66d8631SMauro Carvalho Chehab------- 97e66d8631SMauro Carvalho ChehabDifferent from other read-only file systems, an EROFS volume is designed 98e66d8631SMauro Carvalho Chehabto be as simple as possible:: 99e66d8631SMauro Carvalho Chehab 100e66d8631SMauro Carvalho Chehab |-> aligned with the block size 101e66d8631SMauro Carvalho Chehab ____________________________________________________________ 102e66d8631SMauro Carvalho Chehab | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data | 103e66d8631SMauro Carvalho Chehab |_|__|_|_____|__________|_____|______|__________|_____|______| 104e66d8631SMauro Carvalho Chehab 0 +1K 105e66d8631SMauro Carvalho Chehab 106e66d8631SMauro Carvalho ChehabAll data areas should be aligned with the block size, but metadata areas 107e66d8631SMauro Carvalho Chehabmay not. All metadatas can be now observed in two different spaces (views): 108e66d8631SMauro Carvalho Chehab 109e66d8631SMauro Carvalho Chehab 1. Inode metadata space 110e66d8631SMauro Carvalho Chehab 111e66d8631SMauro Carvalho Chehab Each valid inode should be aligned with an inode slot, which is a fixed 112e66d8631SMauro Carvalho Chehab value (32 bytes) and designed to be kept in line with compact inode size. 113e66d8631SMauro Carvalho Chehab 114e66d8631SMauro Carvalho Chehab Each inode can be directly found with the following formula: 115e66d8631SMauro Carvalho Chehab inode offset = meta_blkaddr * block_size + 32 * nid 116e66d8631SMauro Carvalho Chehab 117e66d8631SMauro Carvalho Chehab :: 118e66d8631SMauro Carvalho Chehab 119e66d8631SMauro Carvalho Chehab |-> aligned with 8B 120e66d8631SMauro Carvalho Chehab |-> followed closely 121e66d8631SMauro Carvalho Chehab + meta_blkaddr blocks |-> another slot 122e66d8631SMauro Carvalho Chehab _____________________________________________________________________ 123e66d8631SMauro Carvalho Chehab | ... | inode | xattrs | extents | data inline | ... | inode ... 124e66d8631SMauro Carvalho Chehab |________|_______|(optional)|(optional)|__(optional)_|_____|__________ 125e66d8631SMauro Carvalho Chehab |-> aligned with the inode slot size 126e66d8631SMauro Carvalho Chehab . . 127e66d8631SMauro Carvalho Chehab . . 128e66d8631SMauro Carvalho Chehab . . 129e66d8631SMauro Carvalho Chehab . . 130e66d8631SMauro Carvalho Chehab . . 131e66d8631SMauro Carvalho Chehab . . 132e66d8631SMauro Carvalho Chehab .____________________________________________________|-> aligned with 4B 133e66d8631SMauro Carvalho Chehab | xattr_ibody_header | shared xattrs | inline xattrs | 134e66d8631SMauro Carvalho Chehab |____________________|_______________|_______________| 135e66d8631SMauro Carvalho Chehab |-> 12 bytes <-|->x * 4 bytes<-| . 136e66d8631SMauro Carvalho Chehab . . . 137e66d8631SMauro Carvalho Chehab . . . 138e66d8631SMauro Carvalho Chehab . . . 139e66d8631SMauro Carvalho Chehab ._______________________________.______________________. 140e66d8631SMauro Carvalho Chehab | id | id | id | id | ... | id | ent | ... | ent| ... | 141e66d8631SMauro Carvalho Chehab |____|____|____|____|______|____|_____|_____|____|_____| 142e66d8631SMauro Carvalho Chehab |-> aligned with 4B 143e66d8631SMauro Carvalho Chehab |-> aligned with 4B 144e66d8631SMauro Carvalho Chehab 145e66d8631SMauro Carvalho Chehab Inode could be 32 or 64 bytes, which can be distinguished from a common 146e66d8631SMauro Carvalho Chehab field which all inode versions have -- i_format:: 147e66d8631SMauro Carvalho Chehab 148e66d8631SMauro Carvalho Chehab __________________ __________________ 149e66d8631SMauro Carvalho Chehab | i_format | | i_format | 150e66d8631SMauro Carvalho Chehab |__________________| |__________________| 151e66d8631SMauro Carvalho Chehab | ... | | ... | 152e66d8631SMauro Carvalho Chehab | | | | 153e66d8631SMauro Carvalho Chehab |__________________| 32 bytes | | 154e66d8631SMauro Carvalho Chehab | | 155e66d8631SMauro Carvalho Chehab |__________________| 64 bytes 156e66d8631SMauro Carvalho Chehab 157e66d8631SMauro Carvalho Chehab Xattrs, extents, data inline are followed by the corresponding inode with 158e66d8631SMauro Carvalho Chehab proper alignment, and they could be optional for different data mappings. 159*2a9dc7a8SGao Xiang _currently_ total 5 data layouts are supported: 160e66d8631SMauro Carvalho Chehab 161e66d8631SMauro Carvalho Chehab == ==================================================================== 162e66d8631SMauro Carvalho Chehab 0 flat file data without data inline (no extent); 163e66d8631SMauro Carvalho Chehab 1 fixed-sized output data compression (with non-compacted indexes); 164e66d8631SMauro Carvalho Chehab 2 flat file data with tail packing data inline (no extent); 165*2a9dc7a8SGao Xiang 3 fixed-sized output data compression (with compacted indexes, v5.3+); 166*2a9dc7a8SGao Xiang 4 chunk-based file (v5.15+). 167e66d8631SMauro Carvalho Chehab == ==================================================================== 168e66d8631SMauro Carvalho Chehab 169e66d8631SMauro Carvalho Chehab The size of the optional xattrs is indicated by i_xattr_count in inode 170e66d8631SMauro Carvalho Chehab header. Large xattrs or xattrs shared by many different files can be 171e66d8631SMauro Carvalho Chehab stored in shared xattrs metadata rather than inlined right after inode. 172e66d8631SMauro Carvalho Chehab 173e66d8631SMauro Carvalho Chehab 2. Shared xattrs metadata space 174e66d8631SMauro Carvalho Chehab 175e66d8631SMauro Carvalho Chehab Shared xattrs space is similar to the above inode space, started with 176e66d8631SMauro Carvalho Chehab a specific block indicated by xattr_blkaddr, organized one by one with 177e66d8631SMauro Carvalho Chehab proper align. 178e66d8631SMauro Carvalho Chehab 179e66d8631SMauro Carvalho Chehab Each share xattr can also be directly found by the following formula: 180e66d8631SMauro Carvalho Chehab xattr offset = xattr_blkaddr * block_size + 4 * xattr_id 181e66d8631SMauro Carvalho Chehab 182e66d8631SMauro Carvalho Chehab:: 183e66d8631SMauro Carvalho Chehab 184e66d8631SMauro Carvalho Chehab |-> aligned by 4 bytes 185e66d8631SMauro Carvalho Chehab + xattr_blkaddr blocks |-> aligned with 4 bytes 186e66d8631SMauro Carvalho Chehab _________________________________________________________________________ 187e66d8631SMauro Carvalho Chehab | ... | xattr_entry | xattr data | ... | xattr_entry | xattr data ... 188e66d8631SMauro Carvalho Chehab |________|_____________|_____________|_____|______________|_______________ 189e66d8631SMauro Carvalho Chehab 190e66d8631SMauro Carvalho ChehabDirectories 191e66d8631SMauro Carvalho Chehab----------- 192e66d8631SMauro Carvalho ChehabAll directories are now organized in a compact on-disk format. Note that 193e66d8631SMauro Carvalho Chehabeach directory block is divided into index and name areas in order to support 194e66d8631SMauro Carvalho Chehabrandom file lookup, and all directory entries are _strictly_ recorded in 195e66d8631SMauro Carvalho Chehabalphabetical order in order to support improved prefix binary search 196e66d8631SMauro Carvalho Chehabalgorithm (could refer to the related source code). 197e66d8631SMauro Carvalho Chehab 198e66d8631SMauro Carvalho Chehab:: 199e66d8631SMauro Carvalho Chehab 200e66d8631SMauro Carvalho Chehab ___________________________ 201e66d8631SMauro Carvalho Chehab / | 202e66d8631SMauro Carvalho Chehab / ______________|________________ 203e66d8631SMauro Carvalho Chehab / / | nameoff1 | nameoffN-1 204e66d8631SMauro Carvalho Chehab ____________.______________._______________v________________v__________ 205e66d8631SMauro Carvalho Chehab | dirent | dirent | ... | dirent | filename | filename | ... | filename | 206e66d8631SMauro Carvalho Chehab |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____| 207e66d8631SMauro Carvalho Chehab \ ^ 208e66d8631SMauro Carvalho Chehab \ | * could have 209e66d8631SMauro Carvalho Chehab \ | trailing '\0' 210e66d8631SMauro Carvalho Chehab \________________________| nameoff0 211e66d8631SMauro Carvalho Chehab Directory block 212e66d8631SMauro Carvalho Chehab 213e66d8631SMauro Carvalho ChehabNote that apart from the offset of the first filename, nameoff0 also indicates 214e66d8631SMauro Carvalho Chehabthe total number of directory entries in this block since it is no need to 215e66d8631SMauro Carvalho Chehabintroduce another on-disk field at all. 216e66d8631SMauro Carvalho Chehab 217*2a9dc7a8SGao XiangChunk-based file 218*2a9dc7a8SGao Xiang---------------- 219*2a9dc7a8SGao XiangIn order to support chunk-based data deduplication, a new inode data layout has 220*2a9dc7a8SGao Xiangbeen supported since Linux v5.15: Files are split in equal-sized data chunks 221*2a9dc7a8SGao Xiangwith ``extents`` area of the inode metadata indicating how to get the chunk 222*2a9dc7a8SGao Xiangdata: these can be simply as a 4-byte block address array or in the 8-byte 223*2a9dc7a8SGao Xiangchunk index form (see struct erofs_inode_chunk_index in erofs_fs.h for more 224*2a9dc7a8SGao Xiangdetails.) 225*2a9dc7a8SGao Xiang 226*2a9dc7a8SGao XiangBy the way, chunk-based files are all uncompressed for now. 227*2a9dc7a8SGao Xiang 22846f2e044SGao XiangData compression 22946f2e044SGao Xiang---------------- 23046f2e044SGao XiangEROFS implements LZ4 fixed-sized output compression which generates fixed-sized 23146f2e044SGao Xiangcompressed data blocks from variable-sized input in contrast to other existing 23246f2e044SGao Xiangfixed-sized input solutions. Relatively higher compression ratios can be gotten 23346f2e044SGao Xiangby using fixed-sized output compression since nowadays popular data compression 23446f2e044SGao Xiangalgorithms are mostly LZ77-based and such fixed-sized output approach can be 23546f2e044SGao Xiangbenefited from the historical dictionary (aka. sliding window). 23646f2e044SGao Xiang 23746f2e044SGao XiangIn details, original (uncompressed) data is turned into several variable-sized 23846f2e044SGao Xiangextents and in the meanwhile, compressed into physical clusters (pclusters). 23946f2e044SGao XiangIn order to record each variable-sized extent, logical clusters (lclusters) are 24046f2e044SGao Xiangintroduced as the basic unit of compress indexes to indicate whether a new 24146f2e044SGao Xiangextent is generated within the range (HEAD) or not (NONHEAD). Lclusters are now 24246f2e044SGao Xiangfixed in block size, as illustrated below:: 243e66d8631SMauro Carvalho Chehab 2441b55767dSGao Xiang |<- variable-sized extent ->|<- VLE ->| 245e66d8631SMauro Carvalho Chehab clusterofs clusterofs clusterofs 2461b55767dSGao Xiang | | | 2471b55767dSGao Xiang _________v_________________________________v_______________________v________ 2481b55767dSGao Xiang ... | . | | . | | . ... 2491b55767dSGao Xiang ____|____._________|______________|________.___ _|______________|__.________ 2501b55767dSGao Xiang |-> lcluster <-|-> lcluster <-|-> lcluster <-|-> lcluster <-| 25146f2e044SGao Xiang (HEAD) (NONHEAD) (HEAD) (NONHEAD) . 25246f2e044SGao Xiang . CBLKCNT . . 25346f2e044SGao Xiang . . . 25446f2e044SGao Xiang . . . 25546f2e044SGao Xiang _______._____________________________.______________._________________ 2561b55767dSGao Xiang ... | | | | ... 2571b55767dSGao Xiang _______|______________|______________|______________|_________________ 25846f2e044SGao Xiang |-> big pcluster <-|-> pcluster <-| 259e66d8631SMauro Carvalho Chehab 26046f2e044SGao XiangA physical cluster can be seen as a container of physical compressed blocks 26146f2e044SGao Xiangwhich contains compressed data. Previously, only lcluster-sized (4KB) pclusters 26246f2e044SGao Xiangwere supported. After big pcluster feature is introduced (available since 26346f2e044SGao XiangLinux v5.13), pcluster can be a multiple of lcluster size. 264e66d8631SMauro Carvalho Chehab 26546f2e044SGao XiangFor each HEAD lcluster, clusterofs is recorded to indicate where a new extent 26646f2e044SGao Xiangstarts and blkaddr is used to seek the compressed data. For each NONHEAD 26746f2e044SGao Xianglcluster, delta0 and delta1 are available instead of blkaddr to indicate the 26846f2e044SGao Xiangdistance to its HEAD lcluster and the next HEAD lcluster. A PLAIN lcluster is 26946f2e044SGao Xiangalso a HEAD lcluster except that its data is uncompressed. See the comments 27046f2e044SGao Xiangaround "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details. 27146f2e044SGao Xiang 27246f2e044SGao XiangIf big pcluster is enabled, pcluster size in lclusters needs to be recorded as 27346f2e044SGao Xiangwell. Let the delta0 of the first NONHEAD lcluster store the compressed block 27446f2e044SGao Xiangcount with a special flag as a new called CBLKCNT NONHEAD lcluster. It's easy 27546f2e044SGao Xiangto understand its delta0 is constantly 1, as illustrated below:: 27646f2e044SGao Xiang 27746f2e044SGao Xiang __________________________________________________________ 27846f2e044SGao Xiang | HEAD | NONHEAD | NONHEAD | ... | NONHEAD | HEAD | HEAD | 27946f2e044SGao Xiang |__:___|_(CBLKCNT)_|_________|_____|_________|__:___|____:_| 28046f2e044SGao Xiang |<----- a big pcluster (with CBLKCNT) ------>|<-- -->| 28146f2e044SGao Xiang a lcluster-sized pcluster (without CBLKCNT) ^ 28246f2e044SGao Xiang 28346f2e044SGao XiangIf another HEAD follows a HEAD lcluster, there is no room to record CBLKCNT, 28446f2e044SGao Xiangbut it's easy to know the size of such pcluster is 1 lcluster as well. 285