[linux-2.6-block.git] / Documentation / filesystems / erofs.rst

.. SPDX-License-Identifier: GPL-2.0

======================================
EROFS - Enhanced Read-Only File System
======================================

Overview
========

EROFS filesystem stands for Enhanced Read-Only File System.  It aims to form a
generic read-only filesystem solution for various read-only use cases instead
of just focusing on storage space saving without considering any side effects
of runtime performance.

It is designed to meet the needs of flexibility, feature extendability and user
payload friendly, etc.  Apart from those, it is still kept as a simple
random-access friendly high-performance filesystem to get rid of unneeded I/O
amplification and memory-resident overhead compared to similar approaches.

It is implemented to be a better choice for the following scenarios:

 - read-only storage media or

 - part of a fully trusted read-only solution, which means it needs to be
   immutable and bit-for-bit identical to the official golden image for
   their releases due to security or other considerations and

 - hope to minimize extra storage space with guaranteed end-to-end performance
   by using compact layout, transparent file compression and direct access,
   especially for those embedded devices with limited memory and high-density
   hosts with numerous containers.

Here are the main features of EROFS:

 - Little endian on-disk design;

 - Block-based distribution and file-based distribution over fscache are
   supported;

 - Support multiple devices to refer to external blobs, which can be used
   for container images;

 - 4KiB block size and 32-bit block addresses for each device, therefore
   16TiB address space at most for now;

 - Two inode layouts for different requirements:

   =====================  ============  ======================================
                          compact (v1)  extended (v2)
   =====================  ============  ======================================
   Inode metadata size    32 bytes      64 bytes
   Max file size          4 GiB         16 EiB (also limited by max. vol size)
   Max uids/gids          65536         4294967296
   Per-inode timestamp    no            yes (64 + 32-bit timestamp)
   Max hardlinks          65536         4294967296
   Metadata reserved      8 bytes       18 bytes
   =====================  ============  ======================================

 - Support extended attributes as an option;

 - Support POSIX.1e ACLs by using extended attributes;

 - Support transparent data compression as an option:
   LZ4 and MicroLZMA algorithms can be used on a per-file basis; In addition,
   inplace decompression is also supported to avoid bounce compressed buffers
   and page cache thrashing.

 - Support chunk-based data deduplication and rolling-hash compressed data
   deduplication;

 - Support tailpacking inline compared to byte-addressed unaligned metadata
   or smaller block size alternatives;

 - Support merging tail-end data into a special inode as fragments.

 - Support large folios for uncompressed files.

 - Support direct I/O on uncompressed files to avoid double caching for loop
   devices;

 - Support FSDAX on uncompressed images for secure containers and ramdisks in
   order to get rid of unnecessary page cache.

 - Support file-based on-demand loading with the Fscache infrastructure.

The following git tree provides the file system user-space tools under
development, such as a formatting tool (mkfs.erofs), an on-disk consistency &
compatibility checking tool (fsck.erofs), and a debugging tool (dump.erofs):

- git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git

Bugs and patches are welcome, please kindly help us and send to the following
linux-erofs mailing list:

- linux-erofs mailing list   <linux-erofs@lists.ozlabs.org>

Mount options
=============

===================    =========================================================
(no)user_xattr         Setup Extended User Attributes. Note: xattr is enabled
                       by default if CONFIG_EROFS_FS_XATTR is selected.
(no)acl                Setup POSIX Access Control List. Note: acl is enabled
                       by default if CONFIG_EROFS_FS_POSIX_ACL is selected.
cache_strategy=%s      Select a strategy for cached decompression from now on:

		       ==========  =============================================
                         disabled  In-place I/O decompression only;
                        readahead  Cache the last incomplete compressed physical
                                   cluster for further reading. It still does
                                   in-place I/O decompression for the rest
                                   compressed physical clusters;
                       readaround  Cache the both ends of incomplete compressed
                                   physical clusters for further reading.
                                   It still does in-place I/O decompression
                                   for the rest compressed physical clusters.
		       ==========  =============================================
dax={always,never}     Use direct access (no page cache).  See
                       Documentation/filesystems/dax.rst.
