Skip to content

docs: improve clarity in xattrs and chunked format documentation #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SKM2227229725 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: improve clarity in xattrs and chunked format documentation #29

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b34316
docs: improve clarity in xattrs and chunked format documentation
SKM2227229725 Mar 21, 2026
a961a65
Escfix: clarify e_name_index 0 usage per maintainer feedback
SKM2227229725 Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/ondisk/chunked_format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ inode offset 0x10) is interpreted as a chunk info summary:

| Bits | Width | Description |
|-------|-------|-------------|
| 0–4 | 5 | `chunkbits`: chunk size = `2^(blkszbits + chunkbits)` |
| 0–4 | 5 | `chunkbits`: chunk size = 2 to the power of (`blkszbits + chunkbits`) |
Copy link
Copy Markdown
Member

@SToPire SToPire May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need to change this

| 5 | 1 | `EROFS_CHUNK_FORMAT_INDEXES`: entry format selector (see below) |
| 6 | 1 | 48-bit layout specific; ignored for basic chunk-based inodes |
| 7–31 | 25 | Reserved; must be 0 |
Expand Down
5 changes: 3 additions & 2 deletions src/ondisk/xattrs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ When clear, the full byte selects one of the built-in short namespace prefixes:
| 4 | `trusted.` |
| 6 | `security.` |

Comment on lines +120 to +127
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The e_name_index mapping table is labeled as a "Prefix", but entries system.posix_acl_access and system.posix_acl_default are full xattr names rather than prefixes (they don't end with a dot). Consider renaming the column/wording (e.g. "Prefix or full name") and/or explicitly stating that for these indexes the stored name suffix length (e_name_len) is 0.

Suggested change
| Value | Prefix |
|-------|--------|
| 1 | `user.` |
| 2 | `system.posix_acl_access` |
| 3 | `system.posix_acl_default` |
| 4 | `trusted.` |
| 6 | `security.` |
| Value | Prefix or full name |
|-------|----------------------|
| 1 | `user.` |
| 2 | `system.posix_acl_access` |
| 3 | `system.posix_acl_default` |
| 4 | `trusted.` |
| 6 | `security.` |
For indices `2` and `3`, the string shown above is the entire xattr name (no additional suffix bytes are stored), so `e_name_len` must be `0`. For the other indices, the string is a prefix and the remaining name bytes are stored as the suffix of length `e_name_len`.

Copilot uses AI. Check for mistakes.
All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension.
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a blank line before the (shared_xattr_area)= label. As written, the label is immediately adjacent to the preceding paragraph, which can cause MyST/Sphinx to treat it as part of the paragraph instead of a standalone label and may break cross-referencing.

Suggested change
All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension.
All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

@hsiangkao hsiangkao Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, e_name_index 0 is used for arbitary namespace xattrs. They are only hidden by the runtime.

Copy link
Copy Markdown
Contributor Author

@SKM2227229725 SKM2227229725 Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @hsiangkao,

Thanks for the clarification. I’ve updated the documentation to correctly reflect the usage of e_name_index = 0 for arbitrary namespace xattrs and pushed the changes.

Please let me know if anything else needs adjustment.

Thanks!

(shared_xattr_area)=
## Shared Xattr Area

Expand All @@ -144,8 +145,8 @@ This section applies when `EROFS_FEATURE_INCOMPAT_XATTR_PREFIXES` is set.

When this feature is set, a table of `xattr_prefix_count` prefix entries is
present; see {ref}`xattr_prefix_table_placement` for where that table is stored.
Each entry has the following fixed header, padded together with the
variable-length `infix` payload to a 4-byte boundary:
Each entry has the following fixed header. The full entry, including the
variable-length `infix` payload, is padded to a 4-byte boundary.

| Offset | Size | Type | Name | Description |
|--------|------|-------|--------------|-------------|
Expand Down
Loading