4 EROFS file-system stands for Enhanced Read-Only File System. Different
5 from other read-only file systems, it aims to be designed for flexibility,
6 scalability, but be kept simple and high performance.
8 It is designed as a better filesystem solution for the following scenarios:
9 - read-only storage media or
11 - part of a fully trusted read-only solution, which means it needs to be
12 immutable and bit-for-bit identical to the official golden image for
13 their releases due to security and other considerations and
15 - hope to save some extra storage space with guaranteed end-to-end performance
16 by using reduced metadata and transparent file compression, especially
17 for those embedded devices with limited memory (ex, smartphone);
19 Here is the main features of EROFS:
20 - Little endian on-disk design;
22 - Currently 4KB block size (nobh) and therefore maximum 16TB address space;
24 - Metadata & data could be mixed by design;
26 - 2 inode versions for different requirements:
28 Inode metadata size: 32 bytes 64 bytes
29 Max file size: 4 GB 16 EB (also limited by max. vol size)
30 Max uids/gids: 65536 4294967296
31 File creation time: no yes (64 + 32-bit timestamp)
32 Max hardlinks: 65536 4294967296
33 Metadata reserved: 4 bytes 14 bytes
35 - Support extended attributes (xattrs) as an option;
37 - Support xattr inline and tail-end data inline for all files;
39 - Support POSIX.1e ACLs by using xattrs;
41 - Support transparent file compression as an option:
42 LZ4 algorithm with 4 KB fixed-output compression for high performance;
44 The following git tree provides the file system user-space tools under
45 development (ex, formatting tool mkfs.erofs):
46 >> git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
48 Bugs and patches are welcome, please kindly help us and send to the following
49 linux-erofs mailing list:
50 >> linux-erofs mailing list <linux-erofs@lists.ozlabs.org>
55 fault_injection=%d Enable fault injection in all supported types with
56 specified injection rate. Supported injection type:
58 FAULT_KMALLOC 0x000000001
59 FAULT_READ_IO 0x000000002
60 (no)user_xattr Setup Extended User Attributes. Note: xattr is enabled
61 by default if CONFIG_EROFS_FS_XATTR is selected.
62 (no)acl Setup POSIX Access Control List. Note: acl is enabled
63 by default if CONFIG_EROFS_FS_POSIX_ACL is selected.
64 cache_strategy=%s Select a strategy for cached decompression from now on:
65 disabled: In-place I/O decompression only;
66 readahead: Cache the last incomplete compressed physical
67 cluster for further reading. It still does
68 in-place I/O decompression for the rest
69 compressed physical clusters;
70 readaround: Cache the both ends of incomplete compressed
71 physical clusters for further reading.
72 It still does in-place I/O decompression
73 for the rest compressed physical clusters.
77 use_vmap=[0|1] Use vmap() instead of vm_map_ram() (default 0).
84 Different from other read-only file systems, an EROFS volume is designed
85 to be as simple as possible:
87 |-> aligned with the block size
88 ____________________________________________________________
89 | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data |
90 |_|__|_|_____|__________|_____|______|__________|_____|______|
93 All data areas should be aligned with the block size, but metadata areas
94 may not. All metadatas can be now observed in two different spaces (views):
95 1. Inode metadata space
96 Each valid inode should be aligned with an inode slot, which is a fixed
97 value (32 bytes) and designed to be kept in line with v1 inode size.
99 Each inode can be directly found with the following formula:
100 inode offset = meta_blkaddr * block_size + 32 * nid
104 + meta_blkaddr blocks |-> another slot
105 _____________________________________________________________________
106 | ... | inode | xattrs | extents | data inline | ... | inode ...
107 |________|_______|(optional)|(optional)|__(optional)_|_____|__________
108 |-> aligned with the inode slot size
115 .____________________________________________________|-> aligned with 4B
116 | xattr_ibody_header | shared xattrs | inline xattrs |
117 |____________________|_______________|_______________|
118 |-> 12 bytes <-|->x * 4 bytes<-| .
122 ._______________________________.______________________.
123 | id | id | id | id | ... | id | ent | ... | ent| ... |
124 |____|____|____|____|______|____|_____|_____|____|_____|
128 Inode could be 32 or 64 bytes, which can be distinguished from a common
129 field which all inode versions have -- i_advise:
131 __________________ __________________
132 | i_advise | | i_advise |
133 |__________________| |__________________|
136 |__________________| 32 bytes | |
138 |__________________| 64 bytes
140 Xattrs, extents, data inline are followed by the corresponding inode with
141 proper alignes, and they could be optional for different data mappings,
142 _currently_ there are totally 3 valid data mappings supported:
144 1) flat file data without data inline (no extent);
145 2) fixed-output size data compression (must have extents);
146 3) flat file data with tail-end data inline (no extent);
148 The size of the optional xattrs is indicated by i_xattr_count in inode
149 header. Large xattrs or xattrs shared by many different files can be
150 stored in shared xattrs metadata rather than inlined right after inode.
152 2. Shared xattrs metadata space
153 Shared xattrs space is similar to the above inode space, started with
154 a specific block indicated by xattr_blkaddr, organized one by one with
157 Each share xattr can also be directly found by the following formula:
158 xattr offset = xattr_blkaddr * block_size + 4 * xattr_id
160 |-> aligned by 4 bytes
161 + xattr_blkaddr blocks |-> aligned with 4 bytes
162 _________________________________________________________________________
163 | ... | xattr_entry | xattr data | ... | xattr_entry | xattr data ...
164 |________|_____________|_____________|_____|______________|_______________
168 All directories are now organized in a compact on-disk format. Note that
169 each directory block is divided into index and name areas in order to support
170 random file lookup, and all directory entries are _strictly_ recorded in
171 alphabetical order in order to support improved prefix binary search
172 algorithm (could refer to the related source code).
174 ___________________________
176 / ______________|________________
177 / / | nameoff1 | nameoffN-1
178 ____________.______________._______________v________________v__________
179 | dirent | dirent | ... | dirent | filename | filename | ... | filename |
180 |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
184 \________________________| nameoff0
188 Note that apart from the offset of the first filename, nameoff0 also indicates
189 the total number of directory entries in this block since it is no need to
190 introduce another on-disk field at all.
194 Currently, EROFS supports 4KB fixed-output clustersize transparent file
195 compression, as illustrated below:
197 |---- Variant-Length Extent ----|-------- VLE --------|----- VLE -----
198 clusterofs clusterofs clusterofs
200 _________v_______________________________v_____________________v_______________
201 ... | . | | . | | . | ...
202 ____|____.________|_____________|________.____|_____________|__.__________|____
203 |-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|
204 size size size size size
208 _______._____________._____________._____________._____________________
209 ... | | | | ... physical data
210 _______|_____________|_____________|_____________|_____________________
211 |-> cluster <-|-> cluster <-|-> cluster <-|
214 Currently each on-disk physical cluster can contain 4KB (un)compressed data
215 at most. For each logical cluster, there is a corresponding on-disk index to
216 describe its cluster type, physical cluster address, etc.
218 See "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details.