dax                    A legacy option which is an alias for ``dax=always``.
device=%s              Specify a path to an extra device to be used together.
fsid=%s                Specify a filesystem image ID for Fscache back-end.
domain_id=%s           Specify a domain ID in fscache mode so that different images
                       with the same blobs under a given domain ID can share storage.
===================    =========================================================

Sysfs Entries
=============

Information about mounted erofs file systems can be found in /sys/fs/erofs.
Each mounted filesystem will have a directory in /sys/fs/erofs based on its
device name (i.e., /sys/fs/erofs/sda).
(see also Documentation/ABI/testing/sysfs-fs-erofs)

On-disk details
===============

Summary
-------
Different from other read-only file systems, an EROFS volume is designed
to be as simple as possible::

                                |-> aligned with the block size
   ____________________________________________________________
  | |SB| | ... | Metadata | ... | Data | Metadata | ... | Data |
  |_|__|_|_____|__________|_____|______|__________|_____|______|
  0 +1K

All data areas should be aligned with the block size, but metadata areas
may not. All metadatas can be now observed in two different spaces (views):

 1. Inode metadata space

    Each valid inode should be aligned with an inode slot, which is a fixed
    value (32 bytes) and designed to be kept in line with compact inode size.

    Each inode can be directly found with the following formula:
         inode offset = meta_blkaddr * block_size + 32 * nid

    ::

                                 |-> aligned with 8B
                                            |-> followed closely
     + meta_blkaddr blocks                                      |-> another slot
       _____________________________________________________________________
     |  ...   | inode |  xattrs  | extents  | data inline | ... | inode ...
     |________|_______|(optional)|(optional)|__(optional)_|_____|__________
              |-> aligned with the inode slot size
                   .                   .
                 .                         .
               .                              .
             .                                    .
           .                                         .
         .                                              .
       .____________________________________________________|-> aligned with 4B
       | xattr_ibody_header | shared xattrs | inline xattrs |
       |____________________|_______________|_______________|
       |->    12 bytes    <-|->x * 4 bytes<-|               .
                           .                .                 .
                     .                      .                   .
                .                           .                     .
            ._______________________________.______________________.
            | id | id | id | id |  ... | id | ent | ... | ent| ... |
            |____|____|____|____|______|____|_____|_____|____|_____|
                                            |-> aligned with 4B
                                                        |-> aligned with 4B

    Inode could be 32 or 64 bytes, which can be distinguished from a common
    field which all inode versions have -- i_format::

        __________________               __________________
       |     i_format     |             |     i_format     |
       |__________________|             |__________________|
       |        ...       |             |        ...       |
       |                  |             |                  |
       |__________________| 32 bytes    |                  |
                                        |                  |
                                        |__________________| 64 bytes

    Xattrs, extents, data inline are followed by the corresponding inode with
    proper alignment, and they could be optional for different data mappings.
    _currently_ total 5 data layouts are supported:

    ==  ====================================================================
     0  flat file data without data inline (no extent);
     1  fixed-sized output data compression (with non-compacted indexes);
     2  flat file data with tail packing data inline (no extent);
     3  fixed-sized output data compression (with compacted indexes, v5.3+);
     4  chunk-based file (v5.15+).
    ==  ====================================================================

    The size of the optional xattrs is indicated by i_xattr_count in inode
    header. Large xattrs or xattrs shared by many different files can be
    stored in shared xattrs metadata rather than inlined right after inode.

 2. Shared xattrs metadata space

    Shared xattrs space is similar to the above inode space, started with
    a specific block indicated by xattr_blkaddr, organized one by one with
    proper align.

    Each share xattr can also be directly found by the following formula:
         xattr offset = xattr_blkaddr * block_size + 4 * xattr_id

::

                           |-> aligned by  4 bytes
    + xattr_blkaddr blocks                     |-> aligned with 4 bytes
     _________________________________________________________________________
    |  ...   | xattr_entry |  xattr data | ... |  xattr_entry | xattr data  ...
    |________|_____________|_____________|_____|______________|_______________

