From nobody Tue Apr 28 23:18:09 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9F646C433EF for ; Fri, 27 May 2022 07:01:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1344701AbiE0HBt (ORCPT ); Fri, 27 May 2022 03:01:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40552 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234075AbiE0HBq (ORCPT ); Fri, 27 May 2022 03:01:46 -0400 Received: from out30-42.freemail.mail.aliyun.com (out30-42.freemail.mail.aliyun.com [115.124.30.42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 25F4226DB for ; Fri, 27 May 2022 00:01:43 -0700 (PDT) X-Alimail-AntiSpam: AC=PASS;BC=-1|-1;BR=01201311R211e4;CH=green;DM=||false|;DS=||;FP=0|-1|-1|-1|0|-1|-1|-1;HT=e01e04426;MF=hsiangkao@linux.alibaba.com;NM=1;PH=DS;RN=4;SR=0;TI=SMTPD_---0VEW9436_1653634894; Received: from e18g06460.et15sqa.tbsite.net(mailfrom:hsiangkao@linux.alibaba.com fp:SMTPD_---0VEW9436_1653634894) by smtp.aliyun-inc.com(127.0.0.1); Fri, 27 May 2022 15:01:41 +0800 From: Gao Xiang To: Chao Yu , linux-erofs@lists.ozlabs.org Cc: linux-kernel@vger.kernel.org, Gao Xiang Subject: [PATCH] erofs: update documentation Date: Fri, 27 May 2022 15:01:33 +0800 Message-Id: <20220527070133.77962-1-hsiangkao@linux.alibaba.com> X-Mailer: git-send-email 2.24.4 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" - refine the filesystem overview for better description of recent new features like FSDAX or Fscache; - add the new `fsid' mount option; - fix some typos. Signed-off-by: Gao Xiang Reviewed-by: Chao Yu --- Documentation/filesystems/erofs.rst | 62 +++++++++++++++++++---------- 1 file changed, 41 insertions(+), 21 deletions(-) diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystem= s/erofs.rst index bef6d3040ce4..4f108a218049 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -1,63 +1,82 @@ .. SPDX-License-Identifier: GPL-2.0 =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -Enhanced Read-Only File System - EROFS +EROFS - Enhanced Read-Only File System =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Overview =3D=3D=3D=3D=3D=3D=3D=3D =20 -EROFS file-system stands for Enhanced Read-Only File System. Different -from other read-only file systems, it aims to be designed for flexibility, -scalability, but be kept simple and high performance. +EROFS filesystem stands for Enhanced Read-Only File System. It aims to fo= rm a +generic read-only filesystem solution for various read-only use cases inst= ead +of just focusing on storage space saving without considering any side effe= cts +of runtime performance. =20 -It is designed as a better filesystem solution for the following scenarios: +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: =20 - read-only storage media or =20 - 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 and other considerations and + their releases due to security or other considerations and =20 - hope to minimize extra storage space with guaranteed end-to-end perform= ance by using compact layout, transparent file compression and direct access, especially for those embedded devices with limited memory and high-dens= ity - hosts with numerous containers; + hosts with numerous containers. =20 Here is the main features of EROFS: =20 - Little endian on-disk design; =20 - - Currently 4KB block size (nobh) and therefore maximum 16TB address spac= e; - - - Metadata & data could be mixed by design; + - 4KiB block size and 32-bit block addresses, therefore 16TiB address spa= ce + at most for now; =20 - - 2 inode versions for different requirements: + - Two inode layouts for different requirements: =20 - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D compact (v1) extended (v2) - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Inode metadata size 32 bytes 64 bytes - Max file size 4 GB 16 EB (also limited by max. vol si= ze) + Max file size 4 GiB 16 EiB (also limited by max. vol s= ize) Max uids/gids 65536 4294967296 Per-inode timestamp no yes (64 + 32-bit timestamp) Max hardlinks 65536 4294967296 Metadata reserved 4 bytes 14 bytes - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + - Metadata and data could be mixed as an option; =20 - Support extended attributes (xattrs) as an option; =20 - - Support xattr inline and tail-end data inline for all files; + - Support tailpacking data inline and xattr inline compared to byte-addre= ssed + unaligned metadata or smaller block size alternatives; =20 - Support POSIX.1e ACLs by using xattrs; =20 - Support transparent data compression as an option: - LZ4 algorithm with the fixed-sized output compression for high performa= nce; + LZ4 and MicroLZMA algorithms can be used on a per-file basis; In additi= on, + inplace decompression is also supported to avoid bounce compressed buff= ers + and page cache thrashing. + + - Support direct I/O on uncompressed files to avoid double caching for lo= op + devices; =20 - - Multiple device support for multi-layer container images. + - Support FSDAX on uncompressed images for secure containers and ramdisks= in + order to get rid of unnecessary page cache. + + - Support multiple devices for multi blob container images; + + - Support file-based on-demand loading with the Fscache infrastructure. =20 The following git tree provides the file system user-space tools under -development (ex, formatting tool mkfs.erofs): +development, such as a formatting tool (mkfs.erofs), an on-disk consistenc= y & +compatibility checking tool (fsck.erofs), and a debugging tool (dump.erofs= ): =20 - git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git =20 @@ -91,6 +110,7 @@ dax=3D{always,never} Use direct access (no page cach= e). See Documentation/filesystems/dax.rst. dax A legacy option which is an alias for ``dax=3Dalway= s``. device=3D%s Specify a path to an extra device to be used toge= ther. +fsid=3D%s Specify a filesystem image ID for Fscache back-en= d. =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 Sysfs Entries @@ -226,8 +246,8 @@ 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. =20 -Chunk-based file ----------------- +Chunk-based files +----------------- In order to support chunk-based data deduplication, a new inode data layou= t has been supported since Linux v5.15: Files are split in equal-sized data chun= ks with ``extents`` area of the inode metadata indicating how to get the chunk --=20 2.24.4