Documentation/filesystems/erofs.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 EROFS - Enhanced Read-Only File System
   5 ======================================
   6
   7 Overview
   8 ========
   9
  10 EROFS filesystem stands for Enhanced Read-Only File System.  It aims to form a
  11 generic read-only filesystem solution for various read-only use cases instead
  12 of just focusing on storage space saving without considering any side effects
  13 of runtime performance.
  14
  15 It is designed to meet the needs of flexibility, feature extendability and user
  16 payload friendly, etc.  Apart from those, it is still kept as a simple
  17 random-access friendly high-performance filesystem to get rid of unneeded I/O
  18 amplification and memory-resident overhead compared to similar approaches.
  19
  20 It is implemented to be a better choice for the following scenarios:
  21
  22  - read-only storage media or
  23
  24  - part of a fully trusted read-only solution, which means it needs to be
  25    immutable and bit-for-bit identical to the official golden image for
  26    their releases due to security or other considerations and
  27
  28  - hope to minimize extra storage space with guaranteed end-to-end performance
  29    by using compact layout, transparent file compression and direct access,
  30    especially for those embedded devices with limited memory and high-density
  31    hosts with numerous containers.
  32
  33 Here are the main features of EROFS:
  34
  35  - Little endian on-disk design;
  36
  37  - Block-based distribution and file-based distribution over fscache are
  38    supported;
  39
  40  - Support multiple devices to refer to external blobs, which can be used
  41    for container images;
  42
  43  - 32-bit block addresses for each device, therefore 16TiB address space at
  44    most with 4KiB block size for now;
  45
  46  - Two inode layouts for different requirements:
  47
  48    =====================  ============  ======================================
  49                           compact (v1)  extended (v2)
  50    =====================  ============  ======================================
  51    Inode metadata size    32 bytes      64 bytes
  52    Max file size          4 GiB         16 EiB (also limited by max. vol size)
  53    Max uids/gids          65536         4294967296
  54    Per-inode timestamp    no            yes (64 + 32-bit timestamp)
  55    Max hardlinks          65536         4294967296
  56    Metadata reserved      8 bytes       18 bytes
  57    =====================  ============  ======================================
  58
  59  - Support extended attributes as an option;
  60
  61  - Support POSIX.1e ACLs by using extended attributes;
  62
  63  - Support transparent data compression as an option:
  64    LZ4 and MicroLZMA algorithms can be used on a per-file basis; In addition,
  65    inplace decompression is also supported to avoid bounce compressed buffers
  66    and page cache thrashing.
  67
  68  - Support chunk-based data deduplication and rolling-hash compressed data
  69    deduplication;
  70
  71  - Support tailpacking inline compared to byte-addressed unaligned metadata
  72    or smaller block size alternatives;
  73
  74  - Support merging tail-end data into a special inode as fragments.
  75
  76  - Support large folios for uncompressed files.
  77
  78  - Support direct I/O on uncompressed files to avoid double caching for loop
  79    devices;
  80
  81  - Support FSDAX on uncompressed images for secure containers and ramdisks in
  82    order to get rid of unnecessary page cache.
  83
  84  - Support file-based on-demand loading with the Fscache infrastructure.
  85
  86 The following git tree provides the file system user-space tools under
  87 development, such as a formatting tool (mkfs.erofs), an on-disk consistency &
  88 compatibility checking tool (fsck.erofs), and a debugging tool (dump.erofs):
  89
  90 - git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
  91
  92 Bugs and patches are welcome, please kindly help us and send to the following
  93 linux-erofs mailing list:
  94
  95 - linux-erofs mailing list   <linux-erofs@lists.ozlabs.org>
  96
  97 Mount options
  98 =============
  99
 100 ===================    =========================================================
 101 (no)user_xattr         Setup Extended User Attributes. Note: xattr is enabled
 102                        by default if CONFIG_EROFS_FS_XATTR is selected.
 103 (no)acl                Setup POSIX Access Control List. Note: acl is enabled
 104                        by default if CONFIG_EROFS_FS_POSIX_ACL is selected.
 105 cache_strategy=%s      Select a strategy for cached decompression from now on:
 106
 107                        ==========  =============================================
 108                          disabled  In-place I/O decompression only;
 109                         readahead  Cache the last incomplete compressed physical
 110                                    cluster for further reading. It still does
 111                                    in-place I/O decompression for the rest
 112                                    compressed physical clusters;
 113                        readaround  Cache the both ends of incomplete compressed
 114                                    physical clusters for further reading.
 115                                    It still does in-place I/O decompression
 116                                    for the rest compressed physical clusters.
 117                        ==========  =============================================
 118 dax={always,never}     Use direct access (no page cache).  See
 119                        Documentation/filesystems/dax.rst.
 120 dax                    A legacy option which is an alias for ``dax=always``.
 121 device=%s              Specify a path to an extra device to be used together.
 122 fsid=%s                Specify a filesystem image ID for Fscache back-end.
 123 domain_id=%s           Specify a domain ID in fscache mode so that different images
 124                        with the same blobs under a given domain ID can share storage.
 125 ===================    =========================================================
 126
 127 Sysfs Entries
 128 =============
 129
 130 Information about mounted erofs file systems can be found in /sys/fs/erofs.
 131 Each mounted filesystem will have a directory in /sys/fs/erofs based on its
 132 device name (i.e., /sys/fs/erofs/sda).
 133 (see also Documentation/ABI/testing/sysfs-fs-erofs)
 134
 135 On-disk details
 136 ===============
 137
 138 Summary
 139 -------
 140 Different from other read-only file systems, an EROFS volume is designed
 141 to be as simple as possible::
 142
 143                                 |-> aligned with the block size
 144    ____________________________________________________________
 145   | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data |
 146   |_|__|_|_____|__________|_____|______|__________|_____|______|
 147   0 +1K
 148
 149 All data areas should be aligned with the block size, but metadata areas
 150 may not. All metadatas can be now observed in two different spaces (views):
 151
 152  1. Inode metadata space
 153
 154     Each valid inode should be aligned with an inode slot, which is a fixed
 155     value (32 bytes) and designed to be kept in line with compact inode size.
 156
 157     Each inode can be directly found with the following formula:
 158          inode offset = meta_blkaddr * block_size + 32 * nid
 159
 160     ::
 161
 162                                  |-> aligned with 8B
 163                                             |-> followed closely
 164      + meta_blkaddr blocks                                      |-> another slot
 165        _____________________________________________________________________
 166      |  ...   | inode |  xattrs  | extents  | data inline | ... | inode ...
 167      |________|_______|(optional)|(optional)|__(optional)_|_____|__________
 168               |-> aligned with the inode slot size
 169                    .                   .
 170                  .                         .
 171                .                              .
 172              .                                    .
 173            .                                         .
 174          .                                              .
 175        .____________________________________________________|-> aligned with 4B
 176        | xattr_ibody_header | shared xattrs | inline xattrs |
 177        |____________________|_______________|_______________|
 178        |->    12 bytes    <-|->x * 4 bytes<-|               .
 179                            .                .                 .
 180                      .                      .                   .
 181                 .                           .                     .
 182             ._______________________________.______________________.
 183             | id | id | id | id |  ... | id | ent | ... | ent| ... |
 184             |____|____|____|____|______|____|_____|_____|____|_____|
 185                                             |-> aligned with 4B
 186                                                         |-> aligned with 4B
 187
 188     Inode could be 32 or 64 bytes, which can be distinguished from a common
 189     field which all inode versions have -- i_format::
 190
 191         __________________               __________________
 192        |     i_format     |             |     i_format     |
 193        |__________________|             |__________________|
 194        |        ...       |             |        ...       |
 195        |                  |             |                  |
 196        |__________________| 32 bytes    |                  |
 197                                         |                  |
 198                                         |__________________| 64 bytes
 199
 200     Xattrs, extents, data inline are followed by the corresponding inode with
 201     proper alignment, and they could be optional for different data mappings.
 202     _currently_ total 5 data layouts are supported:
 203
 204     ==  ====================================================================
 205      0  flat file data without data inline (no extent);
 206      1  fixed-sized output data compression (with non-compacted indexes);
 207      2  flat file data with tail packing data inline (no extent);
 208      3  fixed-sized output data compression (with compacted indexes, v5.3+);
 209      4  chunk-based file (v5.15+).
 210     ==  ====================================================================
 211
 212     The size of the optional xattrs is indicated by i_xattr_count in inode
 213     header. Large xattrs or xattrs shared by many different files can be
 214     stored in shared xattrs metadata rather than inlined right after inode.
 215
 216  2. Shared xattrs metadata space
 217
 218     Shared xattrs space is similar to the above inode space, started with
 219     a specific block indicated by xattr_blkaddr, organized one by one with
 220     proper align.
 221
 222     Each share xattr can also be directly found by the following formula:
 223          xattr offset = xattr_blkaddr * block_size + 4 * xattr_id
 224
 225 ::
 226
 227                            |-> aligned by  4 bytes
 228     + xattr_blkaddr blocks                     |-> aligned with 4 bytes
 229      _________________________________________________________________________
 230     |  ...   | xattr_entry |  xattr data | ... |  xattr_entry | xattr data  ...
 231     |________|_____________|_____________|_____|______________|_______________
 232
 233 Directories
 234 -----------
 235 All directories are now organized in a compact on-disk format. Note that
 236 each directory block is divided into index and name areas in order to support
 237 random file lookup, and all directory entries are _strictly_ recorded in
 238 alphabetical order in order to support improved prefix binary search
 239 algorithm (could refer to the related source code).
 240
 241 ::
 242
 243                   ___________________________
 244                  /                           |
 245                 /              ______________|________________
 246                /              /              | nameoff1       | nameoffN-1
 247   ____________.______________._______________v________________v__________
 248  | dirent | dirent | ... | dirent | filename | filename | ... | filename |
 249  |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
 250       \                           ^
 251        \                          |                           * could have
 252         \                         |                             trailing '\0'
 253          \________________________| nameoff0
 254                              Directory block
 255
 256 Note that apart from the offset of the first filename, nameoff0 also indicates
 257 the total number of directory entries in this block since it is no need to
 258 introduce another on-disk field at all.
 259
 260 Chunk-based files
 261 -----------------
 262 In order to support chunk-based data deduplication, a new inode data layout has
 263 been supported since Linux v5.15: Files are split in equal-sized data chunks
 264 with ``extents`` area of the inode metadata indicating how to get the chunk
 265 data: these can be simply as a 4-byte block address array or in the 8-byte
 266 chunk index form (see struct erofs_inode_chunk_index in erofs_fs.h for more
 267 details.)
 268
 269 By the way, chunk-based files are all uncompressed for now.
 270
 271 Data compression
 272 ----------------
 273 EROFS implements fixed-sized output compression which generates fixed-sized
 274 compressed data blocks from variable-sized input in contrast to other existing
 275 fixed-sized input solutions. Relatively higher compression ratios can be gotten
 276 by using fixed-sized output compression since nowadays popular data compression
 277 algorithms are mostly LZ77-based and such fixed-sized output approach can be
 278 benefited from the historical dictionary (aka. sliding window).
 279
 280 In details, original (uncompressed) data is turned into several variable-sized
 281 extents and in the meanwhile, compressed into physical clusters (pclusters).
 282 In order to record each variable-sized extent, logical clusters (lclusters) are
 283 introduced as the basic unit of compress indexes to indicate whether a new
 284 extent is generated within the range (HEAD) or not (NONHEAD). Lclusters are now
 285 fixed in block size, as illustrated below::
 286
 287           |<-    variable-sized extent    ->|<-       VLE         ->|
 288         clusterofs                        clusterofs              clusterofs
 289           |                                 |                       |
 290  _________v_________________________________v_______________________v________
 291  ... |    .         |              |        .     |              |  .   ...
 292  ____|____._________|______________|________.___ _|______________|__.________
 293      |-> lcluster <-|-> lcluster <-|-> lcluster <-|-> lcluster <-|
 294           (HEAD)        (NONHEAD)       (HEAD)        (NONHEAD)    .
 295            .             CBLKCNT            .                    .
 296             .                               .                  .
 297              .                              .                .
 298        _______._____________________________.______________._________________
 299           ... |              |              |              | ...
 300        _______|______________|______________|______________|_________________
 301               |->      big pcluster       <-|-> pcluster <-|
 302
 303 A physical cluster can be seen as a container of physical compressed blocks
 304 which contains compressed data. Previously, only lcluster-sized (4KB) pclusters
 305 were supported. After big pcluster feature is introduced (available since
 306 Linux v5.13), pcluster can be a multiple of lcluster size.
 307
 308 For each HEAD lcluster, clusterofs is recorded to indicate where a new extent
 309 starts and blkaddr is used to seek the compressed data. For each NONHEAD
 310 lcluster, delta0 and delta1 are available instead of blkaddr to indicate the
 311 distance to its HEAD lcluster and the next HEAD lcluster. A PLAIN lcluster is
 312 also a HEAD lcluster except that its data is uncompressed. See the comments
 313 around "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details.
 314
 315 If big pcluster is enabled, pcluster size in lclusters needs to be recorded as
 316 well. Let the delta0 of the first NONHEAD lcluster store the compressed block
 317 count with a special flag as a new called CBLKCNT NONHEAD lcluster. It's easy
 318 to understand its delta0 is constantly 1, as illustrated below::
 319
 320    __________________________________________________________
 321   | HEAD |  NONHEAD  | NONHEAD | ... | NONHEAD | HEAD | HEAD |
 322   |__:___|_(CBLKCNT)_|_________|_____|_________|__:___|____:_|
 323      |<----- a big pcluster (with CBLKCNT) ------>|<--  -->|
 324            a lcluster-sized pcluster (without CBLKCNT) ^
 325
 326 If another HEAD follows a HEAD lcluster, there is no room to record CBLKCNT,
 327 but it's easy to know the size of such pcluster is 1 lcluster as well.
 328
 329 Since Linux v6.1, each pcluster can be used for multiple variable-sized extents,
 330 therefore it can be used for compressed data deduplication.