Directories
-----------
All directories are now organized in a compact on-disk format. Note that
each directory block is divided into index and name areas in order to support
random file lookup, and all directory entries are _strictly_ recorded in
alphabetical order in order to support improved prefix binary search
algorithm (could refer to the related source code).

::

                  ___________________________
                 /                           |
                /              ______________|________________
               /              /              | nameoff1       | nameoffN-1
  ____________.______________._______________v________________v__________
 | dirent | dirent | ... | dirent | filename | filename | ... | filename |
 |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
      \                           ^
       \                          |                           * could have
        \                         |                             trailing '\0'
         \________________________| nameoff0
                             Directory block

Note that apart from the offset of the first filename, nameoff0 also indicates
the total number of directory entries in this block since it is no need to
introduce another on-disk field at all.

Chunk-based files
-----------------
In order to support chunk-based data deduplication, a new inode data layout has
been supported since Linux v5.15: Files are split in equal-sized data chunks
with ``extents`` area of the inode metadata indicating how to get the chunk
data: these can be simply as a 4-byte block address array or in the 8-byte
chunk index form (see struct erofs_inode_chunk_index in erofs_fs.h for more
details.)

By the way, chunk-based files are all uncompressed for now.

Data compression
----------------
EROFS implements fixed-sized output compression which generates fixed-sized
compressed data blocks from variable-sized input in contrast to other existing
fixed-sized input solutions. Relatively higher compression ratios can be gotten
by using fixed-sized output compression since nowadays popular data compression
algorithms are mostly LZ77-based and such fixed-sized output approach can be
benefited from the historical dictionary (aka. sliding window).

In details, original (uncompressed) data is turned into several variable-sized
extents and in the meanwhile, compressed into physical clusters (pclusters).
In order to record each variable-sized extent, logical clusters (lclusters) are
introduced as the basic unit of compress indexes to indicate whether a new
extent is generated within the range (HEAD) or not (NONHEAD). Lclusters are now
fixed in block size, as illustrated below::

          |<-    variable-sized extent    ->|<-       VLE         ->|
        clusterofs                        clusterofs              clusterofs
          |                                 |                       |
 _________v_________________________________v_______________________v________
 ... |    .         |              |        .     |              |  .   ...
 ____|____._________|______________|________.___ _|______________|__.________
     |-> lcluster <-|-> lcluster <-|-> lcluster <-|-> lcluster <-|
          (HEAD)        (NONHEAD)       (HEAD)        (NONHEAD)    .
           .             CBLKCNT            .                    .
            .                               .                  .
             .                              .                .
       _______._____________________________.______________._________________
          ... |              |              |              | ...
       _______|______________|______________|______________|_________________
              |->      big pcluster       <-|-> pcluster <-|

A physical cluster can be seen as a container of physical compressed blocks
which contains compressed data. Previously, only lcluster-sized (4KB) pclusters
were supported. After big pcluster feature is introduced (available since
Linux v5.13), pcluster can be a multiple of lcluster size.

For each HEAD lcluster, clusterofs is recorded to indicate where a new extent
starts and blkaddr is used to seek the compressed data. For each NONHEAD
lcluster, delta0 and delta1 are available instead of blkaddr to indicate the
distance to its HEAD lcluster and the next HEAD lcluster. A PLAIN lcluster is
also a HEAD lcluster except that its data is uncompressed. See the comments
around "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details.

If big pcluster is enabled, pcluster size in lclusters needs to be recorded as
well. Let the delta0 of the first NONHEAD lcluster store the compressed block
count with a special flag as a new called CBLKCNT NONHEAD lcluster. It's easy
to understand its delta0 is constantly 1, as illustrated below::

   __________________________________________________________
  | HEAD |  NONHEAD  | NONHEAD | ... | NONHEAD | HEAD | HEAD |
  |__:___|_(CBLKCNT)_|_________|_____|_________|__:___|____:_|
     |<----- a big pcluster (with CBLKCNT) ------>|<--  -->|
           a lcluster-sized pcluster (without CBLKCNT) ^

If another HEAD follows a HEAD lcluster, there is no room to record CBLKCNT,
but it's easy to know the size of such pcluster is 1 lcluster as well.

