Add documentation for the long xattr name prefixes feature, which has
landed upstream since v6.4.
Signed-off-by: Jingbo Xu <jefflexu@xxxxxxxxxxxxxxxxx>
---
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
