[RFC] erofs-utils: addressing the 16 GiB xattr prefix offset limit in incremental builds

[RFC] erofs-utils: addressing the 16 GiB xattr prefix offset limit in incremental builds

[lanbingying]

[-- Attachment #1: Type: text/plain, Size: 2857 bytes --]

Hi,
xattr_prefix_start is a 32-bit field storing an offset in four-byte units. When an incremental build places a new long xattr name prefix table at or beyond 16 GiB, the offset cannot be represented and mkfs.erofs rejects the build.
Before working on patches, I would like to discuss several possible solutions:

 * 
Store the prefix table in the packed inode.
Use the existing format support so that the table is addressed by a logical offset within the packed inode rather than a physical offset in the image. This avoids a format extension, although the table’s logical offset remains subject to the same limit, and existing references to fragment data must be preserved.

 * 
Reserve space for the prefix table near the beginning of the image.
Reserve sufficient space at a low offset when creating the image, with a feature flag identifying this layout. Subsequent incremental builds would use the reserved region, while images without the flag would retain the existing behavior. Existing images without reserved space would require migration or rebuilding to adopt this layout.

 * 
Extend the offset using reserved superblock space.
Add an upper field for xattr_prefix_start in the superblock’s reserved space and combine it with the existing field. A new incompat feature would enable the extended interpretation; without it, readers would retain the current interpretation. This would allow the table to remain appended to the image, but require reader updates.

 * 
Reserve space for the prefix table within the packed inode.
Building on option 1, reserve a dedicated region at a low logical offset within the packed inode when creating the image. Subsequent incremental builds could use this region instead of appending a new table after the growing fragment data. A feature flag could identify the reservation; existing images without such a region would need a migration or rebuild path.
All options should preserve the interpretation of existing images. Where a new interpretation is introduced, readers that do not support it should reject the feature rather than read the table from an incorrect location.
Separately, we could reuse the existing prefix table when the required prefix entries and their indices match those in the base image, provided the original table remains valid and accessible. For example, newly added files may use existing long prefixes even if their xattr values differ, so no table update is needed. This would avoid writing another identical table at the end of the image. However, it is an optimization rather than a complete solution: the addressing limit still needs to be handled when new prefixes are added or the table must be relocated.
Which approach would best fit EROFS’s long-term format and maintenance goals? Are there other options or constraints that should be considered?
Thanks,
Bingying

[-- Attachment #2: Type: text/html, Size: 3960 bytes --]

Re: [RFC] erofs-utils: addressing the 16 GiB xattr prefix offset limit in incremental builds

[Gao Xiang]

Hi,

On Fri, Oct 30, 2026 at 04:32:48PM +0800, lanbingying wrote:
> Hi,
> xattr_prefix_start is a 32-bit field storing an offset in four-byte units. When an incremental build places a new long xattr name prefix table at or beyond 16 GiB, the offset cannot be represented and mkfs.erofs rejects the build.
> Before working on patches, I would like to discuss several possible solutions:

Thanks for discussing this.

I wonder in which case the long xattr name prefix table needs to be
extended?

> 
>  * 
> Store the prefix table in the packed inode.
> Use the existing format support so that the table is addressed by a logical offset within the packed inode rather than a physical offset in the image. This avoids a format extension, although the table’s logical offset remains subject to the same limit, and existing references to fragment data must be preserved.

I think we can this one.  Currently, it seems that mkfs.erofs should
support keeping long xattr name prefix table in the packed inode,
but I'm not sure if it supports incremental builds.

> 
>  * 
> Reserve space for the prefix table near the beginning of the image.
> Reserve sufficient space at a low offset when creating the image, with a feature flag identifying this layout. Subsequent incremental builds would use the reserved region, while images without the flag would retain the existing behavior. Existing images without reserved space would require migration or rebuilding to adopt this layout.

I think this one is okay too, and it's doable, maybe even without a new
feature flag. 

> 
>  * 
> Extend the offset using reserved superblock space.
> Add an upper field for xattr_prefix_start in the superblock’s reserved space and combine it with the existing field. A new incompat feature would enable the extended interpretation; without it, readers would retain the current interpretation. This would allow the table to remain appended to the image, but require reader updates.

I don't think it needs to be done, because long xattr name prefix
table has 128 entries at most. we could just reserve at the beginning.

and long xattr name prefix table table should not be vulnerable to
change a lot when doing incremental builds.

> 
>  * 
> Reserve space for the prefix table within the packed inode.

This one is doable too.

Thanks,
Gao Xiang

> Building on option 1, reserve a dedicated region at a low logical offset within the packed inode when creating the image. Subsequent incremental builds could use this region instead of appending a new table after the growing fragment data. A feature flag could identify the reservation; existing images without such a region would need a migration or rebuild path.
> All options should preserve the interpretation of existing images. Where a new interpretation is introduced, readers that do not support it should reject the feature rather than read the table from an incorrect location.
> Separately, we could reuse the existing prefix table when the required prefix entries and their indices match those in the base image, provided the original table remains valid and accessible. For example, newly added files may use existing long prefixes even if their xattr values differ, so no table update is needed. This would avoid writing another identical table at the end of the image. However, it is an optimization rather than a complete solution: the addressing limit still needs to be handled when new prefixes are added or the table must be relocated.
> Which approach would best fit EROFS’s long-term format and maintenance goals? Are there other options or constraints that should be considered?
> Thanks,
> Bingying