Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jingbo Xu <jefflexu@linux.alibaba.com>
To:     hsiangkao@linux.alibaba.com, chao@kernel.org,
        linux-erofs@lists.ozlabs.org
Cc:     huyue2@coolpad.com, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: [PATCH] erofs: add documentation for long xattr name prefixes feature
Date:   Mon, 19 Jun 2023 19:01:50 +0800
Message-Id: <20230619110150.107958-1-jefflexu@linux.alibaba.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Add documentation for the long xattr name prefixes feature, which has
landed upstream since v6.4.

Signed-off-by: Jingbo Xu <jefflexu@linux.alibaba.com>
---
 Documentation/filesystems/erofs.rst | 47 +++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst
index 4654ee57c1d5..d3408d25165e 100644
--- a/Documentation/filesystems/erofs.rst
+++ b/Documentation/filesystems/erofs.rst
@@ -328,3 +328,50 @@ 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.
+
+Long xattr name prefixes
+------------------------
+In use cases together with overlayfs like Composefs model, there are xattrs with
+diverse xattr values but only a few common xattr names (trusted.overlay.redirect,
+trusted.overlay.digest, and maybe more in the future).  The existing predefined
+prefixes mechanism, e.g. {.e_name_index = EROFS_XATTR_INDEX_TRUSTED,
+.e_name = "overlay.redirect"} for "trusted.overlay.redirect", works inefficiently
+in both image size and runtime performance in such scenarios.
+
+The long xattr name prefixes feature is introduced (since Linux v6.4) to address
+this issue.  The general idea is that, apart from the existing predefined
+prefixes, the xattr entry could also refer to user specified long xattr name
+prefixes, e.g. "trusted.overlay." in above described use cases.
+
+When referring to a long xattr name prefix, the highest bit (bit 7) of
+erofs_xattr_entry.e_name_index is set, while the lower bits (bit 0-6) as a whole
+represents the index of the referred long name prefix among all long xattr name
+prefixes.  Besides only the trailing part of the xattr name apart from the long
+xattr name prefix is stored in erofs_xattr_entry.e_name, which could be empty if
+the xattr name matches exactly as the long xattr name prefix.
+
+All long xattr prefixes are stored one by one in the packed inode as long as the
+packed inode exists, or meta inode otherwise.  The xattr_prefix_count (of
+on-disk superblock) represents the total number of the long xattr name prefixes,
+while (xattr_prefix_start * 4) indicates the start offset of long name prefixes
+in the packed/meta inode.  The long xattr name prefixes feature is not used when
+xattr_prefix_count is 0.
+
+Each long xattr name prefix (in packed/meta inode) is stored in the format:
+ALIGN({__le16 len, data}, 4), where len represents the total size of following
+data.  The data part, describing one long xattr name prefixes record, is
+represented by 'struct erofs_xattr_long_prefix', where base_index represents the
+index of the referred predefined short xattr name prefix, e.g.
+EROFS_XATTR_INDEX_TRUSTED for "trusted.overlay." long name prefix, while the
+infix string represents the string after stripping the short prefix, e.g.
+"overlay." for the above example.
+
+::
+
+         |-> aligned with 4 bytes               |-> aligned with 4 bytes
+     _________________________________________________________________________________
+    | .. | len | base_index | infix string | .. | len | base_index | infix string | ..
+    |____|_____|____________|______________|____|_____|____________|______________|___
+         ^     |<--  xattr_long_prefix  -->|          |<--  xattr_long_prefix  -->|
+	 .
+    + (xattr_prefix_start * 4) offset
-- 
2.19.1.6.gb485710b