Since Linux v6.1, each pcluster can be used for multiple variable-sized extents,
therefore it can be used for compressed data deduplication.
Commit	Line	Data
e66d8631 MCC	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	======================================
6e95d0a0	4	EROFS - Enhanced Read-Only File System
e66d8631 MCC	5	======================================
e66d8631 MCC	6
fdb05364 GX	7	Overview
	8	========
	9
6e95d0a0 GX	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.
fdb05364	14
6e95d0a0 GX	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:
e66d8631	21
fdb05364 GX	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
6e95d0a0	26	their releases due to security or other considerations and
fdb05364	27
dfeab2e9 GX	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
6e95d0a0	31	hosts with numerous containers.
fdb05364	32
2109901d	33	Here are the main features of EROFS:
e66d8631	34
fdb05364 GX	35	- Little endian on-disk design;
fdb05364 GX	36
2109901d GX	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	- 4KiB block size and 32-bit block addresses for each device, therefore
	44	16TiB address space at most for now;
fdb05364	45
6e95d0a0	46	- Two inode layouts for different requirements:
e66d8631	47
6e95d0a0	48	===================== ============ ======================================
ffafde47	49	compact (v1) extended (v2)
6e95d0a0	50	===================== ============ ======================================
e66d8631	51	Inode metadata size 32 bytes 64 bytes
6e95d0a0	52	Max file size 4 GiB 16 EiB (also limited by max. vol size)
e66d8631	53	Max uids/gids 65536 4294967296
a1108dcd	54	Per-inode timestamp no yes (64 + 32-bit timestamp)
e66d8631	55	Max hardlinks 65536 4294967296
6e95d0a0 GX	56	Metadata reserved 8 bytes 18 bytes
	57	===================== ============ ======================================
	58
2109901d	59	- Support extended attributes as an option;
fdb05364	60
2109901d	61	- Support POSIX.1e ACLs by using extended attributes;
516c115c	62
46f2e044	63	- Support transparent data compression as an option:
6e95d0a0 GX	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
2109901d GX	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
e6687b89 JX	76	- Support large folios for uncompressed files.
e6687b89 JX	77
6e95d0a0 GX	78	- Support direct I/O on uncompressed files to avoid double caching for loop
6e95d0a0 GX	79	devices;
dfeab2e9	80
6e95d0a0 GX	81	- Support FSDAX on uncompressed images for secure containers and ramdisks in
	82	order to get rid of unnecessary page cache.
	83
6e95d0a0	84	- Support file-based on-demand loading with the Fscache infrastructure.
fdb05364 GX	85
fdb05364 GX	86	The following git tree provides the file system user-space tools under
6e95d0a0 GX	87	development, such as a formatting tool (mkfs.erofs), an on-disk consistency &
6e95d0a0 GX	88	compatibility checking tool (fsck.erofs), and a debugging tool (dump.erofs):
e66d8631 MCC	89
e66d8631 MCC	90	- git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
fdb05364 GX	91
	92	Bugs and patches are welcome, please kindly help us and send to the following
	93	linux-erofs mailing list:
e66d8631 MCC	94
e66d8631 MCC	95	- linux-erofs mailing list <linux-erofs@lists.ozlabs.org>
fdb05364	96
fdb05364 GX	97	Mount options
	98	=============
	99
e66d8631	100	=================== =========================================================
fdb05364 GX	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.
4279f3f9	105	cache_strategy=%s Select a strategy for cached decompression from now on:
e66d8631 MCC	106
	107	========== =============================================
	108	disabled In-place I/O decompression only;
	109	readahead Cache the last incomplete compressed physical
4279f3f9 GX	110	cluster for further reading. It still does
	111	in-place I/O decompression for the rest
	112	compressed physical clusters;
e66d8631	113	readaround Cache the both ends of incomplete compressed
4279f3f9 GX	114	physical clusters for further reading.
	115	It still does in-place I/O decompression
	116	for the rest compressed physical clusters.
