Merge tag 'erofs-for-7.4-rc3-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs

Pull erofs fixes from Gao Xiang:

 - Fix stacked fs check for file-backed mounts with extra devices

 - Disallow file-backed mounts on shared backing inodes

 - Reset metadata offsets when fsoffset= is used to fix xattr reads
   inside and outside the metabox in ont shot

 - Refine on-disk format summary

* tag 'erofs-for-7.4-rc3-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs:
  docs: erofs: refine the on-disk overview
  erofs: reset buf->off in erofs_init_metabuf()
  erofs: treat files shared by inode_share as stacked
  erofs: apply the stacked fs check to extra file-backed devices
This commit is contained in:
Linus Torvalds
2026-11-13 09:48:11 -08:00
3 changed files with 112 additions and 32 deletions
+91 -29
View File
@@ -171,13 +171,28 @@ 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 metadata
consistency checks, retaining only those that are strictly necessary
at runtime.
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 +200,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.
1. Inode metadata space
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.
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.
.. [#unencoded_data] Strictly speaking, data refers to unencoded data;
encoded inodes are outside the scope of EROFS core metadata.
Each inode can be directly found with the following formula:
inode offset = meta_blkaddr * block_size + 32 * nid
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.
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.
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" (v6.17+), 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 +273,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 +285,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.
2. Shared xattrs metadata space
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.
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.
2. Shared xattrs metadata view
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
+1
View File
@@ -60,6 +60,7 @@ int erofs_init_metabuf(struct erofs_buf *buf, struct super_block *sb,
struct erofs_sb_info *sbi = EROFS_SB(sb);
buf->mc = false;
buf->off = 0;
if (in_metabox) {
if (unlikely(!sbi->metabox_inode))
return -EFSCORRUPTED;
+20 -3
View File
@@ -122,6 +122,17 @@ void *erofs_read_metadata(struct super_block *sb, struct erofs_buf *buf,
return buffer;
}
/* see the comment in erofs_fc_fill_super() */
static bool erofs_is_stacked_file(struct file *file)
{
struct inode *inode = file_inode(file);
struct super_block *sb = inode->i_sb;
return (sb->s_op == &erofs_sops && !sb->s_bdev) || sb->s_stack_depth ||
(IS_ENABLED(CONFIG_EROFS_FS_PAGE_CACHE_SHARE) &&
inode->i_fop == &erofs_ishare_fops);
}
static int erofs_init_device(struct erofs_buf *buf, struct super_block *sb,
struct erofs_device_info *dif, erofs_off_t *pos)
{
@@ -161,6 +172,11 @@ static int erofs_init_device(struct erofs_buf *buf, struct super_block *sb,
} else if (!S_ISREG(file_inode(file)->i_mode)) {
fput(file);
return -EINVAL;
} else if (erofs_is_stacked_file(file)) {
erofs_err(sb, "%s: file-backed devices cannot be on stacked fses",
dif->path);
fput(file);
return -EINVAL;
}
if (!dif->dax_dev && test_opt(&sbi->opt, DAX_ALWAYS)) {
erofs_info(sb, "DAX unsupported by %s. Turning off DAX.",
@@ -700,10 +716,11 @@ static int erofs_fc_fill_super(struct super_block *sb, struct fs_context *fc)
* EROFS is the only fs supporting file-backed mounts for now.
* It MUST change if another fs plans to support them, which
* may also require adjusting FILESYSTEM_MAX_STACK_DEPTH.
* Files shared by inode_share may be read through a
* file-backed EROFS in the same domain, so treat them as
* stacked too.
*/
inode = file_inode(sbi->dif0.file);
if ((inode->i_sb->s_op == &erofs_sops &&
!inode->i_sb->s_bdev) || inode->i_sb->s_stack_depth) {
if (erofs_is_stacked_file(sbi->dif0.file)) {
erofs_err(sb, "file-backed mounts cannot be applied to stacked fses");
return -ENOTBLK;
}