Re: [PATCH v2] docs: erofs: refine the on-disk overview

From: hudsonZhu

Date: Thu Nov 12 2026 - 04:29:06 EST


Reviewed-by: Chengyu Zhu <hudsonzhu@xxxxxxxxxxx>

Thanks,
Chengyu

> 2026年11月12日 17:16,Gao Xiang <xiang.gao@xxxxxxxxxx> 写道:
>
> The existing on-disk summary mainly describes inode and shared xattr
> metadata views, leaving the overall layout and design rationale unclear.
>
> Expand the summary and refine the terminology and wording while keeping
> the section a high-level overview.
>
> Assisted-by: chatgpt:gpt-6.1-sol
> Signed-off-by: Gao Xiang <xiang.gao@xxxxxxxxxx>
> ---
> changes since v1:
> - address Chengyu's comment to describe more about the metabox.
>
> Documentation/filesystems/erofs.rst | 119 +++++++++++++++++++++-------
> 1 file changed, 90 insertions(+), 29 deletions(-)
>
> diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst
> index 02caf3b061fe..cea781b3cb16 100644
> --- a/Documentation/filesystems/erofs.rst
> +++ b/Documentation/filesystems/erofs.rst
> @@ -171,13 +171,27 @@ 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
> -===============
> +On-disk format
> +==============
> +
> +This section provides a high-level overview. For the latest complete on-disk
> +format specification, see:
> +
> +- https://erofs.docs.kernel.org/en/latest/ondisk/
>
> Summary
> -------
> -Different from other read-only file systems, an EROFS volume is designed
> -to be as simple as possible::
> +
> +EROFS keeps its on-disk format as simple as possible to minimize the need
> +for metadata consistency checks.
> +
> +The guiding principle is that malformed or deliberately crafted metadata
> +may describe a corrupt filesystem, but its effects should remain confined
> +to the data and metadata exposed to userspace: garbage filesystems return
> +garbage (meta)data to users, and nothing more. Violating this rule is
> +unsafe and must be prevented by our on-disk design.
> +
> +::
>
> |-> aligned with the block size
> ____________________________________________________________
> @@ -185,16 +199,50 @@ to be as simple as possible::
> |_|__|_|_____|__________|_____|______|__________|_____|______|
> 0 +1K
>
> -All data areas should be aligned with the block size, but metadata areas
> -may not. All metadata can be now observed in two different spaces (views):
> +Apart from the EROFS superblock, which starts at byte offset 1024, metadata
> +and data regions have no fixed locations or boundaries and may be interleaved
> +throughout the image. As a result, inodes do not need to reside in a fixed
> +central table, allowing incremental builds, although the image creator may
> +still choose to group all inodes together.
> +
> +All data except inline data must be aligned to the filesystem block size
> +[#unencoded_data]_ to enable efficient block I/O, support memory mapping,
> +and avoid unnecessary data copies. Metadata does not require block alignment.
> +
> +.. [#unencoded_data] Strictly speaking, data refers to unencoded data;
> + encoded inodes are outside the scope of EROFS core metadata.
>
> - 1. Inode metadata space
> +EROFS core metadata consists only of the superblock, inodes, and directory
> +entries stored in directory inode data. The physical locations of inode
> +data are recorded as block numbers to avoid block-alignment checks.
>
> - 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.
> +Only a few superblock fields, including the root nid (see below), are needed
> +to parse the filesystem tree. Most of the remaining fields provide filesystem
> +statistics reported to userspace and should not affect the core filesystem
> +logic.
>
> - Each inode can be directly found with the following formula:
> - inode offset = meta_blkaddr * block_size + 32 * nid
> +Encoded inodes, which contain encoded data such as compressed data (including
> +compressed directories), use a distinct inode "datalayout" number that allows
> +them to be identified or rejected when reading the inode metadata. Support for
> +encoded layouts is optional and can be explicitly disabled at runtime if there
> +are security concerns about parsing compressed data in the kernel.
> +
> +There are two metadata views: one for inode metadata and one for shared
> +extended attributes. Both can also be located in a special hidden inode
> +called "metabox", which provides a unified way to compress inode and xattr
> +metadata:
> +
> + 1. Inode metadata view
> +
> + Each valid inode is aligned to a 32-byte inode slot, matching the
> + size of a compact inode. Inodes can be stored either inside or outside
> + the metabox inode, with a flag in the nid indicating whether they are
> + stored inside.
> +
> + For inodes not in the metabox, each inode can be located directly
> + using the following formula::
> +
> + inode physical position = meta_blkaddr * block_size + 32 * nid
>
> ::
>
> @@ -224,8 +272,8 @@ may not. All metadata can be now observed in two different spaces (views):
> |-> 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::
> + Inodes can be 32 or 64 bytes, distinguished by the i_format field common
> + to both formats::
>
> __________________ __________________
> | i_format | | i_format |
> @@ -236,31 +284,44 @@ may not. All metadata can be now observed in two different spaces (views):
> | |
> |__________________| 64 bytes
>
> - Xattrs, extents, data inline are placed after the corresponding inode with
> - proper alignment, and they could be optional for different data mappings.
> - _currently_ total 5 data layouts are supported:
> + Xattrs, extents, and inline data follow the corresponding inode with
> + proper alignment. Their presence depends on the inode's datalayout.
> + Five data layouts are currently 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+).
> + 0 Flat inode data without inline data (no extents);
> + 1 Encoded inode
> + 2 Flat inode data with inline tail data (no extents);
> + 3 Encoded inode (compact indexes)
> + 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.
> + The size of the optional xattrs is indicated by i_xattr_count in the inode
> + header. Large xattrs or xattrs shared by many files can be stored in
> + shared xattr metadata rather than inlined immediately after the inode.
> +
> + For inodes in the metabox, the remaining nid bits identify the inode slot
> + within the metabox's inode address space. This data is read through the
> + metabox inode, with decompression as needed. The metabox inode itself is
> + located outside the metabox and is identified by metabox_nid in the
> + superblock.
>
> - 2. Shared xattrs metadata space
> + 2. Shared xattrs metadata view
>
> - 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.
> + The shared xattr metadata view is similar to the inode metadata view.
> + It starts at the block indicated by xattr_blkaddr, with entries stored
> + sequentially on 4-byte boundaries. Shared xattrs are stored either all
> + inside or all outside the metabox; this metadata view cannot be selected
> + individually for each entry.
> +
> + Each shared xattr can be located using the following formula::
>
> - Each share xattr can also be directly found by the following formula:
> xattr offset = xattr_blkaddr * block_size + 4 * xattr_id
>
> + When COMPAT_SHARED_EA_IN_METABOX feature is enabled, this offset is within
> + the metabox inode's address space. Otherwise, it is a physical position
> + in the filesystem image.
> +
> ::
>
> |-> aligned by 4 bytes
> --
> 2.54.0 (Apple Git-157)
>