e66d8631	117	========== =============================================
06252e9c GX	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``.
dfeab2e9	121	device=%s Specify a path to an extra device to be used together.
6e95d0a0	122	fsid=%s Specify a filesystem image ID for Fscache back-end.
b22c7b97 JX	123	domain_id=%s Specify a domain ID in fscache mode so that different images
b22c7b97 JX	124	with the same blobs under a given domain ID can share storage.
e66d8631	125	=================== =========================================================
fdb05364	126
168e9a76 HJ	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
fdb05364 GX	135	On-disk details
	136	===============
	137
	138	Summary
	139	-------
	140	Different from other read-only file systems, an EROFS volume is designed
e66d8631	141	to be as simple as possible::
fdb05364 GX	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):
e66d8631	151
fdb05364	152	1. Inode metadata space
e66d8631	153
fdb05364	154	Each valid inode should be aligned with an inode slot, which is a fixed
ffafde47	155	value (32 bytes) and designed to be kept in line with compact inode size.
fdb05364 GX	156
	157	Each inode can be directly found with the following formula:
	158	inode offset = meta_blkaddr * block_size + 32 * nid
	159
e66d8631 MCC	160	::
e66d8631 MCC	161
1b55767d GX	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
fdb05364 GX	187
fdb05364 GX	188	Inode could be 32 or 64 bytes, which can be distinguished from a common
e66d8631	189	field which all inode versions have -- i_format::
fdb05364 GX	190
fdb05364 GX	191	__________________ __________________
ffafde47	192	\| i_format \| \| i_format \|
fdb05364 GX	193	\|__________________\| \|__________________\|
	194	\| ... \| \| ... \|
	195	\| \| \| \|
	196	\|__________________\| 32 bytes \| \|
	197	\| \|
	198	\|__________________\| 64 bytes
	199
	200	Xattrs, extents, data inline are followed by the corresponding inode with
ffafde47	201	proper alignment, and they could be optional for different data mappings.
2a9dc7a8	202	_currently_ total 5 data layouts are supported:
fdb05364	203
e66d8631	204	== ====================================================================
ffafde47 GX	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);
2a9dc7a8 GX	208	3 fixed-sized output data compression (with compacted indexes, v5.3+);
2a9dc7a8 GX	209	4 chunk-based file (v5.15+).
e66d8631	210	== ====================================================================
fdb05364 GX	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
e66d8631	217
fdb05364 GX	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
1b55767d	225	::
e66d8631	226
1b55767d GX	227	\|-> aligned by 4 bytes
	228	+ xattr_blkaddr blocks \|-> aligned with 4 bytes
	229	_________________________________________________________________________
	230	\| ... \| xattr_entry \| xattr data \| ... \| xattr_entry \| xattr data ...
	231	\|________\|_____________\|_____________\|_____\|______________\|_______________
fdb05364 GX	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
e66d8631 MCC	241	::
e66d8631 MCC	242
1b55767d GX	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
fdb05364 GX	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
6e95d0a0 GX	260	Chunk-based files
6e95d0a0 GX	261	-----------------
2a9dc7a8 GX	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
46f2e044 GX	271	Data compression
46f2e044 GX	272	----------------
2109901d	273	EROFS implements fixed-sized output compression which generates fixed-sized
46f2e044 GX	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::
e66d8631	286
1b55767d GX	287	\|<- variable-sized extent ->\|<- VLE ->\|
	288	clusterofs clusterofs clusterofs
	289	\| \| \|
	290	_________v_________________________________v_______________________v________
	291	... \| . \| \| . \| \| . ...
	292	____\|____._________\|______________\|________.___ _\|______________\|__.________
	293	\|-> lcluster <-\|-> lcluster <-\|-> lcluster <-\|-> lcluster <-\|
46f2e044 GX	294	(HEAD) (NONHEAD) (HEAD) (NONHEAD) .
	295	. CBLKCNT . .
	296	. . .
	297	. . .
	298	_______._____________________________.______________._________________
1b55767d GX	299	... \| \| \| \| ...
1b55767d GX	300	_______\|______________\|______________\|______________\|_________________
46f2e044 GX	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.
2109901d GX	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.